webnovel-writer/.trellis/tasks/archive/2026-07/07-06-fix-review-round3/implement.md

执行计划：第三轮 review 修复

按批推进，每批一个 commit（独立回滚点）。每批完成即跑该批验证命令；最后一轮全量。

约定：测试命令在 v7/ 下跑，Windows 需 PYTHONUTF8=1（涉 python 时）与 $env:NODE_OPTIONS 不动；node 测试 npm test（vitest）。

批 0：测试基建（G-1）

• test/commands/_helper.js gitBookCtx：写 .gitignore（.cache/、工作区/）+ core.quotepath false + 只 add 跟踪面（对齐 persist.js:58-78）
• 跑全量测试，逐条修正依赖旧形态的断言（预期 goto/relink/finalize 相关有波动）
• 验证：npm test 全绿；git -C <tmp仓库> ls-files | grep 工作区 为空（用一条新断言固化）

commit: test(v7): gitBookCtx 对齐真实建书形态（G-1）

批 1：数据安全 + 互斥守卫（R1 R2 R3 R4 R7 R8 R12 + C2/C4/G-4）

• R7/R8 serializers/yaml-dialect.js：needsQuoting 补全 + 双引号分支完整转义；新增往返测试表（review 全部 DRIFT/PARSEFAIL 值）
• R12 storage/atomic.js：renamedIn 标志 + restorePlan 三段式；故障注入测试（第 2 文件 writeFile 抛错 → B 原文完好）
• R3 state-machine/persist.js：validateRepairContent 按路径分派（book.yaml→parseBookConfig / 名册·时间线→parseMarkdownTable / 其余→parseFrontMatter）；测试覆盖三类文件修复被接受
• R4+C2+G-4+C4：util/workspace-path.js normalizeWorkspaceRel（剥前缀+按段拒 ..）；finalizeChapter/stageChapter/两命令壳接入；finalize 清理 recursive+try/warning 不改写 ok；测试：目录清理失败仍 ok:true、.. 逃逸被拒、前缀直调不漏清
• R1 flows/goto-chapter.js + R2 commands/finalize.js：active 批次守卫 + 人话指引；测试：批次在场 goto 被拒、手动 finalize 被拒（用批 0 修正后的 gitBookCtx）
• 验证：npm test；针对性重放上轮探针场景 P-1/P-2/P-3/P-7b 断言新语义

commit: fix(v7): 互斥守卫+序列化器+原子写时序——第三轮 review 批1（R1-R4/R7/R8/R12）

批 2：迁移链（R5 R6 R9 R10 R11 + G-3 落点）

• R6 util/aliases.js splitAliases 单源；EntityReader:87 / rebuilder:262 / staging 接入（A13 顺带）
• R5 util/entity-type.js normalizeEntityType；rebuilder scanEntities/scanCharacters（ON CONFLICT 补 type）+ EntityReader 降级路径接入；fixture 名册类型改中文；测试：中文类型迁移书 list-characters/report/审稿名册可见
• R11 serializers/markdown-table.js + parsers/markdown-table.js：\| 转义读写对称、全角行归一、多余列保留；EntityWriter.upsertRosterRow 合并保额外列；往返测试
• R9 migrate/transform.js book.yaml 走 serializeYAML；测试：[快穿]反派/*追读/纯数字书名迁移后 parseBookConfig ok 且 books.jsonl 扫描重建不丢书
• R10 transform 一对多别名降级（首实体保留+待校对文件）；测试：共享别名 v6 项目迁移成功、待校对文件在、rebuild 无别名冲突
• 验证：npm test + migrate e2e（v6-inline/v6-sqlite fixtures）+ 探针场景 P-5/P-6

commit: fix(v7): 迁移链类型/别名/序列化收口——第三轮 review 批2（R5/R6/R9-R11）

批 3：P2/S 清扫 + spawn 冒烟

按 design.md 模块分组执行，可按模块拆多个小 commit：

• storage/adapters：A6 键名统一中文、A9/C3 有界匹配、A10/F-7 角色卡文件名同源、A12 时间线按（卷,章）替换、A14/A15/A16 死代码删除、A17 段匹配收紧
• cache：B1 warning 补齐+catch 收窄、B2 UNIQUE 冒泡 ROLLBACK+卷复盘条目查重、imagery preserveDerived（决策 D5）
• staging/dto：E3 幂等重跑（决策 D3）、E4 清理失败不谎报、E5 --until 建议、E6 打回空目录状态、E8 isWeakHook 单源、D5/D6 readBatch heal 参数+现存口径
• state-machine：D3 区 TRACKED_SOURCE_PREFIXES（决策 D6）、D4 retcon 逐文件回滚、D7/G-7 防御
• migrate/export：F-4 码点截断、F-5 mtime 阈值、F-6 删可写回退（决策 D4）、F-8 错误人话化、F-9 warning+类型归一复用、F-10 保留设备名
• bin/docs：G-9 命令名白名单、G-8 删硬编码计数、G-5 files 加 docs/
• G-6：bin spawn 冒烟 ×2（export/migrate）
• 验证：npm test 全量

commit: fix(v7): P2/S 清扫——第三轮 review 批3（或按模块多 commit）

收尾

• spec 回填：story-repo-spec 0.14（G-3/E7/E9 条款 + 决策表）、database-guidelines B-S 条款、SKILL.md rosterUpserts 值域
• 上轮探针脚本拷入本任务目录改造为修复后断言，跑通留档；有代表性的场景确认已固化进正式测试
• 全量验证：npm test（429+新增全绿）→ push 观察 CI 六 job
• AC 逐条勾验 → spec 更新（3.3）→ commit → 归档

commit: docs(v7): spec 0.14 回填——第三轮 review 修复收口

回滚点

每批独立 commit；批 1/2 涉及序列化器写路径，若发现写格式回归（存量书读不回），revert 对应批 commit 即可——读路径未动，存量文件安全。

风险与注意

• 批 0 的断言修正量未知（gitBookCtx 被 goto/relink/finalize 多处测试用），预留弹性；修正原则=对齐真实形态，不为保绿而弱化断言。
• E3 幂等重跑改了 finalizeBatch 循环顺序（先 meta 后 rm），注意与 readBatch「记录外目录按受影响纳入」的交互——meta 已删行+目录残留时目录会被重新纳入，因此删除失败必须报错止步（不能静默继续），设计已定。
• A6 键名统一会改 read-chapter/read-thread 的缓存命中输出形状——检查 SKILL/roles 是否有依赖英文键的文案（预期无：作者域一直宣称中文）。