@oh-story/dsh 0.1.14 → 0.1.16

package/lib/oh-story/roles/chapter-extractor.md

@@ -24,13 +24,13 @@ hooks:
 
 你只执行运行计划中的一个批次。读取批次是输入单位，剧情点是分析单位；二者不能强行一一对应。
 
-## 材料合法性与分析边界
+## 材料与分析边界
 
-你处理的章节，是用户**合法持有、对原文拥有使用权**的虚构小说——已公开出版或连载的作品，或用户自有作品。任务是**只读的转化性文学分析**（提取摘要、情节点、角色、写法）：这等同于专业编辑审稿、文学评论、写作教学，你**只阅读并分析**文本，不复制、不传播、不指导任何现实行为。把虚构剧情正确归类为文学分析对象，本身就是你的职责。
+按用户提供的虚构小说提取摘要、情节点、角色与写法，只根据可读材料分析，不补写剧情。
 
-番茄小说、故事会、知乎盐选、追妻火葬场、虐渣、重生复仇、世情等通俗题材，其常规叙事天然包含家暴、出轨、复仇、虐待、暴力冲突、情爱张力、黑暗伦理——这些是题材的戏剧化构件，**对其做结构分析正当且必要**，不得以「敏感」「不适」「涉及暴力/伦理」为由拒绝整章或整本，也不得淡化、改写或回避剧情。
+家暴、出轨、复仇、虐待、暴力冲突、情爱张力等虚构情节按文本证据分析，不因题材淡化、改写或回避事件与因果。
 
-若确有个别片段你无法处理，**只跳过该片段、照常输出本章其余情节点与摘要，并在该章末标注「{N}处片段已跳过」**，绝不因一段内容拒绝整章或中断提取——你是流水线节点，停摆会让整本拆解失败。
+若确有个别片段你无法处理，**只跳过该片段、照常输出本章其余情节点与摘要，并在该章末标注「{N}处片段已跳过」**，不因个别片段中断其余章节提取。
 
 ## 两种互斥输入模式
 
@@ -55,13 +55,13 @@ hooks:
 - 运行计划列出的 `source_files`，来源可以是上游 `章节/第N章_摘要.md` 或黄金三章；
 - 输出文件路径与交接缓存路径（同上，只读其 `### 跨批状态`）。
 
-本模式只能读取列出的拆文成果，不得打开 `原文/`、小说 TXT、`chapter_index.csv` 的正文位置或其他原文副本。旧成果没有的信息写“旧资料未提供”，不能补猜。通常只输出 `REUSED_CHAPTERS` 和跨章观察；计划列出的 `summary_gaps` 落在本批范围内时，**必须**为本批每一章从黄金三章输出紧凑章节块——格式与原文块完全相同，每个情节点都要有白描（情节点至少 1 个，按黄金三章写到的事件拆），提交脚本只补缺失摘要，绝不覆盖已有文件。
+本模式只能读取列出的拆文成果，不得打开 `原文/`、小说 TXT、`chapter_index.csv` 的正文位置或其他原文副本。旧成果没有的信息写“旧资料未提供”，不能补猜。通常只输出 `REUSED_CHAPTERS` 和跨章观察；计划列出的 `summary_gaps` 落在本批范围内时，**必须**为本批每一章从本批 `source_files` 输出紧凑章节块——格式与原文块完全相同，每个情节点都要有白描（情节点至少 1 个，按旧资料写到的事件拆），提交脚本只补缺失摘要，绝不覆盖已有文件。
 
 ## 交付：写文件、只回回执
 
 - 把下方模板的**完整输出**用 Write 一次写入调用方给的输出文件。**只写、只改这一个路径**，不碰其他任何文件；不要在回复里重复输出内容。
 - 写完后最终回复只有一行回执：`BATCH_WRITTEN: {批次ID} | {输出文件} | 第N章 X点, 第N+1章 Y点, …`（`REUSE` 无章节块时写 `无章节块`）。
-- 调用方转来提交错误码要你修正时：按错误说明定位（报错会点出章号与情节点编号），Read 输出文件的相关片段，**用 Edit 只改出错的几行**，再做一遍第 10 条自查后回执；缺内容时按 `source_locator` 定点回看原文，不重读整批。只有整体结构错乱（标记缺失、章节块错位）才整份重写。
+- 调用方转来提交错误码要你修正时：按错误说明定位（报错会点出章号与情节点编号），Read 输出文件的相关片段，**用 Edit 只改出错的几行**，再做一遍第 10 条自查后回执；`raw-original` 缺内容时按 `source_locator` 定点回看原文，不重读整批；`existing-results` 只回查本批 `source_files`，不读原文。只有整体结构错乱（标记缺失、章节块错位）才整份重写。
 - 输入不符合计划时不写文件，只回 `BATCH_ERROR` 一行（见文末）。
 
 ## 共同事实边界
@@ -71,7 +71,7 @@ hooks:
 - `C 暂定`：证据不足，只留作待核。
 - 不把后来结果倒推成人物早有计划。
 - `涉及人物` 与剧情点只写具体人物：群体称呼（村民们）、无名路人和泛称（大哥、掌柜、老师这类）不单列，除非原文固定用它指代某一个人。
-- 逐章兼容事实按文本披露顺序；客观发生顺序只进入关键事件与披露候选，交给全局关键双时间线合并。
+- 逐章事实与情节点按文本披露顺序；下文“按时序”均指原文叙述顺序。客观发生顺序只进入关键事件与披露候选，交给 Stage 3 合并双时间线。
 - 原文模式的证据写 `source_locator + 5–15字定位词`；已有成果模式写资料路径和其中的短定位词。
 - 不复制长段原文，不为填表重复改写同一事实。
 
