eryao/.opencode/commands/doc-update.md

description

description
审查并更新 docs/protocols，确保与当前代码实现一致

你现在要执行一次“协议文档一致性审查与更新”，目标是让 docs/protocols/ 成为项目协议与数据格式的最新事实来源，并与当前代码实现保持一致。

执行目标

1. 审查 docs/protocols/ 下所有协议文档是否过期、缺失或与实现不一致。
2. 在发现差异时，优先更新协议文档（而不是先改代码），明确兼容策略。
3. 输出结构化审查结果：发现的问题、已更新内容、仍待确认项。

约束

• 审查范围优先限定在：docs/protocols/** 与本次协议相关代码（backend/**、apps/**）。
• 不做无关重构，不改动与协议无关模块。
• 禁止“吞错式”描述：若不确定，明确标记为待确认，不要假设正确。
• 若涉及破坏性变更，必须在文档中写明迁移与回滚策略。

步骤

1. 建立协议清单

   • 列出 docs/protocols/ 中所有文档。
   • 为每份文档提取：涉及的接口、事件、字段、枚举、状态码、错误结构。

2. 建立实现映射

   • 在 backend/**、apps/** 中定位对应实现与调用点。
   • 对每个协议项建立“文档 -> 实现”映射（文件路径 + 关键符号/接口名）。

3. 逐项比对并分级

   • 比对以下维度：
     • 请求/响应结构与字段可选性
     • 字段命名、类型、默认值、约束
     • 错误码/错误体格式
     • 版本号、兼容说明、废弃说明
   • 给每个差异打级别：
     • CRITICAL：会导致客户端/服务端不兼容
     • HIGH：行为偏差明显，容易引发线上错误
     • MEDIUM：文档缺失或描述不完整
     • LOW：措辞、示例、格式问题

4. 更新文档（优先）

   • 先更新 docs/protocols/**，使其反映当前真实实现。
   • 每处更新都要补充“兼容策略”：
     • backward-compatible（向后兼容）或
     • requires-migration（需要迁移）
   • 如为 requires-migration，补充迁移步骤与回滚注意事项。

5. 一致性复核

   • 复查所有变更是否与实现一致。
   • 如仓库有协议相关测试/校验脚本，执行最小必要验证。

输出格式（必须）

1. Protocol Audit Scope

   • 本次审查的文档列表
   • 对应实现文件映射

2. Findings

   • 按 CRITICAL/HIGH/MEDIUM/LOW 分组列出差异
   • 每条包含：文档位置、实现位置、差异说明、影响范围

3. Doc Updates Applied

   • 列出已更新的文档与关键修改点
   • 标注每项兼容策略（backward-compatible / requires-migration）

4. Open Questions

   • 仍需产品/后端/前端确认的点

5. Verification

   • 列出执行的验证命令与结果（通过/失败）

完成标准

• docs/protocols/ 覆盖当前实现的真实协议。
• 所有发现的关键差异（CRITICAL/HIGH）要么已修正文档，要么被明确记录为阻塞项。
• 输出报告完整，后续协作者可据此继续推进。