@oh-story/dsh 0.1.4 → 0.1.5

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

@@ -3,25 +3,40 @@
 
 The language model supplies compact semantic JSON.  This tool validates and
 merges that input in memory, renders every derived view, then atomically writes
-``_tracking-state.json`` last as the single commit point.  One book project has
-one serial writer; concurrent commits are intentionally unsupported.
+``_tracking-state.json`` last as the single commit point. Per-project locking
+serializes concurrent writers before revision and wordcount checks.
 """
 
 from __future__ import annotations
 
 import argparse
 import copy
+import importlib.util
 import json
 import os
 import re
 import stat
 import sys
 import tempfile
+import time
 import unicodedata
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
 
+_WORDCOUNT_CORE_PATH = Path(__file__).with_name("wordcount_core.py")
+if not _WORDCOUNT_CORE_PATH.is_file():  # pragma: no cover - broken deployment
+    raise RuntimeError("TOOL_UNAVAILABLE: wordcount_core.py")
+_WORDCOUNT_CORE_SPEC = importlib.util.spec_from_file_location(
+    "story_wordcount_core", _WORDCOUNT_CORE_PATH
+)
+if _WORDCOUNT_CORE_SPEC is None or _WORDCOUNT_CORE_SPEC.loader is None:  # pragma: no cover
+    raise RuntimeError("unable to load wordcount core")
+wordcount_core = importlib.util.module_from_spec(_WORDCOUNT_CORE_SPEC)
+_WORDCOUNT_CORE_SPEC.loader.exec_module(wordcount_core)
+
+
 INPUT_SCHEMA_VERSION = 1
 TRACKING_SCHEMA_VERSION = 4
 DELTA_TARGET_BYTES = 1536
@@ -74,6 +89,13 @@ def require(condition: bool, message: str) -> None:
         raise TrackingError(message)
 
 
+def wordcount_value(function: Any, *args: Any, **kwargs: Any) -> Any:
+    try:
+        return function(*args, **kwargs)
+    except wordcount_core.WordcountError as exc:
+        raise TrackingError(str(exc)) from exc
+
+
 def as_mapping(value: object, label: str) -> dict[str, Any]:
     require(isinstance(value, dict), f"{label} must be a JSON object")
     return value
@@ -188,6 +210,34 @@ def state_path(project: Path) -> Path:
     return tracking_root(project) / "_tracking-state.json"
 
 
+@contextmanager
+def project_write_lock(project: Path, *, timeout_seconds: float = 10.0):
+    tracking = tracking_root(project)
+    tracking.mkdir(parents=True, exist_ok=True)
+    path = tracking / ".tracking-commit.lock"
+    deadline = time.monotonic() + timeout_seconds
+    descriptor: int | None = None
+    while descriptor is None:
+        try:
+            descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            if time.monotonic() >= deadline:
+                raise TrackingError(
+                    "tracking commit lock is busy or stale; retry, or remove 追踪/.tracking-commit.lock after confirming no commit is running"
+                )
+            time.sleep(0.05)
+    try:
+        os.write(descriptor, f"pid={os.getpid()}\n".encode("ascii"))
+        os.fsync(descriptor)
+        yield
+    finally:
+        os.close(descriptor)
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+
+
 def delta_path(tracking: Path, chapter: int) -> Path:
     width = max(3, len(str(chapter)))
     return tracking / "逐章记录" / f"第{chapter:0{width}d}章.md"
@@ -735,6 +785,18 @@ def render_delta(chapter: int, title: str, delta: dict[str, Any], core_names: se
     return payload
 
 
+def normalize_wordcount_records(value: object, last_chapter: int) -> dict[str, dict[str, Any]]:
+    records = as_mapping(value, "tracking state.wordcount_records")
+    normalized: dict[str, dict[str, Any]] = {}
+    for raw_chapter, raw_record in records.items():
+        require(isinstance(raw_chapter, str) and re.fullmatch(r"[1-9]\d*", raw_chapter) is not None,
+                "wordcount record chapter key is invalid")
+        chapter = int(raw_chapter)
+        require(chapter <= last_chapter, "wordcount record exceeds last committed chapter")
+        normalized[raw_chapter] = wordcount_value(wordcount_core.normalize_wordcount_record, raw_record)
+    return normalized
+
+
 def normalize_state(document: object) -> dict[str, Any]:
     root = as_mapping(document, "tracking state")
     require_known_keys(
@@ -742,6 +804,7 @@ def normalize_state(document: object) -> dict[str, Any]:
         {
             "schema_version", "book_title", "last_committed_chapter", "imported_through_chapter",
             "state_revision", "context", "characters", "foreshadow", "timeline",
+            "wordcount_records",
         },
         "tracking state",
     )
@@ -766,16 +829,19 @@ def normalize_state(document: object) -> dict[str, Any]:
     if last_chapter == 0:
         require(not foreshadow, "a chapter-0 project cannot have planted foreshadow facts")
         require(not timeline, "a chapter-0 project cannot have established timeline facts")
+    state_revision = as_int(root.get("state_revision"), "tracking state.state_revision")
+    wordcount_records = normalize_wordcount_records(root.get("wordcount_records", {}), last_chapter)
     return {
         "schema_version": TRACKING_SCHEMA_VERSION,
         "book_title": clean_text(root.get("book_title"), "tracking state.book_title", max_bytes=240),
         "last_committed_chapter": last_chapter,
         "imported_through_chapter": imported_through,
-        "state_revision": as_int(root.get("state_revision"), "tracking state.state_revision"),
+        "state_revision": state_revision,
         "context": context,
         "characters": characters,
         "foreshadow": foreshadow,
         "timeline": timeline,
+        "wordcount_records": wordcount_records,
     }
 
 
@@ -789,7 +855,10 @@ def normalize_initial_document(document: object) -> dict[str, Any]:
     root = as_mapping(document, "init input")
     require_known_keys(
         root,
-        {"schema_version", "book_title", "last_chapter", "context", "character_snapshots", "foreshadow", "timeline_events"},
+        {
+            "schema_version", "book_title", "last_chapter", "context", "character_snapshots",
+            "foreshadow", "timeline_events",
+        },
         "init input",
     )
     require(root.get("schema_version") == INPUT_SCHEMA_VERSION, "init input schema_version is unsupported")
@@ -826,17 +895,18 @@ def normalize_initial_document(document: object) -> dict[str, Any]:
             "characters": snapshots,
             "foreshadow": foreshadow,
             "timeline": timeline,
+            "wordcount_records": {},
         }
     )
 
 
-def normalize_transaction(state: dict[str, Any], document: object) -> dict[str, Any]:
+def normalize_transaction(project: Path, state: dict[str, Any], document: object) -> dict[str, Any]:
     root = as_mapping(document, "transaction")
     require_known_keys(
         root,
         {
             "schema_version", "mode", "chapter", "chapter_title", "expected_state_revision",
-            "delta", "context", "character_snapshots",
+            "delta", "context", "character_snapshots", "wordcount",
         },
         "transaction",
     )
@@ -845,6 +915,7 @@ def normalize_transaction(state: dict[str, Any], document: object) -> dict[str,
     require(mode in {"append", "revision"}, "mode must be append or revision")
     chapter = as_int(root.get("chapter"), "chapter", minimum=1)
     expected_revision = as_int(root.get("expected_state_revision"), "expected_state_revision")
+    wordcount_input = root.get("wordcount")
     require(expected_revision == state["state_revision"], "tracking state changed since this transaction was prepared")
     last = state["last_committed_chapter"]
     if mode == "append":
@@ -864,6 +935,11 @@ def normalize_transaction(state: dict[str, Any], document: object) -> dict[str,
         snapshots=snapshots,
         existing_core_names=existing_names,
     )
+    wordcount = None
+    if wordcount_input is not None:
+        wordcount = wordcount_value(
+            wordcount_core.validate_current_wordcount_record, project, chapter, wordcount_input
+        )
     return {
         "mode": mode,
         "chapter": chapter,
@@ -871,6 +947,7 @@ def normalize_transaction(state: dict[str, Any], document: object) -> dict[str,
         "delta": delta,
         "context": context,
         "snapshots": snapshots,
+        "wordcount": wordcount,
     }
 
 
@@ -891,6 +968,8 @@ def merge_transaction(state: dict[str, Any], transaction: dict[str, Any]) -> dic
         next_state["last_committed_chapter"] = chapter
     next_state["state_revision"] += 1
     next_state["characters"].update(transaction["snapshots"])
+    if transaction["wordcount"] is not None:
+        next_state["wordcount_records"][str(chapter)] = transaction["wordcount"]
 
     next_context = transaction["context"]
     # 退役说的是「从此刻起离开当前状态」，只有 append 的逐章记录代表此刻；
@@ -1013,7 +1092,7 @@ def warn_sizes(views: dict[str, str], delta_payload: str | None = None) -> None:
             )
 
 
-def initialize(project: Path, document: object) -> dict[str, Any]:
+def _initialize_locked(project: Path, document: object) -> dict[str, Any]:
     tracking = tracking_root(project)
     require(not state_path(project).exists(), "tracking state already exists; init never overwrites project state")
     state = normalize_initial_document(document)
@@ -1036,11 +1115,16 @@ def initialize(project: Path, document: object) -> dict[str, Any]:
     return state
 
 
-def apply_transaction(project: Path, document: object) -> dict[str, Any]:
+def initialize(project: Path, document: object) -> dict[str, Any]:
+    with project_write_lock(project):
+        return _initialize_locked(project, document)
+
+
+def _apply_transaction_locked(project: Path, document: object) -> dict[str, Any]:
     tracking = tracking_root(project)
     require_no_retired_tracking_paths(tracking)
     state = load_state(project)
-    transaction = normalize_transaction(state, document)
+    transaction = normalize_transaction(project, state, document)
     next_state = merge_transaction(state, transaction)
 
     delta_payload = render_delta(
@@ -1067,6 +1151,11 @@ def apply_transaction(project: Path, document: object) -> dict[str, Any]:
     return next_state
 
 
+def apply_transaction(project: Path, document: object) -> dict[str, Any]:
+    with project_write_lock(project):
+        return _apply_transaction_locked(project, document)
+
+
 def check_project(project: Path) -> dict[str, Any]:
     tracking = tracking_root(project)
     require_no_retired_tracking_paths(tracking)

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

@@ -0,0 +1,246 @@
+#!/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*$")
+_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)
+
+
+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 compute_wordcount_bands(value: Any) -> dict[str, dict[str, int]]:
+    target = parse_target(value)
+    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,
+        "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,
+) -> 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:
+        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)
+    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),
+        "status": status, "invalid_reason": None,
+    }
+
+
+def checkpoint_wordcount(
+    value: str, target_value: Any, *, chapter: Any = None, case_id: Any = None,
+) -> dict[str, Any]:
+    target = parse_target(target_value)
+    actual = count_visible_chars(value)
+    user = compute_wordcount_bands(target)["user"]
+    return {
+        "schema": CHECKPOINT_SCHEMA, "metric": METRIC, "chapter": chapter, "case_id": case_id,
+        "target": target, "actual": actual, "user_band": user,
+        "remaining_user_range": {
+            "min": max(0, user["min"] - actual),
+            "max": max(0, user["max"] - actual),
+        },
+    }
+
+
+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])
+
+
+def _chapter_number_from_name(name: str, *, outline: bool) -> int | 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 build_project_wordcount_record(project: Path, chapter: int, *, resolution: str) -> dict[str, Any]:
+    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)
+    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)
+    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",
+    )
+    return {
+        "metric": METRIC,
+        "target": result["target"],
+        "actual": result["actual"],
+        "status": result["status"],
+        "resolution": resolution,
+        "body_sha256": hashlib.sha256(body_bytes).hexdigest(),
+    }
+
+
+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"},
+        "wordcount record fields are invalid",
+    )
+    require(value.get("metric") == METRIC, "wordcount metric is unsupported")
+    target = parse_target(value.get("target"))
+    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)
+    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 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"])
+    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

@@ -2,7 +2,7 @@
 name: story-long-analyze
 version: 1.0.0
 description: "长篇网文拆文。深度拆解爆款长篇小说的黄金三章、人设架构、爽点设计、节奏控制。单一深度拆解管道：跑完黄金三章（Stage 1）后产出快速预览报告并询问是否继续全量拆解，确认后从 Stage 2 续跑逐章摘要、聚合分析、设定关系、汇总报告，全程产物落盘 拆文库/{书名}/。触发方式：/story-long-analyze、/长篇拆文、「帮我拆这本书」「拆这本书」「分析黄金三章」「深度拆解」「完整拆解」「系统拆解」或提供小说文本文件路径——全部进入同一管道。"
-metadata: {"openclaw":{"source":"https://github.com/worldwonderer/oh-story-claudecode"}}
+metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
 ---
 # story-long-analyze：长篇网文拆文
 
@@ -12,9 +12,9 @@ metadata: {"openclaw":{"source":"https://github.com/worldwonderer/oh-story-claud
 
 ---
 
-> Agent 兼容性：检查专业 agent 是否可用时，按 `.claude/agents/{agent}.md` → `.opencode/agents/{agent}.md` → `.codex/agents/{agent}.toml` 的顺序查找。Codex 原生子代理调用优先使用同名 `agent_type`；如果当前 Codex 运行时返回 `unknown agent_type` 或未暴露 custom-agent registry，必须降级为 solo/direct。检测到 `.zcode/` 时同样直接 solo/direct，因为 ZCode 3.3.4 不执行项目 custom agents；报告 `Fallback: project custom agents unavailable -> solo`。Claude/OpenCode 兼容面保留 `subagent_type`。
+> Agent 兼容性：只检查当前运行时的 canonical 目录：Claude `.claude/agents/{agent}.md`、OpenCode `.opencode/agents/{agent}.md`、Codex `.codex/agents/{agent}.toml`、Antigravity `.agents/agents/agent-name/agent.md`（`agent-name` 为目标 agent 名），不得因其他端文件存在而误判。Codex 使用同名 `agent_type`；Antigravity 使用 `invoke_subagent` + `TypeName`。对应运行时未暴露 custom-agent registry / `invoke_subagent` 或返回未知 agent 时，必须降级 solo/direct。检测到 `.zcode/` 时同样直接 solo/direct，因为 ZCode 3.3.4 不执行项目 custom agents；报告 `Fallback: project custom agents unavailable -> solo`。Claude/OpenCode 兼容面保留 `subagent_type`。
 >
-> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 25` 不一致时（标记缺失、字段缺失/非整数、小于或大于 25）**照常按文件存在性检查并 spawn**，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 25）` 并提示重新运行 `/story-setup` 后新开会话；大于 25 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。
+> Spawn 版本提示（不阻断 spawn）：先读取项目根 `.story-deployed` 的 `agents_version`。与本版 `agents_version: 29` 不一致时（标记缺失、字段缺失/非整数、小于或大于 29）**照常按文件存在性检查并 spawn**，同时报告 `Notice: agents bundle 版本不匹配（项目 {N}，本版 29）` 并提示重新运行 `/story-setup` 后新开会话；大于 29 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 `Fallback: ... -> solo`。
 
 ## 拆解边界声明（主线程同样适用）
 
@@ -267,7 +267,7 @@ Agent(
 
 以下任一情况，Stage 2 自动退回串行模式，由主线程逐章处理（质量不受影响，只是改为串行、速度略慢）。**两条路径的要求是同一份**：串行时概要写法、情节点白描、原文引用精选规则和输出自检都按 [output-templates.md](references/output-templates.md)「Stage 2 章节摘要+情节点」执行；上面的机械硬检查串行同样要跑。串行没有 sonnet 升级重试这条路——硬检查命中时由主线程按失败项重写本章摘要 1 次，仍不过按 `⚠️ 跳过` 记入 `_progress.md` 「失败记录」表。
 
-- **agent 未部署**：agent 目录（优先 `.claude/agents/`，其次 `.opencode/agents/`，再检查 `.codex/agents/`）下的 `chapter-extractor.md` 或 `.codex/agents/chapter-extractor.toml` 不存在。`.claude/agents/` 通常不随仓库提交，应重新运行 `/story-setup` 完成当前适配器部署，不跨 Skill 读取模板源。
+- **agent 未部署**：当前运行时的 canonical agent 目录未找到 `chapter-extractor.md` 或 Codex 同名 TOML。项目 agent 通常不随写作仓库预置，应重新运行 `/story-setup` 完成当前适配器部署，不跨 Skill 读取模板源。
 - **环境不支持 spawn 子代理**：本 skill 正运行在某个子代理上下文中，无法再起下一层 agent。
 
 ### Stage 2 收尾：合并章节摘要（_章节摘要汇总.md）

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

@@ -2,7 +2,7 @@
 name: story-long-scan
 version: 1.0.0
 description: "长篇网文扫榜。分析起点、番茄、晋江等平台排行榜数据，提炼市场趋势与热门题材。触发方式：/story-long-scan、/长篇扫榜、「长篇什么火」「起点排行」。"
-metadata: {"openclaw":{"source":"https://github.com/worldwonderer/oh-story-claudecode"}}
+metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
 ---
 # story-long-scan：长篇网文扫榜