CLI 稳定性策略

Holon 仍处于 1.0 之前，但并非每个 CLI 接口都有相同的变更风险。 本策略说明哪些命令行接口对脚本安全、哪些主要供人类或调试使用， 以及未来的命令变更需要达到什么标准。

配合以下页面阅读：

• CLI 参考，了解当前命令树和常见工作流。
• CLI 契约清单，了解逐命令的稳定性级别、输出模式和已知契约缺口。
• CLI 退出码，了解进程退出码和 stdout/stderr 路由。
• API 契约清单，了解许多 CLI JSON 输出所镜像的 HTTP 响应形态。

稳定性级别

级别	预期用途	支持策略
stable	用户和脚本可以依赖的公开 CLI 契约。	避免破坏性变更。若无法避免，保留有记录的迁移路径并在发布说明中说明。
experimental	公开可达、但仍在成型的接口。	在 Holon 运行时模型稳定期间可能变化。可行时优先提供警告、别名或兼容输出，再考虑移除。
internal	调试、fixture、本地开发或运行时检查接口。	不面向外部自动化。可能随实现细节变化。
deprecated	带有记录替代方案的兼容接口。	在满足记录的兼容窗口或移除标准前保持可用。不要对新增自动化使用它。

当命令有混合输出模式时，把级别应用到你所消费的具体接口。例如，某个命令路径可能是稳定候选，而其人类可读措辞仍为 experimental。

脚本安全接口

脚本应优先使用同时具备以下全部属性的接口：

1. 在 CLI 参考或契约清单中有记录的命令路径和标志集。
2. 机器可读 JSON 输出，最好经由 Holon 规范化的 JSON 打印路径输出，而非直接透传原始 HTTP 响应。
3. 有记录的响应归属方：CLI 契约清单，或当 CLI 镜像控制平面响应时的 HTTP/API 清册。
4. 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 行为时：

1. 当命令路径、标志或常见工作流变化时，更新 CLI 参考。
2. 当稳定性分类、输出模式或脚本安全性变化时，更新 CLI 契约清单。
3. 当 CLI 输出镜像了变化后的控制平面响应时，更新 API 契约清单。
4. 为 stable 和 stable 候选命令的形态、输出或退出码行为添加或更新测试。
5. 避免为自动化引入新的原始输出路径。若必须透传原始输出，在规范化前将其记录为 experimental。

稳定的 CLI 接口应当变得乏味：被明确命名、有测试、并在用户写脚本前会查看的地方有记录。