@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

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

@@ -1,328 +0,0 @@
-"""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/tests/README.md

@@ -1,70 +0,0 @@
-# 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]` / 命令行路径都需要同步更新——跑全套就能
-立刻发现哪些路径断了。

package/skills/trtc-topic/tests/conftest.py

@@ -1,72 +0,0 @@
-"""pytest fixtures for the topic state-machine and gate hooks.
-
-These fixtures only know about session files and a simulated project root.
-They never touch the real repo session.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-import yaml
-
-
-# Default confirmed_plan used by most tests — mirrors the general-conference
-# minimal scope (P0).
-DEFAULT_CONFIRMED_PLAN = [
-    "conference/login-auth",
-    "conference/room-lifecycle",
-    "conference/participant-list",
-    "conference/video-layout",
-    "conference/device-control",
-    "conference/network-quality",
-]
-
-
-@pytest.fixture
-def session_factory(tmp_path: Path):
-    """Factory that writes a `.trtc-session.yaml` into tmp_path.
-
-    Returns a callable: ``make_session(**overrides) -> Path``.
-    Defaults are picked to match a typical mid-integration general-conference/web
-    session so individual tests only override what they care about.
-    """
-
-    def _make(**overrides) -> Path:
-        base = {
-            "schema_version": 1,
-            "status": "active",
-            "product": "conference",
-            "platform": "web",
-            "intent": "integrate-scenario",
-            "scenario": "general-conference",
-            "ui_mode": None,
-            "current_step": "topic-handoff",
-            "confirmed_plan": list(DEFAULT_CONFIRMED_PLAN),
-            "completed_steps": [],
-            "project_state": {
-                "project_root": str(tmp_path / "user-project"),
-            },
-        }
-        base.update(overrides)
-        path = tmp_path / ".trtc-session.yaml"
-        path.write_text(yaml.safe_dump(base, sort_keys=False, allow_unicode=True))
-        return path
-
-    return _make
-
-
-@pytest.fixture
-def project_factory(tmp_path: Path):
-    """Factory that creates an empty user project skeleton at tmp_path/user-project.
-
-    Returns the project root Path. Tests can write whatever Vue/TS files they
-    need into it.
-    """
-
-    def _make() -> Path:
-        root = tmp_path / "user-project"
-        (root / "src").mkdir(parents=True, exist_ok=True)
-        return root
-
-    return _make