Star94
37
代码
代码
Issues81
Pull Requests12
Actions
项目讨论
Wiki
分析
Star94
37
Aaflyingtofeat(install): unify diagnostics and automatic npm updates
9a4913c4创建于 8月10日历史提交

Agent-Friendly CLI 规范

本文档定义 gitcode-cli 在面向 AI 代理、脚本和非交互环境时必须遵守的 CLI 契约。

职责

定义结构化输出、非 TTY 行为、错误模型、确认语义和命令发现能力。

适用场景

  • 新增或修改命令输出
  • 新增或修改交互式确认
  • 调整错误输出或退出码
  • 设计 schema / help / 机器可消费接口

必须

  • 机器可消费输出必须提供稳定结构
  • 非交互环境不得隐式阻塞等待输入
  • 破坏性命令必须有统一确认策略
  • 错误和退出码要有稳定语义

禁止

  • 只为人工阅读优化而忽视自动化调用
  • 在非 TTY 环境下静默等待输入
  • 同类命令输出契约随意漂移

同步要求

  • 行为变化时同步 docs/COMMANDS.md
  • AI 使用路径变化时同步 docs/AI-GUIDE.md、AGENTS.md、CLAUDE.md 和相关 skills
  • 回归矩阵变化时同步 docs/REGRESSION.md

1. 目标

本规范的目标是让 gc 同时满足：

  • 人类终端交互可读
  • AI 代理和脚本可稳定消费
  • 错误和确认行为可预测
  • 新命令沿统一模板演进

2. 输出契约

2.1 文本输出

文本输出面向人工阅读，应满足：

  • 主要数据输出到 stdout
  • 结构尽量稳定
  • 不把错误和警告混入 stdout

2.2 JSON 输出

对外暴露数据结构的命令，优先支持 --json。

当前执行基线：

  • 高频只读命令应优先支持 --json
  • 高频写路径命令应逐步支持成功结果 --json
  • 同一命令同时支持 --json 与 --dry-run 时，组合输出也应保持可解析 JSON，或明确返回用法错误
  • JSON 输出必须只写 stdout
  • JSON 字段名应直接映射现有 API / 领域模型，避免随意重命名

2.3 向后兼容

TTY 场景下默认文本输出可保留既有体验。新增 JSON 输出视为增强能力，不应无故破坏已有文本路径。

3. 非 TTY 与非交互行为

命令在非交互环境下必须满足：

  • 不隐式等待人工输入
  • 无法继续时立即报错
  • 明确提示使用 --yes 或等价参数

允许逐步推进的能力：

  • 非 TTY 默认结构化输出
  • 全局 --no-interactive

但在这些能力完全落地前，必须先满足“不可阻塞”的最低要求。

4. 破坏性命令确认

删除、覆盖、变更状态等高风险写操作必须遵守：

  • 默认有确认保护
  • --yes 明确跳过确认
  • 非 TTY 且未显式跳过确认时必须立即失败
  • 命令不得直接绕过共享确认组件自行读取 stdin

5. Dry Run 与预检查

适合预演的写命令应优先支持 --dry-run 或等价预检查模式。

最低要求：

  • dry-run 不执行真实写入
  • 输出明确描述将发生的动作
  • 文档写明哪些命令支持 dry-run，哪些仅支持预检查

6. 错误模型与退出码

命令应尽量把常见失败归一到稳定退出码：

  • 0 成功
  • 1 通用错误
  • 2 参数或用法错误
  • 3 资源不存在
  • 4 认证或权限错误
  • 5 资源冲突

当错误无法精确分类时，允许回退到 1。

7. Help 与命令发现

--help 不只是人工文档，也是代理发现接口。

命令帮助至少应包含：

  • 命令用途
  • 核心示例
  • 关键 flag 说明
  • 是否支持 --json
  • 是否存在非交互限制或确认要求

如果命令支持 schema / metadata 查询，帮助中也应给出入口。

8. 命令开发要求

新增命令或大幅改动命令时，应优先复用共享能力：

  • 统一输出辅助
  • 统一认证获取
  • 统一确认组件
  • 统一错误类型

不应在每个命令里重复发明一套 I/O 和错误处理逻辑。

9. 当前执行基线

安装诊断与 npm 更新还必须满足：

  • doctor install --json 完全离线、无需认证，stdout 只包含稳定诊断对象；不得读取认证配置或 Token
  • update --check --json / update --json 字段固定为 status、distribution、current、latest、message
  • 后台更新摘要只写 stderr，不得污染业务命令 JSON stdout
  • CI=true、--no-interactive、--no-update-check、GC_NO_UPDATE_CHECK=1 禁用隐式自动应用；显式 update 仍按用户请求执行
  • registry 超时、离线、权限失败、锁冲突和回滚不得改变已经完成的业务命令退出码，也不得产生交互式提权提示

当前阶段的最低基线是：

  1. 高频只读命令逐步补齐 --json
  2. 高频写路径命令逐步补齐成功结果 --json
  3. 删除类命令收口到统一确认策略
  4. CLI 退出码具有基本稳定语义
  5. gc schema 或等价元数据能力提供命令发现入口

下一步去看哪里