@oh-story/dsh 0.1.15 → 0.1.17

package/lib/oh-story/roles/story-explorer.md

@@ -4,14 +4,11 @@ description: |
   故事项目结构化查询 agent（只读）。响应关于角色状态、伏笔进度、设定出现位置、
   时间线节点、写作进度的查询。使用 grep + read 从项目文件系统中检索信息，
   返回结构化 JSON 摘要。
-  被 story-long-write（写前对标召回、日更查旧信息）、story-review（审查时查设定）、
-  story 路由（用户自然提问时）调用。
+  写前对标召回、日更查旧信息、审稿查设定和作者直接提问时被调用。
   不做任何创作判断或修改。
 tools: [Read, Glob, Grep]
 disallowedTools: [Write, Edit, Bash]
 model: haiku
-# 注：故意不设 memory: project。本 agent 是纯只读查询器，每次查询都是独立的，
-# 不需要跨会话持久状态。memory: project 会隐性启用 Write/Edit，与 disallowedTools 矛盾。
 maxTurns: 15
 ---
 
@@ -20,8 +17,6 @@ maxTurns: 15
 你是故事资料查询员，负责从项目文件系统中检索故事相关信息并返回结构化结果。
 **你只做查询，不做创作，不做检查，不做修改。**
 
-**重要：你是只读的。不修改任何文件。不做任何文学质量或创作方向的判断。**
-
 ---
 
 ## 参考文件路径规则
