@lemoncat7/dsh-partner 2.8.0 → 2.8.2

package/resources/skills/story-creation/upstream/skills/story-review/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-setup/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: story-setup
+version: 1.3.2
+description: "网文写作工具集基础设施部署与检查。为 Claude Code / OpenCode / Codex / Google Antigravity / ZCode / OpenClaw / Reasonix 提供内置适配；Web AI / 通用 Agent 可走 skills + AGENTS.md 文件模式。触发方式：/story-setup、$story-setup、「准备写书」「帮我搭一下环境」「配置写作项目」「检查写作环境」。"
+metadata: {"openclaw":{"source":"https://github.com/zenstory-ai/oh-story-claudecode"}}
+---
+# story-setup：网文写作工具集基础设施部署
+
+你是写作基础设施部署器。将网文写作工具集部署到用户项目目录：已适配的 CLI 走专用 hooks/agents/config；NarraFork、Web AI、自定义 Agent 等环境走通用文件模式。
+
+**执行铁律：不覆盖用户已有配置，合并而非替换。**
+
+作者第一次部署的顺序：判断当前宿主 → 确认项目根 → 按宿主部署 → 验收 → 告诉作者下一步。本文件只写各宿主通用的流程；每个宿主专属的部署清单、算法、校验和安装报告提示在各自的部署文件里，**只读本次目标宿主的那一份**（见 Phase 2）。
+
+## 选择模式
+
+- 参数为 `check`，或用户只要求检查部署、诊断环境、排查 agent 不可用时：完整读取 [references/diagnostics.md](references/diagnostics.md)，按其中流程仅检查并报告；不进入下面的部署流程。
+- 用户要求安装、更新或修复时：执行下面的部署流程。检查后已明确授权的修复沿用本文件与宿主部署文件的部署与合并规则。
+
+---
+
+## Phase 1：判断宿主与项目
+
+**先自检参考目录**：以正在执行的本 `SKILL.md` 所在目录为准，列出与它同级的 `references/` 下的子目录，核对下面 9 个名字是否都在**且都非空**——`agent-references`、`templates`、`opencode`、`codex`、`antigravity`、`zcode`、`openclaw`、`reasonix`、`generic`；同级 `references/deploy-*.md`（8 份宿主部署文件）、`scripts/merge-claude-settings.py`、`scripts/merge-codex-hooks.py`、`scripts/merge-antigravity-hooks.py`、`scripts/generate-antigravity-agents.mjs`、`scripts/deploy-antigravity-skills.py` 与 `scripts/copy-path-safety.py` 也必须存在（宿主部署步骤、Claude/Codex/Antigravity hooks 合并、Antigravity Skills 物化与 agent 生成、递归复制安全检查依赖它们）。有缺即 skill 包没装全，**立即停止，不写任何部署文件**，报告里区分「缺目录」「目录为空」和「缺脚本或部署文件」，并给修复指令：「story-setup 参考资料包不完整，缺 {路径}。按你的安装方式重装 oh-story-claudecode（命令行装的重跑 `npx skills add zenstory-ai/oh-story-claudecode -y -g`，marketplace / Plugin Management 装的在面板里重装），再执行 /story-setup。」
+
+> 判据是「有没有 `SKILL.md`」：只看正在执行的 `SKILL.md` 同级的 `references/`。项目内 `.claude/skills/story-setup/`、`.codex/skills/story-setup/` 和 OpenCode 的 `skills/story-setup/` 只有 `references/agent-references/`、不含 `SKILL.md`，不会是执行目录，也不要拿它们核对。Antigravity / ZCode / OpenClaw / Reasonix / generic 的项目副本是整份 skill 拷贝、自带 `SKILL.md`，9 个子目录本就齐全，照常核对即可。
+
+1. 检查当前目录是否已部署过（存在 `.story-deployed`）
+   - `agents_version` 缺失、非整数或小于 `34` → 标记为待更新，继续执行当前部署
+   - `agents_version: 34` → 使用 AskUserQuestion 确认是否重新部署；提示里写明重新部署只用**当前本地 skill 包**刷新项目文件，要拿 skill 本身的新版本得先更新 oh-story-claudecode（`npx skills add` 或 marketplace），再回来重跑
+   - `agents_version` 大于 `34` → 当前 story-setup 比项目部署旧；停止以避免降级覆盖，提示先更新 oh-story-claudecode，不写任何部署文件
+   - 同时读 `target_cli` 字段。**已部署项目以 sentinel 里的值为准**：非空时（逗号分隔的多端组合原样保留）这些端照常重新部署，不再让作者选；第 4 步仍判断当前宿主：判断出来且不在其中（作者换了软件）→ AskUserQuestion 问「这个文件夹之前是给 {已部署宿主名} 装的，你现在用的是 {当前宿主名}，要一起装上吗？」（「一起装上（推荐）」「只更新原来的」），选前者就加进 `target_cli`；判断不出不问。字段缺失或为空才走第 4-6 步。用户明确要求增删目标端时，用 AskUserQuestion 在现有值基础上改，改完的值写回 sentinel。
+   - `target_cli` 不含 opencode、但项目里有 `.opencode/plugins/story-hooks.ts` 或 `.opencode/agents/`（多端部署时 OpenCode 曾被版本门拦下）→ 用 AskUserQuestion 问是否把 OpenCode 加回来；选加回则先过 [references/deploy-opencode.md](references/deploy-opencode.md) 的「部署前置」，通过后写回 `target_cli`
+2. 检查是否有书名目录（包含 `追踪/` 子目录的目录，或用户自定义结构）
+   - 有 → 识别为长篇项目，显示当前项目信息
+   - 无 → 识别为新项目或短篇项目
+3. 检查 `.active-book` 文件是否存在：存在 → 显示当前活跃书目；不存在 → 跳过
+4. **判断当前宿主（能判断就不问作者）**。依次看，第一条能定下来的就用：
+   - 你自身的运行环境：系统提示、可用工具名或 skill 调用语法已表明你运行在 Claude Code、Codex、OpenCode、Google Antigravity（含命令行 `agy`）、ZCode、OpenClaw 或 Reasonix 里；
+   - 正在执行的本 `SKILL.md` 的安装位置带有宿主专属目录（如 `.claude/`、`.codex/`、`.zcode/`、`.gemini/`、`.openclaw/`、`.opencode/`）；
+   - 判断不出（例如网页版 AI、自建 Agent，或以上信号互相矛盾）→ 第 5 步的项目标记只当候选，交第 6 步问作者。
+5. 看项目里已有哪些宿主的标记：
+   - `.claude/` 或 `CLAUDE.md` → `target_cli = claude-code`
+   - `opencode.json`、`opencode.jsonc` 或 `.opencode/` → `target_cli = opencode`
+   - `.codex/`、`.codex/config.toml`、`.codex/agents/`、`.codex/hooks.json`、`AGENTS.md` 中的 Codex 段 → `target_cli = codex`
+   - `.agents/hooks.json`、`.agents/agents/`，或 `.agents/rules/oh-story.md` 中的 Antigravity 标记 → `target_cli = antigravity`
+   - `.zcode/`、`.zcode/config.json`、`zcode.json`、`.zcode/skills/`、`.zcode/commands/`、`AGENTS.md` 中的 ZCode 段 → `target_cli = zcode`
+   - `openclaw.json`、`.openclaw/`，或 `AGENTS.md` 中的 OpenClaw 段（标题行含 `网文写作工具集（OpenClaw）`）→ `target_cli = openclaw`
+   - `.reasonix/`、`reasonix-plugin.json`、`REASONIX.md`，或 `AGENTS.md` 中的 Reasonix 段（标题行含 `网文写作工具集（Reasonix）`）→ `target_cli = reasonix`
+   - `AGENTS.md` 中的通用段（标题行含 `网文写作工具集（通用 Agent / Web AI）`）→ `target_cli = generic`
+
+   > 后三类只认各端**互斥**的标记：`skills/*/SKILL.md` 的 `metadata.openclaw` 不作 OpenClaw 信号（13 个 skill 都带，三条 skills-only 路径部署出的 `skills/` 一样）；`.agents/skills/` 由 Antigravity、Codex 与 Reasonix 共用，也不单独作准。
+6. 定下 `target_cli`：
+   - 第 4 步定出了当前宿主 → `target_cli` 就是它。项目里另有其他宿主的标记时，用 AskUserQuestion 问一句白话：「这个文件夹之前也给 {其他宿主名} 装过写作工具，这次要一起更新吗？」选项：「只装 {当前宿主名}（推荐）」「一起更新」。作者一开始就说要装多个时照办。
+   - 定不出、项目标记恰好只有一个宿主 → AskUserQuestion 问「上次是给 {宿主名} 装的，这次还是它吗？」，是就用它，不是按下一条问。
+   - 定不出、其余情况 → 用 AskUserQuestion 问：「你现在是在哪个软件里跟我对话？」选项用产品名加一句说明：Claude Code（Anthropic 的命令行 / 桌面版）、Codex（OpenAI 的命令行）、OpenCode、Google Antigravity（含命令行 agy）、ZCode、OpenClaw、Reasonix（DeepSeek 的命令行）、网页版 AI 或其他工具（NarraFork、自建 Agent 等）、好几个都要用。提问工具一次放不下这么多选项时，把项目标记里出现过的放前面，其余让作者在「其他」里直接写名字。
+   - 作者的答案按「Claude Code → `claude-code`、网页版 AI 或其他工具 → `generic`、其余取小写产品名」换成 `target_cli`；多端为 `claude-code,opencode,codex,antigravity,zcode,openclaw,reasonix,generic` 中选中的端。
+7. **确认项目根（通常不问）**：项目根就是当前工作目录。只有当前目录是用户主目录、磁盘根目录、系统目录，或就是本 skill 包自身的安装/源码目录时，才用一句白话问作者：「写作工具要装在哪个文件夹？一般就是放书稿的那个文件夹。」其他情况直接部署，在安装报告的「部署明细」里写明装在哪。
+
+## Phase 2：部署基础设施
+
+整个 Phase 2 幂等：目录复制、文件写入和各宿主部署文件里的合并算法重复执行结果一致。因环境原因（工具不可用、权限被拒、网络失败）中途失败时，直接从头重跑本 Phase，不需要先清理半成品；`create only if absent` 的用户状态文件（见各部署清单的 Owner class）不会被二次覆盖。
+
+**两列基准目录不同**：部署清单里 `Source path` 相对正在执行的这份 skill 包，`Target path` 相对用户项目根。执行每一行（以及各宿主部署算法里的每个递归复制步骤）之前，先把通配符具体化为单个源/目标，再用本 `SKILL.md` 同级的 `scripts/copy-path-safety.py` 检查。该脚本按 `Path.resolve` / `realpath` 语义跟随已有 symlink，并在两侧都存在时用 `samefile` 核对文件系统对象；**只转绝对路径或比较字符串不算检查完成**。读取其 JSON：`status: same` 时 no-op，禁止复制；仅 `copy_allowed: true` 时可以复制；`source_missing`、`unsafe_target_within_source` 或 `filesystem_identity_error` 必须停止该步骤并报告。无法运行脚本时只能用当前环境的文件系统 API 做完全相同的 canonical realpath、same-object 与 target-descendant 检查；无法确认就停止，不得尝试复制。OpenClaw / Reasonix / generic 的项目副本是整份 skill 拷贝，重跑时执行的就是项目里那份；Reasonix / Codex 还可能经 `.agents/skills → ../skills` symlink 加载，路径文本不同也可能指向同一目录，照字面复制会把目录嵌进自身并撑满磁盘。
+
+**部署前清理自嵌套残留**：`{.claude,.codex,.zcode}/skills/story-setup/references/agent-references/` 与项目根 `skills/story-setup/references/agent-references/` 里若多出 `agent-references/` 层（可能嵌了多层），以及 `skills/story-setup/skills/`，整段删掉再部署，并在安装报告里列出删掉的路径。
+
+### Step 1：按宿主部署
+
+对 `target_cli` 里的每个宿主，**完整读取**对应部署文件，按其中的部署清单（机械可检查）与算法依次执行；不读其他宿主的文件。
+
+| `target_cli` | 部署文件 |
+|---|---|
+| `claude-code` | [references/deploy-claude-code.md](references/deploy-claude-code.md) |
+| `opencode` | [references/deploy-opencode.md](references/deploy-opencode.md)（先过其中「部署前置」版本门） |
+| `codex` | [references/deploy-codex.md](references/deploy-codex.md) |
+| `antigravity` | [references/deploy-antigravity.md](references/deploy-antigravity.md) |
+| `zcode` | [references/deploy-zcode.md](references/deploy-zcode.md) |
+| `openclaw` | [references/deploy-openclaw.md](references/deploy-openclaw.md) |
+| `reasonix` | [references/deploy-reasonix.md](references/deploy-reasonix.md) |
+| `generic` | [references/deploy-generic.md](references/deploy-generic.md) |
+
+多端部署时几个宿主共用根 `AGENTS.md`，按下方「AGENTS.md 合并策略」合并成一份；某一端被自己的前置条件拦下（如 OpenCode 版本门、Antigravity 缺 Node）时，按该端部署文件的规定处理，其他端照常部署。
+
+### Step 2：创建部署标记
+
+- 创建 `.story-deployed` 文件（sentinel file）
+- 写入以下字段（YAML `key: value` 格式，hook 用 `references/templates/hooks/lib/sentinel.sh` 读取）：
+  ```
+  deployed_at: <date -u +"%Y-%m-%dT%H:%M:%SZ">
+  agents_version: 34
+  setup_skill_version: 1.3.2
+  target_cli: claude-code（或 opencode、codex、antigravity、zcode、openclaw、reasonix、generic，或其任意组合）
+  resolver_strategy: project-local-skill-reference
+  references_dir: .claude/skills/story-setup/references/agent-references（Codex 写 .codex/skills/...；Antigravity 写 .agents/skills/...；ZCode 写 .zcode/skills/...；OpenCode / OpenClaw / Reasonix / generic 写 skills/...；多端用逗号分隔）
+  ```
+- 此文件供 session-start.sh 和写作 skill 检测部署状态，避免重复提示
+- 宿主部署文件里「部署标记补充」要求的额外标记一并创建（如 Claude Code 的重启确认标记）
+- 如果 `.story-deployed` 已存在但 `agents_version` 缺失、非整数或小于 `34`，按本次流程更新 hooks/agents/rules/reference bundle（具体变更见 `UPGRADING.md`）；大于 `34` 时已在 Phase 1 停止，不得降级覆盖
+
+## Phase 3：验证安装
+
+仅检查模式复用第 1–2 项，跳过第 3 项，且其中要求实际执行 hook 或写入 fixture 的子项改为只做静态校验（文件存在、语法有效、注册项齐全），不运行会写入项目的 hook，也不创建部署标记。
+
+1. 对 `target_cli` 里的每个宿主，执行其部署文件的「验证」一节。
+2. 验证部署标记：
+   - 检查 `.story-deployed` 是否存在且包含时间戳、`agents_version: 34`、`setup_skill_version: 1.3.2`、`target_cli`、`resolver_strategy`、`references_dir`
+3. 输出安装报告。读者是不懂编程的作者，按这个顺序写：
+   - **先写「现在可以做什么」**：用写书的话列本次部署后真正可用的事（如「可以开新书、续写：说 /story-long-write」「可以拆一本对标书」），端的限制如实翻译（如「这个工具里审稿由我一个人完成，没有分工助手」）。
+   - **再写「你还需要做的事」**：逐条可照做，如「新开一个会话」「在 Codex 里打开 /hooks，把 oh-story 的几条信任一下」「先安装 Node」；没有就写「无需其他操作」。这两段不出现脚本名、字段名、状态名或文件路径；各宿主部署文件「安装报告必须提示」的内容先翻译进这两段。
+   - **最后是简短的「部署明细」**：装在哪个文件夹、已部署文件、已合并的配置、删掉的残留路径、宿主部署文件要求的摘要（如 OpenCode 模型配置）和技术原因，放在报告末尾。
+
+---
+
+## 模板占位符
+
+| 占位符 | 替换规则 | 示例 |
+|--------|----------|------|
+| `{项目名}` | 用户项目名称或目录名 | 《剑来》、《暗卫》 |
+| `{书名}` | 书名目录名（与目录一致） | 与 `{项目名}` 相同，或用户自定义 |
+| `{目标平台}` | 目标发布平台 | 起点、番茄、晋江、知乎盐言 |
+| `{作者名}` | 用户笔名或昵称 | 未指定时用「作者」 |
+
+替换时去掉花括号。如果用户未指定项目名，用当前目录名。未指定的占位符保留原样不替换。CLAUDE.md 的合并策略在 Claude Code 部署文件里。
+
+## AGENTS.md 合并策略（OpenCode / Codex / ZCode / OpenClaw / Reasonix / generic）
+
+用户已有 AGENTS.md 时，按 marker/section 合并：
+1. 优先识别 story-setup 管理块标记（如果旧项目已有标记，只替换标记内内容）
+2. 无标记时，读取用户现有 AGENTS.md，按 `##` 标题切分为 section map
+3. OpenCode 使用 `skills/story-setup/references/opencode/AGENTS.md.tmpl`；Codex 使用 `skills/story-setup/references/codex/AGENTS.md.tmpl`；ZCode 使用 `skills/story-setup/references/zcode/AGENTS.md.tmpl`；OpenClaw 使用 `skills/story-setup/references/openclaw/AGENTS.md.tmpl`；Reasonix 使用 `skills/story-setup/references/reasonix/AGENTS.md.tmpl`；通用 Web AI / 其他 Agent 使用 `skills/story-setup/references/generic/AGENTS.md.tmpl`
+4. 模板中的标准 section（Skill 路由表、文件结构、协作规则、与作者协作、Compact 后恢复上下文；模板有而用户文件没有的 section 直接补入）覆盖同名 section；用户独有 section 保留
+5. 多端同时部署时，Codex/OpenCode/ZCode/OpenClaw/Reasonix/generic 共同可用的通用段落只保留一份；工具特有说明以小节区分，避免互相覆盖
+
+## 重新部署
+
+- `.story-deployed` 不存在 → 全新安装，Phase 2 全部执行
+- `.story-deployed` 存在且 `agents_version: 34` → 提示已部署，AskUserQuestion 确认是否重新部署；提示里写明重新部署只用当前本地 skill 包刷新项目文件，skill 本身的更新走 `npx skills add` 或 marketplace
+- `.story-deployed` 存在但 `agents_version` 缺失、非整数或小于 `34` → 提示需要更新，重新执行 Phase 2 覆盖 agents/hooks/rules/reference bundle，CLAUDE.md / AGENTS.md / settings.local.json / .codex/hooks.json / `.agents/hooks.json` / .zcode/config.json 走合并策略
+- `.story-deployed` 存在且 `agents_version` 大于 `34` → 当前 skill 版本过旧，停止并提示先更新 oh-story-claudecode；不覆盖项目中的更新部署
+
+---
+
+## 参考资料
+
+| 文件 | 用途 |
+|------|------|
+| references/deploy-*.md | 8 份宿主部署文件：各自的部署清单、算法、验证与安装报告提示，按 Phase 2 Step 1 只读目标宿主那份 |
+| [references/diagnostics.md](references/diagnostics.md) | 仅检查模式 |
+| UPGRADING.md | 各版本升级要点 |
+
+---
+
+## 流程衔接
+
+**流水线：** 部署
+**位置：** 初始化（最前置）
+
+| 时机 | 跳转到 | 命令 |
+|---|---|---|
+| 部署完成，开始写作 | story-long-write / story-short-write | `/story-long-write` 或 `/story-short-write` |
+| 导入已有小说做拆解 | story-import | `/story-import` |
+| 需要浏览器登录态（扫榜/拆文取原文） | browser-cdp | `/browser-cdp`；generic 需平台允许本地脚本/浏览器控制 |
+
+各端调用语法：Claude `/名`、Codex/ZCode `$名`、Antigravity 通过 `/skills` 浏览或直接点名、OpenClaw `/skill 名`、Reasonix / generic 直接点名 skill。

package/resources/skills/story-creation/upstream/skills/story-setup/references/agent-references/agent-quality.md

@@ -0,0 +1,72 @@
+# Agent 通用质量核心
+
+> 只放长篇与短篇都成立的判断。审查时必须再按 `agent-reference-profiles.md` 加载当前 profile 的质量覆盖文件；本文件不提供篇幅、密度或揭示位置阈值。
+
+## 叙事单元推进
+
+- [ ] 本单元改变目标、风险、信息、关系、资源、身份或情绪立场中的至少一项。
+- [ ] 删除本单元会造成可指出的因果、人物或期待损失；答不出才判为可能填充。
+- [ ] 开头承接当前目标或提出有效异常，不用无功能天气、风景或日常垫场。
+- [ ] 结尾落在决定、发现、后果、关系变化或未完成动作上，不用作者总结代替变化。
+- [ ] 推进强弱服从当前 profile、题材和已建立的兑现节奏，不套跨体裁固定字数。
+
+## 信息与场景
+
+- [ ] 每个场景有目标、阻碍和结束后的状态变化。
+- [ ] 设定跟着行动、冲突或证据出现，没有连续说明文。
+- [ ] 人物在选择、行动或承受后果，不是连续几段重复感觉同一情绪。
+- [ ] 新概念数量与当前场景的理解负荷匹配；必要概念给可验证的使用边界。
+
+## 语言与格式
+
+- [ ] 对话符合身份、关系与当下权力位置，不同角色能区分。
+- [ ] 抽象情绪有选择、台词、物件或实际后果支撑；直写更准确时可以直写。
+- [ ] 没有空泛总结、连续套路修辞或为显得精致而堆叠身体反应。
+- [ ] 标题行以外不混入“本章、细纲、伏笔、读者”等写作工程元信息；故事内真实语境除外。
+
+## 五维评分
+
+每个维度 0–100 分。分数必须附证据和失败影响，不凭整体印象打分。
+
+### 核心一致度
+
+检查关键冲突、行动、人物动机和收益归属是否前后一致。
+
+| 问题 | 严重度 | 修复 |
+|---|---|---|
+| 人物动机无触发突然改变 | critical | 补触发或调整行动 |
+| 核心冲突前后不一致 | high | 回溯统一冲突设定 |
+| 关键行动与已立人设矛盾 | high | 调整行动或补足可见原因 |
+| 次要矛盾被遗忘 | medium | 回收、延期并留痕，或明确弱化 |
+
+### 表层重写度
+
+检查措辞是否自然、是否复刻输入形状或套用万能表达。正常原句不为追求“重写率”强改。
+
+| 问题 | 严重度 | 修复 |
+|---|---|---|
+| 照搬提纲或参考原句导致语气不自然 | medium | 保留事实，重组叙事形状 |
+| AI 标志词、同构句或解释尾巴成片出现 | high | 改成具体行动、证据或关系后果 |
+| 辞藻、比喻或身体反应堆叠 | medium | 删除无功能部分，保留角色化细节 |
+
+### 格式一致度
+
+检查段落是否按戏剧单元自然断开、引号与章节标记是否服从项目约定、目标字数是否使用当前流程的确定性口径。
+
+### 可读性
+
+检查是否啰嗦、信息顺序混乱、心理描写空转或重要因果被华丽表达遮住。带新信息、决断或情绪转折的独白不按句数压缩。
+
+### 逻辑连贯
+
+检查设定、时间线、角色知识、证据链和“原因 → 行动 → 结果 → 后果”是否闭合；证据不足时明确标注，不替作者补设定。
+
+## 严重度与修复策略
+
+| 级别 | 判定 | 动作 |
+|---|---|---|
+| blocking / critical | 核心契约、因果或事实无法成立 | 必须修：先修再继续下游写作 |
+| high | 会明显损害追读、人物可信度或核心卖点 | 必须修：本轮修复 |
+| medium | 局部拖慢、重复或表达不清 | 建议看：按收益排序修复 |
+| low / optional | 不影响成立，只是可增强 | 仅提示：不得包装成硬门槛 |
+