webnovel-writer v6 迁移收官计划清理 Legacy Checker、落地章节状态状态机与 Spec 对齐【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer本文基于 webnovel-writer 仓库中归档的实施计划 2026-04-09-v6-migration-completion.md完整解读 v6 架构迁移的收官方案如何删除已被 reviewer 取代的旧 checker 聚合体系、如何为state.json引入单调递进的章节状态模型、如何修正 spec 与实现之间的偏差以及如何用可执行的 grep/pytest 退出标准验证迁移完成度。读完后你将掌握一套差距摘要 → 任务拆解 → 逐 Task 提交 → 退出标准验证的可复制迁移方法论并能对照当前仓库源码确认每一项工作的最终落地形态。一、计划背景为什么需要一个迁移收官阶段该计划面向 agentic workers即由 Agent 按任务逐条执行的开发模式明确标注了两种可使用的执行方式superpowers:subagent-driven-development推荐或superpowers:executing-plans并以- [ ]复选框语法追踪步骤。其元信息如下Goal完成 v6 迁移剩余工作——清理 legacy 代码、落地章节状态模型、修正 spec 与实现的不一致、通过退出标准验证Architecture三条并行工作线——(A) legacy 代码删除与清理、(B) 章节状态模型新增、(C) spec/参考资料修正。A 和 C 无依赖可并行B 是新功能需独立开发测试Tech StackPython 3.13、pytest、SQLitestate.jsonindex.db、Claude Code pluginmarkdown skills/agentsSpecv6 设计文档当前仓库归档位置为 2026-04-02-harness-v6-design.md前置条件Phase 1 的创建新模块部分已完成reviewer.md、review_schema.py、review_pipeline.py 均已存在且通过测试Phase 3memory_contract和 Phase 4context-agent research 模式已完成。这里体现了该计划的定位它不是从头设计的架构文档而是迁移收口清单——新体系reviewer review_pipeline已经就位剩余工作全部是删除旧体系、补齐一个新状态模型、并把文档拉齐。二、当前差距摘要迁移遗留项的全量盘点计划开篇用一张差距表把全部残留项定位到具体文件与行号这是该文档最有复用价值的部分——迁移类计划必须先回答还差什么、差在哪里类别残留项文件旧 checker 函数_normalize_checker_issue、_build_timeline_gate、_aggregate_checker_results、ReviewAggregateResultindex_manager.py:208-232, 678-808旧 checker CLIaggregate-review-results、materialize-review-metricsindex_manager.py:963-969, 1318-1327旧 checker 脚本整文件 570 行golden_three_checker.py旧 checker 测试test_aggregate_checker_results_cliL1428-1551、test_aggregate_checker_results_blocks_...L1553-1596test_data_modules.py旧 checker 测试test_index_aggregate_review_results_forwards_...L173test_webnovel_unified_cli.py:173-218旧 checker 引用continuity-checker在已知 checker 列表test_prompt_integrity.py:247workflow 残留注释引用 测试白名单webnovel.py:94、test_prompt_integrity.py:221Step 2B 残留职责边界说明polish-guide.md:13-17legacy 引用continuity-checker映射表reading-power-taxonomy.md:343-348legacy 消费overall_score用于低分告警context_manager.py:310-318缺失功能章节状态模型无需新增到state_manager.pyspec 不一致v0 接口尚未实现但实际已实现spec 4.5上表路径均为当时 monorepo 布局下的相对位置对应当前仓库中 webnovel-writer/scripts/data_modules/ 目录下的文件。配套的文件级改动清单分为三类要删除的文件文件原因scripts/golden_three_checker.py旧 checker 模式570 行已被 reviewer 替代要修改的文件文件改什么scripts/data_modules/index_manager.py删除ReviewAggregateResult、旧 checker 函数、旧 CLI 命令scripts/data_modules/context_manager.pyoverall_score低分判断改为 severity 信号scripts/data_modules/tests/test_data_modules.py删除旧 checker 聚合测试约 170 行scripts/data_modules/tests/test_webnovel_unified_cli.py删除旧 aggregate-review-results 转发测试scripts/data_modules/tests/test_prompt_integrity.py清理 checker 白名单、workflow_manager 白名单scripts/data_modules/webnovel.py清理 workflow_manager 注释scripts/data_modules/state_manager.py新增 chapter_status 管理skills/webnovel-write/references/polish-guide.md删除 Step 2B 边界段落references/reading-power-taxonomy.md更新 checker 映射表v6 设计 spec修正 spec 与实现不一致要创建的文件文件职责scripts/data_modules/tests/test_chapter_status.py章节状态模型测试三、Task 1-2移除旧 checker 聚合体系v6 的审查路径从多个独立 checker 脚本 聚合器收敛为单一 reviewer agent review_pipeline 流水线。Task 1 负责删除聚合器一侧步骤是删除ReviewAggregateResultdataclassindex_manager.pyL208-232 及to_review_metrics方法。这里有一条关键约束保留ReviewMetricsdataclass因为它仍被save-review-metricsCLI 使用。从源码结构看这一区分在 index_manager.py 当前版本中成立——ReviewMetricsL196 附近与save-review-metrics的 parser 注册L866 附近、命令处理L1227 附近仍然存在而ReviewAggregateResult、_aggregate_checker_results等符号已无处可查删除三个旧 checker 函数_normalize_checker_issue、_build_timeline_gate、_aggregate_checker_resultsL678-808删除旧 CLI 注册与处理分支aggregate-review-results、materialize-review-metrics两个子命令的 parser 注册L963-969与命令处理L1318-1327删除配套测试test_data_modules.py中 L1428-1596 的两个聚合测试函数约 170 行以及 test_webnovel_unified_cli.py 中 L173-218 的转发测试回归测试python -m pytest webnovel-writer/scripts -x --tbshort --no-cov预期全部通过单独提交commit message 明确说明reviewer review_pipeline 已完全替代。Task 2 删除 golden_three_checker.py 整个文件570 行并给出了一个值得借鉴的删除前验证步骤grep -r golden_three webnovel-writer/ --include*.py --include*.md | grep -v golden_three_checker.py # Expected: 无命中或仅在 test_prompt_integrity 白名单中当前仓库中该文件已不存在佐证此任务已执行完成。四、Task 3清理散落的 legacy 引用legacy 代码的危害不只在于死代码本身还在于文档和测试白名单里残留的旧世界地图。Task 3 处理四处webnovel.py 的注释L94把兼容没有 main() 的脚本例如 workflow_manager.py改为不再提及已删除的 workflow_manager——注释里引用不存在的文件会误导后续维护者test_prompt_integrity.py 的白名单将golden_three_checker.py加入KNOWN_DELETED_FILESL215-223 区间并审视 L247 处continuity-checker引用的语义——计划特别要求先确认该检查是不应出现在 prompt 中保留还是允许出现的白名单移除这种删除前先判断引用语义的步骤避免了误删防护逻辑polish-guide.md 的 Step 2B 段落L13-17Step 2B风格转译在 v6 流程中已取消原职责边界说明失去对象。替换后的职责定义收敛为Step 4 同时负责风格适配消除模板腔、说明腔、机械腔和问题修复包括审查问题修复、Anti-AI 终检、毒点规避reading-power-taxonomy.md 的 checker 映射表旧表列的是reader-pull-checker、high-point-checker、pacing-checker、continuity-checker等已不存在的脚本名新表改为按 reviewer 的审查维度组织审查维度 (reviewer)使用的 TaxonomycontinuityHard-001 (可读性底线)、Hard-002 (结构完整)pacingHard-003 (节奏灾难)、爽点模式、微兑现ai_flavor钩子类型、钩子强度对照当前仓库reading-power-taxonomy.md L347-349 已经是新表格式说明该清理已落地。五、Task 4overall_score消费点迁移context_manager.py是旧 checker 数据的最后一个运行时消费者它用overall_score 75判断近期章节低分并产生告警。而旧聚合器删除后overall_score不再可靠需要改为结合notes中的 blocking 信号判断。计划给出的新旧逻辑对比# 旧逻辑只看 overall_score for row in review_trend.get(recent_ranges, []): score row.get(overall_score) if isinstance(score, (int, float)) and float(score) 75: low_score_ranges.append({...}) # 新逻辑低分 或 notes 中出现非零 blocking 即告警 for row in review_trend.get(recent_ranges, []): score row.get(overall_score) notes row.get(notes, ) has_issues blocking in notes and blocking0 not in notes is_low_score isinstance(score, (int, float)) and float(score) 75 if is_low_score or has_issues: low_score_ranges.append({ start_chapter: row.get(start_chapter), end_chapter: row.get(end_chapter), overall_score: score if isinstance(score, (int, float)) else 0.0, notes: notes, })当前 context_manager.py L285-299 的实际实现与这段新逻辑一致has_blocking blocking in notes and blocking0 not in notesis_low_score or has_blocking时入列。值得注意的细节是overall_score字段并未被彻底移除而是降级为参考值之一告警主判据切换为 notes 中结构化写入的 blocking 计数——这是旧数据格式向 v6 reviewer 输出格式过渡的典型兼容写法。六、Task 5章节状态模型落地核心新功能这是整个计划中唯一的新增功能也是 webnovel-writer 解决长连载遗忘问题的关键一环为每一章维护一个单调递进的状态机供 v6 Write 流程做充分性闸门例如未chapter_reviewed的章节不应进入提交链。6.1 状态模型设计状态序列CHAPTER_STATUS_ORDER [chapter_drafted, chapter_reviewed, chapter_committed]语义drafted初稿完成→ reviewed通过审查→ committed已提交入库不变量状态单调递进、不可回退相同状态设置幂等存储state.json的progress.chapter_status字段以章号字符串为键。6.2 TDD 流程先写测试确认失败再实现计划严格按照测试驱动推进完整测试文件见 test_chapter_status.py覆盖 5 个场景def test_get_chapter_status_default(state_project): sm _make_manager(state_project) sm._load_state() status sm.get_chapter_status(5) assert status is None # 未设置过 def test_set_chapter_status_monotonic(state_project): sm _make_manager(state_project) sm._load_state() sm.set_chapter_status(5, chapter_reviewed) # 不能回退到 drafted with pytest.raises(ValueError, match不可回退): sm.set_chapter_status(5, chapter_drafted) def test_chapter_status_persists(state_project): sm _make_manager(state_project) sm._load_state() sm.set_chapter_status(3, chapter_drafted) sm._save_state() # 重新加载验证持久化 sm2 _make_manager(state_project) sm2._load_state() assert sm2.get_chapter_status(3) chapter_drafted先运行测试预期失败于AttributeError: StateManager object has no attribute get_chapter_status——这确认了功能确实缺失而非测试本身写错然后再实现。6.3 核心实现计划给出的实现骨架CHAPTER_STATUS_ORDER [chapter_drafted, chapter_reviewed, chapter_committed] def get_chapter_status(self, chapter: int) - Optional[str]: 查询章节状态。 statuses self._state.get(progress, {}).get(chapter_status, {}) return statuses.get(str(chapter)) def set_chapter_status(self, chapter: int, status: str) - None: 设置章节状态单调递进不可回退。 if status not in self.CHAPTER_STATUS_ORDER: raise ValueError(f无效状态: {status}有效值: {self.CHAPTER_STATUS_ORDER}) current self.get_chapter_status(chapter) if current is not None: current_idx self.CHAPTER_STATUS_ORDER.index(current) new_idx self.CHAPTER_STATUS_ORDER.index(status) if new_idx current_idx: raise ValueError(f章节 {chapter} 状态不可回退: {current} - {status}) if new_idx current_idx: return # 幂等 progress self._state.setdefault(progress, {}) chapter_status progress.setdefault(chapter_status, {}) chapter_status[str(chapter)] status self._save_state()6.4 当前仓库的最终形态实现比计划更进一步对照 state_manager.py 源码落地实现包含计划之外的增强体现了计划是最低线、实现可以长出来新增chapter_rejected状态L113-114REJECTED_CHAPTER_STATUS chapter_rejected有效状态集扩展为CHAPTER_STATUS_ORDER [REJECTED_CHAPTER_STATUS]用于审查不通过的章节排序函数_chapter_status_rankL706-712rejected 的 rank 为 -1允许 rejected 与正常序列共存而不破坏单调判断写入走 pending 合并而非直接落盘L700-704set_chapter_status把变更记入self._pending_chapter_status后调用save_state()_save_state()L714-717才是绕过 pending 合并的轻量直写路径。从源码结构看这个 pending 机制配合 L251、L289-313 的锁内重读合并逻辑是为了与state.json.lock的原子写协议保持一致避免并发下的状态丢失CLI 子命令L1491-1501get-chapter-status --chapter N与set-chapter-status --chapter N --status {chapter_drafted|chapter_reviewed|chapter_committed|...}输出走统一的emit_success/emit_error通道与state_manager.py其余 CLI 命令保持一致的机器可读输出风格。七、Task 6修正 spec 与实现的不一致迁移期最常见的技术债之一是设计文档说的和代码做的对不上。本计划把 spec 修正也纳入 Task 级管理针对 v6 设计文档当前归档于 2026-04-02-harness-v6-design.md的 4.5 节修正 memory contract v0 状态描述原文写v0 接口当前尚未实现现有实现通过webnovel.pyCLI 子命令充当但 Phase 3 实际已通过memory_contract.pyProtocol 类型和memory_contract_adapter.py适配器实现CLI 入口为webnovel.py memory-contract子命令context-agent 已在消费。修正为v0已实现当前冻结更新 Phase 表Phase 3记忆模块接口契约设计、Phase 4context-agent research 模式重构状态列标注✅ 已完成更新版本号 状态草案 v7v6 实现对齐修正。这一步的价值在于如果 spec 停留在v0 尚未实现后续按 spec 编程的 Agent 或人类会重复造轮子spec 与代码对齐是迁移完成定义的一部分而不是有空再改的杂务。八、Task 7全量回归与退出标准验证收官 Task 分两步先跑python -m pytest webnovel-writer/scripts --tbshort全量回归再逐条执行退出标准脚本每条都对应差距表中的一类残留# 标准 1: 无旧 checker 运行时引用 grep -rn continuity-checker\|setting-checker\|ooc-checker\|high-point-checker\|pacing-checker\|reader-pull-checker \ webnovel-writer/skills/ webnovel-writer/agents/ webnovel-writer/scripts/*.py \ --include*.md --include*.py || echo PASS: 无旧 checker 引用 # 标准 2: 审查路径唯一write 与 review 两个 SKILL 均走 reviewer grep -l reviewer webnovel-writer/skills/webnovel-write/SKILL.md webnovel-writer/skills/webnovel-review/SKILL.md # 标准 3: workflow_manager 已删除 test ! -f webnovel-writer/scripts/workflow_manager.py echo PASS: 文件已删除 # 标准 4: 运行时无 legacy 聚合符号 grep -rn timeline_gate\|_aggregate_checker\|_normalize_checker\|_build_timeline_gate \ webnovel-writer/scripts/ --include*.py | grep -v test_ | grep -v __pycache__ # 标准 6: 章节状态 CLI 已注册 python -X utf8 data_modules/state_manager.py --help 21 | grep -q get-chapter-status echo PASS: CLI 已注册这套退出标准的写法有几点可复用每条标准都是单条可执行命令 明确的 PASS/FAIL 判据grep 范围精确到运行时路径标准 4 显式排除测试文件因为测试可能合法地引用旧符号名做回归功能类标准标准 6用--help输出来验证 CLI 注册而不是读源码。当前仓库可对照确认golden_three_checker.py已不存在、workflow_manager.py已不存在、get-chapter-status/set-chapter-status已在 state_manager.py 中注册——退出标准所列各条均有对应实现。九、方法论提炼这份迁移计划值得借鉴的四点差距表先行迁移计划的第一资产不是任务列表而是残留项 × 文件 × 行号的差距表。每个删除类 Task 都能直接映射到差距表一行验收时逐条勾销没有模糊空间删除与新增分线并行A删 legacy、C修文档无依赖可并行B新状态模型独立 TDD 开发。这种工作线划分让 Agent 执行时可以安全地并发推进而互斥的只有 B 对state_manager.py的修改TDD 验证缺失本身Task 5 先写测试并确认失败于AttributeError再实现。这一步在人工开发中常被认为多余但在 Agent 执行模式下它是防止假装完成的关键检查点退出标准即验收合同全量 pytest 定向 grep --help探测组合把迁移完成从主观判断变成可重复执行的脚本。计划中的命令使用了原作者的本地路径D:/wk/...在实际仓库中执行时替换为仓库根目录即可例如在当前仓库根目录下运行python -m pytest webnovel-writer/scripts --tbshort。这套差距盘点 → 并行工作线 → TDD 落地 → 可执行退出标准的结构同样适用于任何把旧模块体系整体替换为新架构的长周期迁移。【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统解决 AI 写作中的「遗忘」和「幻觉」问题支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考