Skip to content

zenstory-ai/oh-story-claudecode / skills/story-long-write

story-long-write

Verified

长篇网文规划与写作。支持只讨论结构、只写大纲或指定细纲,明确要求正文后再写章节。触发方式:/story-long-write、/写长篇、「帮我开书」「定设定」「出卷纲」「规划剧情」「写大纲」「补细纲」「日更」「续写」「继续写」「修改第X章」「回炉」「重写第X章」。

FileKindSize
SKILL.mdskill md13.0 KB
references/agent-calls.mdmarkdown5.3 KB
references/artifact-protocols.mdmarkdown9.8 KB
references/author-memory.mdmarkdown6.6 KB
references/banned-words.mdmarkdown10.9 KB
references/benchmark-recall.mdmarkdown5.2 KB
references/character-basics.mdmarkdown12.3 KB
references/character-relations.mdmarkdown10.2 KB
references/cross-book-recall.mdmarkdown3.9 KB
references/dialogue-mastery.mdmarkdown11.0 KB
references/emotional-methods.mdmarkdown7.9 KB
references/female-audience-writing.mdmarkdown7.5 KB
references/genre-prose-cards.mdmarkdown7.0 KB
references/genre-prose-cards/东方仙侠.mdmarkdown2.3 KB
references/genre-prose-cards/传统玄幻.mdmarkdown1.9 KB
references/genre-prose-cards/历史古代.mdmarkdown1.7 KB
references/genre-prose-cards/历史脑洞.mdmarkdown2.0 KB
references/genre-prose-cards/双男主.mdmarkdown2.3 KB
references/genre-prose-cards/古言脑洞.mdmarkdown1.8 KB
references/genre-prose-cards/古风世情.mdmarkdown2.3 KB
references/genre-prose-cards/女频悬疑.mdmarkdown1.8 KB
references/genre-prose-cards/女频种田.mdmarkdown1.8 KB
references/genre-prose-cards/宫斗宅斗.mdmarkdown1.6 KB
references/genre-prose-cards/年代.mdmarkdown2.1 KB
references/genre-prose-cards/快穿.mdmarkdown1.9 KB
references/genre-prose-cards/悬疑灵异.mdmarkdown1.7 KB
references/genre-prose-cards/悬疑脑洞.mdmarkdown1.9 KB
references/genre-prose-cards/战神赘婿.mdmarkdown1.9 KB
references/genre-prose-cards/抗战谍战.mdmarkdown1.8 KB
references/genre-prose-cards/星光璀璨.mdmarkdown1.8 KB
references/genre-prose-cards/民国言情.mdmarkdown1.9 KB
references/genre-prose-cards/流派兜底.mdmarkdown8.4 KB
references/genre-prose-cards/游戏体育.mdmarkdown1.9 KB
references/genre-prose-cards/玄幻脑洞.mdmarkdown2.0 KB
references/genre-prose-cards/玄幻言情.mdmarkdown1.7 KB
references/genre-prose-cards/现言脑洞.mdmarkdown1.8 KB
references/genre-prose-cards/科幻末世.mdmarkdown1.7 KB
references/genre-prose-cards/职场婚恋.mdmarkdown1.7 KB
references/genre-prose-cards/西方奇幻.mdmarkdown1.9 KB
references/genre-prose-cards/豪门总裁.mdmarkdown2.3 KB
references/genre-prose-cards/都市修真.mdmarkdown1.7 KB
references/genre-prose-cards/都市日常.mdmarkdown2.8 KB
references/genre-prose-cards/都市种田.mdmarkdown1.7 KB
references/genre-prose-cards/都市脑洞.mdmarkdown2.4 KB
references/genre-prose-cards/都市高武.mdmarkdown2.0 KB
references/genre-prose-cards/青春甜宠.mdmarkdown1.8 KB
references/genre-readers.mdmarkdown6.9 KB
references/long-chapter-hooks.mdmarkdown6.5 KB
references/long-chapter-quality.mdmarkdown3.3 KB
references/long-format.mdmarkdown2.1 KB
references/long-genre-catalog.mdmarkdown11.9 KB
references/long-genre-mechanics.mdmarkdown8.3 KB
references/long-reversal.mdmarkdown12.3 KB
references/long-suspense.mdmarkdown9.2 KB
references/opening-design.mdmarkdown4.5 KB
references/outline-methods.mdmarkdown12.5 KB
references/outline-template.mdmarkdown8.0 KB
references/plot-core-methods.mdmarkdown5.3 KB
references/project-files.mdmarkdown4.7 KB
references/reader-contract-and-progression.mdmarkdown6.9 KB
references/revision-diagnosis.mdmarkdown3.6 KB
references/style-combat-face.mdmarkdown9.1 KB
references/tracking-initialization.mdmarkdown1.6 KB
references/tracking-transaction.mdmarkdown9.0 KB
references/workflow-chapter.mdmarkdown12.5 KB
references/workflow-daily.mdmarkdown6.3 KB
references/workflow-outline.mdmarkdown11.5 KB
references/workflow-revision.mdmarkdown6.5 KB
references/workflow-setup.mdmarkdown10.9 KB
references/workflow-volume.mdmarkdown6.4 KB
references/writing-craft.mdmarkdown23.6 KB
scripts/author_memory_commit.pyscript75.0 KB
scripts/build_architect_brief.pyscript21.8 KB
scripts/build_writer_prompt.pyscript41.7 KB
scripts/check-ai-patterns.jsexecutablescript79.8 KB
scripts/check-degeneration.jsscript15.4 KB
scripts/check-outline-contract.jsscript28.3 KB
scripts/check-outline-copy.jsscript13.4 KB
scripts/convert_outline_format.pyscript20.0 KB
scripts/normalize-punctuation.jsexecutablescript19.0 KB
scripts/outline_view.pyscript18.2 KB
scripts/storyctl.pyexecutablescript37.0 KB
scripts/style-whitelist.jsscript1.1 KB
scripts/template_fence.pyscript2.6 KB
scripts/tracking_commit.pyscript89.6 KB
scripts/wordcount_core.pyexecutablescript18.9 KB

scripts/tracking_commit.py

