CLI 稳定性策略
Holon 仍处于 1.0 之前，但并非每个 CLI 接口都有相同的变更风险。 本策略说明哪些命令行接口对脚本安全、哪些主要供人类或调试使用， 以及未来的命令变更需要达到什么标准。
配合以下页面阅读：
- CLI 参考，了解当前命令树和常见工作流。
- CLI 契约清单，了解逐命令的稳定性级别、输出模式和已知契约缺口。
- CLI 退出码，了解进程退出码和 stdout/stderr 路由。
- API 契约清单，了解许多 CLI JSON 输出所镜像的 HTTP 响应形态。
稳定性级别
| 级别 | 预期用途 | 支持策略 |
|---|---|---|
stable | 用户和脚本可以依赖的公开 CLI 契约。 | 避免破坏性变更。若无法避免，保留有记录的迁移路径并在发布说明中说明。 |
experimental | 公开可达、但仍在成型的接口。 | 在 Holon 运行时模型稳定期间可能变化。可行时优先提供警告、别名或兼容输出，再考虑移除。 |
internal | 调试、fixture、本地开发或运行时检查接口。 | 不面向外部自动化。可能随实现细节变化。 |
deprecated | 带有记录替代方案的兼容接口。 | 在满足记录的兼容窗口或移除标准前保持可用。不要对新增自动化使用它。 |
当命令有混合输出模式时，把级别应用到你所消费的具体接口。例如，某个命令路径可能是稳定候选，而其人类可读措辞仍为 experimental。
脚本安全接口
脚本应优先使用同时具备以下全部属性的接口：
- 在 CLI 参考或契约清单中有记录的命令路径和标志集。
- 机器可读 JSON 输出，最好经由 Holon 规范化的 JSON 打印路径输出，而非直接透传原始 HTTP 响应。
- 有记录的响应归属方：CLI 契约清单，或当 CLI 镜像控制平面响应时的 HTTP/API 清册。
- CLI 退出码契约中明确的退出码行为。
当前的面向脚本候选包括：
holon daemon status、holon daemon logs以及守护进程生命周期命令。holon config get|set|unset|schema以及打印 JSON 的凭据/provider 管理命令。holon agent list和holon agent status。holon workspace attach|exit|detach，前提是 workspace 身份契约稳定。holon run --json和holon solve --json仅限已记录的响应形态；它们的人类输出仍面向操作者。
脚本不应解析确切的帮助文本、tracing 日志、调试措辞或人类摘要。这些输出面向人类，可能为提升清晰度而改变。
人类与诊断接口
以下接口有意不作为主要的自动化契约：
holon --help和holon <command> --help的措辞。命令名和标志名是契约材料；格式和说明文字不是。holon run和holon solve的默认人类输出。holon serve的启动摘要和日志。holon debug *命令。stderr，包括 tracing 日志、Clap 错误、凭据提示以及 provider/运行时诊断。
如果某个诊断接口对自动化变得重要，应把所需字段提升到 JSON 响应或有记录的 API/CLI 契约中，而不是解析调试文本。
已废弃的 holon control
holon control 已废弃。请改用 agent 生命周期命令：
| 已废弃命令 | 替代 |
|---|---|
holon control start --agent <AGENT> | holon agent start <AGENT> |
holon control stop --agent <AGENT> | holon agent stop <AGENT> |
holon control abort --agent <AGENT> | holon agent abort <AGENT> |
兼容策略：
- 除非发布说明宣布更窄的移除窗口，否则在 0.x 线内保持
holon control start|stop|abort可达。 - 不要仅为
holon control添加新选项或行为；改进应先落到holon agent ...。 - 移除前，替代命令必须在生命周期状态变更和退出/错误报告上具备等价且有记录的行为。
- 只有在 CLI 契约清单记录移除标准且发布说明已把用户指向替代后，才应执行移除。
变更要求
变更 CLI 行为时：
- 当命令路径、标志或常见工作流变化时，更新 CLI 参考。
- 当稳定性分类、输出模式或脚本安全性变化时，更新 CLI 契约清单。
- 当 CLI 输出镜像了变化后的控制平面响应时，更新 API 契约清单。
- 为 stable 和 stable 候选命令的形态、输出或退出码行为添加或更新测试。
- 避免为自动化引入新的原始输出路径。若必须透传原始输出，在规范化前将其记录为 experimental。
稳定的 CLI 接口应当变得乏味：被明确命名、有测试、并在用户写脚本前会查看的地方有记录。