CLI 契约清单
本清单按 src/main.rs 记录 Holon 当前的 CLI 接口，并对照 target/debug/holon --help（holon 0.39.0）核验。
它是稳定性规划文档，不代表清单中的每条命令都已稳定。
当前实现把 CLI 收在一个 Rust 二进制中：
src/main.rs定义 Clap 命令树和大部分 CLI 处理器。docs/website/reference/cli.md是面向用户的命令参考。docs/website/reference/cli-stability-policy.md记录 stable、experimental、internal 和 deprecated CLI 接口的面向用户支持策略。docs/website/reference/configuration.md记录配置文件、凭据相关环境变量和诊断。
稳定性级别
这些标签背后的面向用户支持策略见 CLI 稳定性策略。
| 级别 | 含义 | 变更策略 |
|---|---|---|
stable | 面向公众的预期接口，用户和脚本可以合理依赖。 | 避免破坏性变更；需要发布说明和迁移路径。 |
experimental | 公开可达，但仍在成型。 | 1.0 前可能变化；移除前优先提供警告或别名。 |
internal | 调试、运行时或本地开发接口。 | 不面向外部自动化；内部实现变化时可能改变。 |
deprecated | 为兼容而保留，但已被其他接口取代。 | 记录替代方案，仅通过明确的废弃计划移除。 |
跨领域 CLI 契约
| 接口 | 当前行为 | 初始稳定性 | 备注 |
|---|---|---|---|
| 命令解析器 | 由 Clap 派生的命令树，根级带 --help 和 --version。 | stable | 命令名和标志名是价值最高的 CLI 契约。 |
| 帮助文本 | 人类可读的 Clap 输出。 | experimental | 对用户有用；不应把确切的间距和措辞当作机器可读。 |
| 错误 | 由二进制运行时渲染的 Clap 校验错误或 anyhow 错误。 | experimental | 在宣布稳定前，退出码形态需要明确的测试。 |
| JSON 输出 | 面向脚本的 JSON 命令通过共享的 print_json 路径向 stdout 打印美化 JSON。 | experimental | JSON 字段形态通常来自运行时/控制平面结构体，需要与 API 清册对齐。 |
| 人类输出 | run、solve、serve、debug latency、debug prompt 以及部分 debug/export 命令向 stdout 输出人类文本。 | experimental | 除非命令有意面向脚本，否则不要对完整措辞做快照。 |
| stderr | tracing 日志、Clap 错误、凭据提示以及部分 provider/运行时诊断。 | experimental | 凭据提示有意写到 stderr。 |
| stdin | 目前只有 config credentials set --stdin 从 stdin 读取。 | stable 候选 | 交互细节需要专门的测试。 |
| 配置/环境变量 | 大多数命令加载 AppConfig；配置命令用 $HOLON_HOME 定位离线配置路径。 | experimental | 更广的环境变量范围见配置参考。 |
命令清单
根命令
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon --help | none | -h, --help, -V, --version | 向 stdout 输出人类帮助 | stable 候选 | 应由命令树快照测试覆盖。 |
holon <COMMAND> --help | 取决于命令 | 取决于命令 | 向 stdout 输出人类帮助 | 形态为 stable 候选；措辞为 experimental | 命令形态变化时重新生成 cli.md。 |
服务器与守护进程
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon serve | none | --access <local|tunnel|lan|tailnet> 默认 local；--host <HOST>；--listen <LISTEN>；--port <PORT>；--advertise <ADVERTISE>；--token <TOKEN>；--token-file <TOKEN_FILE> | 长期运行的服务器；启动摘要在 stdout；日志/tracing 在 stderr | experimental | 非 loopback/tailnet/lan 访问需要通过标志、文件或 HOLON_CONTROL_TOKEN 提供控制令牌。 |
holon daemon start | none | 与 serve 相同的 ServeOptions | JSON 守护进程生命周期响应 | stable 候选 | 内联令牌通过环境变量传给子进程，而非 argv。 |
holon daemon stop | none | none | JSON 守护进程生命周期响应 | stable 候选 | 使用本地守护进程生命周期辅助函数。 |
holon daemon status | none | none | JSON 守护进程状态响应 | stable 候选 | 重要的本地检查接口。 |
holon daemon restart | none | 与 serve 相同的 ServeOptions | JSON 守护进程生命周期响应 | stable 候选 | 与 serve 相同的访问/令牌校验。 |
holon daemon logs | none | --tail <TAIL> 默认 80 | JSON 守护进程日志响应 | stable 候选 | daemon logs 被记录为本地故障排查接口。 |
离线配置
这些命令直接操作持久化配置或凭据文件，不要求守护进程运行。
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon config get | <KEY> | none | 该键的 JSON 值 | stable 候选 | 可达时优先使用守护进程运行时配置 API，保持 stdout 形态；键集来自配置契约。 |
holon config set | <KEY> <VALUE> | none | 写入后的 JSON 值 | stable 候选 | 可达时优先使用守护进程运行时配置 API，否则回退到离线模式，并在 stderr 报告 applied_via；守护进程的拒绝会透出原因。 |
holon config unset | <KEY> | none | JSON { "key": ..., "status": "unset" } | stable 候选 | 可达时优先使用守护进程运行时配置 API，否则回退到离线模式，并在 stderr 报告 applied_via；若脚本依赖该状态字符串，应将其锁定。 |
holon config list | none | none | 完整的持久化配置 JSON | experimental | 可达时优先使用守护进程运行时配置 API，保持 stdout 形态；会暴露较广的配置文件形态。 |
holon config schema | none | none | JSON 配置 schema/元数据 | stable JSON | 由 tests/cli_json_contract.rs 锁定；条目对象暴露 key、kind、description、default 以及可选的 allowed_values。 |
holon config doctor | none | none | JSON provider/系统诊断 | experimental | 诊断形态可能随 provider 变化。 |
holon config models list | none | none | JSON 模型可用性列表 | experimental | Provider 目录和可用性细节仍在演进。 |
Provider 配置
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon config providers set | <PROVIDER> | --transport <TRANSPORT>；--base-url <BASE_URL>；--credential-source <SOURCE> 默认 none；--credential-kind <KIND> 默认 none；--credential-env <ENV>；--credential-profile <PROFILE>；--credential-external <COMMAND> | JSON { "applied_via": "offline_store", "provider": ... } | 命令形态为 stable 候选；provider 对象为 experimental | 内置 provider 可能拒绝不兼容的 transport 覆盖。 |
holon config providers get | <PROVIDER> | none | JSON provider 视图 | experimental | 输出使用运行时 provider 视图。 |
holon config providers list | none | none | provider 视图的 JSON 数组/对象 | experimental | 输出形态应与 API/配置清册对齐。 |
holon config providers remove | <PROVIDER> | none | JSON { "applied_via": "offline_store", "provider": ..., "status": "removed|not_configured" } | stable JSON | 由 tests/cli_json_contract.rs 锁定；状态字符串面向脚本。 |
holon config providers doctor | <PROVIDER> | none | JSON provider 视图加模型链诊断 | experimental | 诊断细节可能变化。 |
凭据配置
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon config credentials set | <PROFILE> | 必填 --kind <KIND>；--stdin 或 --material <MATERIAL> 二选一 | JSON { "applied_via": "offline_store", "credential": { "profile": ..., "kind": ..., "configured": true } } | stable JSON | 由 tests/cli_json_contract.rs 锁定；--stdin 提示写到 stderr；raw --material 有意不推荐用于机密。 |
holon config credentials list | none | none | 带 profile、kind 和 configured 的 JSON 凭据 profile 列表；绝不包含凭据材料 | stable JSON | 由 tests/cli_json_contract.rs 锁定；绝不能暴露凭据材料。 |
holon config credentials remove | <PROFILE> | none | JSON { "applied_via": "offline_store", "credential": { "profile": ..., "kind": ..., "configured": false } } | stable JSON | 由 tests/cli_json_contract.rs 锁定；不存在的 profile 返回 kind: "unknown" 和 configured: false。 |
Agent 交互与检查
除非另有说明，这些命令要求本地控制平面可达。
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon prompt | <TEXT> | --agent <AGENT> | JSON 控制平面 prompt 响应 | experimental | 轻量 prompt 路径；响应形态属于控制平面 API 清册。 |
holon tail | none | --limit <LIMIT> 默认 20；--agent <AGENT> | JSON 近期 brief/日志尾部 | stable 候选 | 结果形态应与 brief/输出契约对齐。 |
holon transcript | none | --limit <LIMIT> 默认 50；--agent <AGENT> | JSON transcript 条目 | stable 候选 | transcript 条目的稳定性需要 API 清册。 |
holon task run | <SUMMARY> | 必填 --cmd <CMD>；--workdir <WORKDIR>；--shell <SHELL>；--login <true|false>；--tty；--yield-time-ms <MS>；--max-output-tokens <N>；--agent <AGENT> | 美化 JSON 控制平面响应 | experimental | 通过控制平面创建命令任务。 |
holon task status | <TASK_ID> | --agent <AGENT> | 美化 JSON TaskStatusSnapshot | experimental | 通过任务状态 API 读取任务生命周期状态。 |
holon task output | <TASK_ID> | --block；--timeout-ms <MS>；--agent <AGENT> | 美化 JSON TaskOutputResult | experimental | 输出预览长度遵循任务创建时的 --max-output-tokens；本命令只控制就绪等待。 |
holon task input | <TASK_ID> | 必填 --text <TEXT>；--agent <AGENT> | 美化 JSON TaskInputResult | experimental | 向命令任务 stdin/TTY 或受监督子 Agent 的后续输入发送可信操作者文本。 |
holon task stop | <TASK_ID> | --agent <AGENT> | 美化 JSON TaskStopResult | experimental | 通过控制平面请求取消受管任务。 |
holon work-item list | none | --limit <LIMIT> 默认 50；--agent <AGENT> | WorkItemRecord 的美化 JSON 数组 | experimental | JSON schema 归属为 HTTP/API WorkItemRecord 读模型，由 /agents/:agent_id/work-items 返回。 |
holon work-item get | <WORK_ITEM_ID> | --agent <AGENT> | 美化 JSON WorkItemRecord | experimental | 通过 /agents/:agent_id/work-items/:work_item_id 读取单个工作项；create、pick、update、complete 子命令已存在，但其变更 API 契约仍在稳定中。 |
holon timer | none | 旧式创建语法：必填 --after-ms <MS>；--every-ms <MS>；--summary <SUMMARY>；--agent <AGENT> | 美化 JSON TimerRecord | experimental | holon timer create 的向后兼容别名。 |
holon timer create | none | 必填 --after-ms <MS>；--every-ms <MS>；--summary <SUMMARY>；--agent <AGENT> | 美化 JSON TimerRecord | experimental | 通过控制平面创建一次性或重复定时器。 |
holon timer list | none | --limit <LIMIT> 默认 50；--agent <AGENT> | TimerRecord 的美化 JSON 数组 | experimental | 通过 agent 定时器 API 读取近期定时器。 |
holon timer cancel | <TIMER_ID> | --agent <AGENT> | 美化 JSON TimerRecord | experimental | 取消活跃定时器；已取消的定时器操作幂等。 |
Agent 生命周期与模型选择
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon agent / holon agents | 可选子命令 | none | 默认为 agent list JSON | stable 候选 | agents 是别名。 |
holon agent list | none | none | JSON agent 条目 | stable 候选 | 公开的多 Agent 检查接口。 |
holon agent status | 可选 [AGENT_ID] | none | JSON agent 状态 | stable 候选 | 位置参数 agent id；默认为配置的默认 agent。 |
holon agent create | <AGENT_ID> | --template <TEMPLATE> | 美化 JSON 控制平面响应 | stable 候选 | 模板标识符契约应与 Agent 初始化文档对齐。 |
holon agent repair | <AGENT_ID> | none | 美化 JSON AgentDetail | experimental | 重试未完成的创建后引导步骤，而不重建 Agent。 |
holon agent start | 可选 [AGENT_ID] | none | JSON 生命周期控制响应 | stable 候选 | 已废弃 control start 的替代。 |
holon agent stop | 可选 [AGENT_ID] | none | JSON 生命周期控制响应 | stable 候选 | 已废弃 control stop 的替代。 |
holon agent abort | 可选 [AGENT_ID] | none | 美化 JSON 控制平面响应 | stable 候选 | 已废弃 control abort 的替代；与 start/stop 共用生命周期 JSON 输出路径。 |
holon agent model get | 可选 [AGENT_ID] | none | JSON 模型覆盖/状态片段 | stable 候选 | 从 agent 状态读取 summary.model。 |
holon agent model set | <MODEL> [AGENT_ID] | none | JSON 模型覆盖响应 | stable 候选 | 位置参数 AGENT_ID 已测试。 |
holon agent model clear | 可选 [AGENT_ID] | none | JSON 模型覆盖响应 | stable 候选 | 应与 set/get 共享契约。 |
holon control | <start|stop|abort> | --agent <AGENT> | 美化 JSON 生命周期响应 | deprecated | 使用 `holon agent start |
已废弃的 holon control 兼容性记录在
CLI 稳定性策略。
新自动化应使用 holon agent ... 生命周期命令。
Skills
技能管理分为库操作和 Agent 启用两部分：
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon skills catalog | none | none | JSON catalog 响应 | experimental | 列出本地 Skill Library 中的所有技能。 |
holon skills refresh | none | none | JSON catalog 响应 | experimental | 重新扫描本地技能根目录以刷新运行时 catalog。不与锁文件对账，也不拉取远程更新。 |
holon skills add | <SOURCE> | --remote；--skill <SKILL>；--copy | 美化 JSON 控制平面响应 | experimental | 向本地 Skill Library 添加技能。本地路径为目录时相对 cwd 解析。 |
holon skills remove | <NAME> | none | 美化 JSON 控制平面响应 | experimental | 从本地 Skill Library 移除技能。 |
holon skills check | [NAME] | none | 美化 JSON 控制平面响应 | experimental | 对照 .skill-lock.json 检查 Skill Library 一致性。 |
holon skills reconcile | [NAME] | none | 美化 JSON 控制平面响应 | experimental | 将库条目与锁文件对账。 |
holon skills list | none | --agent <AGENT> | JSON agent 技能响应 | experimental | 列出某 agent 已启用/生效的技能。 |
holon skills enable | <NAME> | --agent <AGENT>；--copy | 美化 JSON 控制平面响应 | experimental | 为 agent 启用本地已知技能。 |
holon skills disable | <NAME> | --agent <AGENT> | 美化 JSON 控制平面响应 | experimental | 为 agent 禁用技能。 |
holon skills install | <NAME_OR_PATH> | --remote；--skill <SKILL>；--copy；--agent <AGENT> | 美化 JSON 控制平面响应 | deprecated | 兼容别名。库操作用 skills add，agent 用 skills enable。 |
holon skills uninstall | <NAME> | --agent <AGENT> | 美化 JSON 控制平面响应 | deprecated | 兼容别名。库操作用 skills remove，agent 用 skills disable。 |
一次性与 solve 工作流
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon run | <TEXT> | --authority-class <AUTHORITY_CLASS> 默认 operator-instruction；--json；--agent <AGENT>；--create-agent；--template <TEMPLATE>；--max-turns <N>；--no-wait-for-tasks；--home <HOME>；--workspace-root <PATH>；--cwd <PATH> | 默认人类 render_text()；带 --json 时为美化 JSON | 命令形态为 stable 候选；输出为 experimental | 核心用户入口。JSON 响应形态应在给出稳定自动化指引前锁定。 |
holon solve | <REF> | --repo <REPO>；--base <BASE>；--goal <GOAL>；--role <ROLE>；--agent <AGENT>；--template <TEMPLATE>；--model <MODEL>；--max-turns <N>；--authority-class <AUTHORITY_CLASS> 默认 operator-instruction；--json；--home <HOME>；--workspace <PATH>；--workspace-root <PATH>；--cwd <PATH>；--input <INPUT>；--output <OUTPUT> | 默认人类 render_text()；带 --json 时为美化 JSON | experimental | GitHub/任务工作流接口。--workspace 与 --workspace-root 目前被合并。 |
Workspace
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon workspace attach | <PATH> | --agent <AGENT> | JSON attach 响应 | stable 候选 | Workspace 身份/投影契约是运行时稳定性的核心。 |
holon workspace exit | none | --agent <AGENT> | JSON exit 响应 | stable 候选 | 应与 workspace 绑定 RFC 对齐。 |
holon workspace detach | <WORKSPACE_ID> | --agent <AGENT> | JSON detach 响应 | stable 候选 | WORKSPACE_ID 的稳定性属于 API/运行时清册。 |
TUI
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon tui | none | --no-alt-screen；--connect <URL>；--token <TOKEN>；--token-file <PATH>；--token-profile <PROFILE> | 交互式终端 UI | experimental | --connect 要求且仅要求一个令牌来源。TUI 不是主要的稳定运行时契约。 |
调试工具
| 命令 | 参数 | 选项 | 输出 | 初始稳定性 | 备注 |
|---|---|---|---|---|---|
holon debug prompt | <TEXT> | --agent <AGENT>；--authority-class <AUTHORITY_CLASS> 默认 operator-instruction | 人类 prompt dump | internal | 仅用于调试的 prompt 检查。 |
holon debug latency | none | --agent <AGENT>；--limit <LIMIT> 默认 10；--events-limit <EVENTS_LIMIT> 默认 5000 | 人类延迟报告 | internal | 有用的诊断；措辞不应作为机器契约。 |
holon debug scheduler-fixture | none | --agent <AGENT>；必填 --output <OUTPUT> | 写出 JSON/JSONL fixture 文件；打印导出摘要 | internal | Fixture 文件形态对测试可能有用，但若稳定化应单独记录。 |
holon debug scheduler-recovery | none | --agent <AGENT>；--json；--apply；--no-backup（要求 --apply） | 只读的规范化恢复诊断；可选的类型化 apply 结果 | internal | 默认只读。它是当前二进制中唯一允许打开紧邻的上一版 scheduler schema 而不迁移的命令，因此被阻塞的清理迁移仍可恢复。--json 输出 `{ "report": ..., "apply": null |
CLI 触及的环境与配置输入
这不是完整的配置清册；它只列出在调用命令时明显影响 CLI 行为的环境变量。
| 输入 | 使用方 | 当前行为 | 初始稳定性 |
|---|---|---|---|
HOLON_HOME | 配置/凭据与运行时配置加载 | 选择 Holon home/配置/凭据路径。 | stable 候选 |
HOLON_HTTP_ADDR | 运行时/控制平面命令 | 在加载 AppConfig 时选择本地控制平面 HTTP 地址。 | stable 候选 |
HOLON_CALLBACK_BASE_URL | serve、运行时配置 | 设置回调 base URL 默认值。 | experimental |
HOLON_SOCKET_PATH | daemon/serve | 选择本地控制 socket 路径。 | experimental |
HOLON_WORKSPACE_DIR | 运行时命令 | 设置默认 workspace 目录。 | experimental |
HOLON_AGENT_ID | 带可选 --agent / [AGENT_ID] 的命令 | 设置默认 agent id。 | stable 候选 |
HOLON_CONTROL_TOKEN | serve、daemon、控制平面客户端配置 | 提供 bearer token/控制认证。 | stable 候选 |
HOLON_CONTROL_AUTH_MODE | 控制平面配置 | 解析 auto、required 或 disabled。 | experimental |
HOLON_MODEL | run、solve、provider 配置 | 设置默认模型；solve --model 会为该进程写入此环境变量。 | stable 候选 |
| Provider API-key 环境变量 | 由 provider 支撑的命令 | 例如 OPENAI_API_KEY、ANTHROPIC_AUTH_TOKEN，以及配置的自定义环境变量名。 | 已记录的 provider 环境变量为 stable 候选 |
RUST_LOG 与 tracing 环境过滤器 | 所有命令 | 控制输出到 stderr 的 tracing。 | internal |
输出契约缺口
- 面向脚本的命令现在共用规范化的 stdout 路径。 剩余的输出工作是给每个响应形态指定 schema 归属和稳定性级别。
- 退出码现在有基线进程契约。 见 CLI 退出码。把特定命令的业务状态提升为非零退出仍是有意选择加入的，必须逐命令记录。
- 机器可读输出需要 schema 归属。 CLI JSON 常镜像控制平面/运行时结构体。API 清册应决定哪些字段是稳定的、诊断的或内部的。
- 人类输出与运维摘要混在一起。
serve、run、solve和 debug 命令应明确说明其 stdout 是否脚本安全。 - 已废弃的
control仍可达。 在记录移除计划前应保持兼容。 - 帮助快照是手工的。
docs/website/reference/cli.md声称由holon --help重新生成，但仓库中没有生成器或快照测试。
跟踪 issue
Milestone 8 的初始 CLI/API 稳定性后续工作已完成。第 2 阶段工作仍由 CLI/API Stability Contracts 里程碑通过 #1444 跟踪：
| 优先级 | Issue | 范围 |
|---|---|---|
| 1 | #1437 | 在 Milestone 8 完成后刷新 API/CLI 契约清册。 |
| 1 | #1442 | 为稳定命令添加 JSON 输出 schema 和 golden 测试。 |
| 2 | #1438 | 将 OpenAPI 基线迁移到 aide 路由/类型元数据。 |
| 2 | #1439 | 为稳定读模型收紧 OpenAPI DTO schema。 |
| 2 | #1440 | 添加 WorkItem 变更 HTTP 生命周期端点。 |
| 2 | #1441 | 添加 Timer 取消生命周期端点。 |
| 3 | #1443 | 定义稳定的面向操作者事件负载子集。 |
建议的下一批契约测试
| 优先级 | 测试 | 目的 |
|---|---|---|
| 1 | 归一化空白后的 Clap 命令树/帮助快照 | 检测意外的命令/标志漂移。 |
| 1 | 针对稳定候选位置参数和别名的解析测试 | 锁定高价值 CLI 形态，而不过度快照措辞。 |
| 1 | 用假 provider 或 fixture 对 run/solve 做 --json 冒烟测试 | 确认机器可读模式仍可解析。 |
| 2 | get、set、unset、schema、provider remove、credential list/remove 的配置命令 golden JSON | 锁定离线脚本接口。 |
| 2 | daemon/status/log JSON 形态测试 | 锁定本地运维接口。 |
| 2 | 更多缺失令牌和命令特定业务状态的错误行为测试 | 在命令把领域失败提升为进程失败处扩展基线退出码契约。 |
| 3 | 规范或记录原始 HTTP-body 命令（task、timer、agent create/abort、skills add/remove/enable/disable） | 减少输出契约漂移。 |
后续清册范围
本 CLI 清册评审通过后，按以下顺序继续：