muse-agent-example/docs/实现回顾/专项检查-计划.md

全仓专项检查计划

日期：2026-09-16 ｜ 状态：已执行完毕并冻结（14 份模块报告与台账已产出；附录 A/B 已转正为审查标准） ｜ 编排：主代理统筹分派，子代理详细检查并出具报告 范围：仓内代码与文档；排除缓存、构建产物、小说正文与数据库内容。

1. 目的与范围

对 R2 合并后的全仓做一次质量、表述、链路、口径层面的专项检查，产出问题台账与处置提案；修复不在本计划内，另立计划经授权执行。

检查对象：src/muse、tests、web、数据库、工具、.agent、docs、根文件（AGENTS.md、README、Makefile、pyproject.toml、CLAUDE.md、.gitignore、.github/workflows）。

排除：

• 缓存与本地环境：.venv、node_modules、__pycache__、.zcode 等；
• 构建产物与生成物：src/muse/资源/工作台、资源.zip、docs/接口契约/生成/openapi.generated.json、web/src/接口/生成/类型.ts（只验与权威同步，不评质量）；
• 小说正文与创作内容：数据库内正文、实体、规划产物一律不读不改；
• 历史留痕（docs/实现回顾 既有文件、git 历史）：表述不复查、内容不修改。

2. 编排与交付

• 主代理：维护本计划口径；按第 4 节分派任务，每次列明 2~3 个最小必读文件；汇总去重成台账；复核阻断级发现；不代替子代理读文件。
• 子代理：按模块要求详细检查，报告落盘为 docs/实现回顾/专项检查-报告-<模块>.md；对话返回按《子代理交付》三要素不超过 20 行，只报结论与路径。
• 并行协调：检查期间另一会话正在提交，git 状态类证据只做一次性快照并注明时点；「.gitignore 与跟踪文件交集」已于当日 20:43 复检（跟踪 1320 / 命中 0）。

3. 检查方向（现状 → 目标）

D1 代码质量

现状：门禁齐全（make 检查、make 测试、make 前端检查、make 前端测试）但本轮未在当前工作区复核；复杂度、超长文件、吞错、伪抽象从未系统排查；ruff 规则集（E/F/W/I/B/UP）不含复杂度类。 目标：门禁红绿有结论；后端 295 个文件全部经子代理精读；热点（复杂度、超 500 行、吞错、无证据抽象）全部入台账；测试文件按第 4 节深度抽查断言真实性与隔离纪律。

D2 AI 泔水识别

现状：去 AI 味口径已成文（AGENTS.md 汇报纪律、《中文正文与界面》规范），但代码、文档、提示词从未按此复查；R2 产出文档按旧口径写成。 目标：四类判定（套话、无判据的空洞承诺、同义重复、幻路径引用）覆盖全部权威文档与代码注释、命名、界面文案；泔水清单分级入台账；历史留痕豁免。

D3 代码链路清理

现状：前端构建产物被 gitignore 但仍被 git 跟踪（同类别未全量排查）；迁移 SQL 双物理副本（数据库/迁移 与 src/muse/资源/迁移 各 45 个）一致性未验证；tests/夹具 是空目录；迁移编号空洞（缺 V0008、V0010–V0015、V0017–V0019）；孤儿公共入口未排查。 目标：零误跟踪；迁移双副本零漂移或同步纪律成文；空目录与编号空洞消除或记录成因；公共入口零孤儿（每个入口有真实消费者或删除）。

D4 过期口径更新/清理

现状（已证实）：AGENTS.md 两行 SoT 指向已退出路径（muse/content/meta/schemas/、muse/lifecycle/flow/chains/）；「物理清单以 skills.json 为准」但全仓无此文件；「旧代码用 .venv-旧」所指环境不存在；多处链接文字是旧文件名（目标存在、文字未更新）；审查标准（提示词 4 问、技能 7 问、D8 规程）原文在 .agent/ 与设计文档中定位不到。未复核的旧结论：R2 审计「证据死链 846/889、AGENTS.md 三处矛盾」（来自记忆，未经机械复现）。 目标：现行权威文档零死链（以链接校验为机械证据）；过时陈述与旧链接文字清零；历史留痕豁免边界成文；被推翻或证实的旧结论同步更新记忆；审查标准缺失作为发现处置——找到原文回填，或本计划附录口径转正。

D5 提示词与技能质量

现状：.agent/角色 提示词与 59 个技能从未按结构化标准复查；审查标准原文缺失（见 D4）。 目标：提示词按附录 A 四问、技能按附录 B 七问逐个过；与《角色合同》的模型策略、工具权限一致性抽查；不合格项入台账。

D6 凭据与安全

现状：《凭据与外部调用》纪律成文，但从未全仓扫描硬编码凭据、SQL 拼接、危险路径操作。 目标：机械扫描加精读确认，凭据类问题一律 P0；CI workflows 的 secrets 用法核对。

D7 代码-文档一致性

现状：Makefile 自称「每个声明命令都必须真实可执行」未逐条验证；接口契约生成物与后端路由、web 类型的同步状态未知；AGENTS.md SoT 表与物理结构的一致性从未系统校验。 目标：Makefile 与 pyproject scripts 每条可执行；openapi 生成物与路由一致；权威文档声明抽查对照代码（每个领域至少 1 项）。