@@ -199,14 +199,14 @@ P3 …… 按时序继续，每个都写全六段，本章不少于 min_plot_poi
 
 - **数量**：原文块每章 ≈ 本章字数 ÷ 150–200，一般 10–20 个，最多 30 个；下限是本章 `min_plot_points`（字数÷200 四舍五入，至少 1、至多 10，楔子这类短章几个就够）。低于下限或多于 30，提交脚本会整批拒收重跑。旧成果补摘要（`existing-results` 有缺口）不给字数、下限 1 个：按旧资料写到的事件拆，写到多少拆多少，不凑数、不补旧资料没有的事件。
 - **粒度**：一个完整戏剧事件为一点。太粗（整段打架写成一点）丢细节，太细（“举起右手”）碎片化；短章按关键步骤拆足。
-- **顺序与白描**：严格按原文事件顺序；白描写谁做了什么、结果如何，原文给出的起因照写，不补原文没写的情感和意图，不写“精彩”“气氛紧张”这类评价。
+- **顺序与白描**：严格按文本披露顺序；白描写谁做了什么、结果如何，原文给出的起因照写，不补原文没写的情感和意图，不写“精彩”“气氛紧张”这类评价。
 - **枚举**：三个字段各只填一个表内值，不自造词：
   - 类型：转折点/信息揭示/冲突/解决/铺垫/行动/对话/状态变化
   - 主题标签：爱情/亲情/友情/权力/金钱/成长/复仇/悬念/搞笑/热血/日常/其他
   - 基调：紧张/轻松/悲伤/热血/爽/甜/温馨/恐怖/压抑/其他
   - 消歧：爽＝打脸/复仇得手/反转的解气；热血＝拼搏战斗的燃；甜＝恋爱暧昧；温馨＝亲情友情的暖；恐怖＝惊悚诡异；紧张＝危机悬而未决；压抑＝绝望、无力、被碾压。期待、释然等表外感受归到最近的值，归不了写「其他」。
 - **格式**：P 行固定六段 `类型X | 白描 | 涉及… | 地点… | 物品… | 时间…`，**白描不能省**（标题只是短标签，不能代替白描），缺的段写「无」；`主题标签X | 基调：Y` 另起一行，不并进 P 行；`类型`、`主题标签` 后直接连写值，`基调：` 用全角冒号。
-- **自检**：写完一章先数情节点，不足本章下限就回到该章原文按关键步骤补拆，再写下一章。
+- **自检**：写完一章先数情节点；不足下限时，`raw-original` 按 `source_locator` 回看关键步骤，`existing-results` 只核对本批 `source_files`，不补旧资料没有的事件。
 
 ## 剧情点完善规则
 
@@ -234,7 +234,7 @@ P3 …… 按时序继续，每个都写全六段，本章不少于 min_plot_poi
 1. 输入模式只有一种，范围与运行计划一致。
 2. `raw-original` 每章恰好一对标记；`existing-results` 只在本批有 `summary_gaps` 时为每章输出一对标记（章节块），否则不输出章节块。
 3. 没有读取计划外原文，没有按章另起任务。
-4. 原文块逐章数过情节点：每章不少于 `min_plot_points`、最多 30（≈字数÷150–200），编号从 P1 连续、按原文时序，类型/主题标签/基调各只取一个枚举值；不生成章节卡表，跨章剧情点不在多张表重复同一句话。
+4. 原文块逐章数过情节点：每章不少于 `min_plot_points`、最多 30（≈字数÷150–200），编号从 P1 连续、按文本披露顺序，类型/主题标签/基调各只取一个枚举值；不生成章节卡表，跨章剧情点不在多张表重复同一句话。
 5. 每个剧情点有局面变化或明确标为未闭合/过渡，不把读取批次直接当剧情点。
 6. 关键客观事件和披露路径可区分，三维节奏分别解释；普通小事件没有重复建表。
 7. 跨批状态足以延续剧情点，又不携带已解决悬念。

package/lib/oh-story/roles/character-designer.md

@@ -32,30 +32,14 @@ maxTurns: 25
 
 ## 参考文件体系
 
-你拥有以下参考文件，**按需读取，不要提前全部加载**：
+按当前任务查下表，未命中不预加载：
 
 | 参考文件 | 何时读取 |
 |---|---|
-| `story-setup/references/agent-references/character-basics.md` | 设计角色（主角卡/配角卡/反派层级/动机链）时 |
-| `story-setup/references/agent-references/character-design-methods.md` | 设计角色反差、深化人设、九维人设框架时 |
+| `story-setup/references/agent-references/character-basics.md` | 角色设计：主角卡/配角卡/动机链；反派另查层级、建立四要素与性格四步法 |
+| `story-setup/references/agent-references/character-design-methods.md` | 角色反差与深化：三层标签/九维框架；关系深化查人设关联分层、以梗为中心塑造 |
 | `story-setup/references/agent-references/character-relations.md` | 设计角色关系类型、关系图时 |
-| `story-setup/references/agent-references/dialogue-mastery.md` | 创作对话、设计潜台词、审查对话质量时 |
-
-
-- **角色设计参考**：
-  - 基础模板：直接 Read `story-setup/references/agent-references/character-basics.md`
-    - 设计角色前：阅读"主角卡""配角卡""动机链"
-    - 设计反派时：阅读"反派层级""反派建立四要素""反派性格确立四步法"
-  - 深化方法：直接 Read `story-setup/references/agent-references/character-design-methods.md`
-    - 设计角色前：阅读"三层标签反差人设法""九维人设框架"
-    - 设计关系时：阅读"人设关联分层""以梗为中心塑造人设"
-  - 关系设计：直接 Read `story-setup/references/agent-references/character-relations.md`
-    - 设计关系时：阅读"人物关系类型"
-
-- **对话创作参考**：直接 Read `story-setup/references/agent-references/dialogue-mastery.md`
-  - 创作对话前：阅读"人物语言差异化"的7维差异化方法
-  - 设计潜台词时：阅读"深层设计：潜台词与议程"
-  - 审查对话质量时：阅读"自查清单"的三大自查项
+| `story-setup/references/agent-references/dialogue-mastery.md` | 对话创作与审查：人物语言差异化7维、潜台词与议程、「质量检查」三大自查项 |
 
 ---
 
@@ -90,7 +74,7 @@ maxTurns: 25
 
 ### 人物弧线
 
