CLI 参考 - HeavenBase

CLI 是正门，不是另一栋摆着可疑同款家具的大楼。

1. 动机

hb 公开常见的设置、工作区、配置、LLM、Toolkit、Prompt 与 Dashboard 工作流，但不会发明独立的运行时权威。

hb --help
hb --version
hb setup

请对任意命令使用 --help，查看当前环境所安装的精确选项。

2. 设置与路径

hb setup 初始化默认 Context Registry，并确保默认工作区定义存在。它不会创建项目本地的 .heavenbase/ 目录。

hb setup
hb setup --reset
hb pj %/system.db
hb pj '&/configs/default.yaml'

hb pj 解析 HeavenBase 路径别名，例如用于包状态的 %/ 与用于资源的 &/。

3. 工作区

hb ws list
hb ws create demo --preset debug
hb ws get demo
hb ws open demo
hb ws health demo
hb ws activate demo
hb ws deactivate
hb ws manifest demo > workspace.yaml
hb ws import workspace.yaml
hb ws unset demo

创建与导入会注册持久定义，但不会激活它。选择始终通过独立的 hb ws activate <id> 操作完成。 hb ws presets list 与 hb ws presets show debug 检查打包 Preset。本地无服务示例使用 debug，本地服务栈使用 local-lts，托管部署使用 web-lts。

4. 配置

hb config 及其别名 hb cfg 通过 ConfigManager 编辑值。

hb cfg get heavenbase.llm.default_preset
hb cfg list heavenbase.llm.presets
hb cfg set heavenbase.llm.default_preset mock
hb cfg unset heavenbase.llm.default_preset
hb cfg history --limit 5
hb cfg scope
hb cfg diff
hb cfg edit --scope heavenbase
hb cfg reset --scope heavenbase.scratch
hb cfg compact --scope heavenbase

使用 --scope 指定配置层，使用 --version 读取保留历史，使用 --json 输出 JSON 或解析值。

5. Dashboard

hb dashboard
hb dashboard --no-open
hb dashboard --app
hb dashboard --host 127.0.0.1 --port 42777

除非显式传入 --allow-network，Dashboard 会拒绝非 loopback 绑定。该选项会暴露未经认证的配置 API，因此只能在你信任的网络上使用。

6. LLM

hb llm chat --preset mock --no-stream "hello"
hb llm embed "semantic text" --preview
hb llm session --preset chat
hb llm imagen "a simple product diagram" --output ./image.png
hb llm status --preset mock
hb llm verbose --preset chat-pro
hb llm list all

调用命令共享 --preset、--model、--provider、--gateway、缓存与详细输出控制。 Chat 与 Session 接受重复的 --mcp 值，可传 URL 或 quickstart.math-tools:-1 这样的 Toolkit ref。规范 Toolkit ref 为 namespace.toolkit:version。负版本从最新向最旧计数，因此 -1 选择最新版。

7. MCP Toolkit

hb mcp setup --workspace demo
hb mcp list --workspace demo
hb mcp show quickstart.math-tools:-1 --workspace demo
hb mcp tools quickstart.math-tools:-1 --workspace demo
hb mcp call quickstart.math-tools:-1 add --args '{"left": 2, "right": 3}' --workspace demo
hb mcp mcp-json quickstart.math-tools:-1 --workspace demo
hb mcp serve quickstart.math-tools:-1 --workspace demo

Toolkit 行与引用的 Capsule 行属于选中的应用工作区。请使用 hb mcp --help 检查 stdio、HTTP、删除与 Capsule 列表命令。

8. Prompt 与翻译

hb prompt list
hb prompt show welcome
hb prompt create welcome --template "Hello, {name}!"
hb prompt render welcome --args '{"name": "Ada"}'
hb prompt tr-list

Prompt 命令通过打包的 Prompt 扩展管理模板行与翻译字典。请使用 hb prompt --help 查看翻译绑定、解绑、设置与删除操作。

9. 其他 CLI 编译器

Typer 是打包的 CLI 前端。宿主应用可以把同一个命令 Registry 编译为 Click 或 argparse：

from heavenbase.cli import create_cli

typer_app = create_cli("typer")
click_app = create_cli("click")
argparse_parser = create_cli("argparse")

编译器改变呈现，而不改变命令所有权。

总结

hb 是公共 HeavenBase 领域之上的浅层适配器。
工作区创建、导入与激活保持独立。
LLM、Toolkit 与 Prompt 命令复用各自的 Python 权威。
命令帮助是已安装构建的精确参考。

进一步探索

相关资源：

工作区 (Workspace) — 持久身份与激活
Dashboard — 本地可视化操作台
LLM 概述 — Preset 与路由解析
MCP Toolkit 参考 — Toolkit 持久化与服务

​1. 动机

​2. 设置与路径

​3. 工作区

​4. 配置

​5. Dashboard

​6. LLM

​7. MCP Toolkit

​8. Prompt 与翻译

​9. 其他 CLI 编译器

​总结

​进一步探索

1. 动机

2. 设置与路径

3. 工作区

4. 配置

5. Dashboard

6. LLM

7. MCP Toolkit

8. Prompt 与翻译

9. 其他 CLI 编译器

总结

进一步探索