Plugin Runtime Hardening Implementation Plan

日期：2026-06-04 状态：草案 v1 对应 spec：docs/architecture/plugin-runtime-hardening-spec-2026-06-04.md 范围：把 spec 拆成可实施、可验收、可回退的工程计划，重点说明修改范围与影响面

1. 目标

本计划把 webnovel-writer 从“主要靠 Skill 文档约束流程”推进到“关键边界由 runtime 可验证”的插件形态。

核心交付：

project_phase / project-status：统一项目阶段推导和短状态摘要，保留现有 status_reporter.py 的宏观创作健康报告语义。
/webnovel-doctor：阶段感知的项目体检，检查目录、文件、数据库、RAG、Python 依赖、Dashboard 配置，并给修复建议。
artifact_validator：统一校验 agent 产物，避免字段漂移和 schema 错误。
write-gate：在写前、提交前、提交后三个自然边界做批量校验。
projection_log：把 commit 事实和 projection 执行日志拆开。
projections retry/replay：投影失败后可补跑。
Skill / Agent 契约补强：按官方 plugin-dev 规范收束 frontmatter、description、tools、输出约束。
Behavior evals 与 package validator：验证插件行为和发布物一致性。
可选轻量 hook：SessionStart 状态提示与 PreToolUse 危险动作兜底提醒 / 阻断。

2. 实施原则

2.1 先观察，后阻断，再迁移

顺序必须是：

先提供只读诊断能力。
再加入 schema / gate 阻断。
最后处理 projection log 与 replay。

这样可以减少一次性大改对现有写作流程的冲击。

2.2 不破坏现有用户项目

所有新增能力默认兼容旧数据：

