@oh-story/dsh 0.1.10 → 0.1.11

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

@@ -26,8 +26,71 @@ _FRONTMATTER_KEY_RE = re.compile(r"^[A-Za-z_\u3400-\u9FFF][^:\n]{0,80}:[ \t]*(?:
 _LEADING_BLANK_RE = re.compile(r"^[\u0009\u0020\u3000]*$")
 _ATX_HEADING_RE = re.compile(r"^[\u0009\u0020]{0,3}#{1,6}[\u0009\u0020]+\S")
 _POSITIVE_INTEGER_RE = re.compile(r"^[1-9]\d*$")
-_TARGET_LINE_RE = re.compile(r"^[ \t>*-]*字数目标[ \t]*[:：][ \t]*([1-9]\d*)[ \t]*(?:字)?[ \t]*$", re.MULTILINE)
-_METRIC_LINE_RE = re.compile(r"^[ \t>*-]*字数口径[ \t]*[:：][ \t]*([A-Za-z0-9_-]+)[ \t]*$", re.MULTILINE)
+# 细纲「字数目标」「字数范围」「字数口径」的唯一写法语法；check-outline-contract.js 逐字镜像同一组正则，
+# scripts/test-storyctl.py 用同一批写法同时跑两边，保证细纲验收过了、章节检查不会再拒。
+# 值里一个数字都没有的目标/范围行（「字数目标：按卷规划」）是说明文字，不参与取值。
+_NUMBER = r"([1-9][0-9]{0,2}(?:[,，][0-9]{3})+|[1-9][0-9]*)"
+_NOTE = r"(?:[（(][^（）()]*[）)])?"
+_TARGET_VALUE_RE = re.compile(rf"^(?:约|大约)?[ \t]*{_NUMBER}[ \t]*字?(?:左右)?[ \t]*{_NOTE}$")
+_RANGE_VALUE_RE = re.compile(
+    rf"^{_NUMBER}[ \t]*字?[ \t]*(?:-|~|～|—|–|－|至|到)[ \t]*{_NUMBER}[ \t]*字?[ \t]*{_NOTE}$"
+)
+_METRIC_VALUE_RE = re.compile(rf"^([A-Za-z0-9_-]+)[ \t]*{_NOTE}$")
+_HAS_DIGIT_RE = re.compile(r"[0-9０-９]")
+
+
+def _field_values(text: str, label: str) -> list[str]:
+    pattern = re.compile(
+        rf"^[ \t>]*(?:[-*+][ \t]*)?(?:\*\*)?{label}(?:\*\*)?[ \t]*[:：][ \t]*(.*?)[ \t]*$", re.MULTILINE
+    )
+    return [value.replace("**", "").strip() for value in pattern.findall(text)]
+
+
+def _numeric_field_values(text: str, label: str) -> list[str]:
+    return [raw for raw in _field_values(text, label) if _HAS_DIGIT_RE.search(raw)]
+
+
+def _number(raw: str) -> int:
+    return int(re.sub(r"[,，]", "", raw))
+
+
+def parse_target_field(text: str) -> dict[str, Any]:
+    """Return {"status": ok|missing|invalid|conflict, "value": int|None, "raw": [...]}."""
+    raws = _numeric_field_values(normalize_newlines(text).lstrip("\ufeff"), "字数目标")
+    if not raws:
+        return {"status": "missing", "value": None, "raw": raws}
+    matches = [_TARGET_VALUE_RE.fullmatch(raw) for raw in raws]
+    if not all(matches):
+        return {"status": "invalid", "value": None, "raw": raws}
+    values = sorted({_number(match.group(1)) for match in matches if match})
+    if len(values) != 1:
+        return {"status": "conflict", "value": None, "raw": raws}
+    return {"status": "ok", "value": values[0], "raw": raws}
+
+
+def parse_range_field(text: str) -> dict[str, Any]:
+    """Optional author range line 「字数范围：2000-2600」; same status vocabulary as parse_target_field."""
+    raws = _numeric_field_values(normalize_newlines(text).lstrip("\ufeff"), "字数范围")
+    if not raws:
+        return {"status": "missing", "value": None, "raw": raws}
+    matches = [_RANGE_VALUE_RE.fullmatch(raw) for raw in raws]
+    if not all(matches):
+        return {"status": "invalid", "value": None, "raw": raws}
+    values = sorted({(_number(match.group(1)), _number(match.group(2))) for match in matches if match})
+    if len(values) != 1:
+        return {"status": "invalid", "value": None, "raw": raws}
+    low, high = values[0]
+    if low > high:
+        return {"status": "invalid", "value": None, "raw": raws}
+    return {"status": "ok", "value": {"min": low, "max": high}, "raw": raws}
+
+
+def parse_metric_field(text: str) -> dict[str, Any]:
+    """「字数口径：visible_chars_v1（按可见字符）」；每行都得是口径名（可带括号备注），且只能是 METRIC。"""
+    raws = _field_values(normalize_newlines(text).lstrip("\ufeff"), "字数口径")
+    matches = [_METRIC_VALUE_RE.fullmatch(raw) for raw in raws]
+    ok = bool(raws) and all(matches) and {match.group(1) for match in matches if match} == {METRIC}
+    return {"ok": ok, "raw": raws}
 
 
 class WordcountError(ValueError):
@@ -80,8 +143,26 @@ def parse_target(value: Any) -> int:
     return target
 
 
-def compute_wordcount_bands(value: Any) -> dict[str, dict[str, int]]:
+def normalize_author_range(value: Any) -> dict[str, int] | None:
+    """作者明确给出的上下限；None 表示沿用默认 ±12% / ±15% 双层带。"""
+    if value is None:
+        return None
+    require(isinstance(value, dict) and set(value) == {"min", "max"}, "author range must be {min, max}")
+    low, high = value["min"], value["max"]
+    require(
+        all(isinstance(item, int) and not isinstance(item, bool) and item >= 1 for item in (low, high)),
+        "author range bounds must be positive integers",
+    )
+    require(low <= high, "author range min must not exceed max")
+    return {"min": low, "max": high}
+
+
+def compute_wordcount_bands(value: Any, author_range: Any = None) -> dict[str, dict[str, int]]:
     target = parse_target(value)
+    author = normalize_author_range(author_range)
+    if author is not None:
+        # 作者给定区间原样优先：内部带与用户带都取它，不再有 borderline。
+        return {"internal": dict(author), "user": dict(author)}
     return {
         "internal": {"min": (target * 88 + 99) // 100, "max": target * 112 // 100},
         "user": {"min": (target * 85 + 99) // 100, "max": target * 115 // 100},
@@ -95,7 +176,7 @@ def invalid_wordcount_result(
     return {
         "schema": WORDCOUNT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
         "target": target, "actual": actual, "internal_band": None, "user_band": None,
-        "signed_error_pct": None, "absolute_error_pct": None,
+        "signed_error_pct": None, "absolute_error_pct": None, "band_source": None,
         "status": "invalid", "invalid_reason": reason,
     }
 
@@ -115,19 +196,23 @@ def measure_wordcount(value: str, *, chapter: Any = None, case_id: Any = None) -
 
 
 def evaluate_wordcount(
-    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None,
+    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None, author_range: Any = None,
 ) -> dict[str, Any]:
     try:
         target = parse_target(target_value)
     except (TypeError, ValueError):
         return invalid_wordcount_result("INVALID_TARGET", chapter=chapter, case_id=case_id)
+    try:
+        author = normalize_author_range(author_range)
+    except WordcountError:
+        return invalid_wordcount_result("INVALID_RANGE", chapter=chapter, case_id=case_id, target=target)
     try:
         actual = count_visible_chars(value)
     except (TypeError, ValueError):
         return invalid_wordcount_result("INVALID_BODY", chapter=chapter, case_id=case_id, target=target)
     if actual == 0:
         return invalid_wordcount_result("EMPTY_BODY", chapter=chapter, case_id=case_id, target=target, actual=actual)
-    bands = compute_wordcount_bands(target)
+    bands = compute_wordcount_bands(target, author)
     internal_pass = bands["internal"]["min"] <= actual <= bands["internal"]["max"]
     user_pass = bands["user"]["min"] <= actual <= bands["user"]["max"]
     status = "internal_pass" if internal_pass else (
@@ -140,19 +225,22 @@ def evaluate_wordcount(
         "internal_band": {**bands["internal"], "status": "pass" if internal_pass else "fail"},
         "user_band": {**bands["user"], "status": "pass" if user_pass else "fail"},
         "signed_error_pct": signed_error, "absolute_error_pct": abs(signed_error),
+        "band_source": "author" if author else "default",
         "status": status, "invalid_reason": None,
     }
 
 
 def checkpoint_wordcount(
-    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None,
+    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None, author_range: Any = None,
 ) -> dict[str, Any]:
     target = parse_target(target_value)
     actual = count_visible_chars(value)
-    user = compute_wordcount_bands(target)["user"]
+    author = normalize_author_range(author_range)
+    user = compute_wordcount_bands(target, author)["user"]
     return {
         "schema": CHECKPOINT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
         "target": target, "actual": actual, "user_band": user,
+        "band_source": "author" if author else "default",
         "remaining_user_range": {
             "min": max(0, user["min"] - actual),
             "max": max(0, user["max"] - actual),
@@ -160,15 +248,30 @@ def checkpoint_wordcount(
     }
 
 
+_FIELD_ERRORS = {
+    "missing": "is missing",
+    "invalid": "is not a recognizable number (write e.g. 2300 字 / 约 2300 / 2,300)",
+    "conflict": "has conflicting values",
+}
+
+
 def target_from_outline(value: str) -> int:
     text = normalize_newlines(value)
     if text.startswith("\ufeff"):
         text = text[1:]
-    targets = list(dict.fromkeys(_TARGET_LINE_RE.findall(text)))
-    metrics = list(dict.fromkeys(_METRIC_LINE_RE.findall(text)))
-    require(len(targets) == 1, "字数目标 must appear exactly once with one value")
-    require(metrics == [METRIC], f"字数口径 must appear exactly once as {METRIC}")
-    return parse_target(targets[0])
+    parsed = parse_target_field(text)
+    require(parsed["status"] == "ok", f"字数目标 {_FIELD_ERRORS.get(parsed['status'], '')}: {parsed['raw']}")
+    require(parse_metric_field(text)["ok"], f"字数口径 must be {METRIC}")
+    return parse_target(parsed["value"])
+
+
+def range_from_outline(value: str) -> dict[str, int] | None:
+    """细纲可选行「字数范围：2000-2600」；没写返回 None，写了但写不对就报错而不是静默回落默认带。"""
+    parsed = parse_range_field(value)
+    if parsed["status"] == "missing":
+        return None
+    require(parsed["status"] == "ok", f"字数范围 must be one min-max pair with min <= max: {parsed['raw']}")
+    return parsed["value"]
 
 
 def _chapter_number_from_name(name: str, *, outline: bool) -> int | None:
@@ -192,18 +295,40 @@ def find_chapter_file(directory: Path, chapter: int, *, outline: bool) -> Path:
     return matches[0]
 
 
-def build_project_wordcount_record(project: Path, chapter: int, *, resolution: str) -> dict[str, Any]:
+def read_chapter_outline(project: Path, chapter: int) -> tuple[Path, str]:
+    outline_path = find_chapter_file(project.resolve() / "大纲", chapter, outline=True)
+    try:
+        return outline_path, outline_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise WordcountError(f"unable to read outline: {exc}") from exc
+
+
+def effective_author_range(outline: str, author_range: Any = None) -> dict[str, int] | None:
+    """命令行给了上下限就以它为准（细纲「字数范围」写错也不阻断）；否则读细纲。"""
+    return normalize_author_range(author_range) if author_range is not None else range_from_outline(outline)
+
+
+def read_project_chapter(
+    project: Path, chapter: int, author_range: Any = None,
+) -> tuple[Path, Path, int, dict[str, int] | None]:
+    """定位本章细纲与正文，读出字数目标和生效的作者字数范围。"""
+    outline_path, outline = read_chapter_outline(project, chapter)
+    body_path = find_chapter_file(project.resolve() / "正文", chapter, outline=False)
+    return outline_path, body_path, target_from_outline(outline), effective_author_range(outline, author_range)
+
+
+def build_project_wordcount_record(
+    project: Path, chapter: int, *, resolution: str, author_range: Any = None,
+) -> dict[str, Any]:
+    """author_range=None 时读细纲「字数范围」；显式传入（命令行 --min-chars/--max-chars）时以它为准。"""
     require(resolution in RESOLUTIONS, f"unsupported wordcount resolution: {resolution}")
-    root = project.resolve()
-    outline_path = find_chapter_file(root / "大纲", chapter, outline=True)
-    body_path = find_chapter_file(root / "正文", chapter, outline=False)
+    _, body_path, target, author = read_project_chapter(project, chapter, author_range)
     try:
-        target = target_from_outline(outline_path.read_text(encoding="utf-8"))
         body_bytes = body_path.read_bytes()
         body = body_bytes.decode("utf-8")
     except (OSError, UnicodeError) as exc:
         raise WordcountError(f"unable to read chapter files: {exc}") from exc
-    result = evaluate_wordcount(body, target, chapter=chapter)
+    result = evaluate_wordcount(body, target, chapter=chapter, author_range=author)
     require(result["status"] != "invalid", f"invalid chapter wordcount: {result['invalid_reason']}")
     in_user_band = result["status"] in {"internal_pass", "borderline"}
     require(
@@ -211,7 +336,7 @@ def build_project_wordcount_record(project: Path, chapter: int, *, resolution: s
         or (resolution == "accepted_current_length" and not in_user_band),
         "wordcount resolution does not match the current length",
     )
-    return {
+    record = {
         "metric": METRIC,
         "target": result["target"],
         "actual": result["actual"],
@@ -219,19 +344,26 @@ def build_project_wordcount_record(project: Path, chapter: int, *, resolution: s
         "resolution": resolution,
         "body_sha256": hashlib.sha256(body_bytes).hexdigest(),
     }
+    if author is not None:
+        record["author_range"] = dict(author)
+    return record
+
+
+_RECORD_FIELDS = {"metric", "target", "actual", "status", "resolution", "body_sha256"}
 
 
 def normalize_wordcount_record(value: object) -> dict[str, Any]:
     require(isinstance(value, dict), "wordcount record must be an object")
     require(
-        set(value) == {"metric", "target", "actual", "status", "resolution", "body_sha256"},
+        set(value) in (_RECORD_FIELDS, _RECORD_FIELDS | {"author_range"}),
         "wordcount record fields are invalid",
     )
     require(value.get("metric") == METRIC, "wordcount metric is unsupported")
     target = parse_target(value.get("target"))
+    author = normalize_author_range(value.get("author_range"))
     actual = value.get("actual")
     require(isinstance(actual, int) and not isinstance(actual, bool) and actual >= 1, "wordcount actual is invalid")
-    expected = evaluate_wordcount("字" * actual, target)
+    expected = evaluate_wordcount("字" * actual, target, author_range=author)
     require(value.get("status") == expected["status"], "wordcount status does not match target and actual")
     resolution = value.get("resolution")
     require(resolution in RESOLUTIONS, "wordcount resolution is unsupported")
@@ -242,8 +374,32 @@ def normalize_wordcount_record(value: object) -> dict[str, Any]:
     return dict(value)
 
 
+def wordcount_record_drift(project: Path, chapter: int, value: object) -> list[str]:
+    """已提交的字数记录对当前文件过期了哪几项：只核对记录钉住的正文字节与字数目标。
+
+    作者事后在细纲补/改「字数范围」只影响下次计数的判定带，不让已提交的记录过期。
+    """
+    record = normalize_wordcount_record(value)
+    root = project.resolve()
+    outline_path = find_chapter_file(root / "大纲", chapter, outline=True)
+    body_path = find_chapter_file(root / "正文", chapter, outline=False)
+    try:
+        outline = outline_path.read_text(encoding="utf-8")
+        body_bytes = body_path.read_bytes()
+    except (OSError, UnicodeError) as exc:
+        raise WordcountError(f"unable to read chapter files: {exc}") from exc
+    drift = []
+    if hashlib.sha256(body_bytes).hexdigest() != record["body_sha256"]:
+        drift.append("正文")
+    if target_from_outline(outline) != record["target"]:
+        drift.append("字数目标")
+    return drift
+
+
 def validate_current_wordcount_record(project: Path, chapter: int, value: object) -> dict[str, Any]:
     record = normalize_wordcount_record(value)
-    current = build_project_wordcount_record(project, chapter, resolution=record["resolution"])
+    current = build_project_wordcount_record(
+        project, chapter, resolution=record["resolution"], author_range=record.get("author_range"),
+    )
     require(record == current, "wordcount record is stale for the current body or target")
     return record

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

@@ -12,7 +12,7 @@ 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 目录。
 >
-> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 32` 不一致时（标记缺失、字段缺失/非整数、小于或大于 32）照常按文件存在性检查并 spawn，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 32）` 并提示重新运行 `/story-setup` 后新开会话；大于 32 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct。
+> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 34` 不一致时（标记缺失、字段缺失/非整数、小于或大于 34）照常按文件存在性检查并 spawn，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 34）` 并提示重新运行 `/story-setup` 后新开会话；大于 34 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct。
 
 ## 分析边界
 
@@ -27,6 +27,20 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 作者读到的一切——停下来提问、进度、拆完汇报、出错说明，以及 `快速预览.md`、`拆文报告.md`、人物关系图——按 [references/author-facing.md](references/author-facing.md) 写：大白话讲书、讲章、讲读者和作者能怎么用；不出现脚本名、命令、字段名、状态值、批次编号、内部文件名、质量指标名和证据分级字母；编号只和名称一起出现；需要作者拿主意时给一个问题、推荐选项和默认值；工程细节默认不写，确需时只在末尾留一行技术备注。脚本输出带 `author_message` 时转述它，不贴 JSON 或错误码。
 
+## 按时刻读
+
+拆文按阶段分成几个时刻。进入一个时刻只读下表这一行的文件；上一时刻的操作说明不必留在上下文里，时刻之间只靠落盘产物和 `_progress.md` 的阶段状态交接（续跑、换新对话都从这里接上）。[references/author-facing.md](references/author-facing.md) 每个时刻都按需用。
+
+| 时刻 | 读 | 交接 |
+|---|---|---|
+| 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` |
+| 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` |
+| 全部拆完 | [final-checks.md](references/final-checks.md) | 按 author-facing「全部拆完」汇报 |
+
 ## Phase 1：确认对象并检查目录
 
 没有书名或原文时询问书名、平台和原文路径；已有完整成果直接使用时不强制索要原文。已有目录先运行只读检查器：
@@ -69,7 +83,7 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 | 5 主报告 | 权威底层结果 | 拆文报告、完整概要 | 文件存在、阶段状态完成 |
 | 6 文风 | 既有资料、样本或索引定点原文 | `文风.md` | 文件存在、阶段状态完成 |
 
-用户未要求一次跑完时，Stage 1 后按 author-facing.md「开头三章拆完、停下来问」询问是否继续，并一并请作者选 Stage 2 派发方式（串行 / 有限并行 / 不限批次顺序，见 pipeline-ops「执行与提交一个批次」）；作者没选、要求一次跑完、多本书一起拆或由导入自动续跑时都按有限并行（每轮 3 批），后三种情况不停下询问；续跑不重复 Stage 0/1。Stage 3–5 不重读原文。Stage 6 可按索引定点读取 4–6 段原文锚点，但不重扫全书。
+用户未要求一次跑完时，Stage 1 后按 author-facing.md「开头三章拆完、停下来问」询问是否继续；要求一次跑完、多本书一起拆或由导入自动续跑时不停下询问。Stage 2 默认有限并行（每轮 3 批），不请作者选派发方式；作者问起或明确要求时再按 author-facing「作者问起怎么拆」解释并切换（见 pipeline-ops「执行与提交一个批次」）。续跑不重复 Stage 0/1。Stage 3–5 不重读原文。Stage 6 可按索引定点读取 4–6 段原文锚点，但不重扫全书。
 
 ## Stage 0：机械章节索引
 
@@ -85,65 +99,31 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 chapter,source_chapter,volume,title,start_line,end_line,char_count,source_locator,status,chapter_sha256,source_sha256,parser_version
 ```
 
-只按 LF 计物理行。支持楔子、序章、第0章、任意正文起始章、番外、后记、中文大数、英文章号、多卷重置和卷章组合。目录与正文标题重复时先剔掉目录块；落表前校验章号连续、无重复和边界有效，其中特殊章独立编号，正文允许从任意首章开始。原文变化先拒绝；确认后用 `--rebuild`，章号口径沿用已有索引（上次并入过楔子就照样并入）；重建后前面的章号对不上时不写索引并返回 `author_message`。追加章节不使前面逐章 hash 失效，只有新章进入待处理；改动已拆章节的原文只会让该批缓存重读，已有摘要不刷新（要刷新就删掉对应摘要和批次缓存再续跑）。旧成果（旧摘要，或旧版 `_progress.md` 下的黄金三章）的章号与新索引对不上时，脚本在写索引前停下并返回 `author_message`：有旧版「章节边界」表就逐章核对标题与起始行，没有表而原文不从第一章开始也停。把说明和选项转告作者（默认推荐①）：① 按旧章号继续——加 `--fold-prologue` 重建，楔子/序章/第0章并进第一章，旧成果原样复用、楔子不单独拆；② 楔子单独成章——把除 `原文/` 外所有按旧章号写的产物（`章节/`、`剧情/`、`角色/`、`设定/`、`人物关系图/`、`快速预览.md`、`概要.md`、`拆文报告.md`、`文风.md`、`_analysis_cache/批次-*.md` 和 `_progress.md`）挪进 `_analysis_cache/legacy/旧章号/`（不删除），再从 Stage 0 重拆；③ 换新目录整本重拆。索引已建过时先删 `chapter_index.csv`（只是机械章节表）再按所选方式重建。
+只按 LF 计物理行。支持楔子、序章、第0章、任意正文起始章、番外、后记、中文大数、英文章号、多卷重置和卷章组合。目录与正文标题重复时先剔掉目录块；落表前校验章号连续、无重复和边界有效，其中特殊章独立编号，正文允许从任意首章开始。原文变化先拒绝；脚本因原文变化、章号对不上而停下并返回 `author_message` 时，读 [references/index-rebuild.md](references/index-rebuild.md)，把说明和选项转告作者（默认推荐按旧章号继续）。
 
-## Stage 2：计划、提取、提交
+`概要.md` 初稿只按章节标题、卷段结构和抽样开头/结尾写，模板见 [references/stage1-golden-chapters.md](references/stage1-golden-chapters.md)。
 
-### 只读计划
-
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" plan --root "{拆文目录}" --intent continue
-```
+## Stage 1：黄金三章
 
-用户明确增强改为 `--intent enhance`。逐批派发加 `--next 1` 只取下一批，确认进度用 `--next 0`。计划不落盘，批次 ID 固定为 `RAW-{起章}-{止章}` 或 `REUSE-{起章}-{止章}`。计划与提交都拒绝超过 3 章或 25,000 字符的非单章原文块；同一章不能出现在两个原文块。计划原文读取数为 0 时不得派发原文任务。
+按索引读前三章原文，同一次阅读写三份单章深度拆解、可选 `_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`，再按上方规则停下来问或继续。
 
-### 两种互斥输入
-
-- `raw-original`：只按索引读取计划范围，一次产生紧凑逐章事实和跨章观察；
-- `existing-results`：只读 `source_files` 列出的摘要或黄金三章，不得打开原文。完整旧项目增强只产批次观察；本批含摘要缺口时必须为每章生成紧凑章块。
-
-`chapter-extractor` 输出字段为：概要、因果、关键行动、局面结果、涉及人物、信息变化、状态变化、三维节奏、章尾钩子、证据，以及情节点列表（原文块每章 10–20 个、长章最多 30 个，格式见 output-templates）。不得另做章节卡表。派发只给 `source_locator`、字数、输出文件路径和上一批缓存路径：子代理自己读原文、把完整结果写进 `_analysis_cache/输入-{批次ID}.md`，只回一行回执；主会话不转贴原文、不读这份输入，直接提交（细则见 pipeline-ops「执行与提交一个批次」）。
-
-提交：
-
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" commit --root "{拆文目录}" --input "{拆文目录}/_analysis_cache/输入-RAW-4-6.md" --batch-id "RAW-4-6" --range-sha256 "{plan 输出值}" --source-file "{plan 来源}"
-```
-
-提交脚本先完整校验（原文块每章情节点不足 10 或超过 30 即整批拒收），再按“缓存 → 缺失摘要 → `_progress.md`”写入。摘要投影逐个情节点固定主题、基调和类型枚举，映射不上时主题/基调写“其他”；保留“关键事件”“情节点”“涉及”“基调”等旧消费者字段。任何已有摘要均不覆盖，结果里的 `kept_existing_summary_chapters` 列出被保留的章。
-
-### 拆分与恢复
-
-```text
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" split --root "{拆文目录}" --batch-id "RAW-4-6"
-"{PYTHON}" "{story-long-analyze skill 根}/scripts/manage_analysis_run.py" repair-progress --root "{拆文目录}"
-```
+## Stage 2：计划、提取、提交
 
-拆分将父块记为 `superseded` 并持久化两个相邻子块，重规划不会合回。计划不再有批次、全部摘要落盘后运行 `manage_analysis_run.py mark-stage --stage stage2`；Stage 1 的黄金三章与快速预览落盘后同样标 `--stage stage1`。恢复只信任带结束标记且范围 hash 有效的完整缓存，只补缺失摘要，最后更新进度；不覆盖用户文件。
+按 [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：剧情、双时间线与三维节奏
 
-Stage 3–5 用 `manage_analysis_run.py digest` 取料：先读全书跨章观察，逐章字段与情节点简表按章节窗口取，不整份读批次缓存（用法见 pipeline-ops「Stage 3–6」）。
-
-剧情点按“起始目标与阻碍 → 改变局面的选择/行动/外部事件 → 局面变化与得失 → 后续影响”合并。事件发生与信息披露分开；同一事实的异常、线索、解释、确认属于一条披露路径。全局只保留约 8–15 个主线或关键转折节点。
-
-三维节奏分别说明：事件推进 1–5 及状态变化，读者情绪类型/强度 1–5 及触发，篇幅展开度 1–3 及展开/压缩/省略/反复的作用。情绪机制写完整卡，至少覆盖最强三个，值得复现的不设数量上限；其余保留索引。完整卡以 `读者想看什么`、`情绪链`、`戏剧单元`、`可替换项`、`不可照搬` 五个字段齐全为准，字段名按 `references/output-templates.md` 的 EM 卡表原样使用；缺任一项即无法登记灵感库。铺垫、成立条件、关键触发物、复现步骤、失效情形等按需增列。索引节标题用字面量 `## 其他机制索引`。
-
-`剧情/情绪模块.md` 与 `剧情/节奏.md` 都落盘后，用 `manage_analysis_run.py mark-stage --stage stage3 --output "剧情/节奏.md"` 标记。命令会同时检查两份必需产物；阶段没有 receipt 或依赖 hash。
+按 [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：角色、设定与关系
 
-从 Stage 2 的 `涉及人物`、状态变化和批次关系观察归一实体，再结合 Stage 3 剧情单元生成角色档案与设定。关系记录动作方向、触发、双方得失、表面/真实状态、阶段变化和证据；“甲保护乙”与“乙依赖甲”分别记录。
-
-关系图只从 `角色/角色关系.md` 生成：`"{PYTHON}" "{story-long-analyze skill 根}/scripts/render_relation_chart.py" --root "{拆文目录}" --png`。主产物是 `人物关系图/人物关系图.md`（Mermaid + 文字清单，任何 Markdown 查看器都显示中文）；PNG 只在找到能显示图中全部文字的字体时生成（表情等符号不画进图片）。字体不够就不出图，不得自行改画拼音或首字母版，把脚本的 `author_message` 转告作者。
-
-至少一份角色档案和一份设定文件落盘后运行 `manage_analysis_run.py mark-stage --stage stage4`；缺任一类文件时不得标完成。
+按 [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`，把旧报告完整保存到 `_analysis_cache/legacy/拆文报告.md`；新报告落盘后再运行 `manage_analysis_run.py mark-stage --stage stage5`，命令在 `拆文报告.md` 不存在或为空时拒绝完成。报告只综合底层结果，不再次阅读全文。
+报告按 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；文件不存在不影响拆文。
+如项目存在 `选题决策.md`，只回填仍标记“待拆文验证”且题材匹配的项。没有「推荐选题」一节（只扫了榜）就跳过回填，不算无效；有推荐选题但缺少当前契约必需的“能爆的原因”等字段时返回 `invalid_topic_decision_contract`，提示重跑 `story-long-scan` Phase 5；文件不存在不影响拆文。
 
 ## Stage 6：文风与单独重建
 
@@ -153,10 +133,8 @@ Stage 3–5 用 `manage_analysis_run.py digest` 取料：先读全书跨章观
 
 用户提出「灵感库 / 提炼灵感 / 跨书灵感聚合 / 更新灵感库」时加载 [references/inspiration-library.md](references/inspiration-library.md)。复用 Stage 3 的 EM 机制卡：`inspiration_index.py register-atoms` 机械登记原子灵感索引（无 IA 文件），再按该文档做单书合并与带受控标签的跨书聚合；卡内只用 `书名/EM-xxx` 裸 ID，禁路径引用。缺情绪模块的书先走上方按需增强，不在灵感层代拆。单书拆文不自动入库。
 
-## 状态、旧项目与最终回归
+## 状态与旧项目
 
 运行状态只有 `_progress.md` 受管区；既有 `schema_version: 2` 原值保留；`chapter_index.csv` 是机械索引；缓存是恢复证据。有阶段记录后，受管区的 `最终状态` 由脚本按 Stage 3–6 的阶段状态写出（都完成为 `completed`，否则 `pending`）；旧项目沿用自己原有的 `最终状态` 行，全部完成时由脚本改为 `completed`，不写第二行，会话 hooks 靠它判断拆文是否完成，不要手改。不得创建运行计划、checkpoint、逐批 JSON receipt 或 Stage receipt。
 
-全部完成后按 author-facing.md「全部拆完」向作者汇报。最终必须回归：黄金三章、逐章摘要、情绪模块、节奏、角色、设定、文风、导入、对标和写作仍可用；旧完整项目直接使用；部分项目只补精确缺章；混存项目报告来源但不重拆；增强/恢复不改旧产物与原 schema。
-
-详细命令和恢复顺序见 [references/pipeline-ops.md](references/pipeline-ops.md)。输出模板见 [references/output-templates.md](references/output-templates.md)，素材聚合方法见 [references/material-decomposition.md](references/material-decomposition.md)。联合验收用 [references/semantic-acceptance-fixtures.md](references/semantic-acceptance-fixtures.md) 的六项 0–2 分表，真实模型结果至少 10/12 且无硬失败才算语义通过。
+全部完成后按 [references/final-checks.md](references/final-checks.md) 做收尾检查，再按 author-facing.md「全部拆完」向作者汇报。

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

@@ -22,14 +22,21 @@
 一句话判断：{开篇靠什么抓人、主角怎么立住，一两句}。
 最值得学的一点：{最有借鉴价值的写法，一句}。
 
-要继续把后面 {剩余章数} 章也拆完吗？我建议{继续 / 只拆某一段 / 到此为止}，因为{理由}。
+要继续把后面 {剩余章数} 章也拆完吗？我建议{继续 / 只拆第 X–Y 章这一段 / 到此为止}，因为{理由}。
+继续的话我每次同时拆三段，比一段段按顺序拆快两三倍，段和段之间的人物称呼、没收尾的剧情在最后汇总时对齐。
 
-继续的话，想怎么拆？
+不回复的话我按「{推荐选项}」处理。
+```
+
+### 作者问起怎么拆
+
+拆法默认替作者定好（每次同时拆三段），不主动列选项。作者问能不能更快、更稳，或说想换拆法时，才这样解释，作者选了就换：
+
+```text
+有三种拆法：
 1. 一段接一段按顺序拆：前后章的人物称呼、没收尾的剧情都接得最稳；最慢。
-2. 每次同时拆三段：快两三倍；段和段之间偶尔要等全部拆完汇总时再对齐人物和剧情。
+2. 每次同时拆三段（现在用的）：快两三倍；段和段之间偶尔要等全部拆完汇总时再对齐人物和剧情。
 3. 能同时拆多少就拆多少：最快；前后接续全靠最后汇总时对齐，汇总会多花些工夫。电脑或账号扛不住时我会自动放慢。
-
-不回复的话我按「{推荐选项}」、每次同时拆三段处理。
 ```
 
 ### 拆的过程中报进度

package/lib/oh-story/skills/story-long-analyze/references/deconstruction-notes.md

@@ -1,5 +1,5 @@
 # 长篇拆文参考
-拆书方法论、结构设计、卖点循环、题材实战要点的速查手册。配合 SKILL.md 和 `material-decomposition.md` 使用。
+拆书方法论、结构设计、卖点循环、题材实战要点的速查手册。配合 SKILL.md 与各 Stage 的规则文件使用。
 
 ## 管道阶段映射
 

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

@@ -0,0 +1,19 @@
+# 收尾检查与维护者回归
+
+全部拆完（或本次要拆的一段拆完）的时刻读本文件的「收尾检查」；「维护者回归」只在改动本 skill 时用。
+
+## 收尾检查
+
+检查全部通过后，按 [author-facing.md](author-facing.md)「全部拆完」给作者汇报；下面这些检查结果不写进汇报。
+
+- 再运行检查器和计划器；完整项目应 `direct_use`，继续意图应无待处理批次；
+- 对比受保护路径 hash：旧 `章节/`、`剧情/`、`角色/`、`设定/`、`文风.md`、`拆文报告.md` 不得被增强或恢复流程改写；
+- 允许变化的旧项目文件只有 `_progress.md` 受管状态区和 `_analysis_cache/` 新证据；
+- 检查旧 `schema_version` 原值；
+- 检查新投影的情节点序列、主题、基调、类型和“涉及”字段能被导入与写作流程读取。
+
+## 维护者回归
+
+改动本 skill 后必须回归：黄金三章、逐章摘要、情绪模块、节奏、角色、设定、文风、导入、对标和写作仍可用；旧完整项目直接使用；部分项目只补精确缺章；混存项目报告来源但不重拆；增强/恢复不改旧产物与原 schema。报告未执行的真实模型或跨平台检查，不得用静态 fixture 冒充。
+
+联合验收用 [semantic-acceptance-fixtures.md](semantic-acceptance-fixtures.md) 的六项 0–2 分表，真实模型结果至少 10/12 且无硬失败才算语义通过。

package/lib/oh-story/skills/story-long-analyze/references/index-rebuild.md

@@ -0,0 +1,11 @@
+# 原文变化与章号对不上
+
+`build_chapter_index.py` 因原文变化非零退出，或返回 `chapter_mapping_ambiguous`、`index_would_shrink` 时读本文件；把脚本的 `author_message` 按 [author-facing.md](author-facing.md)「停下来或出错时」转告作者。
+
+同源索引直接复用且不重写。原文变化时先非零退出；人工确认后加 `--rebuild`。重建沿用已有索引的章号口径：已有索引第 1 章是正式章节、而原文开头有楔子/序章/第0章（即上次用了 `--fold-prologue`），自动照样并入，无需再加参数；重建出的前面各章与已有索引对不上（`chapter_mapping_ambiguous:position=N` 或 `index_would_shrink`）时不写索引，返回 `author_message`。追加新章时旧章 hash 保持稳定，输出仅列出新增或内容变化的 `pending_chapters`。改动已拆章节的原文只会让覆盖它的批次缓存失效、下次计划重读该批；已有摘要不刷新——要刷新哪章就删掉哪章的 `章节/第N章_摘要.md` 和覆盖它的 `_analysis_cache/批次-*.md` 再续跑（只删摘要会从缓存原样补回）。旧成果按旧章号命名，写新索引前逐一核对：旧摘要一律参与；黄金三章在 `_progress.md` 来自旧版（有「章节边界」表，或没有运行状态受管区）时参与，本次 Stage 1 按索引写的不参与。有旧版「章节边界」表时逐章定位：起始行正好是某章标题行就直接认定；否则按标题找（统一全半角，去掉章号前缀和「（求收藏）」「【二合一】」这类尾注，允许包含关系；标题只有章号时比章号），多个候选取离旧起始行最近的；全部对上才放行；没有表时，原文首章不是第 1 章就无法确认。对不上时不写索引，返回 `chapter_mapping_ambiguous` 和 `author_message`；`plan` 遇到已建好的错位索引同样拒绝。作者的三个选择：
+
+1. **按旧章号继续（推荐）**：`build_chapter_index.py ... --fold-prologue`，开头的楔子/序章/引子/前言/第0章并进第一个正式章节，编号回到旧版口径，旧成果原样复用；输出里的 `folded_into_first_chapter` 列出被并入的章节标签（如「楔子」「第0章」）。楔子内容不会单独拆，要在报告「还不确定的地方」说明。
+2. **楔子单独成章**：把除 `原文/` 外所有按旧章号写的产物——`章节/`、`剧情/`、`角色/`、`设定/`、`人物关系图/`、`快速预览.md`、`概要.md`、`拆文报告.md`、`文风.md`、`_analysis_cache/批次-*.md` 和 `_progress.md`——挪进 `_analysis_cache/legacy/旧章号/`（挪走，不删除），再从 Stage 0 按新章号重拆。旧库只拆到黄金三章时代价最小。
+3. **换一个新目录整本重拆**。
+
+`chapter_index.csv` 已按错误口径建好时，先删掉它（纯机械章节表，可随时重建），再按选择重建；`--rebuild` 只沿用已有索引的口径，不能用来改口径。