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

ksadk/studio/api_resource_connections.py

@@ -0,0 +1,183 @@
+"""Data-only resource connection configuration under the existing Studio API guard."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+from fastapi import FastAPI, Query
+from pydantic import Field
+
+from ksadk.api.client import AgentEngineClient
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.plugins.dsh_installation_digest import installation_digest
+from ksadk.resource_runtime.snapshots import ConnectionTarget
+from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_connections import (
+    ResourceConnectionDeclaration,
+    ResourceCredentialReferences,
+)
+
+PlatformResourceKind = Literal["knowledge-base", "memory-instance", "skill-space"]
+
+_PLATFORM_RESOURCE_ACTIONS = {
+    "knowledge-base": ("list_knowledge_bases", "knowledge_bases"),
+    "memory-instance": ("list_memory_instances", "memory_instances"),
+    "skill-space": ("list_skill_workspaces", "skill_workspaces"),
+}
+_PLATFORM_RESOURCE_PLUGINS = {
+    "knowledge-base": ("kingsoftcloud.dsh-knowledge", "dsh-knowledge"),
+    "memory-instance": ("kingsoftcloud.dsh-memory", "dsh-memory"),
+    "skill-space": ("kingsoftcloud.dsh-skill-center", "dsh-skill-center"),
+}
+
+
+class SaveResourceConnection(PluginContractModel):
+    expected_revision: int = Field(strict=True, ge=0)
+    connection: ResourceConnectionDeclaration
+
+
+class ValidateResourceBindings(PluginContractModel):
+    expected_revision: int = Field(strict=True, ge=1)
+
+
+def register_resource_connection_routes(app: FastAPI, studio: Any) -> None:
+    @app.get("/api/v1/platform-resources")
+    async def list_platform_resources(kind: PlatformResourceKind):
+        method_name, result_key = _PLATFORM_RESOURCE_ACTIONS[kind]
+        client = AgentEngineClient()
+        try:
+            payload = await getattr(client, method_name)()
+        finally:
+            await client.close()
+        raw_items = payload.get(result_key, [])
+        if not isinstance(raw_items, list) or any(not isinstance(item, dict) for item in raw_items):
+            raise StudioError(
+                "PLATFORM_RESOURCE_RESPONSE_INVALID",
+                "平台资源服务返回了无效列表",
+                status_code=502,
+            )
+        plugin_id, component_id = _PLATFORM_RESOURCE_PLUGINS[kind]
+        bundle_root = (
+            Path(__file__).parents[1]
+            / "plugins"
+            / "providers"
+            / "bundles"
+            / plugin_id.split(".", 1)[1]
+        )
+        connections = await asyncio.to_thread(studio.resource_connections.list)
+        connection_ref = connections[0].target.connection_ref if connections else None
+        return {
+            "kind": kind,
+            "connectionRef": connection_ref,
+            "pluginRef": f"plugin://{plugin_id}@0.1.0",
+            "pluginSnapshotDigest": installation_digest(bundle_root),
+            "componentId": component_id,
+            "items": [
+                {
+                    "id": str(item.get("id") or ""),
+                    "name": str(item.get("name") or item.get("id") or ""),
+                    "region": str(item.get("region") or ""),
+                    "status": str(item.get("status") or "unknown"),
+                    "disabled": bool(item.get("disabled", False)),
+                    "disableReason": str(item.get("disable_reason") or ""),
+                    **(
+                        {"sceneId": str(item.get("scene_id") or "")}
+                        if item.get("scene_id") is not None
+                        else {}
+                    ),
+                }
+                for item in raw_items
+                if item.get("id")
+            ],
+            "total": int(payload.get("total_count") or len(raw_items)),
+        }
+
+    @app.post("/api/v1/resource-connections:bootstrap", status_code=201)
+    async def bootstrap_resource_connection():
+        authority = studio.resource_authority
+        access_key = os.environ.get("KSYUN_ACCESS_KEY", "").strip()
+        secret_key = os.environ.get("KSYUN_SECRET_KEY", "").strip()
+        if authority is None or not access_key or not secret_key:
+            raise StudioError(
+                "RESOURCE_CONNECTION_BOOTSTRAP_UNAVAILABLE",
+                "请先通过 Studio env-file 配置云端签名凭证和控制面地址",
+                status_code=503,
+            )
+        tenant_ref, principal_ref = await asyncio.to_thread(
+            authority.resolve_signed_identity, access_key, secret_key
+        )
+        connection_ref = "ksyun-platform-default"
+        try:
+            existing = await asyncio.to_thread(studio.resource_connections.get, connection_ref)
+        except StudioError as error:
+            if error.status_code != 404:
+                raise
+        else:
+            return {
+                **existing.model_dump(by_alias=True, mode="json"),
+                "validationState": "verified",
+            }
+        declaration = ResourceConnectionDeclaration(
+            label="金山云平台资源",
+            target=ConnectionTarget(
+                connection_ref=connection_ref,
+                tenant_ref=tenant_ref,
+                principal_ref=principal_ref,
+                endpoint=authority.policy.allowed_data_endpoints[0],
+                auth_mode="signed",
+            ),
+            credentials=ResourceCredentialReferences(
+                access_key_ref="env://KSYUN_ACCESS_KEY",
+                secret_key_ref="env://KSYUN_SECRET_KEY",
+            ),
+        )
+        record = await asyncio.to_thread(
+            studio.resource_connections.save, declaration, expected_revision=0
+        )
+        return {
+            **record.model_dump(by_alias=True, mode="json"),
+            "validationState": "verified",
+        }
+
+    @app.get("/api/v1/agents/{agent_id}/resource-bindings/status")
+    async def binding_status(
+        agent_id: str,
+        activation_id: str = Query(alias="activationId", min_length=1, max_length=256),
+    ):
+        return await studio.resource_binding_status(agent_id, activation_id=activation_id)
+
+    @app.post("/api/v1/agents/{agent_id}/resource-bindings/validate")
+    async def validate_bindings(agent_id: str, request: ValidateResourceBindings):
+        return await asyncio.to_thread(
+            studio.validate_resource_bindings,
+            agent_id,
+            expected_revision=request.expected_revision,
+        )
+
+    @app.get("/api/v1/resource-connections")
+    async def list_connections():
+        records = await asyncio.to_thread(studio.resource_connections.list)
+        return {
+            "items": [
+                {**record.model_dump(by_alias=True, mode="json"), "validationState": "unverified"}
+                for record in records
+            ]
+        }
+
+    @app.put("/api/v1/resource-connections/{connection_ref:path}")
+    async def save_connection(connection_ref: str, request: SaveResourceConnection):
+        if request.connection.target.connection_ref != connection_ref:
+            raise StudioError(
+                "RESOURCE_CONNECTION_REFERENCE_MISMATCH",
+                "路径与连接引用不一致",
+                status_code=422,
+            )
+        record = await asyncio.to_thread(
+            studio.resource_connections.save,
+            request.connection,
+            expected_revision=request.expected_revision,
+        )
+        return {**record.model_dump(by_alias=True, mode="json"), "validationState": "unverified"}

ksadk/studio/authoring_coordinator.py

@@ -13,6 +13,7 @@ from collections import OrderedDict
 from pathlib import Path
 from typing import Any, cast
 
+from ksadk.plugins.providers.legacy_catalog import CODEX_AGENT_PROVIDER_PLUGIN_ID
 from ksadk.studio.authoring import AgentAuthoringService, ConversationProposal
 from ksadk.studio.codex_manifest import CodexAgentManifest
 from ksadk.studio.contracts import (
@@ -77,6 +78,16 @@ def _deduplicated_bindings(resource_ids: list[str]) -> list[CapabilityBinding]:
     return result
 
 
+def _uses_codex_native_tools(runtime: RuntimeRef | None) -> bool:
+    if runtime is None:
+        return False
+    return runtime.type == "codex" or (
+        runtime.type == "plugin"
+        and bool(runtime.provider_ref)
+        and runtime.provider_ref.startswith(f"plugin://{CODEX_AGENT_PROVIDER_PLUGIN_ID}@")
+    )
+
+
 def _inject_managed_bindings(
     proposal: Any,
     *,
@@ -218,9 +229,7 @@ class StudioAuthoringCoordinator:
             ),
             "请根据已确认的需求完成 Agent，并在部署前检查配置和权限。",
         )
-        previous_instructions = (
-            previous_proposal.spec.instructions if previous_proposal else None
-        )
+        previous_instructions = previous_proposal.spec.instructions if previous_proposal else None
         fallback_payload = {
             "name": previous_proposal.name if previous_proposal else "待确认 Agent",
             "slug": previous_proposal.slug if previous_proposal else "conversation-agent",
@@ -257,9 +266,7 @@ class StudioAuthoringCoordinator:
                 "active": True,
                 "reason": _LOCAL_FALLBACK_REASON.get(reason_code, "model-unavailable"),
             },
-            "usage": Usage(source="local-fallback").model_dump(
-                by_alias=True, mode="json"
-            ),
+            "usage": Usage(source="local-fallback").model_dump(by_alias=True, mode="json"),
         }
 
     def create(
@@ -312,6 +319,9 @@ class StudioAuthoringCoordinator:
                     canonical_runtime.version = proposed_runtime.version
                     canonical_runtime.detection = proposed_runtime.detection
             resolved.runtime = canonical_runtime
+            if _uses_codex_native_tools(canonical_runtime):
+                resolved.bindings = resolved.bindings.model_copy(update={"tools": []})
+                resolved.capabilities = resolved.capabilities.model_copy(update={"tools": []})
             if description:
                 resolved.description = description
             draft = self.studio.create_studio_agent(
@@ -686,8 +696,7 @@ class StudioAuthoringCoordinator:
             if exc.code != "AUTHORING_MODEL_OUTPUT_INVALID":
                 raise
             LOGGER.warning(
-                "conversation authoring patch invalid; returning local fallback: "
-                "modelProfileId=%s",
+                "conversation authoring patch invalid; returning local fallback: modelProfileId=%s",
                 model_profile_id,
             )
             self._record_conversation_stage(request_id, "done")
@@ -711,9 +720,7 @@ class StudioAuthoringCoordinator:
                 proposal,
                 model_spec=model_spec,
                 bindings=bindings,
-            ).model_dump(
-                by_alias=True, mode="json"
-            ),
+            ).model_dump(by_alias=True, mode="json"),
             "requiresConfirmation": True,
             "authoringMode": "chat",
             "usage": response.usage.model_dump(by_alias=True, mode="json"),
@@ -773,9 +780,7 @@ class StudioAuthoringCoordinator:
                 result.proposal,
                 model_spec=model_spec,
                 bindings=bindings,
-            ).model_dump(
-                by_alias=True, mode="json"
-            ),
+            ).model_dump(by_alias=True, mode="json"),
             "requiresConfirmation": True,
             "authoringMode": "codex",
             "usage": result.usage.model_dump(by_alias=True, mode="json"),

ksadk/studio/builder.py

@@ -26,11 +26,16 @@ from ksadk.studio.contracts import (
     BundleManifest,
     FileEntry,
 )
+from ksadk.studio.errors import StudioError
 from ksadk.studio.hosted_kernel import (
     build_hosted_kernel_requirement,
     hosted_kernel_requirement_digest,
 )
 from ksadk.studio.repository import BuildRepository
+from ksadk.studio.resource_build_admission import (
+    AdmittedResourceBuild,
+    resource_build_required,
+)
 from ksadk.studio.soul import render_soul_markdown
 from ksadk.studio.workspace import Workspace
 
@@ -56,13 +61,42 @@ class AgentBundleBuilder:
         draft: AgentDraft,
         *,
         composition: ResolvedComposition | None = None,
+        resource_build: AdmittedResourceBuild | None = None,
     ) -> BuildRecord:
         LOGGER.info(
             "bundle build started: agent=%s revision=%s",
             draft.metadata.id,
             draft.metadata.revision,
         )
+        requires_resource_build = resource_build_required(draft)
+        if requires_resource_build != (resource_build is not None):
+            raise StudioError(
+                "RESOURCE_BUILD_ADMISSION_REQUIRED",
+                "平台资源绑定必须通过可信准入后写入同一个 AgentBundle",
+                status_code=409,
+                field="spec.bindings.plugins",
+            )
         compiled = self.compiler.compile(draft)
+        if composition is None and any(
+            server.get("materialization") == "dsh-profile"
+            for server in compiled.resolved.capabilities.mcp_servers
+        ):
+            raise StudioError(
+                "PLUGIN_COMPOSITION_REQUIRED",
+                "动态 DSH MCP 必须通过当前草稿的 Plugin composition 构建",
+                status_code=409,
+                field="spec.bindings.mcpServers",
+            )
+        if composition is not None and (
+            not composition.source_digest
+            or composition.source_digest != compiled.resolved.source_digest
+        ):
+            raise StudioError(
+                "PLUGIN_COMPOSITION_SOURCE_MISMATCH",
+                "Plugin composition 与当前 Agent 草稿快照不一致，请重新编译",
+                status_code=409,
+                field="spec.bindings",
+            )
         # Bundle v2 already carries a deterministic empty lock.  P2-00A now
         # validates that wire shape through PluginLock while deliberately not
         # resolving or loading a PluginHost before P2-02/P2-03.
@@ -90,6 +124,8 @@ class AgentBundleBuilder:
         if composition is not None:
             resolved_digest_payload["compositionProfileDigest"] = composition_profile_digest_value
             resolved_digest_payload["pluginLockDigest"] = plugin_lock_digest_value
+        if resource_build is not None:
+            resolved_digest_payload["resourceSnapshotDigest"] = resource_build.snapshot.digest
         resolved_digest = sha256_digest(canonical_json(resolved_digest_payload))
         short_digest = resolved_digest.removeprefix("sha256:")[:20]
         build_id = f"build_{short_digest}"
@@ -103,15 +139,29 @@ class AgentBundleBuilder:
         )
         bundle_root = staging / "agent-bundle"
         bundle_root.mkdir(parents=True, exist_ok=False)
+        resource_reference = None
         try:
             self._copy_runtime_source(bundle_root, draft)
             self._write_runtime_launch_config(bundle_root, draft)
+            if resource_build is not None:
+                resource_reference = resource_build.materialize(
+                    bundle_root / "platform-resources"
+                )
+                if resource_reference.snapshot_digest != resource_build.snapshot.digest:
+                    raise ValueError("Resource Build reference does not match admitted snapshot")
             launch_config = bundle_root / "runtime" / "agentengine.yaml"
             hosted_kernel_requirement = build_hosted_kernel_requirement(
                 runtime_type=runtime_type,
                 entry_point=runtime_lock.get("entryPoint"),
                 agent_variable=runtime_lock.get("agentVariable"),
                 launch_config=launch_config.read_bytes() if launch_config.is_file() else None,
+                composition_profile_digest=composition_profile_digest_value,
+                plugin_lock_digest=plugin_lock_digest_value,
+                provider_ref=(
+                    composition_profile.agent_provider.ref
+                    if composition_profile is not None
+                    else None
+                ),
             )
             hosted_kernel_requirement_digest_value = hosted_kernel_requirement_digest(
                 hosted_kernel_requirement
@@ -128,6 +178,14 @@ class AgentBundleBuilder:
                 hosted_kernel_requirement=hosted_kernel_requirement,
                 hosted_kernel_requirement_digest_value=hosted_kernel_requirement_digest_value,
                 compatibility_facts_digest_value=compatibility_facts_digest_value,
+                resource_build_digest=(
+                    resource_reference.digest if resource_reference is not None else None
+                ),
+                resource_snapshot_digest=(
+                    resource_reference.snapshot_digest
+                    if resource_reference is not None
+                    else None
+                ),
             )
             self._write_json(
                 bundle_root / "compatibility-report.json",
@@ -166,6 +224,14 @@ class AgentBundleBuilder:
                 composition_mode="composed" if composition is not None else "legacy",
                 composition_profile_digest=composition_profile_digest_value,
                 hosted_kernel_requirement_digest=hosted_kernel_requirement_digest_value,
+                resource_build_digest=(
+                    resource_reference.digest if resource_reference is not None else None
+                ),
+                resource_snapshot_digest=(
+                    resource_reference.snapshot_digest
+                    if resource_reference is not None
+                    else None
+                ),
                 files=files,
             )
             manifest.bundle_digest = compute_bundle_digest(manifest)
@@ -197,6 +263,8 @@ class AgentBundleBuilder:
             source_digest=source_digest,
             runtime_lock=runtime_lock,
             bundle_digest=manifest.bundle_digest,
+            resource_build_digest=manifest.resource_build_digest,
+            resource_snapshot_digest=manifest.resource_snapshot_digest,
             artifact_path=self.workspace.relative(zip_path),
             created_at=now,
             completed_at=now,
@@ -224,6 +292,8 @@ class AgentBundleBuilder:
         hosted_kernel_requirement: dict,
         hosted_kernel_requirement_digest_value: str,
         compatibility_facts_digest_value: str,
+        resource_build_digest: str | None,
+        resource_snapshot_digest: str | None,
     ) -> None:
         definition_digest = compiled.resolved.resolved_digest
         resolved_payload = compiled.resolved.model_dump(
@@ -336,6 +406,12 @@ class AgentBundleBuilder:
                 "profileDigest": composition_profile_digest_value,
                 "pluginLockDigest": sha256_digest(canonical_json(plugin_lock)),
             }
+        if resource_build_digest is not None and resource_snapshot_digest is not None:
+            provenance["platformResources"] = {
+                "manifestPath": "platform-resources/resource-build.json",
+                "resourceBuildDigest": resource_build_digest,
+                "resourceSnapshotDigest": resource_snapshot_digest,
+            }
         self._write_json(root / "provenance.json", provenance)
 
     def _runtime_snapshot(self, draft: AgentDraft, compiled) -> tuple[str, str, dict]: