8.4 KiB
8.4 KiB
架构文档同步工作流
1. 目标与边界
当用户要求“更新项目文档”或“同步架构文档”时，先只读分析影响，得到明确确认后，再局部同步当前实现文档。
运行时只允许修改：
core/backend/ARCHITECTURE.mdcore/frontend/ARCHITECTURE.md
禁止修改：
core/ARCHITECTURE.md- 任何业务代码、配置、迁移、测试和部署文件
- Git 暂存区、commit、push 和远端状态
- 本工作流、扫描脚本和 Skill 自身
不得访问或输出 .env、account.md、密钥、数据库文件、用户上传文件及其他敏感信息。
2. 基本原则
- 默认只读；没有有效确认时不得写文件。
- 使用扫描脚本提取事实，不用 AI 全量阅读项目代替扫描。
- 只读取扫描结果列出的证据文件和目标章节。
- 只做局部补丁，不整份重写文档。
- 保留原章节、历史决策和规划内容。
- 明确区分“当前实现”与“目标架构”。
- 无法从代码证实时，跳过并报告，不推测补写。
- 不覆盖或整理与本次任务无关的用户改动。
- 每次写入后必须验证；验证失败时停止，不扩大范围补救。
3. 状态机
IDLE
→ ANALYZE_READ_ONLY
→ WAIT_CONFIRMATION
→ REVALIDATE_PLAN
→ UPDATE_ALLOWED_DOCS
→ VERIFY
→ DONE
任何异常进入 STOPPED，报告原因并等待用户决定。
4. 阶段 A：只读分析
- 使用 Git 确定仓库根目录。
- 确认
tools/architecture-sync/scan_architecture.py存在；不存在则报告安装未完成并停止，不回退为全量 AI 扫描。 - 运行扫描器的
plan模式；默认使用--scope all，用户明确只处理后端或前端时分别使用--scope backend或--scope frontend。 - 解析扫描器 JSON；不得自行扩大
changed_files、evidence或目标文档范围。 - 若
analysis_ready不为true，说明扫描器的影响分析能力尚未安装完整并停止，不得进入确认或写入阶段。 - 若
requires_update=false，说明没有架构性变化并结束，不修改文件。 - 若存在影响，将扫描器返回的
plan_id、scope、snapshot_id、目标文档指纹和planned_updates作为当前对话唯一待确认计划，按“影响预览”格式展示，然后强制停止并等待确认；不得预先修改文件。
影响预览必须包含：
plan_id。- 发现的架构变化。
- 每项变化的证据文件。
- 准备修改的文档和章节。
- 明确不会修改的范围。
- 扫描警告和无法确认的事项。
使用以下输出结构：
架构文档更新计划：<plan_id>
更新范围：<scope>
发现的架构变化：
1. <变化>
- 依据：<证据文件或符号>
- 影响：<目标文档> · <章节>
准备修改：
- <目标文档> · <章节>
不会修改：
- core/ARCHITECTURE.md
- 业务代码、配置、迁移、测试和部署文件
- Git 暂存、commit、push
警告或待确认：
- <没有则写“无”>
是否确认更新？请回复：确认更新项目文档
5. 确认规则
有效确认必须同时满足：
- 当前对话存在尚未执行的影响预览。
- 用户确认的必须是当前唯一待确认
plan_id，旧计划、已执行计划和被新请求替代的计划均无效。 - 用户在预览后回复
确认更新项目文档；同一连续对话中也可接受明确的确认。 - 用户没有改变目标、排除项或更新范围。
- 待确认计划没有被新的请求替代。
新对话中的单独“确认”、含糊回复、提前确认或针对其他任务的确认均无效。
用户拒绝、改变范围或提出新约束时，立即丢弃旧 plan_id，使用新的 scope 或约束返回阶段 A 重新生成并展示计划；不得沿用旧确认。
6. 阶段 B：确认后重新校验
写文件前必须使用与待确认计划完全相同的 --scope 重新运行 plan：
- 新
plan_id与已确认值一致，才可继续。 - 证据文件、目标章节或目标文档发生变化时，展示新计划并重新确认。
- 目标文档自计划生成后被其他操作修改时，停止并重新计划。
- 扫描器返回警告升级、敏感文件或越界路径时，停止。
确认只授权当前 plan_id，不授权未来变化。
7. 局部更新规则
阶段 B 重校验通过后，锁定扫描器返回的 update_context，不得自行扩大范围：
- 校验
update_context.plan_id等于已确认plan_id，并校验每个document_preconditions.before_sha256仍与目标文档一致；任一不一致立即停止并重新规划。 - 将
evidence_allowlist视为最大读取白名单，只选取证明当前影响所必需的文件；禁止因方便而遍历其他代码。 - 目标文档只读取
document_preconditions.sections指定章节及定位标题所需的相邻行；不把整篇文档交给 AI 重写。 - 根据证据判断这是当前实现变化、规划变化还是普通业务修复；普通业务修复没有改变架构边界时，跳过该影响。
- 使用
apply_patch对一个文档、一个局部事实逐项修改；禁止生成整篇替换内容或用脚本重写 Markdown。 - 保留标题层级、术语、相对链接、风险说明、演进原则、历史决策和原有写作风格。
- 当前实现与历史设计或目标架构并存时，保留原内容并明确标注“当前实现”与“目标架构”，不得用当前代码覆盖历史决策。
- 正文事实确实发生变化时，将文首“最后核对”更新为执行当日日期，并将同步标记设置为
update_context.sync_metadata.marker；标记必须使用完整小写 HEAD SHA，且每份文档只能存在一条。 - 对缺少同步标记的
baseline_review，若证据核对后正文已经准确，允许只新增首次同步标记并更新“最后核对”日期；不得借首次基线核对改写无关正文。 - 若
has_uncommitted_evidence=true，同步标记仍只表示当前 HEAD；结果中必须说明包含了工作区证据，后续代码提交后需要再次扫描。 - 修改完成后直接进入阶段 C；不得执行
git add、git commit、git push，也不得生成或保存临时计划文件。
禁止：
- 删除未受影响章节。
- 为了“精简”覆盖整个文件。
- 把规划内容改写成已实现事实。
- 把暂时未使用的历史决策直接删除。
- 根据文件名猜测实现细节。
- 顺手修复代码、格式化其他文件或清理工作区。
- 在没有有效确认时执行以上任何写入步骤。
8. 阶段 C：验证
更新后必须使用原计划令牌运行：
python tools/architecture-sync/scan_architecture.py verify --scope <原 scope> --guard <update_context.verification_guard>
不得省略、修改或跨计划复用校验令牌。只有 verification.status=passed 才能完成流程。验证器检查：
- 本流程新增的文件修改是否仅落在两个允许文档。
- 计划外的目标章节是否保持不变。
- 原有一级、二级标题是否被误删。
- 文档引用的目录、文件和关键符号是否存在。
- 相对链接是否有效。
- 是否引入本机绝对路径、敏感信息或裸密钥。
- 是否出现异常大范围删除或整篇覆盖。
- Markdown 格式是否有效。
- 计划生成后 HEAD、相关代码指纹、证据文件和同步控制文件是否发生漂移。
验证失败：
- 停止流程并列出失败项。
- 按验证器返回的
code、message和suggestion向用户说明原因；不得绕过失败项。 - 不自动修改业务代码来迁就文档。
- 不自动扩大写入白名单。
- 不暂存、不提交、不推送。
验证通过后输出：
架构文档已更新：
- <文档> · <章节>：<一句话变化>
验证：通过
未执行：业务代码修改、git add、commit、push
9. 工作区保护
- 阶段 A 记录目标文档摘要和现有工作区变化，阶段 B 用于漂移检查。
- 已存在的用户改动属于用户，不得覆盖、回滚、暂存或提交。
- 如果现有改动与目标章节重叠且不能安全合并，停止并请求用户处理。
- 不使用
git reset、git checkout --或任何破坏性恢复命令。
10. 安装与能力缺失
缺少扫描脚本、Python、Git、读取权限或写入权限时：
- 明确指出缺少的能力。
- 保持只读并停止。
- 不改用无约束的全项目 AI 扫描。
- 不建议扩大业务服务权限或让线上服务访问 Git 仓库。