Protocol 说明

介绍

ac-workflow 的 protocol 不是 CLI 子命令，而是安装 Skill 后你在对话里对 AI 触发的动作协议。AI 会根据当前 .agent-context/ 的状态决定该创建计划、执行计划还是做增量修补。

核心规则：

• 任意时刻每个 SCOPE 最多一个当前计划
• 计划只有两个状态：未执行 和 已执行
• 影响范围（## 影响范围）不包含 .agent-context/ 目录下的文件

快速使用

两条原则：

1. 有活跃且已执行的当前计划，再提变更时优先走 patch
2. implement 只执行当前计划，不接受追加需求

最常见的说法：

初始化这个项目的 agent context
为"新增导出功能"出计划
按当前计划开始实现
给当前计划补一个 patch，修复 CSV 编码问题
当前计划已经真正完成，归档它
rush 一下，把 README 里的命令表更新为最新版本
review

API参考

Protocol	适用时机	前置状态	典型产物
init	项目还没有稳定协作规则	无	新建或补全 AGENTS.md，初始化 SCOPE
plan	新需求需要正式拆分步骤	不能有冲突的当前计划	.agent-context/{scope}/plan-{N}/plan.md
replan	计划未执行，但方案要重做	目标计划必须是 未执行	更新后的计划结构
implement	计划已确认，开始实施	当前计划必须存在且为 未执行	代码/文档改动，计划状态变为 已执行
patch	已执行计划上补修复或增量需求	当前计划必须是 已执行	patch-{N}.md 与更新后的影响范围
rush	任务很明确，想直接创建并实施	当前不能有未实施计划	单计划立即执行
review	对当前计划做独立第三方审查	当前计划存在且校验通过	审查报告；典型后续为 replan 或 patch
done	当前计划确实完成	当前计划必须是 已执行	当前计划归档到 done/，自动更新索引

init

用于建立项目级协作基线并初始化 SCOPE。

适合：

• 新项目刚开始，还没有 AGENTS.md
• 老项目已有 AGENTS.md，但规则不完整
• 首次在项目中使用 agent-context

典型输入：

初始化这个项目的 agent context，技术栈是 Bun + TypeScript

执行重点：

• 判断新项目还是旧项目
• 生成或补全 AGENTS.md
• 初始化 SCOPE（自动取 git user.name）
• 新项目可继续推进到计划创建阶段

plan

用于把一个需求转换成正式计划。

适合：

• 需求已经明确，但还没开始实施
• 任务较复杂，需要拆步骤或拆成多个计划

典型输入：

为"给 HTTP 客户端增加重试插件"出计划

执行重点：

• 先做必要澄清，避免目标模糊
• 创建 plan.md，包含目标、内容、影响范围和历史补丁四个部分（模板见同步的 protocols/plan.md）
• 复杂任务可拆成「一个当前计划 + 多个 preparing/ 计划」；多计划时最小编号为当前计划，其余入队
• 自检通过前须消除 ## 内容 中的模糊指令；完成后可按协议询问用户是否对新建计划执行 review
• 计划编号在当前 SCOPE 内扫描全部 plan-N 目录取 max(N)+1

replan

用于重做未实施计划。

适合：

• 技术路线变了
• 原计划拆分不合理
• 想保留目标，但改动实施方式

典型输入：

重做当前计划，不引入任何新依赖

执行重点：

• 只处理 未执行 的计划
• 已执行计划不允许 replan（应走 patch）
• 需要保持单当前计划模型

implement

用于严格执行当前计划。

适合：

• plan.md 已经存在且经过确认
• 现在要开始真正落地

典型输入：

按当前计划开始实现

执行重点：

• 读取当前 plan.md 的 ## 目标 与 ## 内容
• 对照内容逐项实施；仅操作当前计划，不直接操作 preparing/ 中的计划
• 进入验证循环：编码任务运行 Lint/Typecheck/测试；非编码任务凭审阅验收
• 完成后将状态改为 已执行，回写 ## 影响范围（.agent-context/ 下路径不计入）
• 不接受附加需求，遇阻塞向用户报告
• 结束后可按协议询问用户是否对刚实施结果执行 review

patch

用于在已执行计划上做增量修改。

适合：

• 修 Bug
• 补遗漏项
• 加一个不值得新开计划的小改动

典型输入：

给当前计划补一个 patch，修复流式读取时空行被跳过的问题

执行重点：

• 读取主计划和历史补丁，避免重复修
• 生成新的 patch-{N}.md
• 同步更新主计划的 ## 历史补丁 与 ## 影响范围

rush

用于快速处理一个边界很清楚的任务。

适合：

• 小范围文档修订
• 单一测试修复
• 明确脚本修改

典型输入：

rush 一下，把 README 里的 protocol 解释补完整

执行重点：

• 仍然会创建计划（plan.md）；强制单计划，不拆分、不进入 preparing/ 队列
• 仅在描述已足够明确时跳过 plan 的「需求澄清」；须做「无模糊指令检查」，有歧义时向用户提问澄清，不得硬 rush
• 完成 plan 后不等待用户确认，直接进入 implement，且须按 implement 协议完整执行（验证循环、状态改为 已执行、## 影响范围 等），与 packages/agent-context/src/skill/protocols/rush.ts 一致
• 前置（与源码一致）：已存在已执行的当前计划时，应询问是否先 agent-context done 再 rush；已存在未执行的当前计划时，应询问是否改走当前计划的 implement 等
• 实施结束后可按协议询问用户是否立即 review（与 implement 协议末尾一致）
• 不适合需求范围模糊的大任务

review

用于在不混入当前对话实施上下文的前提下，对当前计划做独立审查。

适合：

• 计划已定稿但想在上手前做一次结构性与风险检查
• 实施已完成，想对照计划与 git diff 做代码与完整性审查

典型输入：

review

执行重点：

• 不接受额外描述；前置需 agent-context validate 通过
• 未执行：审查 plan.md 全文（目标、步骤、影响范围、模糊指令等）
• 已执行：结合 plan.md、全部 patch-*.md、## 影响范围 与相关文件的 git diff 审查实现质量
• 协议要求通过独立子代理执行审查，产出结构化问题列表
• 审查结束后通常会引导你选择：未执行计划走 replan（推荐）或继续 implement；已执行计划走 patch（推荐）或收尾

done

用于归档真正完成的当前计划。

适合：

• 当前计划已经实施完毕
• 相关补丁也已经补完
• 需要把上下文推进到下一个计划

典型输入：

当前计划已经真正完成，归档它

执行重点：

• 最终调用 agent-context done
• 归档到 .agent-context/{scope}/done/plan-{N}-{YYYYMMDD}/
• 如果有 preparing 队列，自动晋升下一个计划
• 自动更新计划索引