docs: add architecture adaptation plans

.gitattributes

@@ -0,0 +1,7 @@
+# Keep repository text files stable across Windows/macOS/Linux.
+*.md text eol=lf
+*.py text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.sh text eol=lf

docs/README.md

@@ -9,6 +9,8 @@
 - [`architecture/overview.md`](./architecture/overview.md)：系统架构、Agent 分工、Story System 设计
 - [`architecture/plugin-runtime-hardening-spec-2026-06-04.md`](./architecture/plugin-runtime-hardening-spec-2026-06-04.md)：基于优秀 Claude Code 插件调研的运行时可靠性重构 spec
 - [`architecture/plugin-runtime-hardening-plan-2026-06-04.md`](./architecture/plugin-runtime-hardening-plan-2026-06-04.md)：运行时可靠性重构实施计划、修改范围与影响分析
+- [`architecture/multi-agent-adaptation-spec-2026-06-05.md`](./architecture/multi-agent-adaptation-spec-2026-06-05.md)：基于 v6.1.0 现状的多宿主与多智能体适配 spec
+- [`architecture/context-minimal-writing-flow-plan-2026-06-05.md`](./architecture/context-minimal-writing-flow-plan-2026-06-05.md)：Skills / Agents / References 上下文减负、读取方式与 token 优化重构计划（v3）
 - [`archive/architecture/current-system-diagnosis.md`](./archive/architecture/current-system-diagnosis.md)：历史系统状态诊断
 
 ### 使用指南

docs/architecture/context-minimal-writing-flow-plan-2026-06-05.md

