@oh-story/dsh 0.1.16 → 0.1.17

package/lib/oh-story/skills/story-import/scripts/outline_view.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""卷纲取段器 —— 让「不整读卷纲」成立。
+
+按声明作用域选取卷级、单元级和批次材料；未声明的旧段保守纳入并告警。
+
+段头约定（每个 ## / ### / #### 标题的**下一行非空行**）：
+
+    > 作用域：卷级常任
+    > 作用域：单元级 D1-03
+    > 作用域：批次底稿 D1-03｜状态：在用
+    > 作用域：批次底稿 D1-02｜状态：已退役
+
+退役行（行内覆盖）：以 `⊘` 起头的列表行 / 表格行，默认过滤。
+
+用法：
+    outline_view.py --toc   卷纲.md
+    outline_view.py --unit D1-03 卷纲.md
+    outline_view.py --contract 卷纲.md
+    outline_view.py --check 卷纲.md
+    任意子命令加 --history 连退役行一起输出
+"""
+import argparse
+import io
+import re
+import sys
+
+HEADING = re.compile(r"^(#{2,4})\s+(.*\S)\s*$")
+SCOPE = re.compile(r"^>\s*作用域[：:]\s*(.+?)\s*$")
+RETIRED_LINE = re.compile(r"^\s*(?:[-*]\s*)?⊘|^\s*\|\s*⊘")
+# 单元块内不该出现的全卷字样——出现即说明这条常任规则放错了地方
+LEAK = re.compile(r"全卷常任|全程生效|全卷生效|本单元起常任|自 ?[LD]\d+-\d+ ?起生效")
+# 指向卷级的指针行不算泄漏：单元块可以引用常任规则，不可以复述它
+POINTER = re.compile(r"全卷常任裁定|已提为卷级|不复读|规则本身见|见「全卷")
+UNIT_IN_TITLE = re.compile(r"(?<![\w-])([LD]\d+-\d+|U\d+)(?![\w-])")
+# 批次底稿里出现跨章祈使＝这条约束在写作期还有效，而写作档不给底稿 → 必须下沉
+IMPERATIVE = re.compile(r"全程不许|一律不许|往后任何章|此后不再|往后每|从此不|终局前不")
+CH_RANGE = re.compile(r"章节范围[：:]\s*第\s*(\d+)\s*[-–—~至]\s*(\d+)\s*章")
+# 情绪弧线逐章行：首列写「12」或模板里的「第12章」都认
+ARC_ROW = re.compile(r"^\|\s*第?\s*(\d+)\s*章?\s*\|")
+
+
+def read(path):
+    with io.open(path, encoding="utf-8-sig") as handle:
+        return handle.read()
+
+
+class Section:
+    __slots__ = ("level", "title", "start", "end", "scope", "kind",
+                 "unit", "status", "lines")
+
+    def __init__(self, level, title, start):
+        self.level = level
+        self.title = title
+        self.start = start          # 标题行号（0 基）
+        self.end = None
+        self.scope = None           # 原始作用域串，None ＝ 未声明
+        self.kind = None            # 卷级常任 / 单元级 / 批次底稿
+        self.unit = None
+        self.status = "在用"
+        self.lines = []
+
+
+def parse(text):
+    lines = text.split("\n")
+    sections = []
+    fence = None
+    for index, line in enumerate(lines):
+        marker = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
+        if marker:
+            value = marker.group(1)
+            if fence is None:
+                fence = value
+            elif value[0] == fence[0] and len(value) >= len(fence):
+                fence = None
+            continue
+        if fence:
+            continue
+        match = HEADING.match(line)
+        if match:
+            if sections:
+                sections[-1].end = index
+            sections.append(Section(len(match.group(1)), match.group(2), index))
+    if sections:
+        sections[-1].end = len(lines)
+    for section in sections:
+        section.lines = lines[section.start:section.end]
+        for candidate in section.lines[1:]:
+            if not candidate.strip():
+                continue
+            scope_match = SCOPE.match(candidate)
+            if scope_match:
+                section.scope = scope_match.group(1)
+            break
+        if section.scope:
+            head = section.scope.split("｜")[0].strip()
+            if head == "卷级常任":
+                section.kind = "卷级常任"
+            elif re.fullmatch(r"单元级(?:\s+[A-Za-z][\w-]*)?", head):
+                section.kind = "单元级"
+            elif re.fullmatch(r"批次底稿(?:\s+[A-Za-z][\w-]*)?", head):
+                section.kind = "批次底稿"
+            found = re.search(r"^(?:单元级|批次底稿)\s+([A-Za-z][\w-]*)$", head)
+            if found:
+                section.unit = found.group(1)
+            if "已退役" in section.scope:
+                section.status = "已退役"
+        if section.unit is None:
+            found = re.search(r"剧情单元\s+([A-Za-z][\w-]*)", section.title) or UNIT_IN_TITLE.search(section.title)
+            if found:
+                section.unit = found.group(1)
+        if section.unit is None and section.scope is None:
+            for line in section.lines[1:]:
+                field = re.match(r"^\s*[-*+]\s*单元ID\s*[：:]\s*([A-Za-z][\w-]*)\s*$", line.replace("**", ""))
+                if field:
+                    section.unit = field.group(1)
+                    break
+    return lines, sections
+
+
+def strip_retired(block_lines, keep_history):
+    if keep_history:
+        return block_lines
+    return [line for line in block_lines if not RETIRED_LINE.match(line)]
+
+
+def unit_chapter_range(sections, unit):
+    for section in sections:
+        if section.unit == unit and section.kind == "单元级" and "剧情单元" in section.title:
+            for line in section.lines:
+                found = CH_RANGE.search(line)
+                if found:
+                    return int(found.group(1)), int(found.group(2))
+    return None
+
+
+def slice_arc(section, span):
+    """情绪弧线这类逐章表：只留本单元章区间的行，表头与说明照留。"""
+    if span is None:
+        return section.lines
+    low, high = span
+    kept = []
+    for line in section.lines:
+        row = ARC_ROW.match(line)
+        if row and not (low <= int(row.group(1)) <= high):
+            continue
+        kept.append(line)
+    return kept
+
+
+def emit(sections, chosen, span, keep_history, note, preamble):
+    out = ["\n".join(strip_retired(preamble, keep_history)).rstrip()] if preamble else []
+    for section in sections:
+        if section not in chosen:
+            continue
+        body = section.lines
+        if "情绪弧线" in section.title or "排班" in section.title:
+            body = slice_arc(section, span)
+        body = strip_retired(body, keep_history)
+        out.append("\n".join(body).rstrip())
+    text = "\n\n".join(out)
+    sys.stdout.write(text + "\n")
+    if note:
+        sys.stderr.write(note + "\n")
+
+
+def cmd_toc(sections):
+    print("%-3s %-6s %-9s %-8s %-46s %s" %
+          ("#", "行", "作用域", "单元", "段", "字符"))
+    for number, section in enumerate(sections, 1):
+        size = sum(len(line) + 1 for line in section.lines)
+        print("%-3d %-6d %-9s %-8s %-46s %d" %
+              (number, section.start + 1, section.kind or "**未声明**",
+               (section.unit or "-") + ("(退)" if section.status == "已退役" else ""),
+               section.title[:44], size))
+
+
+def cmd_check(sections, strict=False):
+    problems = []
+    warnings = []
+    for section in sections:
+        if section.kind == "批次底稿":
+            for offset, line in enumerate(section.lines):
+                if IMPERATIVE.search(line):
+                    warnings.append(
+                        ("W1", "第%d行" % (section.start + offset + 1),
+                         "批次底稿里有跨章祈使，写作档不给底稿——确认已下沉到单元级段或细纲：%s"
+                         % line.strip()[:52]))
+    for section in sections:
+        where = "第%d行「%s」" % (section.start + 1, section.title[:36])
+        if section.scope is None:
+            (problems if strict else warnings).append(("E1" if strict else "W2", where, "缺「> 作用域：」声明行；旧段保守纳入"))
+            continue
+        if section.kind is None:
+            problems.append(("E2", where, "作用域值不认识：%s" % section.scope))
+        if section.kind in ("单元级", "批次底稿") and section.unit is None:
+            problems.append(("E3", where, "单元级/批次底稿段未标单元ID"))
+        if section.kind in ("单元级", "批次底稿"):
+            for offset, line in enumerate(section.lines):
+                if LEAK.search(line) and not POINTER.search(line):
+                    problems.append(
+                        ("E4", "第%d行" % (section.start + offset + 1),
+                         "单元块内出现全卷字样，常任规则放错了位置：%s"
+                         % line.strip()[:56]))
+    for code, where, message in problems + warnings:
+        print("%s %s %s" % (code, where, message))
+    print("---")
+    print("段 %d ／ 问题 %d ／ 告警 %d（告警不阻断，逐条人工判断）"
+          % (len(sections), len(problems), len(warnings)))
+    return 1 if problems else 0
+
+
+def main():
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument("path")
+    parser.add_argument("--toc", action="store_true")
+    parser.add_argument("--unit")
+    parser.add_argument("--contract", action="store_true")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--history", action="store_true")
+    parser.add_argument("--strict", action="store_true", help="新建卷纲校验：缺作用域也视为错误")
+    # 排纲底稿现在放在卷纲外的 大纲/排纲底稿_{单元ID}.md，默认输出就是写作要的闭包。
+    # --stage outline 只为老卷纲保留：它们的供给自查等底稿还写在卷纲里（作用域：批次底稿）。
+    parser.add_argument("--stage", choices=["outline", "write"], default="write",
+                        help="write（默认）＝卷级常任＋单元级；"
+                             "outline＝另带老卷纲里仍在用的批次底稿段")
+    args = parser.parse_args()
+
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+
+    try:
+        lines, sections = parse(read(args.path))
+    except (OSError, UnicodeError) as error:
+        sys.stderr.write(f"无法读取卷纲：{error}\n")
+        return 2
+    if not sections:
+        sys.stderr.write("卷纲里没有 ## 段，路径对不对？\n")
+        return 2
+
+    if args.toc:
+        cmd_toc(sections)
+        return 0
+    if args.check:
+        return cmd_check(sections, args.strict)
+
+    invalid = [s for s in sections if s.scope and
+               (s.kind is None or (s.kind != "卷级常任" and s.unit is None))]
+    if invalid:
+        sys.stderr.write("作用域声明无效，先运行 --check 修正\n")
+        return 1
+    active = [s for s in sections if args.history or s.status != "已退役"]
+    permanent = [s for s in active if s.kind == "卷级常任"]
+    undeclared = [s for s in active if s.scope is None]
+    note = ("%d 段未声明作用域，已保守纳入；用 --check 查看" % len(undeclared)) if undeclared else None
+    preamble = lines[:sections[0].start]
+    if args.contract:
+        emit(sections, set(permanent + undeclared), None, args.history, note, preamble)
+        return 0
+
+    if args.unit:
+        unit = args.unit
+        owned = [s for s in active if s.unit == unit]
+        if not owned:
+            sys.stderr.write(
+                "找不到单元 %s —— 不静默降级。核对单元ID，或先补卷纲。\n" % unit)
+            return 1
+        if args.stage == "write":
+            # 写作档不给批次底稿：它是排纲期的工作底稿，其中有写作期约束力的条目
+            # 必须已经下沉到单元级段或细纲（见 artifact-protocols.md 段位契约「排纲底稿不进卷纲」）
+            live = [s for s in owned if s.kind == "单元级"]
+        else:
+            live = [s for s in owned
+                    if s.kind == "单元级"
+                    or s.kind == "批次底稿"]
+        chosen = set(permanent + live + undeclared)
+        span = unit_chapter_range(active, unit)
+        emit(sections, chosen, span, args.history, note, preamble)
+        return 0
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -10,14 +10,14 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 **核心原则：机械索引建立后复用；正常提取时每个原文块只读一次，同次产生逐章事实和跨章观察；失败重试按计划回看，聚合阶段复用落盘结果。**
 
-> Agent 兼容性：只检查当前运行时 canonical 目录。运行时不支持项目 agent 或找不到文件时降级 solo/direct，并报告 `Fallback: project custom agents unavailable -> solo`。ZCode 3.3.4 不提供项目 custom agents，直接按此规则降级，不扫描其他 CLI 的 agent 目录。
+> Agent 兼容性：只检查当前运行时自己的 agent 目录。运行时不支持项目 agent 或找不到文件时降级 solo/direct，并报告 `Fallback: project custom agents unavailable -> solo`。ZCode 3.3.4 不提供项目 custom agents，直接按此规则降级，不扫描其他 CLI 的 agent 目录。
 >
-> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 35` 不一致时（标记缺失、字段缺失/非整数、小于或大于 35）照常按文件存在性检查并 spawn，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 35）` 并提示重新运行 `/story-setup` 后新开会话；大于 35 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct。
+> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 36` 不一致时（标记缺失、字段缺失/非整数、小于或大于 36）照常按文件存在性检查并 spawn，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 36）` 并提示重新运行 `/story-setup` 后新开会话；大于 36 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct。
 
 ## 分析边界
 
 1. 只根据可读原文和已有资料下结论；缺失写“未知”或“文本未明确”。
-2. 硬事实附章节、`source_locator` 或 5–15 字定位词；推断标证据强度。
+2. 硬事实附章节、`source_locator` 或 5–15 字定位词；推断标证据等级。
 3. 区分客观发生顺序、文本披露顺序、读者所知和角色所知。
 4. 分开分析事件推进、读者情绪和篇幅安排，分数不能代替解释。
 5. 只迁移抽象机制，不复刻专有设定、角色组合、关键事件链、标志性场面或原句。
@@ -27,6 +27,12 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 对话回复、`快速预览.md`、`拆文报告.md` 和人物关系图按 [references/author-facing.md](references/author-facing.md) 写，讲清书中情节、阅读感受和可借鉴写法。内部字段、命令与质量指标留在运行资料中；编号带名称。脚本返回 `author_message` 时转述说明与选项。
 
+## 运行约定
+
+- `{PYTHON}`：依次试 `python3`、`python`、`py -3`，用第一个能运行的。`{story-long-analyze skill 根}` 是本文件所在目录，`{拆文目录}` 是 `拆文库/{书名}/`。
+- 首次拆一本书时，把作者给的 TXT 存为 `{拆文目录}/原文/原文.txt`；若编码不是 UTF-8（常见为 GBK），先转成 UTF-8，否则子代理按行号读取时会乱码。
+- 全文不足 2 万字或认不出章节标题时多半是短篇，建议作者改用 `/story-short-analyze`；作者坚持或由导入调用（篇幅已在导入时定好）时照常按长篇拆。
+
 ## 按时刻读
 
 进入各阶段时只加载下表对应的说明，续跑或新会话通过落盘产物和 `_progress.md` 的阶段状态衔接。[references/author-facing.md](references/author-facing.md) 每个时刻都按需用。
@@ -35,11 +41,13 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 |---|---|---|
 | Phase 1–2、Stage 0–1 开头三章 | 本文件 + [stage1-golden-chapters.md](references/stage1-golden-chapters.md)；原文变了或章号对不上时加 [index-rebuild.md](references/index-rebuild.md) | 黄金三章与快速预览落盘，标 `stage1` |
 | Stage 2 逐批提取 | [pipeline-ops.md](references/pipeline-ops.md)；子代理不可用、自己写批次时加 [stage2-extraction.md](references/stage2-extraction.md) | 全部摘要落盘，标 `stage2` |
-| Stage 3 剧情与节奏 | [synthesis-inputs.md](references/synthesis-inputs.md) + [stage3-plot-rhythm.md](references/stage3-plot-rhythm.md)；打桥段标签时查 [deconstruction-notes.md](references/deconstruction-notes.md)「桥段词表」 | 节奏与情绪模块落盘，标 `stage3` |
+| 补缺 / 增强（检查器给出 `repair_stages`、`enhance_existing`，或写作端请作者来补拆） | 本文件「Phase 2」两张表，再按缺的那个 Stage 读下面对应一行 | 只补缺的产物，各自标阶段 |
+| Stage 3 剧情与节奏 | [synthesis-inputs.md](references/synthesis-inputs.md) + [stage3-plot-rhythm.md](references/stage3-plot-rhythm.md) | 节奏与情绪模块落盘，标 `stage3` |
 | Stage 4 角色与设定 | [synthesis-inputs.md](references/synthesis-inputs.md) + [stage4-characters-settings.md](references/stage4-characters-settings.md) | 角色与设定落盘，标 `stage4` |
 | Stage 5 主报告 | [synthesis-inputs.md](references/synthesis-inputs.md) + [stage5-report.md](references/stage5-report.md) | 报告落盘，标 `stage5` |
-| Stage 6 文风 | [style-profile-generator.md](references/style-profile-generator.md)（它再指向文风协议） | `文风.md` 落盘，标 `stage6` |
+| Stage 6 文风 | [style-profile-generator.md](references/style-profile-generator.md) | `文风.md` 落盘，标 `stage6` |
 | 全部拆完 | [final-checks.md](references/final-checks.md) | 按 author-facing「全部拆完」汇报 |
+| 灵感库（作者提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时） | [references/inspiration-library.md](references/inspiration-library.md) | 只写 `灵感库/`，不改拆文产物 |
 
 ## Phase 1：确认对象并检查目录
 
@@ -49,92 +57,47 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 "{PYTHON}" "{story-long-analyze skill 根}/scripts/inspect_existing_assets.py" --root "拆文库/{书名}" --compact
 ```
 
-路径错误必须停止。完整旧项目返回 `direct_use` 后直接使用，不建索引、不读原文。只有用户明确要求增强才读取旧成果。已有摘要一律不覆盖：要重拆某章就删掉它的 `章节/第N章_摘要.md` 和覆盖它的 `_analysis_cache/批次-*.md`（只删摘要会从缓存原样补回），整本重拆就换一个新目录。`schema_version` 只报告，不作为新旧门禁，也不得在复用时改写。
+路径错误必须停止。已有摘要一律不覆盖：要重拆某章就删掉它的 `章节/第N章_摘要.md` 和覆盖它的 `_analysis_cache/批次-*.md`（只删摘要会从缓存原样补回），整本重拆就换一个新目录。`schema_version` 只报告，不作为新旧门禁，也不得在复用时改写。新旧投影混存要报告来源，但不要求重拆。
 
-## Phase 2：唯一管道与三种情况
+## Phase 2：按检查结果走哪条路
+
+| `recommended_path` | 做什么 |
+|---|---|
+| `new_analysis` | 全新小说：Stage 0 建索引 → Stage 1 → 停下来问 → Stage 2–6 |
+| `continue_partial` | 部分完成：缺索引时补建；Stage 1 产物（前三章深度拆解、`快速预览.md`）缺哪份补哪份，已有的不覆盖，齐了标 `stage1`；再 `plan --intent continue` 只补缺章，按 Stage 3–6 补齐 |
+| `direct_use` | 完整旧成果：直接使用，不建索引、不读原文；作者明确要求增强时才 `plan --intent enhance` |
+| `repair_stages` | 逐章成果已齐，只缺后面的产物：按下表逐项补 |
+| `enhance_existing` | 有逐章成果但不成套：总章数不明时先建索引再检查；缺摘要时 `plan --intent continue` 从旧成果补（不读原文）；作者要求增强时用 `--intent enhance` |
 
-| 情况 | 行为 |
+| `stage_repairs` 代码 | 补哪一步 |
 |---|---|
-| 部分完成 | 已完成章只读旧拆文；黄金三章可补缺失摘要；缺失语义成果的章进入原文块；已有语义但缺摘要时从旧成果补投影 |
-| 已完整拆完 | 默认直接使用；增强复用旧成果，只补所请求的缺失产物、批次缓存与状态，保留既有成果 |
-| 全新小说 | 建索引、完成黄金三章，再把其余正文放入不重叠连续章块 |
+| `stage3_emotion`、`stage3_rhythm` | Stage 3：补缺的那份（情绪模块或节奏） |
+| `stage6_style` | Stage 6：文风 |
+| `stage3`、`stage4`、`stage5`、`stage6` | 没标完成：产物都在且合格就只 `mark-stage`，不重写；缺了才重做 |
 
-检查器只扫描上游 `章节/*_摘要.md` 与黄金三章，逐章报告缺口。新旧投影混存要报告来源，但不要求重拆。
+有多项时按 Stage 顺序逐项补完并标记。情绪模块卡字段不全（灵感库登记报错）时，检查器不会报缺：作者同意后把旧 `剧情/情绪模块.md` 复制到 `_analysis_cache/legacy/`，按 Stage 3 只改出错的卡，再标 `stage3`。Stage 3–5 只用已有成果和批次缓存，不读原文；没有批次缓存的旧项目用 `digest` 取逐章字段，再加上已有剧情、关系资料。写作端「对标书还缺情绪/节奏分析」「缺文风」分别对应这里的 Stage 3、Stage 6。
 
 ### 固定交付接口
 
 - `拆文报告.md`、`概要.md`、`快速预览.md`；
-- `章节/第1-3章_深度拆解.md`、`章节/第N章_摘要.md`；
-- `剧情/故事线.md`、剧情单元、`节奏.md`、`情绪模块.md`、`散落情节.md`；
+- `章节/第1章_深度拆解.md`、`章节/第2章_深度拆解.md`、`章节/第3章_深度拆解.md`，`章节/第N章_摘要.md`；
+- `剧情/README.md`、`剧情/故事线.md`、剧情单元、`剧情/节奏.md`、`剧情/情绪模块.md`、`剧情/散落情节.md`；
 - `角色/`、`设定/`、`人物关系图/`、`文风.md`；
 - `chapter_index.csv`、`_progress.md`、`_analysis_cache/`。
 
 `拆文报告.md` 是阅读入口。剧情单元管因果事实，`剧情/节奏.md` 管信息推进与三维节奏，`剧情/情绪模块.md` 管读者需求和复现机制，`角色/角色关系.md` 管关系事实，`文风.md` 管表达层。
 
-### Stage 0–6
-
-| 阶段 | 输入 | 主要输出 | 完成判断 |
-|---|---|---|---|
-| 0 机械索引 | 原文 | `chapter_index.csv`、`概要.md` 初稿（Stage 5 覆盖） | 章界、逐章 hash 和全源 hash 有效 |
-| 1 黄金三章 | 前三章原文 | 深度拆解、快速预览、可选 `_style-sample.txt` | 深度拆解与快速预览完整；同次阅读可保存文风样本 |
-| 2 连续块提取 | 只读计划列出的旧成果或原文块 | 批次缓存；缺失逐章摘要投影 | 缓存完整、摘要存在、状态范围 hash 有效 |
-| 3 剧情与机制 | 批次缓存和可信旧成果 | 剧情单元、故事线、节奏、情绪模块 | 文件存在、阶段状态完成 |
-| 4 角色与设定 | 批次涉及人物、状态变化、关系观察 | 角色、设定、关系图 | 文件存在、阶段状态完成 |
-| 5 主报告 | 权威底层结果 | 拆文报告、完整概要 | 文件存在、阶段状态完成 |
-| 6 文风 | 既有资料、样本或索引定点原文 | `文风.md` | 文件存在、阶段状态完成 |
-
-用户未要求一次跑完时，Stage 1 后按 author-facing.md「开头三章拆完、停下来问」询问是否继续；要求一次跑完、多本书一起拆或由导入自动续跑时不停下询问。Stage 2 默认有限并行（每轮 3 批），不请作者选派发方式；作者问起或明确要求时再按 author-facing「作者问起怎么拆」解释并切换（见 pipeline-ops「执行与提交一个批次」）。续跑不重复 Stage 0/1。Stage 3–5 不重读原文。Stage 6 可按索引定点读取 4–6 段原文锚点，但不重扫全书。
-
-## Stage 0：机械章节索引
-
-全新和部分完成运行：
-
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/build_chapter_index.py" --source "{拆文目录}/原文/原文.txt" --output "{拆文目录}/chapter_index.csv" --locator-path "原文/原文.txt"
-```
-
-完整旧成果直接使用或纯增强时不建索引。索引只含机械事实：
-
-```csv
-chapter,source_chapter,volume,title,start_line,end_line,char_count,source_locator,status,chapter_sha256,source_sha256,parser_version
-```
-
-只按 LF 计物理行。支持楔子、序章、第0章、任意正文起始章、番外、后记、中文大数、英文章号、多卷重置和卷章组合。目录与正文标题重复时先剔掉目录块；落表前校验章号连续、无重复和边界有效，其中特殊章独立编号，正文允许从任意首章开始。原文变化先拒绝；脚本因原文变化、章号对不上而停下并返回 `author_message` 时，读 [references/index-rebuild.md](references/index-rebuild.md)，把说明和选项转告作者（默认推荐按旧章号继续）。
-
-`概要.md` 初稿只按章节标题、卷段结构和抽样开头/结尾写，模板见 [references/stage1-golden-chapters.md](references/stage1-golden-chapters.md)。
-
-## Stage 1：黄金三章
-
-按索引读前三章原文，同一次阅读写三份单章深度拆解、可选 `_style-sample.txt`，再写 `快速预览.md`（模板在 author-facing.md「快速预览.md」）；深度拆解与文风样本模板见 [references/stage1-golden-chapters.md](references/stage1-golden-chapters.md)。黄金三章与快速预览落盘后运行 `manage_analysis_run.py mark-stage --stage stage1`，再按上方规则停下来问或继续。
-
-## Stage 2：计划、提取、提交
-
-按 [references/pipeline-ops.md](references/pipeline-ops.md) 执行：`manage_analysis_run.py plan` 出只读计划（用户明确增强用 `--intent enhance`，逐批加 `--next`，只拆一段加 `--chapters 起-止`），每批派一个 `chapter-extractor`，只照抄计划里这一批的字段；子代理自己读原文、把结果写进 `_analysis_cache/输入-{批次ID}.md`、只回一行回执，主会话不转贴原文、不读这份输入，直接 `commit`。批次过大或连续失败用 `split`，中断用 `repair-progress`。计划不再有批次、全部摘要落盘后运行 `manage_analysis_run.py mark-stage --stage stage2`。
-
-## Stage 3：剧情、双时间线与三维节奏
-
-按 [references/stage3-plot-rhythm.md](references/stage3-plot-rhythm.md) 生成剧情单元、故事线、`剧情/节奏.md` 与 `剧情/情绪模块.md`，取料用 `digest`（见 synthesis-inputs.md）。两份权威文件都落盘后运行 `manage_analysis_run.py mark-stage --stage stage3 --output "剧情/节奏.md"`。
-
-## Stage 4：角色、设定与关系
-
-按 [references/stage4-characters-settings.md](references/stage4-characters-settings.md) 生成角色档案、设定和 `角色/角色关系.md`，关系图只从该文件用 `render_relation_chart.py` 生成。至少一份角色档案和一份设定文件落盘后运行 `manage_analysis_run.py mark-stage --stage stage4`；缺任一类文件时不得标完成。
-
-## Stage 5：主报告
-
-报告按 author-facing.md「拆文报告.md」写：拆到哪、核心发现、读者在追什么、故事怎么推进、人物与关系、读者与角色的信息差、节奏、核心机制、可借鉴套路、不建议模仿、文风一句话、还不确定的地方。生成新报告前运行 `manage_analysis_run.py mark-stage --stage stage5 --prepare`，新报告与完整概要落盘后再运行 `manage_analysis_run.py mark-stage --stage stage5`（细则见 [references/stage5-report.md](references/stage5-report.md)）。报告只综合底层结果，不再次阅读全文。
-
-如项目存在 `选题决策.md`，只回填仍标记“待拆文验证”且题材匹配的项。没有「推荐选题」一节（只扫了榜）就跳过回填，不算无效；有推荐选题但缺少当前契约必需的“能爆的原因”等字段时返回 `invalid_topic_decision_contract`，提示重跑 `story-long-scan` Phase 5；文件不存在不影响拆文。
-
-## Stage 6：文风与单独重建
-
-加载 [references/style-profile-generator.md](references/style-profile-generator.md)。优先使用已有 `文风.md` 和有效 `_style-sample.txt`；样本不足时允许依据索引选择 4–6 章、定点读取原文行段。只缺文风时直接运行 Stage 6，不重跑 Stage 1–5。没有有效样本，且无法通过索引取得原文片段时明确失败，不生成锚点全空的可用档案。
-
-## 三层灵感库管道（可选后置）
+## 各阶段要点
 
-用户提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时加载 [references/inspiration-library.md](references/inspiration-library.md)。复用 Stage 3 的 EM 机制卡：`inspiration_index.py register-atoms` 机械登记原子灵感索引（无 IA 文件），再按该文档做单书合并与带受控标签的跨书聚合；卡内只用 `书名/EM-xxx` 裸 ID，禁路径引用。缺情绪模块的书先走上方按需增强，不在灵感层代拆。单书拆文不自动入库。
+- **Stage 0 机械索引**：全新和部分完成且要读原文时建 `chapter_index.csv`（命令见 stage1-golden-chapters.md）。只按 LF 计物理行，目录与正文标题重复时先剔掉目录块；落表前校验章号连续、无重复和边界有效。脚本因原文变化或章号对不上停下时读 index-rebuild.md，把说明和选项转告作者（默认推荐按旧章号继续）。
+- **Stage 1 黄金三章**：按索引读前三章，同一次阅读写三份单章深度拆解、可选 `_style-sample.txt` 和 `快速预览.md`，再运行 `manage_analysis_run.py mark-stage --stage stage1`。作者没要求一次跑完时按 author-facing「开头三章拆完、停下来问」询问；要求一次跑完、多本书一起拆或由导入自动续跑时不停。
+- **Stage 2 逐批提取**：`plan` 出只读计划，每批派一个 `chapter-extractor`，默认有限并行（每轮 3 批），作者问起才解释并切换拆法；子代理自己读原文并写批次输入，主会话不转贴、不读它，直接 `commit`。细则见 pipeline-ops.md。
+- **Stage 3–5**：用 `digest` 取料，不重读原文；怎么标阶段见 synthesis-inputs.md「阶段标记」；Stage 5 写新报告前先 `mark-stage --stage stage5 --prepare` 备份旧报告。
+- **选题回填**：Stage 5 报告落盘后找 `选题决策.md`，只回填仍标记“待拆文验证”且题材匹配的项（查找位置与写法见 stage5-report.md）。没有「推荐选题」一节（只扫了榜）就跳过，不算无效；有推荐选题但缺少当前契约必需的“能爆的原因”等字段时返回 `invalid_topic_decision_contract`，提示重跑 `story-long-scan` Phase 5；文件不存在不影响拆文。
+- **Stage 6 文风**：优先用已有 `文风.md` 和有效 `_style-sample.txt`，样本不足时按索引定点读 4–6 段原文，不重扫全书；只缺文风时直接运行，不重跑 Stage 1–5。取不到可核验原句时明确失败。
 
 ## 状态与旧项目
 
-运行状态只有 `_progress.md` 受管区；既有 `schema_version: 2` 原值保留；`chapter_index.csv` 是机械索引；缓存是恢复证据。有阶段记录后，受管区的 `最终状态` 由脚本按 Stage 3–6 的阶段状态写出（都完成为 `completed`，否则 `pending`）；旧项目沿用自己原有的 `最终状态` 行，全部完成时由脚本改为 `completed`，不写第二行，会话 hooks 靠它判断拆文是否完成，不要手改。不得创建运行计划、checkpoint、逐批 JSON receipt 或 Stage receipt。
+运行状态只有 `_progress.md` 受管区；既有 `schema_version: 2` 原值保留；`chapter_index.csv` 是机械索引；缓存是恢复证据。有阶段记录后 `最终状态` 由脚本写：Stage 3–6 都完成为 `completed`，否则新项目写 `pending`、旧项目保留原值（只改原有那一行）；会话 hooks 靠它判断拆文是否完成，不要手改。
 
 全部完成后按 [references/final-checks.md](references/final-checks.md) 做收尾检查，再按 author-facing.md「全部拆完」向作者汇报。

package/lib/oh-story/skills/story-long-analyze/references/author-facing.md

@@ -22,10 +22,10 @@
 一句话判断：{开篇靠什么抓人、主角怎么立住，一两句}。
 最值得学的一点：{最有借鉴价值的写法，一句}。
 
-要继续把后面 {剩余章数} 章也拆完吗？我建议{继续 / 只拆第 X–Y 章这一段 / 到此为止}，因为{理由}。
-继续的话我每次同时拆三段，减少等待时间；段和段之间的人物称呼、没收尾的剧情在最后汇总时对齐。
+要继续把后面 {剩余章数} 章也拆完吗？我建议{继续 / 先拆到第一卷末 / 只拆第 X–Y 章这一段 / 到此为止}，因为{理由}。
+继续的话我每次同时拆三段（每段最多三章），全部拆完大约要 {轮数} 轮；段和段之间的人物称呼、没收尾的剧情在最后汇总时对齐。
 
-如果继续，我会按「{推荐拆法}」执行；是否继续拆，等你决定。
+是否继续，等你决定。
 ```
 
 ### 作者问起怎么拆
@@ -61,7 +61,7 @@
 ```text
 《{书名}》拆完了：共 {总章数} 章、约 {总字数} 万字，{全部拆完 / 第 {x}–{y} 章没拆成：{原因}}。
 
-这本书最值得学的三点：
+这本书最值得学的{一到三}点：
 1. {开篇怎么钩住读者——在第几章、用了什么手法}
 2. {读者追着看的核心情绪或爽点，怎样一次次兑现}
 3. {节奏上的特点：哪里快、哪里慢、为什么这样安排}
@@ -74,7 +74,7 @@
 
 去哪看：
 - 先看总报告：拆文报告.md
-- 开头三章逐章怎么写的：章节/第1-3章_深度拆解.md
+- 开头三章逐章怎么写的：章节/第1章_深度拆解.md 到 第3章_深度拆解.md
 - 节奏和信息怎么一步步放出来：剧情/节奏.md
 - 读者爱看的情绪套路（可以拿去用的模块）：剧情/情绪模块.md
 - 故事主线和每段剧情：剧情/故事线.md 和 剧情/ 下的各段
@@ -86,7 +86,7 @@
 {需要你定的：一个问题 + 推荐选项；没有就不写这一段}
 ```
 
-只拆了一部分、或只补了某几个文件时，删掉用不上的「去哪看」条目，只列这次新增或更新的文件，并说清哪些是上次就有的。
+只拆了一部分或只补了几个文件时，「去哪看」只列这次新增或更新的文件，并说清哪些是上次就有的。
 
 ### 停下来或出错时
 
@@ -128,7 +128,11 @@
 
 ## 基本信息
 
-书名 | 题材 | 总章数 | 总字数 | 目标平台（原书所在平台，看不出来就留空）
+书名：{书名}
+题材：{题材}
+总章数：{总章数}
+总字数：{总字数} 万
+目标平台：{原书所在平台，看不出来就留空}
 
 ## 黄金三章评分
 
@@ -162,7 +166,7 @@
 
 ## 拆文报告.md
 
-全书的阅读入口。只综合已经落盘的剧情、节奏、情绪模块、角色、设定和文风结果，不为写报告重读全文，也不复制逐章摘要；细节写一句结论再指向对应文件。下列一级小节名被导入、写作和选题回填读取，保留原名。
+这是全书的阅读入口，只综合落盘的剧情、节奏、情绪模块、角色、设定和文风结果，不为写报告重读全文，也不复制逐章摘要；细节写一句结论再指向对应文件。这几个小节名有下游在读，保留原名：「基本信息」（写作端读题材，导入读题材与目标平台）、「核心发现」「读者在追什么」「伏笔与冲突」（导入；核心发现也用于选题回填）、「不建议模仿」（写作排卷纲）、「写法技巧」「可借鉴套路」「文风一句话」（文风）。
 
 ```markdown
 # 拆文报告：{书名}
@@ -172,7 +176,11 @@
 
 ## 基本信息
 
-书名 | 题材 | 总章数 | 总字数 | 目标平台（与 快速预览.md 同结构）
+书名：{书名}
+题材：{题材}
+总章数：{总章数}
+总字数：{总字数} 万
+目标平台：{原书所在平台，看不出来就留空}
 
 ## 核心发现
 
@@ -192,7 +200,7 @@
 
 ## 人物与关系
 
-主角、主要对手、核心配角各一两句：是谁、想要什么、在故事里起什么作用。
+主角、主要对手、核心配角各一两句：是谁、想要什么、在故事里起什么作用；功能角色只列名字和戏份。
 关系图见 人物关系图/人物关系图.md（有图片版时在这里嵌入 人物关系图/核心人物关系.png）。
 关键关系的变化逐条写成「甲 → 乙：由……到……（第几章，因为……）」；甲保护乙、乙依赖甲这类方向不同的关系分开写。
 
@@ -214,22 +222,12 @@
 
 跨章较远或影响主线的伏笔：在第几章埋下、第几章揭开、揭开时读者是什么感受。冲突怎么一级级升级，最后落到哪里。
 
-## 核心机制
-
-这本书反复使用的爽点类型、节奏套路和更新上的做法，各一两句。
-
-## 角色体系
-
-主角 / 对手 / 核心配角 / 功能性角色各有哪些人、分别承担什么戏份。
-
 ## 可借鉴套路
 
-1. {套路名}：在什么场景用、怎么起效、第几章能看到（对应情绪模块卡「{模块名}」（EM-{编号}））
-2. ……
-
-## 可复现模块
+先用一两句说这本书反复使用的爽点类型和节奏套路，再列最值得复用的几条（最多三条）：
 
-从 剧情/情绪模块.md 挑最值得复用的三张卡，每张写：读者想看什么、情绪链、戏剧单元、可替换项、不可照搬。
+1. {套路名}：读者想看什么、情绪怎么一步步推上去、在什么场景用、第几章能看到、换书时哪些要换掉、哪些不能照搬（原书专名、事件顺序、标志性台词）（对应情绪模块卡「{模块名}」（EM-{编号}））
+2. ……
 
 ## 写法技巧
 

package/lib/oh-story/skills/story-long-analyze/references/final-checks.md

@@ -1,20 +1,11 @@
-# 收尾检查与维护者回归
+# 收尾检查
 
-全书或本次指定范围拆完后，执行「收尾检查」；「维护者回归」只在改动本 skill 时用。
+全书或本次指定范围拆完后执行。检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
 
-## 收尾检查
-
-检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
-
-- 再运行检查器和计划器；完整项目应 `direct_use`；`continue` 应在本次指定范围内无待处理批次；
+- 再运行检查器和计划器：完整项目应 `direct_use`；`continue` 在本次指定范围内无待处理批次；
 - 完整管道及其续跑确认「文风一句话」已根据 `文风.md` 补齐；单独补旧项目文风时保留已有报告；
-- 对比受保护路径 hash：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md` 不得被常规增强或恢复流程改写；明确请求重建文风或主报告时，分别按文风协议或 Stage 5 备份规则处理；
-- 常规增强与恢复只补缺失产物、新证据和 `_progress.md` 受管状态区；已有产物的明确重建按各阶段约定处理；
-- 检查旧 `schema_version` 原值；
-- 检查新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取。
-
-## 维护者回归
-
-改动本 skill 后必须回归：黄金三章、逐章摘要、情绪模块、节奏、角色、设定、文风、导入、对标和写作仍可用；旧完整项目直接使用；部分项目只补精确缺章；混存项目报告来源但不重拆；增强/恢复不改旧产物与原 schema。报告未执行的真实模型或跨平台检查，不得用静态 fixture 冒充。
-
-联合验收用 [semantic-acceptance-fixtures.md](semantic-acceptance-fixtures.md) 的六项 0–2 分表，真实模型结果至少 10/12 且无硬失败才算语义通过。
+- 检查受保护路径：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md` 不得被常规增强或恢复流程改写；明确请求重建文风、主报告或修情绪模块卡时，按各自的说明处理；
+- 常规增强与恢复只补缺失产物、新证据和 `_progress.md` 受管状态区；
+- 旧 `schema_version` 原值未变；
+- 新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取；
+- 找到过 `选题决策.md` 时，确认回填只改了题材匹配的选题那一行。