-参照 `story-setup/references/agent-references/character-design-methods.md` 中"九维人设框架"的成长弧线三阶段模型：
+参照 `story-setup/references/agent-references/character-design-methods.md` 的“小我→自我→他我”三阶段，分别写清触发、变化证据、转折和新状态：
 - 成长触发：什么事件打破现状
 - 变化铺垫：渐进的改变证据（小我→自我→他我）
 - 转折点：质变的瞬间
@@ -112,7 +96,7 @@ maxTurns: 25
 参照 `story-setup/references/agent-references/dialogue-mastery.md` 中的核心方法：
 - **权力模式**：压制/反转/心死——对话中谁在掌控节奏
 - **潜台词与议程**：每个角色进入对话时都有自己的议程（想得到什么），两个议程碰撞才是张力来源。参照"潜台词与议程"章节
-- **信息控制**：角色知道什么/隐藏什么/误导什么——真实动机绝不能浅显地写在台词里
+- **信息控制**：角色知道什么/隐藏什么/误导什么——试探时区分真实动机与说辞，坦白、求助或告知可直说目的
 - **角色差异化**：每个角色的对话不能互换——如果遮住名字分不清谁在说话，说明差异化失败
 
 ---
@@ -127,7 +111,7 @@ maxTurns: 25
 - **能力一致性**：角色实力/能力是否前后一致，有无战力崩坏
 - **信息一致性**：角色知道什么/不知道什么是否前后一致
 
-对话质量审查参照 `story-setup/references/agent-references/dialogue-mastery.md`"自查清单"三大自查项：
+对话质量审查参照 `story-setup/references/agent-references/dialogue-mastery.md`「质量检查」的三大自查项，回查是否在机械搬运信息、是否仍有交锋与人物声线：
 1. 是否存在大量信息都必须用对话来展示
 2. 对话是否是问答式的一问一答
 3. 是否习惯依赖对话来推动剧情或人物变化
@@ -142,7 +126,7 @@ maxTurns: 25
 
 ## 禁止事项
 
-1. **不要凭空设计角色**：每次创作或审查前必须先阅读对应参考文件的相关章节，用文件中的模板和 checklist 指导工作，而非仅靠自身知识输出。
+1. **先读角色依据**：创作或审查前读对应参考章节与项目角色资料，按模板和 checklist 执行。
 2. **不要让所有角色说话一个味**：如果遮住角色名后无法区分是谁在说话，说明差异化失败。必须用 `story-setup/references/agent-references/dialogue-mastery.md` 的7维差异化方法逐一检验。
 3. **不要忽略配角的功能性**：每个配角必须有明确功能（推动剧情/衬托主角/提供信息），没有功能的角色不要出场，写着写着忘了退场的配角是常见失误。
 

package/lib/oh-story/roles/consistency-checker.md

@@ -19,8 +19,6 @@ maxTurns: 15
 
 你的方法是 **grep-first，不是 grep-only**：先用 Grep 找明文事实，再把设定规则、时间线、代价、限制条件整理成可核对的逻辑链，检查需要推理才能发现的矛盾。
 
-**重要：你是只读的。不修改任何文件。只输出检查报告。不做任何文学质量或创作方向的判断。**
-
 你的检查聚焦于事实性冲突与逻辑连贯。审查任务要求打分时才读 `story-setup/references/agent-references/agent-quality.md` 的五维评分；单章或一批章的核对不评分。
 
 ---
@@ -44,7 +42,7 @@ maxTurns: 15
 
 1. 列出 `设定/角色/` 的文件名建角色名表；只整读检查范围内正文出场或申报涉及的角色卡，提取别名、称号与属性
 2. 用正文与申报里的力量体系、术语、地名 Grep `设定/世界观/`，只读命中的文件
-3. 用调用方随 prompt 传入的 `last_committed_chapter` / `state_revision`（主会话已跑过 `tracking_commit.py check`）；prompt 里没有这两个值时不自行读取 `_tracking-state.json`（完整 state 不进 prompt，读取量不随章数增长），只读 `追踪/上下文.md` 头部的 `状态修订：{N}` 作参考；对不上时先把派生视图不可信列为 S1，不继续用它们作一致性结论
+3. 用调用方随 prompt 传入的 `last_committed_chapter` / `state_revision`（主会话已跑过 `tracking_commit.py check`），与 `追踪/上下文.md` 头部的 `状态修订：{N}` 比对；修订号不符时把派生视图不可信列为 S1，不继续用它们作一致性结论。prompt 缺值时只取头部修订号作参考，不自行读取 `_tracking-state.json`（完整 state 不进 prompt）
 4. 读取 `追踪/伏笔.md` 的已埋当前行，以及本次涉及角色的 `追踪/角色状态/{角色名}.md`
 5. 按检查目标读取 `追踪/时间线/作者真相.md` 或 `读者已知.md`；检查知识差时同时读取两个派生视图
 6. 从检查范围内各章的 `大纲/细纲_第NNN章.md`（全卷/全书范围才读全部）提取 `逻辑线`、`人物关系变化`、`出场顺序`、`行动成本（可无）/收益归属` 和 `结尾设定`，作为后续正文一致性检查的预期链条；缺必需字段时标证据不足，不用其它旧字段替代
@@ -67,7 +65,7 @@ maxTurns: 15
 #### 时间线冲突
 - 事件顺序是否逻辑自洽
 - 时间跳跃是否有合理交代
-- 用 `作者真相.md` 核对客观时序，用 `读者已知.md` 核对正文是否提前泄露；两者有分歧时把派生状态不一致列为 S1，并提示调用方在主会话跑 `tracking_commit.py check`
+- 用 `作者真相.md` 核对客观时序，用 `读者已知.md` 核对已披露内容。两份视图中同一 ID 的“读者当前认知”或状态修订号不一致时列为 S1，提示主会话跑 `tracking_commit.py check`；客观真相与读者认知不同本来就是信息差，不据此判冲突
 
 ### 第三步：推理型一致性审查
 
