Agent 友好 CLI 设计
Agent-Friendly CLI Design
专为 AI Agent 优化的 CLI 设计模式，包括 JSON 输出、原子操作和非交互式接口
子问题
1.JSON 输出模式
2.原子性操作（CAS claim）
3.Doctor-Fix 统一健康检查
4.避免交互式命令
5.Agent 模式自动检测与环境感知
6.输出紧凑性与 token 预算优化
7.读写分离的命令权限模型
各项目的解法1 solutions
Signals
横向对比
| 维度 | Beads |
|---|---|
| JSON 输出模式 | 全局 --json flag + outputJSON/outputJSONError 双通道，错误也是 JSON |
| 原子性操作 | SQL 条件 UPDATE 实现 CAS claim，事务内 DOLT_COMMIT 保证一致性 |
| Agent 模式检测 | IsAgentMode() 自动检测 BD_AGENT_MODE 和 CLAUDE_CODE 环境变量 |
| 健康检查 | bd doctor 集成 30+ 项检查，--fix --yes 非交互式自动修复 |
| 非交互设计 | 所有写操作纯 flag 驱动，--body-file=- 支持 stdin，--yes 跳过确认 |
| 输出紧凑性 | Agent 模式自动降低 limit、跳过 tips/升级通知、禁用 glamour 渲染 |
| 任务发现 | bd ready 使用依赖图分析排除间接阻塞，区别于简单 status 过滤 |
最佳实践
1.所有命令支持 --json flag
2.原子 claim 防止多 agent 竞争
3.Doctor 模式统一诊断与修复入口
4.错误输出也用 JSON 格式（stderr），Agent 可精确解析失败原因
5.自动检测已知 Agent 环境变量，减少 Agent 需要传递的参数
6.读写命令分离映射表，读命令自动以只读模式打开存储