@oh-story/dsh 0.1.15 → 0.1.16

package/lib/oh-story/skills/story-short-write/references/submission-craft.md

@@ -1,10 +1,10 @@
 # 投稿范式：平台基调 · 导语 · 付费点
 
-> 短篇是投出去过稿的，不是写完就算。这份文件管三件投稿层的事：按平台定基调、单独打磨导语、把付费点卡在断点上。题材招式仍按 `genre-styles/{题材}.md`，本文只叠加"投稿怎么写才收得掉"这一层。
+> 投稿前按平台定基调、单独打磨导语，并设计付费断点；题材招式按 `genre-styles/{题材}.md`。
 
 ## 一、先定平台基调
 
-动笔前先确认投稿平台，正文的视角、矛盾烈度、章末钩子、结局质感随之切换。三大主流基调：
+动笔前确认投稿平台，结合本篇目标情绪选择视角、矛盾烈度、章末钩子与结局质感。以下基调用作创作参考：
 
 | 平台 | 视角 | 矛盾演进 | 章末钩子 | 结局质感 |
 |---|---|---|---|---|
@@ -12,24 +12,24 @@
 | 小程序 | 上帝视角或强情绪第一人称，开局即地狱 | 冲突全外化到对白和动作，走"被羞辱→亮底牌→当众打脸→夺实利"快循环 | 卡脖子断点（巴掌将落、协议撕一半、话说一半） | 直白粗暴的爽，反派付实质代价（破产/入狱/众叛亲离），主角高位不留遗憾 |
 | 番茄短篇 | 流畅第一/第三人称，目标清晰、金手指直白 | 顺滑无毒点，反派挑衅一两节内转成主角升级/发财的垫脚石 | 开新地图 / 拿到新底牌 / 新人物带资源登场 | 圆满畅快，事业感情双收，坏人受罚 |
 
-- 小程序收稿量最大，打脸爽文是主力盘；同一个脑洞可以分别按知乎/小程序/番茄各跑一版，挑最顺的投。
-- 基调只调"声音和落点"，不覆盖题材招式和本篇目标情绪。基调是投放渠道的声音，与 `short-format.md` 的排版模板是两个轴——小程序基调的稿，排版仍按 short-format 选一套 app 模板。
+- 同一个脑洞可以分别按知乎/小程序/番茄试写，比较声音与落点后选择投稿方向。
+- 平台基调须与题材招式及本篇目标情绪配合；排版另按 `short-format.md` 选择，小程序基调的稿也要选定一套平台模板。
 - **调基调不松去 AI 底线**：强情绪靠具体动作和对白落地，别把话硬拆成三字碎句成片排列；前情背景靠场景带出，别整段插叙成"来龙去脉"说明书；对仗句式（"上辈子…这辈子…"）别高频复用。去 AI 味仍按本套件既有规则。
 
 ## 二、导语（投稿门面，单独打磨）
 
-导语是正文最前面的引子，也是编辑第一眼看的东西。编辑一天审几百篇，**导语不行，正文再好也被一眼刷掉**。所以导语要单独当一件作品来打磨，别指望编辑往下翻。
+导语是正文最前面的引子，要让编辑和读者尽快看清核心冲突与继续读的理由。
 
-- **长度与形态**：约 150-220 字（题材包如写 150-300，投稿时按此收紧），就是正文开头那几段。一句一段指完整句各自独立成段，不是把整句拆成三字碎句；这是黑岩/盐言导语的形态，番茄导语按 `short-format.md` 该平台的短段叙织即可。导语写完即接正文（内容本身就是第一章开头，不重写）。
+- **长度与形态**：约 150-220 字，题材包如写 150-300，投稿时按此收紧。黑岩/盐言用完整句各自成段，番茄按 `short-format.md` 的短段模板。导语就是正文开头几段，写完顺接后文。
 - **四维骨架**：起因（悲剧源头或荒诞开端）+ 核心冲突（被凝视、被剥削、被算计的绝境）+ 人设底色（清醒、有底牌，不是纯惨）+ 情绪反转（钩子卡在最后半句，戛然而止）。
 - **黄金三角**：一个有冲击力的具体物件（撕碎的 B 超单、代持协议、落灰的旧相机）+ 一个信息差（主角藏在暗处的底牌，读者知道、施害者不知道）+ 一个留白的致命钩子。
 - **反面**：别用导语平铺背景或抒情；别把底牌全亮完（留给正文兑现）；别只写惨不写"她有后手"。
 
 ## 三、付费点（投稿结构）
 
-短篇按"免费试读 + 付费点 + 付费正文"投稿（投稿语境的"章"即本 skill 的"节"）。付费点是免费段和付费段的分界，卡不好读者不付费，卡对了转化高。
+采用付费试读的短篇按"免费试读 + 付费点 + 付费正文"组织，投稿语境的"章"即本 skill 的"节"。分界处要留下读者正在等待的答案或后果。
 
-- **断点位置**：付费点卡在一个章末的卡脖子断点上——一个即将揭晓、读者必须付费才能看到的反转或对决瞬间（亲子鉴定撕开一半、底牌刚要拍上桌、名字念到一半）。别把核心大爽点在免费段全放完。
+- **断点位置**：在章末截住即将揭晓的反转或对决，如亲子鉴定撕开一半、底牌刚要拍上桌、名字念到一半，让付费段兑现尚未完成的动作。核心大爽点不要在免费段全部放完。
 - **剧情点密度**：付费点前完成处境、选择与代价的因果链，付费点后集中兑现已经承诺的打脸、反转或爽点。相关变化可由同一动作链完成，不按每章数量补剧情点；连续单元没有状态变化才复核是否停滞。
 - **反推法排细纲**：先定付费点卡在第几节章末，先把那一节的剧情想透（如复仇虐爽：前几节情绪递进越来越虐，付费点节章末预示反击），再倒推安排前面各节"情绪冲突逐渐递进"，最后排付费点之后的兑现段。
 - **投稿成品形态**：标题 + 导语（不写"导语"二字，只留那几句）+ 数字分节的正文（含付费点断点）。投稿建议区间比 SKILL 框架（8000-20000）更收敛：整篇约 8000-12000 字；分节数量与长度服从动作链、转场和付费断点，不设统一章长。

package/lib/oh-story/skills/story-short-write/references/villain-and-reveal.md

@@ -1,12 +1,10 @@
-# 反派系统 + 真相揭露机制
+# 反派设计与真相揭露
 
 > 反派设计模板、真相揭露方式、报应设计。Phase 2 设计反派时加载。
 
 ---
 
-**本文件职责**（其他内容去哪看）：
-- 各题材的反派套路（世情打脸反派、重生复仇反派等）已在 genre-writing-formulas.md，本文件只提供通用设计模板
-- 本文件的反派人设模板 `{身份}+{动机}+{作恶方式}+{致命弱点}` 侧重「设计蓝图」，genre-writing-formulas.md 的 `{人设}+{动机}+{行为}+{态度}+{受伤害程度}` 侧重「矛盾冲突公式」——前者用于 Phase 2 设计，后者用于 Phase 3 写作
+按题材决定反派的恶行与关系压力，再用以下模板记录身份、动机、手段、弱点与报应。
 
 ---
 