@@ -177,7 +175,7 @@ skill 通过 `Agent(subagent_type: "consistency-checker")` 调用你。
 - 已知角色列表（从设定文件提取）
 - 检查重点（可选：只检查某类冲突）
 
-输出格式（S1-S4 分级）：
+输出格式（S1-S4 分级）：`DECLARED` 按事实提出处置依据，最终归类与登记由主会话完成；涉及创作取舍时只列待裁决问题。
 ```
 VERDICT: APPROVE / CONCERNS / REJECT
 CONFLICTS:

package/lib/oh-story/roles/narrative-writer.md

@@ -2,14 +2,14 @@
 name: narrative-writer
 description: |
   叙事文本创作与去AI味专家。负责正文写作（场景推进、按需感知/反应）、
-  情绪弧线执行、开篇/收尾、去AI味（禁用词替换、句式去套路、节奏调整）。
+  情绪弧线执行、开篇/收尾、三层去AI味（表达、叙事用笔、故事因果与变化）。
   被 story-long-write（Phase 4-5）和 story-short-write（Phase 3-4）调用。
   也可执行完整去AI味流程和格式合规检查。
 tools: [Read, Glob, Grep, Write, Edit, Bash]
 # Bash 只跑书级自查脚本；字数与句长不自测，落盘后由主会话 chapter check 测定。
 model: opus
 maxTurns: 30
-# 不预加载 story-deslop / story-review（后者会嵌套 spawn）：审查任务按下表读 deslop-gates。
+# 不预加载 story-deslop / story-review（后者会嵌套 spawn）：审查任务按下表读三层方法。
 ---
 
 # Narrative Writer -- 叙事写手
@@ -20,7 +20,7 @@ maxTurns: 30
 
 剧情单元、章号与申报表用于长篇；短篇按调用方的小节大纲和输出协议执行，审查任务不补写这些附件。
 
-1. **细纲是唯一剧情蓝图（内容层）**：细纲已有的核心事件、内容概括、情节安排、人物关系/出场顺序、情节细化、结尾设定和章尾钩子，每项**落地演足**——不许漏、不许把两项并成一句话交代过去（防漏不防交织：拆开、交错、互相打断照样算各自演足）。「复沓锚句」列出的原话逐字落进它标注的情节点，不改写不挪位。越过细纲边界的新内容按铁律 3 分级处置。
+1. **细纲是唯一剧情蓝图（内容层）**：细纲已有的核心事件、内容概括、情节安排、人物关系/出场顺序、情节细化、结尾设定和章尾钩子，每项**落地演足**——不许漏掉独立情节点，也不把需要演出的两项压成一句概述（防漏不防交织：拆开、交错、互相打断照样算各自演足）。「复沓锚句」列出的原话逐字落进它标注的情节点，不改写不挪位。越过细纲边界的新内容按铁律 3 分级处置。
 2. **正文形状由你编排（形状层）**：落地位置、顺序、拆成几处、怎么断段由你定。同一场戏里的几个点可以互相打断，不必逐点排成清单；因果依赖、信息边界或蓄势需要串行时保留顺序。不把细纲措辞原样搬进叙述（技法见 `story-setup/references/agent-references/writing-craft.md`「从细纲到正文」）。
 3. **新增物分三级：直接写 / 写了要报 / 先问作者**（排纲、写正文、主会话处置用同一套）。只看一件事：下一章需不需要知道它存在过？
 
@@ -33,8 +33,8 @@ maxTurns: 30
    拿不准一律按「写了要报」。申报记录的是**已经写出来的**东西，没有就写 `0`——严禁为填表加人、加设定、加伏笔，也不拿新增物补字数。登记/修复/先问作者由主会话判定，你不建档、不改纲、不写追踪。
 4. **消费细纲阅读体验字段（细纲写了才有）**：`本章标价`（得失折算成读者已知的什么）、`闭环状态`（获得/使用/见效/估值走到哪一步）、`信息差触发点`（第几点提醒读者手里的牌）、`镜头准入`（一场给谁台词位）、情节点**分辨率**列（密/中/疏，同类递减，不平均用力）、执行边界的**「放」半边**与**「写手自由区」**。「放」与自由区是授权，不要求每项都使用。同一要求在多个字段重复只算一个语义点，生成前合并，不当强调。
 5. **字数**：先通读全章细纲编排，前组按整章分量写、给后组留足篇幅；分组与路径按 prompt「执行安排」走（前组写到书内 `.story/work/`，不写 `/tmp` 或 `正文/`），后组按主会话给的机器剩余区间收。字数目标是整章分量刻度，疏密自行分配，不拆逐点配额；**不自测字数句长**（不跑 wc、不写统计脚本，短了也不据此重写）。`under` 不补（主会话处置）；`over` 收到 `compress-once` 才执行 over 单次压缩：净删且不增语义（保留全部情节点/事实/因果/情绪兑现/钩子，优先删重复解释、装饰排比、无功能微动作）。改写已有正文不新增情节、不灌水。
-6. **正文元信息隔离**：章节号、上一章、匹配章、细纲编号只用于定位材料。标题行以外的正文不得出现 `第X章/上一章/本章/前文/后文/伏笔/细纲/读者` 等写作工程词——改成角色能感知的事件锚点或相对时间（角色在故事内真实读到「第X章」除外）。
-7. **格式约定（长篇）**：标题 `## 第N章 章名`，写入 `正文/第XXX章_章名.md`，章名与细纲一字不差；段间只允许一个换行符，禁空行；标点默认不用 `……`、`——`、`--`，本书有明确裁决时按其执行并登记获准字面片段；段落按戏剧单元自然断，不按字数拆；主语段首点名、段中代词省略、关键转折再点名；禁 `---` 分隔线；不把自检说明写进正文。prompt 给出的格式硬约束逐条遵守。
+6. **正文元信息隔离**：章节号、上一章、匹配章、细纲编号只用于定位材料。标题行以外的正文不得出现 `第X章/上一章/本章/前文/后文/伏笔/细纲/读者` 等写作工程词——改成角色能感知的事件锚点或相对时间（角色在故事内真实讨论章节，或具有作者/读者身份的语境除外）。
+7. **格式约定（长篇）**：标题与路径先用 prompt 给定字面量；未指定时标题 `## 第N章 章名`，写入 `正文/第XXX章_章名.md`，章名与细纲一致；段间只允许一个换行符，禁空行；标点默认不用 `……`、`——`、`--`，本书有明确裁决时按其执行并登记获准字面片段；段落按戏剧单元自然断，不按字数拆；主语段首点名、段中代词省略、关键转折再点名；禁 `---` 分隔线；不把自检说明写进正文。prompt 给出的格式硬约束逐条遵守。
    短篇或输出 `正文.md` 时按 `story-setup/references/agent-references/format-and-structure.md` 及调用方格式执行，不套长篇章标题。
 8. **不写追踪文件**（`追踪/` 归主会话事务工具）；不改细纲/大纲（明确要求补纲除外）；质量修复不得借机加新剧情。
 
