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

ksadk/harness/skill_feedback.py

@@ -0,0 +1,123 @@
+"""Project Skill disclosure events into feedback suitable for Studio/Skill Service.
+
+The Harness does not install, publish or rank marketplace Skills.  It does own the
+runtime evidence: which bound Skill was recommended, which levels the model loaded,
+and whether disclosure calls failed.  This module exposes that evidence without
+including Skill content, tool results or user prompts.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from ksadk.harness.events import EventType, RuntimeEvent
+
+_SKILL_TOOLS = {
+    "skill_read_manifest": 1,
+    "skill_read_instructions": 2,
+    "skill_read_resource": 3,
+}
+
+
+def skill_feedback(
+    events: Sequence[RuntimeEvent],
+    *,
+    bound_skill_refs: Sequence[str] = (),
+) -> dict[str, Any]:
+    """Return metadata-only disclosure and failure metrics grouped by Skill ref."""
+
+    state: dict[str, dict[str, Any]] = {
+        ref: _new_item(ref) for ref in dict.fromkeys(bound_skill_refs) if ref
+    }
+    begins: dict[str, tuple[str, str]] = {}
+
+    for event in sorted(events, key=lambda item: (item.timestamp, item.seq_id)):
+        payload = event.payload
+        if event.event_type == EventType.TOOL_CALL_BEGIN:
+            name = str(payload.get("name") or "")
+            if name not in _SKILL_TOOLS:
+                continue
+            args = payload.get("args") or payload.get("arguments") or {}
+            skill_ref = str(args.get("skill_id") or "") if isinstance(args, dict) else ""
+            begins[str(payload.get("call_id") or "")] = (name, skill_ref)
+            if skill_ref:
+                item = state.setdefault(skill_ref, _new_item(skill_ref))
+                item["disclosure_calls"] += 1
+            continue
+
+        if event.event_type == EventType.TOOL_CALL_END:
+            call_id = str(payload.get("call_id") or "")
+            name, skill_ref = begins.pop(
+                call_id,
+                (str(payload.get("name") or ""), ""),
+            )
+            if name not in _SKILL_TOOLS or not skill_ref:
+                continue
+            item = state.setdefault(skill_ref, _new_item(skill_ref))
+            if payload.get("error"):
+                item["failed_calls"] += 1
+            else:
+                item["successful_calls"] += 1
+            continue
+
+        if event.event_type != EventType.SKILL_DISCLOSED:
+            continue
+        skill_ref = str(payload.get("skill_ref") or "")
+        if not skill_ref:
+            continue
+        item = state.setdefault(skill_ref, _new_item(skill_ref))
+        level = int(payload.get("level") or 0)
+        if level in {1, 2, 3} and level not in item["levels_reached"]:
+            item["levels_reached"].append(level)
+            item["levels_reached"].sort()
+        item["max_level"] = max(item["max_level"], level)
+        item["recommended"] = item["recommended"] or bool(payload.get("recommended"))
+        item["disclosed_bytes"] += max(0, int(payload.get("size_bytes") or 0))
+        item["resource_reads"] += int(level == 3)
+
+    items = []
+    for skill_ref in sorted(state):
+        item = state[skill_ref]
+        item["used"] = item["max_level"] > 0
+        item["completed_progression"] = item["levels_reached"] == [1, 2, 3]
+        item["invalid_call_rate"] = _ratio(
+            item["failed_calls"], item["successful_calls"] + item["failed_calls"]
+        )
+        item["deep_disclosure_without_resource"] = (
+            item["max_level"] == 2 and item["resource_reads"] == 0
+        )
+        items.append(item)
+
+    return {
+        "schemaVersion": 1,
+        "boundCount": len(tuple(dict.fromkeys(ref for ref in bound_skill_refs if ref))),
+        "observedCount": len(items),
+        "usedCount": sum(1 for item in items if item["used"]),
+        "recommendedUsedCount": sum(
+            1 for item in items if item["used"] and item["recommended"]
+        ),
+        "failedCallCount": sum(item["failed_calls"] for item in items),
+        "items": items,
+    }
+
+
+def _new_item(skill_ref: str) -> dict[str, Any]:
+    return {
+        "skill_ref": skill_ref,
+        "recommended": False,
+        "used": False,
+        "levels_reached": [],
+        "max_level": 0,
+        "disclosure_calls": 0,
+        "successful_calls": 0,
+        "failed_calls": 0,
+        "resource_reads": 0,
+        "disclosed_bytes": 0,
+    }
+
+
+def _ratio(numerator: int, denominator: int) -> float:
+    return round(numerator / denominator, 6) if denominator else 0.0
+
+
+__all__ = ["skill_feedback"]

ksadk/harness/skill_matrix.py

@@ -0,0 +1,233 @@
+"""Skill Runtime 解析与发布就绪矩阵。
+
+这里只检查 Revision 已绑定 Skill 的运行时消费条件，不承担安装、升级、市场
+推荐或版本治理。报告可供 CI/Studio 使用，并刻意不包含 Skill 正文、本地绝对
+路径或缓存实现细节。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ksadk.harness.skill_composition import (
+    SkillResolutionError,
+    parse_skill_ref,
+    resolve_skill_roots,
+)
+from ksadk.harness.spec import HarnessSpec
+from ksadk.skills.loader import load_local_skill
+
+
+@dataclass(frozen=True)
+class SkillMatrixRow:
+    skill_ref: str
+    status: str
+    required: bool
+    load_policy: str
+    findings: tuple[dict[str, str], ...] = ()
+    capabilities: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SkillMatrixReport:
+    schema_version: int
+    status: str
+    rows: tuple[SkillMatrixRow, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        counts = {
+            state: sum(1 for row in self.rows if row.status == state)
+            for state in ("ready", "warning", "blocked")
+        }
+        return {
+            "schemaVersion": self.schema_version,
+            "status": self.status,
+            "counts": counts,
+            "rows": [
+                {
+                    "skillRef": row.skill_ref,
+                    "status": row.status,
+                    "required": row.required,
+                    "loadPolicy": row.load_policy,
+                    "findings": [dict(item) for item in row.findings],
+                    "capabilities": dict(row.capabilities),
+                }
+                for row in self.rows
+            ],
+        }
+
+
+def run_skill_matrix(
+    spec: HarnessSpec,
+    *,
+    explicit_roots: dict[str, str | Path] | None = None,
+    local_dir: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+) -> SkillMatrixReport:
+    """检查 Skill 引用、运行时内容解析与 Manifest 可加载性。"""
+
+    rows: list[SkillMatrixRow] = []
+    for binding in spec.capabilities.skill_bindings:
+        ref = binding.capability_ref
+        findings: list[dict[str, str]] = []
+        try:
+            name, version = parse_skill_ref(ref)
+        except SkillResolutionError as exc:
+            rows.append(
+                _failed_row(binding, "skill.reference", str(exc))
+            )
+            continue
+
+        fixed = bool(version)
+        findings.append(
+            {
+                "rule": "skill.version.pinned",
+                "status": "passed" if fixed else "failed",
+                "detail": "fixed version reference" if fixed else "version is not pinned",
+            }
+        )
+
+        if binding.load_policy == "explicit":
+            findings.append(
+                {
+                    "rule": "skill.runtime.visibility",
+                    "status": "passed",
+                    "detail": "explicit binding is hidden from the model loop",
+                }
+            )
+            status = "ready" if fixed else ("blocked" if binding.required else "warning")
+            rows.append(
+                SkillMatrixRow(
+                    skill_ref=ref,
+                    status=status,
+                    required=binding.required,
+                    load_policy=binding.load_policy,
+                    findings=tuple(findings),
+                    capabilities={"resolved": False, "manifestValid": False, "name": name},
+                )
+            )
+            continue
+
+        single_spec = spec.model_copy(
+            update={
+                "capabilities": spec.capabilities.model_copy(
+                    update={"skill_bindings": (binding,)}
+                )
+            }
+        )
+        try:
+            roots, warnings = resolve_skill_roots(
+                single_spec,
+                explicit_roots=explicit_roots,
+                local_dir=local_dir,
+                cache_dir=cache_dir,
+            )
+        except SkillResolutionError as exc:
+            findings.append(
+                {"rule": "skill.content.resolution", "status": "failed", "detail": _safe(exc)}
+            )
+            rows.append(_row(binding, findings, name=name, resolved=False))
+            continue
+
+        root = roots.get(ref)
+        if root is None:
+            findings.append(
+                {
+                    "rule": "skill.content.resolution",
+                    "status": "failed",
+                    "detail": _safe(warnings[0] if warnings else "content unavailable"),
+                }
+            )
+            rows.append(_row(binding, findings, name=name, resolved=False))
+            continue
+
+        findings.append(
+            {
+                "rule": "skill.content.resolution",
+                "status": "passed",
+                "detail": "validated local content resolved",
+            }
+        )
+        try:
+            loaded = load_local_skill(root)
+        except Exception as exc:  # noqa: BLE001 - stable matrix failure
+            findings.append(
+                {"rule": "skill.manifest", "status": "failed", "detail": _safe(exc)}
+            )
+            rows.append(_row(binding, findings, name=name, resolved=True))
+            continue
+        findings.append(
+            {
+                "rule": "skill.manifest",
+                "status": "passed",
+                "detail": "manifest loaded",
+            }
+        )
+        rows.append(
+            _row(
+                binding,
+                findings,
+                name=loaded.name,
+                resolved=True,
+                manifest_valid=True,
+            )
+        )
+
+    overall = "ready"
+    if any(row.status == "blocked" for row in rows):
+        overall = "blocked"
+    elif any(row.status == "warning" for row in rows):
+        overall = "warning"
+    return SkillMatrixReport(schema_version=1, status=overall, rows=tuple(rows))
+
+
+def _row(
+    binding: Any,
+    findings: list[dict[str, str]],
+    *,
+    name: str,
+    resolved: bool,
+    manifest_valid: bool = False,
+) -> SkillMatrixRow:
+    failed = any(item["status"] == "failed" for item in findings)
+    status = ("blocked" if binding.required else "warning") if failed else "ready"
+    return SkillMatrixRow(
+        skill_ref=binding.capability_ref,
+        status=status,
+        required=binding.required,
+        load_policy=binding.load_policy,
+        findings=tuple(findings),
+        capabilities={
+            "resolved": resolved,
+            "manifestValid": manifest_valid,
+            "progressiveDisclosure": binding.load_policy == "on_demand",
+            "name": name,
+        },
+    )
+
+
+def _failed_row(binding: Any, rule: str, detail: str) -> SkillMatrixRow:
+    return _row(
+        binding,
+        [{"rule": rule, "status": "failed", "detail": _safe(detail)}],
+        name="",
+        resolved=False,
+    )
+
+
+def _safe(value: object) -> str:
+    # 绝对路径可能暴露宿主目录；报告只保留稳定错误类别和文件名。
+    text = str(value or "")[:512]
+    for token in text.split():
+        if token.startswith("/"):
+            text = text.replace(token, Path(token.rstrip(":")).name)
+    return text
+
+
+__all__ = [
+    "SkillMatrixReport",
+    "SkillMatrixRow",
+    "run_skill_matrix",
+]

ksadk/harness/skill_runtime.py

@@ -0,0 +1,259 @@
+"""Harness Skill 渐进披露（plan §10.4）。
+
+四级披露：Level 0 名称+一句话 → Level 1 Manifest → Level 2 完整 SKILL.md →
+Level 3 引用资源仅执行时加载。Skill 管理面（包校验/安全解压/Loader）留在
+现有 Skill 子系统，本模块只负责披露层级控制。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from ksadk.skills.loader import load_local_skill
+
+SKILL_MANIFEST_TOOL = "skill_read_manifest"
+SKILL_INSTRUCTIONS_TOOL = "skill_read_instructions"
+SKILL_RESOURCE_TOOL = "skill_read_resource"
+
+
+class SkillDisclosureError(RuntimeError):
+    """越级披露（未先读过 Level 1/2 就要求 Level 3 正文/资源）。"""
+
+
+@dataclass(frozen=True)
+class SkillManifest:
+    """Level 1：Manifest + 使用条件 + 权限需求。"""
+
+    name: str
+    summary: str
+    conditions: str = ""
+    required_tools: tuple[str, ...] = ()
+
+
+class SkillSource(Protocol):
+    """Skill 内容源（宿主注入，对接现有 Skill Loader）。"""
+
+    def manifest(self, skill_id: str) -> SkillManifest: ...
+
+    def full_text(self, skill_id: str) -> str: ...
+
+    def resource(self, skill_id: str, resource_ref: str) -> bytes: ...
+
+
+@dataclass(frozen=True)
+class SkillDisclosureTool:
+    """暴露给模型的只读披露工具描述；执行仍由默认 Agent Loop 接管。"""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    source: str = "harness:skill-disclosure"
+
+    @property
+    def openai_schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+class LocalSkillSource:
+    """把已校验、已解压的本地 Skill 目录适配为披露内容源。
+
+    ``skill_roots`` 的键应是 Revision 中固定版本的完整 Skill 引用。包下载、
+    校验和安全解压仍由 ``ksadk.skills`` 负责，本类不承担管理面职责。
+    """
+
+    def __init__(self, skill_roots: dict[str, str | Path]) -> None:
+        self._roots = {skill_id: Path(root).resolve() for skill_id, root in skill_roots.items()}
+
+    def _root(self, skill_id: str) -> Path:
+        try:
+            return self._roots[skill_id]
+        except KeyError:
+            raise KeyError(f"skill {skill_id!r} 未绑定本地内容目录") from None
+
+    def manifest(self, skill_id: str) -> SkillManifest:
+        skill = load_local_skill(self._root(skill_id))
+        return SkillManifest(name=skill.name, summary=skill.description or skill.name)
+
+    def full_text(self, skill_id: str) -> str:
+        return load_local_skill(self._root(skill_id)).body
+
+    def resource(self, skill_id: str, resource_ref: str) -> bytes:
+        root = self._root(skill_id)
+        candidate = (root / resource_ref).resolve()
+        if candidate == root or not candidate.is_relative_to(root):
+            raise SkillDisclosureError(f"skill {skill_id} 资源路径越界: {resource_ref!r}")
+        if not candidate.is_file():
+            raise FileNotFoundError(f"skill {skill_id} 资源不存在: {resource_ref!r}")
+        return candidate.read_bytes()
+
+
+class SkillRuntime:
+    """渐进披露控制器：记录每个 (run, skill) 已到达的最高层级。"""
+
+    def __init__(self, source: SkillSource) -> None:
+        self._source = source
+        self._levels: dict[tuple[str, str], int] = {}
+
+    def level(self, run_id: str, skill_id: str) -> int:
+        return self._levels.get((run_id, skill_id), 0)
+
+    # ------------------------------------------------------------- 披露
+
+    def level0(self, skill_id: str) -> str:
+        """名称 + 一句话描述（进入上下文的最小信息）。"""
+        return self._source.manifest(skill_id).summary
+
+    def catalog_entry(self, skill_id: str) -> dict[str, str]:
+        """Level 0 的结构化目录项；读取目录不提升披露级别。"""
+        manifest = self._source.manifest(skill_id)
+        return {"skill_id": skill_id, "name": manifest.name, "summary": manifest.summary}
+
+    def recommend(
+        self,
+        skill_ids: tuple[str, ...],
+        *,
+        query: str,
+        limit: int = 5,
+    ) -> tuple[dict[str, str], ...]:
+        """Rank bound Skills without loading L1/L2/L3 content.
+
+        This is deliberately deterministic and metadata-only: it improves discovery
+        while keeping model execution, installation and version selection outside of
+        the recommender.  A zero-score catalog keeps Revision order.
+        """
+        entries = [self.catalog_entry(skill_id) for skill_id in skill_ids]
+        query_terms = _search_terms(query)
+        ranked: list[tuple[float, int, dict[str, str]]] = []
+        for index, entry in enumerate(entries):
+            name_terms = _search_terms(entry["name"])
+            summary_terms = _search_terms(entry["summary"])
+            name_hits = len(query_terms.intersection(name_terms))
+            summary_hits = len(query_terms.intersection(summary_terms))
+            score = float(name_hits * 3 + summary_hits)
+            ranked.append((score, index, entry))
+        ranked.sort(key=lambda item: (-item[0], item[1]))
+        positive = {id(entry) for score, _index, entry in ranked[:limit] if score > 0}
+        return tuple(
+            {
+                **entry,
+                "recommended": "true" if id(entry) in positive else "false",
+                "recommendation_score": f"{score:g}",
+            }
+            for score, _index, entry in ranked
+        )
+
+    def level1(self, run_id: str, skill_id: str) -> SkillManifest:
+        manifest = self._source.manifest(skill_id)
+        self._levels[(run_id, skill_id)] = max(self.level(run_id, skill_id), 1)
+        return manifest
+
+    def level2(self, run_id: str, skill_id: str) -> str:
+        """完整 SKILL.md：必须先读过 Level 1（Manifest）。"""
+        if self.level(run_id, skill_id) < 1:
+            raise SkillDisclosureError(f"skill {skill_id} 须先披露 Level 1 (Manifest) 再读正文")
+        self._levels[(run_id, skill_id)] = 2
+        return self._source.full_text(skill_id)
+
+    def level3(self, run_id: str, skill_id: str, resource_ref: str) -> bytes:
+        """引用资源：仅执行时加载，必须已披露 Level 2。"""
+        if self.level(run_id, skill_id) < 2:
+            raise SkillDisclosureError(f"skill {skill_id} 须先披露 Level 2 (SKILL.md) 再加载资源")
+        instructions = self._source.full_text(skill_id)
+        if resource_ref not in instructions:
+            raise SkillDisclosureError(f"skill {skill_id} 的 SKILL.md 未引用资源 {resource_ref!r}")
+        resource = self._source.resource(skill_id, resource_ref)
+        self._levels[(run_id, skill_id)] = 3
+        return resource
+
+    def clear_run(self, run_id: str) -> None:
+        """Run 关闭后清理披露游标，避免长期进程累积状态。"""
+        for key in [key for key in self._levels if key[0] == run_id]:
+            self._levels.pop(key, None)
+
+    @staticmethod
+    def disclosure_tools() -> tuple[SkillDisclosureTool, ...]:
+        skill_id = {
+            "type": "string",
+            "description": "Revision 已绑定的完整 Skill 引用。",
+        }
+        return (
+            SkillDisclosureTool(
+                name=SKILL_MANIFEST_TOOL,
+                description=(
+                    "读取已绑定 Skill 的 Manifest、适用条件和所需工具。"
+                    "使用 Skill 前必须先调用此工具。"
+                ),
+                parameters={
+                    "type": "object",
+                    "properties": {"skill_id": skill_id},
+                    "required": ["skill_id"],
+                    "additionalProperties": False,
+                },
+            ),
+            SkillDisclosureTool(
+                name=SKILL_INSTRUCTIONS_TOOL,
+                description=("读取 Skill 的完整操作说明。必须先读取同一 Skill 的 Manifest。"),
+                parameters={
+                    "type": "object",
+                    "properties": {"skill_id": skill_id},
+                    "required": ["skill_id"],
+                    "additionalProperties": False,
+                },
+            ),
+            SkillDisclosureTool(
+                name=SKILL_RESOURCE_TOOL,
+                description=("按引用读取 Skill 附属资源。必须先读取同一 Skill 的完整操作说明。"),
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "skill_id": skill_id,
+                        "resource_ref": {
+                            "type": "string",
+                            "description": "SKILL.md 中引用的相对资源路径。",
+                        },
+                    },
+                    "required": ["skill_id", "resource_ref"],
+                    "additionalProperties": False,
+                },
+            ),
+        )
+
+    @staticmethod
+    def content_digest(content: str | bytes) -> str:
+        raw = content.encode("utf-8") if isinstance(content, str) else content
+        return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def _search_terms(value: str) -> set[str]:
+    """Produce small English tokens and CJK bi-grams for metadata matching."""
+    normalized = value.casefold()
+    terms = set(re.findall(r"[a-z0-9][a-z0-9._-]*", normalized))
+    for chunk in re.findall(r"[\u3400-\u9fff]+", normalized):
+        if len(chunk) == 1:
+            terms.add(chunk)
+        else:
+            terms.update(chunk[index : index + 2] for index in range(len(chunk) - 1))
+    return terms
+
+
+__all__ = [
+    "LocalSkillSource",
+    "SKILL_INSTRUCTIONS_TOOL",
+    "SKILL_MANIFEST_TOOL",
+    "SKILL_RESOURCE_TOOL",
+    "SkillDisclosureError",
+    "SkillDisclosureTool",
+    "SkillManifest",
+    "SkillRuntime",
+]