保留现有 .story-system/commits/*.commit.json 结构。
保留 commit 内 projection_status 至少一个版本周期。
.webnovel/state.json、index.db、summaries/、memory_scratchpad.json 继续作为 projection / read-model。
Dashboard 先兼容旧字段，再逐步读取新 projection log。

2.3 遵循官方 `plugin-dev`

所有插件组件改动必须遵循：

C:\Users\lcy\.claude\plugins\marketplaces\claude-plugins-official\plugins\plugin-dev

落地要求：

插件结构按 plugin-structure。
Skill 按 skill-development，保持 SKILL.md 精简，详细规则放 references/。
Command 按 command-development。
Agent 按 agent-development。
Hook 按 hook-development，插件级 hooks/hooks.json 使用 wrapper 格式。
每轮插件组件改动后按 plugin-validator 思路校验 manifest、skills、agents、hooks、README、LICENSE、路径可移植性。

2.4 每阶段独立可回退

每阶段应尽量做到：

新增文件多于修改旧文件。
旧入口可继续工作。
新 CLI 子命令失败不影响旧命令。
可通过删除新增入口或关闭 hook 回退。

2.5 新入口统一 UTF-8

所有新增 CLI / hook / 子进程入口必须兼容 Windows 中文路径：

CLI 入口调用 enable_windows_utf8_stdio() 或等价逻辑。
文件读写显式 encoding="utf-8"。
hook / 子进程使用 python -X utf8 或设置 PYTHONUTF8=1。
不依赖系统默认编码。

3. 总体依赖顺序

Phase 0 基线审计
  ↓
Phase 1 project_phase + project-status + doctor
  ↓
Phase 2 artifact_validator
  ↓
Phase 3 write-gate
  ↓
Phase 4 projection_log
  ↓
Phase 5 projection retry/replay
  ↓
Phase 6 skill / agent 契约补强
  ↓
Phase 7 behavior evals
  ↓
Phase 8 package validator
  ↓
Phase 9 hooks

说明：

project_phase / project-status / doctor 可以先做，因为它们只读、风险最低，并且后续 gates 和 hooks 都依赖统一 phase。
artifact_validator 应早于 write-gate，否则 gate 会重复写 schema 判断。
projection_log 应早于 retry/replay，否则失败记录不稳定。
hooks 放后面，因为它们会改变 Claude Code 会话体验。

4. Phase 0：基线审计与测试冻结

4.1 目标

在动代码前确认当前功能基线，避免重构时不知道哪里被破坏。

4.2 修改范围

优先不改 runtime 代码，只新增或更新文档 / 测试清单：

docs/architecture/plugin-runtime-hardening-plan-2026-06-04.md
可选更新 docs/README.md

4.3 工作项

记录当前 CLI 命令表。
记录现有 Skills、Agents、Dashboard API。
跑一组最小测试：
- test_webnovel_unified_cli.py
- test_story_runtime_health.py
- test_chapter_commit_service.py
- test_event_projection_router.py
- test_rag_adapter.py
- test_dashboard_app.py
确认当前 repo 是否已有未提交改动，避免误覆盖用户修改。

4.4 影响

无用户可见行为变化。

4.5 验收

记录基线测试结果。
明确当前失败项是否为既有问题。

5. Phase 1：`project_phase` / `project-status` / `webnovel-doctor`

5.1 目标

新增统一 phase resolver、短状态入口和只读项目体检入口，回答：

当前项目处于什么阶段。
这个阶段应该有哪些文件。
目录、JSON、SQLite、RAG、Python 依赖、Dashboard 配置是否完整。
缺失或异常时如何修复。

当前代码已有两个相关入口，必须先明确关系：

webnovel.py preflight：已有快速环境检查，保留并复用。
webnovel.py status：已转发到 scripts/status_reporter.py，语义是宏观创作健康报告，保留不占用。

5.2 修改范围

新增：

webnovel-writer/scripts/data_modules/project_phase.py
webnovel-writer/scripts/data_modules/project_status.py
webnovel-writer/scripts/data_modules/doctor.py
webnovel-writer/scripts/data_modules/tests/test_project_phase.py
webnovel-writer/scripts/data_modules/tests/test_project_status.py
webnovel-writer/skills/webnovel-doctor/SKILL.md
webnovel-writer/scripts/data_modules/tests/test_doctor.py

修改：

webnovel-writer/scripts/data_modules/webnovel.py
docs/guides/commands.md
docs/README.md

可复用：

webnovel.py 中现有 _build_preflight_report()
story_runtime_health.py
story_runtime_sources.py
config.py
Dashboard 里的 _inspect_vector_db() / _build_env_status() 思路

5.3 具体工作

实现共享 project_phase.py：
- 单一 phase 词表。
- 不写状态文件。
- doctor / project-status / write-gate 共用。
实现 project-status：
- webnovel.py project-status --format json|summary
- 保留 webnovel.py status 现有转发，不改 status_reporter.py 语义。
- 输出 latest accepted chapter、target chapter、phase、warnings、next action。
实现 doctor 数据模型：
- DoctorReport
- DoctorCheck
- RepairSuggestion
- ExpectedFiles
由 project_phase.py 实现 phase 推导：
- no_project
- unknown
- init_scaffolded
- init_ready
- plan_in_progress
- chapter_contract_ready
- draft_in_progress
- ready_to_commit
- chapter_committed
- projection_failed
实现阶段感知 expected files：
- init 后只要求骨架、state.json、设定集、总纲、.env.example。
- init 阶段不要求 commit、summary、memory、vectors。
- plan / write / commit 阶段再逐步提高要求。
实现文件检查：
- 目录存在性。
- JSON 可读性。
- 关键字段检查。
实现 SQLite 检查：
- index.db 是否可打开。
- 关键表是否存在。
- 行数统计。
- vectors.db 是否可打开、是否有 vectors 表。
实现系统配置检查：
- Python 版本。
- 核心包 import。
- RAG env / .env 配置。
- Dashboard dist / requirements / package.json。
在统一 CLI 注册：
- webnovel.py project-status --format json|summary
- webnovel.py doctor --format json|text
- webnovel.py doctor --chapter N --format json|text
- webnovel.py doctor --deep --format json|text
新增 /webnovel-doctor Skill：
- 只读。
- 不修复。
- 输出结论、影响、建议命令。

5.4 影响

用户影响：

新增一个体检命令，不改变旧流程。
新增 project-status 短状态命令，不改变既有 status 健康报告。
出问题时用户能看到缺什么、影响什么、怎么修。

代码影响：

webnovel.py 增加 project-status 和 doctor 子命令。
新增 doctor.py 只读模块。
新增共享 phase resolver。
不修改 commit、state、index、summary、memory。

风险：

phase 推导不准会导致误报。
数据库表清单如果过严，会把旧项目误判为坏。
project-status 与现有 status_reporter.py 混淆。

控制：

phase 不确定时只做低风险检查。
init 阶段缺后续产物只返回 skip/info。
数据库检查分 required 和 observed，避免旧表缺失直接阻断。
命令名使用 project-status，保留 status 原语义。
doctor 快检部分复用 _build_preflight_report()，避免 preflight / doctor 两套环境检查漂移。

5.5 验收

空目录返回 no_project，无 traceback。
webnovel.py status 仍运行现有 status_reporter.py。
webnovel.py project-status --format json 返回统一 phase。
preflight 仍可运行，并与 doctor 快检结果不冲突。
init 刚结束返回 init_scaffolded 或 init_ready。
init 刚结束缺 commit / summary / vectors 不报 blocker。
index.db 缺关键表时能显示表名、影响、修复建议。
缺 RAG key 返回 warning，并说明降级 BM25。
默认模式不联网、不写文件、不安装依赖、不启动服务。
Windows 中文路径下不因默认编码失败。

5.6 回退

移除 CLI doctor / project-status 注册。
保留 doctor.py 不被调用也不影响现有流程。
保留 project_phase.py 不被调用也不影响现有流程。
删除 /webnovel-doctor Skill 后插件仍可按原方式运行。

6. Phase 2：Artifact Validator

6.1 目标

统一校验 agent 产物，避免 review_result、fulfillment_result、disambiguation_result、extraction_result 字段漂移。

6.2 修改范围

新增：

webnovel-writer/scripts/data_modules/artifact_validator.py
webnovel-writer/scripts/data_modules/tests/test_artifact_validator.py

可能修改：

chapter_commit_service.py
chapter_commit.py
chapter_commit_schema.py

6.3 具体工作

定义统一错误类型：
- schema_error
- missing_artifact
- blocking_review
- missed_outline_node
- pending_disambiguation
- projection_failure
包装现有 Pydantic schema。权威源统一为 chapter_commit_schema.py 中 commit 所需模型：
- ReviewResult
- FulfillmentResult
- DisambiguationResult
- ExtractionResult
明确同名 / 近名模型边界：
- review_schema.py 是 reviewer / review pipeline 局部模型。
- entity_linker.py 中的消歧模型是实体链接局部模型。
- artifact_validator 只以 commit artifact schema 作为最终提交权威。
提供统一入口：
- validate_review_result(path)
- validate_fulfillment_result(path)
- validate_disambiguation_result(path)
- validate_extraction_result(path)
- validate_chapter_commit(path)
允许兼容已知旧字段，无法兼容时给明确诊断。

6.4 影响

用户影响：

提交前更早发现 agent 输出错误。
报错从 Python traceback 变成结构化说明。

代码影响：

chapter_commit_service 可以逐步改为依赖 validator。
后续 write-gate 复用 validator，减少重复校验。

风险：

过严 schema 可能阻断旧产物。
同名模型选错会制造新的 schema 漂移。

控制：

首版对旧字段做兼容或 warning。
只有明确影响 commit 正确性的错误才 blocker。
在代码注释和测试中固定权威源为 chapter_commit_schema.py。

6.5 验收

缺 artifact 返回 missing_artifact。
JSON 外层包错返回 schema_error。
disambiguation.pending 非空返回 blocker。
reviewer blocking issue 返回 blocker。
ReviewResult / DisambiguationResult 同名模型不混用。

6.6 回退

chapter_commit_service 保留旧校验路径。
如果 validator 有误，可先只用于 doctor / gate 报告，不阻断 commit。

7. Phase 3：Runtime Gates

7.1 目标

新增写章关键边界校验：

prewrite
precommit
postcommit

7.2 修改范围

新增：

webnovel-writer/scripts/data_modules/write_gates/__init__.py
webnovel-writer/scripts/data_modules/write_gates/prewrite.py
webnovel-writer/scripts/data_modules/write_gates/precommit.py
webnovel-writer/scripts/data_modules/write_gates/postcommit.py
webnovel-writer/scripts/data_modules/tests/test_write_gates.py

修改：

webnovel-writer/scripts/data_modules/webnovel.py
webnovel-writer/skills/webnovel-write/SKILL.md
docs/guides/commands.md

复用：

webnovel-writer/scripts/data_modules/prewrite_validator.py
webnovel-writer/scripts/data_modules/tests/test_prewrite_validator.py

7.3 具体工作

注册 CLI：
- webnovel.py write-gate --chapter N --stage prewrite --format json
- webnovel.py write-gate --chapter N --stage precommit --format json
- webnovel.py write-gate --chapter N --stage postcommit --format json
prewrite 检查必须包装 PrewriteValidator：
- project root。
- phase 是否允许写。
- Story System 合同是否齐。
- 占位符 blocker。
precommit 检查：
- 正文文件。
- review / fulfillment / disambiguation / extraction artifacts。
- artifact validator。
- blocking issue。
postcommit 检查：
- commit 文件。
- projection_status。
- summary / index / memory / backup 基本存在性。
更新 /webnovel-write：
- 用 Claude Code Todo 管过程。
- 只在自然边界调用 gate。

7.4 影响

用户影响：

写章流程增加 2-3 次确定性检查。
提交前错误更清晰。

代码影响：

/webnovel-write 的执行说明会改变。
webnovel.py 增加子命令。
现有 PrewriteValidator 成为 prewrite gate 的底层实现，避免两套逻辑漂移。

风险：

gate 太严格会打断写作体验。
gate 太宽松则无法提升可靠性。
如果重写 prewrite 逻辑，会和现有 PrewriteValidator 漂移。

控制：

首版只阻断明确不可信状态。
warning 不阻断。
所有 gate 输出 repair 建议。
prewrite 不重写，先适配现有 validator 输出。

7.5 验收

缺 review artifact 时 precommit.ok=false。
blocking review 时 precommit.ok=false。
disambiguation pending 时 precommit.ok=false。
projection failed 时 postcommit.ok=false。
init 阶段调用 prewrite 能给出明确下一步建议。
现有 test_prewrite_validator.py 继续通过。

7.6 回退

/webnovel-write 可临时回到旧流程。
CLI 子命令保留但不被 Skill 调用。

8. Phase 4：Projection Log

8.1 目标

将 commit 事实和 projection 执行状态拆开，降低 commit 文件同时承载事实与执行日志的混乱。

开工前必须先确认现状痛点：

是否出现过 projection failed 后无法定位 writer。
是否出现过 commit 内 projection_status 与实际 read-model 不一致。
Dashboard / doctor 是否确实需要跨 writer 的执行历史。

如果没有真实痛点，本阶段可以延后，只保留 doctor 对现有 projection_status 的诊断。

8.2 修改范围

新增：

webnovel-writer/scripts/data_modules/projection_log.py
webnovel-writer/scripts/data_modules/tests/test_projection_log.py

修改：

chapter_commit_service.py
event_projection_router.py
story_runtime_health.py
doctor.py
dashboard/app.py

8.3 具体工作

新增 JSONL projection log：
- .webnovel/projection_log.jsonl
定义 run schema：
- run_id
- chapter
- commit_path
- commit_hash
- writer
- status
- started_at
- finished_at
- error
chapter_commit_service.apply_projections() 每个 writer 写一条 log。
保留 commit 内 projection_status 双写。
doctor 优先读取 projection log，缺失时 fallback 到 commit 内字段。
Dashboard 先兼容读取，不做大改版。

8.4 影响

用户影响：

投影失败时能看到具体哪个 writer 失败。
不改变章节提交命令。

数据影响：

新增 .webnovel/projection_log.jsonl。
commit 文件结构暂时不删字段。

风险：

双写不一致。
Dashboard 读取逻辑复杂一点。
新增 projection log 会形成第二份执行状态来源。

控制：

projection log 写失败不应影响 commit 主流程，但必须 warning。
doctor 报告双写不一致。
保留一个明确决策点：确认收益大于双写复杂度后再施工。

8.5 验收

每个 writer 有 projection log。
单 writer failed 不影响其他 writer 记录。
doctor 能指出 failed writer。
commit 内 projection_status 仍存在。

8.6 回退

Dashboard 和 doctor fallback 到 commit 内 projection_status。
删除 projection log 不影响 commit 读取。

9. Phase 5：Projection Retry / Replay

9.1 目标

投影失败后能按 writer 补跑，尤其是 vector / summary / memory。

本阶段风险最高，必须先完成 writer 幂等性审计和测试。

9.2 修改范围

新增：

webnovel-writer/scripts/data_modules/projection_runner.py
webnovel-writer/scripts/data_modules/tests/test_projection_runner.py

修改：

event_projection_router.py
webnovel.py
projection writer 测试

9.3 具体工作

新增 CLI：
- webnovel.py projections status --chapter N
- webnovel.py projections retry --chapter N --writer vector
- webnovel.py projections retry-failed --chapter N
- webnovel.py projections replay --from 1 --to 20 --writers state,index,summary
先审计 5 个 writer 幂等性：
- state
- index
- summary
- memory
- vector
补齐 writer 幂等测试，尤其关注：
- 字数重复累计。
- 关系 / 事件重复插入。
- memory 重复沉淀。
- vector chunk 重复。
runner 只读取 accepted commit。
retry 不修改 commit 事实内容。
retry 结果写 projection log，并兼容更新旧 projection_status。

9.4 影响

用户影响：

外部依赖失败后不用重写整章。
可单独补 vector / summary。

数据影响：

projection read-model 可能被重建。
需要保证幂等，避免重复累计字数或重复关系。

风险：

幂等不足导致重复数据。
replay 命令一旦写错，影响范围比单章 commit 大。

控制：

先对 state/index/summary/memory/vector writer 分别补幂等测试。
replay 默认要求明确 chapter 范围。
默认不提供全书无边界 replay。

9.5 验收

删除 summary 后 retry summary 可恢复。
重复 replay 同一章节不会重复累计 state / index / memory / vector 数据。
vector key 缺失时 vector failed，其余 writer done。
配置 key 后 retry vector 只补 vector。
replay 后 state/index/summary 与 commit 链一致。

9.6 回退

隐藏或下线 projections CLI。
继续使用旧 chapter commit 流程。

10. Phase 6：Skill / Agent 契约补强

10.1 目标

按官方 plugin-dev 规范增强 Skill / Agent 的触发、工具范围、输出契约。

10.2 修改范围

修改：

webnovel-writer/skills/*/SKILL.md
webnovel-writer/agents/*.md
webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py

可选新增：

webnovel-writer/agents/continuity-reviewer.md
webnovel-writer/agents/style-reviewer.md
webnovel-writer/agents/reader-pull-reviewer.md

10.3 具体工作

Skill frontmatter：
- 补强 description，写清触发场景和不适用场景。
- 保持 SKILL.md 精简。
- 大段规则移动到 references/。
Agent frontmatter：
- 补 name。
- 补具体 description。
- 明确 tools。
- 需要时补 model。
Agent 输出契约：
- reviewer 输出维度固定。
- data-agent 明确只产出 artifacts，不写 projection。
- context-agent 明确上下文优先级。
用 plugin-dev 的 validate-agent 规则做人工或脚本校验。

10.4 影响

用户影响：

Claude Code 触发技能和代理更稳定。
误触发和漏触发减少。

代码影响：

主要是 prompt / markdown 文件。
可能影响 Claude Code 的选择行为。

风险：

description 改动导致触发习惯变化。

控制：

改一组测一组。
增加 prompt integrity 测试。
保留命令名称不变。

10.5 验收

7 个 Skill 都有明确触发型 description。
4 个现有 Agent frontmatter 符合 plugin-dev 要求。
prompt integrity 测试通过。
data-agent 文档仍明确不写 state/index/summary/memory。

10.6 回退

单个 Skill / Agent 可独立回滚 frontmatter。
不影响 Python runtime。

11. Phase 7：Behavior Evals

11.1 目标

验证插件在真实行为层面是否按协议执行，而不是只验证 Python 函数。

11.2 修改范围

新增：

webnovel-writer/evals/
webnovel-writer/scripts/run_behavior_evals.py
webnovel-writer/evals/fixtures/

修改：

CI / 本地测试文档。
docs/operations/operations.md

11.3 具体工作

建立 eval 分类：
- skill triggering
- workflow behavior
- agent output schema
- continuity conflict
- memory commit
首批用例：
- init 不污染插件目录。
- write 遇 blocking issue 不进入 commit。
- data-agent 不写 projection。
- commit 驱动 projection。
- dashboard 只读。
Runner 输出 JSON 报告。
区分 fast fixture eval 和 slow transcript eval。

11.4 影响

用户影响：

无直接使用变化。
发布前可靠性更高。

代码影响：

增加测试资产。
CI 时间可能增加。

风险：

transcript eval 成本高、慢。

控制：

默认只跑 fast。
slow 只在发布前或手动运行。

11.5 验收

每个 Skill 至少一个 eval。
/webnovel-write 覆盖成功链路和 blocking 链路。
eval report 有 pass/fail/reason/artifacts。

11.6 回退

eval 不参与默认流程时可暂时跳过。
不影响 runtime。

12. Phase 8：Package Validator

12.1 目标

防止 manifest、marketplace、README、version、frontmatter 漂移。

12.2 修改范围

新增：

webnovel-writer/scripts/validate_plugin_package.py
webnovel-writer/scripts/tests/test_validate_plugin_package.py

修改：

docs/operations/plugin-release.md
docs/guides/commands.md

12.3 具体工作

检查 .claude-plugin/plugin.json：
- name kebab-case。
- version semver。
- description 非空。
检查 marketplace 文件。
复用或对齐现有 Plugin Version Check：
- marketplace version。
- plugin.json version。
- README 中既有版本位置 / 版本表。
- 不新增一套与现有 CI 冲突的 README badge 规则。
检查 skills frontmatter。
检查 agents frontmatter。
检查 hooks schema。
检查 LICENSE。
检查 Dashboard dist。
检查无硬编码本机绝对路径。

12.4 影响

用户影响：

发布包更稳定。

代码影响：

新增发布前校验脚本。

风险：

校验规则过严影响开发阶段。
版本校验与现有 CI 不一致，导致本地通过但 CI 失败，或相反。

控制：

区分 --strict 和默认模式。
默认只阻断明显错误。
先读现有 CI / release 文档，再实现版本检查。

12.5 验收

clean clone 校验通过。
version 任一处漂移时失败。
版本漂移规则与现有 CI 一致。
删除 Skill frontmatter 时失败。
hooks 路径不用 ${CLAUDE_PLUGIN_ROOT} 时 warning 或失败。

12.6 回退

release 流程暂不调用 validator。
不影响插件运行。

13. Phase 9：Hooks

13.1 目标

基于 Phase 1 的 project-status 提供轻量状态摘要，并对最危险的绕过 runtime 写入做兜底提醒 / 阻断。

13.2 修改范围

新增：

webnovel-writer/hooks/hooks.json
webnovel-writer/hooks/session_start.py
webnovel-writer/hooks/scripts/guard-runtime-write.py

修改：

webnovel-writer/scripts/data_modules/webnovel.py
webnovel-writer/.claude-plugin/plugin.json，仅在需要显式声明 hook 路径时修改。
docs/operations/operations.md

13.3 具体工作

SessionStart hook：
- 只输出短摘要。
- 不写文件。
- 不运行完整 doctor。
- 调用 webnovel.py project-status --format summary。
- 可通过 env 关闭。
PreToolUse hook：
- 阻断直接写 .story-system/commits。
- 阻断直接写 .webnovel/state.json、index.db、memory_scratchpad.json。
- 对 Bash 中绕过 gate 的危险 commit / projection 命令做 best-effort 检测。
- 不把 Bash 字符串解析当作唯一硬保证。
按 plugin-dev hook-development 校验：
- hooks/hooks.json 使用 wrapper 格式。
- hook 命令使用 ${CLAUDE_PLUGIN_ROOT}。
- hook 脚本校验 stdin JSON。

13.4 影响

用户影响：

新对话能看到短状态。
直接改主链 / projection 文件会被阻断或要求显式走 runtime。

代码影响：

新增 hooks 目录。
Claude Code 会话启动多一次轻量命令。

风险：

hook 输出太长影响上下文。
hook 误阻断开发者调试。
Bash 命令变体太多，hook 无法可靠识别全部绕过方式。

控制：

输出限制 8 行 / 1000 字符。
提供关闭 env。
先只阻断最危险路径。
真正可靠性仍由 runtime gate 和 commit 入口保证。

13.5 验收

无项目根时不报错。
有项目根时输出 latest chapter / phase / next action。
设置 disable env 后无输出。
直接写 commit 文件被阻断。
合法 runtime 命令不被阻断。
webnovel.py status 仍保留宏观创作健康报告语义。

13.6 回退

删除或禁用 hooks/hooks.json。
保留 project-status CLI 不影响旧流程。

14. 横向影响分析

14.1 项目健康入口归属

入口	当前/目标职责	输出	是否深检	是否写文件
`preflight`	快速环境检查，保留兼容	text/json	否	否
`project-status`	机器可读短状态、phase、下一步	summary/json	否	否
`doctor`	文件/数据库/配置体检和修复建议	text/json	默认否，`--deep` 可选	否
`status` / `status_reporter.py`	宏观创作健康报告，如角色、伏笔、爽点、关系图谱	markdown/text	是，偏创作分析	现状可能输出报告文件，语义保持
`build_story_runtime_health()`	内部主链就绪度 helper	dict	否	否

原则：

不把所有问题塞进一个命令。
不改变现有 status 语义。
doctor 复用 preflight 和 story runtime health，不复制逻辑。

14.2 对用户命令的影响

新增命令：

/webnovel-doctor
webnovel.py doctor
webnovel.py write-gate
webnovel.py projections
webnovel.py project-status

现有命令保持：

/webnovel-init
/webnovel-plan
/webnovel-write
/webnovel-review
/webnovel-query
/webnovel-dashboard
/webnovel-learn

现有 webnovel.py status 保持转发到 status_reporter.py。

14.3 对项目数据的影响

新增文件：

.webnovel/projection_log.jsonl
可能新增 .webnovel/tmp/* 的校验约定。

不改变：

.story-system/ 主链真源地位。
accepted commit 是写后事实入口。
.webnovel/* 是 projection / read-model。

14.4 对 Dashboard 的影响

短期：

Dashboard 保持只读。
继续兼容 commit 内 projection_status。

中期：

Dashboard 可展示 projection log。
System 页可展示 doctor / project-status 摘要。

风险：

Dashboard 前端 bundle 可能需要 rebuild。

14.5 对 RAG 的影响

默认：

缺 key 降级 BM25。
vectors.db 缺失只 warning。

深度检查：

才测试 API 连通。

14.6 对测试的影响

新增测试量较大，需要分层：

单元测试：doctor / validator / gates / projection log。
集成测试：chapter commit + projection。
行为测试：skill / agent 协议。
发布测试：package validator。

15. 建议 PR 切分

PR 1：Phase Resolver + Project Status + Doctor

包含：

shared project_phase。
project-status CLI。
doctor runtime。
doctor CLI。
/webnovel-doctor Skill。
doctor tests。
preflight 快检复用关系。

不包含：

write-gate。
projection log。
hooks。

PR 2：Validator + Gates

包含：

artifact validator。
write-gates。
prewrite gate 包装现有 PrewriteValidator。
/webnovel-write 更新。
gate tests。

PR 3：Projection Writer 幂等审计

包含：

state / index / summary / memory / vector writer 幂等测试。
replay 风险评估。

PR 4：Projection Log

包含：

projection log。
chapter commit 双写。
doctor / dashboard 兼容读取。

PR 5：Projection Retry / Replay

包含：

projection runner。
projections CLI。
writer 幂等测试。

PR 6：Skill / Agent 契约

包含：

skill frontmatter。
agent frontmatter。
prompt integrity tests。

PR 7：Evals + Package Validator

包含：

behavior eval runner。
validate plugin package。
release docs。

PR 8：Hooks

包含：

SessionStart hook。
PreToolUse guard。
plugin-dev hook validation。

16. 总体验收

完成后应满足：

用户能运行 /webnovel-doctor 看懂项目文件、数据库、配置是否正常。
project-status 能给短状态，且不占用现有 status_reporter.py。
init 刚结束不会因为缺 commit / summary / vectors 被误报。
写章只在三个自然边界增加 gate 检查。
agent 产物 schema 错误能被统一报告。
projection 失败能定位 writer，并能补跑。
commit 事实和 projection 执行日志可区分。
Skill / Agent / Hook 结构符合官方 plugin-dev 规范。
发布前能校验插件包一致性。

17. 最小先行版本

如果要尽快落地一版高收益版本，建议只做前三项：

doctor
project-status / project_phase
artifact_validator
write-gate

这三项能先解决最核心的问题：

用户知道项目哪里坏。
runtime 和短状态共用同一套 phase。
runtime 知道 agent 产物是否可信。
写章关键边界不再只靠文档约束。

Projection log、retry/replay、hooks 和 evals 可以在基础稳定后继续推进。

plugin-runtime-hardening-plan-2026-06-04.md 31 KB Trvalý odkaz Historie Surový

Plugin Runtime Hardening Implementation Plan

1. 目标

2. 实施原则

2.1 先观察，后阻断，再迁移

2.2 不破坏现有用户项目

2.3 遵循官方 plugin-dev

2.4 每阶段独立可回退

2.5 新入口统一 UTF-8

3. 总体依赖顺序

4. Phase 0：基线审计与测试冻结

4.1 目标

4.2 修改范围

4.3 工作项

4.4 影响

4.5 验收

5. Phase 1：project_phase / project-status / webnovel-doctor

5.1 目标

5.2 修改范围

5.3 具体工作

5.4 影响

5.5 验收

5.6 回退

6. Phase 2：Artifact Validator

6.1 目标

6.2 修改范围

6.3 具体工作

6.4 影响

6.5 验收

6.6 回退

7. Phase 3：Runtime Gates

7.1 目标

7.2 修改范围

7.3 具体工作

7.4 影响

7.5 验收

7.6 回退

8. Phase 4：Projection Log

8.1 目标

8.2 修改范围

8.3 具体工作

8.4 影响

8.5 验收

8.6 回退

9. Phase 5：Projection Retry / Replay

9.1 目标

9.2 修改范围

9.3 具体工作

9.4 影响

9.5 验收

9.6 回退

10. Phase 6：Skill / Agent 契约补强

10.1 目标

10.2 修改范围

10.3 具体工作

10.4 影响

10.5 验收

10.6 回退

11. Phase 7：Behavior Evals

11.1 目标

11.2 修改范围

11.3 具体工作

11.4 影响

11.5 验收

11.6 回退

12. Phase 8：Package Validator

12.1 目标

12.2 修改范围

12.3 具体工作

12.4 影响

12.5 验收

12.6 回退

13. Phase 9：Hooks

13.1 目标

13.2 修改范围

13.3 具体工作

13.4 影响

13.5 验收

13.6 回退

14. 横向影响分析

plugin-runtime-hardening-plan-2026-06-04.md 31 KB

Trvalý odkaz Historie Surový

2.3 遵循官方 `plugin-dev`

5. Phase 1：`project_phase` / `project-status` / `webnovel-doctor`