CLI 命令

介绍

agent-context 的 CLI 不负责替代 Skill protocol。它主要做这些事：

• 初始化 SCOPE 与安装/同步 Skill 文件
• 校验 .agent-context/ 结构
• 一次输出状态快照 + 校验结果（context，Skill 启动步骤使用的结构化接口）
• 查看状态与归档当前计划
• 生成或更新计划索引
• 评估 Skill description 触发样例覆盖（skill-eval）
• 在用户主目录生成各工具的全局提示词文件（prompt-gen）
• 升级 CLI 自身到最新版本（upgrade）

对话里说"出计划""开始实现""补 patch"触发的是 Skill protocol，不是 CLI 子命令。

当前发布产物中的 ESM JavaScript 文件统一使用 .js 后缀，例如 CLI 入口为 dist/cli.js；Skill 安装时依赖的脚本也会随构建一并发布到 dist/skill/scripts/。

快速使用

最常用的命令：

agent-context init          # 首次使用，初始化 SCOPE
agent-context install       # 安装 canonical Skill 到 .agents
agent-context validate      # 校验目录结构
agent-context context       # 输出状态快照 JSON（含校验；Skill 启动步骤等价物）
agent-context status        # 查看当前状态
agent-context sync          # 同步 canonical Skill 并刷新兼容入口
agent-context done          # 归档已执行计划
agent-context index         # 生成/更新计划索引
agent-context skill-eval    # 检查 Skill description 触发样例覆盖
agent-context prompt-gen    # 可选：写入本机全局提示词模板
agent-context upgrade       # 升级到最新版本

安装完成后，日常推进通常靠自然语言触发 Skill；CLI 更多用于初始化、检查和收尾。

API参考

agent-context init

初始化当前项目的 SCOPE。首次在项目中使用时必须运行，自动检测 git user.name 作为 SCOPE 名称，创建 .agent-context/.env 和作用域目录。

agent-context init
agent-context init --scope alice
agent-context init --yes

选项	说明
--scope <name>	手动指定 SCOPE 名称，不使用 git user.name
--yes	非交互模式：自动覆盖已存在的 SCOPE

如果 .env 中已有 SCOPE，默认会询问是否覆盖。

agent-context install

安装 ac-workflow Skill。默认只写入 Agent Skills 开放标准目录 .agents/skills/ac-workflow/，作为 canonical source。

agent-context install
agent-context install --tools claude,codex,cursor
agent-context install --check --tools copilot
agent-context install --yes

选项	说明
--tools <tools>	指定要创建的兼容入口工具，逗号分隔
--check	只检查是否会产生变更，不写文件
--yes	非交互模式；未传 --tools 时仍只安装 canonical source

支持的工具（技能目录名均为 ac-workflow）。.agents 是 canonical source；其他目录是可选兼容入口，优先 symlink / junction 指向 .agents/skills/ac-workflow/，不支持 symlink 或已有普通目录时按 copy fallback 同步：

工具	Skill 目录
Agent Skills（.agents）	.agents/skills/ac-workflow/
Cursor	.cursor/skills/ac-workflow/
Claude Code	.claude/skills/ac-workflow/
Codex	.codex/skills/ac-workflow/
Antigravity	.agent/skills/ac-workflow/
Gemini CLI	.gemini/skills/ac-workflow/
GitHub Copilot	.github/skills/ac-workflow/

安装产物采用轻量入口 + 按需引用：

• SKILL.md：包含触发描述、单条启动命令、状态路由和硬约束，不内联完整协议正文
• references/init.md、plan.md、replan.md、implement.md、patch.md、rush.md、review.md：协议细节，确定动作后读取对应文件
• references/ask-user-question.md：只有准备调用交互式提问工具时读取；按语义在自己的工具清单中识别宿主提问工具（ask / question / choice / select / prompt / input / followup 等），命中必须调用，不绑死具体工具名；含"何时禁止提问"红线避免走流程式反复确认
• references/_principles.md：规划、实施、审查三类角色的共享专业素养；协议内不再重复，仅在文件开头引用这份基线
• scripts/get-context-info.js：从项目根目录运行，同时输出路由所需的结构化上下文 JSON 与内置格式校验；发现问题时以非 0 退出码打印错误，修复后重跑
• scripts/validate-context.js：仅在上面的主脚本无法启动时（例如 Node 权限问题）作为独立校验 fallback

触发边界：description 只匹配 ac-workflow / .agent-context 相关意图；普通代码实现、普通 code review、普通计划讨论或单纯修改 AGENTS.md 不应触发该 Skill。

agent-context sync

同步项目中已安装的 Skill 内容，适合升级包版本后刷新协议文件。

agent-context sync
agent-context sync --check

选项	说明
--check	只检查是否存在待同步内容，不写文件

说明：

• sync 不接受 --tools
• 它会从源码重新渲染 .agents/skills/ac-workflow/，再刷新已存在的兼容入口链接或 copy fallback
• 如果当前项目尚未安装任何 Skill，会直接报错并提示先执行 install