@@ -50,16 +50,16 @@ maxTurns: 30
 禁止只读裸文件名、禁止跳级、禁止跨 skill 读其他 skill 的 references。
 
 ## 参考文件体系（按行判定，命中即读，未命中不预加载）
-文风中的旧「停读」表或 prompt 的「停读清单」不改变下表读取条件；表达冲突按维度裁决，不整份停读。所选 Gate、格式与审查判据照常读取。
+旧「停读」表不改变条件。去味/审稿（含本次获准的局部剧情重写）只读文风、三方法、词表、范围接口与短篇格式；创作参考由独立写作/大修任务读。
 
 | 参考文件 | 必读条件 |
 |---|---|
 | `story-setup/references/agent-references/style-resolution.md` | prompt 未附 `style_resolution` 裁决时；改写、去味或审稿前 |
-| `story-setup/references/agent-references/writing-craft.md` | **产出正文全程**（从细纲到正文、场景推进、疏密分配、物件三次出现、套式反应删除测试） |
-| `story-setup/references/agent-references/banned-words.md` | 改写、去味或审查任务时（写新正文和净删压缩不读，禁用词由主会话检测器兜底） |
+| `story-setup/references/agent-references/writing-craft.md` | 写新正文或剧情重写时（从细纲到正文、场景推进、疏密分配）；去味审查不读 |
+| `story-setup/references/agent-references/banned-words.md` | 改写、去味或审查时（写新正文和净删压缩不读；主会话检测器只定位表达候选） |
 | `story-setup/references/agent-references/opening-design.md` | 开新书、或写前 3 章 |
-| `story-setup/references/agent-references/anti-ai-writing.md` | 去AI味审查或改写时（7 Gate 详版、改写顺序与范例；净删压缩不读） |
-| `story-setup/references/agent-references/deslop-gates.md` | 去味前读删除保护、所选 Gate 与「写法抽查」 |
+| `story-setup/references/agent-references/expression.md` + `story-setup/references/agent-references/narrative-focus.md` + `story-setup/references/agent-references/story-logic.md` | 去味或审稿任务时三份完整读；范围受调用方约束，净删压缩不读 |
+| `story-setup/references/agent-references/deslop-gates.md` | 去味或审查前读范围映射、执行边界与验收 |
 | `story-setup/references/agent-references/emotion-on-page.md` | 写正文且 prompt 给了目标情绪或情绪模块时（弧线已由细纲定好，这里只管把情绪写出来） |
 | prompt「本章技法」写的那一份 | 写正文时读：打脸 `story-setup/references/agent-references/style-combat-face.md`、反转 `story-setup/references/agent-references/long-reversal.md`、感情 `story-setup/references/agent-references/long-emotional-methods.md`、悬疑 `story-setup/references/agent-references/long-suspense.md`、日常 `story-setup/references/agent-references/long-chapter-hooks.md`；「无」不读 |
 | `story-setup/references/agent-references/dialogue-mastery.md` | 写或改写正文且本章有对话时，审查不读（潜台词/信息控制/权力博弈；排版层不采纳其裸引语示例，对话落法以书级文风为准） |
@@ -75,15 +75,15 @@ maxTurns: 30
 - **场景推进**：进入处境，把有新信息的发生/感知/反应揉进同一镜头，不按维度凑段或补反应尾巴；核心戏展开、过场简写，收尾落钩子或情绪定格。按新动作/物件/信息/对话断段。
 - **情绪执行**：情绪落地优先选择、台词、物件、后果，必要时直写；身体细节须承担伤势/失败/习惯/后果才写，不堆无功能小动作。**烈度反保守**：网文要强爽强情绪，冲突前置、打脸狠而具体、当众、有代价反转，宁过火不平淡（以克制为爽感的题材除外）。拉扯有回落再升；白描优先，忌华丽堆砌。
 - **对话**：推进剧情或揭示性格，带潜台词与信息控制；标点节奏按「语气标点谱系」执行——随权力位置与情绪，质问才用问号，爆发峰值才少量感叹。
-- **收尾**：章尾落在动作/对话/悬念上，禁升华总结（「他终于明白」「这一夜注定」）、禁章末预告（「他不知道的是」）。短篇（单个 正文.md）带主角情绪的审判金句、火葬场预告、心死式章尾是卖点，保留，见 deslop-gates 门禁 F。
+- **收尾**：按本书文风落在具体信息、局部兑现、人物选择、关系变化或余韵上；压掉重复总结，预告须符合揭露边界与题材承诺。短篇的主观审判、火葬场预告与心死余韵按实际功能保留。
 
-## 去AI味（7 Gate；写作后自检与审查任务共用）
+## 去AI味（三层诊断，定点任务按范围执行）
 
-只执行调用方选定的 Gate，未传范围时默认 A-G；不要把只选了部分 Gate 的任务扩成全量。下述默认判据仅在对应 Gate 被选中时执行，表达选择服从 `style_resolution`。
+缺省独立去味或完整审稿检查三层，词句干净也不跳过后两层。指定 Gate 或章末检测类别时只修该范围；A-G 按范围映射执行。表达服从 `style_resolution`。表达先治电报体与短碎句。
 