@@ -27,7 +25,7 @@
 
 ### 嚣张度递增阶梯
 
-反派行为必须逐级递增，不跳跃也不重复：
+按前因与损失加重反派行为，避免重复同一种恶行；下表展示一种升级路径：
 
 | 级别 | 行为类型 | 示例 |
 |------|----------|------|
@@ -39,11 +37,11 @@
 
 | 类型 | 特征 | 代表作 | 致命弱点 |
 |------|------|--------|----------|
-| 操控型 | 以爱为名控制一切 | 王氏（皇弟） | 控制欲导致行事留下证据 |
+| 操控型 | 以爱为名控制一切 | 王氏（《皇弟欺负幼子》） | 控制欲导致行事留下证据 |
 | 贪婪型 | 无底线索取 | 准儿媳 | 贪心过度暴露真面目 |
-| 伪装型 | 隐藏真实身份/目的 | 诈骗犯（重生弟弟） | 身份经不起调查 |
-| 嚣张型 | 仗势欺人，有恃无恐 | 萧琅（皇弟） | 傲慢导致不看身后 |
-| 软刀型 | 示弱博同情，暗中操控 | 妈妈（姐夫捎路） | 假面被证据击碎 |
+| 伪装型 | 隐藏真实身份/目的 | 女友（《重生弟弟》中的诈骗犯） | 身份经不起调查 |
+| 嚣张型 | 仗势欺人，有恃无恐 | 萧琅（《皇弟欺负幼子》） | 傲慢导致不看身后 |
+| 软刀型 | 示弱博同情，暗中操控 | 妈妈（《姐夫捎路要奶粉钱》） | 假面被证据击碎 |
 
 ---
 
@@ -116,7 +114,7 @@
 
 ### 规则
 
-报应必须与恶行形成对应。恶行有多重，报应就有多重。
+报应须与恶行及其后果对应，让读者看清反派为何承担这一代价。
 
 ### 对应原则
 
@@ -138,7 +136,7 @@
 
 ### 报应强度校准
 
-- 报应强度 = 恶行强度 × 1.0-1.2（不过度也不轻描淡写）
+- 按恶行、受害后果与本篇情绪决定报应强度，避免轻轻放过或无因夸大
 - 不写长段报应描写，2-3 句带过，留白给读者
 - 报应的「爽」来自对应感，不是来自描写长度
 
@@ -146,8 +144,8 @@
 
 ## 4. 反转有效性自检（Phase 2 使用）
 
-写完 outline 后按 writing-workflow.md「反转信息差验证」逐项过：揭示时机按功能定（误判先参与至少一次重要决定），百分比只记录、不当阈值。本文件只补两条：
+写完大纲后按 writing-workflow.md「反转信息差验证」检查，先让误判参与至少一次重要决定，再揭示真相；位置百分比只作记录。另查：
 - 反转前读者和角色至少有一方不知道真相；没有就制造信息差（读者不知道 / 角色不知道 / 双方都不知道）。
 - 假线索用红鲱鱼或选择性叙述；真相线索藏在日常细节里，回看能找到、正读会忽略，不用强调语气。
 
-**失败模式**：「延迟揭露」不算反转。读者在第 2 节就知道真相，后面 10 节只等角色追上来 = 延迟揭露，读者会无聊。真正的反转发生在揭示那一刻，让读者和角色一起震惊。
+**失败模式**：读者早已知道真相，后续只等角色追上来，却没有新行动或代价。此时只有角色获知信息；若目标是让读者震惊，揭示还须推翻读者此前的判断。

package/lib/oh-story/skills/story-short-write/references/workflow-design.md

@@ -4,7 +4,9 @@
 
 已部署 story-architect 时可 spawn `Agent(subagent_type: "story-architect", prompt: "项目目录：{dir}\n任务类型：短篇构思\n查询参数：{目标情绪+题材方向}")` 辅助框架设计；不可用由主会话直接执行。
 
-帮用户确定短篇的核心框架：
+与作者确定核心框架：
+
+情绪设计中的反转项仅用于有反转篇；无反转时在该位置记录报应兑现或甜度变化，按本篇设计安排高潮。
 
 ```
 ## 短篇核心框架
@@ -43,20 +45,20 @@
 - {作者在对话里定下的人称、偏好、红线，一条一行；否掉的方案也记一行，写明为什么不要}
 ```
 
-框架确定后，完成设计任务，然后在工作目录下创建文件。
+框架确定后按以下任务设计，再将结果写入工作目录。
 
 #### 设计任务（框架确定后执行）
 
-详细步骤和模板见 `references/writing-workflow.md`。构思时从目标情绪反推剧情，不是从灵感正向构建。按顺序完成：
+从目标情绪反推剧情，按 `references/writing-workflow.md` 的步骤和模板依次完成：
 
-1. 定平台基调 + 加载题材风格包 → 先读 `references/submission-craft.md` 定投稿平台（知乎/小程序/番茄），正文视角、矛盾烈度、章末落点随之切换；再读 `references/genre-styles/{题材}.md`（核心 10 题材）+ 通用底座 `references/short-craft.md`，从招式库选 2-3 个核心招式（如追妻的白月光触发链 / 信物翻转 / 火葬场预告），写入 设定.md「题材招式」区，全程照此招式与腔调写；冷门题材把所用公式要点按模板一并写进该区，写正文与精修不再重读公式全文
-2. 设计反派（如有）→ 加载 `villain-and-reveal.md`
-3. 确定揭露方式 → 同上
-4. 编写 小节大纲.md（12 列表格见 writing-workflow.md，只做轻量蓝图）。**标出付费点卡在哪一节末**（见 `submission-craft.md`「付费点」：用未完成动作、身份/证据变化或两难选择形成真实断点）；用反推法先想透付费点那一节，再倒排前后。每节可选一个任务卡点，但必须服务情绪升级、证据推进、关系撕裂、反转铺垫或反击动作；没有就不强补
+1. 定平台基调并加载题材风格包：先读 `references/submission-craft.md`，定投稿平台及正文视角、矛盾烈度、章末落点；再读核心 10 题材对应的 `references/genre-styles/{题材}.md` 和通用方法 `references/short-craft.md`，选 2-3 个核心招式，写明本篇用法并存入 `设定.md`「题材招式」。冷门题材将所用公式要点按模板写入该区，供正文与精修直接使用
+2. 设计反派（如有）：加载 `villain-and-reveal.md`
+3. 确定揭露方式：按同一文件选择；无需揭露时写明原因
+4. 编写 `小节大纲.md`，使用 writing-workflow.md 的 12 列表格。**标出付费点卡在哪一节末**：按 `submission-craft.md`「付费点」，用未完成动作、身份/证据变化或两难选择形成断点；先想透该节，再倒排前后。任务卡点仅在能推动情绪、证据、关系、反转或反击时使用
 5. 反转信息差验证（公式见 writing-workflow.md）
 6. 伏笔回查清单（标准见 writing-workflow.md）
 
