@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/story-creation/upstream/skills/story-long-write/scripts/tracking_commit.py

@@ -0,0 +1,1691 @@
+#!/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
+SNAPSHOT_TARGET_BYTES = 4096
+SNAPSHOT_MAX_BYTES = 8192
+
+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 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"
+        ),
+        "relationships": clean_string_list(snapshot.get("relationships", []), f"{label}.relationships"),
+        "knowledge": clean_string_list(snapshot.get("knowledge", []), f"{label}.knowledge"),
+        "open_threads": clean_string_list(snapshot.get("open_threads", []), f"{label}.open_threads"),
+    }
+
+
+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"
+    require(
+        byte_size(payload) <= SNAPSHOT_MAX_BYTES,
+        f"character snapshot {name} exceeds hard cap of {SNAPSHOT_MAX_BYTES} bytes",
+    )
+    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"]) <= 6, "context.active_character_names may contain at most 6 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"「{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]:
+    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")
+    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 normalize_state(
+        {
+            "schema_version": TRACKING_SCHEMA_VERSION,
+            "book_title": clean_text(root.get("book_title"), "book_title", max_bytes=240),
+            "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"]:
+        # 已提交字数记录的章节：正文或目标改过却绕开 storyctl 提交修订，会留下过期的 actual/body_sha256。
+        # 只核对记录钉住的正文与目标；细纲事后补的「字数范围」不算过期。
+        try:
+            drift = wordcount_core.wordcount_record_drift(project, chapter, state["wordcount_records"][str(chapter)])
+        except wordcount_core.WordcountError as exc:
+            raise TrackingError(f"第{chapter}章的字数记录无法核对（{exc}）；{RECOUNT_HINT}") from exc
+        if drift:
+            raise TrackingError(f"第{chapter}章{'和'.join(drift)}已改；{RECOUNT_HINT}")
+    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 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:
+            emit(
+                f"WARNING: character snapshot {Path(relative).stem} is {size} bytes; target is <= {SNAPSHOT_TARGET_BYTES}",
+                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)
+    if previous_record is not None:
+        warn_emptied_record(transaction["chapter"], previous_record, transaction["delta"])
+    return next_state
+
+
+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.*.goal / state": 100, "逐章记录总量": 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) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    """按当前 state 预填一份逐章事务：修订号、模式、章名和整份提交的上下文当前值都填好。
+    新章（append）调用方只写本章变化；另返回在场核心角色的当前快照，供有变化时整份改写后放进事务。
+    新章的故事时间与场景留空：它们必须是本章结束时的位置，沿用上一章的值能静默提交，
+    所以不预填，上一章的值另行返回作参考。
+    修订（revision）的 delta 是修订后本章的完整记录，所以按已提交的逐章记录预填，调用方在上面改；
+    第三项返回 {"notes": [...], "prefilled": bool}：没能预填的条目，以及逐章记录是否读到。"""
+    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 重核")
+    return "；".join(notes)
+
+
+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:
+        if args.command == "draft":
+            document, snapshots, extra = draft_transaction(args.project, args.chapter)
+            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 args.project / ".story" / "work" / f"第{args.chapter:03d}章" / "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),
+                                                    load_state(args.project)["characters"])
+            out.write_text(json.dumps(document, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
+            if document["mode"] == "revision" and not record_prefilled:
+                fill = (f"这是修订，但本章逐章记录缺失或读不了（{delta_path(Path('追踪'), args.chapter).as_posix()}），delta 没有预填："
+                        "按修订后正文把本章完整记录整份写上（结果、承诺、角色变化、伏笔、时间线、约束），没写的项不会进记录。"
+                        "角色快照、伏笔、时间线写截至最新已写章的当前值；context 原样保留全部当前条目（修订不能退役）。"
+                        "正文改过就用 story-long-write 的 storyctl.py chapter commit 提交（重新计数并清理本章工作目录）。"
+                        "不要从脚本源码或 state 文件里另找格式。")
+            elif document["mode"] == "revision":
+                fill = ("这是修订：delta 是修订后本章的完整记录，已按本章现有逐章记录预填（伏笔与时间线取当前值，"
+                        "记录里的核心角色快照已放进 character_snapshots）。对照修订后正文逐项改：仍成立的原样保留，"
+                        "被推翻的删掉或改写，新增的补上；不要清空后只写改动，没写的项会从本章记录里消失。"
+                        "角色快照、伏笔、时间线改成截至最新已写章的当前值；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）；本章有变化的核心角色把下面的当前快照整份改好放进 character_snapshots，"
+                        "并在 character_changes 写一句变化。每类条目照 shapes 的形状写，不要从脚本源码或 state 文件里另找格式。")
+            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,
+            }
+            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())