@@ -0,0 +1,963 @@
+# 写作流程上下文减负重构 Plan
+
+> 日期：2026-06-05
+> 状态：草案 v3
+> 范围：重构 `skills/`、`agents/` 与 `references/` 的提示词与读取方式，减少主 agent 不必要上下文，降低 token 消耗
+> 核心原则：先保住端到端流程，再压缩提示词；Skill 只写调度合同，Agent 自带专业流程，Runtime 负责硬校验
+> 裁剪总纲：所有保留 / 下沉 / 删除决策由第 4 节四条裁剪判据（职责、token、噪音、读取方式）推导，不靠逐条拍清单
+> v3 变更：① 新增第 4 节裁剪判据；② 第 5 节不可删清单收敛为跨层红线；③ 第 6 节纳入 references 与读取方式优化（以 reference-loading-map 为基线）；④ 第 12 节验收从文案级断言改为行为 / 契约级
+> 工具能力基线：Claude Code 工具名、subagent / Skill 能力、shell 行为以官方最新文档和本机实际安装为准；不得靠记忆或经验猜测
+
+---
+
+## 0. 本版读法
+
+这份 plan 不是为了把所有文件压成某个固定格式，也不是为了让现有测试继续变绿。
+
+本轮真正要做的是：
+
+1. 先确认 init / plan / write / review / query / learn / dashboard / doctor 的完整业务链路（第 3 节）。
+2. 把跨层业务红线提成行为断言（第 5 节、第 12 节）。
+3. 按第 4 节四条裁剪判据精简 Skill、Agent、references，并为每个读取动作定下读取方式（第 4 节、第 6 节）。
+4. 用 runtime、prompt integrity、behavior eval 和 package validator 验收；验收对象是行为与契约，不是提示词文案（第 12 节）。
+
+两条立场必须贯穿全程：
+
+- **测试是探针，不是约束。** 瘦身会让一批文案级断言（`assert "字符串" in text`）变红，这些断言本身就是要清掉的噪音；它们保护的若是真红线，就改写成行为级断言并迁到生产方，而不是为了过测试保留废话。
+- **不能删除第 3 节的端到端流程。** 任何格式化、瘦身、下沉 reference、压缩 schema、改读取方式的动作，都不得删掉第 3 节的业务步骤。第 3 节是红线来源，第 4 节是裁剪依据，二者不冲突。
+- **工具能力不靠猜。** 任何涉及 `allowed-tools`、subagent 调用方式、Skill frontmatter、Skill / subagent 是否能加载彼此、Bash / PowerShell 行为、Read / Grep / Glob 参数能力的设计，都必须先核对 Claude Code 官方最新文档与本机当前版本；若二者有差异，以本机实际可用能力为落地准绳，并把差异记录到 Phase 0 清单。
+
+---
+
+## 1. 背景
+
+当前 Webnovel Writer 已经不是单一提示词 Skill，而是一个有运行时主链的写作插件：
+
+- `project-status` 判断项目短状态。
+- `doctor` 做阶段感知体检。
+- `placeholder-scan` 捕捉占位符与未补齐内容。
+- `story-system` 生成 `.story-system/` 写前合同树。
+- `write-gate` 在写前、提交前、提交后做批量校验。
+- `context-agent` 负责写前上下文组装。
+- `reviewer` 负责结构化审查。
+- `review-pipeline` 生成报告、指标并落库。
+- `data-agent` 负责提取 commit artifacts。
+- `chapter-commit` 负责写后事实提交和 projection。
+- `projections retry` 负责失败投影补跑。
+- `backup` 负责按书项目根备份。
+
+问题不在于缺少上下文，而是：
+
+1. 主 agent 知道了太多 subagent 内部流程。
+2. Skill 文本混有调度、教程、schema、示例和失败规则。
+3. 有些信息应该由工具按需获取，却提前塞进主上下文。
+4. 同一批上下文在 Skill、Agent、runtime 之间重复出现。
+5. 长 schema 和长示例占用 token，但真正执行时只需要输入、输出、验收。
+
+本轮重构要把写作流程从“主 agent 背完整教程”改成“主 agent 调度，subagent 专业执行，runtime 验收”。
+
+---
+
+## 2. 一句话目标
+
+> 主 agent 不传教程，只传任务；subagent 自带教程；runtime 负责验收；流程完整性由断言表兜底。
+
+---
+
+## 3. 端到端流程基准
+
+本节是重构的业务基准。后续任何压缩都必须先对照本节。
+
+### 3.1 全局不可变式
+
+所有 Skill / Agent 改写必须保留这些规则：
+
+- 现有项目类 Skill 必须先解析真实书项目根，不能在插件目录写项目文件。
+- `/webnovel-init` 在新项目尚未生成前不能用 `where` 把工作区解析成旧项目；必须用书名安全化得到目标目录。
+- `.story-system/` 是写前合同与写后 commit 的主链事实源。
+- `.webnovel/state.json` 是兼容投影 / read model，不重新变成写后事实真源。
+- 调用 `story-system` 时，章级 query 必须来自详细大纲中的真实本章目标，禁止传 `{章纲目标}`、`第N章章纲目标` 等占位文本。
+- 有具体章节写作 / 审查 / 合同刷新时，必须生成或确认 `.story-system/MASTER_SETTING.json`、`.story-system/volumes/`、`.story-system/chapters/`、`.story-system/reviews/`。
+- 写章主链必须保留 `write-gate --stage prewrite`、`precommit`、`postcommit` 三道 gate。
+- 必须用 `Agent` 工具显式调用 subagent，不得由主流程口头替代 `context-agent`、`reviewer`、`data-agent`、`deconstruction-agent` 的产物。
+- 失败只补跑失败步骤，不全量回退。
+- 能由 runtime 确定性校验的内容，提示词只保留最小说明和阻断边界。
+- reference 只按需读取；不要为了“结构好看”新增没有真实复用价值的 reference。
+
+### 3.2 `/webnovel-init` 完整流程
+
+init 不是单纯采集器。精简时必须保留完整生成链：
+
+1. 确认 `CLAUDE_PLUGIN_ROOT` 与 `${CLAUDE_PLUGIN_ROOT}/scripts/webnovel.py` 可用。
+2. 初始化前不使用 `where` 解析旧项目。
+3. 加载最小参考：数据流规范、题材套路库、题材画像；其他 reference 按需加载。
+4. 进入故事核采集前，询问灵感来源；参考书拆解是可选项，不默认执行。
+5. 用户提供参考文本路径或摘录时，必须调用 `webnovel-writer:deconstruction-agent`，不得由 init 主流程口头替代。
+6. `deconstruction-agent` 只返回 `init_reference_research`，不写任何文件，不创建 `.story-system`、`.webnovel`、`设定集`、`大纲`、`正文` 或 canon/read model。
+7. 拆书结果只消费可迁移模式和差异化要求；`quality.passed=false`、`confidence < 0.85` 或有 warnings 时，不能折叠进创意约束包，只能展示风险并让用户确认。
+8. Step 2-6 只能使用用户确认过、并已变形为本书差异化表达的模式。
+9. 采集故事核、角色、金手指、世界观、力量规则、创意约束包。
+10. 输出初始化摘要草案并等待用户明确确认。
+11. 用书名安全化生成 `PROJECT_SLUG` 和 `PROJECT_ROOT`，展示 `WORKSPACE_ROOT`、`PROJECT_SLUG`、`PROJECT_ROOT`，确认后再写文件。
+12. 运行 `webnovel.py init`。
+13. 写入 `.webnovel/idea_bank.json`，只写最终确认的创意约束。
+14. patch `大纲/总纲.md`，补齐故事一句话、核心主线 / 暗线、创意约束、反派分层、爽点里程碑。
+15. init 完成后立即生成 MASTER 合同：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  story-system "${GENRE}" --genre "${GENRE}" --persist --format json
+```
+
+此处不传 `--chapter`，只生成 `MASTER_SETTING.json` 和 `anti_patterns.json`。
+
+16. 验证 `state.json`、核心设定集、`大纲/总纲.md`、`idea_bank.json`、`.story-system/MASTER_SETTING.json`。
+17. 失败恢复只补缺失字段、重跑最小步骤，不全量重问。
+
+### 3.3 `/webnovel-plan` 完整流程
+
+plan 不是只生成章纲。精简时必须保留规划到写作合同的桥：
+
+1. 解析真实项目根，运行 `placeholder-scan`。
+2. 读取 `.webnovel/state.json` 的初始化配置快照获取 genre；后续写作真源仍是 `.story-system/`。
+3. 读取 `大纲/总纲.md`，确认卷名、章节范围、核心冲突、卷末高潮，不足则阻断。
+4. 跨卷规划时读取最近摘要、核心角色状态、核心关系、活跃伏笔。
+5. 补齐设定基线：世界观、力量体系、主角卡、反派设计；发现冲突先阻断。
+6. 选择目标卷并确认范围。
+7. 生成卷节拍表，必须有中段反转或明确无反转理由，危机链至少递增 3 次。
+8. 生成卷时间线表，必须明确时间体系、时间跨度、倒计时事件。
+9. 生成卷纲骨架，包含卷摘要、人物与反派层级、Strand、爽点、伏笔、约束触发。
+10. 批量生成章纲，默认 `10章/批`，复杂题材可降到 `8章/批`，不建议超过 `12章/批`。
+11. 每章必须包含目标、阻力、代价、时间锚点、章内跨度、与上章时间差、倒计时、爽点、Strand、反派层级、视角 / 主角、关键实体、本章变化、章末未闭合问题、钩子。
+12. 结构化节点必须保留：`CBN`、`CPNs`、`CEN`、`必须覆盖节点`、`本章禁区`。
+13. 新设定只增量写回现有设定集。
+14. 验证节拍表、时间线、详细大纲、时间字段、倒计时、BLOCKER、节点承接。
+15. 生成显式结构化写回文件 `大纲/第{volume_id}卷-总纲写回.json`。
+16. 调用 `master-outline-sync`，只允许更新 V+1 卷锚点与显式伏笔 / open loop，不从自由文本推断。
+17. 调用 `update-state -- --volume-planned ... --chapters-range ...`。
+18. 当本次规划已落到具体章节后，必须用真实章纲目标刷新 Story System runtime 合同：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  story-system "${CHAPTER_GOAL}" --genre "${GENRE}" --chapter {chapter_num} \
+  --persist --emit-runtime-contracts --format both
+```
+
+进入写章前不得保留当前章相关实体的 `[待...]`、`暂名`、`{占位}`。
+
+### 3.4 `/webnovel-write` 完整流程
+
+write 是本轮最重要的验收对象。精简时必须保留：
+
+#### 准备
+
+1. 设置 `WORKSPACE_ROOT`、`SCRIPTS_DIR`、`SKILL_ROOT`。
+2. 运行 `preflight`。
+3. 用 `where` 解析真实 `PROJECT_ROOT`。
+4. 运行 `placeholder-scan`。
+5. 从详细大纲解析真实 `CHAPTER_GOAL`。
+6. 从 `.webnovel/state.json` 的初始化配置快照读取 genre。
+7. 刷新章级 Story System runtime 合同：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  story-system "${CHAPTER_GOAL}" --genre "${GENRE}" --chapter {chapter_num} \
+  --persist --emit-runtime-contracts --format both
+```
+
+8. 运行 prewrite gate：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  write-gate --chapter {chapter_num} --stage prewrite --format json
+```
+
+prewrite 必备：`MASTER_SETTING.json`、`volume_{NNN}.json`、`chapter_{NNN}.json`、`chapter_{NNN}.review.json`。
+
+#### Step 1：写作任务书
+
+必须调用 `webnovel-writer:context-agent`。
+
+输入只给必要参数：章节号、项目根、脚本目录、存储路径 / state 兼容读取路径、输出要求。
+
+输出必须是一份可独立支撑起草的五段写作任务书。上下文不足时返回 blocker，不让主流程自行补脑。
+
+#### Step 2：起草正文
+
+只根据任务书起草。不要重新加载长篇 core constraints 或 anti-AI guide。
+
+有结构化节点时围绕 `CBN -> CPNs -> CEN` 展开。正文必须无占位符。
+
+#### Step 3：审查
+
+默认与 `--fast` 必须调用 `webnovel-writer:reviewer`，`--minimal` 可跳过。
+
+reviewer 输出 `.webnovel/tmp/review_results.json` 后，必须调用：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" review-pipeline \
+  --chapter {chapter_num} \
+  --review-results "${PROJECT_ROOT}/.webnovel/tmp/review_results.json" \
+  --metrics-out "${PROJECT_ROOT}/.webnovel/tmp/review_metrics.json" \
+  --report-file "审查报告/第{chapter_num}章审查报告.md" \
+  --save-metrics
+```
+
+写章主链中 reviewer 只调用一轮。`blocking=true` 的问题必须定点修复，或经用户裁决后才进入润色 / 提交。非 blocking issue 交给润色。
+
+#### Step 4：润色
+
+只改表达，不改事实。
+
+可保留现有 reference 加载，但不要让主 Skill 携带长教程：
+
+- `references/polish-guide.md`
+- `references/writing/typesetting.md`
+- `references/style-adapter.md`
+
+顺序：修复非 blocking issue -> 风格适配 -> 排版 -> Anti-AI 终检。
+
+`anti_ai_force_check=fail` 时不进入提交。`--minimal` 仅排版。
+
+#### Step 5：提交
+
+必须调用 `webnovel-writer:data-agent` 生成三份 artifacts：
+
+- `.webnovel/tmp/fulfillment_result.json`
+- `.webnovel/tmp/disambiguation_result.json`
+- `.webnovel/tmp/extraction_result.json`
+
+data-agent 不直接写 state / index / summaries / memory / vectors，也不直接写 projection。
+
+随后运行 precommit gate：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  write-gate --chapter {chapter_num} --stage precommit --format json
+```
+
+再运行 `chapter-commit`：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" chapter-commit \
+  --chapter {chapter_num} \
+  --review-result "${PROJECT_ROOT}/.webnovel/tmp/review_results.json" \
+  --fulfillment-result "${PROJECT_ROOT}/.webnovel/tmp/fulfillment_result.json" \
+  --disambiguation-result "${PROJECT_ROOT}/.webnovel/tmp/disambiguation_result.json" \
+  --extraction-result "${PROJECT_ROOT}/.webnovel/tmp/extraction_result.json"
+```
+
+自动判定：`blocking_count > 0`、`missed_nodes` 非空或 `pending` 非空 -> rejected，否则 accepted。
+
+#### Step 6：提交后验证与备份
+
+必须运行 postcommit gate：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  write-gate --chapter {chapter_num} --stage postcommit --format json
+```
+
+projection_status 五项 `state/index/summary/memory/vector` 必须全部 `done` 或 `skipped`。
+
+projection 失败只补跑：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
+  projections retry --chapter {chapter_num} --format json
+```
+
+最后备份必须以解析后的 `PROJECT_ROOT` 为准：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" backup \
+  --chapter {chapter_num} \
+  --chapter-title "{title}"
+```
+
+禁止从工作区父目录执行裸 `git add .`。
+
+### 3.5 `/webnovel-review` 完整流程
+
+独立 review Skill 可以比写章 Step 3 更完整，但不能伪造 reviewer 结果：
+
+1. 解析真实项目根。
+2. 如目标章缺少 runtime 合同，先用真实 `CHAPTER_GOAL` 刷新 `story-system --emit-runtime-contracts`。
+3. 读取必要 reference：core constraints、review schema；其他按 issue 需要读取。
+4. 加载 `.webnovel/state.json` 兼容投影和待审正文。
+5. 调用 `webnovel-writer:reviewer` 输出 `.webnovel/tmp/review_results.json`。
+6. 调用 `review-pipeline --save-metrics` 生成报告与 metrics 并写入 `review_metrics`。
+7. 调用 `update-state -- --add-review ...` 写兼容审查记录。
+8. 存在 `blocking=true` 时，询问用户立即修复或稍后处理。
+
+### 3.6 查询、学习、面板、体检完整流程
+
+`webnovel-query`：
+
+- 只读。
+- 先解析项目根。
+- 先识别查询类型，再用最窄工具。
+- 数据源优先级固定：`.story-system` 写前合同 -> latest accepted `CHAPTER_COMMIT` -> `memory-contract` -> `.webnovel/state.json` / `index.db` fallback。
+- 时序查询优先用 `knowledge query-entity-state` / `knowledge query-relationships`。
+- 降级到 legacy fallback 时必须明说。
+
+`webnovel-learn`：
+
+- 解析项目根。
+- 读取 state 获取当前章节号，失败可用 `source_chapter: null`。
+- 必须调用 `project-memory add-pattern`，不得手写 JSON。
+
+`webnovel-dashboard`：
+
+- 只读。
+- 解析 dashboard 模块与项目根。
+- 前端 dist 缺失时提示，不写项目文件。
+- 面板必须暴露 Story Runtime 主链状态，例如 `/api/story-runtime/health`。
+
+`webnovel-doctor`：
+
+- 只读诊断，不修复、不安装依赖、不启动 dashboard。
+- 先 `project-status --format summary`，再 `doctor --format text`。
+- 缺失项按 runtime 推导的阶段解释，不把 init 项目误判成已写多章项目。
+
+---
+
+## 4. 裁剪判据与职责边界
+
+本节是后续所有 Phase 的总纲。每一处“保留 / 下沉 / 删除 / 怎么读”的决策都由下面四条判据推导，不靠在各 Phase 里逐条枚举“必须保留”。
+
+### 4.1 四条裁剪判据
+
+**判据一·职责（谁生产、谁消费，信息就归谁）**
+
+- 主 agent 是调度者，只保留**契约的形状**：调哪个 subagent、得到哪几份产物、产物流向哪个 runtime 命令、什么情况算 blocker。
+- 字段级细则归生产方：artifact 字段名由 data-agent 生产、由 runtime validator 校验，归 `data-agent.md` 与 runtime，不进主 Skill。
+- 一段信息只该有一个真源；出现在第二处即为重复，删到只剩生产方。
+
+**判据二·token（测主 agent 的常驻输入，不测文件行数）**
+
+- 优化对象是“主 agent 写一章实际加载的上下文 token”，不是文件有多长。
+- 只在某 subagent / 某 step 执行时才需要的内容，绝不进主 agent 常驻上下文。
+- 短文件全文读没问题，别为瘦而瘦；靶心是“`always` 全文读的大文件”（见第 6 节）。
+
+**判据三·噪音（只留指令与红线，删元叙述与叮嘱）**
+
+| 噪音类型 | 例子 | 处理 |
+|---|---|---|
+| 重复 | schema 字段在 Skill / Agent 各写一遍 | 删一处，留生产方 |
+| 元叙述（教它怎么想） | reviewer 的“思维链（ReAct）：先读→对比→判断” | 删，不改变输出 |
+| 过度否定堆叠 | 一连串“不要…禁止…” | 区分红线与叮嘱：红线留，叮嘱删 |
+| 给错对象 | 主 agent 拿到只有 subagent 用的细则 | 按判据一迁走 |
+| 凑结构 | 为段落模板硬撑的空段 | 删，并松绑对应的结构型测试 |
+
+**判据四·读取方式（该全文读的全文读，该部分读的按需读）**
+
+每个“读文件”动作必须标注读取方式，不默认全文 `cat`：
+
+- **全文读**：短文件，且必须整体理解（schema、铁律、方法论总纲）。
+- **区段读**：只需某节时，使用 Claude Code 当前可用的内置读取 / 搜索工具或宿主 shell 等价能力定位稳定标题锚点后读取片段；不要在 plan 中假定某个具体命令或参数一定是内置能力。
+- **检索读**：结构化数据（CSV / JSON）优先用本项目 runtime 工具，如 `reference_search.py`、`knowledge query-*`、专用 schema/validator；只有确认宿主可用时才使用 shell 工具按字段取，绝不默认 `cat` 整表。
+- **不读**：内容已迁走或不再被消费的文件，清理（见第 6 节）。
+
+### 4.2 职责边界
+
+| 层 | 保留什么 | 不做什么 |
+|---|---|---|
+| Skill | 项目根保护、调度顺序、runtime 命令、Agent 输入契约形状、成功标准、失败恢复 | 不讲 subagent 内部教程，不复制长 schema，不吞掉 runtime gate |
+| Agent | 专业流程、最小必要规则、输出合同、边界 | 不依赖 `agents/references/*`，不写主链投影，不替 runtime commit |
+| Runtime | schema、gate、commit、projection、backup、状态推进 | 不承载 LLM 写作判断 |
+| Skill references | 长示例、详细采集字段、章节节点细则、润色清单 | 不作为 subagent 的隐藏说明书；不被无差别全文加载 |
+
+### 4.3 Agent 单文件约束
+
+Agent 当前只能加载自己的单个 Agent 文件，因此不新增 `agents/references/*`。Agent 需要的专业规则（含其产物的完整 schema）必须压缩后保留在单文件内——这正是判据一“字段细则归生产方”的落点。
+
+---
+
+## 5. 不可删红线与可下沉内容
+
+本节不再逐条枚举字段级“必须保留”。字段、示例、采集细则的去留交给第 4 节判据；本节只钉两件事：可下沉对象的范围，和**绝不可删的跨层红线**。
+
+### 5.1 可下沉 / 压缩 / 改按需读（示例，非穷举，按第 4 节判据裁）
+
+- subagent 内部查询流程与推断说明。
+- reviewer 维度解释、元叙述（ReAct）与长示例。
+- data artifact 的完整 payload 细则（迁到 data-agent 单文件，不在主 Skill 重复）。
+- init 详细采集字段、题材列表、反套路库。
+- plan 的 CBN / CPN / CEN 详细规则与示例。
+- polish 长 checklist。
+- 第 6 节列出的 `always` 全文读大 reference（改区段读 / 检索读 / 条目化）。
+
+### 5.2 不可删的跨层红线（穷举，由第 12 节行为测试守护）
+
+这些是跨 Skill / Agent / Runtime 的业务红线，任何瘦身都不得删，且必须有对应的行为 / 契约级断言（第 12 节）：
+
+- 项目根保护、init 目录安全化、用户确认前不写 canon。
+- `placeholder-scan` 出现在 plan / write 关键节点。
+- 真实 `CHAPTER_GOAL` 解析，禁止占位 query。
+- `story-system --persist --emit-runtime-contracts` 的章级刷新。
+- `write-gate` prewrite / precommit / postcommit 三道 gate，顺序不可乱。
+- 必须用 `Agent` 工具显式调用 subagent，不得主流程口头替代。
+- reviewer 原始 JSON 经 `review-pipeline --save-metrics` 落库。
+- data-agent 产三份 artifacts；artifact 字段由 runtime validator 守，不靠主 Skill 文案。
+- `chapter-commit` 是唯一事实提交入口，驱动 projection。
+- postcommit projection 五项验证；失败只 `projections retry`，不回退写作步骤。
+- `backup --project-root "${PROJECT_ROOT}"`，禁止裸 `git add .`。
+- plan 的节拍表、时间线、章纲节点、设定写回、结构化总纲写回、状态更新。
+
+> 字段级条目（如 `planned_nodes` 等具体字段名）**不在本清单**——它们由判据一归到生产方 agent 与 runtime schema，由第 12 节契约级测试守护，不再作为主 Skill 的文案红线。
+
+---
+
+## 6. 修改范围
+
+### 6.1 重点文件
+
+| 类型 | 文件 |
+|---|---|
+| 写章 Skill | `webnovel-writer/skills/webnovel-write/SKILL.md` |
+| 写前 Agent | `webnovel-writer/agents/context-agent.md` |
+| 数据 Agent | `webnovel-writer/agents/data-agent.md` |
+| 审查 Agent | `webnovel-writer/agents/reviewer.md` |
+| 拆书 Agent | `webnovel-writer/agents/deconstruction-agent.md` |
+| 初始化 Skill | `webnovel-writer/skills/webnovel-init/SKILL.md` |
+| 规划 Skill | `webnovel-writer/skills/webnovel-plan/SKILL.md` |
+| 审查 Skill | `webnovel-writer/skills/webnovel-review/SKILL.md` |
+| 查询 Skill | `webnovel-writer/skills/webnovel-query/SKILL.md` |
+| 轻量 Skill | `webnovel-learn`、`webnovel-dashboard`、`webnovel-doctor` |
+
+### 6.2 references 与读取方式优化
+
+references 是本轮被低估的 token 面：顶层 `references/` 加各 Skill 的 `references/` 合计 60+ 个文件。优化不靠新增，而靠三件事——以现有加载映射为基线、给每个读取动作定读取方式、清掉已迁走的死文件。
+
+#### 6.2.1 基线：reference-loading-map
+
+`references/index/reference-loading-map.md` 已登记每个 Skill 每个 step 的实际 reference 消费，并已区分三类：
+
+- **直接 Read 的 md**（整文件加载）——问题集中在这里。
+- `reference_search.py` 检索 CSV（按 `--table --query --genre` 返回条目）——已是“按字段读”的范本。
+- `story-system` 间接消费 CSV——已是按需。
+
+CSV 那条线已经做对了，本轮**不重做检索层**；只治“直接 Read 的 md 全文加载”，并把读取方式登记进 loading-map，使其从“读哪些文件”升级为“怎么读这些文件”。
+
+#### 6.2.2 token 靶心：`always` 全文读的大 md
+
+以下是“直接 Read 且 always / 高频触发”的大文件，是 init / plan / write 每跑必吞的常驻成本，按判据四改读取方式：
+
+| 文件 | 行数 | 谁全文读 | 目标读取方式 |
+|---|---|---|---|
+| `references/genre-profiles.md` | 552 | init + plan 双重 always | 区段读：按目标 genre 定位该题材段 |
+| `creativity/selling-points.md` | 513 | init Step5 always | 区段读 / 条目化 |
+| `reading-power-taxonomy.md` | 268 | plan Step7 | 区段读 |
+| `outlining/chapter-planning.md` | 260 | plan Step7 | 区段读「结构化节点规范」一节 |
+| `creativity/creativity-constraints.md` | 248 | init Step5 always | 区段读 `8.1 五维评分` 等命中节 |
+| `webnovel-write/references/polish-guide.md` | 246 | write Step4 always | 区段读 / 条目化 checklist |
+| `shared/cool-points-guide.md` | 242 | plan / review 触发 | 区段读 |
+
+短文件（如 `strand-weave-pattern.md` 90 行）维持全文读，不动。
+
+#### 6.2.3 清理死 reference（处置前先核验 CSV 覆盖）
+
+`reference-gap-register.md` 记录的 `writing/*.md → CSV` 迁移已部分完成：loading-map 的「当前非直接调用项」确认 `combat-scenes`、`dialogue-writing`、`emotion-psychology`、`scene-description`、`desire-description`、`genre-hook-payoff-library` 等已不再被直接 Read（由 CSV 承担触发），但文件仍在，合计约 1400 行死内容。处置步骤：
+
+1. 对每个候选 md，先核验 `场景写法.csv` / `写作技法.csv` 是否真覆盖其内容——不盲删。
+2. 已覆盖：删除，或保留为指向 CSV 的空壳。
+3. 未覆盖：先把缺口条目人工补进 CSV（遵循 `csv/README.md` 手动迁移规则），再处置 md。
+
+#### 6.2.4 修正过时的“新增候选”
+
+v2 第 6.2 列的候选已与现状脱节，按现状重判：
+
+| v2 候选 | 现状 | 处置 |
+|---|---|---|
+| `blocking-override-guidelines.md` | 已存在并落位（gap-register 2026-04-16） | 删候选，改为“沿用现有” |
+| `chapter-node-rules.md` | 与现有 `outlining/chapter-planning.md`「结构化节点规范」重复 | 不新建，对该节做区段读 |
+| `init-flow.md` | 与现有 `init-collection-schema.md` 重复 | 不新建，沿用并改区段读 |
+| `subagent-contracts.md` | 与判据一冲突（契约形状在主 Skill，schema 在生产方 agent） | 不新建 |
+| `polish-checklist.md` | 可作为 `polish-guide.md` 条目化的产物 | 仅在 6.2.2 条目化时顺带产出 |
+
+原则不变：不为“三段式结构”强行新增 reference；优先改读取方式与清死文件，而非加文件。
+
+---
+
+## 7. Phase 0：基线统计、读取审计与红线测试
+
+### 7.1 目标
+
+先确认哪些文本该保留、下沉、删除、改读取方式，并把跨层红线先补成行为测试，形成瘦身前的绿色基线。
+
+### 7.2 要做
+
+1. 统计 8 个 Skill、4 个 Agent 与 references 的体量；references 直接用 reference-loading-map + 行数表（见第 6 节），不另起炉灶。
+2. 对每个文件按第 4 节判据标出归属：主 agent（契约形状）/ subagent / runtime / 下沉 references / 改读取方式 / 第 3 节红线。
+3. **token 基线**：测“主 agent 写一章实际加载的上下文”，而非文件行数——记录 webnovel-write 主链一次 default 写章，主 Skill + 内联内容 + 全文读 reference 的近似 token，作为降幅度量基准。
+4. **读取审计**：对照 loading-map「直接 Read 的 md」，逐条标 全文 / 区段 / 检索 / 不读（第 6.2.2 靶心优先）。
+5. **先补红线测试再瘦身**：把第 5.2 跨层红线中当前只有文案级断言或无断言的，补成行为 / 契约级断言（第 12 节），使其在改动前先变绿。
+6. **工具能力复核**：核对 Claude Code 官方最新 tools / subagents / skills 文档、本机 plugin-dev 指导和当前安装版本；确认 `Agent`、`Skill`、`AskUserQuestion`、`Read`、`Grep`、`Glob`、`Bash`、`PowerShell` 等是否存在、如何授权、在 subagent 中如何表现。复核结果落盘，后续提示词不得写入未核实的工具能力。
+7. 跑基线验证：
+
+```bash
+python -m pytest webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py -q --no-cov
+python -X utf8 webnovel-writer/scripts/run_behavior_evals.py --format json
+python -X utf8 webnovel-writer/scripts/validate_plugin_package.py --format json
+```
+
+### 7.3 验收
+
+- 得到每个 Skill / Agent / reference 的“保留 / 下沉 / 删除 / 读取方式”清单，**落盘为可追踪文件**，不只是口头结论。
+- token 基线数值已记录，作为后续降幅度量基准。
+- 第 5.2 全部跨层红线都有行为 / 契约级断言且通过。
+- 当前验证命令通过。
+
+---
+
+## 8. Phase 1：精简 `webnovel-write`
+
+### 8.1 目标
+
+让写章 Skill 从“详细教程”变成“调度合同”，但保留完整写章主链。
+
+### 8.2 必须保留
+
+- 模式：默认 / `--fast` / `--minimal`。
+- 准备：`preflight`、`where`、`placeholder-scan`、真实 `CHAPTER_GOAL`、`story-system` 合同刷新、`write-gate prewrite`。
+- 三个 Agent 调用：`context-agent`、`reviewer`、`data-agent`。
+- 起草只吃五段写作任务书。
+- reviewer 原始 JSON + `review-pipeline --save-metrics`。
+- blocking issue 只定点修复或用户裁决，不伪造通过。
+- 润色顺序和 anti-AI 终检。
+- data-agent 三份 artifacts。
+- `write-gate precommit`。
+- `chapter-commit`。
+- `write-gate postcommit`。
+- `projections retry`。
+- `backup --project-root "${PROJECT_ROOT}"`。
+- 成功标准与失败恢复。
+
+### 8.3 可压缩
+
+- context-agent 怎么查上下文。
+- reviewer 怎么逐维度审查。
+- data-agent 完整 payload schema。
+- 长润色教程和大段示例。
+
+### 8.4 Agent 调用目标形态
+
+context-agent：
+
+```text
+chapter={chapter_num}
+project_root=${PROJECT_ROOT}
+scripts_dir=${SCRIPTS_DIR}
+storage_path=${PROJECT_ROOT}/.webnovel
+state_file=${PROJECT_ROOT}/.webnovel/state.json（projection/read-model，仅兼容读取）
+要求：先 research，再按 本章硬性约束 -> CBN/CPNs/CEN -> 本章禁区 -> 风格指引 -> dynamic_context 补充参考 的顺序输出五段写作任务书；上下文不足时返回 blocker。
+```
+
+reviewer：
+
+```text
+chapter={chapter_num}
+chapter_file=${CHAPTER_FILE}
+project_root=${PROJECT_ROOT}
+scripts_dir=${SCRIPTS_DIR}
+output=${PROJECT_ROOT}/.webnovel/tmp/review_results.json
+要求：只输出结构化审查结果，不评分，不口头总结。
+```
+
+data-agent：
+
+```text
+chapter={chapter_num}
+chapter_file=${CHAPTER_FILE}
+project_root=${PROJECT_ROOT}
+scripts_dir=${SCRIPTS_DIR}
+output_dir=${PROJECT_ROOT}/.webnovel/tmp
+要求：生成 fulfillment_result.json、disambiguation_result.json、extraction_result.json；不直接写 projection。
+```
+
+### 8.5 风险控制
+
+- `write-gate precommit` 与 `artifact_validator` 兜底 schema。
+- behavior eval 检查三道 gate、三类 artifacts、chapter-commit、postcommit、backup。
+- prompt integrity 检查禁止裸 `git add .`、禁止主流程口头替代 subagent。
+
+---
+
+## 9. Phase 2：精简 4 个 Agent
+
+### 9.1 `context-agent`
+
+目标：成为上下文压缩器，输出稳定 `chapter_task_brief`。
+
+必须保留：
+
+- `memory-contract load-context`。
+- `query-entity`、`query-rules`、`get-timeline` 按需查询。
+- load-context 已包含内容不重复查。
+- `.story-system/` 合同优先，`state.json` 仅兼容读取。
+- `chapter_directive.goal` / 章纲真实目标优先，`dynamic_context` 只作写法参考。
+- 五段任务书：开篇委托、这章的故事、这章的人物、怎么写更顺、收在哪里。
+- 红线校验和上下文不足 blocker。
+
+可以删除或压缩：
+
+- 长示例。
+- 过细推断说明。
+- 不必要术语解释。
+
+### 9.2 `data-agent`
+
+目标：只做事实提取和 artifacts 生成。
+
+必须保留：
+
+- 读取正文、实体索引和别名。
+- 三份 artifact 文件名。
+- `fulfillment_result.json` 顶层 `planned_nodes`、`covered_nodes`、`missed_nodes`、`extra_nodes`。
+- `disambiguation_result.json` 顶层 `pending`。
+- `extraction_result.json` 顶层 `accepted_events`、`state_deltas`、`entity_deltas`、`entities_appeared`、`scenes`、`summary_text`。
+- `accepted_events` 子项最小字段：`event_id`、`chapter`、`event_type`、`subject`、`payload`。
+- `state_deltas` 字段命名：`field`、`old`、`new`。
+- `entity_deltas` 字段命名：`entity_type`。
+- 禁止直接写 state / index / summaries / memory / vectors / projection。
+
+可以删除或压缩：
+
+- 各 event_type 完整 payload 长说明。
+- 长 JSON 示例。
+- 兼容旧字段名的详细解释。
+
+### 9.3 `reviewer`
+
+目标：只做可验证事实审查。
+
+必须保留：
+
+- 五个维度：setting、timeline、continuity、character、logic。
+- 每个维度都给 `dimension_results`，无问题也写 `pass`。
+- 每个 issue 有 evidence 和 fix_hint。
+- 不评分、不评价文笔、不建议新增剧情、不暴露未发生大纲。
+- 输出严格 JSON。
+
+必须删除或改写：
+
+- “思维链 / ReAct”类表述。
+- 过长审查教程。
+
+### 9.4 `deconstruction-agent`
+
+目标：拆参考书的可迁移模式，不污染新书 canon。
+
+必须保留：
+
+- quick / deep / auto 路由。
+- 只有书名/平台无文本时，不得凭记忆编造黄金三章、角色、设定、剧情。
+- 不写任何文件。
+- 不生成新书 canon。
+- 输出 `init_reference_research` JSON。
+- `quality`、`resume_state`、`do_not_copy`、`canon_contamination_warnings`。
+- 快速模式、深度模式、情节点、质量门控、抽象转化规则。
+
+可以压缩：
+
+- 长质量门控表。
+- 超长 schema 细节。
+- 深度拆解分阶段长说明。
+
+---
+
+## 10. Phase 3：精简 init / plan / review Skills
+
+### 10.1 `webnovel-init`
+
+Skill 可以更短，但必须保留第 3.2 节完整链。
+
+压缩方向：
+
+- 详细采集字段保留在现有 `init-collection-schema.md`，对其做区段读；不新建 init-flow.md（见 6.2.4）。
+- 题材列表只保留 canonical 集合和少量示例。
+- CLI 参数长表可收缩为“参数来自采集对象”，但要保留执行 init 的事实。
+- 创意约束细则、反套路库、世界观设计指南按需读取。
+
+不可删：
+
+- Step 1.5 灵感来源询问。
+- deconstruction-agent 调用边界。
+- 用户确认前不写 canon。
+- project root 安全化和确认。
+- `idea_bank.json`。
+- patch 总纲。
+- init 后 MASTER_SETTING 生成。
+- 验证与最小回滚。
+
+### 10.2 `webnovel-plan`
+
+Skill 可以更短，但必须保留第 3.3 节完整链。
+
+压缩方向：
+
+- CBN / CPN / CEN 细则保留在现有 `outlining/chapter-planning.md`「结构化节点规范」，对该节做区段读；不新建 chapter-node-rules.md（见 6.2.4）。
+- 长 reference 表可改为“按阶段触发读取”。
+- 结构化节点示例下沉。
+
+不可删：
+
+- placeholder-scan。
+- 跨卷状态读取。
+- 设定基线补齐。
+- 卷节拍表。
+- 卷时间线。
+- 卷纲。
+- 批量章纲。
+- 设定写回。
+- 显式 `大纲/第{volume_id}卷-总纲写回.json`。
+- `master-outline-sync`。
+- `update-state`。
+- 真实 `CHAPTER_GOAL` 刷新 Story System 合同。
+
+### 10.3 `webnovel-review`
+
+Skill 可以更短，但必须保留第 3.5 节完整链。
+
+压缩方向：
+
+- reviewer 审查方法留给 reviewer。
+- 证据查询过程不在 Skill 展开。
+
+不可删：
+
+- 合同缺失时补 `story-system`。
+- reviewer Agent 调用。
+- `review-pipeline --save-metrics`。
+- `update-state --add-review`。
+- blocking 用户裁决。
+
+---
+
+## 11. Phase 4：精简轻量 Skills
+
+### 11.1 `webnovel-query`
+
+目标：查询先分类，再用最窄工具。
+
+保留：
+
+- 只读。
+- 项目根保护。
+- `.story-system` -> latest accepted commit -> memory-contract -> projection fallback 的优先级。
+- 降级说明。
+
+优化：
+
+- 不默认全量 `memory-contract load-context`；按查询类型调用最窄工具。
+- 角色状态用 `knowledge query-entity-state`。
+- 关系用 `knowledge query-relationships`。
+- 规则用 `memory-contract query-rules`。
+- 伏笔用 open-loop 查询。
+
+### 11.2 `webnovel-learn`
+
+目标：保持极简。
+
+保留：
+
+- 项目根保护。
+- 读当前章节号。
+- `project-memory add-pattern`。
+- 不手写 JSON。
+
+### 11.3 `webnovel-dashboard`
+
+目标：保持只读面板。
+
+保留：
+
+- 只读边界。
+- `story-runtime/health`。
+- 项目根解析。
+- 前端 dist 校验。
+
+可调整：
+
+- 不默认安装依赖；缺依赖时提示命令。
+- 启动前可运行轻量检查。
+
+### 11.4 `webnovel-doctor`
+
+目标：保持只读诊断。
+
+保留：
+
+- `project-status` 先行。
+- `doctor` 阶段感知检查。
+- 不修复、不安装、不启动 dashboard。
+
+可调整：
+
+- frontmatter description 改成简洁中文触发型描述。
+
+---
+
+## 12. Phase 5：测试与行为验证
+
+### 12.1 修改文件
+
+- `webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py`
+- `webnovel-writer/evals/fixtures/behavior/fast.json`
+- 新增行为 / 契约级断言；删除或迁移过时的文案级断言（见 12.2）。
+
+### 12.2 验收原则：行为 / 契约级，不锚文案
+
+总原则：断言“做没做对”，不断言“文案里有没有某串字”。`fast.json` 的 `commit_projection_runtime`（真跑 commit → projection 并断言状态）是样板；`assert "字符串" in text` 是要逐步退役的形式。
+
+#### 必保行为（用行为 / 契约断言守，不锚具体措辞）
+
+- 写章主链：三道 gate（prewrite / precommit / postcommit）按序落地；reviewer 一轮；blocking 只定点修复或用户裁决；data-agent 三份 artifacts；`chapter-commit` 提交并驱动 projection；postcommit 五项 projection 全 done/skipped；失败只 `projections retry`；`backup --project-root`。
+- artifact 契约：三份 artifact 字段由 runtime schema（`chapter_commit_schema` / `story_event_schema` / `schemas`）校验；**新增 precommit 负向用例**——缺 `missed_nodes` / `pending` / 关键字段时 precommit 必须拦截。这取代“主 Skill 文案里必须出现字段名”的检查。
+- 8 个 Skill 可发现、frontmatter 合法、description 可触发、中文优先。
+- 4 个 Agent 单文件、frontmatter 含 `name`/`description`/`model`/`color`、`tools` 最小集、不依赖 `agents/references/*`。
+- Agent 边界：data-agent 不直接写 projection；reviewer 只输出结构化 JSON 且覆盖 5 维；context-agent 输出五段任务书、用 `load-context`；deconstruction-agent 不写文件、产 `init_reference_research`、防 canon 污染、保留 Step 1.5 与确认门。
+- plan 保留 `.story-system/` 主链与节拍表/时间线/章纲节点/总纲写回/状态更新；query / dashboard / doctor 只读不写项目文件。
+
+#### 该删 / 该迁 / 该松绑的现有断言
+
+| 现有断言 | 问题 | 处置 |
+|---|---|---|
+| `test_webnovel_write_data_agent_prompt_requires_extraction_schema` | 逐字要求主 Skill 写出 schema 字段名，与判据一冲突 | **删**；字段保障迁到 data-agent 单文件 + precommit 负向用例 |
+| `test_data_agent_is_described_as_extraction_only...` 的字段名清单 | 检查 data-agent.md 含字段名（文案级） | 保留并加强为 data-agent 单文件 schema 的契约校验 |
+| `test_agent_template_structure`（要求 1–8 连续编号段） | 强迫凑结构；删 reviewer 的 ReAct 节会误伤 | **松绑**：删 ReAct 后重排编号或下调段数要求，别为过测试留空段 |
+| 各 `assert "字符串" in SKILL.md` 措辞锚定项 | 锚文案、阻碍瘦身 | 改为行为 / 契约断言，或迁到生产方 |
+
+### 12.3 验证命令
+
+文档与提示词层：
+
+```bash
+python -m pytest webnovel-writer/scripts/data_modules/tests/test_prompt_integrity.py -q --no-cov
+python -X utf8 webnovel-writer/scripts/run_behavior_evals.py --format json
+python -X utf8 webnovel-writer/scripts/validate_plugin_package.py --format json
+```
+
+稳妥回归：
+
+```bash
+python -m pytest webnovel-writer/scripts/data_modules/tests webnovel-writer/scripts/tests -q --no-cov
+```
+
+### 12.4 验收标准
+
+- 8 个 Skill 仍可发现；4 个 Agent frontmatter 合法。
+- 插件结构符合官方 `plugin-structure`；Skill / Agent 修改符合 `plugin-dev`。
+- behavior eval、package validator、prompt integrity 全过（在退役文案断言、补齐行为 / 契约断言之后）。
+- 第 5.2 跨层红线全部有行为 / 契约级断言守护。
+- **token：写章主链“主 agent 写一章加载的上下文”相对 Phase 0 基线下降，并给出数值**，不是“明显下降”的主观判断。
+- 主 Skill 不再携带 subagent 长流程与 data schema；schema 真源唯一在生产方 agent + runtime。
+- references：第 6.2.2 靶心大文件已改按需读；死 reference 已核验并处置。
+- 第 3 节端到端流程未被瘦身删掉。
+
+---
+
+## 13. 官方 plugin-dev 约束
+
+后续所有修改必须遵循本机官方插件指导：
+
+```text
+C:\Users\lcy\.claude\plugins\marketplaces\claude-plugins-official\plugins\plugin-dev
+```
+
+落地规则：
+
+- 插件结构遵循 `plugin-structure`：`.claude-plugin/plugin.json` 位于插件根的 `.claude-plugin/`；`skills/`、`agents/`、`hooks/`、`scripts/` 保持插件根层级。
+- Skill 遵循 `skill-development`：每个 Skill 一个目录，必须有 `SKILL.md`；frontmatter 至少包含 `name` 和具体触发型 `description`；详细资料可以放入该 Skill 自己的 `references/`，按需读取。
+- Agent 遵循 `agent-development`：每个 Agent 是 `agents/*.md` 单文件；frontmatter 包含 `name`、`description`、`model`、`color`，`tools` 限定到最小必要集合。
+- 本项目的 4 个 Agent 由 Skill 显式调用，不依赖自动触发；Agent `description` 只需说明调用方、职责和交付产物。
+- Agent 不使用外部 reference 作为隐藏说明书。
+- Hook 相关修改继续遵循 `hook-development`：插件级 `hooks/hooks.json` 使用 wrapper 格式，命令路径使用 `${CLAUDE_PLUGIN_ROOT}`。
+- 每轮改完插件组件后，按 `plugin-validator` 思路校验 manifest、skills、agents、hooks、README、LICENSE、敏感信息和路径可移植性。
+
+---
+
+## 14. 风险与控制
+
+| 风险 | 影响 | 控制 |
+|---|---|---|
+| 为了格式精简删掉真实流程 | 写作链断裂 | 第 3 节作为流程断言，prompt integrity / behavior eval 覆盖 |
+| 主 Skill 过度精简 | Agent 输入不足 | Skill 保留 Agent 最小输入合同 |
+| schema 压缩后 agent 漏字段 | commit 前失败 | `artifact_validator` 与 `write-gate precommit` 阻断 |
+| Agent 单文件过短 | 专业执行质量下降 | 单文件保留最小必要流程、边界和输出合同 |
+| reference 下沉过多 | 执行时忘记读取 | reference 只给长细则，主流程保留触发条件 |
+| 区段读锚点漂移 | 读到错段或空内容 | reference 用稳定标题锚点；区段读失败时回退全文读并告警 |
+| 文案级断言阻碍瘦身 | 误把测试当约束 | 退役文案断言、改行为 / 契约级（第 12 节）；删 / 迁前确认非红线 |
+| query 默认少查导致答案不完整 | 查询质量下降 | 分类后按需补查，回答中说明降级 |
+| state.json 被误当事实源 | 写后事实漂移 | 明确 `.story-system` 与 accepted commit 优先级 |
+| init 拆书污染 canon | 新书设定侵权或撞梗 | deconstruction-agent 不写文件，init 用户确认后才写入差异化模式 |
+
+---
+
+## 15. 推荐施工顺序
+
+1. Phase 0：基线统计、读取审计、token 基线，**先把第 5.2 红线补成行为测试形成绿色基线**。
+2. `webnovel-write`：先保全写章主链，再瘦主 Skill；同步退役锚文案的 schema 断言。
+3. `context-agent`：稳定五段任务书和上下文压缩。
+4. `data-agent`：schema 作为单文件唯一真源，删长 payload 教程；加 precommit 负向用例。
+5. `reviewer` + `webnovel-review`：删 ReAct 元叙述并重排段号，统一结构化审查链。
+6. `webnovel-init` + `deconstruction-agent`：保留确认门和防 canon 污染。
+7. `webnovel-plan`：保留规划到合同的桥。
+8. references 与读取方式：按第 6.2 改靶心大文件读取方式、清死文件、登记进 loading-map。
+9. `webnovel-query` / `webnovel-learn` / `webnovel-dashboard` / `webnovel-doctor`。
+10. 测试与 eval 收口。
+
+原因：
+
+- 写章链路最吃 token，也最容易受上下文污染影响；`webnovel-write` 承载最多 subagent 内部细节，先改收益最大。
+- 先补红线行为测试、固定绿色基线，后续每个 Skill 才能放心瘦身且不误删红线。
+- reference 读取优化独立成步，因为它跨多个 Skill 且以 loading-map 为统一基线。
+
+---
+
+## 16. 最终效果
+
+目标完成后，写章链路应该是：
+
+```text
+preflight / where / placeholder-scan
+  ↓
+解析真实 CHAPTER_GOAL
+  ↓
+story-system 刷新 runtime contracts
+  ↓
+write-gate prewrite
+  ↓
+context-agent 生成五段写作任务书
+  ↓
+主 agent 根据任务书起草
+  ↓
+reviewer 审查
+  ↓
+review-pipeline 落库
+  ↓
+主 agent 定点修复和润色
+  ↓
+data-agent 生成 artifacts
+  ↓
+write-gate precommit
+  ↓
+chapter-commit
+  ↓
+write-gate postcommit
+  ↓
+projection retry（仅失败时）
+  ↓
+backup
+```
+
+每一层只知道自己需要知道的东西：
+
+- 主 agent 知道调度和不可跳过的 runtime 命令。
+- context-agent 知道上下文压缩。
+- reviewer 知道审查。
+- data-agent 知道事实提取。
+- runtime 知道校验、提交、投影和状态推进。
+
+这才是本轮上下文减负的核心：不是把文档变短，而是让每一段上下文只在正确的时刻出现。

docs/architecture/multi-agent-adaptation-spec-2026-06-05.md

@@ -0,0 +1,808 @@
+# Webnovel Writer 多宿主与多智能体适配 Spec
+
+> 日期：2026-06-05
+> 状态：草案 v2
+> 基线：`master` 当前插件形态，`.claude-plugin/plugin.json` 与 marketplace 版本为 `6.1.0`
+> 来源：基于 PR #110 的 review 结论重写，修正过期的 7 Skill / hooks / doctor / runtime 状态描述
+> 定位：把 Webnovel Writer 在不破坏 Claude Code 现有体验的前提下，演进为可验证、可生成、可降级的多宿主写作插件
+
+---
+
+## 1. 背景
+
+PR #110 的方向是对的：Webnovel Writer 不应该永远只被 Claude Code 的表达方式绑定。它已经有完整的写作运行时、Story System、RAG、Dashboard、Agent 分工和发布校验，下一步可以考虑多宿主适配。
+
+但 PR #110 的原始 spec 使用了旧基线：
+
+- 只列出 7 个 Skill，漏掉 `/webnovel-doctor`。
+- 把 hooks 描述为“当前未形成 bootstrap”，但当前主干已经有 `hooks/hooks.json`、`session_start.py` 和 `guard_runtime_write.py`。
+- 没有把 `project-status`、`doctor`、`write-gate`、`projections retry/replay`、`.webnovel/projection_log.jsonl` 纳入最终形态。
+- 新增文档放在 `docs/superpowers/specs/`，但当前 `superpowers` 已归档到 `docs/archive/superpowers/`。
+
+因此，本 spec 以当前 `v6.1.0` 运行时为基线重新定义多宿主适配方案。
+
+---
+
+## 2. 当前真实基线
+
+### 2.1 Claude Code 插件结构
+
+当前插件根为 `webnovel-writer/`，符合官方 `plugin-dev` 对 Claude Code 插件结构的要求：
+
+```text
+webnovel-writer/
+├── .claude-plugin/
+│   └── plugin.json
+├── agents/
+│   ├── context-agent.md
+│   ├── data-agent.md
+│   ├── deconstruction-agent.md
+│   └── reviewer.md
+├── skills/
+│   ├── webnovel-init/
+│   ├── webnovel-plan/
+│   ├── webnovel-write/
+│   ├── webnovel-review/
+│   ├── webnovel-query/
+│   ├── webnovel-learn/
+│   ├── webnovel-dashboard/
+│   └── webnovel-doctor/
+├── hooks/
+│   ├── hooks.json
+│   ├── session_start.py
+│   └── guard_runtime_write.py
+├── scripts/
+├── references/
+├── templates/
+├── genres/
+└── dashboard/
+```
+
+### 2.2 当前 8 个 Skill
+
+| Skill | 当前职责 | 多宿主适配时的地位 |
+|---|---|---|
+| `/webnovel-init` | 初始化新书项目 | 保留为项目创建入口 |
+| `/webnovel-plan` | 规划卷纲、章纲、运行时合同 | 保留为规划入口 |
+| `/webnovel-write` | 写章主链，调用 gate、agent、commit、projection | 多宿主适配的最高优先级主流程 |
+| `/webnovel-review` | 审查章节范围 | 保留为可独立调用的质量入口 |
+| `/webnovel-query` | 只读查询项目状态、设定和记忆 | 保留为跨宿主只读查询入口 |
+| `/webnovel-learn` | 追加项目经验记忆 | 保留为受控写入入口 |
+| `/webnovel-dashboard` | 启动只读 Dashboard | 保留 Claude Code 主路径，其他宿主可降级为 CLI 提示 |
+| `/webnovel-doctor` | 阶段感知体检目录、文件、DB、RAG、依赖 | 必须纳入所有宿主的安装后自检路径 |
+
+### 2.3 当前 4 个 Agent
+
+| 当前文件 | 当前职责 | 目标规范名 |
+|---|---|---|
+| `context-agent.md` | 写前上下文与任务书组装 | `webnovel-context-agent` |
+| `reviewer.md` | 多维审查与 blocking issue 输出 | `webnovel-reviewer` |
+| `data-agent.md` | 提取 commit artifacts，不直接写 projection | `webnovel-data-agent` |
+| `deconstruction-agent.md` | 拆解参考书和结构学习 | `webnovel-deconstruction-agent` |
+
+当前文件名不能直接删除或重命名，因为现有 Skill 文案和用户习惯可能仍引用旧名。目标规范名必须通过兼容迁移引入。
+
+### 2.4 当前 Runtime CLI
+
+所有确定性动作已经统一从 `scripts/webnovel.py` 进入。多宿主适配必须复用这些 runtime 命令，不为每个宿主重写一套业务逻辑。
+
+关键命令：
+
+| 命令 | 作用 |
+|---|---|
+| `preflight` | 快速环境与项目根检查 |
+| `project-status` | 机器可读短状态、phase、下一步 |
+| `doctor` | 阶段感知项目体检与修复建议 |
+| `write-gate` | 写前、提交前、提交后三个自然边界校验 |
+| `story-system` | Story System 合同与运行时数据 |
+| `chapter-commit` | 章节事实提交，驱动 projection |
+| `projections retry/replay` | 基于已有 commit 补跑或重放投影 |
+| `status` | 旧宏观创作健康报告，保持原语义 |
+
+### 2.5 当前 Hook
+
+当前已经存在 Claude Code 插件级 hooks：
+
+- `SessionStart`：只运行 `project-status --format summary`，给新会话提供短状态。
+- `PreToolUse`：对直接写 `.story-system/commits/`、`.webnovel/state.json`、`index.db`、`vectors.db`、`memory_scratchpad.json`、`projection_log.jsonl` 等危险路径做兜底阻断。
+
+hook 是轻量守卫，不是业务状态机。
+
+### 2.6 当前验证能力
+
+当前已有两类基础验证：
+
+- `scripts/validate_plugin_package.py`：按官方 `plugin-dev` 思路检查 manifest、Skill / Agent frontmatter、hooks wrapper、README 版本、路径可移植性。
+- `scripts/run_behavior_evals.py` + `evals/fixtures/behavior/fast.json`：检查 8 个 Skill 的关键行为契约、Agent 边界、commit/projection、Dashboard 只读语义。
+
+多宿主适配必须扩展这两类验证，而不是新造一套互不相干的检查。
+
+---
+
+## 3. 目标
+
+### 3.1 一句话目标
+
+把 Webnovel Writer 从“Claude Code 单宿主插件”升级为：
+
+> 以现有 Python runtime 和 Story System 为唯一业务核心，向多个宿主生成轻量 adapter 的长篇写作插件。
+
+### 3.2 具体目标
+
+1. 保留 Claude Code 现有安装、Skill、Agent、hook 和 CLI 体验。
+2. 让 Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot CLI 等宿主可以通过 adapter 消费同一套写作能力。
+3. 所有宿主都复用 `scripts/webnovel.py` 和 `data_modules`，不复制 Story System、commit、projection、doctor、gate 逻辑。
+4. 每个宿主的支持状态必须可验证，有 manifest 校验、smoke 测试和行为 eval。
+5. 当宿主不支持 subagent 或 hook 时，有明确降级模式，不假装已经调用了不存在的能力。
+6. 所有新增插件组件继续符合官方 `plugin-dev` 的结构、frontmatter、hooks、路径和验证要求。
+
+---
+
+## 4. 非目标
+
+本 spec 不做这些事：
+
+- 不重写 Story System 主链。
+- 不拆掉现有 8 个 Skill。
+- 不改变 `webnovel.py status` 的旧健康报告语义。
+- 不把 `doctor`、`project-status`、`write-gate`、`projection_log` 重新设计成另一套平行系统。
+- 不把 hooks 变成隐藏业务流程。
+- 不自动启动 Docker、Dashboard、RAG 服务或外部依赖。
+- 不把 `docs/superpowers/` 重新作为活跃文档区；活跃架构 spec 进入 `docs/architecture/`。
+- 不承诺未经官方文档和本地验证的外部宿主能力。
+
+---
+
+## 5. 设计原则
+
+### 5.1 Runtime 是唯一业务真源
+
+Skill、Agent、hook、adapter 都只是入口或调度层。真正能修改项目事实的动作必须进入 runtime：
+
+```text
+Skill / host command
+    ↓
+webnovel.py
+    ↓
+data_modules
+    ↓
+.story-system commit
+    ↓
+projection read-models
+```
+
+任何宿主 adapter 都不能直接写 `.story-system/commits/` 或 `.webnovel/*` read-model。
+
+### 5.2 Claude Code 是第一支持宿主
+
+Claude Code 当前体验必须保持稳定：
+
+- `.claude-plugin/plugin.json` 保持官方位置。
+- `skills/`、`agents/`、`hooks/` 保持插件根层级。
+- Claude hooks 继续使用 `${CLAUDE_PLUGIN_ROOT}`，符合官方 `plugin-dev`。
+- `/webnovel-*` Skill 名称继续有效。
+
+### 5.3 Adapter 尽量薄
+
+各宿主 adapter 只负责：
+
+- manifest / metadata
+- tool name mapping
+- agent frontmatter 转换
+- command 暴露方式
+- hook 能力降级
+- smoke/eval 启动方式
+
+adapter 不负责：
+
+- 改写写作流程
+- 解释 Story System
+- 校验 chapter artifacts
+- 执行 projection
+- 自己维护项目状态
+
+### 5.4 不相信手写矩阵
+
+外部宿主能力变化很快。spec 不把“某宿主现在支持什么”写成不可验证的口头事实。
+
+每个宿主 adapter 必须有自己的 `support.md` 或等价记录，包含：
+
+- 官方文档链接
+- 核验日期
+- 支持的 manifest 字段
+- 支持的 skill / command / agent / hook / MCP 能力
+- 不支持能力的降级规则
+- 本仓库对应的 smoke 测试命令
+
+### 5.5 UTF-8 First
+
+所有新增脚本和 adapter 生成器必须显式 UTF-8：
+
+- Python 文件头保留 UTF-8。
+- 文本读写使用 `encoding="utf-8"`。
+- Windows 子进程优先使用 `python -X utf8`。
+- 不依赖系统默认 GBK 编码。
+
+### 5.6 渐进迁移
+
+多宿主适配必须逐步引入：
+
+1. 先锁定现状和验证。
+2. 再补 adapter 目录与生成器。
+3. 再迁移 Agent 规范名和 Skill 文案。
+4. 最后接入跨宿主 smoke/eval。
+
+不能一次性重命名 Agent 或大改 Skill，避免破坏 Claude Code 现有用户。
+
+---
+
+## 6. 目标架构
+
+### 6.1 目标结构
+
+最终结构建议如下：
+
+```text
+webnovel-writer/
+├── .claude-plugin/
+│   └── plugin.json
+├── skills/
+│   ├── webnovel-init/
+│   ├── webnovel-plan/
+│   ├── webnovel-write/
+│   ├── webnovel-review/
+│   ├── webnovel-query/
+│   ├── webnovel-learn/
+│   ├── webnovel-dashboard/
+│   ├── webnovel-doctor/
+│   └── using-webnovel-writer/        # 可选，跨宿主使用说明与工具映射
+├── agents/
+│   ├── context-agent.md              # 旧名兼容
+│   ├── reviewer.md                   # 旧名兼容
+│   ├── data-agent.md                 # 旧名兼容
+│   ├── deconstruction-agent.md       # 旧名兼容
+│   └── aliases.json                  # 可选，声明旧名到规范名的映射
+├── hooks/
+│   ├── hooks.json                    # Claude Code 源 hook
+│   ├── session_start.py
+│   └── guard_runtime_write.py
+├── adapters/
+│   ├── README.md
+│   ├── registry.json                 # 宿主 adapter 注册表
+│   ├── claude/
+│   ├── codex/
+│   ├── cursor/
+│   ├── gemini/
+│   ├── opencode/
+│   └── copilot/
+├── scripts/
+│   ├── webnovel.py
+│   ├── validate_plugin_package.py
+│   ├── run_behavior_evals.py
+│   └── generate_host_artifacts.py    # 新增，生成非 Claude adapter 产物
+├── evals/
+│   └── fixtures/
+├── references/
+├── templates/
+├── genres/
+└── dashboard/
+```
+
+说明：
+
+- `adapters/` 是 adapter 源码和模板，不是生成产物。
+- `dist/` 用于生成后的宿主包，默认不提交。
+- 只有小型、稳定、必须被宿主直接发现的 manifest 可以提交；提交前必须通过 drift check。
+
+### 6.2 业务源与生成产物
+
+| 类型 | 路径 | 是否事实源 | 是否提交 |
+|---|---|---:|---:|
+| Claude 插件 manifest | `.claude-plugin/plugin.json` | 是 | 是 |
+| Skill 源文件 | `skills/*/SKILL.md` | 是 | 是 |
+| Agent 源文件 | `agents/*.md` | 是 | 是 |
+| Claude hook 源文件 | `hooks/hooks.json`、`hooks/*.py` | 是 | 是 |
+| Runtime | `scripts/`、`data_modules/` | 是 | 是 |
+| Adapter 模板 | `adapters/<host>/` | 是 | 是 |
+| 生成器 | `scripts/generate_host_artifacts.py` | 是 | 是 |
+| 非 Claude 生成包 | `dist/<host>/webnovel-writer/` | 否 | 否 |
+| 小型宿主 manifest 快照 | `.codex-plugin/plugin.json` 等 | 视宿主而定 | 需 drift check |
+
+---
+
+## 7. 环境变量与路径策略
+
+### 7.1 Claude Code 路径保持不变
+
+在 Claude Code 插件组件里继续使用：
+
+```text
+${CLAUDE_PLUGIN_ROOT}
+```
+
+这是官方 `plugin-dev` 推荐方式，不能为了跨宿主把 Claude hook 或 Claude Skill 里的路径粗暴替换掉。
+
+### 7.2 Runtime 可增加兼容解析
+
+Python runtime 可以支持更通用的插件根解析顺序：
+
+1. 显式 CLI 参数。
+2. `WEBNOVEL_PLUGIN_ROOT`。
+3. `CLAUDE_PLUGIN_ROOT`。
+4. 当前脚本路径向上推导。
+
+但这属于 runtime 兼容层，不代表 Claude 插件文档主变量要改名。
+
+### 7.3 Skill 文案中的路径写法
+
+Claude Code Skill 里的可执行示例继续用：
+
+```bash
+python -X utf8 "${CLAUDE_PLUGIN_ROOT}/scripts/webnovel.py" ...
+```
+
+跨宿主说明放到 `using-webnovel-writer` 或 `skills/*/references/host-tools.md`，不要把所有宿主变量塞进每个 Skill 主体。
+
+---
+
+## 8. Skill 适配规范
+
+### 8.1 保留当前 8 个业务 Skill
+
+多宿主适配不能删减当前 8 个 Skill，也不能让 `/webnovel-doctor` 成为 Claude-only 的遗漏项。
+
+每个 Skill 必须满足：
+
+- `SKILL.md` 有 `name` 和具体触发型 `description`。
+- 主体只写流程、边界和必要命令。
+- 详细工具映射、宿主差异、参考规则放进 `references/`。
+- 确定性校验交给 runtime 命令，不靠自然语言提醒。
+
+### 8.2 新增可选总入口 Skill
+
+可以新增：
+
+```text
+skills/using-webnovel-writer/SKILL.md
+```
+
+用途：
+
+- 给非 Claude 宿主提供统一使用说明。
+- 解释当前宿主下的工具名映射。
+- 引导先运行 `project-status`，必要时运行 `doctor`。
+- 说明不支持 subagent/hook 的降级模式。
+
+限制：
+
+- 不替代 8 个业务 Skill。
+- 不复制每个 Skill 的完整流程。
+- 不承载题材知识和 Story System schema。
+
+### 8.3 写章 Skill 的硬要求
+
+`webnovel-write` 是多宿主适配的核心验收对象。任何宿主的写章流程都必须保留：
+
+1. 写前调用 `write-gate --stage prewrite`。
+2. 提交前调用 `write-gate --stage precommit`。
+3. 提交事实只能走 `chapter-commit`。
+4. 提交后调用 `write-gate --stage postcommit`。
+5. projection 失败时提示 `projections retry --chapter N`。
+6. 不能直接手写 read-model。
+
+---
+
+## 9. Agent 适配规范
+
+### 9.1 规范名与旧名兼容
+
+目标规范名使用 `webnovel-` 前缀：
+
+| 旧名 | 规范名 |
+|---|---|
+| `context-agent` | `webnovel-context-agent` |
+| `reviewer` | `webnovel-reviewer` |
+| `data-agent` | `webnovel-data-agent` |
+| `deconstruction-agent` | `webnovel-deconstruction-agent` |
+
+迁移方式：
+
+1. 先在文档和 adapter registry 中声明映射。
+2. 再让生成器为不同宿主输出规范名。
+3. 最后逐步修改 Skill 正文使用规范名。
+4. 旧名至少保留一个小版本周期，避免破坏现有调用。
+
+### 9.2 Agent 边界
+
+所有宿主都必须遵守现有边界：
+
+- `context-agent` 只负责写前上下文和任务书。
+- `reviewer` 只负责审查和 blocking 输出。
+- `data-agent` 只产出 commit artifacts，不直接写 projection。
+- `deconstruction-agent` 只负责参考拆解和经验沉淀。
+
+### 9.3 无 subagent 宿主的降级模式
+
+如果宿主不能稳定调用 subagent：
+
+- 进入 compatibility mode。
+- 主 agent 按同一份任务书和 artifact schema 执行。
+- 输出必须明确说明“未调用 subagent，使用兼容模式”。
+- 仍然必须通过 `artifact_validator`、`write-gate` 和行为 eval。
+- 不允许声称已经调用了不存在的 subagent。
+
+---
+
+## 10. Hook 适配规范
+
+### 10.1 Claude Code hook 保持现状
+
+当前 Claude Code hook 是有效基线：
+
+```text
+hooks/hooks.json
+hooks/session_start.py
+hooks/guard_runtime_write.py
+```
+
+必须继续满足官方 `plugin-dev`：
+
+- `hooks/hooks.json` 使用 wrapper 格式：外层包含 `description` 与 `hooks`。
+- command hook 使用 `${CLAUDE_PLUGIN_ROOT}`。
+- hook 脚本只做轻量、确定性、可快速退出的检查。
+
+### 10.2 其他宿主 hook 可选
+
+其他宿主是否支持 hook，由对应 adapter 的 `support.md` 和 smoke test 决定。
+
+若宿主不支持 hook：
+
+- 不影响核心写作流程。
+- 通过 `project-status` / `doctor` / `write-gate` 显式命令补足。
+- 不能让某个关键能力只存在于 hook 中。
+
+### 10.3 hook 禁止做的事
+
+hook 不允许：
+
+- 自动写 commit。
+- 自动改正文。
+- 自动改设定。
+- 自动安装依赖。
+- 自动启动长驻服务。
+- 写入章节流程状态。
+
+---
+
+## 11. Doctor 与状态入口
+
+### 11.1 所有宿主共享同一状态入口
+
+多宿主适配必须统一使用：
+
+```bash
+python -X utf8 "<PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" project-status --format summary
+```
+
+当短状态显示异常时，再运行：
+
+```bash
+python -X utf8 "<PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" doctor --format text
+```
+
+### 11.2 不新增第二套 status
+
+`status` 继续保留宏观创作健康报告语义。
+
+短状态只用 `project-status`。
+
+深度体检只用 `doctor`。
+
+### 11.3 doctor 的跨宿主价值
+
+`doctor` 是多宿主适配的安装后第一检查入口，必须能回答：
+
+- 项目根是否解析正确。
+- 当前 phase 是什么。
+- 当前 phase 应该有哪些文件。
+- 目录、JSON、SQLite 是否完整。
+- RAG 配置是否存在。
+- Python 依赖是否安装。
+- Dashboard 产物是否存在。
+- projection 是否失败。
+- 缺失项怎么修。
+
+---
+
+## 12. Adapter 设计
+
+### 12.1 Adapter registry
+
+新增：
+
+```text
+adapters/registry.json
+```
+
+建议结构：
+
+```json
+{
+  "schema_version": "webnovel-host-adapter-registry/v1",
+  "hosts": {
+    "claude": {
+      "tier": "primary",
+      "source": ".claude-plugin/plugin.json",
+      "supports": ["skills", "agents", "hooks"],
+      "smoke": "python -X utf8 scripts/validate_plugin_package.py --format json"
+    },
+    "codex": {
+      "tier": "adapter",
+      "source": "adapters/codex/",
+      "supports": [],
+      "smoke": ""
+    }
+  }
+}
+```
+
+`supports` 不能手写猜测，必须由该宿主 `support.md` 和 smoke test 支撑。
+
+### 12.2 每个宿主目录
+
+每个宿主 adapter 至少包含：
+
+```text
+adapters/<host>/
+├── support.md              # 官方文档核验记录
+├── manifest.template.*     # 需要时才有
+├── tool-mapping.md         # 工具名与降级规则
+├── agent-mapping.json      # 规范 agent 名与宿主表达
+└── smoke.md                # 本地验证命令
+```
+
+### 12.3 生成器
+
+新增生成器：
+
+```bash
+python -X utf8 scripts/generate_host_artifacts.py --target all
+python -X utf8 scripts/generate_host_artifacts.py --target codex
+python -X utf8 scripts/generate_host_artifacts.py --check
+```
+
+生成器负责：
+
+- 读取 adapter registry。
+- 读取 Skill / Agent / hook 源文件。
+- 生成宿主 manifest。
+- 生成宿主 agent 配置。
+- 生成宿主 command / skill 入口。
+- 生成 drift manifest。
+
+生成器不负责：
+
+- 修改业务源文件。
+- 联网下载依赖。
+- 改写 Story System schema。
+- 运行写作流程。
+
+---
+
+## 13. 验证与 CI
+
+### 13.1 Package validator 扩展
+
+当前 `validate_plugin_package.py` 继续作为基础。后续扩展检查：
+
+- `adapters/registry.json` schema。
+- 每个 adapter 是否有 `support.md`。
+- 每个 adapter 是否声明 smoke 命令。
+- 生成产物是否含本机绝对路径。
+- 小型提交 manifest 是否与生成器输出一致。
+- `docs/README.md` 是否索引活跃 spec。
+
+### 13.2 Behavior eval 扩展
+
+当前 fast eval 已覆盖 8 个 Skill。后续增加：
+
+- 每个宿主至少一个 install / discover smoke。
+- 每个宿主至少一个 `project-status` smoke。
+- `webnovel-doctor` 在每个宿主都有可执行说明。
+- `webnovel-write` 在至少一个非 Claude 宿主完成兼容模式验收。
+- 无 subagent 宿主不得声称调用 subagent。
+
+### 13.3 Drift check
+
+如果提交了任何生成 manifest 或 generated adapter 文件，CI 必须运行：
+
+```bash
+python -X utf8 scripts/generate_host_artifacts.py --check
+```
+
+失败时说明：
+
+- 哪个源文件变化导致 drift。
+- 应该重新运行哪个生成命令。
+- 哪些生成文件需要提交。
+
+### 13.4 外部能力核验
+
+每次实现某个宿主 adapter 前，必须重新核验官方文档。
+
+核验结果写入：
+
+```text
+adapters/<host>/support.md
+```
+
+`support.md` 至少包含：
+
+- 核验日期。
+- 官方链接。
+- 支持能力。
+- 不支持能力。
+- 本仓库采用的降级策略。
+
+---
+
+## 14. 迁移计划
+
+### Phase 0：锁定现状
+
+目标：让 spec 和当前主干一致。
+
+改动：
+
+- 新增本 spec 到 `docs/architecture/`。
+- 更新 `docs/README.md` 索引。
+- 不新增 `docs/superpowers/` 活跃目录。
+
+验收：
+
+- 文档列出 8 个 Skill。
+- 文档列出当前 hooks。
+- 文档列出 doctor、project-status、write-gate、projections、projection_log。
+- `git diff --check` 通过。
+
+### Phase 1：Adapter 研究记录与注册表
+
+目标：先验证外部宿主能力，不写大规模生成器。
+
+改动：
+
+- 新增 `adapters/README.md`。
+- 新增 `adapters/registry.json`。
+- 为每个目标宿主新增 `support.md`。
+- 每个 `support.md` 只记录官方文档核验结果和本项目降级策略。
+
+影响：
+
+- 不影响现有 Claude Code 用户。
+- 不影响 runtime。
+
+### Phase 2：Agent 规范名与兼容映射
+
+目标：引入 `webnovel-*` 规范 Agent 名，但不破坏旧名。
+
+改动：
+
+- 新增 `agents/aliases.json` 或等价映射。
+- 更新 adapter registry 使用规范名。
+- 更新 behavior eval，确保旧名与规范名不会互相漂移。
+
+影响：
+
+- Claude Code 现有 Skill 仍可调用旧名。
+- 后续宿主生成优先使用规范名。
+
+### Phase 3：Skill 瘦身与宿主工具映射
+
+目标：减少 Skill 主体中的 Claude-only 工具表达。
+
+改动：
+
+- 新增 `skills/using-webnovel-writer/`。
+- 把跨宿主工具映射放到 references。
+- 保留 Claude Code 示例中的 `${CLAUDE_PLUGIN_ROOT}`。
+- 不把每个宿主的完整说明复制进 8 个业务 Skill。
+
+影响：
+
+- Skill 更短，更容易被不同宿主消费。
+- 当前 Claude Code 命令不变。
+
+### Phase 4：生成器与 drift check
+
+目标：让非 Claude adapter 可生成、可检查。
+
+改动：
+
+- 新增 `scripts/generate_host_artifacts.py`。
+- 生成 `dist/<host>/webnovel-writer/`。
+- 扩展 `validate_plugin_package.py` 检查 adapter。
+- CI 增加 drift check。
+
+影响：
+
+- 新增开发工具，不改变用户项目数据。
+- 生成文件默认不提交。
+
+### Phase 5：跨宿主 smoke 与行为 eval
+
+目标：证明“能发现、能体检、能执行核心流程或明确降级”。
+
+改动：
+
+- 扩展 `run_behavior_evals.py`。
+- 每个宿主至少有 discover / project-status / doctor smoke。
+- 至少一个非 Claude 宿主完成 `webnovel-write` 兼容模式验收。
+
+影响：
+
+- 发布前检查时间增加。
+- 适配声明更可信。
+
+### Phase 6：发布文档与版本治理
+
+目标：用户知道哪个宿主支持到什么程度。
+
+改动：
+
+- README 增加多宿主支持表。
+- `docs/guides/commands.md` 增加非 Claude 使用口径。
+- `docs/operations/plugin-release.md` 增加 adapter 发布检查。
+- release note 明确每个宿主支持等级。
+
+影响：
+
+- 避免用户误以为所有宿主都已完整支持。
+- 降低 issue 中的环境误解。
+
+---
+
+## 15. 风险与控制
+
+| 风险 | 影响 | 控制 |
+|---|---|---|
+| 外部宿主能力描述过期 | spec 很快失真 | 每个 adapter 用 `support.md` 记录官方核验日期和链接 |
+| 为每个宿主复制业务流程 | 逻辑漂移 | adapter 只调 `webnovel.py`，不复制 runtime |
+| 重命名 Agent 破坏旧流程 | 现有用户调用失败 | 旧名兼容一个小版本周期以上 |
+| hook 被误当业务流程 | 隐藏副作用 | hook 只做状态提示和危险写入兜底 |
+| Skill 主体继续膨胀 | token 消耗高 | 详细内容下沉 references，确定性动作下沉 scripts |
+| 生成产物漂移 | 发布包和源不一致 | `generate_host_artifacts.py --check` |
+| Windows 中文路径失败 | 用户无法运行 | 所有新增 Python I/O 使用 UTF-8，命令用 `python -X utf8` |
+
+---
+
+## 16. 验收清单
+
+最终完成时必须满足：
+
+- [ ] Claude Code 原安装流程不破坏。
+- [ ] 8 个现有 Skill 仍可发现。
+- [ ] `/webnovel-doctor` 保留并进入多宿主自检路径。
+- [ ] 当前 hooks 保持 plugin-dev wrapper 格式。
+- [ ] `project-status`、`doctor`、`write-gate`、`projections` 都是跨宿主共享 runtime 入口。
+- [ ] `status` 仍保留旧宏观健康报告语义。
+- [ ] Agent 规范名有 `webnovel-` 前缀，旧名有兼容映射。
+- [ ] 每个 adapter 都有 `support.md`，包含官方文档核验日期和链接。
+- [ ] 每个 adapter 都有 smoke 命令或明确阻断原因。
+- [ ] 生成器可生成非 Claude 宿主产物。
+- [ ] drift check 能发现生成产物不一致。
+- [ ] package validator 覆盖 adapter registry、support.md 和 manifest 漂移。
+- [ ] behavior eval 覆盖 8 个 Skill 和至少一个非 Claude 兼容写作流程。
+- [ ] README 和 release note 明确每个宿主的支持等级。
+
+---
+
+## 17. 简短结论
+
+这次多宿主适配的核心不是“再写一套插件”，而是：
+
+- 保住当前 `v6.1.0` 已经做好的 runtime 基线。
+- 把 Claude Code 作为第一宿主继续维护。
+- 用 adapter 和生成器把同一套能力暴露给其他宿主。
+- 用 doctor、project-status、write-gate、projection log 和 eval 证明它真的能用。
+
+这样改，后续扩展宿主时不会把项目重新打散，也不会让用户在多个看起来相似、实际语义不同的入口里迷路。