-`设定.md` 必须包含以下机器可验收字段（内容本身也是后续写作依据，不是读文件回执）：
+将以下设计字段写入 `设定.md`，供机器验收与后续写作使用：
 
 ```markdown
 ## Phase 2 设计校验
@@ -78,7 +80,7 @@
 
 两份文件生成后、向用户声明构思完成或进入 Phase 3 前，运行 `node scripts/check-phase2-contract.js --json {短篇目录}`：
 
-- exit 0：Phase 2 机械契约通过，才可进入下一阶段；这不替代故事质量判断
+- exit 0：Phase 2 机械契约通过，可进入下一阶段；故事质量仍需判断
 - exit 1：只把 `repair_scope` 中的检查 ID、证据、期望、reference 路径和修复范围交给本轮 writer；只改失败字段，再运行同一命令
 - 最多做 2 轮定向 repair；仍失败则停止，用中文告诉作者设计还缺什么，不得声称 Phase 2 已完成
 - exit 2、脚本缺失或不可执行：告诉作者自动检查没跑成，不得用泛化“自检”替代后继续

package/lib/oh-story/skills/story-short-write/references/workflow-draft.md

@@ -4,30 +4,30 @@
 
 **格式规范（最高优先级）**：正文只存 `正文.md`，主会话与写手同一套格式：段间只允许一个换行符、不留空行，小节标记与引号全篇统一，按 `设定.md`「平台基调」，没写才查 `short-format.md` 平台覆盖表；子代理输出不一致时按此重排。
 
-**构思收口先验**：写前先跑 `node {skill 根}/scripts/check-phase2-contract.js --json {短篇目录}`；不是 exit 0 就告诉作者构思还没收口、请回到构思补完，不自己重读构思方法论补写。
+**构思完成检查**：写前先跑 `node {skill 根}/scripts/check-phase2-contract.js --json {短篇目录}`；未返回 exit 0 时，告诉作者设计还缺什么，请其回到构思补完。
 
 **本时刻只靠落盘文件接上构思**：`设定.md`（核心框架、作者已定、平台基调、题材招式、反转铺垫、贯穿道具、反派与揭露方式、对标摘要）与 `小节大纲.md` 为 Phase 2 产出，`正文.md` 为本阶段产出。反转、反派、揭露、付费点与平台基调以两份设计文件为准，不重读构思方法论（workflow-design、writing-workflow、short-reversal、submission-craft、villain-and-reveal、冷门题材公式全文）；作者在对话里改过、设计文件还没写的，先写回 `设定.md` 再动笔。
 
 **导入项目续写基线**：`设定.md` 存在「本书续写基线」时先读取，作为已写内容的内部连续性与既有写法约束；它不是对标摘要，不参与主/副对标排序，也不复制到 `对标/`。
 
-> 术语说明：Phase 3 按「段」划分叙事结构（开头段/铺垫段/升级段/反转段/结尾段），每段包含若干「小节」（数字编号的 beat）。「场景」指写作时的具体画面。
+> 下文的五「段」指开头、铺垫、升级、反转、结尾等结构部分，各含若干数字编号的「小节」；场景内按节拍（beat）安排动作与情绪变化。
 
-**写前加载**：`short-format.md`（正文格式）、`short-craft.md`（通用底座）、[scene-craft.md](scene-craft.md)（场景写法）、`设定.md` 题材参考里的那一个 `genre-styles/{题材}.md`（冷门题材不读公式，按「题材招式」区记下的要点写，腔调按 `short-craft.md`）；写羁绊铺设或余韵收尾时按需读 `emotional-methods.md` 对应一斧。`short-deslop.md` 到 Phase 4 去味时再读，写作中的 AI 腔由完成门槛的检测器兜底。
+**写前加载**：依次读 `short-format.md` 的正文格式、`short-craft.md` 的通用方法、[scene-craft.md](scene-craft.md) 的场景写法，以及 `设定.md` 题材参考指定的唯一 `genre-styles/{题材}.md`。冷门题材按「题材招式」区的公式要点写，腔调按 `short-craft.md`。写羁绊或余韵时按需读 `emotional-methods.md` 对应一斧；`short-deslop.md` 到 Phase 4 去味时再读，初稿先通过完成门槛的 AI 腔检测。
 
 **交付参数先锁定**：用户明确的字数范围优先，逐字取其最小值/最大值与节数；只给单一目标时用目标的 95%-105%；都未给时用 8000-20000 字和大纲节数。后文的默认字数不得覆盖用户范围。
 
 **写前参数验收（锁定后、写 `正文.md` 前必跑）**：`node {skill 根}/scripts/check-delivery-contract.js --json --check-contract --min-chars {MIN} --max-chars {MAX} --sections {N} [--min-section-chars {用户逐节下限}] {短篇目录}`。exit 0 只说明参数能同时满足，不算交付；exit 2 即冲突，停在写前，用中文告诉用户字数范围与节数哪里对不上，请其选择调整项，不代改用户约束。
 
-**写前准备**（每个场景写前执行 2 步，是核心方法的落地：确认目标情绪 → 召回技法模块）：
+**写前准备**：每个场景动笔前依次确认情绪与技法：
 - **步骤 1：记忆+召回**：① 本场景目标情绪词？② 借鉴哪个参考文件的哪个技法？③ 具体用在哪个段落？答不出 → 先回读本时刻已加载的参考再动笔。有对标时从 `设定.md`「对标摘要」召回 1-2 个与本场景相关的技法，要细看再查主对标 `对标/{书}/写作手法.md`（没有就用 `拆文库/{书}/`）的对应条目，写入“拆文召回摘要”
   - **多对标书时**：副对标只用「对标摘要」里构思时已登记的条目（正文阶段不新增召回），作为“副对标召回摘要”；正文只传摘要，不传副书文风或原文
-- **步骤 2：指令确认**：用一句话概括本场景写作意图（情绪+技法+适配段落），并确认本场景是否有任务卡点、它卡出哪种情绪变化或新证据；没有就不强补。确认后开始写作
+- **步骤 2：指令确认**：用一句话概括本场景的情绪、技法及使用位置；有任务卡点时说明它带来的情绪变化或新证据，确认后开始写作
 
 **写作指令**：写法按 `short-craft.md`（情绪直写与上下文支撑第 2 节、在场叙述第 3 节）与 `scene-craft.md`（三维度揉进与画面分段、疏密与主语节奏），段落与标点按 `short-format.md`，不照搬大纲腔。情绪烈度按 `设定.md` 与题材包的腔调，没写时默认宁烈不温（冲突前置、爽点具体、台词带刺）；任务卡点必须直接加重羞辱、误会、背叛、证据、反击或心死节点，删掉无损就压缩。
 
 #### 分批写与子代理
 
-正文写作阶段默认由主会话按 2-3 节/批分批写正文；主会话输出是短篇正文的标准形态，不要求单次 agent spawn 完成 8000+ 字全文。
+主会话默认按 2-3 节/批写正文，不要求单次 agent spawn 写完 8000+ 字。
 
 - 每批写完后更新短篇目录下 `.story/work/已写小节摘要.md`（3-5 条：已揭示信息、情绪位置、未回收伏笔、下一批衔接句），换对话靠它接上，交付后可删。
 - 下一批先读该摘要和 `正文.md` 尾部 300-500 字再续写。
@@ -40,13 +40,13 @@
 
 **节数守恒**：正文节数必须等于小节大纲规划节数。不得合并多节为一节。如果写作中发现某节不需要独立存在，应回到大纲阶段调整，而非在写作时偷减。
 
-按以下结构分段写（占比仅参考，以小节大纲为准）：
+按以下结构写作，占比仅参考，以小节大纲为准。无反转篇按设计写报应兑现或甜度递进；反转线索、误导与揭露要求仅用于有反转的篇目。反派与贯穿道具仅在设计中选用时执行相应要求。
 
 #### 第一段：开头（前 300-500 字）
 
 **目标**：3 句话内抓住读者。**必须包含一个开篇钩子**（从下表或题材包「开篇范式」选类型）。
 
-**先写导语**：正文开头先写一条 150-220 字导语（投稿门面，编辑第一眼看它）——四维骨架（起因+核心冲突+人设底色+情绪反转）配黄金三角（具体物件+信息差+留白钩子），一句一段（黑岩/盐言导语形态；番茄导语按 short-format.md 短段叙织）——完整句各自独立成段，不是拆成三字碎句。它就是正文开头的头几段，写好顺势往下接、不重写，所以首句同样守下面的开头零环境和前 100 字事件密度≥3（首句是事件/动作/信息炸弹，不是背景或弧线概括），剧透钩子放导语后半；不平铺背景或抒情，底牌不全亮（留给正文兑现），不只写惨不写后手。
+**先写导语**：正文以 150-220 字导语开篇，交代起因、核心冲突、人设底色与情绪反转，结合具体物件、信息差与留白钩子。黑岩/盐言用完整句各自成段，番茄按 short-format.md 短段叙述。导语就是正文头几段，写完顺接后文。首句从事件、动作或信息炸弹起笔，遵守下方开头零环境规则及前 100 字事件密度≥3；剧透钩子放导语后半，留住底牌，也让读者看到主角的后手。
 
 **开头零环境规则**（默认适用；悬疑、惊悚、灾难、强氛围题材可例外）：
 - 前 3 句禁止出现无事件承载的环境描写（灯光、天气、气味、温度、装修）
@@ -86,7 +86,7 @@
 - 随风险和选择升级提高牵引强度；用新证据、代价、误判修正或局部反击推动，不按固定节数另塞钩子（按题材包）
 - 埋入误导信息，让读者猜错反转方向
 - **数字/金额递增作为叙事工具**（具体数字替代模糊描述，见各 genre-styles 招式库「数字承重」）
-- **场景引擎有变化**：行动、对话、证据、任务、等待、空间压力与关系选择按因果需要切换；不为动静交替补无功能小动作
+- **场景引擎有变化**：按因果需要切换行动、对话、证据、任务、等待、空间压力与关系选择
 
 #### 第四段：反转（占全文 10-15%）
 
@@ -108,7 +108,7 @@
 | 类型 | 效果 | 适合情绪 |
 |------|------|----------|
 | 余韵式 | 不说完，让读者自己想 | 意难平 |
-| 呼应式 | 首尾呼应，形成闭环 | 治愈、成长 |
+| 呼应式 | 首尾的物件、动作或话语形成呼应闭环 | 治愈、成长 |
 | 开放式 | 留下悬念 | 细思极恐 |
 | 反转再反转 | 结尾再来一个小反转 | 震惊 |
 | 金句式 | 一句话点题 | 共鸣 |

package/lib/oh-story/skills/story-short-write/references/workflow-revision.md

@@ -2,7 +2,7 @@
 
 本文件中的 `scripts/` 与 `references/` 路径均相对本 skill 根目录。精修必读本文件与 `short-format.md`（格式快速检查、字数口径）；新对话里精修也先读它。
 
-Phase 3 写手只做内容覆盖与格式自检（该分工随写作 prompt 传入）。Phase 4 去味由一个执行者（下方 narrative-writer 或主会话）按 `references/short-deslop.md` 自检清单完成；一致性检查职责不变。S1/S2 与 blocking 必须修，S3 与 advisory 建议看，S4 仅提示。最终扫描与交付验收由主会话对落盘文件执行，修改后只复核改动、重跑受影响检查，不另开整轮去味。
+Phase 3 写手只做覆盖与格式自检。Phase 4 由 narrative-writer 或主会话一方读 `references/short-deslop.md` 与 `references/deslop-gates.md`，定点修复清单及检测问题，再查一致性；完整三层诊断另走 `/story-deslop`。S1/S2 与 blocking 必须修，S3 与 advisory 建议看，S4 仅提示。主会话最终扫描、验收；改后只复核改动并重跑受影响检查。
 
 按文末「精修清单」完成检查。文件模式依次运行 `node scripts/check-ai-patterns.js --check --fail-on=blocking 正文.md`、`node scripts/check-outline-copy.js --outline 小节大纲.md 正文.md`、`node scripts/normalize-punctuation.js 正文.md`、`node scripts/check-degeneration.js --check 正文.md`，blocking 先改正文再复扫。照搬检测报出的誓词、关键原话等功能性台词保留，登记进 `小节大纲.md` 末尾「复沓锚句」再复检，其余现场重写。
 
@@ -12,9 +12,9 @@ Phase 3 写手只做内容覆盖与格式自检（该分工随写作 prompt 传
 
 已部署对应 agent 时可派出：narrative-writer 去味的 prompt 见 [agent-calls.md](agent-calls.md)「精修去味」；一致性检查派 `Agent(subagent_type: "consistency-checker", prompt: "项目目录：{dir}\n检查范围：{正文文件}\n检查类型：事实冲突+伏笔断线+角色属性不一致")`。agent 不可用时主会话直接执行。
 
-**正文洁净规则**：自检（字数、禁用词、格式）结果只在对话里说明，不落盘成文件，**绝对不能**附到正文末尾，正文不得出现 `<!-- 自检 -->` 等检查标记。
+**正文洁净规则**：自检结果只在对话中说明，不另存或附正文；正文不得出现 `<!-- 自检 -->` 等检查标记。
 
-**交付说明（给作者看）**：只用大白话，按三块写：
+**交付说明（给作者看）**：用白话说明：
 1. 写了什么：标题、一句话核心钩子或反转、总字数、几节。
 2. 要作者拍板的事：每件写成一句问题并附推荐默认（如「结尾要不要再留个小反转？默认不留」）；没有就省略。
 3. 下一步可选：精修某段、去 AI 味、换平台改写等。
@@ -25,6 +25,8 @@ Phase 3 写手只做内容覆盖与格式自检（该分工随写作 prompt 传
 
 ### 精修检查清单
 
+反转项仅用于反转篇；无反转时核对核心兑现与关系递进。
+
 ```
 ## 精修清单
 
