agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/harness/sandbox_recovery_conformance.py

@@ -0,0 +1,246 @@
+"""Conformance suite for authoritative Sandbox command journals.
+
+The provider itself belongs to the control plane.  This module gives provider
+implementations a reusable, storage-agnostic acceptance suite so an HTTP or DB
+adapter cannot silently weaken tenant isolation, optimistic concurrency, or
+terminal-state immutability.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from ksadk.harness.sandbox_backend import (
+    SandboxCommandResumeToken,
+    SandboxResumeToken,
+)
+from ksadk.harness.sandbox_recovery import (
+    SandboxCommandJournalConflict,
+    SandboxCommandJournalProvider,
+    SandboxCommandJournalRecord,
+    SandboxCommandJournalScope,
+    SandboxCommandJournalState,
+)
+
+
+@dataclass(frozen=True)
+class SandboxCommandJournalConformanceFinding:
+    rule: str
+    status: str
+    detail: str = ""
+
+
+@dataclass
+class SandboxCommandJournalConformanceReport:
+    findings: list[SandboxCommandJournalConformanceFinding] = field(
+        default_factory=list
+    )
+
+    @property
+    def passed(self) -> bool:
+        return not any(item.status == "failed" for item in self.findings)
+
+    def pass_rule(self, rule: str) -> None:
+        self.findings.append(
+            SandboxCommandJournalConformanceFinding(rule, "passed")
+        )
+
+    def fail_rule(self, rule: str, detail: str) -> None:
+        self.findings.append(
+            SandboxCommandJournalConformanceFinding(rule, "failed", detail)
+        )
+
+
+async def run_sandbox_command_journal_conformance(
+    provider: SandboxCommandJournalProvider,
+    *,
+    scope: SandboxCommandJournalScope,
+    operation_id: str,
+) -> SandboxCommandJournalConformanceReport:
+    """Verify one provider with an isolated, caller-owned operation id.
+
+    The suite intentionally has no delete operation: authoritative journals
+    are audit records.  Callers should use a dedicated test tenant/workspace
+    and a unique ``operation_id`` for every run.
+    """
+
+    report = SandboxCommandJournalConformanceReport()
+    record = _probe_record(scope=scope, operation_id=operation_id)
+
+    try:
+        created = await provider.create_running(record)
+    except Exception as exc:  # noqa: BLE001 - conformance reports provider failures
+        report.fail_rule("journal.create_running", _exception_detail(exc))
+        return report
+    if created == record:
+        report.pass_rule("journal.create_running")
+    else:
+        report.fail_rule("journal.create_running", "provider changed the wire record")
+
+    await _verify_create_only(provider, record, report)
+    await _verify_scope_isolation(provider, record, report)
+
+    loaded = await _safe_load(provider, record, report)
+    if loaded is None:
+        return report
+
+    completed = await _verify_terminal_transition(provider, loaded, report)
+    if completed is None:
+        return report
+    await _verify_stale_write_rejected(provider, loaded, report)
+    await _verify_terminal_immutable(provider, completed, report)
+    await _verify_terminal_load(provider, completed, report)
+    return report
+
+
+async def _verify_create_only(provider, record, report) -> None:
+    try:
+        await provider.create_running(record)
+    except SandboxCommandJournalConflict:
+        report.pass_rule("journal.create_only")
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.create_only", _exception_detail(exc))
+    else:
+        report.fail_rule("journal.create_only", "duplicate create was accepted")
+
+
+async def _verify_scope_isolation(provider, record, report) -> None:
+    other_scope = SandboxCommandJournalScope(
+        tenant_id=f"{record.scope.tenant_id}-other",
+        workspace_id=record.scope.workspace_id,
+    )
+    try:
+        leaked = await provider.load(record.operation_id, scope=other_scope)
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.scope_isolation", _exception_detail(exc))
+        return
+    if leaked is None:
+        report.pass_rule("journal.scope_isolation")
+    else:
+        report.fail_rule(
+            "journal.scope_isolation",
+            "record was visible from another tenant scope",
+        )
+
+
+async def _safe_load(provider, record, report):
+    try:
+        loaded = await provider.load(record.operation_id, scope=record.scope)
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.load_round_trip", _exception_detail(exc))
+        return None
+    if loaded == record:
+        report.pass_rule("journal.load_round_trip")
+        return loaded
+    report.fail_rule("journal.load_round_trip", "stored record did not round-trip")
+    return None
+
+
+async def _verify_terminal_transition(provider, record, report):
+    try:
+        completed = await provider.finish(
+            record.operation_id,
+            scope=record.scope,
+            expected_version=record.version,
+            state=SandboxCommandJournalState.SUCCEEDED,
+            exit_code=0,
+        )
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.finish_cas", _exception_detail(exc))
+        return None
+    if (
+        completed.state is SandboxCommandJournalState.SUCCEEDED
+        and completed.exit_code == 0
+        and completed.version == record.version + 1
+        and completed.scope == record.scope
+    ):
+        report.pass_rule("journal.finish_cas")
+        return completed
+    report.fail_rule("journal.finish_cas", "terminal fields/version are invalid")
+    return None
+
+
+async def _verify_stale_write_rejected(provider, running, report) -> None:
+    try:
+        await provider.finish(
+            running.operation_id,
+            scope=running.scope,
+            expected_version=running.version,
+            state=SandboxCommandJournalState.FAILED,
+            exit_code=1,
+        )
+    except SandboxCommandJournalConflict:
+        report.pass_rule("journal.stale_write_rejected")
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.stale_write_rejected", _exception_detail(exc))
+    else:
+        report.fail_rule("journal.stale_write_rejected", "stale CAS write was accepted")
+
+
+async def _verify_terminal_immutable(provider, completed, report) -> None:
+    try:
+        await provider.finish(
+            completed.operation_id,
+            scope=completed.scope,
+            expected_version=completed.version,
+            state=SandboxCommandJournalState.FAILED,
+            exit_code=1,
+        )
+    except SandboxCommandJournalConflict:
+        report.pass_rule("journal.terminal_immutable")
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.terminal_immutable", _exception_detail(exc))
+    else:
+        report.fail_rule("journal.terminal_immutable", "terminal record was overwritten")
+
+
+async def _verify_terminal_load(provider, completed, report) -> None:
+    try:
+        loaded = await provider.load(completed.operation_id, scope=completed.scope)
+    except Exception as exc:  # noqa: BLE001
+        report.fail_rule("journal.terminal_round_trip", _exception_detail(exc))
+        return
+    if loaded == completed:
+        report.pass_rule("journal.terminal_round_trip")
+    else:
+        report.fail_rule("journal.terminal_round_trip", "terminal record did not persist")
+
+
+def _probe_record(
+    *,
+    scope: SandboxCommandJournalScope,
+    operation_id: str,
+) -> SandboxCommandJournalRecord:
+    return SandboxCommandJournalRecord(
+        operation_id=operation_id,
+        scope=scope,
+        execution_ref="agent-revision://journal-conformance@1#probe",
+        run_id=f"journal-conformance:{operation_id}",
+        sandbox_token=SandboxResumeToken(
+            backend_id="conformance",
+            handle_id=f"handle:{operation_id}",
+            session_locator=f"session:{operation_id}",
+        ),
+        command_token=SandboxCommandResumeToken(
+            backend_id="conformance",
+            handle_id=f"handle:{operation_id}",
+            session_locator=f"session:{operation_id}",
+            process_id=1,
+        ),
+        spec_fingerprint="sha256:" + "1" * 64,
+        request_fingerprint="sha256:" + "2" * 64,
+        timeout_seconds=30,
+        started_at=time.time(),
+    )
+
+
+def _exception_detail(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {exc}"
+
+
+__all__ = [
+    "SandboxCommandJournalConformanceFinding",
+    "SandboxCommandJournalConformanceReport",
+    "run_sandbox_command_journal_conformance",
+]

ksadk/harness/session_store.py

@@ -0,0 +1,243 @@
+"""Harness Session/Transcript 持久化（plan §6.2.1 / §17 Release）。
+
+- Transcript 是会话事实源：完整事件与消息持久化，压缩不删除（§8.4）；
+- 恢复语义：进程重启后先恢复图 Checkpoint（路由），再从 Transcript 重建
+  ``HarnessState`` 消息部分；两份状态以 checkpoint_id 关联，不一致时以
+  Transcript 为准并记录 ``context.recovered`` 事件（payload 必含 reason）。
+
+本地默认后端为 SQLite（同步、单进程内加锁）；生产后端可替换。
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from typing import Any
+
+from ksadk.harness.events import EventType, RuntimeEvent
+from ksadk.harness.state import HarnessState, Message, MessageRole, WorkingContext
+from ksadk.harness.working_context import record_tool_failure, record_tool_result
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS harness_transcript (
+    tenant_id  TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    seq        INTEGER NOT NULL,
+    kind       TEXT NOT NULL,
+    payload    TEXT NOT NULL,
+    PRIMARY KEY (tenant_id, session_id, seq)
+);
+CREATE INDEX IF NOT EXISTS harness_transcript_session
+    ON harness_transcript (tenant_id, session_id);
+"""
+
+_MESSAGE_KIND = "message"
+_EVENT_KIND = "event"
+
+
+class SqliteSessionStore:
+    """Session/Transcript 存储的本地 SQLite 实现（租户隔离由主键强制）。"""
+
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.executescript(_SCHEMA)
+        self._lock = threading.Lock()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    # ------------------------------------------------------------- 写入
+
+    def append_message(
+        self, *, tenant_id: str, session_id: str, message: Message, seq: int
+    ) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO harness_transcript VALUES (?,?,?,?,?)",
+                (
+                    tenant_id,
+                    session_id,
+                    seq,
+                    _MESSAGE_KIND,
+                    json.dumps(
+                        {
+                            "role": message.role.value,
+                            "content": message.content,
+                            "tool_call_id": message.tool_call_id,
+                            "name": message.name,
+                        },
+                        ensure_ascii=False,
+                    ),
+                ),
+            )
+            self._conn.commit()
+
+    def append_event(self, *, tenant_id: str, session_id: str, event: RuntimeEvent) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO harness_transcript VALUES (?,?,?,?,?)",
+                (
+                    tenant_id,
+                    session_id,
+                    event.seq_id,
+                    _EVENT_KIND,
+                    json.dumps(
+                        {"event_type": event.event_type, "payload": event.payload},
+                        ensure_ascii=False,
+                    ),
+                ),
+            )
+            self._conn.commit()
+
+    # ------------------------------------------------------------- 读取
+
+    def _rows(
+        self, *, tenant_id: str, session_id: str, kind: str | None = None
+    ) -> list[tuple[int, str]]:
+        query = "SELECT seq, payload FROM harness_transcript WHERE tenant_id = ? AND session_id = ?"
+        params: list[Any] = [tenant_id, session_id]
+        if kind:
+            query += " AND kind = ?"
+            params.append(kind)
+        with self._lock:
+            return list(self._conn.execute(query + " ORDER BY seq", params).fetchall())
+
+    def messages(self, *, tenant_id: str, session_id: str) -> list[Message]:
+        messages = []
+        for _seq, payload in self._rows(
+            tenant_id=tenant_id, session_id=session_id, kind=_MESSAGE_KIND
+        ):
+            data = json.loads(payload)
+            messages.append(
+                Message(
+                    role=MessageRole(data["role"]),
+                    content=data["content"],
+                    tool_call_id=data.get("tool_call_id"),
+                    name=data.get("name"),
+                )
+            )
+        return messages
+
+    def events(self, *, tenant_id: str, session_id: str) -> list[dict[str, Any]]:
+        return [
+            json.loads(payload)
+            for _seq, payload in self._rows(
+                tenant_id=tenant_id, session_id=session_id, kind=_EVENT_KIND
+            )
+        ]
+
+    # ------------------------------------------------------------- 恢复
+
+    def rebuild_working_context(
+        self, *, tenant_id: str, session_id: str
+    ) -> WorkingContext:
+        """从 Transcript 事件流重放确定性规则，重建 Working Context。
+
+        长任务方案 MVP 第 6 条：Working Context 使用结构化 Patch 更新并可从
+        Transcript 重建。重放规则与引擎内一致（``working_context`` 模块）：
+
+        - ``tool.call.end`` 失败/审批拒绝 → ``recent_tool_failures``；
+        - ``tool.call.end`` 成功结果中的关键事实 → ``verified_facts``。
+
+        Transcript 不受压缩影响（压缩只动图 Checkpoint 内的消息，事件流
+        完整持久化），因此重放结果即确定性真值。
+        """
+        working = WorkingContext()
+        for _seq, payload in self._rows(
+            tenant_id=tenant_id, session_id=session_id, kind=_EVENT_KIND
+        ):
+            data = json.loads(payload)
+            if data.get("event_type") != EventType.TOOL_CALL_END:
+                continue
+            event_payload = data.get("payload") or {}
+            name = str(event_payload.get("name") or "")
+            if not name:
+                continue
+            error = event_payload.get("error")
+            if error:
+                working = record_tool_failure(
+                    working, name=name, error=str(error)
+                )
+            else:
+                working = record_tool_result(
+                    working, name=name, result_text=str(event_payload.get("result") or "")
+                )
+        return working
+
+    def rebuild_state(
+        self,
+        *,
+        tenant_id: str,
+        user_id: str,
+        agent_id: str,
+        session_id: str,
+    ) -> HarnessState:
+        """从 Transcript 重建 HarnessState 的消息与 Working Context（plan §6.2.1
+        + 长任务方案 MVP 第 6 条：Working Context 可从 Transcript 重建）。"""
+        return HarnessState(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            agent_id=agent_id,
+            session_id=session_id,
+            messages=self.messages(tenant_id=tenant_id, session_id=session_id),
+            working_context=self.rebuild_working_context(
+                tenant_id=tenant_id, session_id=session_id
+            ),
+        )
+
+    def recover(
+        self, checkpoint_state: HarnessState, *, invocation_id: str
+    ) -> tuple[HarnessState, RuntimeEvent | None]:
+        """图 Checkpoint 恢复后的影子状态对账：不一致以 Transcript 为准。
+
+        返回 (对账后状态, context.recovered 事件)。一致时事件为 None。
+        """
+        transcript = self.rebuild_state(
+            tenant_id=checkpoint_state.tenant_id,
+            user_id=checkpoint_state.user_id,
+            agent_id=checkpoint_state.agent_id,
+            session_id=checkpoint_state.session_id,
+        )
+        cp_count = len(checkpoint_state.messages)
+        ts_count = len(transcript.messages)
+        # 仅工具派生字段（verified_facts / recent_tool_failures / version）可从
+        # Transcript 重放；goal/plan 等语义字段 Transcript 无法推导，保留 Checkpoint。
+        ts_wc = transcript.working_context
+        cp_wc = checkpoint_state.working_context
+        wc_differs = (
+            ts_wc.verified_facts != cp_wc.verified_facts
+            or ts_wc.recent_tool_failures != cp_wc.recent_tool_failures
+        )
+        if cp_count == ts_count and not wc_differs:
+            return checkpoint_state, None
+        reason = (
+            f"transcript_wins: checkpoint had {cp_count} messages, "
+            f"transcript has {ts_count}; adopting transcript"
+        )
+        # 消息与 Working Context 工具派生字段以 Transcript 为准（Transcript
+        # 不受压缩影响）；Checkpoint 侧其余运行时字段（approval/goal 等）保留。
+        merged_wc = cp_wc.model_copy(
+            update={
+                "version": ts_wc.version,
+                "verified_facts": ts_wc.verified_facts,
+                "recent_tool_failures": ts_wc.recent_tool_failures,
+            }
+        )
+        recovered = checkpoint_state.model_copy(
+            update={"messages": transcript.messages, "working_context": merged_wc}
+        )
+        event = RuntimeEvent.create(
+            EventType.CONTEXT_RECOVERED,
+            agent_id=checkpoint_state.agent_id,
+            user_id=checkpoint_state.user_id,
+            session_id=checkpoint_state.session_id,
+            invocation_id=invocation_id,
+            seq_id=1,
+            payload={"reason": reason},
+        )
+        return recovered, event
+
+
+__all__ = ["SqliteSessionStore"]

ksadk/harness/skill_composition.py

@@ -0,0 +1,212 @@
+"""Revision/Bundle skillRefs → SkillRuntime 的装配层（打通 Skill 主链路）。
+
+链路各段此前已就位、但中间断开：
+
+- Revision 编译：``compile_revision`` 产出 ``spec.capabilities.skill_bindings``
+  （``skill://name@version`` 固定引用，load_policy=on_demand）；
+- 引擎侧：``ManagedLangGraphEngine(skill_runtime=...)`` + SkillDisclosureBridge
+  把 L0 目录与 L1/L2/L3 披露工具接入默认 Agent Loop。
+
+本模块补上中间一环：把 Revision 的 Skill 引用**解析为本地 Skill 内容目录**并
+构建 :class:`~ksadk.harness.skill_runtime.SkillRuntime`：
+
+1. ``explicit_roots``：调用方直接给定 ``{ref: 目录}``（Revision/Bundle 构建
+   方自己解包的场景）；
+2. 本地 Skill 目录（``local_dir``，默认 ``KSADK_LOCAL_SKILLS_DIR``）：
+   按 ``name@version`` / ``name`` 子目录或 SKILL.md frontmatter name 匹配；
+3. ``ksadk.skills.PackageStore`` 缓存（默认 ``KSADK_SKILL_CACHE_DIR``）：
+   命中已校验的解包目录。
+
+解析失败的 **required** 绑定在装配期即报错（不等编译期）；optional 绑定降级
+并给出 warnings。产出经 :func:`compose_engine` 可直接构造接好 Skill 的引擎。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from ksadk.harness.skill_runtime import LocalSkillSource, SkillRuntime
+from ksadk.harness.spec import HarnessSpec
+
+#: ``skill://name@version`` 引用格式。
+_SKILL_REF_RE = re.compile(r"^skill://(?P<name>[^@/]+)(?:@(?P<version>[^/]+))?$")
+
+#: 可解析的本地 Skill 目录名候选后缀顺序。
+_LOCAL_DIR_SUFFIXES = ("@{version}", "-{version}", "")
+
+
+class SkillResolutionError(RuntimeError):
+    """required Skill 绑定无法解析为本地内容目录。"""
+
+
+def parse_skill_ref(ref: str) -> tuple[str, str]:
+    """解析 ``skill://name@version`` → ``(name, version)``。version 可空。"""
+    match = _SKILL_REF_RE.match(ref.strip())
+    if not match:
+        raise SkillResolutionError(f"Skill 引用格式不受支持（期望 skill://name@version）: {ref!r}")
+    return match.group("name"), match.group("version") or ""
+
+
+def resolve_skill_roots(
+    spec: HarnessSpec,
+    *,
+    explicit_roots: dict[str, str | Path] | None = None,
+    local_dir: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+) -> tuple[dict[str, Path], list[str]]:
+    """把 spec 的 skill_bindings 解析为 ``{ref: 本地内容目录}``。
+
+    返回 ``(roots, warnings)``。required 绑定解析失败抛
+    :class:`SkillResolutionError`；optional 失败记入 warnings 降级。
+    """
+    roots: dict[str, Path] = {}
+    warnings: list[str] = []
+    explicit = {ref: Path(p).resolve() for ref, p in (explicit_roots or {}).items()}
+    local_root = _resolve_local_root(local_dir)
+    store = _build_store(cache_dir)
+
+    for binding in spec.capabilities.skill_bindings:
+        ref = binding.capability_ref
+        if binding.load_policy == "explicit":
+            # explicit：模型完全不可见，不进目录也不需要内容目录。
+            continue
+        root = explicit.get(ref) or _find_local_root(local_root, ref) or _find_cached_root(
+            store, ref
+        )
+        if root is None:
+            message = f"Skill {ref!r} 未解析到本地内容目录"
+            if binding.required:
+                raise SkillResolutionError(message)
+            warnings.append(f"{message}（optional，降级跳过）")
+            continue
+        if not (root / "SKILL.md").is_file():
+            message = f"Skill {ref!r} 目录缺少 SKILL.md: {root}"
+            if binding.required:
+                raise SkillResolutionError(message)
+            warnings.append(message)
+            continue
+        roots[ref] = root
+    return roots, warnings
+
+
+def build_skill_runtime(
+    spec: HarnessSpec,
+    *,
+    explicit_roots: dict[str, str | Path] | None = None,
+    local_dir: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+) -> SkillRuntime | None:
+    """解析 skill_bindings 并构建 SkillRuntime；无绑定或全降级时返回 None。"""
+    roots, _warnings = resolve_skill_roots(
+        spec, explicit_roots=explicit_roots, local_dir=local_dir, cache_dir=cache_dir
+    )
+    if not roots:
+        return None
+    return SkillRuntime(LocalSkillSource(skill_roots={ref: str(p) for ref, p in roots.items()}))
+
+
+def compose_engine(
+    spec: HarnessSpec,
+    *,
+    reasoner: Any | None = None,
+    explicit_roots: dict[str, str | Path] | None = None,
+    local_dir: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+    **engine_kwargs: Any,
+) -> Any:
+    """一步装配：Revision spec → Skill 解析 → ManagedLangGraphEngine。
+
+    其余引擎参数（context_engine / memory_runtime / event_sink …）经
+    ``engine_kwargs`` 透传。返回 ``(engine, warnings)`` 前调用方通常只需要
+    engine；warnings 见 :func:`resolve_skill_roots`，此处经
+    ``engine.skill_warnings`` 附带。
+    """
+    from ksadk.harness.engine.langgraph import ManagedLangGraphEngine
+
+    roots, warnings = resolve_skill_roots(
+        spec, explicit_roots=explicit_roots, local_dir=local_dir, cache_dir=cache_dir
+    )
+    skill_runtime = (
+        SkillRuntime(LocalSkillSource(skill_roots={ref: str(p) for ref, p in roots.items()}))
+        if roots
+        else None
+    )
+    engine = ManagedLangGraphEngine(
+        reasoner=reasoner, skill_runtime=skill_runtime, **engine_kwargs
+    )
+    engine.skill_warnings = warnings  # type: ignore[attr-defined]
+    return engine
+
+
+# ------------------------------------------------------------- 内部解析
+
+
+def _resolve_local_root(local_dir: str | Path | None) -> Path | None:
+    if local_dir is not None:
+        return Path(local_dir)
+    env = os.getenv("KSADK_LOCAL_SKILLS_DIR", "").strip()
+    return Path(env) if env else None
+
+
+def _build_store(cache_dir: str | Path | None) -> Any | None:
+    if cache_dir is not None:
+        from ksadk.skills.package_store import PackageStore
+
+        return PackageStore(cache_dir=cache_dir)
+    env = os.getenv("KSADK_SKILL_CACHE_DIR", "").strip()
+    if not env:
+        return None
+    from ksadk.skills.package_store import PackageStore
+
+    return PackageStore(cache_dir=env)
+
+
+def _find_local_root(local_root: Path | None, ref: str) -> Path | None:
+    if local_root is None or not local_root.is_dir():
+        return None
+    name, version = parse_skill_ref(ref)
+    for suffix in _LOCAL_DIR_SUFFIXES:
+        dirname = suffix.format(version=version) if version else ("" if suffix else "")
+        if not version and suffix:
+            continue
+        candidate = local_root / f"{name}{dirname}"
+        if (candidate / "SKILL.md").is_file():
+            return candidate
+    # frontmatter name 兜底：目录名任意但 SKILL.md name 匹配。
+    from ksadk.skills.loader import load_local_skill
+
+    for child in sorted(local_root.iterdir()):
+        if child.is_dir() and (child / "SKILL.md").is_file():
+            try:
+                if load_local_skill(child).name == name:
+                    return child
+            except Exception:  # noqa: BLE001 - 坏包跳过
+                continue
+    return None
+
+
+def _find_cached_root(store: Any | None, ref: str) -> Path | None:
+    if store is None:
+        return None
+    from ksadk.skills.models import SkillRef
+
+    name, version = parse_skill_ref(ref)
+    try:
+        package = store.get_cached(
+            SkillRef(skill_id=name, version=version, name=name)
+        )
+    except Exception:  # noqa: BLE001 - 缓存损坏视为未命中
+        return None
+    return package.root_dir if package is not None else None
+
+
+__all__ = [
+    "SkillResolutionError",
+    "build_skill_runtime",
+    "compose_engine",
+    "parse_skill_ref",
+    "resolve_skill_roots",
+]