agentengine-sdk-python 0.8.2__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/attachment_store.py

@@ -0,0 +1,187 @@
+"""Bounded, content-addressed local attachments for ConversationInput."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.workspace import Workspace
+
+_ATTACHMENT_REF = re.compile(r"^attachment://sha256/(?P<digest>[0-9a-f]{64})$")
+_SAFE_FILENAME = re.compile(r"[^A-Za-z0-9._-]+")
+_TEXT_MEDIA_TYPES = {
+    "application/json",
+    "application/toml",
+    "application/xml",
+    "application/x-httpd-php",
+    "application/x-sh",
+    "application/x-yaml",
+}
+_TEXT_SUFFIXES = {
+    ".csv",
+    ".css",
+    ".go",
+    ".html",
+    ".ini",
+    ".java",
+    ".js",
+    ".json",
+    ".jsx",
+    ".log",
+    ".md",
+    ".py",
+    ".rs",
+    ".sh",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".xml",
+    ".yaml",
+    ".yml",
+}
+
+
+@dataclass(frozen=True)
+class StoredConversationAttachment:
+    attachment_ref: str
+    path: Path
+    name: str
+    media_type: str
+    size: int
+    digest: str
+
+
+class ConversationAttachmentStore:
+    """Persist only the small image/text inputs supported by local Studio."""
+
+    MAX_BYTES = 1_500_000
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+        self.root = self.workspace.resolve(".agentkit/assets/conversation-attachments")
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def store(self, content: bytes, *, filename: str, media_type: str) -> dict[str, object]:
+        if not content:
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_EMPTY",
+                "会话附件不能为空",
+                status_code=422,
+                field="file",
+            )
+        if len(content) > self.MAX_BYTES:
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_TOO_LARGE",
+                "会话附件不能超过 1.5 MiB",
+                status_code=413,
+                field="file",
+                details={"maxBytes": self.MAX_BYTES},
+            )
+        normalized_type = media_type.split(";", 1)[0].strip().lower()
+        safe_name = _SAFE_FILENAME.sub("-", Path(filename).name).strip(".-")[:160]
+        safe_name = safe_name or "attachment"
+        if not self._supported(content, filename=safe_name, media_type=normalized_type):
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_TYPE_UNSUPPORTED",
+                "会话附件仅支持图片或 UTF-8 文本、代码文件",
+                status_code=415,
+                field="file",
+            )
+
+        digest = hashlib.sha256(content).hexdigest()
+        content_path = self.root / f"{digest}.bin"
+        metadata_path = self.root / f"{digest}.json"
+        if not content_path.is_file():
+            self.workspace.atomic_write_bytes(content_path, content)
+        if not metadata_path.is_file():
+            self.workspace.atomic_write_text(
+                metadata_path,
+                json.dumps(
+                    {
+                        "digest": digest,
+                        "name": safe_name,
+                        "mediaType": normalized_type or "application/octet-stream",
+                        "size": len(content),
+                    },
+                    ensure_ascii=False,
+                    sort_keys=True,
+                    separators=(",", ":"),
+                )
+                + "\n",
+            )
+        # The reference identifies content, so its persisted metadata is the
+        # authority as well.  Returning a second upload's conflicting name or
+        # media type would create a ref that immediately fails on resolution.
+        stored = self.resolve(f"attachment://sha256/{digest}")
+        return {
+            "attachmentRef": stored.attachment_ref,
+            "name": stored.name,
+            "mediaType": stored.media_type,
+            "size": stored.size,
+            "digest": stored.digest,
+        }
+
+    def resolve(self, attachment_ref: str) -> StoredConversationAttachment:
+        match = _ATTACHMENT_REF.fullmatch(attachment_ref)
+        if match is None:
+            raise not_found("conversation-attachment", attachment_ref)
+        digest = match.group("digest")
+        content_path = self.root / f"{digest}.bin"
+        metadata_path = self.root / f"{digest}.json"
+        if not content_path.is_file() or not metadata_path.is_file():
+            raise not_found("conversation-attachment", attachment_ref)
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+            content = content_path.read_bytes()
+            content_size = len(content)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_CORRUPT",
+                "会话附件元数据损坏",
+                status_code=409,
+                details={"attachmentRef": attachment_ref},
+            ) from exc
+        actual_digest = hashlib.sha256(content).hexdigest()
+        if (
+            metadata.get("digest") != digest
+            or actual_digest != digest
+            or int(metadata.get("size") or -1) != content_size
+        ):
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_CORRUPT",
+                "会话附件完整性校验失败",
+                status_code=409,
+                details={"attachmentRef": attachment_ref},
+            )
+        return StoredConversationAttachment(
+            attachment_ref=attachment_ref,
+            path=content_path,
+            name=str(metadata.get("name") or "attachment"),
+            media_type=str(metadata.get("mediaType") or "application/octet-stream"),
+            size=content_size,
+            digest=digest,
+        )
+
+    @staticmethod
+    def _supported(content: bytes, *, filename: str, media_type: str) -> bool:
+        if media_type.startswith("image/"):
+            return True
+        if (
+            media_type.startswith("text/")
+            or media_type in _TEXT_MEDIA_TYPES
+            or Path(filename).suffix.lower() in _TEXT_SUFFIXES
+        ):
+            try:
+                content.decode("utf-8")
+            except UnicodeDecodeError:
+                return False
+            return True
+        return False
+
+
+__all__ = ["ConversationAttachmentStore", "StoredConversationAttachment"]

ksadk/studio/authoring.py

@@ -694,6 +694,16 @@ class AgentAuthoringService:
         ignored.add(".git")
         entries: list[dict[str, Any]] = []
         for path in sorted(root.rglob("*"), key=lambda item: item.as_posix()):
+            relative = path.relative_to(root).as_posix()
+            # Studio state and VCS internals may legitimately contain symlinks
+            # (for example managed Node dependencies). They are outside the
+            # imported project contract, so prune them before applying the
+            # source-tree symlink safety check.
+            if any(
+                relative == ignored_dir or relative.startswith(ignored_dir + "/")
+                for ignored_dir in (".agentkit", ".git")
+            ):
+                continue
             if path.is_symlink():
                 raise StudioError(
                     "AUTHORING_SOURCE_UNSAFE",
@@ -703,10 +713,6 @@ class AgentAuthoringService:
                 )
             if not path.is_file() or path.name in ignored:
                 continue
-            # 跳过 .agentkit / .git 目录下的文件
-            relative = path.relative_to(root).as_posix()
-            if any(relative.startswith(ignored_dir + "/") for ignored_dir in (".agentkit", ".git")):
-                continue
             content = path.read_bytes()
             entries.append(
                 {

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(
@@ -278,7 +285,6 @@ class StudioAuthoringCoordinator:
             resolved = (spec or default_agent_spec(template, description=description)).model_copy(
                 deep=True
             )
-            canonical_runtime = self.backend.runtime_ref(agent_id, runtime_type)
             proposed_runtime = resolved.runtime
             if proposed_runtime is not None and proposed_runtime.type != runtime_type:
                 raise StudioError(
@@ -291,7 +297,18 @@ class StudioAuthoringCoordinator:
                         "specRuntimeType": proposed_runtime.type,
                     },
                 )
-            if proposed_runtime is not None:
+            if runtime_type == "plugin":
+                if proposed_runtime is None or proposed_runtime.provider_ref is None:
+                    raise StudioError(
+                        "AGENT_PROVIDER_REFERENCE_REQUIRED",
+                        "外部 AgentProvider 必须选择一个已安装的精确版本",
+                        status_code=422,
+                        field="spec.runtime.providerRef",
+                    )
+                canonical_runtime = proposed_runtime.model_copy(deep=True)
+            else:
+                canonical_runtime = self.backend.runtime_ref(agent_id, runtime_type)
+            if proposed_runtime is not None and runtime_type != "plugin":
                 if runtime_type == "codex" and proposed_runtime.version:
                     canonical_runtime.version = proposed_runtime.version
                 elif runtime_type in {"adk", "langgraph"}:
@@ -302,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(
@@ -676,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")
@@ -701,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"),
@@ -763,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"),