name: docs-writing-protocol
description: 文档写入协议（去躁点版）。控制 AI 何时写入文档、写入什么内容。当用户说"沉淀到文件"、"记录下来"、"update: xxx.md" 时使用。
user-invocable: true
metadata:
short-description: 按需写入文档，纠错不记账，只记契约/流程/规则/语义变更
version: v1.0
文档写入协议（去躁点版）
目标：只有明确指定目标文件时才写入；写入时只记录设计/契约/语义的变化，不把修 bug、重试、风格调整等噪声落进文档。
核心原则（两句口诀）
- 写入门槛：没点名文件，就不写入（只在对话里回答）。
- 去躁点：纠错不记账；改契约/改流程/改规则/改语义，就记账。
1. 写入门槛
只有满足任一条件，才允许对 md 文件做持久化更新：
-
明确指定目标文件路径，例：update: docs/xxx.md
-
明确要求"生成/落地到某个文件路径"的文档产物
-
语义上表达"需要沉淀/记录/落地到文件"，例：
- "这个需求沉淀到文件"
- "把这个记录下来"
- "落地到文档"
- "需要持久化"
- "写进 xxx.md"
→ 若未指定文件名，先询问目标文件路径，确认后再写入。
否则：只在对话中输出，不创建、不修改任何文件。
2. 目标文件绑定
当用户第一次点名 X.md，设置 DocTarget = X.md，后续交互默认继续更新 DocTarget（仍遵守去躁点规则）。
- 切换目标：
switch: Y.md
- 停止写入：
stop writing
3. 去躁点判定
不写入
满足任一条：不写入 DocTarget
- 修复编译/语法/单测
- 修正 AI 理解偏差，但不改变既定设计
- 重试/提示词调整/代码风格/重构不改外部行为
口诀：纠错不记账
必须写入
满足任一条：写入 DocTarget
- 对外契约变了（接口字段、枚举、返回码、回调语义）
- 流程变了（状态机、时序、重试策略）
- 规则变了（优先级、分支条件、开关含义）
- 数据含义变了（字段意义、来源、映射、默认值）
口诀：改契约/改流程/改规则/改语义，就记账
4. 写入格式（强制最小化）
每次写入只允许：
- What changed：变化点（1~3 条）
- Why：一句原因
- Impact：对外影响（可选）
实现过程、排障、试错、重构细节一律不写入。
5. 交互指令
update: path/to/doc.md — 指定写入目标switch: path/to/another.md — 切换目标stop writing — 停止写入no-record — 本轮强制不写入（即便命中必须更新，也只在对话说明）
