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

ksadk/studio/resource_binding_validation.py

@@ -0,0 +1,77 @@
+"""Static resource checks shared by Studio validation and the actual Build entry."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
+from ksadk.resource_runtime.snapshots import MemoryRecallPolicy
+from ksadk.studio.contracts import Diagnostic, DiagnosticSeverity, MemorySpec
+from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_connections import ResourceConnectionRepository
+
+
+def resource_binding_diagnostics(
+    bindings: Sequence[Any],
+    memory: MemorySpec | None,
+    connections: ResourceConnectionRepository,
+) -> list[Diagnostic]:
+    diagnostics = []
+    for index, binding in enumerate(bindings):
+        if not binding.enabled:
+            continue
+        config = resource_plugin_config(
+            binding.plugin_ref,
+            binding.ecosystem,
+            binding.config,
+            enabled=True,
+        )
+        if config is None:
+            continue
+        field = f"spec.bindings.plugins[{index}].config"
+        try:
+            connection = connections.get(config.binding.connection_ref)
+            # Only confirm referenced secrets exist; no network or identity claims.
+            connections.resolve_credentials(connection.target)
+        except StudioError as error:
+            diagnostics.append(
+                Diagnostic(
+                    severity=DiagnosticSeverity.ERROR,
+                    code=error.code,
+                    message=error.message,
+                    field=field + ".binding.connectionRef",
+                )
+            )
+        if (
+            config.binding.resource.kind == "memory-instance"
+            and memory is not None
+            and memory.enabled
+        ):
+            if memory.provider_ref != f"binding://{config.binding.id}":
+                diagnostics.append(
+                    Diagnostic(
+                        severity=DiagnosticSeverity.ERROR,
+                        code="MEMORY_BINDING_MISMATCH",
+                        message="记忆策略必须引用当前记忆插件绑定",
+                        field="spec.memory.providerRef",
+                    )
+                )
+            try:
+                MemoryRecallPolicy.model_validate(memory.recall.model_dump(exclude={"enabled"}))
+            except ValueError:
+                diagnostics.append(
+                    Diagnostic(
+                        severity=DiagnosticSeverity.ERROR,
+                        code="MEMORY_SEARCH_POLICY_UNSUPPORTED",
+                        message="记忆后端不支持当前召回阈值或预算，请调整策略",
+                        field="spec.memory.recall",
+                    )
+                )
+        diagnostics.append(
+            Diagnostic(
+                severity=DiagnosticSeverity.WARNING,
+                code="RESOURCE_AUTHORITY_UNVERIFIED",
+                message="本次仅校验连接声明与凭证引用，尚未验证平台主体和资源权限",
+                field=field + ".binding",
+            )
+        )
+    return diagnostics

ksadk/studio/resource_build_admission.py

@@ -0,0 +1,196 @@
+"""Trusted admission input for immutable platform-resource Build materialization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Protocol
+
+from ksadk.plugins.bridges.dsh import DshProfileBuildSnapshot
+from ksadk.resource_runtime.contracts import ResourceConfig
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
+from ksadk.resource_runtime.snapshots import (
+    FrozenResourceBinding,
+    MemoryRecallPolicy,
+    ResourceSnapshot,
+)
+from ksadk.studio.capabilities import canonical_json, sha256_digest
+from ksadk.studio.contracts import AgentDraft, MemorySpec, NativePluginBinding
+from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_authority import (
+    VerifiedResourceAuthority,
+    resource_allowed_operations,
+)
+from ksadk.studio.resource_build_materializer import materialize_resource_build
+from ksadk.studio.resource_connections import ResourceConnectionRepository
+
+_RESOURCE_BUNDLES = {
+    "knowledge-base": "@kingsoftcloud/dsh-knowledge",
+    "memory-instance": "@kingsoftcloud/dsh-memory",
+    "skill-space": "@kingsoftcloud/dsh-skill-center",
+}
+
+
+class ResourceAuthority(Protocol):
+    def admit(
+        self,
+        config: ResourceConfig,
+        *,
+        expected_connection_revision: int | None = None,
+    ) -> VerifiedResourceAuthority: ...
+
+
+@dataclass(frozen=True)
+class AdmittedResourceBuild:
+    """Credential-free snapshot plus private materialization dependencies."""
+
+    snapshot: ResourceSnapshot
+    bindings: tuple[NativePluginBinding, ...]
+    memory: MemorySpec
+    connections: ResourceConnectionRepository = field(repr=False, compare=False)
+
+    def materialize(self, directory: Path):
+        return materialize_resource_build(
+            directory,
+            bindings=self.bindings,
+            memory=self.memory,
+            admitted_snapshot=self.snapshot,
+            connections=self.connections,
+        )
+
+
+def admit_resource_build(
+    draft: AgentDraft,
+    *,
+    authority: ResourceAuthority | None,
+    connections: ResourceConnectionRepository,
+    dsh_profile: DshProfileBuildSnapshot | None,
+) -> AdmittedResourceBuild | None:
+    """Admit enabled official resources without trusting browser-supplied identity."""
+
+    selected: list[tuple[NativePluginBinding, ResourceConfig]] = []
+    for binding in draft.spec.bindings.plugins:
+        if not binding.enabled:
+            continue
+        config = resource_plugin_config(
+            binding.plugin_ref,
+            binding.ecosystem,
+            binding.config,
+            enabled=True,
+        )
+        if config is not None:
+            selected.append((binding, config))
+    if not selected:
+        return None
+    if authority is None:
+        raise StudioError(
+            "RESOURCE_AUTHORITY_REQUIRED",
+            "平台资源 Build 需要宿主配置可信身份与权限校验",
+            status_code=503,
+            field="spec.bindings.plugins",
+        )
+    if dsh_profile is None:
+        raise StudioError(
+            "RESOURCE_BUILD_PROFILE_REQUIRED",
+            "平台资源 Build 需要锁定当前 DSH Profile 安装快照",
+            status_code=503,
+            field="spec.bindings.plugins",
+        )
+
+    required_bundles = {
+        _RESOURCE_BUNDLES[config.binding.resource.kind]
+        for _, config in selected
+    }
+    missing_bundles = sorted(required_bundles - set(dsh_profile.projection.bundles))
+    if missing_bundles:
+        raise StudioError(
+            "RESOURCE_PLUGIN_NOT_INSTALLED",
+            "当前 DSH Profile 未安装并启用所绑定的平台资源插件",
+            status_code=409,
+            field="spec.bindings.plugins",
+            details={"missingBundles": missing_bundles},
+        )
+
+    frozen: list[FrozenResourceBinding] = []
+    for binding, config in selected:
+        record = connections.get(config.binding.connection_ref)
+        grant = authority.admit(config, expected_connection_revision=record.revision)
+        current = connections.get(config.binding.connection_ref)
+        if current != record:
+            raise StudioError(
+                "RESOURCE_CONNECTION_CHANGED",
+                "资源准入期间连接发生变化，请重新构建",
+                status_code=409,
+            )
+        if (
+            grant.connection_ref != record.target.connection_ref
+            or grant.connection_revision != record.revision
+            or grant.tenant_ref != record.target.tenant_ref
+            or grant.resource_principal_ref != record.target.principal_ref
+            or grant.resource != config.binding.resource
+            or grant.data_endpoint != record.target.endpoint
+            or grant.expires_at <= datetime.now(timezone.utc)
+            or tuple(grant.allowed_operations) != resource_allowed_operations(config)
+        ):
+            raise StudioError(
+                "RESOURCE_AUTHORITY_INVALID",
+                "平台资源准入结果与当前绑定不一致",
+                status_code=409,
+                field="spec.bindings.plugins",
+            )
+        frozen.append(
+            FrozenResourceBinding(
+                config=config,
+                connection=record.target,
+                connection_revision=record.revision,
+                memory_recall=(
+                    MemoryRecallPolicy.model_validate(
+                        draft.spec.memory.recall.model_dump(exclude={"enabled"})
+                    )
+                    if config.binding.resource.kind == "memory-instance"
+                    and draft.spec.memory.enabled
+                    else None
+                ),
+            )
+        )
+
+    native_lock = [
+        {
+            "pluginRef": binding.plugin_ref,
+            "ecosystem": binding.ecosystem,
+            "snapshotDigest": binding.snapshot_digest,
+            "components": sorted(binding.components),
+            "configDigest": config.digest,
+        }
+        for binding, config in selected
+    ]
+    native_lock.sort(key=lambda item: item["pluginRef"])
+    snapshot = ResourceSnapshot(
+        plugin_lock_digest=sha256_digest(canonical_json(native_lock)),
+        bindings=tuple(frozen),
+        dsh_profile=dsh_profile,
+    )
+    return AdmittedResourceBuild(
+        snapshot=snapshot,
+        bindings=tuple(binding for binding, _ in selected),
+        memory=draft.spec.memory.model_copy(deep=True),
+        connections=connections,
+    )
+
+
+def resource_build_required(draft: AgentDraft) -> bool:
+    return any(
+        binding.enabled
+        and resource_plugin_config(
+            binding.plugin_ref,
+            binding.ecosystem,
+            binding.config,
+            enabled=True,
+        )
+        is not None
+        for binding in draft.spec.bindings.plugins
+    )
+
+
+__all__ = ["AdmittedResourceBuild", "admit_resource_build", "resource_build_required"]