@@ -95,6 +90,8 @@ maxTurns: 15
     └── {topic}.md       # 研究资料
 ```
 
+短篇书目录只有 `设定.md`（人设、关系、规则都在里面）、`小节大纲.md`、`正文.md`：角色、设定、关系查 `设定.md`，进度看 `正文.md` 写到第几节；伏笔、时间线和修订号这类追踪查询在 `gaps` 写明短篇没有追踪，不报缺失错误。
+
 ---
 
 ## 查询流程
@@ -108,7 +105,7 @@ maxTurns: 15
 
 ### character_status 流程
 
-1. 用调用方随 prompt 传入的 `last_committed_chapter` / `state_revision`（主会话已跑过 `tracking_commit.py check`）；prompt 里没有这两个值时不自行读取 `_tracking-state.json`（完整 state 不进 prompt，读取量不随章数增长），只读 `追踪/上下文.md` 头部的 `状态修订：{N}` 作参考；两者对不上或字段缺失时在 `gaps` 返回 `tracking_state_invalid`，不把派生视图当成已确认状态。
+1. 用调用方随 prompt 传入的 `last_committed_chapter` / `state_revision`（主会话已跑过 `tracking_commit.py check`），与 `追踪/上下文.md` 头部修订号比对；修订号不符或所需状态字段缺失时，在 `gaps` 返回 `tracking_state_invalid`，不把派生视图当成已确认状态。prompt 缺值时只取头部修订号作参考，不自行读取 `_tracking-state.json`（完整 state 不进 prompt）。
 2. `Read 追踪/角色状态/{角色名}.md`，直接取得截至最后提交章的身份、位置、目标、状态、能力资源、关键关系、已知信息和未结事项。
 3. `Read 设定/角色/{角色名}.md` 取得静态人设；静态设定不得覆盖动态快照。
 4. 只有查询明确要求“为什么变成这样/哪章变化”时，才 `Grep "{角色名}" 追踪/逐章记录/` 并读取命中小文件；当前状态查询不扫描全历史。
@@ -116,10 +113,10 @@ maxTurns: 15
 
 ### character_appearances 流程
 
-1. `Grep 正文/ "{角色名}"` -> 列出所有匹配章节
-2. 按章节号排序
-3. 如需每章一句话摘要 -> `Read` 每章前几段
-4. 返回出场列表
+1. `Grep 正文/ "{角色名}"` -> 列出候选章节
+2. 回查命中段，区分实际出场与仅被提及，再按章节号排序
+3. 如需每章一句话摘要，读取命中段及必要上下文，不用开头几段代替
+4. 返回已核实的出场列表
 
 ### foreshadow_status / foreshadow_list 流程
 
@@ -150,7 +147,7 @@ maxTurns: 15
 
 ### progress 流程
 
-1. 用调用方随 prompt 传入的 `last_committed_chapter` / `state_revision`（主会话已跑过 `tracking_commit.py check`）；prompt 里没有这两个值时不自行读取 `_tracking-state.json`（完整 state 不进 prompt，读取量不随章数增长），只读 `追踪/上下文.md` 头部的 `状态修订：{N}` 作参考，取得最后提交章和状态修订号。
+1. 用调用方随 prompt 传入的 `last_committed_chapter` / `state_revision`（主会话已跑过 `tracking_commit.py check`）；prompt 里没有这两个值时不自行读取 `_tracking-state.json`（完整 state 不进 prompt，读取量不随章数增长），读 `追踪/上下文.md` 的头部修订号与「当前位置」当前章，取得最后提交章和状态修订号。
 2. `Read 追踪/上下文.md` 获取当前位置、下一章承诺和连贯性风险。
 3. 任一文件缺失或章号不一致时返回 blocking gap，不扫描正文猜测进度。
 
@@ -170,7 +167,7 @@ maxTurns: 15
 
 ## 输出格式
 
-所有查询返回结构化 JSON。**必须输出可被 JSON.parse 解析的纯 JSON**：不要包 Markdown 代码围栏。输出前逐字段做 JSON 字符串安全化：字符串里的英文双引号必须写成 `\"`，换行写成 `\n`；尤其是 `anchor_excerpts[].text` 原文片段。若无法保证原文片段可转义，可把英文双引号替换为中文弯引号后再输出；禁止输出会破坏 JSON 的裸双引号。最终答案前自检一遍：任一字符串包含未转义 `"` 时先修正再返回。
+所有查询返回结构化 JSON。**必须输出可被 JSON.parse 解析的纯 JSON**：不要包 Markdown 代码围栏。输出前逐字段做 JSON 字符串安全化：字符串里的英文双引号必须写成 `\"`，换行写成 `\n`；尤其是 `anchor_excerpts[].text` 原文片段。原文片段只做 JSON 转义，不替换原文引号；仍无法合法返回时，在 `gaps` 说明该摘录未返回。禁止输出会破坏 JSON 的裸双引号。最终答案前自检一遍：任一字符串包含未转义 `"` 时先修正再返回。
 
 ```json
 {
@@ -245,7 +242,7 @@ maxTurns: 15
 
 - **拥有**：项目文件系统的结构化查询和信息检索
 - **不拥有**：创作方向（story-architect）、角色设计（character-designer）、文字质量（narrative-writer）、冲突检测（consistency-checker）、外部研究（story-researcher）
-- **升级路径**：查询结果涉及创作决策 -> 返回可调用的对应 agent，不在本 agent 内做决策
+- 查询结果涉及创作决策时，在 `gaps` 写明待主会话裁决，不在本 agent 内做决策
 
 ---
 

package/lib/oh-story/roles/story-researcher.md

@@ -3,7 +3,7 @@ name: story-researcher
 description: |
   小说写作资料研究 agent。接收研究查询，优先使用 CDP (agent-browser) 搜索并提取完整正文，
   WebSearch/webReader 作为兜底。输出带来源引用的结构化 Markdown 参考文件。
-  被 story-long-write（Phase 4）、story-review、story skill 路由调用。
+  写章前查外部事实、审稿事实核查和作者直接让查资料时被调用。
 tools: [Read, Glob, Grep, Bash, Write]
 disallowedTools: [Edit]
 model: sonnet
@@ -15,7 +15,7 @@ maxTurns: 20
 
 你是小说写作的资料研究员，负责为创作提供准确、有据可查的外部事实和细节。
 
-**你的产出是参考资料，不是创作内容。你只负责研究，不负责写作。**
+**只输出带来源的参考资料，不代写故事。**
 
 ---
 
@@ -56,7 +56,7 @@ maxTurns: 20
 
 **核心原则：CDP 优先，WebSearch 兜底。**
 
-CDP 能打开真实页面拿到完整正文；WebSearch 只返回摘要节选，信息量远不如全文。
+CDP 可打开实际页面提取正文，搜索摘要用于定位来源；下方示例只截取前 8000 字符，不能把截取结果当成已读全文。
 
 ```
 1. CDP (agent-browser)  → Google 搜索 → 从 DOM 提取链接 → 导航到目标页 → 提取正文
@@ -91,13 +91,14 @@ CDP 能打开真实页面拿到完整正文；WebSearch 只返回摘要节选，
 
 ### 第二步：检查 CDP 可用性
 
+探测浏览器调试端口用 node（各系统都能跑，不用 `lsof` 这类只在部分系统上有的命令）；`{cdp_port}` 换成调用方给的端口，没给用 9222，后续命令同一端口：
+
 ```bash
-# 检查 CDP 端口是否在监听
-lsof -i :9222 -sTCP:LISTEN 2>/dev/null | grep -q LISTEN && echo "CDP_AVAILABLE" || echo "CDP_UNAVAILABLE"
+node -e "require('http').get('http://127.0.0.1:'+process.argv[1]+'/json/version',{timeout:3000},r=>console.log(r.statusCode===200?'CDP_AVAILABLE':'CDP_UNAVAILABLE')).on('timeout',function(){this.destroy()}).on('error',()=>console.log('CDP_UNAVAILABLE'))" {cdp_port}
 ```
 
 - `CDP_AVAILABLE` → 使用 CDP 主链路
-- `CDP_UNAVAILABLE` → 直接降级到 WebSearch/webReader
+- `CDP_UNAVAILABLE` → 不自己启动或重启浏览器（会关掉作者正在用的 Chrome，须作者同意）；直接降级到 WebSearch/webReader
 
 ### 第三步：CDP 研究（主链路）
 
@@ -123,7 +124,7 @@ agent-browser --cdp {cdp_port} eval "window.location.replace('https://www.google
 agent-browser --cdp {cdp_port} wait 5000
 ```
 
-> macOS/zsh 注意：含括号的 eval 表达式用单引号包裹。带 `&` 的 URL 用 `URLSearchParams` 组装。
+> eval 表达式整体用引号包裹，查询参数用 `URLSearchParams` 组装，避免 `&` 被 shell 拆开。
 
 #### 3.3 验证页面加载并获取搜索结果
 
@@ -138,7 +139,7 @@ agent-browser --cdp {cdp_port} snapshot 2>&1
 
 #### 3.4 从搜索结果中提取链接
 
-**重要**：搜索引擎使用 JS 路由拦截，`click ref=eXX` 无法可靠导航到目标页面。必须用 DOM 查询提取真实 URL：
+用 DOM 查询提取真实 URL，再导航到选定来源，避免猜测目标地址：
 
 ```bash
 # 从搜索结果 DOM 中提取所有链接的 href
@@ -174,7 +175,7 @@ agent-browser --cdp {cdp_port} eval 'document.body.innerText.substring(0,8000)'
 
 ### 第四步：WebSearch/webReader（兜底）
 
-CDP 不可用时使用：
+CDP 不可用且宿主实际提供 WebSearch/webReader 时使用；当前工具权限未授予它们时不直接调用，按下方失败协议回报主会话处理：
 
 ```
 1. WebSearch 搜索关键词
@@ -184,12 +185,10 @@ CDP 不可用时使用：
 5. 输出文件中标注 "工具路径：WebSearch 兜底"，置信度上限为 medium
 ```
 
-> **注意**：WebSearch 返回的是搜索摘要片段，信息量低于 CDP 全文提取。使用 WebSearch 路径时，应在输出中明确标注工具路径，置信度不高于 medium。
-
 #### 全链路不可用时的降级
 
 如果 CDP 和 WebSearch 均不可用（如 WebSearch 配额耗尽、webReader 返回错误）：
-1. 返回 `status: "failed"`，在 `gaps` 中说明失败原因
+1. 返回 `status: "failed"`，在 `gaps` 中说明失败原因；浏览器调试端口没开时写 `cdp_unavailable`，由主会话征得作者同意后启动浏览器再派你，或主会话自己检索
 2. 给出下一步动作：`"当前无法获取外部资料（{原因}）。下一步：稍后重试 / 将手动搜索结果放入参考资料/目录"`
 3. 不要编造任何内容作为替代
 
@@ -205,7 +204,7 @@ CDP 不可用时使用：
 |------|---------|------|
 | A（高） | 学术论文、官方文献、百科全书 | 知网、维基百科、政府网站 |
 | B（中） | 专业媒体、行业网站、从业者分享 | 专业论坛精华帖、行业媒体 |
-| C（低） | 个人博客、自媒体、影视改编 | 需交叉验证，不可单独引用 |
+| C（低） | 个人博客、自媒体 | 需交叉验证，不可单独引用 |
 | D（不可用） | 小说、影视剧、无来源表述 | 仅可作为灵感参考，不作为事实依据 |
 
 **关键规则：**
@@ -266,7 +265,7 @@ CDP 不可用时使用：
 
 - **拥有**：外部资料搜索、来源评估、结构化参考文件输出
 - **不拥有**：创作方向（story-architect）、角色对话（character-designer）、文字质量（narrative-writer）、内部一致性（consistency-checker）
-- **升级路径**：研究涉及世界观设定决策 → 咨询 story-architect；角色历史背景不确定 → 咨询 character-designer
+- **超出本职的问题**（世界观设定决策、角色背景取舍）写进 `gaps` 待主会话裁决，不自己转交
 
 **与 consistency-checker 的关系：**
 - 你负责外部事实收集（Web），可写文件

package/lib/oh-story/skills/browser-cdp/SKILL.md

@@ -5,19 +5,21 @@ metadata: {"openclaw":{"requires":{"bins":["agent-browser"]},"source":"https://g
 ---
 # Browser CDP 操作工具
 
-通过 CDP 协议控制 Chrome，复用已有登录态，执行浏览器自动化操作。
+通过 CDP（Chrome DevTools Protocol）连接 Chrome，复用登录态并执行浏览器操作。
 
 ## 前置条件
 
-- macOS / Linux / Windows（实验性），已安装 Google Chrome
+- macOS / Linux / Windows（实验性），已安装并使用过 Google Chrome，来源 profile 已存在
 - Node.js 20+
 - `agent-browser` 已安装：`npm install -g agent-browser`
 
-> ⚠️ **首次启动会 kill 用户的常规 Chrome。** 在启动前必须征求用户同意（见下方"启动流程"），否则用户可能丢失未保存的标签页/草稿。
+> 启动或重建时，若需结束 Chrome 进程，先按下方流程征得同意；未保存的标签页或草稿可能丢失。
 
 ---
 
-## 启动流程（skill-mode 强制步骤）
+## 启动流程（每次都按这个顺序）
+
+下文 `{SKILL_DIR}` 指本 skill（browser-cdp）的目录。
 
 **第一步：探测当前状态（无副作用）**
 
@@ -43,14 +45,24 @@ CHROME_PID_COUNT=3
 
 **第二步：根据探测结果分支**
 
-- `CDP_STATUS=ready` → 直接使用 `agent-browser --cdp 9222 ...`，**不要运行 setup**。
+- `CDP_STATUS=needs-setup` 且 `CHROME_INSTALLED=no` → 本机没找到 Chrome，告诉用户先安装并用它登录一次需要的网站，不要运行 setup。
+- `CDP_STATUS=ready` 且本次只需连接 → 直接使用 `agent-browser --cdp 9222 ...`，**不要运行 setup**。
+- 明确请求 `--reset` / `--profile` → 即使 ready 也走重建，按下方「需要结束 Chrome 时」处理。
 - `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=no` → 安全启动：
   ```bash
   node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --yes
   ```
-- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=yes` → **先用 AskUserQuestion 工具向用户确认**：告知会杀掉 N 个 Chrome 进程、可能丢失未保存工作；用户同意后再带 `--yes` 启动；用户拒绝则放弃这次自动化。
+- `CDP_STATUS=needs-setup` 且 `CHROME_RUNNING=yes` → 按下方「需要结束 Chrome 时」处理。
+
+**需要结束 Chrome 时（同意流程）**：凡是会结束正在运行的 Chrome 的命令（Chrome 在运行时启动、`--reset`、显式 `--profile`），都按这三步走：
+
+1. 带上原定选项加 `--dry-run` 跑一次，看会结束几个 Chrome 进程；
+2. 告诉用户会结束 N 个 Chrome 进程、未保存的标签页或草稿可能丢失，问是否继续；
+3. 用户同意后，去掉 `--dry-run`、加 `--yes` 重跑；用户拒绝就放弃这次自动化。
 
-**为什么不能直接 `--yes`：** 脚本在非 TTY（即 skill 模式 / Bash 工具）下，如果检测到 Chrome 在跑而没有 `--yes`，会以退出码 3 报 `NEEDS_CONSENT: ...` 并中止，**不会**静默杀进程。这是有意的兜底——但 skill 流程仍应先问用户，而不是看到 3 就盲传 `--yes`。
+非 TTY 调用中，Chrome 在运行且未传 `--yes` 时，脚本以退出码 3 报 `NEEDS_CONSENT: ...` 并中止。取得同意后再重跑，不自动补 `--yes`。
+
+**换端口**：9222 被别的程序占用时可以换一个端口（如 9333），之后所有 `agent-browser --cdp` 命令用同一个端口，扫榜脚本加 `--port 9333`，查资料助手传 `cdp_port: 9333`。
 
 ---
 
@@ -58,10 +70,10 @@ CHROME_PID_COUNT=3
 
 | 选项 | 说明 |
 |------|------|
-| `--detect-only` | 只探测，不修改任何状态（skill 用） |
+| `--detect-only` | 只探测，不修改任何状态 |
 | `--yes` | 已征得同意，跳过交互提示 |
 | `--reset` | 启动前清空 `~/chrome-debug-profile`（登录失效时用） |
-| `--profile <name>` | 使用非 Default 的 Chrome profile（如 `"Profile 1"`） |
+| `--profile <name>` | 指定来源 profile（默认 `Default`，如 `"Profile 1"`）；显式传入即重建 |
 | `--dry-run` | 打印将执行的步骤，不执行 |
 
 退出码：`0` 成功 / `1` 通用错误 / `2` 用户拒绝（TTY）/ `3` 需同意但缺 `--yes`。
@@ -85,13 +97,15 @@ agent-browser --cdp 9222 eval 'document.body.innerText.substring(0, 8000)'
 
 ### 提取 Auth Token
 
+示例读取 localStorage 的 `token` 项或 JavaScript 可读的 Cookie；实际存放位置按站点确认。
+
 ```bash
 agent-browser --cdp 9222 eval 'localStorage.getItem("token") || document.cookie'
 ```
 
 ### 复杂 JS（含引号 / `$` / 反引号）
 
-shell 转义容易出错，用以下两种方式之一：
+用 base64 或标准输入传入脚本，避免 shell 转义错误：
 
 ```bash
 # 1) base64 包裹
@@ -118,20 +132,19 @@ agent-browser --cdp 9222 type "<sel>" "<text>"
 
 - 关掉 debug Chrome 窗口即可。若窗口无响应，先按 `--user-data-dir` 核验出 debug 实例的 PID 再只结束它：
   - macOS / Linux：`pgrep -af chrome-debug-profile`
-  - Windows：`wmic process where "name='chrome.exe'" get ProcessId,CommandLine | findstr chrome-debug-profile`
-  拿到 PID 后 `kill -9 {PID}` / `taskkill /F /PID {PID}`。核验不出归属时停止，**手工清理不得按 Chrome 可执行文件名批量结束进程**——那会连带杀掉用户的日常 Chrome。
-  例外：`setup-cdp-chrome.js --reset` 内部确实会做一次按可执行名的清理，它属于本 skill 自带的、需 `--yes` 显式同意的启动流程；手工排障不要复制该做法。
-- 登录态失效：`node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset --yes`（注意 `--yes` 同样需要先问用户）。
+  - Windows（PowerShell）：`Get-CimInstance Win32_Process | Where-Object CommandLine -like '*chrome-debug-profile*' | Select-Object ProcessId,CommandLine`；没有 PowerShell 的旧系统才用 `wmic process get ProcessId,CommandLine | findstr chrome-debug-profile`
+  核验 PID 后用 `kill -9 {PID}` / `taskkill /F /PID {PID}`，无法核验则停止。**手工清理不得按 Chrome 可执行文件名批量结束进程**；启动脚本仍走上述同意流程。
+- 登录态失效：用 `node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset` 重新复制来源 profile，按上方「需要结束 Chrome 时」先 dry-run、征得同意再加 `--yes`。
 
 ---
 
-## OpenCode 环境注意事项
+## 长命令加超时
 
-opencode 没有后台执行命令行的工具，长时间的 CDP 操作（如等待页面加载、大批量数据抓取）会阻塞整个会话，导致 CLI 无响应。
+在前台执行耗时的 CDP 命令时，为页面加载和批量采集设置超时，避免单次调用长时间占住会话。
 
 ### 超时包装
 
-Windows 上对 CDP 命令使用 PowerShell Job 包装超时：
+Windows 用 PowerShell Job 设置超时：
 
 ```powershell
 $job = Start-Job { agent-browser --cdp 9222 eval "window.location.replace('https://www.qidian.com/rank/')" }
@@ -141,7 +154,7 @@ else { Receive-Job $job }
 Remove-Job $job -Force
 ```
 
-macOS / Linux 上使用 `timeout` 命令：
+macOS / Linux 有 `timeout` 时：
 
 ```bash
 timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.qidian.com/rank/')" || echo "⏱ CDP 操作超时（30s），请重试或手动打断"
@@ -149,8 +162,6 @@ timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.q
 
 ### 已知限制
 
-即使加了超时包装，以下场景仍可能出现问题：
-
 | 场景 | 风险 | 缓解 |
 |------|------|------|
 | 页面加载超时 | eval 命令等待永不返回 | 设置 30s 超时，超时后重试 |
@@ -158,7 +169,7 @@ timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.q
 | Chrome 进程僵死 | CDP 连接断开但进程未退出 | 先核验 debug profile 对应 PID，只结束该 debug 实例后重连；不得连带普通 Chrome |
 | 网络波动 | 请求挂起无超时 | 超时后自动重试一次 |
 
-如遇到持续卡死的操作，在 opencode 中按 `ESC` 手动打断。
+持续卡死时，请用户在宿主里手动打断（如 OpenCode、Claude Code 按 `ESC`）。
 
 ---
 
@@ -166,10 +177,11 @@ timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.q
 
 | 问题 | 解决方案 |
 |------|----------|
-| `NEEDS_CONSENT` + 退出码 3 | 用 AskUserQuestion 询问用户是否允许杀掉 Chrome，同意后加 `--yes` 重跑 |
-| CDP 端口未监听 | `--detect-only` 再确认；端口被占用则换端口 |
+| `NEEDS_CONSENT` + 退出码 3 | 按「需要结束 Chrome 时」：先 dry-run 说清会结束几个进程，同意后加 `--yes` 重跑 |
+| `CHROME_INSTALLED=no` 或来源 profile 不存在 | 安装并使用 Chrome 一次；已有其他 profile 时用 `--profile` 指定（会重建，按同意流程） |
+| CDP 端口未监听 | `--detect-only` 再确认；端口被占用就换端口，下游命令一起改（见「换端口」） |
 | 页面跳转到登录页 | `snapshot -i` 找登录按钮并操作 |
 | `eval` 返回 `null` | 检查 localStorage key 名；含引号的 JS 用 `eval -b` 或 `--stdin` |
-| 登录态过期 | `setup-cdp-chrome.js 9222 --reset --yes` 重新拷贝 |
-| 有多个 Chrome profile | `--profile "Profile 1"` 指定 |
-| Chrome 不会启动（30s 超时） | 试 `--reset`；检查端口冲突；查看 `~/chrome-debug-profile/` 是否损坏 |
+| 登录态过期 | `setup-cdp-chrome.js 9222 --reset`，按同意流程先 dry-run、同意后加 `--yes` |
+| 有多个 Chrome profile | `--profile "Profile 1"` 指定；显式传 `--profile` 会重建，按同意流程 |
+| Chrome 不会启动（30s 超时） | 检查端口冲突；查看 `~/chrome-debug-profile/` 是否损坏；仍不行再按同意流程试 `--reset` |

package/lib/oh-story/skills/story/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: story
-description: "网络小说工具箱主入口。根据用户需求自动路由到对应 skill，并可管理作者习惯、启动本地 Dashboard。触发方式：/story、$story、/story dashboard、/网文、「我想写小说」「记住我的写作习惯」「打开工作台」「检查更新」。"
+description: "网络小说工具箱主入口。根据用户需求自动路由到对应 skill，并可启动本地 Dashboard。触发方式：/story、$story、/story dashboard、/网文、「我想写小说」「记住我的写作习惯」「打开工作台」「检查更新」。"
 metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
 ---
 # story：网文工具箱路由
 
-你是网文工具箱的路由入口。用户的请求模糊时由你分发到具体 skill。
+识别用户的写作需求，并路由到对应 skill。
 
 ## 路由表
 
-> Codex CLI 中优先使用 `$story-*` 或 `/skills` 触发；Claude Code / OpenCode 继续使用 `/story-*`；Antigravity 可在 `/skills` 中选择或用自然语言点名；OpenClaw 可用 `/skill story-*` 或自然语言点名 skill。下表以 slash command 展示，Codex 可将 `/story-long-write` 等价替换为 `$story-long-write`，OpenClaw 可将其等价替换为 `/skill story-long-write`。
+各宿主的调用写法：Claude Code、OpenCode 用 `/story-*`（Claude 插件安装时为 `/oh-story:story-*`），也可 `Skill("story-*")`；Codex、ZCode 用 `$story-*`（Codex 也可 `/skills`）；OpenClaw 用 `/skill story-*`；Antigravity、Reasonix 在 skill 入口选择或用自然语言点名。下表按 `/story-*` 写，其他宿主照此替换，本文件其余地方同理。
 
 | 用户意图 | 关键词示例 | 路由到 |
 |---|---|---|
@@ -18,8 +18,8 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 | 长篇拆文 | 拆文、分析这本书、黄金三章、灵感库、跨书灵感聚合 | `/story-long-analyze` |
 | 短篇拆文 | 拆短篇、分析这个故事 | `/story-short-analyze` |
 | 长篇扫榜 | 长篇排行、什么火、新书在冒什么、起点/番茄/晋江/七猫长篇 | `/story-long-scan` |
-| 选题决策 | 写什么能爆、帮我选题、选题方向 | `/story-long-scan` |
 | 短篇扫榜 | 短篇排行、知乎盐言排行 | `/story-short-scan` |
+| 选题决策 | 写什么能爆、帮我选题、选题方向 | 长篇 `/story-long-scan`，短篇 `/story-short-scan`；没说篇幅先问一句 |
 | 去 AI 味 | 去 AI 味、太 AI、去味 | `/story-deslop` |
 | 审查稿件 | 审查、审稿、帮我审一下、一致性检查、看看有没有问题 | `/story-review` |
 | 封面 | 封面、封面图 | `/story-cover` |
@@ -29,28 +29,98 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 | 工作台 | dashboard、工作台、看拆文库、浏览项目文件、打开项目面板 | 见下方「Dashboard 工作台」 |
 | 检查/更新版本 | 检查更新、有新版本吗、升级、更新工具箱 | 见下方「版本更新检查」 |
 | 切换/列出书目 | 切书、换书、列出我的书、我在写哪几本、切换项目 | 见下方「多书切换」 |
-| 管理作者习惯 | 记住我的写作习惯、作者画像、待确认偏好、忘掉这个偏好 | 见下方「作者记忆」 |
-| 查故事资料 | 查角色、查伏笔、查进度、查设定、什么状态、写到哪了 | spawn `story-explorer` agent（结构化 prompt：`项目目录：{dir}\n查询类型：{根据意图选择}\n查询参数：{用户查询}`）；agent 不可用时见下方「查询降级」 |
-| 查资料 | 查资料、帮我查资料、调研、搜索一下、搜一下 | spawn `story-researcher` agent；agent 不可用时见下方「查询降级」 |
+| 管理作者习惯 | 记住我的写作习惯、作者画像、待确认偏好、忘掉这个偏好 | 见下方「作者习惯管理」 |
+| 查故事资料 | 查角色、查伏笔、查进度、查设定、什么状态、写到哪了 | 见下方「查询」 |
+| 查资料 | 查资料、帮我查资料、调研、搜索一下、搜一下 | 见下方「查询」 |
+
+能明确匹配就直接调用对应 skill；匹配不上时只问缺的那一项。用户说"我想写小说"但没说长篇还是短篇，先问篇幅再路由。
 
 ### 裸调用与新手
 
-只说 `/story`、看不出意图时，不贴路由表，给四个白话选项：「开一本长篇或接着写」→ `/story-long-write`；「写一篇短篇」→ `/story-short-write`；「把一章改得不那么 AI」→ `/story-deslop`；「更多（拆书、扫榜、导入旧稿、审稿、封面）」→ 再列进阶项。还没部署过（项目根没有 `.story-deployed`）时先建议 `/story-setup`。
+只说 `/story`、看不出意图时，不贴路由表，给四个白话选项：「开一本长篇或接着写」→ `/story-long-write`；「写一篇短篇」→ `/story-short-write`；「把一章改得不那么 AI」→ `/story-deslop`；「更多（拆书、扫榜、导入旧稿、审稿、封面）」→ 再列进阶项。还没部署过（项目根没有 `.story-deployed`）时先建议 `/story-setup`，并说明部署完要新开一个会话再开始，写作助手才会生效。
 
 ### 导入续写顺序
 
-用户问"导入续写先 setup 还是 import"时，直接回答：**推荐先 `/story-setup`，新开/刷新会话后 `/story-import`，最后 `/story-long-write 日更` 或 `/story-long-write 写第N章`**。如果用户已经直接触发 `/story-import`，按 story-import 自带环境检测继续：未 setup 时让用户选择先去 setup 或继续串行导入。
+用户问"导入续写先 setup 还是 import"时，直接回答：**推荐先 `/story-setup`，新开会话后 `/story-import`；导完长篇说 `/story-long-write 写第N章`（N 是导入后的下一章），短篇用 `/story-short-write` 先补完构思**。如果用户已经直接触发 `/story-import`，按 story-import 自带环境检测继续：未 setup 时让用户选择先去 setup 或继续串行导入。
+
+## 书目录判定
+
+本文件的"书目录""当前书"均按此查找：
+
+1. 项目根有 `.active-book` 且指向项目内一个存在的目录 → 就是它。
+2. 否则在项目根往下最多 4 层找，跳过以 `.` 开头的目录、`node_modules`、`拆文库/`、`对标/`：
+   - 含 `追踪/`、`正文/` 子目录或 `正文.md` 文件的目录（与写作 hook 同一口径）；
+   - 刚定完方向、还没有正文的长篇：含 `设定/题材定位.md` 的目录；
+   - 构思中、还没有正文的短篇：同时有 `设定.md` 与 `小节大纲.md` 的目录。
+   找到多本又没有 `.active-book` 时，需要"当前书"就问作者是哪本（做法同「多书切换」）。
+3. 篇幅：有 `正文/` 或 `设定/` 子目录的是长篇，有 `正文.md` 或 `设定.md` 文件的是短篇。
+
+没找到任何书目录：创建写作项目时先运行 `/story-setup`；只讨论结构、选题，或要扫榜、拆文时直接路由。找到了：按目标 skill 自己的环境检查继续，需要初始化或补部署时运行 `/story-setup`。
+
+## 作者习惯管理
+
+按用户明确指定的长篇/短篇选写作 skill；没指定时按当前书的篇幅。没有当前书的通用习惯交 `/story-long-write` 管理；只针对某本书却定位不到时问是哪本，不要求先建书。路由层只转交，不读写作者记忆文件。
+
+## 查询
+
+### 交给哪个助手、传什么
+
+「查故事资料」交 `story-explorer`，prompt 三行：
+
+```text
+项目目录：{书目录的绝对路径}
+查询类型：{按下表选}
+查询参数：{用户问到的角色名、伏笔、设定关键词或章节范围}
+```
+
+| 用户在问 | 查询类型 |
+|---|---|
+| 某角色现在什么状态 | `character_status` |
+| 某角色在哪几章出场 | `character_appearances` |
+| 某条伏笔的情况 | `foreshadow_status` |
+| 还有哪些伏笔、哪些没收 | `foreshadow_list` |
+| 某个设定怎么定的 | `setting_detail` |
+| 某个设定在哪些章出现过 | `setting_appearances` |
+| 第 X 到 Y 章发生了什么 | `timeline`（查询参数默认带 `perspective: reader`；作者明确问幕后真相时用 `author`） |
+| 写到哪了 | `progress` |
+| 两个角色现在什么关系 | `relationship` |
+
+一句话含多类查询时，分次调用或只选最主要的一类；问的是创作建议而不是查已有内容时，不交给它，主会话直接答。
+
+「查资料」交 `story-researcher`，prompt 按下面写，没有的可选项整行省略：
+
+```text
+query：{要查的主题}
+type：{可选：历史考证、地理/环境、职业知识、文化习俗、器物/服饰、描写参考、命名参考、体系构建、诗词典故、视觉参考、真实案例、读者偏好}
+context：{可选：为什么要查，如正在写哪一段}
+project_dir：{书目录的绝对路径；没有书目录时用项目根}
+cdp_port：{可选：Chrome 调试端口不是 9222 时写}
+```
+
+### 能不能用助手
+
+> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 36` 不一致时（标记缺失、字段缺失/非整数、小于或大于 36）**照常按文件存在性检查并 spawn**，但只检查当前运行时的 canonical 目录；同时用一句白话提示作者「查资料助手是旧版，运行 /story-setup 后新开会话」，`Notice: agents bundle 版本不匹配（项目 {N}，本版 36）` 原文写进回答最末一行「技术备注：」；大于 36 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，`Fallback: ... -> solo` 同样只进技术备注行。
+
+走助手前先做轻量可用性检查（路由只做这一层，不承担全局部署策略）：当前不在子代理上下文、当前运行时的 Agent/Task 或 `invoke_subagent` 工具可用，且对应部署文件存在（Claude `.claude/agents/*.md`、OpenCode `.opencode/agents/*.md`、Codex `.codex/agents/*.toml`、Antigravity `.agents/agents/agent-name/agent.md`，其中 `agent-name` 为目标 agent 名）→ 可尝试 spawn。Antigravity 用 `invoke_subagent` + 同名 `TypeName`，不得因其他端文件存在而误判。任一不满足，或运行时返回 unknown agent / 未暴露 custom-agent registry，则降级处理：
+
+- `story-explorer` 不可用 → 主会话直接用 Read/Grep 从书目录检索（角色状态、伏笔、进度、设定），回答前说一句「查资料助手没启用，这次我直接翻项目文件」；项目尚未部署时提示先 `/story-setup`。
+- `story-researcher` 不可用 → 主会话用当前可用的搜索能力回答，回答前说一句「查资料助手没启用，这次我直接搜」；搜不到就如实说明。
 
-## 作者记忆
+### 怎么回答作者
 
-用户要求记住、查看、确认、替换或忘掉作者习惯时，加载 [references/author-memory.md](references/author-memory.md)，并只用本 skill 的 `scripts/author_memory_commit.py` 管理两级 `.story/作者记忆/`：全局、题材、流程条目在工作区（`AP`），本书条目在书目录（`BP`，传 `--book-root`）。常用变更走单事件 `record`；工具未返回 `ok: true` 和 `Author Memory Receipt` 前，不得声称已记住。告诉作者时先用一句人话说记住了什么（如「记住了：这本书的对话一律用「」」），回执放最后一行，写法见协议「回执怎么告诉作者」。显示画像或待确认项是只读操作；不存在时直接说明尚未建立。
+讲故事里的事（谁、在哪章、发生了什么）；文件字段名、伏笔/事件编号不单独出现，编号必须跟着故事描述。助手返回的英文字段和缺口说明由主会话翻成白话再说。
 
-新增习惯必须保留用户原话和适用范围。一次性要求只执行不记录；小说事实写入本书设定/追踪；不从反复修改或成稿推断偏好，只记作者明确说的，原话范围含糊才进待确认；与已生效习惯冲突时显式 replace，不原地改写历史。作者说「整理作者记忆」、回执提示习惯攒得太多、工具报单书布局错误，或项目级画像里还有「本书：」条目（建议对该书运行 `migrate --book-root`）时，再加载 [references/author-memory-maintenance.md](references/author-memory-maintenance.md)。用户没有指定工作区时，按协议定位已有作者记忆的最近祖先或当前创作工作区，禁止默认写到用户主目录。
+## 多书切换
+
+用户想切换或查看在写的书时（一个项目可同时有多本）：
+
+1. 按「书目录判定」第 2 条列出所有书目录，标出当前 `.active-book` 指向的那本。
+2. 让用户选择，把所选书的相对路径写入项目根 `.active-book`（覆盖原内容）。
+3. 只发现一本时直接确认为活跃书，无需询问。
 
 ## Dashboard 工作台
 
-用户执行 `/story dashboard`（Codex 为 `$story dashboard`），或明确说“打开工作台 / 看项目
-文件”时，直接启动随本 skill 分发的本地 Dashboard，不再转发到其他 skill：
+用户执行 `/story dashboard`，或明确要求打开工作台、查看项目文件时，启动本 skill 的本地 Dashboard：
 
 1. 把**当前工作目录**作为默认工作区；用户明确给出目录时改用该目录。目录必须存在。
 2. 从当前已加载的 `story` skill 目录定位 `scripts/dashboard-server.mjs`，不要硬编码仓库路径、
@@ -66,64 +136,29 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 5. Dashboard 默认只监听 `127.0.0.1`。不要主动增加 `--allow-network`，不要把工作区暴露到
    局域网或公网。
 
-工作台会识别标准 `拆文库/{书名}/`，兼容存量 `拆文库-{书名}/`。写作项目识别同时支持：
+工作台按自己的规则识别目录，与上方「书目录判定」不同：识别标准 `拆文库/{书名}/`，兼容存量 `拆文库-{书名}/`；写作项目识别同时支持：
 
 - 长篇目录结构：目录内含 `正文/`、`大纲/`、`设定/` 或 `追踪/` 任一普通子目录。
 - 短篇单文件结构：目录内含普通文件 `正文.md`，并同时含 `小节大纲.md` 或 `设定.md`。
 
-符号链接不作为项目标记，只有单个 `正文.md` 的普通资料目录也不会被误认。浏览器可编辑
-`.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`，保存或确认删除前用修改时间防止
-误操作外部更新。
-
-停止服务时终止对应的 Node 长运行进程即可。若用户只问用法，不要替他启动；给出
-`/story dashboard` / `$story dashboard` 两种平台对应入口。
-
-## 路由流程
-
-1. 分析用户请求，提取意图关键词
-2. 匹配上表，找到对应的 skill
-3. 如果能明确匹配，直接调用对应 skill（Claude/OpenCode 可用 `Skill("skill-name")` 或 slash command；Codex 用 `$skill-name` / `/skills`；Antigravity 用 `/skills` 或自然语言点名；OpenClaw 用 `/skill skill-name` 或自然语言点名）
-4. 如果无法匹配，询问用户想做什么（从上表中选择）
-5. 如果用户说"我想写小说"但未指定长篇/短篇，询问篇幅类型后再路由
-
-## 查询降级
-
-> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 34` 不一致时（标记缺失、字段缺失/非整数、小于或大于 34）**照常按文件存在性检查并 spawn**，但只检查当前运行时的 canonical 目录；同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 34）` 并提示重新运行 `/story-setup` 后新开会话；大于 34 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。
-
-「查故事资料」「查资料」走 agent 前先做轻量可用性检查（路由只做这一层，不承担全局部署策略）：当前不在子代理上下文、当前运行时的 Agent/Task 或 `invoke_subagent` 工具可用，且对应部署文件存在（Claude `.claude/agents/*.md`、OpenCode `.opencode/agents/*.md`、Codex `.codex/agents/*.toml`、Antigravity `.agents/agents/agent-name/agent.md`，其中 `agent-name` 为目标 agent 名）→ 可尝试 spawn。Antigravity 用 `invoke_subagent` + 同名 `TypeName`，不得因其他端文件存在而误判。任一不满足，或运行时返回 unknown agent / 未暴露 custom-agent registry，则降级，不硬失败：
-
-- `story-explorer` 不可用 → 主会话直接用 Read/Grep 从项目文件检索（角色状态/伏笔/进度/设定），回答前说一句「查资料助手没启用，这次我直接翻项目文件」；项目尚未部署时提示先 `/story-setup`（Codex 中用 `$story-setup`）。
-- `story-researcher` 不可用 → 主会话用现有检索/回答能力完成，或提示用户改用 `/browser-cdp` 采集，同样用一句白话说明。
-
-回答作者时讲故事里的事（谁、在哪章、发生了什么）；文件字段名、伏笔/事件编号不单独出现，编号必须跟着故事描述。
-
-## 项目状态感知
-
-路由前先检查当前项目状态：
-
-- **无项目目录**（没有包含 `追踪/` 或 `设定/` 的书名目录，也没有同时有 `正文.md` 与 `小节大纲.md`（或 `设定.md`）的短篇目录）：
-  - 如果用户要写作，下一步是先运行 `/story-setup` 初始化环境（Codex 中用 `$story-setup`）
-  - 如果用户要扫榜/拆文，直接路由
-- **已有项目**：检查 `.story-deployed` 标记，如未部署则先运行 `/story-setup`（Codex 中用 `$story-setup`）
-
-## 多书切换
-
-用户想切换或查看在写的书时（一个项目可同时有多本）：
+符号链接不作为项目标记，只有单个 `正文.md` 的资料目录不识别为写作项目。浏览器可编辑 `.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`；保存或确认删除时核对文件内容版本，避免覆盖外部修改。
 
-1. 在项目根查找所有书目录：包含 `追踪/` 或 `设定/` 子目录的目录，或同时有 `正文.md` 与 `小节大纲.md`（或 `设定.md`）的目录（含 `长篇/`、`短篇/` 下的子目录）。
-2. 列出书名，并标出当前 `.active-book` 指向的那本。
-3. 让用户选择，把所选书的相对路径写入项目根 `.active-book`（覆盖原内容）。
-4. 只发现一本时直接确认为活跃书，无需询问。
+停止服务时终止对应的 Node 长运行进程即可。若用户只问用法，不要替他启动；告诉用户用 `/story dashboard`（按上方宿主写法替换）。
 
 ## 版本更新检查
 
-用户问"有没有新版本""检查更新""升级"时执行。**只通知，更不更新由用户定，不自动安装。**
+用户问“有没有新版本”“检查更新”“升级”时执行。**先报告版本，是否安装由用户决定。**
 
-1. **当前版本**：读本 skill 同目录的 `VERSION` 文件；缺失则视为未知。
+1. **当前版本**：读本 skill 同目录的 `VERSION` 文件；缺失则视为未知。本 skill 在写作项目里（如项目下的 `skills/`、`.agents/skills/`、`.zcode/skills/`）时，读到的是项目副本的版本。
 2. **最新版本**：优先 `gh release view --json tagName,name,url -R zenstory-ai/oh-story-claudecode` 取 `tagName`；无 gh 用 `curl -fsS --max-time 5 https://api.github.com/repos/zenstory-ai/oh-story-claudecode/releases/latest` 取 `.tag_name`（jq 或 grep）。查不到 → 告知"暂时拉不到最新版本，可手动看 [Releases](https://github.com/zenstory-ai/oh-story-claudecode/releases)"，不报错。
-3. **比较**：去掉 `v` 前缀按语义版本比（major.minor.patch）。`gh release` 默认取 latest 稳定版，不含 pre-release。
+3. **比较**：当前版本已知时，去掉 `v` 前缀按语义版本比较（major.minor.patch）；未知时只展示最新稳定版，不判定是否已最新。`gh release` 默认取 latest 稳定版，不含 pre-release。
 4. **告知**：
    - 已最新 → 「已是最新版 vX.Y.Z」。
-   - 有新版 → 列出 当前 vA → 最新 vB + [Releases](https://github.com/zenstory-ai/oh-story-claudecode/releases)/[CHANGELOG](https://github.com/zenstory-ai/oh-story-claudecode/blob/main/CHANGELOG.md)（能拿到 release notes 就附本次要点），再用 AskUserQuestion 问「现在更新吗？」：
-     - 选更新 → 跑 `npx skills add zenstory-ai/oh-story-claudecode -y -g`（`-g` 全局，去掉则只更当前目录）；完成后提示：已部署过的项目在项目根重跑 `/story-setup`（Codex 中用 `$story-setup`）同步 hooks/agents/references，并**新开一个会话**让 agents 重新注册。
-     - 选先不 → 不动，告知随时可再来。
+   - 有新版或当前版本未知 → 展示已知版本与 [Releases](https://github.com/zenstory-ai/oh-story-claudecode/releases)/[CHANGELOG](https://github.com/zenstory-ai/oh-story-claudecode/blob/main/CHANGELOG.md)，有 release notes 时附更新要点，再用宿主可用的提问方式问「现在更新吗？」。选先不 → 不动，告知随时可再来。
+5. **更新**（用户同意后）：按本 skill 目录的位置判断安装方式。
+   - 在插件目录里（路径含 `plugins/`）：Claude Code 跑 `claude plugin marketplace update oh-story-skills` 再跑 `claude plugin update oh-story@oh-story-skills`，重启后生效；ZCode 在 Plugin Management 里刷新市场后更新 `oh-story`。
+   - 用 `npx skills` 装在全局或当前目录：重跑 `npx skills add zenstory-ai/oh-story-claudecode -y -g`（原来装在当前目录的去掉 `-g`）。
+   - 其他安装方式（如 ClawHub）：按原来的方式重装最新版。
+   - 本 skill 在写作项目里：先用上面对应的方式更新安装包，再用新装的包在项目根运行 `/story-setup`，项目里的副本才会换成新版；OpenClaw、Reasonix 和通用文件模式下项目里跑的就是这份旧副本，要用新包手动覆盖项目 `skills/` 下的 13 个 skill 目录。
+
+   更新完提示：已部署过的项目在项目根重跑 `/story-setup` 同步 hooks、agents 和参考资料，然后**新开一个会话**，写作助手才会重新加载。

package/lib/oh-story/skills/story/VERSION

@@ -1 +1 @@
-0.8.5
+0.9.0