@@ -56,10 +58,10 @@ Phase 3 写手只做内容覆盖与格式自检（该分工随写作 prompt 传
 - [ ] 章末是否有未完成动作、新信息、局部兑现、关系变化、余韵或明确下一步之一？
 
 ### AI 腔
-- [ ] 无禁止比喻：「命运的齿轮」「如潮水般」「仿佛春风」「心猛地一沉」「眼眶泛红」
+- [ ] 比喻、情绪词与反应有上下文作用；不凭「如潮水般」「心猛地一沉」「眼眶泛红」孤立词句判错
 - [ ] 重复的身体/情绪描写按功能取舍：无新增信息就删，不换部位或同义动作凑数
 - [ ] 「像/好像/仿佛/如同」不成片堆叠；超过 10 处或检测器报比喻密度时逐处复核功能，有功能的留，不设硬上限、不机械全删
-- [ ] 完整 AI 腔黑名单见 short-deslop.md
+- [ ] 检测候选已逐处按功能复核，短篇卖点保护见 short-deslop.md
 
 ### 技法
 - [ ] 情绪落地：按 `short-craft.md` 第 2 节检查上下文支撑，保留准确直写，清理空泛与重复说明
@@ -72,10 +74,9 @@ Phase 3 写手只做内容覆盖与格式自检（该分工随写作 prompt 传
 - [ ] 读者会不会想转发？
 ```
 
-### 标点确定性收尾
+### 标点收尾
 
-精修后对 `正文.md` 先运行 `node scripts/check-ai-patterns.js --check --fail-on=blocking 正文.md`。blocking 先改正文并复扫；advisory 只作读感提示，确属问题才改，功能性写法标 `[需复核]`。
-再运行 `node scripts/normalize-punctuation.js 正文.md`（默认 `--quote-mode keep`）清理无功能省略号、破折号、双连字符和独立分隔线；盐言「」不受影响。
+按本文件开头的文件扫描顺序，先运行 `node scripts/check-ai-patterns.js --check --fail-on=blocking 正文.md`，修正 blocking 后复扫；advisory 结合读感判断，功能性写法标 `[需复核]`。再运行 `node scripts/normalize-punctuation.js 正文.md`，默认 `--quote-mode keep`，清理无功能省略号、破折号、双连字符和独立分隔线，保留盐言「」。
 
 ### 删减原则
 
@@ -92,7 +93,7 @@ Phase 3 写手只做内容覆盖与格式自检（该分工随写作 prompt 传
 | 反转没力度 | 铺垫不够或太明显 | 增加误导线索 |
 | 结尾无力 | 反转后还在补交代 | 篇幅按小节大纲；反转后只写兑现与余韵 |
 | 全篇平淡 | 情绪曲线太平 | 加大情绪落差 |
-| 感觉像流水账 | 缺乏情绪描写 | 加入人物内心感受 |
+| 感觉像流水账 | 事件没有改变判断、选择或情绪 | 补清事件后果及人物回应，删掉无变化的复述 |
 
 ### 冷门题材公式核对
 

package/lib/oh-story/skills/story-short-write/references/writing-workflow.md

@@ -1,6 +1,6 @@
 # writing-workflow.md：短篇写作工作流详解
 
-Phase 2 设计任务的步骤与验收；Phase 4 精修清单在 workflow-revision.md。
+Phase 2 按本文件完成设计与验收；Phase 4 精修按 workflow-revision.md。
 
 ---
 
@@ -12,7 +12,7 @@ Phase 2 设计任务的步骤与验收；Phase 4 精修清单在 workflow-revisi
    - 填写：`- 第1次出现（第X节）：{场景}（{含义}）` 重复三次，含节号定位
 2. **设计反派**（如有）：用 villain-and-reveal.md 反派模板
    - 填写：`{身份} + {动机} + {作恶方式} + {致命弱点} + {报应}`
-3. **确定揭露方式**：从 villain-and-reveal.md 4 种真相揭露机制中选一种，写进 设定.md 反派设计区
+3. **确定揭露方式**：需要揭露真相时，从 villain-and-reveal.md 的 4 种机制中选择，写进 `设定.md` 反派设计区；无需揭露时写明原因
 4. **编写 小节大纲.md**：使用固定 12 列 Markdown 表格，每节 1 行，表头如下（列名和顺序不可改）：
 
    `| 结构段/五段功能 | 主事件 | 情节推进 | 情绪 | 人物/关系变化 | 因果/逻辑链 | 读者新获知什么 | 结尾承接/钩子 | 伏笔/物件 | 场景形态 | 对白作用 | 目标字数 |`
@@ -27,7 +27,7 @@ Phase 2 设计任务的步骤与验收；Phase 4 精修清单在 workflow-revisi
      `具体发生了什么{功能标签}` 如 `发现账单上多了一笔4800{发现}` / `把戒指冲进马桶{冲突}` / `他笑了{递进}`
      功能标签：`对话` / `冲突` / `伏笔` / `回忆` / `发现` / `递进`
      情节点描述要具体到"谁做了什么"，不能只写标签如`对话`或`冲突`
-   - `场景形态` 写主要推进引擎，如行动、对话权力、证据核验、手艺、等待、空间压力或关系回落；不要求动静交替
+   - `场景形态` 写主要推进引擎，如行动、对话博弈、证据核验、手艺、等待、空间压力或关系回落；不要求动静交替
    - `对白作用` 写对白实际改变的信息、策略、权力、关系或下一步行动；无对白时写明由哪种动作、证据、物件或任务推进，不设占比或话轮数量
 5. **反转信息差验证**（outline 写完后、写作前必须验证）：
    - `short-reversal.md` 判为无反转 → 写明理由，改查报应因果或甜度期待是否经过铺垫并得到兑现；跳过以下揭示检查
@@ -46,5 +46,5 @@ Phase 2 设计任务的步骤与验收；Phase 4 精修清单在 workflow-revisi
 
 ### 设定.md 内容构成
 
-核心框架（含平台基调、人设速写）+ 作者已定 + 题材招式 + 反转铺垫（信息差验证与伏笔回查结果）+ 贯穿道具 + 反派设计与揭露方式 + 对标摘要；写正文只读它与小节大纲，所以构思里定下的都要写进来。贯穿道具追踪表：
+将核心框架、平台基调、人设速写、作者已定、题材招式、反转铺垫验证、贯穿道具、反派与揭露方式、对标摘要写入 `设定.md`，正文阶段靠它与小节大纲接续构思。贯穿道具追踪表：
 `| 物件 | 第1次出现(节号/含义) | 第2次出现(节号/含义) | 第3次出现(节号/含义) |`

package/lib/types/role-tool.d.ts

@@ -1,12 +1,52 @@
 import type { Context } from "@deepseek-ai/cordis";
-import type { SubagentRuntime } from "@deepseek-ai/dsh-subagent";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { ContentBlock } from "@deepseek-ai/dsh-llm";
+import type { Session, SessionId } from "@deepseek-ai/dsh-session";
+import type { SubagentResult } from "@deepseek-ai/dsh-subagent";
 import { type ToolDefinition } from "@deepseek-ai/dsh-tools";
 import { type OhStoryRoleName } from "./role-provider.js";
 export declare const OH_STORY_ROLE_TOOL_NAME = "oh_story_role";
-export type OhStoryRoleSubagents = Pick<SubagentRuntime, "start">;
+interface RoleStartRequest {
+    readonly label: string;
+    readonly prompt: ContentBlock[];
+    readonly parent: Agent;
+    readonly persona: string;
+    readonly toolFilter: {
+        readonly allow: readonly string[];
+    };
+    readonly maxDepth: number;
+    readonly signal: AbortSignal;
+}
+interface RoleRun {
+    readonly id: string;
+    readonly localAgent?: {
+        readonly session: Session;
+    };
+    readonly result: Promise<SubagentResult>;
+    dispose(): Promise<void>;
+}
+interface ManagedRoleSpec {
+    readonly provider: string;
+    readonly label: string;
+    readonly childId: SessionId;
+    readonly request: Pick<RoleStartRequest, "parent" | "prompt" | "maxDepth">;
+    readonly signal: AbortSignal;
+    readonly delivery: "caller";
+}
+/** Local seam types also let TypeScript consumers use the older DSH declarations. */
+export type OhStoryRoleSubagents = {
+    startActivation(spec: ManagedRoleSpec): Promise<{
+        readonly childId: SessionId;
+        readonly result: Promise<SubagentResult>;
+        dispose(): Promise<void>;
+    }>;
+} | {
+    start(provider: string, request: RoleStartRequest): Promise<RoleRun>;
+};
 export declare function roleToolFilter(role: OhStoryRoleName): {
     readonly allow: readonly string[];
 };
 export declare function createOhStoryRoleTool(subagents?: OhStoryRoleSubagents): Promise<ToolDefinition>;
 export declare function registerOhStoryRoleTool(context: Context): Promise<void>;
+export {};
 //# sourceMappingURL=role-tool.d.ts.map

package/lib/types/role-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role-tool.d.ts","sourceRoot":"","sources":["../../src/role-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAOzE,OAAO,EAAwC,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEhG,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AACvD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAelE,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAE3F;AAMD,wBAAsB,qBAAqB,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqErG;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa7E"}
+{"version":3,"file":"role-tool.d.ts","sourceRoot":"","sources":["../../src/role-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAOzE,OAAO,EAAwC,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEhG,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AACvD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,UAAU,OAAO;IACf,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,qFAAqF;AACrF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC;QAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;QACzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1B,CAAC,CAAC;CACJ,GAAG;IACF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE,CAAC;AAqEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAE3F;AAMD,wBAAsB,qBAAqB,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqErG;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC7E"}

package/lib/types/skill-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-provider.d.ts","sourceRoot":"","sources":["../../src/skill-provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAyNhC,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAuBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAa7D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAKhD;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAK9C;AAED,wBAAgB,2BAA2B,IAAI,MAAM,CAKpD;AAuDD,wBAAgB,0BAA0B,CAAC,SAAS,SAA4B,GAAG,aAAa,CAE/F;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAA0B,GAAG,MAAM,CAM/G;AAED,wBAAgB,wBAAwB,CAAC,SAAS,SAA0B,GAAG,aAAa,CAE3F;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,wBAAgB,8BAA8B,CAAC,SAAS,SAAgC,GAAG,aAAa,CAEvG;AAED,wBAAgB,0BAA0B,IAAI,MAAM,CAKnD;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,wBAAgB,6BAA6B,CAAC,SAAS,SAA+B,GAAG,aAAa,CAErG"}
+{"version":3,"file":"skill-provider.d.ts","sourceRoot":"","sources":["../../src/skill-provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAkNhC,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAuBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAa7D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAKhD;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAK9C;AAED,wBAAgB,2BAA2B,IAAI,MAAM,CAKpD;AAuDD,wBAAgB,0BAA0B,CAAC,SAAS,SAA4B,GAAG,aAAa,CAE/F;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAA0B,GAAG,MAAM,CAM/G;AAED,wBAAgB,wBAAwB,CAAC,SAAS,SAA0B,GAAG,aAAa,CAE3F;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,wBAAgB,8BAA8B,CAAC,SAAS,SAAgC,GAAG,aAAa,CAEvG;AAED,wBAAgB,0BAA0B,IAAI,MAAM,CAKnD;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,wBAAgB,6BAA6B,CAAC,SAAS,SAA+B,GAAG,aAAa,CAErG"}

package/lib/video-recap/CHANGELOG.md

@@ -10,6 +10,14 @@ All notable changes to this project are documented here.
 
 ## [Unreleased]
 
+### Fixed
+
+- **技能与帮助说明按现有实现精修。** 补齐视频理解各远程路径发送的内容及关闭方式，澄清新字幕降级与原片硬字幕、实测字幕带的默认透明度、采用配音的速度策略，以及原声底轨的整数采样长度；删除不存在的 picture-plan 路径，纠正 TTS 前检查与成片看片的时序。双语 README 同步实际安装、缓存续跑与素材库行为；badcase、配对示例及真实媒体产物保留。七个技能包各升补丁号并同步编排依赖。
+
+### Changed
+
+- **七个 SKILL.md 的 `description` 改成单行。** 原来的 `description: >` 折叠块在 OpenClaw 只认单行键值的退路解析器下读不到完整描述；现在每条都是一行，文字与原折叠块解析后的值完全相同。新增测试要求 `description` 非空、不是 `>` / `|` 块、不超过 1024 字符。七个 ClawHub 包各升一个补丁号（video-recap 仍为 blocked，伴随依赖同步到新版本）。
+
 ## [0.6.2] - 2026-10-03
 
 用 dub 模式的命令（包括旧 `work_dir` 打印的续跑命令）都要补上 `--confirm-voice-rights`，否则在外发任何音频之前报错退出；只在有权使用这段视频、且说话人同意被克隆声音时确认。

package/lib/video-recap/README.en.md

@@ -1,5 +1,3 @@
-<!-- Last synced with README.md: 2026-09-20 -->
-
 <p align="center">
   <img src="https://zenstory.ai/brand/zenstory-ai-mark.svg" alt="" width="76" height="76">
 </p>
@@ -23,7 +21,7 @@
 <p align="center">
   <a href="https://github.com/zenstory-ai/video-recap-skills/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/zenstory-ai/video-recap-skills?style=flat-square&color=22D3EE&logo=github&logoColor=white&label=Stars"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/zenstory-ai/video-recap-skills?style=flat-square&color=081431&label=Release"></a>
-  <img alt="Skills 6" src="https://img.shields.io/badge/Skills-6-081431?style=flat-square">
+  <img alt="Skills 7" src="https://img.shields.io/badge/Skills-7-081431?style=flat-square">
   <a href="https://www.python.org/"><img alt="Python 3.10%2B" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/actions/workflows/skill-validate.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/zenstory-ai/video-recap-skills/skill-validate.yml?style=flat-square&label=CI"></a>
   <a href="https://platform.xiaomimimo.com"><img alt="AI Xiaomi%20MiMo" src="https://img.shields.io/badge/AI-Xiaomi%20MiMo-34A853?style=flat-square"></a>
@@ -43,16 +41,16 @@ The 59-second landscape recap above, *Guohuo (这一秒过火)*, is the final de
 Seven skills (six for production plus one on-demand reference skill) install into Claude Code, Codex CLI, OpenCode, or OpenClaw. You give the video paths and the recap you want in plain language; the agent understands picture and dialogue, decides the story and audiovisual plan, cuts, writes, voices, mixes, and subtitles. Supported inputs: `.mp4 / .mov / .mkv / .webm`.
 
 - **One key, ffmpeg locally.** ASR, VLM, and TTS all go through [Xiaomi MiMo](https://platform.xiaomimimo.com); the local runtime is Python's standard library plus `ffmpeg`, with no GPU, no `pip install`, and no model downloads. Voiceover can switch to Fish Audio, which replaces only that stage.
-- **The editorial decision comes before the sound allocation.** The agent compares edit hypotheses first, writes the viewer promise, POV, dramatic question, and change-based beats into `recap_story_plan.json`, then assigns each beat a picture job and an audio owner: narration is voiced as a block only when it has a defined job, and strong dialogue, action sound, or silence may own an entire beat.
-- **Cut first, narrate second, so the timeline is aligned by construction.** Cut mode renders the shortened video first and writes narration against that output timeline; feed several videos at once and pick ranges by `source_id` to cut one story spine; each video's analysis is saved to a filesystem material library for reuse.
+- **The editorial decision comes before the sound allocation.** For a new concept, the agent compares viable edit directions; for a directed task or viewing feedback, it follows the current decisions. It records the viewer promise, POV, dramatic question, and change-based beats in `recap_story_plan.json`, then assigns each beat a picture job and an audio owner: narration is voiced as a block only when it has a defined job, and strong dialogue, action sound, or silence may own an entire beat.
+- **Cut first, narrate second, so the timeline is aligned by construction.** Cut mode renders the shortened video first and writes narration against that output timeline; feed several videos at once and pick ranges by `source_id` to cut one story spine; analysis can be saved to a filesystem material library and reused when the source and settings match.
 - **Keep editing after the render.** The multi-track `timeline.json` exports to a JianYing draft with editable source clips, narration, BGM, subtitles, and image overlays; drop in an accurate subtitle file and it becomes the preferred source for original-dialogue captions.
-- **Every step leaves a record you can check.** Narration lint, assembly QC, delivery QC, and the revision log are machine-readable files.
+- **Every step leaves a record you can check.** Narration lint, assembly QC, and final QC produce machine-readable reports. Viewing revisions can separately record changes, frozen items, and verification.
 
 ## Install
 
 ### ClawHub
 
-ClawHub distribution is governed by the repository's [explicit publish inventory](.clawhub/publish.json), with discovery through [ClawHub](https://clawhub.ai/). A skill-specific link is added here only after its publisher, version, and anonymous accessibility are verified, so this README never presents a nonexistent listing as live.
+ClawHub entries and dependencies are governed by the [explicit publish inventory](.clawhub/publish.json). The `video-recap` orchestrator remains `blocked` pending verification of companion installation under one skills root. For the complete workflow, install the plugin bundle or source checkout below.
 
 
 Prerequisites: Python 3.10 or newer, `ffmpeg` on `PATH`, and one [Xiaomi MiMo](https://platform.xiaomimimo.com) API key. Subtitles are burned in by default, which needs an ffmpeg with libass. Homebrew's stock `ffmpeg` has no libass: the default run then skips the burn, ships a same-name `.srt` sidecar next to the recap, and records a warning in `final_qc.json` (an explicit `--burn-subtitles` stops before the run starts instead). Narration that adds on-screen text overlays (`visual_overlays`) also needs an ffmpeg with drawtext, and stops before voiceover without it. To burn subtitles on macOS, use `brew install ffmpeg-full` (keg-only: put its `bin` first on `PATH`).
@@ -329,7 +327,7 @@ Use /path/to/ep1.mp4 and /path/to/ep2.mp4 to make one ten-minute recap with a sh
 
 > I have permission to use 〈local video〉 and am supplying checked picture and dialogue records for it. Propose only the sound handoff for this material: which full dialogue line, action sound or pause to preserve, where narration is needed, and which record supports each choice. List missing evidence rather than inventing motives or unseen events. Return beat notes and necessary narration drafts without calling TTS or rendering.
 
-The agent handles understanding, story and audiovisual planning, cutting, scripting, voiceover, and assembly. In cut mode it first chooses the footage, renders the shortened video, and only then writes narration on the output timeline; the internal pauses and resumes are the agent's job too.
+For a complete production request, the agent handles understanding, story and audiovisual planning, cutting, scripting, voiceover, and assembly. A text-only handoff stops at the requested scope. In cut mode it first chooses the footage, renders the shortened video, and only then writes narration on the output timeline; the internal pauses and resumes are the agent's job too.
 
 ## Workflow and the seven skills
 
@@ -408,7 +406,7 @@ Use /path/to/library as the resource library: register this BGM, this font and t
 template for 1080x1920 for me to adopt, then render this series with /path/to/series/recap_project.json binding them.
 ```
 