ksadk/studio/resource_build_materializer.py

@@ -0,0 +1,149 @@
+"""Produce resource files inside a caller-owned Build staging directory.
+
+The trusted Build adapter supplies a snapshot after identity, permission, plugin
+lock and engine admission. This producer cannot authorize a browser declaration
+and is deliberately not exposed as a standalone API or artifact repository.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from collections.abc import Sequence
+from dataclasses import replace
+from pathlib import Path
+
+from ksadk.resource_runtime.build_artifacts import ResourceBuildReference, write_resource_build
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
+from ksadk.resource_runtime.snapshots import MemoryRecallPolicy, ResourceSnapshot
+from ksadk.skills.models import ContentHash
+from ksadk.skills.package_store import PackageStore, SkillPackageError
+from ksadk.skills.service_client import SkillServiceClient
+from ksadk.studio.contracts import MemorySpec, NativePluginBinding
+from ksadk.studio.resource_connections import ResourceConnectionRepository
+
+
+def materialize_resource_build(
+    directory: Path,
+    *,
+    bindings: Sequence[NativePluginBinding],
+    memory: MemorySpec | None,
+    admitted_snapshot: ResourceSnapshot,
+    connections: ResourceConnectionRepository,
+) -> ResourceBuildReference:
+    """Validate declaration/admission equality, then retain verified pinned bytes.
+
+    Connections are rechecked before and after downloads. No test writes or Skill
+    execution occur, and no credential or download URL enters the saved artifact.
+    The enclosing Build must still lock dependencies and publish atomically.
+    """
+    snapshot = ResourceSnapshot.model_validate(admitted_snapshot.model_dump())
+    if snapshot.dsh_profile is None:
+        raise ValueError("Resource Build requires its admitted DSH profile snapshot")
+    configs = []
+    for value in bindings:
+        binding = NativePluginBinding.model_validate(value.model_dump())
+        if not binding.enabled:
+            continue
+        config = resource_plugin_config(
+            binding.plugin_ref,
+            binding.ecosystem,
+            binding.config,
+            enabled=True,
+        )
+        if config is not None:
+            configs.append(config)
+    if len(configs) != len(snapshot.bindings) or {
+        item.binding.id: item.digest for item in configs
+    } != {item.config.binding.id: item.config.digest for item in snapshot.bindings}:
+        raise ValueError("Resource declaration does not match admitted Build snapshot")
+    credentials = {}
+    for frozen in snapshot.bindings:
+        config = frozen.config
+        if config.include_public:
+            raise ValueError("Public Skill Build admission is not implemented")
+        if config.execution_mode == "isolated" and frozen.skill_execution is None:
+            raise ValueError("Isolated Skill Build requires an admitted execution target")
+        recall = None
+        if config.binding.resource.kind == "memory-instance" and memory and memory.enabled:
+            if memory.provider_ref != f"binding://{config.binding.id}":
+                raise ValueError("Memory policy does not match admitted binding")
+            recall = MemoryRecallPolicy.model_validate(
+                memory.recall.model_dump(exclude={"enabled"})
+            )
+        if frozen.memory_recall != recall:
+            raise ValueError("Memory recall policy does not match admitted Build snapshot")
+        credentials[config.binding.id] = connections.resolve_credentials(
+            frozen.connection,
+            expected_revision=frozen.connection_revision,
+        )
+        if frozen.skill_execution is not None:
+            connections.resolve_credentials(frozen.skill_execution.connection)
+
+    directory = Path(directory)
+    if directory.exists():
+        raise FileExistsError("Resource Build staging destination already exists")
+    directory.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".resource-packages-", dir=directory.parent) as cache:
+        store = PackageStore(Path(cache), namespace=snapshot.digest, require_hash=True)
+        packages = {}
+        for frozen in snapshot.bindings:
+            config = frozen.config
+            if (
+                config.binding.resource.kind != "skill-space"
+                or config.selection_mode == "discovery"
+                or not config.selected_skills
+            ):
+                continue
+            secret = credentials[config.binding.id]
+            if secret.session_token is not None:
+                raise ValueError("Skill client does not support STS Build downloads")
+
+            def reveal(value):
+                return value.get_secret_value() if value is not None else ""
+
+            client = SkillServiceClient(
+                base_url=frozen.connection.endpoint,
+                region=config.binding.resource.region,
+                access_key=reveal(secret.access_key),
+                secret_key=reveal(secret.secret_key),
+                token=reveal(secret.token),
+                allow_env_fallback=False,
+            )
+            try:
+                listing = client.list_skills_by_space_id(config.binding.resource.id)
+                if listing.space_id != config.binding.resource.id:
+                    raise SkillPackageError("Skill catalog does not match admitted space")
+                catalog = {}
+                for ref in listing.active_skills(allow_partial=True):
+                    if ref.skill_id in catalog:
+                        raise SkillPackageError("Skill catalog contains duplicate identities")
+                    catalog[ref.skill_id] = ref
+                selected_packages = []
+                for selected in config.selected_skills:
+                    ref = catalog.get(selected.skill_id)
+                    if ref is None:
+                        raise SkillPackageError("Selected Skill is absent from admitted catalog")
+                    # The catalog establishes space membership; the selected version
+                    # and hash establish package identity, including historical pins.
+                    algorithm, digest = selected.content_hash.split(":", 1)
+                    ref = replace(
+                        ref,
+                        version_id=selected.version_id,
+                        version="",
+                        archive_uri="",
+                        content_hash=ContentHash(algorithm, digest),
+                    )
+                    selected_packages.append(
+                        store.store_archive(ref, client.download_skill_archive(ref))
+                    )
+                packages[config.binding.id] = selected_packages
+            finally:
+                client.close()
+        for frozen in snapshot.bindings:
+            connections.resolve_credentials(
+                frozen.connection,
+                expected_revision=frozen.connection_revision,
+            )
+            if frozen.skill_execution is not None:
+                connections.resolve_credentials(frozen.skill_execution.connection)
+        return write_resource_build(directory, snapshot, packages)

ksadk/studio/resource_catalog.py

@@ -20,6 +20,13 @@ from pydantic import ValidationError
 
 from ksadk.cli.model_catalog import fetch_provider_model_catalog
 from ksadk.conversations.model_context import normalize_model_metadata
+from ksadk.plugins.providers.dsh_capabilities import (
+    DshProfileCapabilityDescriptor,
+)
+from ksadk.plugins.providers.dsh_mcp import (
+    DSH_PROFILE_TOOL_PERMISSION,
+    dsh_harness_tool_alias,
+)
 from ksadk.studio.capabilities import (
     LocalCapabilityResolver,
     canonical_json,
@@ -162,6 +169,7 @@ class LocalResourceCatalog:
         self.skill_discovery = SkillDiscoveryService(workspace)
         self.python_tool_inspector = PythonToolInspector(workspace)
         self._provider_models: dict[str, ResourceDescriptor] = {}
+        self._dsh_mcp_resources: dict[str, ResourceDescriptor] = {}
         # api_base -> (monotonic_ts, descriptors, source)，见 discover_provider_models。
         self._provider_catalog_cache: dict[
             str, tuple[float, builtins.list[ResourceDescriptor], str]
@@ -274,6 +282,7 @@ class LocalResourceCatalog:
     ) -> builtins.list[ResourceDescriptor]:
         candidates = [
             *self._provider_models.values(),
+            *self._dsh_mcp_resources.values(),
             *self._builtin_tools(),
             *self._persisted("models"),
             *self._persisted("mcp"),
@@ -420,6 +429,77 @@ class LocalResourceCatalog:
             )
         return found
 
+    def replace_dsh_profile_mcp(
+        self,
+        descriptor: DshProfileCapabilityDescriptor,
+    ) -> ResourceDescriptor:
+        """Publish one live DSH Profile as a bindable, credential-free MCP.
+
+        This entry is intentionally memory-only.  The stable descriptor is
+        compiled into a Build when selected, while its endpoint and bearer
+        token are acquired later by the PluginHost runtime.
+        """
+
+        name = f"dsh-profile-{resource_slug(descriptor.profile)}"
+        server = MCPServerRef(
+            name=name,
+            version=descriptor.dsh_version,
+            transport="http",
+            materialization="dsh-profile",
+            profile=descriptor.profile,
+            profile_digest=descriptor.profile_digest,
+            descriptor_digest=descriptor.descriptor_digest,
+            inventory_digest=descriptor.inventory_digest,
+        )
+        resolved = self.resolver.resolve_mcp(server)
+        resolved["discoveredTools"] = [
+            ToolContract(
+                name=tool.name,
+                version=descriptor.dsh_version,
+                description=tool.description,
+                input_schema=tool.input_schema,
+                permissions=["network:mcp", DSH_PROFILE_TOOL_PERMISSION],
+                timeout_seconds=60,
+                side_effect="external",
+                approval="policy",
+                executor="mcp",
+                mcp_server=name,
+                group="dsh",
+                boundary="dsh-profile-sidecar",
+                backend="mcp",
+            ).model_dump(by_alias=True, exclude_none=True, mode="json")
+            for tool in descriptor.tools
+        ]
+        stable_id = resource_id("mcp", "provider", name, descriptor.dsh_version)
+        snapshot_suffix = descriptor.descriptor_digest.removeprefix("sha256:")[:20]
+        resource = ResourceDescriptor(
+            resource_id=f"{stable_id}:{snapshot_suffix}",
+            kind="mcp",
+            name=name,
+            display_name=f"DSH Profile: {descriptor.profile}",
+            version=descriptor.dsh_version,
+            digest=str(resolved["digest"]),
+            source="provider",
+            status="ready",
+            description="DSH/Cordis Profile tools exposed through a runtime MCP lease",
+            category="dsh",
+            contract=resolved,
+            health={
+                "profileDigest": descriptor.profile_digest,
+                "descriptorDigest": descriptor.descriptor_digest,
+                "inventoryDigest": descriptor.inventory_digest,
+            },
+        )
+        self._dsh_mcp_resources = {resource.resource_id: resource}
+        return resource
+
+    def clear_dsh_profile_mcp(self) -> None:
+        """Withdraw stale Profile resources before the DSH generation changes."""
+
+        # Copy-on-write keeps concurrent catalog readers on a complete old or
+        # new snapshot instead of mutating a dict while it is being iterated.
+        self._dsh_mcp_resources = {}
+
     def create_model_profile(
         self,
         *,
@@ -455,6 +535,13 @@ class LocalResourceCatalog:
         description: str,
         server: MCPServerRef,
     ) -> ResourceDescriptor:
+        if server.materialization == "dsh-profile":
+            raise StudioError(
+                "DSH_MCP_MANAGED_RESOURCE_REQUIRED",
+                "DSH Profile MCP 只能由当前受管理 Profile 发布",
+                status_code=422,
+                field="server.materialization",
+            )
         require_exact_version(server.version, field="version")
         resolved = self.resolver.resolve_mcp(server)
         descriptor = self._descriptor(
@@ -638,6 +725,13 @@ class LocalResourceCatalog:
         detail: str | None = None,
     ) -> ResourceDescriptor:
         descriptor = self.get(resource)
+        if descriptor.kind != "mcp" or descriptor.source != "local":
+            raise StudioError(
+                "RESOURCE_KIND_INVALID",
+                "只有本地 MCP Resource 可以保存探测结果",
+                status_code=422,
+                details={"resourceId": resource},
+            )
         updated = descriptor.model_copy(deep=True)
         updated.status = "unhealthy"
         updated.health = {
@@ -767,17 +861,33 @@ class LocalResourceCatalog:
             if not binding.enabled:
                 continue
             descriptor = self._ready_binding(binding, expected_kind="mcp")
+            raw_filter = binding.config.get("toolFilter")
+            tool_filter = (
+                {str(item).strip() for item in raw_filter} if isinstance(raw_filter, list) else None
+            )
+            raw_prefix = binding.config.get("toolNamePrefix")
+            prefix = raw_prefix.strip() if isinstance(raw_prefix, str) else ""
+            dynamic_dsh = descriptor.contract.get("materialization") == "dsh-profile"
             for payload in descriptor.contract.get("discoveredTools") or []:
                 tool = ToolContract.model_validate(payload)
+                if tool_filter is not None and tool.name not in tool_filter:
+                    continue
                 approval = self._effective_approval(
                     tool,
                     bindings.policy_template,
                     binding,
                 )
+                name = (
+                    dsh_harness_tool_alias(tool.name, prefix)
+                    if dynamic_dsh
+                    else f"{prefix}_{tool.name}"
+                    if prefix
+                    else tool.name
+                )
                 tools.append(
                     cast(
                         ToolContract,
-                        tool.model_copy(update={"approval": approval}),
+                        tool.model_copy(update={"name": name, "approval": approval}),
                     )
                 )
         return tools
@@ -1113,12 +1223,36 @@ class LocalResourceCatalog:
             )
 
     def _persisted(self, directory: str) -> Iterable[ResourceDescriptor]:
+        expected_kind = {
+            "models": "model",
+            "mcp": "mcp",
+            "tools": "tool",
+        }.get(directory)
+        if expected_kind is None:
+            return
         root = self.workspace.resolve(Path(".agentkit/catalog") / directory)
         for path in sorted(root.glob("*.yaml")):
             try:
-                yield ResourceDescriptor.model_validate(load_yaml_file(path))
+                descriptor = ResourceDescriptor.model_validate(load_yaml_file(path))
             except (StudioError, ValidationError):
                 continue
+            # Provider resources are live, memory-only projections. Never let
+            # a stale or forged workspace YAML shadow their lifecycle fence.
+            if descriptor.source != "local":
+                continue
+            if descriptor.kind != expected_kind:
+                continue
+            expected_id = resource_id(
+                descriptor.kind,
+                "local",
+                descriptor.name,
+                descriptor.version,
+            )
+            if descriptor.resource_id != expected_id:
+                continue
+            if descriptor.contract.get("materialization") == "dsh-profile":
+                continue
+            yield descriptor
 
     def _persist_descriptor(
         self,
@@ -1152,6 +1286,13 @@ class LocalResourceCatalog:
     def delete_resource(self, resource_id: str) -> None:
         """Remove a persisted catalog resource (model/tool/mcp/skill) by id."""
         descriptor = self.get(resource_id)
+        if descriptor.source != "local":
+            raise StudioError(
+                "RESOURCE_DELETE_FORBIDDEN",
+                "只有本地持久化 Resource 可以删除",
+                status_code=422,
+                details={"resourceId": resource_id, "source": descriptor.source},
+            )
         kind = descriptor.kind
         if kind == "skill":
             # Skill 以目录形式安装在 capabilities/skills/{name}