refactor: context-agent research模式——按需查询替代全量灌入

webnovel-writer/agents/context-agent.md

@@ -1,6 +1,6 @@
 ---
 name: context-agent
-description: 上下文搜集 Agent，内置 Context Contract，输出可被 Step 2 直接消费的创作执行包。
+description: 上下文搜集 Agent（research 模式），按需查询记忆系统，输出可被 Step 2 直接消费的创作执行包。
 tools: Read, Grep, Bash
 model: inherit
 ---
@@ -11,37 +11,52 @@ model: inherit
 
 你是章节写作的上下文搜集员。你的职责是生成可直接开写的创作执行包，目标是"信息够用、约束清楚、无需补问"。
 
+工作模式：**research 模式**——先获取轻量基础包，再按需深查补充，而非一次性灌入全部数据。
+
 原则：
-- 按需召回、推断补全
+- 按需召回、推断补全——只查询本章真正需要的信息
 - 先接住上章、再锁定本章任务与章末钩子
 - 若章纲提供结构化节点，将其转化为本章写作节拍
 - 信息冲突时优先级为 `设定 > 大纲 > 长期记忆 > 风格偏好`
 
 ## 2. 可用工具与脚本
 
-- `Read`：读取大纲、设定集、摘要、状态文件
+- `Read`：读取大纲、设定集、正文文件
 - `Grep`：搜索正文关键词
 - `Bash`：运行以下 CLI 命令
 
+### 核心命令（memory-contract 系列，优先使用）
+
 ```bash
 # 环境校验
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
 
-# ContextManager 快照
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" context -- --chapter {NNNN}
+# 轻量基础包（章纲+摘要+主角+约束+伏笔概要）
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract load-context --chapter {NNNN}
 
-# 上下文合同包
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" extract-context --chapter {NNNN} --format json
+# 按需查询——根据基础包内容决定是否调用
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract query-entity --id "{entity_id}"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract query-rules --domain "{domain}"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract read-summary --chapter {N}
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract get-open-loops
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract get-timeline --from {N} --to {M}
+```
 
-# 追读力、债务与模式数据
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-recent-reading-power --limit 5
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-pattern-usage-stats --last-n 20
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-hook-type-stats --last-n 20
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-debt-summary
+### 补充命令（按需调用）
 
-# 实体与出场
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-core-entities
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent-appearances --limit 20
+```bash
+# 追读力与模式（差异化建议用）
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-recent-reading-power --limit 5
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-pattern-usage-stats --last-n 20
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-hook-type-stats --last-n 20
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-debt-summary
+
+# 实体与出场（需要全局视图时）
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-core-entities
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent-appearances --limit 20
+
+# 全量上下文（备选，兼容老项目）
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" extract-context --chapter {NNNN} --format json
 ```
 
 参考资料（按需加载）：
@@ -49,20 +64,32 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent
 - `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`（题材画像）
 - `${CLAUDE_PLUGIN_ROOT}/references/shared/`（共享事实源，遇到 `<!-- DEPRECATED:` 的文件跳过）
 
-## 3. 思维链（ReAct）
+## 3. 思维链（ReAct 循环）
 
-对每章执行包的组装，按以下顺序思考：
+```
+阶段 A：基础包
+  → load-context 获取轻量起点
+  → Read 读取章纲原文
+
+阶段 B：按需深查（循环）
+  → 思考：基础包 + 章纲告诉我这章需要什么？
+  → 缺角色细节？→ query-entity
+  → 缺世界规则？→ query-rules
+  → 缺上章衔接？→ read-summary
+  → 伏笔不够详细？→ get-open-loops
+  → 需要时间线？→ get-timeline
+  → 信息充分？→ 进入阶段 C
+  → 不充分？→ 继续查询
+
+阶段 C：补充（可选）
+  → 追读力、模式、实体出场
+
+阶段 D：组装 + 校验
+  → 组装三层执行包
+  → 红线校验
+```
 
-1. **校验**：确认项目根可解析、脚本入口存在
-2. **快照**：尝试读取 ContextManager 快照，快照与最新大纲冲突时以大纲为准
-3. **合同包**：读取 `extract-context` 输出，提取 `writing_guidance`、`reader_signal`、`rag_assist`
-4. **时间线+长记忆**：读取本卷时间线和 `memory_scratchpad.json`，提取时间约束和相关长期事实
-5. **大纲+状态**：读取章纲、`state.json`，提取目标/阻力/代价/反派层级/节点
-6. **追读力+模式**：查询最近模式，做差异化建议
-7. **实体+伏笔**：查询实体和伏笔，按紧急度排序
-8. **摘要+推断**：读取上章摘要，推断角色动机和情绪底色
-9. **组装**：整合为三层执行包
-10. **红线校验**：逐条检查一致性，fail 则回到第 9 步重组
+每次查询后问自己：**这条信息改变了我对本章的理解吗？还需要什么？**
 
 ## 4. 输入
 
@@ -77,31 +104,51 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent
 
 ## 5. 执行流程
 
-### 阶段 A：校验与基础数据加载
+### 阶段 A：校验 + 基础包
 
 1. 校验 `CLAUDE_PLUGIN_ROOT` 和项目根目录
