| name | plan-archive |
| description | Use when 用户调用 /plan-archive, or 三阶段研发流程的阶段三:在所有模块研发上线后,根据实际代码改动回写阶段一技术方案 + 项目级架构文档(docs/architecture / docs/contracts / docs/assets/概要设计 等)。 |
| argument-hint | --design <path> --since <commit|branch|tag> [--services <list>] |
| disable-model-invocation | true |
Read 项目级文档(以 reelmate-workspace 为例):
- 阶段一产出 `docs/designs/{slug}-{YYYYMMDD}.md`(必传 --design 参数定位)
- `AGENTS.md` § Project Doc Update Triggers(回写触发表 — 决定哪些改动写哪个文件)
- `AGENTS.md` § Documentation Budget(行数预算 — 落盘前自检)
- `docs/assets/万兴剧厂概要设计.md`(项目总架构文档 — 主要回写目标)
- `docs/architecture/README.md` / `glossary.md` / `adr/template.md`
- `docs/contracts.md` / `docs/engineering/rules.md` / `docs/runbooks/README.md`
若上述任一文件不存在,记录"无项目级 X,跳过对应回写",不阻断流程。
技术方案归档(Stage 3)
实施完成后,按实际代码改动回写阶段一技术方案 + 项目级架构文档。三阶段研发流程的阶段三,单点 skill,不进入 workflow 状态机。
用法
/plan-archive --design <path> --since <commit|branch|tag> [--services <list>]
/plan-archive --design docs/designs/asset-batch-upload-20260520.md --since master@{2 weeks ago}
/plan-archive --design docs/designs/asset-batch-upload-20260520.md --since v1.2.0 --services rmdfsrv,rmaisrv
参数:
--design <path>(必填):阶段一文档路径,锚定哪个方案要归档--since <commit|branch|tag>(必填):改动范围起点,例如具体 commit hash / master@{2 weeks ago} / 上次 release tag--services <list>(可选,逗号分隔):限定扫描的服务仓;不传则扫 AGENTS.md § Repository Shape 列出的全部服务
适用 / 不适用
- ✅ 适用:三阶段流程阶段三 / 复杂迭代后期 / 把事实回写到项目级文档
- ❌ 不适用:单 PR 内的局部回写(让 PR description 承担即可);bugfix 不需要;阶段二未完成不要跑
Checklist
- ☐ 输入收集 + 校验
- ☐ 跨服务改动收集(git log / diff)
- ☐ 对比与差异分析(改动 vs 设计 vs 项目级文档)
- ☐ 🛑 回写预览 Hard Stop
- ☐ 落盘 + 自检 + 汇总
Step 1 — 输入收集 + 校验
校验 --design:
- 文件存在
- 是
docs/designs/ 下的合法阶段一文档(含 § 9 实施回写占位章节)
- Status 字段为
Approved 或 Implemented(Draft → 提示用户先确认方案落地再归档)
校验 --since:
- 在 reelmate-workspace 根
git rev-parse <since> 解析成功(若是分支 / tag 别名)
- 不要假设 commit hash 在所有服务仓都存在,各服务仓独立 git history
--services 默认值:
- 不传 → 从
AGENTS.md § Repository Shape 表读 Go 服务(active)+ Python Agent 服务清单
- 不在工作区内的服务仓(未 clone)→ 跳过 + 在汇总里标注"未扫描"
Step 2 — 跨服务改动收集
对每个目标服务仓,顺序执行(避免并发 git 锁):
cd <service>
git log <since>..HEAD --oneline --no-merges
git diff <since>..HEAD --stat
git diff <since>..HEAD -- \
'modules/api/init.go' \
'modules/api/biz/**' \
'modules/api/ctrl/**' \
'migrations/**.sql' \
'**.sql' \
'conf/*.yml' \
'agent/**' \
'pipeline.py' \
'state.py'
汇总产出(per-service):
- 提交数量 + 主要 commit message
- 改动文件清单(分类:路由 / 业务 / SQL / 配置 / Agent / 其他)
- 路由变化:新增 / 修改 / 删除的 endpoint(grep init.go 的 RouterGroup / Handle)
- DDL 变化:新增 / 变更表 + 字段(grep migrations / *.sql)
- 配置变化:新增 / 改动的 Apollo / settings.yml key
- MQ 变化:新增 topic / 消费者注册
Step 3 — 对比与差异分析
三方对照:
- A. 阶段一方案(
--design 文件 § 1-8)
- B. 实际改动(Step 2 汇总)
- C. 当前项目级文档现状
按 AGENTS.md § Project Doc Update Triggers 表生成回写计划(详见 references/archive-checklist.md):
| 改动类型 | 触发判定 | 写入目标 | 写入要点 |
|---|
| 新增 / 改 HTTP 路由 | 路由前缀或 Method 语义变化 | docs/contracts.md | 加一行/改一行,不重写全文 |
| 异步回调 / Agent 链路 | callbacks 约定变化 | docs/contracts.md | 同上 |
| 错误返回格式 | 新错误类型 / 字段 | docs/contracts.md | 同上 |
| 服务边界 / 写权威翻转 / 主链路改 / Deprecated 新增 / 缩写表前缀变 | architecture 表更新 | docs/architecture/README.md + docs/assets/万兴剧厂概要设计.md | architecture 改表格行,概要设计同步段落 |
| 新增领域术语 / 数据键 / 状态枚举 | 新概念出现 | docs/architecture/glossary.md | 加术语条目 |
| 新增分区 / 配置 / Agent / 任务积分硬约束 | rules 变更 | docs/engineering/rules.md | 加一条或改一条 |
| 新增联调 / 排障知识 | 实施期遇到值得记录的坑 | docs/runbooks/README.md | 加排障条目 |
| hard-to-reverse 架构决策 | 服务拆分 / DB 选型 / 写权威翻转 / 协议变更 | 新建 docs/architecture/adr/{NNN}-{slug}.md | 用 template.md 五段 |
始终回写:--design 文件 § 9 实施回写章节。
- § 9.1 实际状态(Implemented / Partial / Cancelled)
- § 9.2 与设计差异(逐条对比 § 2-6)
- § 9.3 关联 PR / Commit
- § 9.4 项目级文档回写清单
Step 4 — 🛑 回写预览 Hard Stop
本卡点为 ../../specs/shared/hard-stop-templates.md § Gate 1 形式 B(展示体量大,纯文本不调 AskUserQuestion)。
展示模板:
## 回写预览
### 1. 设计 → 实施差异摘要
- 接口:<已实现 N/M 条 + 新增 X 条 + 变更 Y 条>
- 数据库:<DDL 已落 N 张表 / 字段差异 X 处>
- 时序:<与设计一致 / 偏差 X 处>
- 工时:<估 X 人日,实际 Y 人日>
### 2. 项目级文档回写计划
| 文件 | 操作 | 行数变化 | 是否超 budget |
| --- | --- | --- | --- |
| docs/contracts.md | 加 2 行 | +2 | 否(47→49,limit 80) |
| docs/architecture/README.md | 改 1 行(写权威表) | ±0 | 否 |
| docs/architecture/glossary.md | 加术语 1 条 | +3 | 否 |
| docs/assets/万兴剧厂概要设计.md | 改 § 二 1 段 | +5 | 无 budget,可写 |
| docs/architecture/adr/009-xxx.md | 新建(用 template.md) | NEW | 否 |
| docs/designs/<slug>-<date>.md | 回写 § 9 | +30 | 无 budget |
### 3. Hard Coding Rules 实测自检
逐条对照阶段一 design-plan 里的"5 条规则触及 / 遵循"声明,用实际代码验证:
- 分区键:<实测所有大表查询带 wsid / 否,列违规位置>
- 跨服务写:<实测无 / 有,列违规位置>
- 任务终态 / 积分:<实测对齐三类记录 / 否>
- Agent 边界:<实测走 rmagsrv + mtrsrv / 否>
- 密钥 Apollo:<实测密钥全 Apollo / 否>
### 4. 关键 diff 摘要(每服务一句)
- rmdfsrv: <X 个 commit,新增批量上传 handler + 1 张表>
- rmaisrv: <Y 个 commit,加 MQ 消费者分支 + 配置项>
- ...
### 5. 未扫描的服务(若有)
- <service>: 未 clone 到工作区,跳过
### 6. 风险 / 残留
- <例如 § 9.2 偏差是否需要补 ADR>
- <例如 budget 超限需迁 ADR>
反馈方式提示(原样输出,不调 AskUserQuestion):
反馈方式:
1. 全部回写按预览执行 → 回「1」/「继续」/「OK」
2. 终止(回写计划不对) → 回「2」/「终止」
- 部分回写 → 直接说改哪些(如"先不写 ADR,等下次","glossary 那条术语换个名")
用户回复归一化:
| 用户回复 | 归一化路径 |
|---|
1 / 继续 / OK | confirm → Step 5 |
2 / 终止 / reject | manual_intervention → 不落盘 |
| 自由文本指出修改 | revise → 调整回写计划后重新输出 Step 4 |
模糊回复 → 反问。立即停止,等用户明确输入。
Step 5 — 落盘 + 自检 + 汇总
用户回 1 / 继续 后,逐文件 Edit(优先 Edit 不用 Write 全量重写;新建文件除外):
5.1 写入顺序
- 先写
docs/designs/{slug}-{YYYYMMDD}.md § 9(主索引)
- 再写
docs/architecture/* / docs/contracts.md / docs/engineering/rules.md / docs/runbooks/README.md(单条 Edit)
- 最后
docs/assets/万兴剧厂概要设计.md(总览,影响最大)
- 若新建 ADR,最后做(用
docs/architecture/adr/template.md 沿袭格式)
- 估时校准回流:若主 design § 5 有估时且能取到实际工时,append 一行到
docs/designs/_estimation-log.md(详见 references/archive-checklist.md § 6);取不到实际工时则跳过
5.2 每文件落盘后自检
5.3 汇总输出
✅ 归档完成
### 写入文件
| 文件 | 操作 | 行数变化 |
| --- | --- | --- |
| docs/designs/<slug>-<date>.md § 9 | 回写实施 | +30 |
| docs/contracts.md | +2 行 | 47→49 |
| ...
### 新建 ADR
- docs/architecture/adr/009-xxx.md(若有)
### 未回写(用户指示跳过 / 阻断)
- <文件>: <原因>
### 下一步建议
- 把回写 PR 发给团队 review
- 若有"未回写 / 阻断"项,跟踪到下一迭代
关键原则
- 以代码改动为准,不以记忆为准 — 必须跑 git log / diff 拿事实
- Edit 优先于 Write — 项目级文档大多 ≤ 100 行,改一两行不要全量重写
- Documentation Budget 是硬约束 — 超出就拆 ADR,不要为了凑 budget 删原有内容
- Hard Stop 是真决策点 — 回写涉及多个团队共享文档,必须卡住等用户确认
- 未扫描的服务不假装扫了 — 显式标注,跟踪到下次