-Resources, templates and sample films are JSON records in your own directory; licence and "adopted" status are only ever set by you. A binding that conflicts with an explicit setting, or a template whose canvas differs from the output, stops the run before voicing. Each render gets a `resource_lock.json` listing what it actually used and whether the licences are clear. Format: [resource library, templates and samples](skills/video-recap/references/resource-library.md).
+Resources, templates and sample films are JSON records in your own directory; licence and "adopted" status are only ever set by you. A binding that conflicts with an explicit setting, or a template whose canvas differs from the output, stops the run before voicing. Each run writes `work_dir/resource_lock.json`, listing what it actually used and whether the licences are clear. Format: [resource library, templates and samples](skills/video-recap/references/resource-library.md).
 
 **Browse projects, runs and the library in a local page (read-only):**
 
@@ -432,7 +430,7 @@ Yes. Understanding relies on the VLM reading the picture and does not require ex
 
 ### A long video hit a 429 or was interrupted halfway. Do I start over?
 
-No. VLM scene analysis resumes from where it stopped and recovers from rate limits; once `narration.json` is written, repeating the same command continues, cut mode records in `recap_phase.json` which clip plan the narration was written for (changing the plan asks for a new narration), and a resume only continues a work directory for the same source video and parameters.
+VLM analysis saves completed scenes and retries suspected rate limits once with lower concurrency. Persistent failures remain visible. After addressing the cause, repeat the same command to reuse matching scene caches and continue. Use the original command after writing `narration.json` too. In cut mode, `recap_phase.json` binds narration to its clip plan; a changed plan requires checking or rewriting the narration. Resuming requires the same source video and parameters.
 
 ### The VLM can't tell who is who and the narration is all "a man in black"?
 

