@lemoncat7/dsh-partner 2.8.0 → 2.8.2

package/resources/skills/story-creation/upstream/skills/story-import/scripts/wordcount_core.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+"""Small deterministic wordcount core shared by storyctl and tracking."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+
+WORDCOUNT_SCHEMA = "story-wordcount-result/v1"
+MEASUREMENT_SCHEMA = "story-wordcount-measurement/v1"
+CHECKPOINT_SCHEMA = "story-wordcount-checkpoint/v1"
+METRIC = "visible_chars_v1"
+RESOLUTIONS = frozenset({"within_user_band", "accepted_current_length"})
+
+_WHITE_SPACE_CODEPOINTS = frozenset(
+    [*range(0x0009, 0x000E)]
+    + [
+        0x0020, 0x0085, 0x00A0, 0x1680, *range(0x2000, 0x200B),
+        0x2028, 0x2029, 0x202F, 0x205F, 0x3000,
+    ]
+)
+_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*$")
+# 细纲「字数目标」「字数范围」「字数口径」的唯一写法语法；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):
+    """Expected deterministic wordcount contract failure."""
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise WordcountError(message)
+
+
+def normalize_newlines(value: str) -> str:
+    return value.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def strip_recognizable_frontmatter(value: str) -> str:
+    lines = value.split("\n")
+    if not lines or lines[0] != "---":
+        return value
+    closing = next((index for index in range(1, min(len(lines), 201)) if lines[index] in {"---", "..."}), -1)
+    if closing < 2 or not any(_FRONTMATTER_KEY_RE.match(line) for line in lines[1:closing]):
+        return value
+    return "\n".join(lines[closing + 1 :])
+
+
+def visible_body(value: str) -> str:
+    if not isinstance(value, str):
+        raise TypeError("body must be a string")
+    text = normalize_newlines(value)
+    if text.startswith("\ufeff"):
+        text = text[1:]
+    lines = strip_recognizable_frontmatter(text).split("\n")
+    while lines and _LEADING_BLANK_RE.match(lines[0]):
+        lines.pop(0)
+    if lines and _ATX_HEADING_RE.match(lines[0]):
+        lines.pop(0)
+    return "\n".join(lines)
+
+
+def count_visible_chars(value: str) -> int:
+    return sum(ord(character) not in _WHITE_SPACE_CODEPOINTS for character in visible_body(value))
+
+
+def parse_target(value: Any) -> int:
+    raw = str(value if value is not None else "")
+    if not _POSITIVE_INTEGER_RE.fullmatch(raw):
+        raise WordcountError("target must be a positive integer")
+    target = int(raw)
+    require(target <= 9_007_199_254_740_991, "target exceeds Number.MAX_SAFE_INTEGER")
+    return target
+
+
+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},
+    }
+
+
+def invalid_wordcount_result(
+    reason: str, *, chapter: Any = None, case_id: Any = None,
+    target: int | None = None, actual: int | None = None,
+) -> dict[str, Any]:
+    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, "band_source": None,
+        "status": "invalid", "invalid_reason": reason,
+    }
+
+
+def measure_wordcount(value: str, *, chapter: Any = None, case_id: Any = None) -> dict[str, Any]:
+    try:
+        actual = count_visible_chars(value)
+    except (TypeError, ValueError):
+        return {
+            "schema": MEASUREMENT_SCHEMA, "metric": METRIC, "chapter": chapter,
+            "case_id": case_id, "actual": None, "status": "invalid", "invalid_reason": "INVALID_BODY",
+        }
+    return {
+        "schema": MEASUREMENT_SCHEMA, "metric": METRIC, "chapter": chapter,
+        "case_id": case_id, "actual": actual, "status": "measured", "invalid_reason": None,
+    }
+
+
+def evaluate_wordcount(
+    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, 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 (
+        "borderline" if user_pass else ("under" if actual < bands["user"]["min"] else "over")
+    )
+    signed_error = (actual - target) / target
+    return {
+        "schema": WORDCOUNT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
+        "target": target, "actual": actual,
+        "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, author_range: Any = None,
+) -> dict[str, Any]:
+    target = parse_target(target_value)
+    actual = count_visible_chars(value)
+    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),
+        },
+    }
+
+
+_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:]
+    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:
+    # 改稿流程把原文备份为 第N章_章名_原稿_{日期}.md，与 hooks 一样不把它当本章正文。
+    if not outline and "_原稿_" in name:
+        return None
+    pattern = r"^细纲_第0*(\d+)章.*\.md$" if outline else r"^第0*(\d+)章(?:[_\- 　].*)?\.md$"
+    match = re.match(pattern, name)
+    return int(match.group(1)) if match else None
+
+
+def find_chapter_file(directory: Path, chapter: int, *, outline: bool) -> Path:
+    require(isinstance(chapter, int) and not isinstance(chapter, bool) and chapter >= 1, "chapter must be >= 1")
+    require(directory.is_dir(), f"chapter directory is missing: {directory}")
+    matches = sorted(
+        path for path in directory.iterdir()
+        if path.is_file() and _chapter_number_from_name(path.name, outline=outline) == chapter
+    )
+    label = "outline" if outline else "body"
+    require(len(matches) == 1, f"chapter {chapter} must have exactly one {label} file")
+    return matches[0]
+
+
+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}")
+    _, body_path, target, author = read_project_chapter(project, chapter, author_range)
+    try:
+        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, author_range=author)
+    require(result["status"] != "invalid", f"invalid chapter wordcount: {result['invalid_reason']}")
+    in_user_band = result["status"] in {"internal_pass", "borderline"}
+    require(
+        (resolution == "within_user_band" and in_user_band)
+        or (resolution == "accepted_current_length" and not in_user_band),
+        "wordcount resolution does not match the current length",
+    )
+    record = {
+        "metric": METRIC,
+        "target": result["target"],
+        "actual": result["actual"],
+        "status": result["status"],
+        "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) 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, 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")
+    in_user_band = expected["status"] in {"internal_pass", "borderline"}
+    require((resolution == "within_user_band") == in_user_band, "wordcount resolution does not match status")
+    digest = value.get("body_sha256")
+    require(isinstance(digest, str) and re.fullmatch(r"[0-9a-f]{64}", digest) is not None, "body_sha256 is invalid")
+    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"], author_range=record.get("author_range"),
+    )
+    require(record == current, "wordcount record is stale for the current body or target")
+    return record

package/resources/skills/story-creation/upstream/skills/story-long-analyze/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: story-long-analyze
+version: 1.0.0
+description: "长篇网文拆文。保留黄金三章、逐章摘要、剧情、情绪、节奏、角色、设定和文风接口，以连续章节块完成因果、双时间线、关系与三维节奏分析；兼容旧成果直接使用、按需增强和断点续跑。含可选三层灵感库管道（灵感库、跨书灵感聚合、更新灵感库）。触发方式：/story-long-analyze、/长篇拆文、「帮我拆这本书」「拆这本书」「分析黄金三章」「深度拆解」「完整拆解」或提供小说文本文件路径。"
+metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
+---
+# story-long-analyze：长篇网文拆文
+
+你是网络小说结构分析师。
+
+**核心原则：机械边界只解析一次；原文按连续章节块读取一次；同次读取产生逐章事实和跨章观察；聚合阶段复用落盘结果，不重新阅读全文。**
+
+> 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: 34` 不一致时（标记缺失、字段缺失/非整数、小于或大于 34）照常按文件存在性检查并 spawn，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 34）` 并提示重新运行 `/story-setup` 后新开会话；大于 34 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct。
+
+## 分析边界
+
+1. 只根据可读原文和已有资料下结论；缺失写“未知”或“文本未明确”。
+2. 硬事实附章节、`source_locator` 或 5–15 字定位词；推断标证据强度。
+3. 区分客观发生顺序、文本披露顺序、读者所知和角色所知。
+4. 分开分析事件推进、读者情绪和篇幅安排，分数不能代替解释。
+5. 只迁移抽象机制，不复刻专有设定、角色组合、关键事件链、标志性场面或原句。
+6. 不为填字段虚构事实，不把结果倒推成人物早有计划。
+
+## 对作者说话
+
+作者读到的一切——停下来提问、进度、拆完汇报、出错说明，以及 `快速预览.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：确认对象并检查目录
+
+没有书名或原文时询问书名、平台和原文路径；已有完整成果直接使用时不强制索要原文。已有目录先运行只读检查器：
+
+```text
+"{PYTHON}" "{story-long-analyze skill 根}/scripts/inspect_existing_assets.py" --root "拆文库/{书名}" --compact
+```
+
+路径错误必须停止。完整旧项目返回 `direct_use` 后直接使用，不建索引、不读原文。只有用户明确要求增强才读取旧成果。已有摘要一律不覆盖：要重拆某章就删掉它的 `章节/第N章_摘要.md` 和覆盖它的 `_analysis_cache/批次-*.md`（只删摘要会从缓存原样补回），整本重拆就换一个新目录。`schema_version` 只报告，不作为新旧门禁，也不得在复用时改写。
+
+## Phase 2：唯一管道与三种情况
+
+| 情况 | 行为 |
+|---|---|
+| 部分完成 | 已完成章只读旧拆文；黄金三章可补缺失摘要；仅缺摘要的章进入原文块 |
+| 已完整拆完 | 默认直接使用；增强只写 `_analysis_cache/` 和 `_progress.md` 状态 |
+| 全新小说 | 建索引、完成黄金三章，再把其余正文放入不重叠连续章块 |
+
+检查器只扫描上游 `章节/*_摘要.md` 与黄金三章，逐章报告缺口。新旧投影混存要报告来源，但不要求重拆。
+
+### 固定交付接口
+
+- `拆文报告.md`、`概要.md`、`快速预览.md`；
+- `章节/第1-3章_深度拆解.md`、`章节/第N章_摘要.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，禁路径引用。缺情绪模块的书先走上方按需增强，不在灵感层代拆。单书拆文不自动入库。
+
+## 状态与旧项目
+
+运行状态只有 `_progress.md` 受管区；既有 `schema_version: 2` 原值保留；`chapter_index.csv` 是机械索引；缓存是恢复证据。有阶段记录后，受管区的 `最终状态` 由脚本按 Stage 3–6 的阶段状态写出（都完成为 `completed`，否则 `pending`）；旧项目沿用自己原有的 `最终状态` 行，全部完成时由脚本改为 `completed`，不写第二行，会话 hooks 靠它判断拆文是否完成，不要手改。不得创建运行计划、checkpoint、逐批 JSON receipt 或 Stage receipt。
+
+全部完成后按 [references/final-checks.md](references/final-checks.md) 做收尾检查，再按 author-facing.md「全部拆完」向作者汇报。