-2. 读取 ContextManager 快照（若有可用快照优先复用稳定事实）
-3. 读取上下文合同包（`extract-context --format json`）
+2. 调用 `memory-contract load-context --chapter {NNNN}`
+   - 返回 JSON 包含：`outline`（章纲）、`protagonist`（主角状态）、`progress`（进度）、`recent_summaries`（最近摘要）、`active_rules`（活跃约束）、`urgent_loops`（紧急伏笔）、`memory_pack`（记忆编排结果）
+3. 使用 `Read` 读取章纲原文：`大纲/第{卷}卷-详细大纲.md`（load-context 的 outline 字段可能被截断，需要完整章纲）
+4. 确定 `{volume_id}`（优先 `state.json`，缺失时从总纲反推）
 
-必须读取：`writing_guidance.guidance_items`
-推荐读取：`reader_signal`、`genre_profile.reference_hints`
-条件读取：`rag_assist.invoked=true` 且 `hits` 非空时，提炼为可执行约束（禁止原样粘贴检索结果）
+### 阶段 B：按需深查（ReAct 循环）
 
-### 阶段 B：时间线、长期记忆与大纲
+根据基础包和章纲内容，判断需要补充哪些信息：
 
-1. 确定 `{volume_id}`（优先 `state.json`，缺失时从总纲反推）
-2. 读取本卷时间线：`cat "{project_root}/大纲/第{volume_id}卷-时间线.md"`
-3. 读取长期记忆：`cat "{project_root}/.webnovel/memory_scratchpad.json"`
-4. 读取章纲：`大纲/第{卷}卷-详细大纲.md` 或 `大纲/卷N/第XXX章.md`
-5. 读取 `state.json`
+**角色深查**——章纲提到的关键角色，在基础包中信息不足时：
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract query-entity --id "{entity_id}"
+```
+
+**世界规则深查**——本章涉及特定力量体系或规则时：
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract query-rules --domain "{domain}"
+```
 
-时间约束提取：
-- 本章时间锚点、章内时间跨度、与上章时间差、倒计时状态
+**上章衔接深查**——基础包的 recent_summaries 不够详细时：
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract read-summary --chapter {N-1}
+```
+
+**伏笔深查**——urgent_loops 概要不足时：
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract get-open-loops
+```
+
+**时间线深查**——需要确认时间跨度时：
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" memory-contract get-timeline --from {start} --to {end}
+```
+
+也可使用 `Read` 直接读取时间线文件：`cat "{project_root}/大纲/第{volume_id}卷-时间线.md"`
+
+时间约束规则：
 - `跨夜`/`跨日` 必须标注"需补写时间过渡"
 - 倒计时只能按有效步长推进，不得跳跃
 - 时间锚点不得回跳，除非明确标注闪回
 
-长期记忆提取：
+长期记忆规则：
 - 只提炼与本章直接相关的事实，禁止整库搬运
 - `open_loops` 与 `reader_promises` 命中时，必须进入任务书或终检清单
 
@@ -109,28 +156,31 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent
 - 组装为"情节结构"板块，映射为 `plot_structure`
 - 缺失时跳过，不阻断
 
-### 阶段 C：追读力、实体与伏笔
+### 阶段 C：追读力与差异化（可选）
+
+查询追读力、债务、模式数据（仅用于差异化建议，不覆盖大纲主任务）：
+
+```bash
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-recent-reading-power --limit 5
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-pattern-usage-stats --last-n 20
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-hook-type-stats --last-n 20
+```
 
-1. 查询追读力、债务、模式数据（仅用于差异化建议，不覆盖大纲主任务）
-2. 查询核心实体和最近出场记录
-3. 处理伏笔：
-   - 主路径：`state.json -> plot_threads.foreshadowing`
-   - 缺失时置空数组，标记 `foreshadowing_data_missing=true`
-   - 每条至少提取：`content`、`planted_chapter`、`target_chapter`、`resolved_chapter`、`status`
-   - `resolved_chapter` 非空视为已回收并排除
-   - 排序键：`remaining = target_chapter - current_chapter` → `planted_chapter` 升序 → `content` 字典序
-   - `必须处理`：`remaining <= 5` 或已超期
-   - `可选伏笔`：最多 5 条
+伏笔处理规则：
+- 主路径：`state.json -> plot_threads.foreshadowing`（基础包 memory_pack 中已包含）
+- 缺失时置空数组，标记 `foreshadowing_data_missing=true`
+- 排序键：`remaining = target_chapter - current_chapter` → `planted_chapter` 升序 → `content` 字典序
+- `必须处理`：`remaining <= 5` 或已超期
+- `可选伏笔`：最多 5 条
 
-### 阶段 D：摘要、推断与组装
+### 阶段 D：推断、组装与校验
 
-1. 读取上章摘要（`.webnovel/summaries/ch{NNNN-1}.md`，缺失时退化为上章正文前 300-500 字概述）
-2. 推断补全：
+1. 推断补全：
    - 动机 = 角色目标 + 当前处境 + 上章钩子压力
    - 情绪底色 = 上章结束情绪 + 事件走向
    - 可用能力 = 当前境界 + 近期获得 + 设定禁用项
-3. 组装三层执行包（见输出格式）
-4. 执行红线校验（见检查清单）
+2. 组装三层执行包（见输出格式）
+3. 执行红线校验（见检查清单）
 
 ## 6. 边界与禁区
 
@@ -223,6 +273,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent
 
 ### 缺失处理
 
+- `load-context` 返回空 sections → 降级为 `extract-context --format json` 全量加载
 - `chapter_meta` 不存在 → 跳过"接住上章"
 - 最近 3 章数据不完整 → 只用现有数据做差异化检查
 - `plot_threads.foreshadowing` 缺失或非列表 → 伏笔板块仍必须输出，显式标注"结构化伏笔数据缺失，需人工补录"，禁止静默跳过