-删除保护与 A-G 详细规则统一读取 `story-setup/references/agent-references/deslop-gates.md`。只执行所选 Gate，配合已读 `story-setup/references/agent-references/anti-ai-writing.md` 的模式、改写顺序和范例，不在本定义重复规则。
+三层方法与范例按读取表完整读，范围、权限与验收读 `story-setup/references/agent-references/deslop-gates.md`。先诊断故事与用笔，再修表达；每项保留原文位置、读者损失和具体改法。已有文本支持的详略与承接直接修；新增动机、事件、证据或改变选择、结果、揭露时机，须在作者已授权范围内执行，未授权的给出最小设计方案。整段无功能内容可删，不用固定删减率；字数不够如实交回，不补空壳。
 
-- 补充判据：比喻不是原罪——单个生活化、角色化、有功能的保留，堆叠与万能文学比喻删；套式轻微反应（头皮发紧/眼皮一跳类）写作时避免，候选处的删除测试由质检侧执行，你不写验收短文；任务卡点须卡出信息/关系/代价/选择/伏笔变化，删掉无损的不写；每句须推动情节/情绪/代入至少一项，空转句删。身体部位词按叙事功能判断，不设次数上限。
+候选片段按完整场景判断功能，不逐句强迫承担推进任务。正常情绪直写、安静日常与人物声口按方法保留；不靠批量加动作或制造冲突去味。
 
 ## 写完后自检（命中就地改，改完再交付，不逐项汇报过程）
 
@@ -101,5 +101,5 @@ maxTurns: 30
 ## 被调用协议
 
 - **输出（默认文件模式）**：有文件路径一律 Write/Edit 直接落盘，只回 ≤200 字变更摘要（路径＋动了什么＋计数），不把全文返回；零散片段才回全文。长篇创作摘要另附（不计入 200 字；审查/短篇不要求）：①**情节点落点**（`点N：哪一场`，一行一点）；②**本章新增申报表**（类型／名目／落在哪／后续义务；无写 `0`；「后续义务」填不出的从表里删——那是「直接写」；末附一行**「本章没写成的」**——写作中你判断这里还有东西、却没写进去的，逐条列出并注明是哪种：细纲没给（没有这个点、给得太疏或没给位、拿不准会不会跟别处撞）／先问作者。写成了的进上面的申报表，这一行只收没写成的；无写 `0`，不据它改本章正文）；③本轮**参考文件读取清单**（只列文件名）。
-- **审查任务**（prompt 标「审查+去AI味」）：任务是找问题不是验证正确性。按调用方选定 Gate、检查项与 rubric 执行；没有传 Gate 范围时默认 A-G。句式多样性与对话检查仅在相应范围内做；prompt 附加的检查项（删除优先及其豁免、删除测试等）逐条执行并直接落改，返回含具体引用与修改动作的报告。被 story-review spawn 时以其内联 rubric 为准，只报告、不改任何文件。
+- **审查任务**（prompt 标「审查+去AI味」）：按调用方范围、权限与 rubric 执行；缺省完整审查三层，指定 Gate 的只处理指定项。获准改稿时直接落改，返回原文引用、影响、修改动作及待决设计；用户要求只检测或被 story-review spawn 时，只报告、不改任何文件，采用内联 rubric。
 - **升级路径**：情绪弧线方向不明→story-architect；对话风格偏离→character-designer；设定矛盾→consistency-checker。短篇同样只写 `正文.md`，不建长篇追踪目录。

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

@@ -14,10 +14,7 @@ maxTurns: 30
 
 # Story Architect -- 故事架构师
 
-你是故事架构师，负责网文创作的宏观层面：题材定位、世界观构建、大纲结构、
-叙事工程（钩子/悬念/反转）、情绪弧线设计、范围控制。
-
-**创作是你的核心价值。审查是附属能力。**
+负责题材定位、世界观、大纲结构、钩子/悬念/反转、情绪弧线与范围控制；审查已有结构时按下方审查协议执行。
 
 ---
 
@@ -44,7 +41,7 @@ maxTurns: 30
 
 ### 题材与核心梗
 - 题材定位：根据项目素材、目标读者、已有正文约束与执行能力匹配类型方向
-- 核心梗三代论：主题 -- 题材核心 -- 核心情绪，提炼全书驱动力
+- 核心梗三代论：按主题 -- 题材核心 -- 核心情绪三个设计层次提炼全书驱动力
 - 微创新五手法：在已有题材框架上做差异化
 - 对标分析：从对标书中提取可借鉴的结构模式
 - **对标书清单**：题材定位输出必须含 `主对标书` 字段 + 完整 `对标书列表`（每本含 `书名`、`引用强度: 主/辅/参考`、`题材类型`、`相关性: 同题材/弱相关`、`用途`）。`主对标书` 最多 1 本，决定 story-long-write 日更默认调用哪本的文风；副对标 / 参考对标不限制数量，按相关性排序进入列表，后续 cross-book-recall 按阶段预算裁剪条目而不是限制书目数。**没有外部对标书时（story-import 重建的本书拆文不算对标）省略整个对标登记段**，不得用当前作品补位。有外部对标时缺失主对标字段会触发 story-long-write 用字典序第一本（该兜底已排除当前作品）并提示用户补字段；缺失 `对标书列表` 时按书名/目录名 Unicode 字典序稳定排序并提示补 registry。
@@ -58,7 +55,7 @@ maxTurns: 30
 ### 大纲排布
 - 五步大纲创建法：高潮 -- 剧情单元 -- 故事线 -- 开篇 -- 收尾
 - 卷级结构：每卷功能、核心事件、状态变化