D8 依赖健康

现状：pyproject 9 个运行依赖、4 个开发依赖与 web/package.json 依赖的使用情况未清点。 目标：未使用与可收敛依赖清单入台账；升级建议只记录不动手。

4. 模块差异化要求

模块（规模）	方向	深度	模块特有要求
src/muse 17 个业务子包（295 .py）	D1 D2 D3 D6 D7	全量精读，按子包分 8 个子代理任务	命名与术语符合 .agent/规范；吞错、无证据抽象是重点；子包职责与领域 SoT 相符
src/muse/资源	D3	仅一致性	工作台与资源包是产物不读；迁移投影与 数据库/迁移 逐字节 diff；make 资源核对 跑一次
tests（157）	D1 D2	架构 5、契约 19、迁移 10、端到端 3、真实调用 1 全读；单元抽 10、集成抽 15	断言真实性；复制用例；隔离标记纪律（《测试隔离》）；用例清单登记一致
web/src（114）与 web/tests（53）	D1 D2 D6	门禁全量加精读抽样 20~30	界面文案泔水；dangerouslySetInnerHTML 等 XSS 面；生成类型与契约同步状态
数据库/迁移（45 SQL）	D3 D6	全量机械加基线与最新 3 个精读	编号空洞核对成因；幂等性；与投影 diff
数据库/旧库迁移（21 .py 加旧结构；该域已于 2026-09-18 整体退场）	D1	机械门禁加 3 个关键文件精读（映射台账、切换检查、入口）	有意 legacy 域：豁免泔水与风格要求
工具（7 文件）	D1 D6 D7	全读	与 Makefile、资源登记一致；路径操作安全
.agent（角色、技能、规则、约束、规范、作者）	D2 D4 D5	全量精读	附录 A/B 问句；与角色合同一致；目录索引与物理结构一致
docs 权威区（系统架构/新版设计、接口契约、运行手册、功能规格、各级目录）	D2 D4 D7	全量精读加链接校验机械全量	每个领域至少 1 项声明对照代码
docs/实现回顾 既有留痕	D4	仅机械统计	死链只计数不修；表述不复查
根文件与 .github/workflows	D4 D6 D7 D8	全读	AGENTS.md 已知过期点逐条处置；Makefile 命令逐条执行验证；workflows 与本地门禁一致

后端分派分组（每任务一个报告）：接入（48）；基础设施+共享（36）；审校修订+效果评测（48）；任务运行+编排（35）；交付连载+上下文（33）；资料研究+作者经验（26）；正文写作+作品规划（25）；知识方法+正式变更+故事世界+元数据（44）。

5. 严重度与处置

• P0 红线与风险：凭据泄漏、误导性权威声明、门禁红——立即报主代理，处置需授权。
• P1 事实错误：悬空引用、死代码、一致性断裂、标准缺失——本批修复候选。
• P2 熵增：泔水、空目录、重复、依赖冗余——择机修。
• P3 记录不改：历史留痕、有意保留项——台账注明理由。

台账每条二值收口：已修（经授权）或保留理由明确。

6. 报告与台账

• 报告：docs/实现回顾/专项检查-报告-<模块>.md，四节——结论（分级计数加一句话）、问题清单（编号｜位置 file:line｜方向｜严重度｜现状摘录｜建议｜所需授权）、豁免与边界（查了什么、没查什么、为何）、证据指针（命令加退出码或校验结果）。
• 台账：docs/实现回顾/专项检查-台账.md，主代理合并去重，按 P0 至 P3 排序；后续修复动作以台账为唯一输入另立计划。

附录 A：提示词四问（已转正为审查标准；原文缺失）

1. 职责边界：做什么、不做什么、输入来源是否成文？
2. 判定可执行：完成标准可机械判定，还是依赖模型自觉？
3. 合同一致：与《角色合同》的模型策略、工具权限一致吗？
4. 失败路径：越界或失败时的行为是否写明？

附录 B：技能七问（已转正为审查标准；原文缺失）

1. 触发命中：目录描述能让派发者命中该技能吗？
2. 边界成文：输入输出、做与不做是否明确？
3. 可复现：步骤确定可重复，该用脚本处是否用脚本？
4. 责任方：与角色槽位分工无重叠吗？
5. 证据留痕：执行后留什么、在哪查？
6. 失败恢复：中断后如何续跑？
7. 复利接入：接入 lesson 与范式卡升格链了吗？

边界与完成口径

• 本计划只检查、出报告与台账；修复另立计划；git add、git commit 一律需明确授权。
• 不动数据库与创作内容；不跑真实模型测试与备份恢复演练；数据库测试本轮不跑（CI 记录为证）。
• 完成 = 各方向目标达成且台账收口，机械证据齐（门禁退出码、链接校验结果、diff 结果），不以「看过了」作数。
• 收口（2026-09-18）：检查当日产出 14 份模块报告与台账；09-17 复核与用户裁决后进入优化执行合同，O00–O14 的离线可验部分已按六批提交合入 main，其后完成测试成本优化与旧库迁移退场。本计划与模块报告自此冻结为历史留痕，不再更新；现行口径以审查标准与优化执行合同为准。