# 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 可验证”的插件形态。

核心交付：

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

---

## 2. 实施原则

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

顺序必须是：

1. 先提供只读诊断能力。
2. 再加入 schema / gate 阻断。
3. 最后处理 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`

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

```text
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. 总体依赖顺序

```text
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 工作项

1. 记录当前 CLI 命令表。
2. 记录现有 Skills、Agents、Dashboard API。
3. 跑一组最小测试：
   - `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`
4. 确认当前 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 具体工作

1. 实现共享 `project_phase.py`：
   - 单一 phase 词表。
   - 不写状态文件。
   - doctor / project-status / write-gate 共用。
2. 实现 `project-status`：
   - `webnovel.py project-status --format json|summary`
   - 保留 `webnovel.py status` 现有转发，不改 `status_reporter.py` 语义。
   - 输出 latest accepted chapter、target chapter、phase、warnings、next action。
3. 实现 `doctor` 数据模型：
   - `DoctorReport`
   - `DoctorCheck`
   - `RepairSuggestion`
   - `ExpectedFiles`
4. 由 `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`
5. 实现阶段感知 expected files：
   - init 后只要求骨架、`state.json`、设定集、总纲、`.env.example`。
   - init 阶段不要求 commit、summary、memory、vectors。
   - plan / write / commit 阶段再逐步提高要求。
6. 实现文件检查：
   - 目录存在性。
   - JSON 可读性。
   - 关键字段检查。
7. 实现 SQLite 检查：
   - `index.db` 是否可打开。
   - 关键表是否存在。
   - 行数统计。
   - `vectors.db` 是否可打开、是否有 `vectors` 表。
8. 实现系统配置检查：
   - Python 版本。
   - 核心包 import。
   - RAG env / `.env` 配置。
   - Dashboard dist / requirements / package.json。
9. 在统一 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`
10. 新增 `/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 具体工作

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

### 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 具体工作

1. 注册 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`
2. `prewrite` 检查必须包装 `PrewriteValidator`：
   - project root。
   - phase 是否允许写。
   - Story System 合同是否齐。
   - 占位符 blocker。
3. `precommit` 检查：
   - 正文文件。
   - review / fulfillment / disambiguation / extraction artifacts。
   - artifact validator。
   - blocking issue。
4. `postcommit` 检查：
   - commit 文件。
   - `projection_status`。
   - summary / index / memory / backup 基本存在性。
5. 更新 `/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 具体工作

1. 新增 JSONL projection log：
   - `.webnovel/projection_log.jsonl`
2. 定义 run schema：
   - `run_id`
   - `chapter`
   - `commit_path`
   - `commit_hash`
   - `writer`
   - `status`
   - `started_at`
   - `finished_at`
   - `error`
3. `chapter_commit_service.apply_projections()` 每个 writer 写一条 log。
4. 保留 commit 内 `projection_status` 双写。
5. doctor 优先读取 projection log，缺失时 fallback 到 commit 内字段。
6. 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 具体工作

1. 新增 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`
2. 先审计 5 个 writer 幂等性：
   - `state`
   - `index`
   - `summary`
   - `memory`
   - `vector`
3. 补齐 writer 幂等测试，尤其关注：
   - 字数重复累计。
   - 关系 / 事件重复插入。
   - memory 重复沉淀。
   - vector chunk 重复。
4. runner 只读取 accepted commit。
5. retry 不修改 commit 事实内容。
6. 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 具体工作

1. Skill frontmatter：
   - 补强 `description`，写清触发场景和不适用场景。
   - 保持 `SKILL.md` 精简。
   - 大段规则移动到 `references/`。
2. Agent frontmatter：
   - 补 `name`。
   - 补具体 `description`。
   - 明确 `tools`。
   - 需要时补 `model`。
3. Agent 输出契约：
   - reviewer 输出维度固定。
   - data-agent 明确只产出 artifacts，不写 projection。
   - context-agent 明确上下文优先级。
4. 用 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 具体工作

1. 建立 eval 分类：
   - skill triggering
   - workflow behavior
   - agent output schema
   - continuity conflict
   - memory commit
2. 首批用例：
   - init 不污染插件目录。
   - write 遇 blocking issue 不进入 commit。
   - data-agent 不写 projection。
   - commit 驱动 projection。
   - dashboard 只读。
3. Runner 输出 JSON 报告。
4. 区分 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 具体工作

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

### 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 具体工作

1. `SessionStart` hook：
   - 只输出短摘要。
   - 不写文件。
   - 不运行完整 doctor。
   - 调用 `webnovel.py project-status --format summary`。
   - 可通过 env 关闭。
2. `PreToolUse` hook：
   - 阻断直接写 `.story-system/commits`。
   - 阻断直接写 `.webnovel/state.json`、`index.db`、`memory_scratchpad.json`。
   - 对 Bash 中绕过 gate 的危险 commit / projection 命令做 best-effort 检测。
   - 不把 Bash 字符串解析当作唯一硬保证。
3. 按 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. 总体验收

完成后应满足：

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

---

## 17. 最小先行版本

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

1. `doctor`
2. `project-status` / `project_phase`
3. `artifact_validator`
4. `write-gate`

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

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

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