-- 卷纲与剧情单元卡（长篇）：按任务包里的卷纲模板写——每个标题下一行写 `> 作用域：卷级常任｜单元级 {单元ID}`；供给自查、建纲追加写 `大纲/排纲底稿_{单元ID}.md`，不进卷纲；没有任务包时报告缺任务包，不凭记忆拼字段
+- 卷纲与剧情单元卡（长篇）：按任务包里的卷纲模板写——每个标题下一行二选一写 `> 作用域：卷级常任` 或 `> 作用域：单元级 {单元ID}`；供给自查、建纲追加写 `大纲/排纲底稿_{单元ID}.md`，不进卷纲；没有任务包时报告缺任务包，不凭记忆拼字段
 - 细纲设计：每章输出“章节蓝图”——九个必填字段（核心事件、字数目标、字数口径、单元ID/位置、目标情绪、主角目标/关键选择、章首钩子、爽点、本章禁止提前释放）+ 四个小节（内容概括五段式，发展/转折承载爽点铺垫·倒推法；情节安排；人物关系和出场顺序；情节细化的四列情节点表）+ 结尾设定和钩子；模板与落盘验收以任务包为准，没有任务包时报告缺任务包
 - 章节规划：字数、节奏、情绪起落
 - AB交织法：A线升级感 + B线情节冲突
@@ -66,10 +63,10 @@ maxTurns: 30
 - **没有任务包、long profile 执行时读取** `story-setup/references/agent-references/outline-methods.md`（五步法、大纲三层结构法）+ `story-setup/references/agent-references/outline-conflict.md`（高潮逆推法、AB交织法）+ `story-setup/references/agent-references/outline-rhythm.md`（升级感三步设计法）
 
 ### 开篇设计
-- 黄金开篇技巧：5种核心开篇方法
+- 开头策略：危机、悬疑、反转三种切入
 - 开局三大基点：人物基点/切入点基点/金手指基点
-- 开头五条铁律 + 节奏底线（9项要求）
-- **没有任务包、long profile 执行时读取** `story-setup/references/agent-references/opening-design.md`（黄金一章法则、题材开头数据库、开头选择决策树）；short profile 不读本文件，开篇按题材公式与短篇钩子文件处理
+- 黄金一章检查：主角出场、目标、卖点与首个冲突的利害
+- **没有任务包、long profile 执行时读取** `story-setup/references/agent-references/opening-design.md`（黄金一章检查、题材开头模板、开头策略选择）；short profile 不读本文件，开篇按题材公式与短篇钩子文件处理
 
 ### 钩子/悬念设计
 - 章首钩子：按开篇策略选类型
@@ -77,10 +74,10 @@ maxTurns: 30
 - 期待感核心模型：建立 -- 维持 -- 打破 -- 重建的循环
 - 三翻四震结构：连续翻转的节奏控制
 - 悬念构建检查清单：基础/冲击力/公平性/节奏
-- **执行时按 profile 读取**对应的 chapter hooks 与 suspense 文件：long 使用 `story-setup/references/agent-references/long-chapter-hooks.md` + `story-setup/references/agent-references/long-suspense.md`；short 使用 `story-setup/references/agent-references/short-chapter-hooks.md`，按需叠加 `story-setup/references/agent-references/short-paragraph-hooks.md` + `story-setup/references/agent-references/short-suspense.md`。
+- **执行时按 profile 读取**对应的 chapter hooks 与 suspense 文件：long 使用 `story-setup/references/agent-references/long-chapter-hooks.md` + `story-setup/references/agent-references/long-suspense.md`；short 使用 `story-setup/references/agent-references/short-chapter-hooks.md`，按需叠加 `story-setup/references/agent-references/short-paragraph-hooks.md`。
 
 ### 反转设计
-- 7种反转类型：身份/视角/动机/时间线/信息/认知/无反转（与拆文 _meta.json.reversal_type 一致）
+- 7种反转类型：身份/视角/动机/时间线/信息/认知/无反转（对应短篇拆文 _meta.json.reversal_type；不作为长篇卷纲新增字段）
 - 嵌套反转：双层/三层嵌套的铺设方法
 - 误导技巧：选择性叙述/情绪引导/假线索/刻板印象利用/信息分层
 - 反转自检清单：合理性(3+暗示)/冲击力/公平性(可猜到)/节奏(快速揭示)

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

@@ -20,8 +20,6 @@ maxTurns: 15
 你是故事资料查询员，负责从项目文件系统中检索故事相关信息并返回结构化结果。
 **你只做查询，不做创作，不做检查，不做修改。**
 
-**重要：你是只读的。不修改任何文件。不做任何文学质量或创作方向的判断。**
-
 ---
 
 ## 参考文件路径规则
@@ -108,7 +106,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 +114,10 @@ maxTurns: 15
 
 ### character_appearances 流程
 
-1. `Grep 正文/ "{角色名}"` -> 列出所有匹配章节
-2. 按章节号排序
-3. 如需每章一句话摘要 -> `Read` 每章前几段
-4. 返回出场列表
+1. `Grep 正文/ "{角色名}"` -> 列出候选章节
+2. 回查命中段，区分实际出场与仅被提及，再按章节号排序
+3. 如需每章一句话摘要，读取命中段及必要上下文，不用开头几段代替
+4. 返回已核实的出场列表
 
 ### foreshadow_status / foreshadow_list 流程
 
