@oh-story/dsh 0.1.9 → 0.1.10

package/lib/oh-story/skills/story-long-analyze/scripts/render_relation_chart.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""Render the character-relationship charts from 角色/角色关系.md.
+
+The Markdown file ``人物关系图/人物关系图.md`` (Mermaid graphs plus a plain
+list) is always written: it shows Chinese names in any Markdown viewer. PNG
+pictures are optional (``--png``) and are drawn only when matplotlib and a font
+that really contains every drawn character are available. Emoji and other
+symbols are left out of the pictures; without a font for the remaining text no
+PNG is written, so names are never replaced by pinyin, initials or empty boxes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unicodedata
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+RELATION_FILE = Path("角色") / "角色关系.md"
+CHART_DIR = Path("人物关系图")
+CHART_MD = CHART_DIR / "人物关系图.md"
+CORE_PNG = CHART_DIR / "核心人物关系.png"
+EVOLUTION_PNG = CHART_DIR / "关键关系演变.png"
+# 「甲 → 乙」, 「甲 ↔ 乙」 (both ways) and chains such as 「甲 → 乙 → 丙」.
+ARROW_RE = re.compile(r"\s*(↔|<->|⇔|<=>|→|->|⇒|=>|—>|－>)\s*")
+BOTH_WAYS = {"↔", "<->", "⇔", "<=>"}
+# Common Simplified-Chinese capable fonts on macOS, Windows and Linux.
+CJK_FONT_NAMES = (
+    "PingFang SC", "Hiragino Sans GB", "Heiti SC", "STHeiti", "Songti SC", "STSong",
+    "Microsoft YaHei", "SimHei", "SimSun", "DengXian",
+    "Noto Sans CJK SC", "Noto Sans SC", "Noto Serif CJK SC", "Source Han Sans SC",
+    "Source Han Sans CN", "WenQuanYi Micro Hei", "WenQuanYi Zen Hei", "Sarasa Gothic SC",
+    "Arial Unicode MS",
+)
+# Fonts that answer every character with a placeholder box; they never count.
+FALLBACK_FONT_RE = re.compile(r"last\s*resort|adobe\s*blank", re.IGNORECASE)
+BASE_TEXT = "中文人物关系未命名→…"
+MD_VIEW = "关系图已经写在 人物关系图/人物关系图.md 里，用能预览 Markdown 的编辑器打开就能看到中文。"
+NO_FONT_MESSAGE = (
+    "这台电脑上没有找到能显示中文的字体，所以没有生成关系图图片（硬画会把人名变成拼音或方块）。"
+    + MD_VIEW + "装上任意一款中文字体（如思源黑体、文泉驿）后再生成一次，就能得到图片版。"
+)
+MISSING_GLYPH_MESSAGE = (
+    "这台电脑上的中文字体显示不了关系图里的「%s」，所以没有生成图片（硬画会变成方块）。"
+    + MD_VIEW + "装上字更全的中文字体（如思源黑体）后再生成一次，就能得到图片版。"
+)
+PNG_FAILED_MESSAGE = "关系图图片这次没画成。" + MD_VIEW
+NO_MATPLOTLIB_MESSAGE = "当前环境不能画图片，" + MD_VIEW
+
+
+class ChartError(ValueError):
+    def __init__(self, code: str, author_message: str) -> None:
+        super().__init__(code)
+        self.code = code
+        self.author_message = author_message
+
+
+def atomic_write(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=".%s." % path.name, suffix=".tmp", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+        os.replace(temporary, str(path))
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        raise
+
+
+def cells(line: str) -> List[str]:
+    """Table cells; an escaped 「\\|」 stays inside its cell."""
+    stripped = line.strip()
+    stripped = stripped[1:] if stripped.startswith("|") else stripped
+    stripped = stripped[:-1] if stripped.endswith("|") and not stripped.endswith("\\|") else stripped
+    return [cell.strip().replace("\\|", "|") for cell in re.split(r"(?<!\\)\|", stripped)]
+
+
+def pick(row: Dict[str, str], *names: str) -> str:
+    for name in names:
+        for key, value in row.items():
+            if name in key and value and value not in {"-", "—", "无"}:
+                return value
+    return ""
+
+
+SOURCE_KEYS = ("主体", "角色A", "人物A", "A", "甲")
+TARGET_KEYS = ("客体", "角色B", "人物B", "B", "乙")
+
+
+def exact(row: Dict[str, str], keys: Tuple[str, ...]) -> str:
+    for key in keys:
+        value = row.get(key, "")
+        if value and value not in {"-", "—"}:
+            return value
+    return ""
+
+
+def parse_relations(text: str) -> Tuple[List[Dict[str, str]], int]:
+    """Relations of a relationship table, plus the number of rows left out.
+
+    Current files use one 「主体 → 客体」 column; older ones use separate
+    主体/客体 or A/B columns. Any table with such a pair of columns counts.
+    """
+    relations = []  # type: List[Dict[str, str]]
+    skipped = 0
+    header = None  # type: Optional[List[str]]
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            header = None
+            continue
+        row_cells = cells(stripped)
+        if header is None:
+            names = set(row_cells)
+            if (any("主体" in cell and "客体" in cell for cell in row_cells) or "关系方向" in names
+                    or (names & set(SOURCE_KEYS) and names & set(TARGET_KEYS))):
+                header = row_cells
+            continue
+        if not "".join(row_cells).strip("-: "):
+            continue
+        row = dict(zip(header, row_cells))
+        pair = next((value for key, value in row.items() if ("主体" in key and "客体" in key) or key == "关系方向"), "")
+        tokens = [part.strip() for part in ARROW_RE.split(pair)] if pair else []
+        names, arrows = tokens[0::2], tokens[1::2]
+        if len(names) < 2:
+            names = [exact(row, SOURCE_KEYS), exact(row, TARGET_KEYS)]
+            arrows = ["→"]
+        if len(names) < 2 or not all(names):
+            skipped += 1
+            continue
+        fields = {
+            "id": pick(row, "关系ID", "ID"),
+            "label": pick(row, "关系动作", "类型", "表面关系"),
+            "state": pick(row, "变化后状态", "真实关系", "表面关系"),
+            "trigger": pick(row, "触发事件", "触发"),
+        }
+        for index, arrow in enumerate(arrows):
+            ends = [(names[index], names[index + 1])]
+            if arrow in BOTH_WAYS:
+                ends.append((names[index + 1], names[index]))
+            for source, target in ends:
+                relations.append(dict(fields, source=source, target=target))
+    return relations, skipped
+
+
+def mermaid_text(value: str, placeholder: str) -> str:
+    value = re.sub(r"[`*]|%{2,}", "", value)
+    value = value.replace('"', "'").replace("|", "/").replace("\n", " ").strip()
+    return value or placeholder
+
+
+def latest_by_pair(relations: List[Dict[str, str]]) -> List[Dict[str, str]]:
+    latest = {}  # type: Dict[Tuple[str, str], Dict[str, str]]
+    for relation in relations:
+        latest[(relation["source"], relation["target"])] = relation
+    return list(latest.values())
+
+
+def evolutions(relations: List[Dict[str, str]]) -> List[Tuple[Tuple[str, str], List[Dict[str, str]]]]:
+    history = {}  # type: Dict[Tuple[str, str], List[Dict[str, str]]]
+    for relation in relations:
+        history.setdefault((relation["source"], relation["target"]), []).append(relation)
+    return [(pair, rows) for pair, rows in history.items() if len(rows) > 1]
+
+
+def render_markdown(book: str, relations: List[Dict[str, str]], png_note: str) -> str:
+    names = []  # type: List[str]
+    for relation in relations:
+        for name in (relation["source"], relation["target"]):
+            if name not in names:
+                names.append(name)
+    node = {name: "p%s" % index for index, name in enumerate(names, start=1)}
+    lines = ["# 人物关系图：%s" % book, "",
+             "> 由 角色/角色关系.md 生成；关系事实以该文件为准。%s" % png_note, "",
+             "## 核心人物关系", "", "```mermaid", "graph LR"]
+    lines.extend('    %s["%s"]' % (node[name], mermaid_text(name, "未命名")) for name in names)
+    for relation in latest_by_pair(relations):
+        label = relation["state"] or relation["label"] or "关系"
+        lines.append('    %s -->|"%s"| %s' % (node[relation["source"]], mermaid_text(label, "关系"),
+                                             node[relation["target"]]))
+    lines.extend(["```", ""])
+    for relation in latest_by_pair(relations):
+        label = relation["state"] or relation["label"] or "关系"
+        lines.append("- %s → %s：%s" % (relation["source"], relation["target"], label))
+    lines.extend(["", "## 关键关系演变", ""])
+    changes = evolutions(relations)
+    if not changes:
+        lines.append("本书没有记录到同一对人物前后变化的关系。")
+    for (source, target), rows in changes:
+        steps = []
+        for row in rows:
+            state = row["state"] or row["label"] or "关系"
+            steps.append("%s（%s）" % (state, row["trigger"]) if row["trigger"] else state)
+        lines.append("- %s → %s：%s" % (source, target, " → ".join(steps)))
+    return "\n".join(lines) + "\n"
+
+
+def png_text(value: str, placeholder: str = "") -> str:
+    """Text as drawn in the pictures: emoji and other symbols are left out."""
+    kept = "".join(char for char in value
+                   if char in BASE_TEXT or not unicodedata.category(char).startswith(("S", "C", "M")))
+    return re.sub(r"\s+", " ", kept).strip() or placeholder
+
+
+def font_face(path: str):  # noqa: ANN201 - matplotlib type
+    from matplotlib.ft2font import FT2Font
+    return FT2Font(path)
+
+
+def missing_glyphs(path: str, text: str) -> Optional[List[str]]:
+    """Characters of text the font (face 0) lacks; None when the font is unusable."""
+    if FALLBACK_FONT_RE.search(os.path.basename(path)):
+        return None
+    try:
+        font = font_face(path)
+        if FALLBACK_FONT_RE.search(str(getattr(font, "family_name", ""))):
+            return None
+        return sorted({char for char in text if not char.isspace() and not font.get_char_index(ord(char))})
+    except Exception:  # noqa: BLE001 - any font loading failure means "not usable"
+        return None
+
+
+def font_candidates() -> List[str]:
+    """Installed fonts worth trying, well-known Chinese fonts first."""
+    try:
+        from matplotlib import font_manager
+    except ImportError:
+        return []
+    by_name = {}  # type: Dict[str, List[str]]
+    for entry in font_manager.fontManager.ttflist:
+        paths = by_name.setdefault(entry.name, [])
+        if entry.fname not in paths:
+            paths.append(entry.fname)
+    candidates = [path for name in CJK_FONT_NAMES for path in by_name.get(name, [])]
+    if shutil.which("fc-list"):
+        try:
+            listed = subprocess.run(["fc-list", ":lang=zh", "file"], capture_output=True, text=True,
+                                    timeout=10, check=False).stdout
+        except (OSError, subprocess.SubprocessError):
+            listed = ""
+        candidates.extend(line.split(":", 1)[0].strip() for line in listed.splitlines())
+    return candidates
+
+
+def find_cjk_font(text: str) -> Tuple[Optional[str], List[str]]:
+    """(font that draws every character of text, []) or (None, characters no Chinese font draws)."""
+    text = text + BASE_TEXT
+    override = os.environ.get("STORY_ANALYZE_CHART_FONT")
+    if override == "none":
+        return None, []
+    fewest = None  # type: Optional[List[str]]
+    seen = set()
+    for path in [override] if override else font_candidates():
+        if not path or path in seen:
+            continue
+        seen.add(path)
+        missing = missing_glyphs(path, text)
+        if missing is None or any(char in BASE_TEXT for char in missing):
+            continue
+        if not missing:
+            return path, []
+        if fewest is None or len(missing) < len(fewest):
+            fewest = missing
+    return None, fewest or []
+
+
+def matplotlib_available() -> bool:
+    try:
+        import matplotlib  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def short_label(value: str, limit: int = 10) -> str:
+    value = png_text(re.sub(r"[`*]|\[[^\]]*\]", "", value), "关系")
+    return value if len(value) <= limit else value[:limit - 1] + "…"
+
+
+def draw_png(relations: List[Dict[str, str]], font_path: str, root: Path) -> List[str]:
+    import matplotlib
+    matplotlib.use("Agg")
+    from matplotlib import font_manager
+    import matplotlib.pyplot as plt
+
+    font = font_manager.FontProperties(fname=font_path)
+    (root / CHART_DIR).mkdir(parents=True, exist_ok=True)
+    written = []
+    core = latest_by_pair(relations)
+    degree = {}  # type: Dict[str, int]
+    for relation in core:
+        for name in (relation["source"], relation["target"]):
+            degree[name] = degree.get(name, 0) + 1
+    # The most connected character (usually the protagonist) sits in the middle.
+    names = sorted(degree, key=lambda name: -degree[name])
+    ring = names[1:] if len(names) > 2 else names
+    positions = {name: (math.cos(2 * math.pi * index / len(ring)), math.sin(2 * math.pi * index / len(ring)))
+                 for index, name in enumerate(ring)}
+    if len(names) > 2:
+        positions[names[0]] = (0.0, 0.0)
+    size = min(14, 8 + 0.3 * len(names))
+    figure, axis = plt.subplots(figsize=(size, size))
+    axis.set_axis_off()
+    bend = 0.18  # curve both directions of a pair apart so their labels do not overlap
+    for relation in core:
+        (x1, y1), (x2, y2) = positions[relation["source"]], positions[relation["target"]]
+        axis.annotate("", xy=(x2, y2), xytext=(x1, y1),
+                      arrowprops={"arrowstyle": "->", "color": "#666666", "shrinkA": 22, "shrinkB": 22,
+                                  "connectionstyle": "arc3,rad=%s" % bend})
+        label_x = (x1 + x2) / 2 + bend * (y2 - y1) / 2
+        label_y = (y1 + y2) / 2 - bend * (x2 - x1) / 2
+        axis.text(label_x, label_y, short_label(relation["state"] or relation["label"] or "关系"),
+                  fontproperties=font, fontsize=9, ha="center", va="center", color="#333333",
+                  bbox={"boxstyle": "round", "fc": "white", "ec": "none", "alpha": 0.8})
+    for name, (x, y) in positions.items():
+        axis.text(x, y, png_text(name, "未命名"), fontproperties=font, fontsize=13, ha="center", va="center",
+                  bbox={"boxstyle": "round,pad=0.5", "fc": "#e8eef7", "ec": "#4a6fa5"})
+    axis.set_aspect("equal")
+    axis.set_xlim(-1.4, 1.4)
+    axis.set_ylim(-1.4, 1.4)
+    figure.savefig(str(root / CORE_PNG), dpi=150, bbox_inches="tight")
+    plt.close(figure)
+    written.append(CORE_PNG.as_posix())
+
+    changes = evolutions(relations)
+    if changes:
+        figure, axis = plt.subplots(figsize=(10, 1.2 + 0.8 * len(changes)))
+        axis.set_axis_off()
+        for row_index, ((source, target), rows) in enumerate(changes):
+            y = len(changes) - row_index
+            pair = "%s → %s" % (png_text(source, "未命名"), png_text(target, "未命名"))
+            axis.text(0, y, pair, fontproperties=font, fontsize=11, ha="left", va="center")
+            for step, row in enumerate(rows):
+                x = 3 + step * 2.2
+                if step:
+                    axis.annotate("", xy=(x - 0.6, y), xytext=(x - 1.6, y),
+                                  arrowprops={"arrowstyle": "->", "color": "#a58a4a"})
+                axis.text(x, y, png_text(row["state"] or row["label"], "关系"), fontproperties=font,
+                          fontsize=10, ha="center", va="center",
+                          bbox={"boxstyle": "round", "fc": "#f3efe6", "ec": "#a58a4a"})
+                if row["trigger"]:
+                    axis.text(x, y - 0.32, png_text(row["trigger"]), fontproperties=font, fontsize=8,
+                              ha="center", va="center", color="#666666")
+        axis.set_xlim(-0.2, 3 + 2.2 * max(len(rows) for _, rows in changes))
+        axis.set_ylim(0.3, len(changes) + 0.7)
+        figure.savefig(str(root / EVOLUTION_PNG), dpi=150, bbox_inches="tight")
+        plt.close(figure)
+        written.append(EVOLUTION_PNG.as_posix())
+    return written
+
+
+def render(root: Path, want_png: bool) -> Dict[str, object]:
+    source = root / RELATION_FILE
+    try:
+        text = source.read_text(encoding="utf-8-sig")
+    except OSError:
+        raise ChartError("relation_file_missing", "还没有 角色/角色关系.md，先整理人物关系，再生成关系图。")
+    relations, skipped = parse_relations(text)
+    if not relations:
+        raise ChartError("relation_table_empty", "角色/角色关系.md 里没有认得出的关系表（需要「主体 → 客体」一列），关系图没有生成。")
+    # The Markdown chart is the main result: write it before trying any picture.
+    atomic_write(root / CHART_MD, render_markdown(root.name, relations, "").encode("utf-8"))
+    png_written = []  # type: List[str]
+    messages = []  # type: List[str]
+    if skipped:
+        messages.append("角色/角色关系.md 里有 %s 行没认出是谁和谁的关系，没画进关系图。" % skipped)
+    if want_png:
+        drawn = "".join(png_text(value) for relation in relations
+                        for value in (relation["source"], relation["target"], relation["state"],
+                                      relation["label"], relation["trigger"]))
+        font_path, missing = find_cjk_font(drawn)
+        if not matplotlib_available():
+            messages.append(NO_MATPLOTLIB_MESSAGE)
+        elif not font_path:
+            messages.append(MISSING_GLYPH_MESSAGE % "".join(missing[:5]) if missing else NO_FONT_MESSAGE)
+        else:
+            try:
+                png_written = draw_png(relations, font_path, root)
+            except Exception:  # noqa: BLE001 - the Markdown chart is already written
+                messages.append(PNG_FAILED_MESSAGE)
+            if png_written:
+                atomic_write(root / CHART_MD,
+                             render_markdown(root.name, relations, "图片版见同目录的 PNG。").encode("utf-8"))
+    return {
+        "ok": True, "markdown": CHART_MD.as_posix(), "png": png_written,
+        "relations": len(relations), "skipped_rows": skipped,
+        "author_message": "".join(messages) or None,
+    }
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", required=True, type=Path, help="拆文库/{书名} 目录")
+    parser.add_argument("--png", action="store_true", help="also draw PNG pictures when a Chinese font exists")
+    args = parser.parse_args()
+    try:
+        if not args.root.is_dir():
+            raise ChartError("root_not_found", "没找到这本书的拆文目录，确认书名或路径。")
+        payload = render(args.root.resolve(), args.png)
+    except ChartError as exc:
+        payload = {"ok": False, "error": exc.code, "author_message": exc.author_message}
+    except (OSError, UnicodeError) as exc:
+        payload = {"ok": False, "error": "io_error", "detail": str(exc),
+                   "author_message": "关系图文件写入失败，检查拆文目录是否可写。"}
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if payload.get("ok") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -234,7 +234,10 @@ node scripts/jjwxc-rank-scraper.js --type 12 --list-only                 # 只
 
 ### Phase 4：输出扫榜报告
 
-```
+报告写给作者：讲市场结论和能写的方向。脚本名、命令和采集状态码不进报告；某个榜没采到，就说一句「XX 榜这次没拿到（原因），结论不含它」。
+
+<!-- author-report -->
+```md
 # 长篇网文扫榜报告：{平台名称}
 
 ## 市场概况

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

@@ -1,7 +1,7 @@
 ---
 name: story-long-write
 version: 1.0.0
-description: "长篇网文写作。从大纲到正文，辅助长篇网络小说的创作，包括世界观、人物、情节线管理。触发方式：/story-long-write、/写长篇、「帮我开书」「写大纲」「日更」「续写」「继续写」「修改第X章」「回炉」「重写第X章」。"
+description: "长篇网文规划与写作。支持只讨论结构、只写大纲或指定细纲，明确要求正文后再写章节。触发方式：/story-long-write、/写长篇、「帮我开书」「规划剧情」「写大纲」「补细纲」「日更」「续写」「继续写」「修改第X章」「回炉」「重写第X章」。"
 metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
 ---
 # story-long-write：长篇网文写作
@@ -14,10 +14,10 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 必须分块读到 EOF：
 
-1. 开书/补纲先完整读取 `references/workflow-setup.md`；写指定章读取 `references/workflow-chapter.md`；日更/大修先读取 `references/workflow-daily.md` 或 `references/workflow-revision.md`，进入正文前再完整读取 `workflow-chapter.md`。
+1. 规划/开书/补纲先完整读取 `references/workflow-setup.md`；写指定章读取 `references/workflow-chapter.md`；日更/大修先读取 `references/workflow-daily.md` 或 `references/workflow-revision.md`，进入正文前再完整读取 `workflow-chapter.md`。
 2. 主会话直接写正文时，首次落笔前完整读取 `references/long-format.md`、`references/writing-craft.md`、`references/long-chapter-quality.md`、`references/long-chapter-hooks.md`；交给 narrative-writer 时，由该 agent 按自己的 reference 表完成同等写前读取，主会话不得用未读 reference 的临时 prompt 替代。
 3. 悬疑、惊悚、异常线索章加读 `references/long-suspense.md`；身份/认知/立场反转章加读 `references/long-reversal.md`。
-4. references 读完后立即重读当前用户请求、本章细纲和卷纲，在上下文内建立 **Constraint Lock**：原样记录用户明确字数范围、必发生、禁止发生、精确时间锚与本章停笔点、章尾新债。references 只提供技法，不得覆盖这些项目事实；用户明确范围优先于自动 ± 比例带。交付前逐项复核：字数带外按 `workflow-chapter.md` 的收口流程交用户处置，不自动补字；其余项越界不算完成。
+4. 正文写前，references 读完后立即重读当前用户请求、本章细纲和卷纲，先在上下文里**记下本轮约束**：原样记录用户明确字数范围、必发生、禁止发生、精确时间锚与本章停笔点、章尾新债。references 只提供技法，不得覆盖这些项目事实；用户明确范围优先于自动 ± 比例带。交付前逐项复核：字数带外按 `workflow-chapter.md` 的收口流程交用户处置，不自动补字；其余项越界不算完成。
 
 任一必需路径不存在、不可读或未读完时立即停止，报告准确路径，**不得先写正文再补读**。门禁按当前任务、当前会话重新执行；旧会话的“读过”不能沿用。
 
@@ -25,7 +25,7 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 > 内置适配 Claude Code / OpenCode / Codex / Antigravity / ZCode / OpenClaw。专业 agent 只查当前端 canonical 目录（`.claude/agents`、`.opencode/agents`、`.codex/agents` TOML、`.agents/agents`）；Antigravity 用 `invoke_subagent` + 同名 `TypeName`。文件或运行时能力缺失、返回 unknown agent，或当前为不执行 custom agents 的 ZCode 3.3.4 时，报告 fallback 并 solo/direct 执行。
 >
-> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 30` 不一致时（标记缺失、字段缺失/非整数、小于或大于 30）**照常按文件存在性检查并 spawn**，但只检查当前运行时的 canonical 目录；同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 30）` 并提示重新运行 `/story-setup` 后新开会话；大于 30 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。
+> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 32` 不一致时（标记缺失、字段缺失/非整数、小于或大于 32）**照常按文件存在性检查并 spawn**，但只检查当前运行时的 canonical 目录；同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 32）` 并提示重新运行 `/story-setup` 后新开会话；大于 32 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。
 
 **文风裁决**：正文写作、改写或审稿前先读 [references/style-resolution.md](references/style-resolution.md)，加载本书文风并形成 `style_resolution`；无作者记忆也执行。当前请求、本书文风和 active 偏好按维度覆盖通用 references；同一裁决交给后续执行者。
 
@@ -37,8 +37,8 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 2. **从验证过的模式出发**。先问"什么被验证过有效，我如何重新交付"，少从"我想写什么"直接起步。扫榜找方向，拆文找模块，对标找节奏。
 3. **用模块组装，不要重新发明**。每个题材都有验证过的剧情模式——反转怎么铺、爽点怎么爆、感情怎么拉扯。找到对的模块，把对标书的具体角色看成功能位（对手/盟友/催化剂），再映射到你的角色。用你自己的素材填充这些功能位。
 4. **只加载必需信息**。写每章只读“不知道就会写错”的角色状态、待收伏笔、相关设定。其余留在文件系统里。
-5. **契约与推进决策走权威参考文件**。涉及读者契约、主角代理权、利益安全、期待债、终局储备（终局底牌/升级台阶）、机构/势力边界和 契约安全 / 需补强 / 契约破坏 风险判定时，先按 `references/reader-contract-and-progression.md` 校准，不在 SKILL.md 内复制长规则。
-6. **作者记忆**：按 [references/author-memory.md](references/author-memory.md) 查询本次相关 active 项、≤2KB，正文前原样传给执行者；当前请求、本书文风优先。长期声明用 `record` 写入并回传回执。
+5. **契约与推进决策走权威参考文件**。涉及读者契约、主角代理权、利益安全、终局底牌与升级台阶、机构/势力边界和契约风险判定时，先按 `references/reader-contract-and-progression.md`「契约四问」校准，不在 SKILL.md 内复制长规则。
+6. **作者记忆**：写正文时组装脚本已代查并注入；其他任务按 [references/author-memory.md](references/author-memory.md) 带 `--book-root` 查询 ≤2KB active 项交执行者；当前请求、本书文风优先。长期声明用 `record` 写入、回传回执。
 
 | 题材 | 核心情绪 | 重点参考 |
 |------|---------|---------|
@@ -54,35 +54,45 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 ## 写作流程
 
-根据用户意图和项目状态选择场景：
+先确定操作对象、交付范围和停点，再看项目状态；空项目不等于授权完整开书。范围与转正文的权威规则如下。
 
 | 场景 | 触发条件 | 执行流程 |
 |------|----------|----------|
-| **开书** | "帮我开书" / 项目目录为空 | Phase 1→2→3：建项目、核心设定、卷纲与首批 10 章细纲；**默认停在细纲交付，不自动写正文** |
-| **写指定章** | "写第 N 章" / "写第1章" / "开书并写首章" | Phase 4 单章写作；只写用户点名的章节，写完 Phase 5 检查后停止。空项目/无细纲（如"开书并写首章"）先补 Phase 1→3 再写点名章 |
-| **补纲/扩纲** | "出细纲/补细纲/规划下一段剧情/接下来写XX剧情（先出细纲）" **且**项目已有大纲 | Phase 3「中途补纲/扩纲小流程」（见 `references/workflow-setup.md`）：选同类剧情单元→追加剧情单元卡→按剧情批滚动补细纲；**默认停在细纲交付，不自动写正文** |
+| **结构讨论** | "只讨论/推敲故事结构" | 只交付结构方案，不建工程、不自动落盘；不要求先填完设定或细纲 |
+| **大纲规划** | "写大纲/规划剧情/规划全书/规划第X卷/开新卷" | 按需取 Phase 1→3，交付所请求大纲/卷纲及必要设定；不自动展开细纲或初始化追踪 |
+| **细纲规划** | "出细纲/补纲/扩纲/补细纲/写或修改第N章细纲" | Phase 3：既有单元内只补/改点名章；需要新单元才走「中途补纲/扩纲小流程」。指定范围不扩到整单元；未指定时按剧情批建纲 |
+| **开书** | "帮我开书"，未限定规划层级 | Phase 1→2→3：建项目、核心设定、卷纲与首批 10 章细纲；**默认停在细纲交付，不自动写正文** |
+| **写指定章** | "写第 N 章" / "写第1章" / "开书并写首章"，对象是正文 | Phase 4→5，只写点名章后停止；缺前置时先补必要设定、卷纲和点名章细纲，不套用完整开书的 10 章默认 |
 | **日更续写** | 关键词（"日更"/"续写"/"继续写"）**且**项目已有正文+追踪 | 加载 `references/workflow-daily.md` |
-| **大修** | "修改第X章" / "回炉" / "重写第X章" | 加载 `references/workflow-revision.md` |
+| **大修** | "修改第X章" / "回炉" / "重写第X章"，对象是已写正文 | 加载 `references/workflow-revision.md`；只改细纲不进此流程 |
 
-> **开新卷**：如果新卷引入新角色/势力/设定，先回 Phase 2 增量补充，再进 Phase 3 补充新卷细纲，最后 Phase 4 写作。如果纯延续，直接回 Phase 3。
+**对象优先**："写/修改第N章细纲"是规划，不因命中"写/修改第N章"而写正文；"以后再写正文"不是本轮授权。仅规划要求优先于旧日更任务，停止旧批量。对象不明或同一请求范围冲突时，只确认冲突项。
 
-### 裸调用与停靠点（防失控）
+**规划续接**：保留当前任务范围；"继续/按这个来/确认方案"不扩大范围，完成即停，不自动转细纲或正文。"继续写/接着写"指正文：下一章已有细纲时按写正文处理，但上一轮在规划就只问一句「要接着写第N章正文吗？」（默认是），不列选项表；缺细纲则问是否先补这一章细纲。新明确请求可调整规划层级/范围；不把规划模式写入追踪或作者记忆，不调用 narrative-writer，委派传同一范围和停点。
+
+**转入正文**：明确正文请求只授权进入既有写作流程，不等于可以直接落笔。创建/修改正文前，重新完成本轮全部正文 Reference Gate，并按 workflow-chapter 处理缺 state、使 `tracking_commit.py check` 通过；任一未完成则停止，不落正文。之后仍按原流程写作、质检、提交追踪，无须再问是否继续。
+
+**开新卷**：新角色/势力/设定按需回 Phase 2 增量补充；Phase 3 只做到本次请求的层级，不自动转正文。
 
-`/story-long-write` 或 `$story-long-write` **裸调用**（没有"开书/写第N章/日更/续写/修改"等明确意图）时，先只做项目状态诊断并列出下一步选项，**不得自动进入正文写作，也不得把已有项目默认为日更 3 章**：
+### 裸调用与停靠点（防失控）
 
-- 空项目 → 建议说「帮我开书」或先提供 `选题决策.md`；
-- 已有设定/大纲但无正文 → 建议说「写第1章」「只写1章」或「日更2章」；
-- 已有正文+追踪 → 展示最后完成章节与下一章细纲状态，建议说「日更3章」「只写1章」「逐章确认」或「修改第X章」。
+`/story-long-write` 或 `$story-long-write` **裸调用**（无明确意图）时，只诊断项目并列选项，**不得自动进入正文写作，也不得把已有项目默认为日更 3 章**：
 
-**开书默认停靠**：用户只说"开书/写大纲/帮我开书"时，完成 Phase 1→3 与首批 10 章细纲后停止，报告已生成文件和下一步命令；除非用户同一句明确说"并写第1章/写 N 章/日更"，否则不要自动进入 Phase 4 正文。
+- 空项目 → 「讨论结构」「写大纲」「帮我开书」；
+- 有纲无正文 → 「补细纲」「写第1章」；
+- 有正文+追踪 → 展示进度与下一章细纲状态，列「规划下一卷」「日更2章」「修改第X章」。
 
 **正文批量上限**：写正文必须由用户显式给出章节范围或日更意图。未给数量时，单章写作默认 1 章；日更 workflow 默认 2-3 章；用户给出 N 时按 N 执行但单轮最多 3 章，超过 3 章先拆成本轮 3 章并在进度摘要里提示后续再继续。
 
-**匹配优先级**：同时命中多行时，按 大修 → 写指定章 → 补纲/扩纲 → 日更续写 → 开书 的顺序匹配。用户点名要"细纲/补纲/规划剧情"而未要正文时，优先入 补纲/扩纲，不入日更。日更续写的 AND 条件（项目已有正文+追踪）不满足时，提示用户"项目还没有正文，建议先开书/写第1章"。
+**匹配顺序**：只规划按 结构讨论 → 细纲规划 → 大纲规划 → 开书，越窄越优先；要正文按 大修 → 写指定章 → 日更续写。日更前置不齐则提示补齐或写第1章，不直接写一批。
+
+**日更续接**：用户未改变任务时，同批"继续/续写/日更"仍走 `references/workflow-daily.md` 的完整串行流程，不直接落正文。正常批量不重复确认；阻塞或用户要求逐章确认时才暂停。切到规划后按上方「规划续接」，不恢复旧日更批量。
+
+无法判断场景时，给 2-4 个白话选项（如「只聊结构」「写大纲」「写第N章正文」）让用户选，不贴场景表，也不开放式提问。
 
-**日更续写保持在 workflow 内**：一旦本次请求路由到 `references/workflow-daily.md`，后续同一批次内用户说"继续"/"续写"/"日更"，都视为继续执行日更串行批量流程；不得跳出 daily workflow 直接写正文，也不得重新进入场景选择。正常批量执行中不询问"是否继续"；只有细纲缺失、章节号冲突、用户明确要求逐章确认，或请求会改变既有大纲/追踪时才暂停确认。
+### 面向作者的汇报
 
-无法判断场景时，列出上述场景表让用户选择，不要开放式提问。
+所有给作者看的汇报、提问和停下说明只讲三件事：写了/改了什么（章名、发生了什么）；要作者定的事（一句白话问题＋白话选项＋推荐默认）；下一步。不写脚本、字段、参数名、状态码和内部清单名（如 排纲自查、供给自查、S1-S4、字数带）；编号必带故事标签，如「伏笔 F057（那封信的去处）」。检查结果一句白话带过，如「自查过设定和前文，没发现冲突」。回执、Notice、Fallback 等机器行放末尾一行。汇报照各 workflow 的模板写，不带代码块围栏；子 agent 返回的术语由主会话翻译后再说。
 
 ### 路径与术语约定
 
@@ -93,10 +103,9 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 > **卷纲不整读（取段器）**：任何场景要卷纲内容一律走
 > `{PYTHON} {skill 根}/scripts/outline_view.py --unit {单元ID} {卷纲路径}`（脚本统一输出 UTF-8），
 > 只要契约不要单元时用 `--contract`，先看一屏目录用 `--toc`。
-> **两档分明**：**写正文用 `--stage write`**（卷级常任＋单元级，批次底稿一概不给）；**排纲/补纲用默认 `--stage outline`**（另带该单元在用的批次底稿）。
-> 供给自查、建纲追加、批次级复检这类底稿是**排纲期的工作底稿，写作期不是输入**——它们里头凡有写作期约束力的条目，
-> 建纲时就必须下沉到单元级段或细纲（`--check` 的 W1 告警专盯这个）。
-> 取的是**闭包不是点名段**——输出恒等于「全部卷级常任段 ＋ 该单元的单元级段 ＋ 该单元在用的批次底稿」，逐章表（情绪弧线等）按该单元章区间裁行，
+> 排纲期的工作底稿（供给自查、建纲追加）不写进卷纲，放 `大纲/排纲底稿_{单元ID}.md`，只在排纲/补纲时读，写正文不读；底稿里对写作有约束力的条目，建纲时写进单元卡或细纲。
+> 老卷纲里还留着「作用域：批次底稿」段的，排纲时加 `--stage outline` 一并取出，写正文照常不加。
+> 取的是**闭包不是点名段**——输出恒等于「全部卷级常任段 ＋ 该单元的单元级段」，逐章表（情绪弧线等）按该单元章区间裁行，
 > 带退役标记的行默认不输出（要看历史加 `--history`）。
 > 找不到单元时脚本 exit 1 并报错，不静默降级——报错就去核对单元ID或先补卷纲，不要改用整读绕过。
 > 段头的 `> 作用域：` 声明是这套的地基，格式与 checker 见 `references/artifact-protocols.md` 卷纲模板；
@@ -122,7 +131,7 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 ### Phase 3：大纲搭建
 
-产出全书体量与阶段总览、卷级大纲、逐章细纲；含大纲安全七检、大纲安全审查、分批建纲与「中途补纲/扩纲小流程」。
+产出全书体量与阶段总览、卷级大纲、逐章细纲；含排纲自查、分批建纲与「中途补纲/扩纲小流程」。
 
 **执行前先读 [references/workflow-setup.md](references/workflow-setup.md) 的「Phase 3：大纲搭建」节**。
 
@@ -136,11 +145,11 @@ metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudec
 
 #### 单章写作流程
 
-**执行前先读 [references/workflow-chapter.md](references/workflow-chapter.md)**，按其中的单章写作流程（步骤 1-13）、写作技巧提醒、字数验收权威与 Phase 5 质量检查执行。日更批量另加载 `references/workflow-daily.md` 控制批次。
+**执行前先读 [references/workflow-chapter.md](references/workflow-chapter.md)**，按其中的单章写作流程（步骤 1-13）、字数测量权威与质量检查执行。日更批量另加载 `references/workflow-daily.md` 控制批次。
 
-#### 追踪文件体积
+#### 追踪
 
-`追踪/_tracking-state.json` 是唯一结构化权威；`上下文.md`、核心角色快照、`伏笔.md`、作者真相与读者已知时间线都由它确定性派生，程序不反向解析 Markdown。`上下文.md` 固定 7 栏且 ≤12KB。`逐章记录/第NNN章.md` 每章只记录会影响后续连续性的紧凑变化，目标 ≤1536 字节、硬上限 3072 字节，不承诺单独重放出全部当前状态。阶段/卷级回看按需查询逐章记录或正文，不维护另一套长期摘要。所有追踪写入都通过 `scripts/tracking_commit.py`，禁止手改派生文件。
+所有追踪写入都走 `scripts/tracking_commit.py`：`追踪/_tracking-state.json` 是唯一权威，`上下文.md`、角色快照、`伏笔.md`、时间线都由它派生，禁止手改。体积上限由脚本检查、超限一次报全；字段与上限见 [tracking-transaction.md](references/tracking-transaction.md)，出错时才读。
 
 ---