agent-context validate

校验 .agent-context/ 的结构是否合法。

agent-context validate

检查内容：

• SCOPE 是否已初始化
• 当前计划是否唯一
• plan.md 是否存在
• 计划状态是否有效（未执行 或 已执行）
• 目录结构是否符合协议

agent-context context

一次输出当前 .agent-context 状态快照 JSON，并内置目录结构校验；校验不通过时把错误列表打到 stderr 并以非 0 退出码返回，供代理直接判断"是否要先修复再继续"。

agent-context context

输出字段（校验通过时）：

• cwd、acRoot、scope、scopeDir、preparingDir、doneDir
• currentPlan、currentPlanStatus、currentPlanNumber、currentPlanDir、currentPlanFile
• nextPlanNumber、nextPatchNumber

与 bundled scripts/get-context-info.js 的字段含义一致——后者是 Skill 在没有全局 CLI 或 npx 不可用时的降级入口，二者都可作为 SKILL.md "启动步骤"的数据来源。两者在边界行为上有两点差异：

• 项目未初始化（.agent-context 目录不存在）：CLI 命令输出 { cwd, acRoot, initialized: false } 并以退出码 0 返回，用于上层编排可判断；bundled 脚本则以非 0 退出并打印 未找到 .agent-context 目录 错误，Skill 接此错误时按 SKILL.md 的"特例"规则直接进入 references/init.md。
• 额外字段：bundled 脚本会额外输出 runner（来自 .agent-context/.env），CLI 命令不输出——Skill 内部脚本需要它来决定子命令使用 node 还是 bun；CLI 使用方若依赖运行时偏好，应直接读取 .agent-context/.env。

agent-context status

查看当前 agent-context 状态。

agent-context status

输出内容：

• 当前 SCOPE 名称
• 当前计划编号和状态
• preparing 队列中的计划数量
• 已归档计划数量

agent-context done

归档当前已执行计划，移入 done/ 目录。

agent-context done
agent-context done --yes

选项	说明
--yes	跳过确认，直接归档

归档后的行为：

• 当前计划移入 .agent-context/{scope}/done/plan-{N}-{YYYYMMDD}/
• 如果 preparing/ 中有待执行计划，自动晋升编号最小的为新当前计划
• 自动调用 index 更新计划索引

agent-context index

生成或更新当前 SCOPE 的计划索引文件 .agent-context/{scope}/index.md。

agent-context index

索引文件按以下顺序列出所有计划：

1. 已归档计划（done/）— 标记为 [x]
2. 当前计划 — 已执行标记 [x]，未执行标记 [ ]
3. 待执行计划（preparing/）— 标记 [ ]

每项格式为 - [x/ ] [计划标题](相对路径)，标题从 plan.md 的一级标题提取。

归档计划时（done）会自动更新索引，也可手动运行。

agent-context skill-eval

评估当前生成的 ac-workflow Skill description 与触发样例 fixture。它会读取 test/fixtures/trigger-prompts.json（发布包中找不到 fixture 时使用内置等价样例），输出：

• 当前 description 文本与长度
• should-trigger 样例覆盖数
• should-not-trigger 近似负例覆盖数

agent-context skill-eval

该命令目前是静态触发评估，用来避免 description 变宽或漏掉近似负例；后续可接入真实 agent 日志判断 Skill 是否实际加载。

agent-context prompt-gen

在用户主目录下写入各 AI 工具的全局提示词模板（与项目内 .agent-context/ 无关）。默认使用通用模板，不包含作者个人环境假设。

agent-context prompt-gen
agent-context prompt-gen --tools claude,codex
agent-context prompt-gen --profile whj --tools codex
agent-context prompt-gen --yes
agent-context prompt-gen --check

选项	说明
--tools <tools>	指定目标工具，逗号分隔：claude、codex、gemini、antigravity
--profile <profile>	指定模板 profile：default、whj
--yes	非交互：已选工具一律覆盖写入
--check	只列出将要创建或覆盖的文件路径，不写入

各工具对应文件：

工具	写入路径
Claude Code	~/.claude/CLAUDE.md
Codex	~/.codex/AGENTS.md
Gemini CLI	~/.gemini/GEMINI.md
Antigravity	~/.gemini/AGENTS.md

未传 --tools 且非 --yes / --check 时，会交互多选工具；默认全部勾选。

agent-context upgrade

升级全局安装的 @cat-kit/agent-context 到最新版本。

agent-context upgrade

等价于手动执行 npm update -g @cat-kit/agent-context。升级完成后建议运行 agent-context sync 同步项目中已安装的 Skill 内容。

通用选项汇总

选项	适用命令	作用
--tools <tools>	install / prompt-gen	指定工具列表，逗号分隔
--check	install / sync / prompt-gen	只检查，不写入文件
--yes	install / init / done / prompt-gen	跳过或减少交互确认
--profile <profile>	prompt-gen	指定提示词模板 profile
--scope <name>	init	手动指定 SCOPE 名称