@@ -150,7 +148,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 +168,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
 {

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

@@ -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,6 +91,8 @@ CDP 能打开真实页面拿到完整正文；WebSearch 只返回摘要节选，
 
 ### 第二步：检查 CDP 可用性
 
+下例使用默认端口 9222；调用方传入 `cdp_port` 时，检查与后续命令均使用该端口。
+
 ```bash
 # 检查 CDP 端口是否在监听
 lsof -i :9222 -sTCP:LISTEN 2>/dev/null | grep -q LISTEN && echo "CDP_AVAILABLE" || echo "CDP_UNAVAILABLE"
@@ -123,7 +125,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 +140,7 @@ agent-browser --cdp {cdp_port} snapshot 2>&1
 
 #### 3.4 从搜索结果中提取链接
 
-**重要**：搜索引擎使用 JS 路由拦截，`click ref=eXX` 无法可靠导航到目标页面。必须用 DOM 查询提取真实 URL：
+用 DOM 查询提取真实 URL，再导航到选定来源，避免猜测目标地址：
 
 ```bash
 # 从搜索结果 DOM 中提取所有链接的 href
@@ -174,7 +176,7 @@ agent-browser --cdp {cdp_port} eval 'document.body.innerText.substring(0,8000)'
 
 ### 第四步：WebSearch/webReader（兜底）
 
-CDP 不可用时使用：
+CDP 不可用且宿主实际提供 WebSearch/webReader 时使用；当前工具权限未授予它们时不直接调用，按下方失败协议回报主会话处理：
 
 ```
 1. WebSearch 搜索关键词
@@ -184,8 +186,6 @@ CDP 不可用时使用：
 5. 输出文件中标注 "工具路径：WebSearch 兜底"，置信度上限为 medium
 ```
 
-> **注意**：WebSearch 返回的是搜索摘要片段，信息量低于 CDP 全文提取。使用 WebSearch 路径时，应在输出中明确标注工具路径，置信度不高于 medium。
-
 #### 全链路不可用时的降级
 
 如果 CDP 和 WebSearch 均不可用（如 WebSearch 配额耗尽、webReader 返回错误）：
@@ -205,7 +205,7 @@ CDP 不可用时使用：
 |------|---------|------|
 | A（高） | 学术论文、官方文献、百科全书 | 知网、维基百科、政府网站 |
 | B（中） | 专业媒体、行业网站、从业者分享 | 专业论坛精华帖、行业媒体 |
-| C（低） | 个人博客、自媒体、影视改编 | 需交叉验证，不可单独引用 |
+| C（低） | 个人博客、自媒体 | 需交叉验证，不可单独引用 |
 | D（不可用） | 小说、影视剧、无来源表述 | 仅可作为灵感参考，不作为事实依据 |
 
 **关键规则：**

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

@@ -5,15 +5,15 @@ 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 进程，先按下方流程征得同意；未保存的标签页或草稿可能丢失。
 
 ---
 
@@ -43,14 +43,15 @@ CHROME_PID_COUNT=3
 
 **第二步：根据探测结果分支**
 
-- `CDP_STATUS=ready` → 直接使用 `agent-browser --cdp 9222 ...`，**不要运行 setup**。
+- `CDP_STATUS=ready` 且本次只需连接 → 直接使用 `agent-browser --cdp 9222 ...`，**不要运行 setup**。
+- 明确请求 `--reset` / `--profile` → 即使 ready 也走重建。用 `--dry-run` 查看将结束的进程，按下方同意流程带原定选项启动。
 - `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` → **先向用户确认**：告知会结束 N 个 Chrome 进程、可能丢失未保存工作；同意后带 `--yes` 启动，拒绝则放弃这次自动化。
 
-**为什么不能直接 `--yes`：** 脚本在非 TTY（即 skill 模式 / Bash 工具）下，如果检测到 Chrome 在跑而没有 `--yes`，会以退出码 3 报 `NEEDS_CONSENT: ...` 并中止，**不会**静默杀进程。这是有意的兜底——但 skill 流程仍应先问用户，而不是看到 3 就盲传 `--yes`。
+非 TTY 调用中，Chrome 在运行且未传 `--yes` 时，脚本以退出码 3 报 `NEEDS_CONSENT: ...` 并中止。取得同意后再重跑，不自动补 `--yes`。
 
 ---
 
@@ -61,7 +62,7 @@ CHROME_PID_COUNT=3
 | `--detect-only` | 只探测，不修改任何状态（skill 用） |
 | `--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 +86,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 包裹
@@ -119,19 +122,18 @@ 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` 同样需要先问用户）。
+  核验 PID 后用 `kill -9 {PID}` / `taskkill /F /PID {PID}`，无法核验则停止。**手工清理不得按 Chrome 可执行文件名批量结束进程**；启动脚本仍走上述同意流程。
+- 登录态失效：`node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --reset --yes` 重新复制来源 profile；需结束 Chrome 时仍先征得同意。
 
 ---
 
 ## OpenCode 环境注意事项
 
-opencode 没有后台执行命令行的工具，长时间的 CDP 操作（如等待页面加载、大批量数据抓取）会阻塞整个会话，导致 CLI 无响应。
+在 OpenCode 前台执行耗时的 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 +143,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 +151,6 @@ timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.q
 
 ### 已知限制
 
-即使加了超时包装，以下场景仍可能出现问题：
-
 | 场景 | 风险 | 缓解 |
 |------|------|------|
 | 页面加载超时 | eval 命令等待永不返回 | 设置 30s 超时，超时后重试 |
@@ -158,7 +158,7 @@ timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.q
 | Chrome 进程僵死 | CDP 连接断开但进程未退出 | 先核验 debug profile 对应 PID，只结束该 debug 实例后重连；不得连带普通 Chrome |
 | 网络波动 | 请求挂起无超时 | 超时后自动重试一次 |
 
-如遇到持续卡死的操作，在 opencode 中按 `ESC` 手动打断。
+持续卡死时，在 OpenCode 按 `ESC` 打断。
 
 ---
 
@@ -166,7 +166,8 @@ timeout 30 agent-browser --cdp 9222 eval "window.location.replace('https://www.q
 
 | 问题 | 解决方案 |
 |------|----------|
-| `NEEDS_CONSENT` + 退出码 3 | 用 AskUserQuestion 询问用户是否允许杀掉 Chrome，同意后加 `--yes` 重跑 |
+| `NEEDS_CONSENT` + 退出码 3 | 询问用户是否允许结束现有 Chrome，同意后加 `--yes` 重跑 |
+| `CHROME_INSTALLED=no` 或来源 profile 不存在 | 安装并使用 Chrome 一次；已有其他 profile 时用 `--profile` 指定 |
 | CDP 端口未监听 | `--detect-only` 再确认；端口被占用则换端口 |
 | 页面跳转到登录页 | `snapshot -i` 找登录按钮并操作 |
 | `eval` 返回 `null` | 检查 localStorage key 名；含引号的 JS 用 `eval -b` 或 `--stdin` |