package/lib/video-recap/README.md

@@ -21,7 +21,7 @@
 <p align="center">
   <a href="https://github.com/zenstory-ai/video-recap-skills/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/zenstory-ai/video-recap-skills?style=flat-square&color=22D3EE&logo=github&logoColor=white&label=Stars"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/zenstory-ai/video-recap-skills?style=flat-square&color=081431&label=Release"></a>
-  <img alt="Skills 6" src="https://img.shields.io/badge/Skills-6-081431?style=flat-square">
+  <img alt="Skills 7" src="https://img.shields.io/badge/Skills-7-081431?style=flat-square">
   <a href="https://www.python.org/"><img alt="Python 3.10%2B" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white"></a>
   <a href="https://github.com/zenstory-ai/video-recap-skills/actions/workflows/skill-validate.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/zenstory-ai/video-recap-skills/skill-validate.yml?style=flat-square&label=CI"></a>
   <a href="https://platform.xiaomimimo.com"><img alt="AI Xiaomi%20MiMo" src="https://img.shields.io/badge/AI-Xiaomi%20MiMo-34A853?style=flat-square"></a>
@@ -44,16 +44,16 @@
 决定故事与视听方案、剪辑、写稿、配音、混音和字幕。支持 `.mp4 / .mov / .mkv / .webm`。
 
 - **一个 key，本地只要 ffmpeg。** ASR、VLM、TTS 都走[小米 MiMo](https://platform.xiaomimimo.com)，本地只用 Python 标准库和 `ffmpeg`，不需要 GPU，不需要 `pip install`，也不下载模型。配音可以换成 Fish Audio，只替换配音这一段。
-- **先做创作决定，再分配声音。** Agent 先比较剪辑假设，把观众承诺、POV、戏剧问题和"发生了什么变化"的 beat 写进 `recap_story_plan.json`，再给每一拍指定画面任务和声音归属：旁白只在有明确任务时整块配音，强对白、动作声或沉默可以完整主导一拍。
-- **先剪后配，时间轴天然对齐。** 剪辑模式先把长视频剪成成片，再对着成片写解说；一次可以传多个视频，按 `source_id` 选段剪成一条主线；每个视频的分析沉淀成文件系统素材库，下次直接复用。
+- **先做创作决定，再分配声音。** 首次策划时，Agent 比较可行的剪辑方向；已有指定结构或看片反馈时，按当前决定修订。观众承诺、POV、戏剧问题和每拍变化写进 `recap_story_plan.json`，再给每一拍指定画面任务和声音归属：旁白只在有明确任务时整块配音，强对白、动作声或沉默可以完整主导一拍。
+- **先剪后配，时间轴天然对齐。** 剪辑模式先把长视频剪成成片，再对着成片写解说；一次可以传多个视频，按 `source_id` 选段剪成一条主线；视频分析可按需保存到文件系统素材库，后续在来源和设置匹配时复用。
 - **成片之外还能继续改。** 多轨时间线 `timeline.json` 可一键导出剪映草稿，原片、解说、BGM、字幕、图片叠层都可编辑；自带一份准确字幕文件就会被当作原声字幕的首选来源。
-- **每一步都留下可核对的记录。** 旁白 lint、组装 QC、交付 QC 和看片修改日志都是机器可读文件。
+- **每一步都留下可核对的记录。** 旁白 lint、组装 QC 与最终 QC 会生成机器可读报告；看片修改可另记录本轮改动、冻结项与验证结果。
 
 ## 安装
 
 ### ClawHub
 
-ClawHub 分发由仓库中的 [显式发布清单](.clawhub/publish.json) 管理，并通过 [ClawHub](https://clawhub.ai/) 提供发现入口。具体 skill 链接只有在发布者、版本和匿名访问均验证后才会写入本文档，避免把尚不存在的条目当成已上架。
+ClawHub 条目与依赖由 [显式发布清单](.clawhub/publish.json) 管理。编排器 `video-recap` 当前仍因同根安装验证未完成而标为 `blocked`；使用完整流程请按下方方式安装整套插件或源码。
 
 
 前提：Python 3.10 或更新版本，`PATH` 上有 `ffmpeg`，以及一个[小米 MiMo](https://platform.xiaomimimo.com) API Key。默认把字幕烧录进画面，这需要带 libass 的 ffmpeg；Homebrew 自带的 `ffmpeg` 没有 libass，这时默认运行不烧录，在成片旁输出同名 `.srt` 外挂字幕并在 `final_qc.json` 里记一条警告（显式传 `--burn-subtitles` 则在开跑前报错）。旁白里写了画面文字叠加（`visual_overlays`）时还需要带 drawtext 的 ffmpeg，缺了会在配音前报错。要在 macOS 上烧录字幕，可用 `brew install ffmpeg-full`（keg-only，需把它的 `bin` 放到 `PATH` 前面）。
@@ -318,7 +318,7 @@ Agent 在剪任何一刀之前先写 [`recap_story_plan.json`](examples/guohuo-6
 
 > 我有权使用〈本地视频〉，并提供了对应的已核对画面与对白记录。先只给这段素材的声音分工建议：哪句对白、哪个动作声或停顿应完整保留，哪里确需旁白，依据是哪条记录。缺证据就列待核对项，不补人物动机或没出现的事件。交付分拍说明和必要的旁白草案，不调用配音或渲染。
 
-Agent 会自动完成理解、故事与视听规划、剪辑、写稿、配音和合成。剪辑模式内部会先确定保留片段、生成剪后成片，再按输出时间轴写旁白；这些暂停和续跑也由 Agent 处理。
+完整制作请求由 Agent 完成理解、故事与视听规划、剪辑、写稿、配音和合成；只做文字交接的请求按指定范围停止。剪辑模式内部会先确定保留片段、生成剪后成片，再按输出时间轴写旁白；这些暂停和续跑也由 Agent 处理。
 
 ## 流程与七个技能
 
@@ -398,7 +398,7 @@ flowchart LR
 ```
 
 资源、模板和样片是你自己目录里的 JSON 记录，授权与"已采用"状态只由你确认；绑定与显式设置冲突、模板画布与成片不符时，会在配音之前停下。
-每条成片旁边的 `resource_lock.json` 记下这次实际用了哪些资源、授权是否清楚。格式见 [资源库、模板与样片](skills/video-recap/references/resource-library.md)。
+每次运行的 `work_dir/resource_lock.json` 记下这次实际用了哪些资源、授权是否清楚。格式见 [资源库、模板与样片](skills/video-recap/references/resource-library.md)。
 
 **在浏览器里看项目、运行和资源库（只读）：**
 
@@ -422,7 +422,7 @@ flowchart LR
 
 ### 长视频跑到一半报 429 或中断了，要从头再来吗？
 
-不用。VLM 场景分析可断点续传，限流会自愈；写好 `narration.json` 后重复同一条命令即可继续，剪辑模式在 `recap_phase.json` 记下解说对应的剪辑计划（改了计划会要求重写解说），续跑只会接同一个源视频、同一组参数的工作目录。
+VLM 会保存已完成的场景；遇到疑似限流会降低并发重试一轮，仍失败时保留错误供处理。解决原因后重复同一条命令，可以复用匹配的场景缓存并继续。写好 `narration.json` 后也用原命令续跑；剪辑模式用 `recap_phase.json` 绑定写稿时的计划，改了计划需重新核对或重写解说。续跑只接受同一源视频、同一组参数的工作目录。
 
 ### VLM 认不出谁是谁，解说里全是"黑衣男子"？