@tencent-rtc/trtc-agent-skills 0.1.0

package/skills/trtc-topic/scripts/init_slice_queue.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""init_slice_queue.py — Topic-skill CLI: materialise execution_queue from session.
+
+Usage:
+    python3 init_slice_queue.py                 # auto-resolves session path
+    python3 init_slice_queue.py --session PATH  # explicit override
+
+Session path resolution (in order):
+    1. --session flag, if given
+    2. $TRTC_SESSION_PATH env var
+    3. $CLAUDE_PROJECT_DIR/.trtc-session.yaml (Claude Code sets this to the
+       user project root)
+    4. ./.trtc-session.yaml (cwd fallback — useful when AI runs Bash from
+       the user project root)
+
+Reads ``confirmed_plan`` from the session and writes:
+    execution_queue, current_execution_index=0, current_execution_state=not_started
+
+Idempotent. Refuses to re-init if the plan has changed (queue is frozen).
+
+Exit codes:
+    0 — success (queue written or already up to date)
+    1 — confirmed_plan missing/empty, or plan diverged from existing queue
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / "lib"))
+import state_machine  # noqa: E402
+
+
+def _resolve_session_path() -> Path:
+    """Match the resolver used by guardrails/gate_*.py:
+    env var → $CLAUDE_PROJECT_DIR → cwd. The session file lives in the
+    user project, never in the skill repo, so we never look at HERE.parents.
+    """
+    explicit = os.environ.get("TRTC_SESSION_PATH")
+    if explicit:
+        return Path(explicit)
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project_dir:
+        return Path(project_dir) / ".trtc-session.yaml"
+    return Path.cwd() / ".trtc-session.yaml"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--session",
+        type=Path,
+        default=None,
+        help="explicit path to .trtc-session.yaml (overrides env-based resolver)",
+    )
+    args = parser.parse_args(argv)
+
+    session_path = args.session if args.session is not None else _resolve_session_path()
+
+    if not session_path.exists():
+        print(
+            f"error: session file not found at {session_path}\n"
+            f"  hint: cd to the user project root, or set $CLAUDE_PROJECT_DIR / "
+            f"$TRTC_SESSION_PATH before running this script.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        state_machine.init_queue(session_path)
+    except RuntimeError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    st = state_machine.status(session_path)
+    kind = st.get("kind", "slice")
+    cur = st.get("current_unit_id") or st.get("current_slice_id")
+    if kind == "unit":
+        print(
+            f"queue initialised — {st['total']} delivery units, "
+            f"cursor at [{st['index']}] {cur} ({st['state']}), "
+            f"slices: {', '.join(st.get('slice_ids') or [])}"
+        )
+    else:
+        print(
+            f"queue initialised — {st['total']} slices, "
+            f"cursor at [{st['index']}] {cur} ({st['state']})"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/trtc-topic/scripts/lib/state_machine.py

@@ -0,0 +1,328 @@
+"""Execution-step state machine for the topic skill.
+
+The state machine is the enforcement mechanism for topic execution. It stores a
+single ``execution_queue`` in ``.trtc-session.yaml``. Each execution step has a
+uniform shape:
+
+    {id, type: "slice" | "unit", status, slices: [...]}
+
+Slices remain the knowledge and rule source. Execution steps define how many
+slices are delivered in one read/write/apply loop.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+import yaml
+
+
+_TRANSITIONS = {
+    ("not_started", "mark_slice_read"): "slice_read",
+    ("slice_read", "mark_code_written"): "code_written",
+    ("code_written", "mark_apply_passed"): "apply_passed",
+    ("code_written", "mark_apply_failed"): "apply_failed",
+    ("apply_failed", "mark_code_written"): "code_written",
+    ("apply_passed", "mark_user_confirmed"): "ADVANCE_INDEX",
+}
+
+_KNOWN_TRANSITIONS = {t for (_state, t) in _TRANSITIONS.keys()}
+_TOPIC_ROOT = Path(__file__).resolve().parents[2]
+_EXECUTION_UNITS_PATH = _TOPIC_ROOT / "references" / "execution-units.yaml"
+
+
+def _load(path: Path) -> dict:
+    return yaml.safe_load(path.read_text()) or {}
+
+
+def _save(path: Path, data: dict) -> None:
+    path.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True))
+
+
+def _step_id_from_slices(slice_ids: list[str]) -> str:
+    if len(slice_ids) == 1:
+        return slice_ids[0]
+    return "__".join(s.split("/", 1)[1] for s in slice_ids)
+
+
+def _step_type(slice_ids: list[str]) -> str:
+    return "unit" if len(slice_ids) > 1 else "slice"
+
+
+def _make_step(step_id: str, title: str, slice_ids: list[str], *, status: str = "pending") -> dict:
+    return {
+        "id": step_id,
+        "type": _step_type(slice_ids),
+        "title": title,
+        "status": status,
+        "slices": slice_ids,
+    }
+
+
+def _build_declared_unit_steps(raw_units, plan: list[str]) -> list[dict]:
+    """Group only slices already present in confirmed_plan."""
+    configured = [
+        sid
+        for raw in raw_units or []
+        for sid in (raw.get("slices") or [])
+    ]
+    duplicates = sorted({sid for sid in configured if configured.count(sid) > 1})
+    if duplicates:
+        raise RuntimeError("delivery unit config contains duplicate slices: " + ", ".join(duplicates))
+
+    remaining = list(plan)
+    steps: list[dict] = []
+
+    for raw in raw_units or []:
+        group = raw.get("slices") or []
+        slice_ids = [sid for sid in group if sid in remaining]
+        if len(slice_ids) < 2:
+            continue
+        step_id = raw.get("id") or _step_id_from_slices(slice_ids)
+        steps.append(_make_step(step_id, raw.get("title") or step_id, slice_ids))
+        for sid in slice_ids:
+            remaining.remove(sid)
+
+    for sid in remaining:
+        steps.append(_make_step(sid, sid, [sid]))
+
+    order = {sid: i for i, sid in enumerate(plan)}
+    steps.sort(key=lambda step: min(order[sid] for sid in step["slices"]))
+    return steps
+
+
+def _scenario_delivery_units(data: dict) -> list[dict]:
+    scenario = data.get("scenario")
+    if not scenario or not _EXECUTION_UNITS_PATH.exists():
+        return []
+    config = yaml.safe_load(_EXECUTION_UNITS_PATH.read_text()) or {}
+    return (
+        (config.get("scenarios") or {})
+        .get(scenario, {})
+        .get("delivery_units")
+        or []
+    )
+
+
+def _build_slice_steps(plan: list[str]) -> list[dict]:
+    return [_make_step(sid, sid, [sid]) for sid in plan]
+
+
+def _flatten_slices(queue: list[dict]) -> list[str]:
+    return [sid for step in queue for sid in step.get("slices", [])]
+
+
+def _execution_queue_from_legacy(data: dict) -> list[dict] | None:
+    """Best-effort read compatibility for old sessions."""
+    if data.get("execution_queue"):
+        return data["execution_queue"]
+    if data.get("delivery_unit_queue"):
+        return [
+            _make_step(
+                entry.get("id") or _step_id_from_slices(entry.get("slices", [])),
+                entry.get("title") or entry.get("id") or "",
+                entry.get("slices", []),
+                status=entry.get("status", "pending"),
+            )
+            for entry in data["delivery_unit_queue"]
+        ]
+    if data.get("slice_queue"):
+        return [
+            _make_step(entry.get("id"), entry.get("id"), [entry.get("id")], status=entry.get("status", "pending"))
+            for entry in data["slice_queue"]
+            if entry.get("id")
+        ]
+    return None
+
+
+def _current_index_state(data: dict) -> tuple[int, str]:
+    if "current_execution_index" in data or "current_execution_state" in data:
+        return data.get("current_execution_index", 0), data.get("current_execution_state") or "not_started"
+    if data.get("execution_granularity") in {"unit", "delivery_unit"}:
+        return data.get("current_unit_index", 0), data.get("current_unit_state") or "not_started"
+    return data.get("current_slice_index", 0), data.get("current_slice_state") or "not_started"
+
+
+def init_queue(session_path) -> None:
+    """Materialise ``confirmed_plan`` into ``execution_queue``.
+
+    Idempotent when the queue already covers the same confirmed_plan. Refuses
+    re-init if the plan changed after topic took ownership.
+    """
+    path = Path(session_path)
+    data = _load(path)
+    plan = data.get("confirmed_plan")
+    if not plan:
+        raise RuntimeError(
+            "confirmed_plan is missing or empty in session — onboarding A2 "
+            "should have populated it before topic ran init_queue."
+        )
+
+    expected_ids = list(plan)
+    existing_queue = data.get("execution_queue")
+    if existing_queue is not None:
+        if _flatten_slices(existing_queue) != expected_ids:
+            raise RuntimeError(
+                "execution_queue is frozen and differs from confirmed_plan — "
+                "remove execution_queue / current_execution_index / "
+                "current_execution_state from the session file and run init again."
+            )
+        return
+
+    if data.get("execution_granularity") in {"unit", "delivery_unit"}:
+        raw_units = data.get("delivery_units") or _scenario_delivery_units(data)
+        queue = _build_declared_unit_steps(raw_units, expected_ids)
+    else:
+        queue = _build_slice_steps(expected_ids)
+
+    data["execution_queue"] = queue
+    data["current_execution_index"] = 0
+    data["current_execution_state"] = "not_started"
+    _save(path, data)
+
+
+def current_scope(session_path) -> dict:
+    """Return the active execution step."""
+    path = Path(session_path)
+    if not path.exists():
+        return {"initialised": False, "reason": "session file missing"}
+
+    data = _load(path)
+    queue = _execution_queue_from_legacy(data)
+    if not queue:
+        return {"initialised": False, "reason": "execution_queue not set"}
+
+    idx, state = _current_index_state(data)
+    if state == "all_done":
+        return {
+            "initialised": True,
+            "kind": "execution",
+            "index": idx,
+            "state": "all_done",
+            "total": len(queue),
+            "id": None,
+            "title": None,
+            "type": None,
+            "slice_ids": [],
+            "queue": queue,
+        }
+    if idx is None or idx < 0 or idx >= len(queue):
+        return {"initialised": False, "reason": "execution cursor out of range"}
+
+    step = queue[idx]
+    slice_ids = step.get("slices") or [step.get("id")]
+    return {
+        "initialised": True,
+        "kind": step.get("type", _step_type(slice_ids)),
+        "index": idx,
+        "state": state,
+        "total": len(queue),
+        "id": step.get("id"),
+        "title": step.get("title") or step.get("id"),
+        "type": step.get("type", _step_type(slice_ids)),
+        "slice_ids": slice_ids,
+        "queue": queue,
+    }
+
+
+def current_slice(session_path) -> Tuple[Optional[int], Optional[str], Optional[str]]:
+    """Compatibility helper returning the first slice in the current step."""
+    scope = current_scope(session_path)
+    if not scope.get("initialised"):
+        return (None, None, None)
+    if scope.get("state") == "all_done":
+        return (scope.get("index"), None, "all_done")
+    slice_ids = scope.get("slice_ids") or []
+    return (scope.get("index"), slice_ids[0] if slice_ids else None, scope.get("state"))
+
+
+def advance(session_path, transition: str) -> str:
+    if transition not in _KNOWN_TRANSITIONS:
+        raise RuntimeError(
+            f"unknown transition '{transition}'. Known transitions: "
+            f"{sorted(_KNOWN_TRANSITIONS)}"
+        )
+
+    path = Path(session_path)
+    data = _load(path)
+    queue = data.get("execution_queue")
+    if not queue:
+        legacy = _execution_queue_from_legacy(data)
+        if legacy:
+            queue = legacy
+            data["execution_queue"] = queue
+        else:
+            raise RuntimeError("execution_queue not initialised — call init_queue() before advance().")
+
+    state = data.get("current_execution_state")
+    idx = data.get("current_execution_index", 0)
+    if state is None:
+        legacy_idx, legacy_state = _current_index_state(data)
+        idx = legacy_idx
+        state = legacy_state
+        data["current_execution_index"] = idx
+        data["current_execution_state"] = state
+
+    if state == "all_done":
+        raise RuntimeError(
+            "all_done — the execution queue is finished; no further transitions "
+            "are allowed. Start a new scenario or reset the session."
+        )
+
+    next_state = _TRANSITIONS.get((state, transition))
+    if next_state is None:
+        raise RuntimeError(
+            f"illegal transition '{transition}' from state '{state}'. "
+            f"Allowed from '{state}': "
+            f"{sorted(t for (s, t) in _TRANSITIONS.keys() if s == state)}"
+        )
+
+    if next_state == "ADVANCE_INDEX":
+        step = queue[idx]
+        step["status"] = "done"
+        evidence_ids = [step.get("id"), *step.get("slices", [])]
+        for evidence_id in [eid for eid in evidence_ids if eid]:
+            ev_path = path.parent / ".trtc-apply-evidence" / (evidence_id.replace("/", "__") + ".json")
+            try:
+                ev_path.unlink()
+            except FileNotFoundError:
+                pass
+
+        new_idx = idx + 1
+        data["execution_queue"] = queue
+        data["current_execution_index"] = new_idx
+        data["current_execution_state"] = "all_done" if new_idx >= len(queue) else "not_started"
+        _save(path, data)
+        return data["current_execution_state"]
+
+    data["execution_queue"] = queue
+    data["current_execution_state"] = next_state
+    _save(path, data)
+    return next_state
+
+
+def status(session_path) -> dict:
+    path = Path(session_path)
+    if not path.exists():
+        return {"initialised": False, "reason": "session file missing"}
+    data = _load(path)
+    queue = _execution_queue_from_legacy(data)
+    if not queue:
+        return {"initialised": False, "reason": "execution_queue not set"}
+
+    idx, state = _current_index_state(data)
+    current = queue[idx] if idx < len(queue) else None
+    slice_ids = (current.get("slices") if current else None) or []
+    step_type = current.get("type", _step_type(slice_ids)) if current else None
+    return {
+        "initialised": True,
+        "kind": step_type or "execution",
+        "index": idx,
+        "state": state,
+        "total": len(queue),
+        "current_slice_id": slice_ids[0] if slice_ids else None,
+        "current_unit_id": current.get("id") if current and step_type == "unit" else None,
+        "current_id": current.get("id") if current else None,
+        "slice_ids": slice_ids,
+        "queue": queue,
+    }

package/skills/trtc-topic/scripts/next_slice.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""next_slice.py — Topic-skill CLI: query and advance the execution cursor.
+
+The topic skill drives one execution step at a time by calling this between
+steps. An execution step may be one slice or one delivery unit containing
+multiple slices.
+
+Usage:
+    python3 next_slice.py status                    # print current cursor
+    python3 next_slice.py advance <transition>      # apply a transition
+
+Transitions (see state_machine.py for the diagram):
+    mark_slice_read       not_started   → slice_read
+    mark_code_written     slice_read    → code_written
+                          apply_failed  → code_written  (retry)
+    mark_apply_passed     code_written  → apply_passed
+    mark_apply_failed     code_written  → apply_failed
+    mark_user_confirmed   apply_passed  → next execution step (or all_done)
+
+Both subcommands print a one-line summary on stdout and exit 0 on success.
+On any error (illegal transition, queue not initialised, etc.) prints to
+stderr and exits 1 — topic should treat that as "abort the current step".
+
+Optional flags:
+    --session PATH    explicit session file path (overrides env-based resolver)
+    --json            emit machine-readable JSON instead of the human line
+
+Session path resolution (when --session not given):
+    1. $TRTC_SESSION_PATH env var
+    2. $CLAUDE_PROJECT_DIR/.trtc-session.yaml (Claude Code sets this to the
+       user project root)
+    3. ./.trtc-session.yaml (cwd fallback)
+"""
+from __future__ import annotations
+
+import argparse
+import json as jsonlib
+import os
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / "lib"))
+import state_machine  # noqa: E402
+
+
+def _resolve_session_path() -> Path:
+    """Match the resolver used by guardrails/gate_*.py."""
+    explicit = os.environ.get("TRTC_SESSION_PATH")
+    if explicit:
+        return Path(explicit)
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project_dir:
+        return Path(project_dir) / ".trtc-session.yaml"
+    return Path.cwd() / ".trtc-session.yaml"
+
+
+def _print_status(session_path: Path, as_json: bool) -> int:
+    st = state_machine.status(session_path)
+    if as_json:
+        print(jsonlib.dumps(st, ensure_ascii=False))
+        return 0
+    if not st.get("initialised"):
+        print(f"queue not initialised: {st.get('reason')}")
+        return 0
+    kind = st.get("kind", "slice")
+    cur = st.get("current_unit_id") or st.get("current_slice_id")
+    detail = ""
+    if kind == "unit":
+        detail = f" ({', '.join(st.get('slice_ids') or [])})"
+    print(f"[{st['index']}/{st['total']}] {kind}:{cur}{detail} :: {st['state']}")
+    return 0
+
+
+def _do_advance(session_path: Path, transition: str, as_json: bool) -> int:
+    try:
+        new_state = state_machine.advance(session_path, transition)
+    except RuntimeError as exc:
+        if as_json:
+            print(jsonlib.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        else:
+            print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    st = state_machine.status(session_path)
+    if as_json:
+        payload = {
+            "ok": True,
+            "transition": transition,
+            "new_state": new_state,
+            "index": st["index"],
+            "current_slice_id": st["current_slice_id"],
+            "current_unit_id": st.get("current_unit_id"),
+            "kind": st.get("kind", "slice"),
+            "slice_ids": st.get("slice_ids") or [],
+        }
+        print(jsonlib.dumps(payload, ensure_ascii=False))
+    else:
+        cur = st.get("current_unit_id") or st["current_slice_id"] or "(none)"
+        print(
+            f"{transition} OK → [{st['index']}/{st['total']}] "
+            f"{st.get('kind', 'slice')}:{cur} :: {new_state}"
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--session", type=Path, default=None)
+    parser.add_argument("--json", action="store_true")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("status")
+    p_advance = sub.add_parser("advance")
+    p_advance.add_argument("transition")
+    args = parser.parse_args(argv)
+
+    session_path = args.session if args.session is not None else _resolve_session_path()
+
+    if not session_path.exists():
+        msg = (
+            f"error: session file not found at {session_path}\n"
+            f"  hint: cd to the user project root, or set $CLAUDE_PROJECT_DIR / "
+            f"$TRTC_SESSION_PATH before running this script."
+        )
+        if args.json:
+            print(jsonlib.dumps({"ok": False, "error": msg}, ensure_ascii=False))
+        else:
+            print(msg, file=sys.stderr)
+        return 1
+
+    if args.cmd == "status":
+        return _print_status(session_path, args.json)
+    return _do_advance(session_path, args.transition, args.json)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/trtc-topic/tests/README.md

@@ -0,0 +1,70 @@
+# Topic state-machine tests
+
+> ⚪ **内部 — 不对外发布**。这些测试只供 TRTC 知识库维护者使用。
+> 跟项目根 `tests/` 的定位一致，不会随 skill 包分发到用户机器；
+> 发布脚本应当排除整个 `tests/` 目录。end user 不会跑、也不应跑这些测试。
+
+这套测试守护 topic skill 的 slice-loop 状态机、PreToolUse / Stop 守门员
+与 `apply.py` 的契约——也就是阻止 AI 批量读 slice、批量生成代码、跳过 `apply`
+这三类坏行为的那一层硬约束。每次改动 `scripts/`、`scripts/lib/`、
+`guardrails/` 下任何一个文件都应跑一遍这套测试。
+
+## 运行
+
+```bash
+# 在 repo 根
+python3 -m pytest ${CLAUDE_PLUGIN_ROOT}/skills/trtc-topic/tests/
+
+# 看详细
+python3 -m pytest ${CLAUDE_PLUGIN_ROOT}/skills/trtc-topic/tests/ -v
+
+# 单文件
+python3 -m pytest ${CLAUDE_PLUGIN_ROOT}/skills/trtc-topic/tests/test_state_machine.py -v
+
+# 单 case
+python3 -m pytest \
+  ${CLAUDE_PLUGIN_ROOT}/skills/trtc-topic/tests/test_apply_cli.py::TestAutoAdvanceOnPass::test_pause_on_failure_pass_advances_to_next_slice -v
+```
+
+依赖：pytest 8+ 与 PyYAML（项目已有）。
+
+## 覆盖矩阵（85 cases）
+
+| 文件 | cases | 守护对象 | 关键场景 |
+|---|---|---|---|
+| `test_state_machine.py` | 25 | `scripts/lib/state_machine.py` | `init_queue` / `current_slice` / `advance` 全部合法 transition；非法 transition 抛错；apply_failed → 重试；user_confirmed 后清理 evidence；queue 末尾 → all_done |
+| `test_gates.py` | 19 | `guardrails/gate_slice_read.py`、`guardrails/gate_slice_write.py` | session 缺失/queue 未初始化静默放行；只放行 cursor 当前 slice 的 .md；`not_started`/`apply_passed` 状态拦 Write；`slice_read`/`code_written`/`apply_failed` 放行 Edit |
+| `test_apply_cli.py` | 16 | `scripts/apply.py` | pass + fail + static-only + 4 类 usage error；`auto_advance_policy` 五种值；apply 失败永远 pause；最后一个 slice → all_done；demo-test-2 三条 regression（注释/字符串塞 pattern / fail 输出不泄漏 patterns）|
+| `test_stop_require_apply.py` | 8 | `guardrails/stop_require_apply_evidence.py` | session/queue 缺失放行；`not_started` / `slice_read` / `apply_passed` / `all_done` 放行；`code_written` / `apply_failed` 拦截 |
+| `test_end_to_end.py` | 3 | 全链路 | 手动 confirm 完整循环；apply 失败路径；`pause_on_failure` 自动推进路径 |
+| `test_topic_skill_invariants.py` | 4 | `topic/SKILL.md` 结构不变量 | Apply Evidence Block 已删；STATE-MACHINE-GUIDE.md 存在且被引用；topic/SKILL.md 不超过 480 行；Calling apply 段保持紧凑 |
+| `test_session_resolver.py` | 10 | 三个 CLI 共享的 session 路径解析 | 4 级解析链（`--session` flag → `$TRTC_SESSION_PATH` → `$CLAUDE_PROJECT_DIR/.trtc-session.yaml` → cwd）；找不到时给 actionable 提示；三个 CLI 行为一致 |
+
+## Fixtures（`conftest.py`）
+
+- `session_factory(**overrides)` — 在 `tmp_path` 写一个 `${CLAUDE_PROJECT_DIR}/.trtc-session.yaml`。
+  默认仿真"general-conference / web 集成中"的状态。`overrides` 可换 `confirmed_plan`、
+  `auto_advance_policy` 等任意根级字段。
+- `project_factory()` — 在 `tmp_path/user-project/src/` 造空项目骨架，
+  测试可以往里写 .vue / .ts。
+
+## 依赖的目录布局（已对齐 apply skill）
+
+```
+topic/
+├── guardrails/                ← Claude Code 注册的 hook
+│   ├── gate_slice_read.py
+│   ├── gate_slice_write.py
+│   └── stop_require_apply_evidence.py
+├── scripts/                   ← AI 通过 Bash 调用的 runtime CLI
+│   ├── apply.py
+│   ├── init_slice_queue.py
+│   ├── next_slice.py
+│   └── lib/
+│       └── state_machine.py   ← 被 import 的库（不直接跑）
+└── tests/                     ← ⚪ 本目录
+```
+
+如果你 git mv 了 `scripts/` 或 `scripts/lib/` 下的任何文件，这套测试里的
+`sys.path.insert` / `parents[N]` / 命令行路径都需要同步更新——跑全套就能
+立刻发现哪些路径断了。