View on GitHub
#!/usr/bin/env python3
"""Maintain one structured story state and its deterministic Markdown views.

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. 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
DELTA_MAX_BYTES = 3072
CONTEXT_TARGET_BYTES = 8192
CONTEXT_MAX_BYTES = 12288
# 角色快照属按需读取的冷视图(不进 上下文.md 四列表);单文件上限对齐各宿主单次无分页 Read 的 25K token 边界。
SNAPSHOT_TARGET_BYTES = 16384
SNAPSHOT_MAX_BYTES = 65536
SNAPSHOT_ITEM_MAX_BYTES = 600
DRAFT_INLINE_SNAPSHOTS_MAX_BYTES = 16384
# 下一章热上下文里列出的活跃角色,不是核心角色总数;体积仍由 CONTEXT_MAX_BYTES 兜底。
ACTIVE_CHARACTER_MAX = 20

CONTEXT_HEADINGS = (
    "## 当前位置",
    "## 长期约束",
    "## 核心角色状态",
    "## 活跃伏笔",
    "## 近三章速记",
    "## 下一章承诺",
    "## 连贯性风险",
)
FORESHADOW_STATUSES = ("已埋", "已回收", "已过期", "放弃")
FORESHADOW_IMPORTANCE = ("高", "中", "低")
REVEAL_STATUSES = ("未揭示", "部分揭示", "已揭示")
# 伏笔与时间线条目里模型常用的同义写法:含义明确的直接改成正式名,不让一次提交为措辞失败。
ACTION_ALIASES = {
    "add": "upsert", "new": "upsert", "create": "upsert", "update": "upsert", "plant": "upsert",
    "advance": "upsert", "resolve": "upsert", "insert": "upsert",
    "新增": "upsert", "埋设": "upsert", "更新": "upsert", "推进": "upsert", "回收": "upsert",
    "remove": "delete", "删除": "delete",
}
# 带状态含义的伏笔动作词:它们也映射成 upsert,但动作词本身说了伏笔走到哪一步。
# status 缺省时按动作词补上(意图只有这一个来源,不会猜错);status 与动作词矛盾时退回,
# 因为无法判断是动作词用错还是状态写错——静默改任何一边都可能把没回收的伏笔记成已回收。
FORESHADOW_ACTION_STATUS = {
    "resolve": "已回收", "回收": "已回收",
    "advance": "已埋", "推进": "已埋",
}
FORESHADOW_KEY_ALIASES = {
    "planned_chapter": "planned_resolution_chapter", "planned_payoff_chapter": "planned_resolution_chapter",
    "payoff_chapter": "planned_resolution_chapter", "resolution_chapter": "planned_resolution_chapter",
    "resolve_chapter": "planned_resolution_chapter", "plant_chapter": "planted_chapter",
    "planted": "planted_chapter", "description": "summary", "content": "summary",
}
TIMELINE_KEY_ALIASES = {"time": "story_time", "fact": "objective_fact", "reveal": "reveal_status"}
INVALID_FILE_CHARS = re.compile(r"[<>:\"/\\|?*\x00-\x1f]")
FORESHADOW_ID = re.compile(r"^F\d{3,}$")
SNAPSHOT_TEXT_FIELDS = ("identity", "location", "goal", "state")
SNAPSHOT_LIST_FIELDS = ("abilities_resources", "relationships", "knowledge", "open_threads")
EVENT_ID = re.compile(r"^E\d{3,}$")
WINDOWS_RESERVED_NAMES = {
    "CON",
    "PRN",
    "AUX",
    "NUL",
    *(f"COM{index}" for index in range(1, 10)),
    *(f"LPT{index}" for index in range(1, 10)),
}
RETIRED_TRACKING_PATHS = (
    "_tracking-meta.json",
    "阶段摘要.md",
    "角色状态.md",
    "时间线.md",
    "摘要",
    "时间线/事件库.json",
)
RETIRED_ARCHIVE_DIR = "_旧追踪存档"


class TrackingError(ValueError):
    """Expected validation or tracking-state error."""


def require(condition: bool, message: str) -> None:
    if not condition:
        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


def as_list(value: object, label: str) -> list[Any]:
    require(isinstance(value, list), f"{label} must be a JSON array")
    return value


def as_int(value: object, label: str, *, minimum: int = 0) -> int:
    require(isinstance(value, int) and not isinstance(value, bool), f"{label} must be an integer")
    require(value >= minimum, f"{label} must be >= {minimum}")
    return value


def as_chapter(value: object, label: str, *, minimum: int = 1) -> int:
    """章号:模型常写成 "22"。纯数字字符串按整数收,语义不变;其余照旧报错。"""
    if isinstance(value, str) and value.strip().isdecimal():
        value = int(value.strip())
    return as_int(value, label, minimum=minimum)


def with_aliases(row: dict[str, Any], aliases: dict[str, str]) -> dict[str, Any]:
    """把含义明确的同义字段名改成正式字段名;正式字段已在时不动,留给未知字段报错。"""
    row = dict(row)
    for alias, canonical in aliases.items():
        if alias in row and canonical not in row:
            row[canonical] = row.pop(alias)
    return row


def normalize_action(value: object, label: str, *, allow_delete: bool) -> str:
    action = clean_text(value, label, max_bytes=24)
    action = ACTION_ALIASES.get(action.lower(), action.lower())
    allowed = ("upsert", "delete") if allow_delete else ("upsert",)
    require(action in allowed, f"{label} is invalid: use {' or '.join(allowed)}")
    return action


def require_known_keys(mapping: dict[str, Any], allowed: set[str], label: str) -> None:
    unknown = set(mapping) - allowed
    require(not unknown, f"{label} contains unsupported fields: {', '.join(sorted(unknown))}"
                         f"(只收 {', '.join(sorted(allowed))})")


# 事务校验期间收集全部超长字段,一次报完;None 表示逐条立即报错(初始化、状态读取等路径)。
_LENGTH_ISSUES: list[str] | None = None


def length_hint(label: str, text: str, max_bytes: int) -> str:
    """把字节上限换算成字数:模型写的是中文,只看得懂「要删几个字」。"""
    size = len(text.encode("utf-8"))
    allowed = max(1, max_bytes * len(text) // size)
    return (f"{label} exceeds {max_bytes} bytes(现 {len(text)} 字,上限约 {allowed} 字,"
            f"至少删 {len(text) - allowed} 字)")


def clean_text(value: object, label: str, *, allow_empty: bool = False, max_bytes: int = 768) -> str:
    require(isinstance(value, str), f"{label} must be a string")
    cleaned = " ".join(value.replace("|", "|").split())
    require(allow_empty or bool(cleaned), f"{label} must not be empty")
    if len(cleaned.encode("utf-8")) > max_bytes:
        if _LENGTH_ISSUES is None:
            raise TrackingError(length_hint(label, cleaned, max_bytes))
        _LENGTH_ISSUES.append(length_hint(label, cleaned, max_bytes))
    return cleaned


def clean_string_list(
    value: object,
    label: str,
    *,
    maximum: int | None = None,
    item_max_bytes: int = 384,
) -> list[str]:
    values = as_list(value, label)
    if maximum is not None:
        require(len(values) <= maximum, f"{label} may contain at most {maximum} items")
    return [clean_text(item, f"{label}[{index}]", max_bytes=item_max_bytes) for index, item in enumerate(values)]


def safe_file_component(value: object, label: str) -> str:
    name = unicodedata.normalize("NFC", clean_text(value, label, max_bytes=180))
    require(not INVALID_FILE_CHARS.search(name), f"{label} contains an invalid filename character")
    require(name not in {".", ".."} and not name.endswith((".", " ")), f"{label} is not a safe filename")
    require(name.split(".", 1)[0].upper() not in WINDOWS_RESERVED_NAMES, f"{label} is reserved on Windows")
    return name


def portable_name_key(name: str) -> str:
    return unicodedata.normalize("NFC", name).casefold()


def byte_size(text: str) -> int:
    return len(text.encode("utf-8"))


def emit(text: str, *, error: bool = False) -> None:
    """Write UTF-8 bytes directly.

    Windows 的文本 stdout 是 cp1252(含中文即 UnicodeEncodeError),stderr 默认
    backslashreplace(中文被转义成反斜杠码位,作者看不懂)。两条路都要绕开。
    """
    stream = sys.stderr if error else sys.stdout
    stream.flush()
    stream.buffer.write((text + "\n").encode("utf-8"))
    stream.buffer.flush()


def read_json(path: Path) -> object:
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise TrackingError(f"unable to read JSON {path}: {exc}") from exc


def json_payload(document: object) -> str:
    return json.dumps(document, ensure_ascii=False, indent=2, sort_keys=True) + "\n"


def atomic_write_text(path: Path, payload: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else 0o644
    fd, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
    temporary = Path(temporary_name)
    try:
        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
            handle.write(payload)
            handle.flush()
            os.fsync(handle.fileno())
        os.chmod(temporary, mode)
        os.replace(temporary, path)
    finally:
        temporary.unlink(missing_ok=True)


def write_if_changed(path: Path, payload: str) -> None:
    try:
        if path.read_text(encoding="utf-8") == payload:
            return
    except FileNotFoundError:
        pass
    atomic_write_text(path, payload)


def tracking_root(project: Path) -> Path:
    return project.resolve() / "追踪"


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"


def chapter_work_dir(project: Path, chapter: int) -> Path:
    width = max(3, len(str(chapter)))
    return project / ".story" / "work" / f"第{chapter:0{width}d}章"


def find_retired_tracking_paths(tracking: Path) -> list[str]:
    found = [relative for relative in RETIRED_TRACKING_PATHS if (tracking / relative).exists()]
    found.extend(sorted(path.name for path in tracking.glob("基线_截至第*章.md")))
    return found


def require_no_retired_tracking_paths(tracking: Path) -> None:
    found = find_retired_tracking_paths(tracking)
    require(not found, f"retired tracking files are not supported: {', '.join(found)}")


def archive_retired_tracking_paths(tracking: Path) -> list[str]:
    """Move a pre-transaction 追踪/ aside so init can build the current protocol in place.

    Nothing is parsed or converted: the old files are kept verbatim for the author to
    consult, and the new state is reconstructed from the init document alone.
    """
    retired = find_retired_tracking_paths(tracking)
    if not retired:
        return []
    archive = tracking / RETIRED_ARCHIVE_DIR
    for relative in retired:
        require(
            not (archive / relative).exists(),
            f"追踪/{RETIRED_ARCHIVE_DIR}/{relative} already exists; move it away before initializing",
        )
    # 先全量校验再搬运;中断后重跑时已搬走的条目不再出现在待搬列表里,可直接续做。
    for relative in retired:
        target = archive / relative
        target.parent.mkdir(parents=True, exist_ok=True)
        os.replace(tracking / relative, target)
    return retired


def _both_blank(position: dict[str, Any]) -> bool:
    return all(isinstance(position.get(key), str) and not position[key].strip() for key in ("story_time", "scene"))


def validate_position(value: object, label: str = "context.position") -> dict[str, Any]:
    position = as_mapping(value, label)
    require_known_keys(position, {"volume", "volume_start_chapter", "story_time", "scene"}, label)
    require(not _both_blank(position),
            f"{label}.story_time and {label}.scene must not be empty: fill where this chapter ends")
    return {
        "volume": safe_file_component(position.get("volume"), f"{label}.volume"),
        "volume_start_chapter": as_int(
            position.get("volume_start_chapter"), f"{label}.volume_start_chapter", minimum=1
        ),
        "story_time": clean_text(position.get("story_time"), f"{label}.story_time", max_bytes=240),
        "scene": clean_text(position.get("scene"), f"{label}.scene", max_bytes=240),
    }


def joined_text(value: object) -> object:
    """单句字段写成了字符串列表时按「;」连成一句,内容不丢。"""
    if isinstance(value, list) and value and all(isinstance(item, str) for item in value):
        return ";".join(value)
    return value


def as_text_list(value: object) -> object:
    """列表字段只写了一句时当作一项。"""
    return [value] if isinstance(value, str) and value.strip() else value


def normalize_snapshot(value: object, label: str) -> dict[str, Any]:
    snapshot = as_mapping(value, label)
    snapshot = {key: joined_text(item) if key in SNAPSHOT_TEXT_FIELDS else as_text_list(item)
                if key in SNAPSHOT_LIST_FIELDS else item for key, item in snapshot.items()}
    require_known_keys(
        snapshot,
        {"identity", "location", "goal", "state", "abilities_resources", "relationships", "knowledge", "open_threads"},
        label,
    )
    return {
        "identity": clean_text(snapshot.get("identity"), f"{label}.identity", max_bytes=240),
        "location": clean_text(snapshot.get("location"), f"{label}.location", max_bytes=240),
        "goal": clean_text(snapshot.get("goal"), f"{label}.goal", max_bytes=300),
        "state": clean_text(snapshot.get("state"), f"{label}.state", max_bytes=300),
        "abilities_resources": clean_string_list(
            snapshot.get("abilities_resources", []),
            f"{label}.abilities_resources",
            item_max_bytes=SNAPSHOT_ITEM_MAX_BYTES,
        ),
        "relationships": clean_string_list(
            snapshot.get("relationships", []),
            f"{label}.relationships",
            item_max_bytes=SNAPSHOT_ITEM_MAX_BYTES,
        ),
        "knowledge": clean_string_list(
            snapshot.get("knowledge", []),
            f"{label}.knowledge",
            item_max_bytes=SNAPSHOT_ITEM_MAX_BYTES,
        ),
        "open_threads": clean_string_list(
            snapshot.get("open_threads", []),
            f"{label}.open_threads",
            item_max_bytes=SNAPSHOT_ITEM_MAX_BYTES,
        ),
    }


def normalize_snapshots(value: object, label: str = "character_snapshots") -> dict[str, dict[str, Any]]:
    snapshots = as_mapping(value, label)
    normalized: dict[str, dict[str, Any]] = {}
    portable_names: set[str] = set()
    for raw_name, raw_snapshot in snapshots.items():
        name = safe_file_component(raw_name, f"{label} character name")
        key = portable_name_key(name)
        require(key not in portable_names, f"{label} contains a cross-platform duplicate character {name}")
        portable_names.add(key)
        normalized[name] = normalize_snapshot(raw_snapshot, f"{label}.{name}")
    return normalized


def render_snapshot(name: str, snapshot: dict[str, Any], through_chapter: int, revision: int) -> str:
    def section(title: str, values: list[str]) -> list[str]:
        return [f"## {title}", *(f"- {item}" for item in values or ["无"]), ""]

    lines = [
        f"# {name}|当前状态",
        "",
        f"- 状态修订:{revision}",
        f"- 截至章节:第{through_chapter}章",
        f"- 身份:{snapshot['identity']}",
        f"- 位置:{snapshot['location']}",
        f"- 当前目标:{snapshot['goal']}",
        f"- 身心状态:{snapshot['state']}",
        "",
    ]
    lines.extend(section("能力与资源", snapshot["abilities_resources"]))
    lines.extend(section("关键关系", snapshot["relationships"]))
    lines.extend(section("已知信息", snapshot["knowledge"]))
    lines.extend(section("未结事项", snapshot["open_threads"]))
    payload = "\n".join(lines).rstrip() + "\n"
    size = byte_size(payload)
    if size > SNAPSHOT_MAX_BYTES:
        allowed = max(1, SNAPSHOT_MAX_BYTES * len(payload) // size)
        counts = "、".join(
            f"{title} {len(values)} 项"
            for title, values in (
                ("能力与资源", snapshot["abilities_resources"]),
                ("关键关系", snapshot["relationships"]),
                ("已知信息", snapshot["knowledge"]),
                ("未结事项", snapshot["open_threads"]),
            )
        )
        raise TrackingError(
            f"character snapshot {name} ({size} bytes) exceeds hard cap of {SNAPSHOT_MAX_BYTES} bytes"
            f"(现 {len(payload)} 字,上限约 {allowed} 字,至少精简 {len(payload) - allowed} 字;"
            f"当前:{counts}。逐章经过已留在 逐章记录/,快照只保留截至当前章仍有效的状态与条目)"
        )
    return payload


def normalize_foreshadow_change(
    value: object,
    label: str,
    *,
    allow_delete: bool,
    through_chapter: int,
) -> dict[str, Any]:
    row = with_aliases(as_mapping(value, label), FORESHADOW_KEY_ALIASES)
    require_known_keys(
        row,
        {"action", "id", "summary", "planted_chapter", "planned_resolution_chapter", "status", "importance"},
        label,
    )
    raw_action = row.get("action", "upsert")
    action = normalize_action(raw_action, f"{label}.action", allow_delete=allow_delete)
    identifier = clean_text(row.get("id"), f"{label}.id", max_bytes=24)
    require(FORESHADOW_ID.fullmatch(identifier) is not None, f"{label}.id must look like F001")
    if action == "delete":
        return {"action": action, "id": identifier}
    implied = FORESHADOW_ACTION_STATUS.get(" ".join(str(raw_action).split()).lower())
    if implied is not None:
        if row.get("status") in (None, ""):
            row["status"] = implied
        right = "回收了就写 status=已回收" if implied == "已回收" else "只是推进、还没回收就写 status=已埋"
        require(
            row["status"] == implied,
            f"{label}.action={raw_action} 与 status={row['status']} 矛盾:{right};"
            "不是这个意思就把 action 改成 upsert 并写实际状态",
        )
    planted_chapter = as_chapter(row.get("planted_chapter"), f"{label}.planted_chapter")
    require(planted_chapter <= through_chapter, f"{label}.planted_chapter cannot be in the future")
    planned_raw = row.get("planned_resolution_chapter")
    planned_chapter = (
        None if planned_raw in (None, "") else as_chapter(planned_raw, f"{label}.planned_resolution_chapter")
    )
    require(
        planned_chapter is None or planned_chapter >= planted_chapter,
        f"{label}.planned_resolution_chapter cannot precede planted_chapter",
    )
    status = clean_text(row.get("status"), f"{label}.status", max_bytes=24)
    importance = clean_text(row.get("importance"), f"{label}.importance", max_bytes=12)
    require(status in FORESHADOW_STATUSES, f"{label}.status must be one of {FORESHADOW_STATUSES}")
    require(importance in FORESHADOW_IMPORTANCE, f"{label}.importance must be one of {FORESHADOW_IMPORTANCE}")
    return {
        "action": action,
        "id": identifier,
        "summary": clean_text(row.get("summary"), f"{label}.summary", max_bytes=360),
        "planted_chapter": planted_chapter,
        "planned_resolution_chapter": planned_chapter,
        "status": status,
        "importance": importance,
    }


def normalize_foreshadow_state(value: object, last_chapter: int) -> dict[str, dict[str, Any]]:
    rows = as_mapping(value, "tracking state.foreshadow")
    normalized: dict[str, dict[str, Any]] = {}
    for raw_identifier, raw_row in rows.items():
        identifier = clean_text(raw_identifier, "tracking state.foreshadow ID", max_bytes=24)
        row = as_mapping(raw_row, f"tracking state.foreshadow.{identifier}")
        require_known_keys(
            row,
            {"id", "summary", "planted_chapter", "planned_resolution_chapter", "status", "importance", "updated_chapter"},
            f"tracking state.foreshadow.{identifier}",
        )
        require(row.get("id") == identifier, f"tracking state.foreshadow.{identifier}.id does not match its key")
        change = normalize_foreshadow_change(
            {
                "action": "upsert",
                **{key: value for key, value in row.items() if key != "updated_chapter"},
            },
            f"tracking state.foreshadow.{identifier}",
            allow_delete=False,
            through_chapter=last_chapter,
        )
        change.pop("action")
        updated = as_int(row.get("updated_chapter"), f"tracking state.foreshadow.{identifier}.updated_chapter", minimum=1)
        require(updated <= last_chapter, f"foreshadow {identifier} updates after current chapter")
        change["updated_chapter"] = updated
        normalized[identifier] = change
    return normalized


def render_foreshadow(rows: dict[str, dict[str, Any]], revision: int) -> str:
    lines = [
        "# 伏笔当前状态",
        "",
        f"> 状态修订:{revision}。每个 ID 只保留一行当前状态;历史变化见 `逐章记录/`。",
        "",
        "| ID | 内容 | 埋设章 | 计划回收章 | 状态 | 重要度 | 最近变更章 |",
        "|---|---|---:|---:|---|---|---:|",
    ]
    for identifier in sorted(rows):
        row = rows[identifier]
        planned = f"第{row['planned_resolution_chapter']}章" if row["planned_resolution_chapter"] else "—"
        lines.append(
            f"| {identifier} | {row['summary']} | 第{row['planted_chapter']}章 | {planned} | "
            f"{row['status']} | {row['importance']} | 第{row['updated_chapter']}章 |"
        )
    return "\n".join(lines) + "\n"


def normalize_timeline_change(
    value: object,
    label: str,
    *,
    allow_delete: bool,
    through_chapter: int,
) -> dict[str, Any]:
    event = with_aliases(as_mapping(value, label), TIMELINE_KEY_ALIASES)
    require_known_keys(
        event,
        {"action", "id", "story_time", "objective_fact", "reader_knowledge", "reveal_status", "reveal_chapter", "characters"},
        label,
    )
    action = normalize_action(event.get("action", "upsert"), f"{label}.action", allow_delete=allow_delete)
    identifier = clean_text(event.get("id"), f"{label}.id", max_bytes=24)
    require(EVENT_ID.fullmatch(identifier) is not None, f"{label}.id must look like E001")
    if action == "delete":
        return {"action": action, "id": identifier}
    reveal_status = clean_text(event.get("reveal_status"), f"{label}.reveal_status", max_bytes=24)
    require(reveal_status in REVEAL_STATUSES, f"{label}.reveal_status must be one of {REVEAL_STATUSES}")
    reveal_raw = event.get("reveal_chapter")
    reveal_chapter = None if reveal_raw in (None, "") else as_chapter(reveal_raw, f"{label}.reveal_chapter")
    if reveal_status == "未揭示":
        require(reveal_chapter is None, f"{label} must not put a future reveal chapter in established timeline facts")
    else:
        require(reveal_chapter is not None, f"{label}.reveal_chapter is required once revealed")
        require(reveal_chapter <= through_chapter, f"{label}.reveal_chapter cannot be in the future")
    return {
        "action": action,
        "id": identifier,
        "story_time": clean_text(event.get("story_time"), f"{label}.story_time", max_bytes=240),
        "objective_fact": clean_text(event.get("objective_fact"), f"{label}.objective_fact", max_bytes=480),
        "reader_knowledge": clean_text(event.get("reader_knowledge"), f"{label}.reader_knowledge", max_bytes=480),
        "reveal_status": reveal_status,
        "reveal_chapter": reveal_chapter,
        "characters": clean_string_list(event.get("characters", []), f"{label}.characters", maximum=12, item_max_bytes=120),
    }


def normalize_timeline_state(value: object, last_chapter: int) -> dict[str, dict[str, Any]]:
    events = as_mapping(value, "tracking state.timeline")
    normalized: dict[str, dict[str, Any]] = {}
    for raw_identifier, raw_event in events.items():
        identifier = clean_text(raw_identifier, "tracking state.timeline ID", max_bytes=24)
        event = as_mapping(raw_event, f"tracking state.timeline.{identifier}")
        require_known_keys(
            event,
            {
                "id", "story_time", "objective_fact", "reader_knowledge", "reveal_status", "reveal_chapter",
                "characters", "first_recorded_chapter", "updated_chapter",
            },
            f"tracking state.timeline.{identifier}",
        )
        require(event.get("id") == identifier, f"tracking state.timeline.{identifier}.id does not match its key")
        change = normalize_timeline_change(
            {
                "action": "upsert",
                **{
                    key: value
                    for key, value in event.items()
                    if key not in {"first_recorded_chapter", "updated_chapter"}
                },
            },
            f"tracking state.timeline.{identifier}",
            allow_delete=False,
            through_chapter=last_chapter,
        )
        change.pop("action")
        first = as_int(event.get("first_recorded_chapter"), f"tracking state.timeline.{identifier}.first_recorded_chapter", minimum=1)
        updated = as_int(event.get("updated_chapter"), f"tracking state.timeline.{identifier}.updated_chapter", minimum=1)
        require(first <= last_chapter, f"timeline event {identifier} starts after current chapter")
        require(updated <= last_chapter, f"timeline event {identifier} updates after current chapter")
        change["first_recorded_chapter"] = first
        change["updated_chapter"] = updated
        normalized[identifier] = change
    return normalized


def render_timeline_views(events: dict[str, dict[str, Any]], revision: int) -> tuple[str, str]:
    author_lines = [
        "# 作者真相时间线",
        "",
        f"> 状态修订:{revision}。客观事实与读者认知的权威对照;未来揭示计划仍留在大纲。",
        "",
        "| ID | 首次登记章 | 故事时间 | 客观事实 | 读者当前认知 | 揭示状态 | 实际揭示章 |",
        "|---|---:|---|---|---|---|---:|",
    ]
    reader_lines = [
        "# 读者已知时间线",
        "",
        f"> 状态修订:{revision}。只呈现读者截至当前章节已经知道或相信的内容,不泄露作者侧客观真相。",
        "",
        "| ID | 读者当前认知 | 认知截至章 |",
        "|---|---|---:|",
    ]
    for identifier in sorted(events):
        event = events[identifier]
        reveal = f"第{event['reveal_chapter']}章" if event.get("reveal_chapter") else "—"
        characters = "、".join(event.get("characters", []))
        objective = event["objective_fact"] + (f"(涉及:{characters})" if characters else "")
        author_lines.append(
            f"| {identifier} | 第{event['first_recorded_chapter']}章 | {event['story_time']} | {objective} | "
            f"{event['reader_knowledge']} | {event['reveal_status']} | {reveal} |"
        )
        reader_lines.append(f"| {identifier} | {event['reader_knowledge']} | 第{event['updated_chapter']}章 |")
    return "\n".join(author_lines) + "\n", "\n".join(reader_lines) + "\n"


def validate_context_input(value: object, *, include_initial_fields: bool) -> dict[str, Any]:
    context = as_mapping(value, "context")
    allowed = {"position", "long_term_constraints", "active_character_names", "continuity_risks"}
    if include_initial_fields:
        allowed.update({"recent_chapters", "next_chapter_commitments"})
    require_known_keys(context, allowed, "context")
    normalized: dict[str, Any] = {
        "position": validate_position(context.get("position")),
        "long_term_constraints": clean_string_list(
            context.get("long_term_constraints", []), "context.long_term_constraints", maximum=6
        ),
        "active_character_names": [
            safe_file_component(name, f"context.active_character_names[{index}]")
            for index, name in enumerate(as_list(context.get("active_character_names", []), "context.active_character_names"))
        ],
        "continuity_risks": clean_string_list(
            context.get("continuity_risks", []), "context.continuity_risks", maximum=5
        ),
    }
    require(
        len(normalized["active_character_names"]) <= ACTIVE_CHARACTER_MAX,
        f"context.active_character_names may contain at most {ACTIVE_CHARACTER_MAX} names",
    )
    require(
        len({portable_name_key(name) for name in normalized["active_character_names"]})
        == len(normalized["active_character_names"]),
        "context.active_character_names contains cross-platform duplicates",
    )
    if include_initial_fields:
        recent: list[dict[str, Any]] = []
        for index, raw_item in enumerate(as_list(context.get("recent_chapters", []), "context.recent_chapters")):
            item = as_mapping(raw_item, f"context.recent_chapters[{index}]")
            require_known_keys(item, {"chapter", "summary"}, f"context.recent_chapters[{index}]")
            recent.append(
                {
                    "chapter": as_int(item.get("chapter"), f"context.recent_chapters[{index}].chapter", minimum=1),
                    "summary": clean_text(item.get("summary"), f"context.recent_chapters[{index}].summary", max_bytes=360),
                }
            )
        require(len(recent) <= 3, "context.recent_chapters may contain at most 3 items")
        normalized["recent_chapters"] = recent
        normalized["next_chapter_commitments"] = clean_string_list(
            context.get("next_chapter_commitments", []), "context.next_chapter_commitments", maximum=5
        )
    return normalized


def active_foreshadow_lines(rows: dict[str, dict[str, Any]]) -> list[str]:
    importance = {value: index for index, value in enumerate(FORESHADOW_IMPORTANCE)}
    candidates = [row for row in rows.values() if row["status"] == "已埋"]
    candidates.sort(
        key=lambda row: (importance[row["importance"]], row["planned_resolution_chapter"] or 10**12, row["id"])
    )
    result = []
    for row in candidates[:8]:
        planned = f"第{row['planned_resolution_chapter']}章" if row["planned_resolution_chapter"] else "回收章未定"
        result.append(f"{row['id']}|{row['summary']}|埋第{row['planted_chapter']}章|{planned}|{row['importance']}")
    return result


def render_context(state: dict[str, Any]) -> str:
    context = state["context"]
    position = context["position"]
    current_chapter = (
        "尚未开篇" if state["last_committed_chapter"] == 0 else f"第{state['last_committed_chapter']}章"
    )
    character_lines = [
        f"{name}|{state['characters'][name]['identity']}|{state['characters'][name]['state']}|"
        f"目标:{state['characters'][name]['goal']}"
        for name in context["active_character_names"]
    ]
    sections: list[tuple[str, list[str]]] = [
        (
            "## 当前位置",
            [
                f"当前章:{current_chapter}",
                f"卷:{position['volume']}(始于第{position['volume_start_chapter']}章)",
                f"故事时间:{position['story_time']}",
                f"场景:{position['scene']}",
            ],
        ),
        ("## 长期约束", context["long_term_constraints"]),
        ("## 核心角色状态", character_lines),
        ("## 活跃伏笔", active_foreshadow_lines(state["foreshadow"])),
        ("## 近三章速记", [f"第{item['chapter']}章|{item['summary']}" for item in context["recent_chapters"]]),
        ("## 下一章承诺", context["next_chapter_commitments"]),
        ("## 连贯性风险", context["continuity_risks"]),
    ]
    lines = [
        f"# 写作连续性上下文 — {state['book_title']}",
        "",
        f"> 状态修订:{state['state_revision']}。截至当前章的续写状态卡,只放下一章真正需要的连续性状态。",
        "",
    ]
    for heading, values in sections:
        lines.append(heading)
        lines.extend(f"- {value}" for value in values or ["无"])
        lines.append("")
    payload = "\n".join(lines).rstrip() + "\n"
    headings = tuple(line for line in payload.splitlines() if line.startswith("## "))
    require(headings == CONTEXT_HEADINGS, "generated context headings do not match the seven-section schema")
    require(byte_size(payload) <= CONTEXT_MAX_BYTES, f"hot context exceeds {CONTEXT_MAX_BYTES} bytes")
    return payload


def normalize_delta(
    value: object,
    *,
    through_chapter: int,
    snapshots: dict[str, dict[str, Any]],
    existing_core_names: dict[str, str],
) -> dict[str, Any]:
    delta = as_mapping(value, "delta")
    require_known_keys(
        delta,
        {
            "result", "character_changes", "foreshadow_changes", "timeline_events", "constraints",
            "next_chapter_commitments", "retired_context_items", "retired_characters",
        },
        "delta",
    )
    retired_characters = [
        safe_file_component(name, f"delta.retired_characters[{index}]")
        for index, name in enumerate(as_list(delta.get("retired_characters", []), "delta.retired_characters"))
    ]
    retired_keys = [portable_name_key(name) for name in retired_characters]
    require(len(retired_keys) == len(set(retired_keys)), "delta.retired_characters contains duplicate characters")
    retiring = set(retired_keys)
    character_changes: list[dict[str, Any]] = []
    for index, raw_change in enumerate(as_list(delta.get("character_changes", []), "delta.character_changes")):
        change = as_mapping(raw_change, f"delta.character_changes[{index}]")
        require_known_keys(change, {"name", "change"}, f"delta.character_changes[{index}]")
        name = safe_file_component(change.get("name"), f"delta.character_changes[{index}].name")
        existing = existing_core_names.get(portable_name_key(name))
        is_core = name in snapshots or existing is not None
        # 本章退役的角色记录最后一次变化即可,不必再交一份马上要删的快照。
        require(
            not is_core or name in snapshots or portable_name_key(name) in retiring,
            f"core character {name} changed but has no current snapshot: 把 draft 输出 current_snapshots"
            f"(或 snapshot_files 里的 {name}.json)中「{name}」的快照整份改成本章结束时的状态,放进 character_snapshots",
        )
        character_changes.append(
            {"name": name, "change": clean_text(change.get("change"), f"delta.character_changes[{index}].change", max_bytes=360)}
        )
    character_keys = [portable_name_key(item["name"]) for item in character_changes]
    require(len(character_keys) == len(set(character_keys)), "delta.character_changes contains duplicate characters")
    foreshadow_changes = [
        normalize_foreshadow_change(
            raw, f"delta.foreshadow_changes[{index}]", allow_delete=True, through_chapter=through_chapter
        )
        for index, raw in enumerate(as_list(delta.get("foreshadow_changes", []), "delta.foreshadow_changes"))
    ]
    timeline_events = [
        normalize_timeline_change(
            raw, f"delta.timeline_events[{index}]", allow_delete=True, through_chapter=through_chapter
        )
        for index, raw in enumerate(as_list(delta.get("timeline_events", []), "delta.timeline_events"))
    ]
    require(
        len({item["id"] for item in foreshadow_changes}) == len(foreshadow_changes),
        "delta.foreshadow_changes contains duplicate IDs",
    )
    require(
        len({item["id"] for item in timeline_events}) == len(timeline_events),
        "delta.timeline_events contains duplicate IDs",
    )
    require(
        set(snapshots).issubset({item["name"] for item in character_changes}),
        "character_snapshots must contain exactly the core characters changed by this transaction",
    )
    return {
        "result": clean_text(delta.get("result"), "delta.result", max_bytes=480),
        "character_changes": character_changes,
        "foreshadow_changes": foreshadow_changes,
        "timeline_events": timeline_events,
        "constraints": clean_string_list(delta.get("constraints", []), "delta.constraints", maximum=6),
        "next_chapter_commitments": clean_string_list(
            delta.get("next_chapter_commitments", []), "delta.next_chapter_commitments", maximum=5
        ),
        "retired_context_items": clean_string_list(
            delta.get("retired_context_items", []), "delta.retired_context_items", maximum=11
        ),
        "retired_characters": retired_characters,
    }


def render_commitments(commitments: list[str]) -> list[str]:
    # 常见情形一行用「;」连写;有承诺原文自带「;」时连写就拆不回来,改成逐条缩进子项。
    if any(";" in item for item in commitments):
        return ["- 下一章承诺:"] + [f"  - {item}" for item in commitments]
    return ["- 下一章承诺:" + (";".join(commitments) or "无")]


def render_delta(chapter: int, title: str, delta: dict[str, Any], core_names: set[str]) -> str:
    lines = [
        f"# 第{chapter:03d}章 · {title}",
        f"- 结果:{delta['result']}",
        *render_commitments(delta["next_chapter_commitments"]),
        "",
        "## 角色变化",
    ]
    lines.extend(
        f"- {item['name']}|{'核心' if item['name'] in core_names else '临时'}|{item['change']}"
        for item in delta["character_changes"]
    )
    if not delta["character_changes"]:
        lines.append("- 无")
    lines.extend(["", "## 伏笔变化"])
    for item in delta["foreshadow_changes"]:
        if item["action"] == "delete":
            lines.append(f"- {item['id']}|删除当前登记")
        else:
            planned = f"第{item['planned_resolution_chapter']}章" if item["planned_resolution_chapter"] else "未定"
            lines.append(f"- {item['id']}|{item['status']}|{item['summary']}|回收{planned}")
    if not delta["foreshadow_changes"]:
        lines.append("- 无")
    lines.extend(["", "## 时间与揭示"])
    for item in delta["timeline_events"]:
        if item["action"] == "delete":
            lines.append(f"- {item['id']}|删除当前登记")
        else:
            lines.append(
                f"- {item['id']}|{item['story_time']}|事实:{item['objective_fact']}|"
                f"读者:{item['reader_knowledge']}|{item['reveal_status']}"
            )
    if not delta["timeline_events"]:
        lines.append("- 无")
    lines.extend(["", "## 连贯性约束"])
    lines.extend(f"- {item}" for item in delta["constraints"])
    if not delta["constraints"]:
        lines.append("- 无")
    retired = delta.get("retired_context_items", []) + [
        f"角色状态:{name}" for name in delta.get("retired_characters", [])
    ]
    if retired:
        # 退役条目在此留档,续写状态卡收缩后仍可回查当初撤下了什么。
        lines.extend(["", "## 本章退役登记"])
        lines.extend(f"- {item}" for item in retired)
    payload = "\n".join(lines) + "\n"
    size = byte_size(payload)
    if size > DELTA_MAX_BYTES:
        longest = sorted((line for line in lines if line.startswith("- ")), key=len, reverse=True)[:3]
        allowed = DELTA_MAX_BYTES * len(payload) // size
        raise TrackingError(
            f"chapter delta is {size} bytes; hard cap is {DELTA_MAX_BYTES}(逐章记录现 {len(payload)} 字,"
            f"上限约 {allowed} 字,至少压缩 {len(payload) - allowed} 字;最长几项:"
            + ";".join(f"{line[2:18]}…({len(line) - 2} 字)" for line in longest) + ")")
    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(
        root,
        {
            "schema_version", "book_title", "last_committed_chapter", "imported_through_chapter",
            "state_revision", "context", "characters", "foreshadow", "timeline",
            "wordcount_records",
        },
        "tracking state",
    )
    require(root.get("schema_version") == TRACKING_SCHEMA_VERSION, "tracking state schema is unsupported")
    last_chapter = as_int(root.get("last_committed_chapter"), "tracking state.last_committed_chapter")
    imported_through = as_int(root.get("imported_through_chapter"), "tracking state.imported_through_chapter")
    require(imported_through <= last_chapter, "imported chapter cutoff exceeds current chapter")
    context = validate_context_input(root.get("context"), include_initial_fields=True)
    require(
        context["position"]["volume_start_chapter"] <= max(1, last_chapter),
        "context.position.volume_start_chapter is after the current writing position",
    )
    recent_numbers = [item["chapter"] for item in context["recent_chapters"]]
    require(recent_numbers == sorted(recent_numbers), "context.recent_chapters must be ordered")
    require(len(recent_numbers) == len(set(recent_numbers)), "context.recent_chapters contains duplicates")
    require(all(chapter <= last_chapter for chapter in recent_numbers), "context.recent_chapters cannot include future chapters")
    characters = normalize_snapshots(root.get("characters", {}), "tracking state.characters")
    for name in context["active_character_names"]:
        require(name in characters, f"active core character {name} has no current snapshot")
    foreshadow = normalize_foreshadow_state(root.get("foreshadow", {}), last_chapter)
    timeline = normalize_timeline_state(root.get("timeline", {}), last_chapter)
    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": state_revision,
        "context": context,
        "characters": characters,
        "foreshadow": foreshadow,
        "timeline": timeline,
        "wordcount_records": wordcount_records,
    }


def load_state(project: Path) -> dict[str, Any]:
    path = state_path(project)
    require(path.exists(), "tracking state is missing; run init first")
    return normalize_state(read_json(path))


def normalize_initial_document(document: object) -> dict[str, Any]:
    global _LENGTH_ISSUES
    _LENGTH_ISSUES = []
    try:
        state_doc = _normalize_initial_document(document)
    finally:
        issues, _LENGTH_ISSUES = _LENGTH_ISSUES, None
    require(not issues, f"{len(issues)} 个字段超长,一次改完再提交:" + ";".join(issues))
    return normalize_state(state_doc)


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",
        },
        "init input",
    )
    require(root.get("schema_version") == INPUT_SCHEMA_VERSION, "init input schema_version is unsupported")
    last_chapter = as_int(root.get("last_chapter"), "last_chapter")
    book_title = clean_text(root.get("book_title"), "book_title", max_bytes=240)
    context = validate_context_input(root.get("context"), include_initial_fields=True)
    snapshots = normalize_snapshots(root.get("character_snapshots", {}))
    foreshadow: dict[str, dict[str, Any]] = {}
    for index, raw_row in enumerate(as_list(root.get("foreshadow", []), "foreshadow")):
        row = normalize_foreshadow_change(
            raw_row, f"foreshadow[{index}]", allow_delete=False, through_chapter=last_chapter
        )
        require(row["id"] not in foreshadow, f"duplicate foreshadow ID {row['id']}")
        row.pop("action")
        row["updated_chapter"] = max(1, last_chapter)
        foreshadow[row["id"]] = row
    timeline: dict[str, dict[str, Any]] = {}
    for index, raw_event in enumerate(as_list(root.get("timeline_events", []), "timeline_events")):
        event = normalize_timeline_change(
            raw_event, f"timeline_events[{index}]", allow_delete=False, through_chapter=last_chapter
        )
        require(event["id"] not in timeline, f"duplicate timeline event ID {event['id']}")
        event.pop("action")
        event["first_recorded_chapter"] = max(1, last_chapter)
        event["updated_chapter"] = max(1, last_chapter)
        timeline[event["id"]] = event
    return {
        "schema_version": TRACKING_SCHEMA_VERSION,
        "book_title": book_title,
        "last_committed_chapter": last_chapter,
        "imported_through_chapter": last_chapter,
        "state_revision": 0,
        "context": context,
        "characters": snapshots,
        "foreshadow": foreshadow,
        "timeline": timeline,
        "wordcount_records": {},
    }


def normalize_transaction(project: Path, state: dict[str, Any], document: object) -> dict[str, Any]:
    global _LENGTH_ISSUES
    _LENGTH_ISSUES = []
    try:
        transaction = _normalize_transaction(project, state, document)
    finally:
        issues, _LENGTH_ISSUES = _LENGTH_ISSUES, None
    require(not issues, f"{len(issues)} 个字段超长,一次改完再提交:" + ";".join(issues))
    return transaction


# 本文件在 story-long-write / story-review / story-import 三份逐字相同;只有 story-long-write 带 storyctl.py。
RECOUNT_HINT = ("修订请用 story-long-write 的 storyctl.py chapter commit(带外用 chapter accept-current-length)"
                "提交同一份事务,它会重新计数并清理本章工作目录")


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", "wordcount",
        },
        "transaction",
    )
    require(root.get("schema_version") == INPUT_SCHEMA_VERSION, "transaction schema_version is unsupported")
    mode = clean_text(root.get("mode"), "mode", max_bytes=24)
    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":
        require(chapter == last + 1, f"append chapter must be {last + 1}, got {chapter}")
    else:
        require(chapter <= last, f"cannot revise unwritten chapter {chapter}; last committed chapter is {last}")
    context = validate_context_input(root.get("context"), include_initial_fields=False)
    snapshots = normalize_snapshots(root.get("character_snapshots", {}))
    existing_names = {portable_name_key(name): name for name in state["characters"]}
    for name in snapshots:
        existing = existing_names.get(portable_name_key(name))
        require(existing is None or existing == name, f"character {name} conflicts with existing character {existing}")
    through_chapter = chapter if mode == "append" else last
    delta = normalize_delta(
        root.get("delta"),
        through_chapter=through_chapter,
        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
        )
    elif mode == "revision" and str(chapter) in state["wordcount_records"]:
        # 已提交字数记录的章节:去味、审稿改过正文或目标后的修订,按现文件重新计数,记录不留旧值。
        # 只核对记录钉住的正文与目标;细纲事后补的「字数范围」不算过期。
        previous = state["wordcount_records"][str(chapter)]
        try:
            drift = wordcount_core.wordcount_record_drift(project, chapter, previous)
        except wordcount_core.WordcountError as exc:
            raise TrackingError(f"第{chapter}章的字数记录无法核对({exc});{RECOUNT_HINT}") from exc
        if drift:
            wordcount = recount_revised_chapter(project, chapter, previous, drift)
    return {
        "mode": mode,
        "chapter": chapter,
        "title": clean_text(root.get("chapter_title"), "chapter_title", max_bytes=240),
        "delta": delta,
        "context": context,
        "snapshots": snapshots,
        "wordcount": wordcount,
    }


def recount_revised_chapter(project: Path, chapter: int, previous: dict[str, Any], drift: list[str]) -> dict[str, Any]:
    """改后仍在作者范围内,或作者原先就接受了带外长度且仍在带外:直接按现文件记账。
    原本在范围内、改后出了范围,才要作者拍板,交给 storyctl 的 accept-current-length。"""
    resolutions = ["within_user_band"]
    if previous["resolution"] == "accepted_current_length":
        resolutions.append("accepted_current_length")
    for resolution in resolutions:
        try:
            return wordcount_core.build_project_wordcount_record(
                project, chapter, resolution=resolution, author_range=previous.get("author_range"),
            )
        except wordcount_core.WordcountError:
            continue
    raise TrackingError(f"第{chapter}章{'和'.join(drift)}已改,字数出了作者范围;{RECOUNT_HINT}")


def checkpoint_record(
    change: dict[str, Any], chapter: int, previous: dict[str, Any] | None, *, keep_first_chapter: bool = False
) -> dict[str, Any]:
    current = {key: value for key, value in change.items() if key != "action"}
    current["updated_chapter"] = max(previous["updated_chapter"] if previous else chapter, chapter)
    if keep_first_chapter:
        current["first_recorded_chapter"] = previous["first_recorded_chapter"] if previous else chapter
    return current


def merge_transaction(state: dict[str, Any], transaction: dict[str, Any]) -> dict[str, Any]:
    next_state = copy.deepcopy(state)
    chapter = transaction["chapter"]
    if transaction["mode"] == "append":
        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 的逐章记录代表此刻;
    # 修订记录属于被改写的旧章,落在那里会谎报退役发生的章节。
    is_revision = transaction["mode"] == "revision"
    require(
        not (is_revision and transaction["delta"]["retired_characters"]),
        "retired_characters must be committed in an append transaction, not a revision",
    )
    for name in transaction["delta"]["retired_characters"]:
        require(name in next_state["characters"], f"retired character {name} has no current snapshot")
        require(
            name not in transaction["snapshots"],
            f"character {name} cannot be retired and updated in the same transaction",
        )
        require(
            name not in next_context["active_character_names"],
            f"retired character {name} is still listed in context.active_character_names",
        )
        next_state["characters"].pop(name)

    # 上下文条目是整份提交的;漏写会静默丢历史裁定,因此掉落必须显式声明。
    previous_items = set(state["context"]["long_term_constraints"]) | set(state["context"]["continuity_risks"])
    dropped = previous_items - (set(next_context["long_term_constraints"]) | set(next_context["continuity_risks"]))
    require(
        not (is_revision and dropped),
        "a revision must resubmit every current context item; retire them in an append transaction instead: "
        + ";".join(sorted(dropped)),
    )
    kept = set(next_context["long_term_constraints"]) | set(next_context["continuity_risks"])
    still_listed = sorted(set(transaction["delta"]["retired_context_items"]) & kept)
    require(
        not still_listed,
        "delta.retired_context_items lists items that are still in context; remove them from context: "
        + ";".join(still_listed),
    )
    undeclared = sorted(dropped - set(transaction["delta"]["retired_context_items"]))
    require(
        not undeclared,
        "context items were dropped without being declared in delta.retired_context_items: "
        + ";".join(undeclared),
    )
    transaction["delta"]["retired_context_items"] = sorted(dropped)

    for change in transaction["delta"]["foreshadow_changes"]:
        if change["action"] == "delete":
            next_state["foreshadow"].pop(change["id"], None)
        else:
            next_state["foreshadow"][change["id"]] = checkpoint_record(
                change, chapter, next_state["foreshadow"].get(change["id"])
            )
    for change in transaction["delta"]["timeline_events"]:
        if change["action"] == "delete":
            next_state["timeline"].pop(change["id"], None)
        else:
            next_state["timeline"][change["id"]] = checkpoint_record(
                change, chapter, next_state["timeline"].get(change["id"]), keep_first_chapter=True
            )

    recent_by_chapter = {item["chapter"]: item for item in state["context"]["recent_chapters"]}
    if chapter in recent_by_chapter or transaction["mode"] == "append":
        recent_by_chapter[chapter] = {"chapter": chapter, "summary": transaction["delta"]["result"]}
    recent = sorted(recent_by_chapter.values(), key=lambda item: item["chapter"])[-3:]
    current_last = next_state["last_committed_chapter"]
    next_commitments = (
        transaction["delta"]["next_chapter_commitments"]
        if transaction["mode"] == "append" or chapter == current_last
        else state["context"]["next_chapter_commitments"]
    )
    next_state["context"] = {
        **next_context,
        "recent_chapters": recent,
        "next_chapter_commitments": next_commitments,
    }
    return normalize_state(next_state)


def render_views(state: dict[str, Any]) -> dict[str, str]:
    revision = state["state_revision"]
    views = {
        "上下文.md": render_context(state),
        "伏笔.md": render_foreshadow(state["foreshadow"], revision),
    }
    author, reader = render_timeline_views(state["timeline"], revision)
    views["时间线/作者真相.md"] = author
    views["时间线/读者已知.md"] = reader
    for name, snapshot in state["characters"].items():
        views[f"角色状态/{name}.md"] = render_snapshot(
            name, snapshot, state["last_committed_chapter"], revision
        )
    return views


def write_views(tracking: Path, views: dict[str, str]) -> None:
    # 上下文携带 next revision,先写它;任何后续失败都会让 hook/check 发现
    # 上下文 revision 与最后提交的 _tracking-state.json 不一致。
    write_if_changed(tracking / "上下文.md", views["上下文.md"])
    for relative in sorted(path for path in views if path != "上下文.md"):
        write_if_changed(tracking / relative, views[relative])
    expected_character_files = {
        Path(relative).name for relative in views if relative.startswith("角色状态/")
    }
    character_dir = tracking / "角色状态"
    character_dir.mkdir(parents=True, exist_ok=True)
    for path in character_dir.glob("*.md"):
        if path.name not in expected_character_files:
            path.unlink()


def warn_sizes(views: dict[str, str], delta_payload: str | None = None) -> None:
    if delta_payload is not None and byte_size(delta_payload) > DELTA_TARGET_BYTES:
        emit(
            f"WARNING: chapter delta is {byte_size(delta_payload)} bytes; target is <= {DELTA_TARGET_BYTES}",
            error=True,
        )
    context_size = byte_size(views["上下文.md"])
    if context_size > CONTEXT_TARGET_BYTES:
        emit(f"WARNING: hot context is {context_size} bytes; target is <= {CONTEXT_TARGET_BYTES}", error=True)
    for relative, payload in views.items():
        if not relative.startswith("角色状态/"):
            continue
        size = byte_size(payload)
        if size > SNAPSHOT_TARGET_BYTES:
            target_chars = max(1, SNAPSHOT_TARGET_BYTES * len(payload) // size)
            emit(
                f"WARNING: character snapshot {Path(relative).stem} is {size} bytes; target is <= {SNAPSHOT_TARGET_BYTES}"
                f"(现 {len(payload)} 字,建议目标约 {target_chars} 字;不影响本次提交,"
                "后续更新时可将已了结事项或已被新状态取代的旧阶段归并为当前值)",
                error=True,
            )


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)
    views = render_views(state)
    state_payload = json_payload(state)

    # 输入全部校验通过后才动用户文件,失败的 init 不会挪走任何东西。
    archived = archive_retired_tracking_paths(tracking)
    for directory in (tracking / "逐章记录", tracking / "角色状态", tracking / "时间线"):
        directory.mkdir(parents=True, exist_ok=True)
    write_views(tracking, views)
    atomic_write_text(state_path(project), state_payload)
    warn_sizes(views)
    if archived:
        emit(
            f"NOTE: 旧追踪结构已原样移入 追踪/{RETIRED_ARCHIVE_DIR}/:{', '.join(archived)};"
            "当前状态以本次 init 输入为准,旧文件不参与解析。",
            error=True,
        )
    return state


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(project, state, document)
    next_state = merge_transaction(state, transaction)
    path = delta_path(tracking, transaction["chapter"])
    previous_record = parse_chapter_record(path) if transaction["mode"] == "revision" else None
    if previous_record is not None:
        # 退役只在 append 发生;修订重写旧章记录时把当初的退役登记原样带过来,不让它随修订消失。
        transaction["delta"]["retired_context_items"] = previous_record["retired"]

    delta_payload = render_delta(
        transaction["chapter"],
        transaction["title"],
        transaction["delta"],
        # 本章退役的角色在 next_state 里已被删除,但本章记录里仍应标为核心。
        set(next_state["characters"]) | set(transaction["delta"]["retired_characters"]),
    )
    views = render_views(next_state)
    next_state_payload = json_payload(next_state)
    if transaction["mode"] == "append" and path.exists():
        require(
            path.read_text(encoding="utf-8") == delta_payload,
            f"chapter delta {transaction['chapter']} already exists with different content",
        )

    write_if_changed(path, delta_payload)
    write_views(tracking, views)
    # 唯一权威文件最后落盘;在此之前失败可用同一事务直接重跑。
    atomic_write_text(state_path(project), next_state_payload)
    warn_sizes(views, delta_payload)
    warn_emptied_snapshots(state["characters"], transaction["snapshots"])
    if previous_record is not None:
        warn_emptied_record(transaction["chapter"], previous_record, transaction["delta"])
    return next_state


def warn_emptied_snapshots(
    previous_characters: dict[str, dict[str, Any]],
    updated_snapshots: dict[str, dict[str, Any]],
) -> None:
    labels = {
        "abilities_resources": "能力与资源",
        "relationships": "关键关系",
        "knowledge": "已知信息",
    }
    for name, updated in updated_snapshots.items():
        previous = previous_characters.get(name)
        if previous is None:
            continue
        emptied = [
            f"{label}(原有 {len(previous[key])} 项)"
            for key, label in labels.items()
            if previous.get(key) and not updated.get(key)
        ]
        if emptied:
            emit(
                f"WARNING: 角色快照「{name}」把 " + "、".join(emptied)
                + " 清空成了空列表;character_snapshots 提交的是角色完整当前状态,不是只写本章新增。"
                "若非有意清空,请从 draft 的 snapshot_files 读回完整快照修改后重提。",
                error=True,
            )


def warn_emptied_record(chapter: int, previous: dict[str, Any], delta: dict[str, Any]) -> None:
    labels = {"character_changes": "角色变化", "foreshadow_changes": "伏笔变化", "timeline_events": "时间与揭示",
              "constraints": "连贯性约束", "next_chapter_commitments": "下一章承诺"}
    emptied = [f"{label}(原有 {len(previous[key])} 项)" for key, label in labels.items()
               if previous[key] and not delta[key]]
    if emptied:
        emit(f"WARNING: 第{chapter}章修订把逐章记录的 " + "、".join(emptied)
             + " 清空了;修订的 delta 是本章完整记录,不是只写改动。不是有意删除就用 draft 重新预填后再提交。", error=True)


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)
    state = load_state(project)
    last_chapter = state["last_committed_chapter"]
    required_delta_start = state["imported_through_chapter"] + 1
    for chapter in range(required_delta_start, last_chapter + 1):
        require(delta_path(tracking, chapter).exists(), f"chapter delta {chapter} is missing")
    for path in (tracking / "逐章记录").glob("第*章.md"):
        match = re.fullmatch(r"第(\d+)章\.md", path.name)
        require(match is not None, f"chapter delta has an invalid filename: {path.name}")
        chapter = as_int(int(match.group(1)), f"chapter delta {path.name}", minimum=1)
        require(path == delta_path(tracking, chapter), f"chapter delta {chapter} filename is not canonical")
        require(chapter <= last_chapter, f"chapter delta {chapter} exceeds last_committed_chapter")
        require(path.stat().st_size <= DELTA_MAX_BYTES, f"chapter delta {chapter} exceeds {DELTA_MAX_BYTES} bytes")

    expected_views = render_views(state)
    for relative, expected in expected_views.items():
        path = tracking / relative
        require(path.exists(), f"derived view is missing: {relative}")
        require(
            path.read_text(encoding="utf-8") == expected,
            f"derived view differs from _tracking-state.json: {relative}",
        )
    expected_character_files = {
        Path(relative).name for relative in expected_views if relative.startswith("角色状态/")
    }
    actual_character_files = {path.name for path in (tracking / "角色状态").glob("*.md")}
    require(actual_character_files == expected_character_files, "character snapshot files differ from tracking state")
    return state


# 事务草稿里各文本字段的字数上限(按全中文估:UTF-8 每字 3 字节),写进提示,免得模型反复试错。
DRAFT_LIMITS = {
    "delta.result": 160, "character_changes[].change": 120, "foreshadow_changes[].summary": 120,
    "timeline_events[].objective_fact / reader_knowledge": 160, "context.position.story_time / scene": 80,
    "character_snapshots.*.identity / location": 80, "character_snapshots.*.goal / state": 100,
    "character_snapshots.*.四个列表单项": 200, "角色快照单文件": 21500, "逐章记录总量": 1024,
}


RECORD_SECTIONS = {"角色变化": "character_changes", "伏笔变化": "foreshadow_changes",
                   "时间与揭示": "timeline_events", "连贯性约束": "constraints", "本章退役登记": "retired"}


def parse_chapter_record(path: Path) -> dict[str, Any] | None:
    """读回本工具自己渲染的逐章记录(render_delta 的固定格式),供修订草稿预填与修订提交核对。
    这是对自家确定性输出的逆运算,不是解析手写 Markdown;读不到返回 None。"""
    try:
        text = path.read_text(encoding="utf-8")
    except (OSError, UnicodeError):
        return None
    record: dict[str, Any] = {"title": "", "result": "", "next_chapter_commitments": [],
                              **{key: [] for key in RECORD_SECTIONS.values()}}
    section = None
    in_commitments = False
    for line in text.splitlines():
        heading = re.match(r"^# 第\d+章 · (.+)$", line)
        if heading and not record["title"]:
            record["title"] = heading.group(1).strip()
            continue
        if line.startswith("## "):
            section = RECORD_SECTIONS.get(line[3:].strip())
            in_commitments = False
            continue
        if in_commitments and line.startswith("  - "):
            record["next_chapter_commitments"].append(line[4:])
            continue
        in_commitments = False
        if not line.startswith("- "):
            continue
        item = line[2:]
        if section is None:
            if item.startswith("结果:"):
                record["result"] = item[len("结果:"):]
            elif item.startswith("下一章承诺:"):
                value = item[len("下一章承诺:"):]
                # 空值 = 逐条子项格式(render_commitments),后面的缩进行逐条读回。
                in_commitments = value == ""
                record["next_chapter_commitments"] = [] if value in ("无", "") else value.split(";")
            continue
        if item == "无" and section != "retired":
            continue
        record[section].append(item)
    return record


def record_prefill(state: dict[str, Any], record: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any], list[str]]:
    """把已提交的逐章记录还原成修订 delta:结果、承诺、约束、角色变化按记录原文;伏笔与时间线
    取受影响 ID 的当前值(修订提交的就是截至最新章的当前值)。另返回记录里核心角色的当前快照。"""
    notes: list[str] = []
    changes = []
    for line in record["character_changes"]:
        parts = line.split("|", 2)
        if len(parts) == 3:
            changes.append({"name": parts[0], "change": parts[2]})
    snapshots = {item["name"]: copy.deepcopy(state["characters"][item["name"]])
                 for item in changes if item["name"] in state["characters"]}

    def rows(lines: list[str], current: dict[str, Any], label: str) -> list[dict[str, Any]]:
        prefilled = []
        for line in lines:
            parts = line.split("|")
            identifier = parts[0]
            if len(parts) > 1 and parts[1] == "删除当前登记":
                if identifier in current:
                    notes.append(f"{label} {identifier} 本章删过、后来又登记了,没有预填删除,确需删除自行加回")
                else:
                    prefilled.append({"action": "delete", "id": identifier})
            elif identifier in current:
                prefilled.append({"action": "upsert", **{key: copy.deepcopy(value) for key, value in current[identifier].items()
                                                         if key not in ("updated_chapter", "first_recorded_chapter")}})
            else:
                notes.append(f"{label} {identifier} 已在后续章节删除,没有预填")
        return prefilled

    delta = {
        "result": record["result"],
        "character_changes": changes,
        "foreshadow_changes": rows(record["foreshadow_changes"], state["foreshadow"], "伏笔"),
        "timeline_events": rows(record["timeline_events"], state["timeline"], "时间线事件"),
        "constraints": list(record["constraints"]),
        "next_chapter_commitments": list(record["next_chapter_commitments"]),
    }
    return delta, snapshots, notes


def entry_shapes(chapter: int) -> dict[str, Any]:
    """draft 当场给出每类条目的形状:模型填 delta 时手里只有空数组,字段名、整数、枚举都靠猜,
    首次提交几乎都因此被退回。取值从校验用的同一组常量生成,不另立一套。"""
    return {
        "delta.character_changes[]": {"name": "角色名", "change": "一句话:本章起了什么变化"},
        "delta.foreshadow_changes[]": {
            "action": "upsert(撤掉整条写 delete,只带 id)", "id": "F007", "summary": "伏笔一句话",
            "planted_chapter": chapter, "planned_resolution_chapter": "计划回收章的整数,未定写 null",
            "status": "|".join(FORESHADOW_STATUSES), "importance": "|".join(FORESHADOW_IMPORTANCE),
        },
        "delta.timeline_events[]": {
            "action": "upsert(撤掉整条写 delete,只带 id)", "id": "E012", "story_time": "故事内时间",
            "objective_fact": "客观发生了什么", "reader_knowledge": "读者此刻知道/以为什么",
            "reveal_status": "|".join(REVEAL_STATUSES),
            "reveal_chapter": f"已揭示或部分揭示时写揭示章的整数(不晚于 {chapter}),未揭示写 null",
            "characters": ["角色名"],
        },
        "character_snapshots.{角色名}": {
            **{key: "一句话" for key in SNAPSHOT_TEXT_FIELDS},
            **{key: ["一条一句"] for key in SNAPSHOT_LIST_FIELDS},
        },
    }


def draft_transaction(
    project: Path, chapter: int, *, state: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
    """按当前 state 预填一份逐章事务:修订号、模式、章名和整份提交的上下文当前值都填好。
    新章(append)调用方只写本章变化;另返回在场核心角色的当前快照,供有变化时整份改写后放进事务。
    新章的故事时间与场景留空:它们必须是本章结束时的位置,沿用上一章的值能静默提交,
    所以不预填,上一章的值另行返回作参考。
    修订(revision)的 delta 是修订后本章的完整记录,所以按已提交的逐章记录预填,调用方在上面改;
    第三项返回 {"notes": [...], "prefilled": bool}:没能预填的条目,以及逐章记录是否读到。"""
    if state is None:
        state = load_state(project)
    last = state["last_committed_chapter"]
    require(1 <= chapter <= last + 1, f"draft chapter must be between 1 and {last + 1}")
    mode = "append" if chapter == last + 1 else "revision"
    title = ""
    for outline in sorted((project / "大纲").glob(f"细纲_第{chapter:03d}章*.md")):
        match = re.search(rf"^#{{1,4}}\s*第\s*0*{chapter}\s*章\s*[::]\s*(.+?)\s*$",
                          outline.read_text(encoding="utf-8"), re.M)
        if match:
            title = match.group(1).strip()
            break
    context = json.loads(json.dumps(state["context"], ensure_ascii=False))
    previous_position = {key: context["position"][key] for key in ("story_time", "scene")}
    delta: dict[str, Any] = {
        "result": "", "character_changes": [], "foreshadow_changes": [], "timeline_events": [],
        "constraints": [], "next_chapter_commitments": [],
    }
    snapshots_prefill: dict[str, Any] = {}
    notes: list[str] = []
    prefilled = False
    if mode == "append":
        delta.update({"retired_context_items": [], "retired_characters": []})
        context["position"].update({"story_time": "", "scene": ""})
    else:
        record = parse_chapter_record(delta_path(tracking_root(project), chapter))
        if record is not None:
            prefilled = True
            delta, snapshots_prefill, notes = record_prefill(state, record)
            title = title or record["title"]
            if chapter == last:
                # 最新章的承诺原样在 state 里,比从记录行按「;」拆回更准。
                delta["next_chapter_commitments"] = list(state["context"]["next_chapter_commitments"])
    document = {
        "schema_version": INPUT_SCHEMA_VERSION,
        "mode": mode,
        "chapter": chapter,
        "chapter_title": title,
        "expected_state_revision": state["state_revision"],
        "delta": delta,
        "context": {key: context[key] for key in
                    ("position", "long_term_constraints", "active_character_names", "continuity_risks")},
        "character_snapshots": snapshots_prefill,
    }
    snapshots = {name: state["characters"][name] for name in context["active_character_names"]
                 if name in state["characters"]}
    if mode == "revision":
        return document, snapshots, {"notes": notes, "prefilled": prefilled}
    return document, snapshots, previous_position


def rebuild_stale_draft(document: dict[str, Any], existing: dict[str, Any], append: bool,
                        current_characters: Any = ()) -> str:
    """修订号变了:中间提交过别的事务。以当前状态为底,只自动合并确定安全的部分,其余列给调用方核对。

    新章草稿之间只可能插进修订事务,修订不能删约束与风险条目,所以当前约束与风险覆盖旧底稿:
    旧草稿多出来的就是本章新增,delta 里声明退役的就是本章删除,可以精确合并。
    修订草稿之间可能插进新章(新章能退役条目),在场角色名修订也能删,都无法判断谁新:
    取当前状态,差异列出来;只有本章带了快照的新角色名自动加回。"""
    def items(value: object) -> list[str]:
        return [item for item in value if isinstance(item, str)] if isinstance(value, list) else []

    def norm(item: str) -> str:
        return " ".join(item.replace("|", "|").split())

    notes = ["修订号已变:context 按当前状态重建,本章已填的 delta" + ("、新增与退役的约束、结尾位置" if append else "")
             + "已合并"]
    for key in ("delta", "character_snapshots"):
        if isinstance(existing.get(key), dict):
            document[key] = existing[key]
    if existing.get("chapter_title"):
        document["chapter_title"] = existing["chapter_title"]
    old_context = existing.get("context") if isinstance(existing.get("context"), dict) else {}
    delta = document["delta"] if isinstance(document["delta"], dict) else {}
    context = document["context"]
    retired = {norm(item) for item in items(delta.get("retired_context_items"))}
    left_out: list[str] = []
    for key in ("long_term_constraints", "continuity_risks"):
        current = {norm(item) for item in context[key]}
        extra = []
        for item in items(old_context.get(key)):
            if norm(item) not in current:
                current.add(norm(item))
                extra.append(item)
        if append:
            context[key] = [item for item in context[key] if norm(item) not in retired] + extra
        else:
            left_out += extra
    snapshots = document["character_snapshots"] if isinstance(document["character_snapshots"], dict) else {}
    names = context["active_character_names"]
    for name in items(old_context.get("active_character_names")):
        if name in names:
            continue
        if append and name in snapshots:
            names.append(name)
        else:
            left_out.append(f"在场角色 {name}")
    names[:] = [name for name in names if name not in set(items(delta.get("retired_characters")))]
    known = set(current_characters)
    for name in list(snapshots):
        if name not in known and name not in names:
            snapshots.pop(name)
            left_out.append(f"角色快照 {name}")
    if left_out:
        notes.append("草稿里有、当前状态没有的条目没有自动带回(可能已被别的提交退役),本章确实需要就加回:"
                     + ";".join(left_out))
    old_position = old_context.get("position") if isinstance(old_context.get("position"), dict) else {}
    position = context["position"]
    if append:
        for key in ("story_time", "scene"):
            if isinstance(old_position.get(key), str) and old_position[key].strip():
                position[key] = old_position[key]
    differs = [f"{key}:草稿写的是「{old_position[key]}」,当前状态是「{position[key]}」"
               for key in ("volume", "volume_start_chapter")
               if key in old_position and old_position[key] != position[key]]
    if differs:
        notes.append("卷信息与当前状态不同,已取当前状态,本章确实换卷就改回(" + ";".join(differs) + ")")
    if snapshots:
        notes.append("带过来的角色快照(" + "、".join(snapshots) + ")可能被中间的提交改过,逐个对照 current_snapshots 或 snapshot_files 重核")
    return ";".join(notes)


def prepare_draft_snapshots(
    project: Path,
    chapter: int,
    all_characters: dict[str, dict[str, Any]],
    active_names: list[str],
) -> tuple[dict[str, dict[str, Any]], dict[str, str], list[str]]:
    """把全部核心角色的当前快照落到本章工作目录,并把 stdout 内联体积控制在预算内。

    久别回归的非在场核心角色不在 active_character_names 里,但本章一旦变化也必须交完整新快照;
    单角色快照放大到 64 KiB 后,20 名在场角色全塞进单行 stdout 又会撑大上下文或被宿主截断。
    因此所有核心角色一律写 `.story/work/第NNN章/snapshots/{名}.json`(随 chapter commit 自动清理),
    stdout 的 `current_snapshots` 只内联预算内的在场角色,其余指路 `snapshot_files`。
    """
    snapshots_dir = chapter_work_dir(project, chapter) / "snapshots"
    expected_files = {f"{name}.json" for name in all_characters}
    if snapshots_dir.is_dir():
        for existing_file in snapshots_dir.glob("*.json"):
            if existing_file.name not in expected_files:
                existing_file.unlink()
        if not all_characters:
            try:
                snapshots_dir.rmdir()
            except OSError:
                pass
    snapshot_files: dict[str, str] = {}
    for name, snap in all_characters.items():
        target = snapshots_dir / f"{name}.json"
        write_if_changed(target, json_payload(snap))
        snapshot_files[name] = str(target)

    inline: dict[str, dict[str, Any]] = {}
    omitted: list[str] = []
    used_bytes = 2
    for name in dict.fromkeys(active_names):
        if name not in all_characters:
            continue
        entry_bytes = byte_size(json.dumps({name: all_characters[name]}, ensure_ascii=False))
        if used_bytes + entry_bytes <= DRAFT_INLINE_SNAPSHOTS_MAX_BYTES:
            inline[name] = all_characters[name]
            used_bytes += entry_bytes
        else:
            omitted.append(name)
    return inline, snapshot_files, omitted


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    subparsers = parser.add_subparsers(dest="command", required=True)
    for command in ("init", "commit"):
        subparser = subparsers.add_parser(command)
        subparser.add_argument("--project", type=Path, required=True, help="book project root containing 追踪/")
        subparser.add_argument("--input", type=Path, required=True, help="UTF-8 JSON input document")
    check_parser = subparsers.add_parser("check")
    check_parser.add_argument("--project", type=Path, required=True, help="book project root containing 追踪/")
    draft_parser = subparsers.add_parser("draft", help="write a pre-filled chapter transaction to fill in")
    draft_parser.add_argument("--project", type=Path, required=True, help="book project root containing 追踪/")
    draft_parser.add_argument("--chapter", type=int, required=True)
    draft_parser.add_argument("--out", type=Path, help="default: <project>/.story/work/第NNN章/tracking.json")
    draft_parser.add_argument("--force", action="store_true",
                              help="discard an existing draft instead of only refreshing its revision")
    return parser


def main() -> int:
    args = build_parser().parse_args()
    try:
        try:
            args.project = wordcount_core.resolve_book_dir(args.project)
        except wordcount_core.WordcountError as exc:
            raise TrackingError(str(exc)) from exc
        if args.command == "draft":
            state = load_state(args.project)
            document, _, extra = draft_transaction(args.project, args.chapter, state=state)
            all_characters = state["characters"]
            previous_position = extra if document["mode"] == "append" else {}
            prefill_notes = extra.get("notes", []) if document["mode"] == "revision" else []
            record_prefilled = bool(extra.get("prefilled")) if document["mode"] == "revision" else False
            out = args.out or chapter_work_dir(args.project, args.chapter) / "tracking.json"
            out.parent.mkdir(parents=True, exist_ok=True)
            refreshed = ""
            if out.exists() and not args.force:
                # 重跑 draft 不冲掉已经填好的变化。修订号变了说明中间提交过别的事务:context 按当前
                # 状态重建(沿用旧 context 会把那次变更整份覆盖回去),只带过本章自己填的部分。
                existing = read_json(out)
                require(isinstance(existing, dict) and existing.get("chapter") == document["chapter"]
                        and existing.get("mode") == document["mode"],
                        f"{out} already holds a draft for a different chapter or mode; pass --force to replace it")
                if existing.get("expected_state_revision") == document["expected_state_revision"]:
                    document, refreshed = existing, "已有草稿且修订号未变,原样保留"
                else:
                    refreshed = rebuild_stale_draft(document, existing, bool(previous_position), all_characters)
            out.write_text(json.dumps(document, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
            raw_active = (document.get("context") or {}).get("active_character_names") if isinstance(document.get("context"), dict) else []
            active_names = [name for name in raw_active if isinstance(name, str)] if isinstance(raw_active, list) else []
            snapshots, snapshot_files, omitted_snapshots = prepare_draft_snapshots(
                args.project, args.chapter, all_characters, active_names
            )
            if document["mode"] == "revision" and not record_prefilled:
                fill = (f"这是修订,但本章逐章记录缺失或读不了({delta_path(Path('追踪'), args.chapter).as_posix()}),delta 没有预填:"
                        "按修订后正文把本章完整记录整份写上(结果、承诺、角色变化、伏笔、时间线、约束),没写的项不会进记录。"
                        "角色快照、伏笔、时间线写截至最新已写章的当前值(已有核心角色的当前快照见 snapshot_files);context 原样保留全部当前条目(修订不能退役)。"
                        "正文改过就用 story-long-write 的 storyctl.py chapter commit 提交(重新计数并清理本章工作目录)。"
                        "不要从脚本源码或 state 文件里另找格式。")
            elif document["mode"] == "revision":
                fill = ("这是修订:delta 是修订后本章的完整记录,已按本章现有逐章记录预填(伏笔与时间线取当前值,"
                        "记录里的核心角色快照已放进 character_snapshots,其他核心角色当前快照见 snapshot_files)。对照修订后正文逐项改:仍成立的原样保留,"
                        "被推翻的删掉或改写,新增的补上;不要清空后只写改动,没写的项会从本章记录里消失。"
                        "角色快照、伏笔、时间线改成截至最新已写章的当前值;context 原样保留全部当前条目(修订不能退役)。"
                        "正文改过就用 story-long-write 的 storyctl.py chapter commit 提交(重新计数并清理本章工作目录)。"
                        "不要从脚本源码或 state 文件里另找格式。")
                if prefill_notes:
                    fill += "没能预填:" + ";".join(prefill_notes) + "。"
            else:
                fill = ("只填 delta 里本章的变化;context 其余字段已是当前值,要撤下的长期约束或连贯性风险从 context 删掉并把原文放进 "
                        "delta.retired_context_items(仅 append);本章有变化的核心角色从 current_snapshots(未内联的大快照或久别回归角色读 snapshot_files 对应 JSON)"
                        "取当前快照整份改好放进 character_snapshots,并在 character_changes 写一句变化。每类条目照 shapes 的形状写,不要从脚本源码或 state 文件里另找格式。")
            if omitted_snapshots:
                fill = (f"在场角色({'、'.join(omitted_snapshots)})快照较大未内联到 stdout,本章若有变化先读取 snapshot_files 对应 JSON 在其基础上修改,勿凭空重写以免丢失既有条目。") + fill
            blank = not (document["context"]["position"].get("story_time") or document["context"]["position"].get("scene"))
            if previous_position and blank:
                fill = ("context.position 的 story_time 与 scene 留空,填本章结束时的故事时间与场景(上一章结束时见 "
                        "previous_position;换卷时连同 volume 与 volume_start_chapter 一起改)。") + fill
            payload = {
                "draft": str(out),
                "mode": document["mode"],
                "expected_state_revision": document["expected_state_revision"],
                "fill": (f"{refreshed};要从头生成加 --force。" if refreshed else "") + fill,
                "limits_chars": DRAFT_LIMITS,
                "shapes": entry_shapes(args.chapter),
                "current_snapshots": snapshots,
                "snapshot_files": snapshot_files,
            }
            if omitted_snapshots:
                payload["omitted_active_snapshots"] = omitted_snapshots
            if previous_position:
                payload["previous_position"] = previous_position
            emit(json.dumps(payload, ensure_ascii=False))
            return 0
        if args.command == "init":
            result = initialize(args.project, read_json(args.input))
        elif args.command == "commit":
            result = apply_transaction(args.project, read_json(args.input))
        else:
            result = check_project(args.project)
    except (TrackingError, OSError, UnicodeError) as exc:
        emit(f"ERROR: {exc}", error=True)
        return 2
    emit(
        json.dumps(
            {
                "last_committed_chapter": result["last_committed_chapter"],
                "state_revision": result["state_revision"],
            },
            ensure_ascii=False,
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall