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