让编码代理可靠运行 CLI 的设计与审查方法

在构建或审查命令行工具时，让代理能非交互、可组合、可重试地稳定执行。

适用场景

解决思路

1. 所有输入都应能通过 flag 或 flag 值表达，不要要求方向键、菜单或定时提示。
2. 缺少 flag 时才回退到交互模式，而不是反过来。
3. 代理会逐步发现子命令：先运行 `mycli`，再运行 `mycli deploy --help`；不要每次运行都打印整本手册。
4. 让每个子命令拥有自己的文档，使未使用的命令不进入上下文。
5. 每个子命令都要有 `--help`。
6. 每个 `--help` 都要包含带真实调用的 **Examples**，示例比散文更利于模式匹配。
7. 在合理的地方接受 stdin，例如 `cat config.json | mycli config import --stdin`。
8. 避免奇怪的位置参数顺序，避免在缺少值时回退到交互提示。
9. 支持链式调用，例如 `mycli deploy --env staging --tag $(mycli build --output tag-only)`。
10. 缺少必需 flag 时立即退出，给出清晰消息和**正确的示例调用**，不要挂起。
11. 保证幂等性：同一条成功命令运行两次应安全（无操作或明确提示“已完成”），而不是产生重复副作用。
12. 对破坏性操作添加 `--dry-run`（或等价选项），让代理在提交前预览计划。
13. 提供 `--yes` / `--force` 跳过确认，同时为人类保留安全默认值。
14. 使用一致的结构模式，例如 `resource` + `verb`：如果存在 `mycli service list`，那么 `mycli deploy list` 和 `mycli config list` 也应遵循同样形状。
15. 成功时返回对机器有用的数据：ID、URL、耗时；纯文本即可，避免只依赖装饰性输出。
16. 审查现有 CLI 时检查：非交互路径、分层帮助、`--help` 上的示例、stdin/管道方案、带调用示例的错误消息、幂等性、dry-run、跳过确认的 flag、一致命令结构、结构化成功输出。