文档写作与优化规范
本文件是 给模型（Agent）使用的文档优化规范。当任务涉及"优化文档""改文档文案""审查中文表述""整理发版日志"等需求时，必须先读本文件，再动手修改 CHANGELOG.md、docs/**/*.md、skills/**/SKILL.md 等中文文档。
人维护者同样遵循本规范。规范本身也受规范约束。
1. 适用范围
| 文档 | 路径 | 备注 |
|---|---|---|
| 发版日志 | CHANGELOG.md（站点经 docs/changelog.md 包含） | 受 release-please 约束，见 §4 |
| 用户文档 | docs/**/*.md | VitePress 站点源 |
| Skill 协议 | skills/**/SKILL.md、references/*.md | 英文 SSOT；用户可读中文在 docs/commands/ 等站点页 |
| 斜杠命令薄入口 | claude-commands/*.md | 行数门禁 ≤40 行 |
| 仓库规则 | AGENTS.md、ARCHITECTURE.md | 修改后需同步事实层 |
历史文件豁免：
exec-plans/completed/**、design-docs/**已完结条目与CHANGELOG.md已发布段落不回溯改写；新写内容仍须遵循本规范。
2. 中文文案总则
2.1 用词：书面优先，禁用口语动词
发版日志与用户文档面向外部读者，统一用书面语。禁止以下口语动词，改为右侧书面词：
| 禁用（口语） | 改用（书面） |
|---|---|
| 跑（跑 ralph_ops / 跑测试） | 执行 / 运行 |
| 搬（搬进 completed/） | 移动到 / 迁入 |
| 吃（只吃该文件 / 不吃聊天） | 读取 / 消费 |
| 清掉（清掉残留） | 清理 |
| 长出（长出"已落地"） | 生成 / 写入 |
| 压到（正文压到子代理返回） | 延迟到 |
| 钉（钉 high / 钉死） | 固定为 / 锁定 |
| 干等 | 静默等待 |
| 挡（仍挡连败） | 拦截 / 阻断 |
| 挂在（挂在 same 入口） | 绑定到 / 放在 |
| 当（当开机清单） | 当作 |
| 教（不教 CLI） | 引导 / 说明 |
| 宣称（不宣称提速） | 声称 / 对外宣传 |
| 回（先回 [OK]） | 回复 |
| 记账（对话记账） | 记录 / 记账仅作 ledger 术语时保留 |
| 喊（怎么喊 / 装好后怎么喊） | 调用 / 写法（见 §2.1.1） |
| 工人（实施工人 / 审查工人） | 执行人（实施执行人 / 审查执行人） |
| 入职（入职 prefix / 调研入职） | 人设提示词 / 派单前缀 |
| 可后读 / 可先看 | 进阶（或去掉括号提示） |
| 用户怎么说 | 用户常用说法 |
| 薄斜杠命令 / 薄入口（用户文档） | Claude 斜杠命令 / 斜杠命令入口 |
| 单仓 / 单仓闭环 | 任务 / 任务闭环 |
要刷新旧副本才加 --force | 覆盖已有安装请加 --force |
| 须你同意才加行 / 才投喂 | 写入须经你确认 |
| 你点头才写 | 经你确认后写入 |
| 不会替你切 / 不替你 X | 不会自动切换分支 / 不负责 X |
| 这一页带你从零到 | 本页说明如何…（直接陈述目标） |
| 输入前缀看有没有补全 | 试输入前缀确认入口可用 |
| 站对位置 | 准备工作区 |
| 公司另有路径可在 | 组织级路径可在 … 配置 |
| 投喂（知识库，用户文档） | 写入（知识库） |
2.1.1 对话入口表述（禁用「喊」）
用户文档说明 skill / 斜杠命令前缀时，禁止用「喊」作动词或标题。
| 禁用（口语） | 改用（书面） |
|---|---|
## 怎么喊 | ## 对话入口 |
## 装好后怎么喊 | ## 装好后如何调用 |
## 可以怎么说 | ## 常用说法 |
表头 怎么喊 | 写法 |
表头 怎么说 | 示例说法 |
| 让它分流 | 由它帮你选择入口 |
正文仍可保留用户原话示例（如「收工」「交接到…」），但章节标题与表头用上表右侧。
2.2 量词：统一为"轮 / 次 / 个"
禁止用"刀""片"作切片量词。
| 禁用 | 改用 |
|---|---|
| 上一刀工人 / 这一刀 / 派下一刀 | 上一轮 / 当前轮 / 派下一轮 |
| 每片冷启动 | 每个切片冷启动 / 每次冷启动 |
| 一刀一派 | 一轮一派 |
2.3 进程与角色：用"运行中"，禁用"活着"
| 禁用 | 改用 |
|---|---|
| 活着的工人 / 活着的 reviewer | 运行中的执行人 / 运行中的 reviewer |
| 空壳（再 init 空壳） | 空壳 → 空占位 / 空会话 |
2.4 中英文混排
- 可保留英文的：已成术语且替换会损失精度的，如
run、gate、spawn、commit、diff、PASS/FAIL/BLOCKED、run_id、task_key、STAGNATION。 - 应改为中文的：能无损中文化且不损失精度的，如
inherit→继承、skip→跳过、listed→列出的/指定的、non-tiny→非 tiny、conversational→对话路径、parent→父会话、plane→控制面、team-lead→团队负责人。 - 首次出现术语：英文术语首次出现时建议括注中文，如
gate（门禁）；同一文档内后续可只用英文。 - 中英空格：中文字符与英文/数字之间统一加一个空格，如
派遣 reviewer、52–96 次工具调用。反引号包裹的代码标识符前后同样加空格。 - 风格一致：同一文档内对同一术语不要时中时英。
2.5 指代与补全
- 禁止悬空指代。"那五份手册""Task n+1""返回注释"等需补全名称或加链接。
- 派单模板类引用应写全，如
Task n+1 派单模板，或拆分说明。 - 缩写首次出现需展开，如
CAP（capability）。
2.6 标点与格式
- 分隔符：并列项统一用
、（顿号），禁止用·（中点）作并列分隔。COMPLETED·ABANDONED·PAUSED改为COMPLETED、ABANDONED、PAUSED。 - 破折号：版本标题时间分隔用
—（em dash）；正文解释用——（双 em dash）或冒号。 - 引号：中文用直角引号「」或弯引号""，全文统一；代码/标识符用反引号。
- 双花括号：VitePress 把
当 Vue 插值，正文与行内代码均禁止出现；只有围栏代码块安全。 - 标题格式：版本标题带时间戳时统一为
## <版本> — <YYYY-MM-DD HH:mm>。
3. 条目写作规范
3.1 一条一义
每条以 **主题**： 开头，冒号后接一句完整陈述。禁止把多个不相关变更塞进同一条。
3.2 动宾完整
- 禁止省略主语导致歧义："
不 gate 当前/下一阶段" 改为 "不触发当前/下一阶段 gate"。 - 禁止动词残缺："
再一次保存 analyze/plan/deliver" 改为 "再次保存 analyze/plan/deliver"。
3.3 证据可追溯
涉及行为变更的条目应附：合约测试路径、评估编号（EP-*）、commit 或 PR 链接。链接写绝对 URL（CHANGELOG 内）或源文件相对路径（docs 内）。
4. CHANGELOG 专项规范
4.1 release-please 边界（重要）
CHANGELOG.md由 release-please 维护。已发布版本段落（带时间戳的## <版本> — <时间>）内容不再改动，否则破坏 release-please 追踪。- 仅
## Unreleased段落可自由编辑；发布时 release-please 会将其升格为版本段落。 ## Unreleased始终保留。无待发布条目时正文只写暂无。（散文，禁止写成-列表，以免升格进下一版）。有新条目时删掉这行；发版把列表条目升格后写回暂无。。- 如需修订已发布版本的文案错误，先与维护者确认，并评估是否影响
src/releaseLog.mjs的版本提取（正则匹配版本标题）。
4.2 条目结构
- **主题**：陈述。合约：`tests/xxx.test.mjs`。eval：`EP-yyyymmdd`。- 主题用名词短语，陈述用完整句子。
- 子项用缩进 4 空格的
-列表。 - 评估编号、commit、PR 写在条目末尾，用句号分隔各段。
4.3 常见文案问题对照（CHANGELOG 专项）
| 原文（问题） | 改为 |
|---|---|
| 审查工人 reasoning 钉 high | 审查工人 reasoning 固定为 high |
| 上一刀工人已结束 | 上一轮工人已结束 |
| 不要每片冷启动 | 不要每次冷启动 |
| 活着的工人只用 send_subagent_message 纠偏 | 运行中的执行人只用 send_subagent_message 纠偏 |
| spawn 只吃该文件，不吃聊天 | spawn 只读取该文件，不读取聊天 |
| 归档搬 completed/ | 归档移动到 completed/ |
| 对话路径不跑 ralph_ops | 对话路径不执行 ralph_ops |
| 不要干等 | 不要静默等待 |
| 缺失才回退 general-purpose | 缺失时才回退 general-purpose |
| 本轮文案/样式 skip | 本轮文案/样式跳过 |
| 审查员只读 listed 文件 | 审查员只读指定文件 |
| 禁止整仓 grep | 禁止全仓 grep |
| 大功能（non-tiny）deliver 后 | 大功能（非 tiny）deliver 后 |
| conversational $jj-same | 对话路径 $jj-same |
| spawn 必须带入职 prefix | spawn 必须带派单前缀 |
| Ralph 入口按客服 team-lead | Ralph 入口按客服 team-lead（团队负责人） |
| 禁止在 parent 改业务代码 | 禁止在父会话中改业务代码 |
| 多轮对话不能推进 plane | 多轮对话不能推进控制面 |
| 顺带抬起上一刀遗留 STAGNATION | 一并重置上一轮遗留 STAGNATION |
| STAGNATION 仍挡同一切片连败 | STAGNATION 仍拦截同一切片连败 |
| 禁止 set-status 假装抬上限 | 禁止 set-status 伪装上调上限 |
| 审查/提交按证据与授权跟随 | 审查/提交依证据与授权进行 |
| 机械 CLI 保留单键及遗留兼容 | 机械 CLI 保留单命令入口及遗留兼容 |
| 先回 [OK]/[BLOCK] 再落盘 | 先回复 [OK]/[BLOCK] 再落盘 |
| 现场：全平台装过旧版后 | 场景：全平台装过旧版后 |
| 把 references/ 当开机清单 | 把 references/ 当作启动清单 |
| 不是工人说明书 | 不是子代理操作说明 |
| live plan 长出"已落地"/"Landed" | live plan 生成"已落地"/"Landed" |
| 来自 team-lead…Task n+1 | 来自 team-lead 的 Task n+1 派单模板 |
| 命令入口也不点名那五份手册 | 命令入口也不再引用那五份参考手册（并补全名称） |
5. 优化流程（模型执行步骤）
- 先读本文件。
- 定位目标文档：用 Glob/Grep 找到待优化文件；CHANGELOG 先确认是
Unreleased还是已发布段落。 - 按 §2/§3 扫描问题：用词、量词、中英混排、指代、标点、动宾完整性。
- 逐条改写：保持事实不变，只改表述；保留所有合约/eval/commit 引用。
- 不改语义：优化文案不得改变行为描述、门禁条件、证据链。拿不准语义时停下问用户。
- 验证：
npm run docs:check（内链 + 侧栏覆盖）- 改了
CHANGELOG.md时确认node --test tests中涉及 releaseLog 的测试通过 git diff --check（空白错误）
- 报告：列出改了哪些文件、哪几类问题、是否触及已发布版本。
6. 不做什么
- 不凭喜好改术语：已成约定的项目术语（ralph、same、dispatch、CAP、DEL-* 等）保留；
ralph_ops仅在机械脚本 / 维护面语境保留，对话路径语境写「不执行 CLI」。 - 不把用户文档当 skill 运行时 SSOT：英文协议只改
skills/；中文用户说明改docs/commands/等站点页。 - 不用 chat/thread/memory 推进 checkpoint。
- 不改已发布 CHANGELOG 段落，除非维护者明确批准。
- 不为"通顺"删掉证据引用（合约测试、eval 编号、commit）。
7. 检查清单（提交前自检）
- [ ] 无口语动词（跑/搬/吃/清掉/长出/压到/钉/干等/挡/挂/喊）
- [ ] 对话入口不用「怎么喊」；表头用「写法」「示例说法」；不用「可后读」「用户怎么说」
- [ ] 无"刀/片"量词
- [ ] 无"活着/活审查"形容进程；用「运行中的」
- [ ] 无「工人」「入职」；用「执行人」「人设提示词/派单前缀」
- [ ] 无「薄斜杠」「才加
--force」「须你同意才投喂」「你点头才写」「不会替你切」「站对位置」「带你从零到」 - [ ] 中英混排一致，中英之间有空格
- [ ] 无悬空指代（那五份手册、Task n+1、返回注释等已补全）
- [ ] 并列用顿号，不用中点
- [ ] 无双花括号
- [ ] 动宾完整，无残缺动词
- [ ] 证据引用（合约/eval/commit）保留
- [ ] 未改动已发布 CHANGELOG 段落（或已获维护者批准）
- [ ]
npm run docs:check通过