bkai-init 0.1.0rc10__py3-none-any.whl

bkai_init/__init__.py

@@ -0,0 +1,19 @@
+"""AIDEV Agent Package initialization CLI."""
+
+import logging
+
+from .services import BkaiInit
+from .utils.exceptions import APIError, BkaiCliError, ConfigurationError, ManifestError
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIError",
+    "BkaiCliError",
+    "BkaiInit",
+    "ConfigurationError",
+    "ManifestError",
+    "__version__",
+]

bkai_init/__main__.py

@@ -0,0 +1,5 @@
+"""Run ``bkai-init`` with ``python -m bkai_init``."""
+
+from .cli import main
+
+raise SystemExit(main())

bkai_init/api/__init__.py

@@ -0,0 +1,5 @@
+"""AIDEV application OpenAPI client."""
+
+from .client import AidevClient
+
+__all__ = ["AidevClient"]

bkai_init/api/client.py

@@ -0,0 +1,398 @@
+"""HTTP client for the BKAIDEV application OpenAPI."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import requests
+
+from .uploads import upload_archive
+from .. import settings
+from ..utils.exceptions import APIError, ConfigurationError
+
+
+class AidevClient:
+    """Small API client with application authentication and response unwrapping."""
+
+    def __init__(
+        self,
+        base_url: str,
+        app_code: str,
+        app_secret: str,
+        *,
+        tenant_id: str = settings.DEFAULT_TENANT_ID,
+        access_token: str | None = None,
+        username: str | None = None,
+        timeout: float = settings.DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url 不能为空")
+        self.api_root = _api_root(base_url)
+        self.timeout = timeout
+        self.tenant_id = tenant_id
+        self._secrets = tuple(value for value in (app_secret, access_token) if value)
+        self.session = session or requests.Session()
+        authorization = {"bk_app_code": app_code, "bk_app_secret": app_secret}
+        if access_token:
+            authorization["access_token"] = access_token
+        headers = {
+            "Accept": "application/json",
+            "X-Bk-Tenant-Id": tenant_id,
+            "X-Bkapi-Authorization": json.dumps(authorization),
+        }
+        if username:
+            headers["X-BKAIDEV-USER"] = username
+        self.session.headers.update({name: _latin1_header(name, value) for name, value in headers.items()})
+
+    def upload_skill(self, archive: Path, space_id: str) -> dict[str, Any]:
+        with archive.open("rb") as file_obj:
+            return self._request(
+                "POST",
+                "/upload/",
+                data={"module": "skill", "space_id": space_id},
+                files={"file": (archive.name, file_obj, "application/zip")},
+            )
+
+    def upsert_skill(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/skills/upsert/", json=payload)
+
+    def upload_knowledge(self, archive: Path, space_id: str) -> dict[str, Any]:
+        with archive.open("rb") as content:
+            sha256 = hashlib.file_digest(content, "sha256").hexdigest()
+        size = archive.stat().st_size
+        grant = self._request(
+            "POST",
+            "/upload/url/",
+            json={
+                "space_id": space_id,
+                "module": "knowledge",
+                "file_name": archive.name,
+            },
+        )
+        if (
+            not isinstance(grant, dict)
+            or not isinstance(grant.get("url"), str)
+            or not grant["url"].startswith("bkrepo://")
+        ):
+            raise self._http_error(
+                "平台返回的知识库直传授权不完整",
+                "POST",
+                "/upload/url/",
+                {"json": {"space_id": space_id, "module": "knowledge", "file_name": archive.name}},
+                grant,
+            )
+        try:
+            upload_archive(archive, grant, self.timeout)
+        except APIError:
+            # A timeout may mean the upload succeeded. Never blindly repeat a PUT.
+            self.knowledge_upload_status(grant["url"], space_id, size, sha256)
+        else:
+            self.knowledge_upload_status(grant["url"], space_id, size, sha256)
+        return {"url": grant["url"], "file_name": archive.stem, "file_type": "zip", "file_size": size}
+
+    def knowledge_upload_status(self, url: str, space_id: str, size: int, sha256: str) -> dict[str, Any]:
+        payload = {"space_id": space_id, "url": url}
+        data = self._request("POST", "/upload/status/", json=payload)
+        if (
+            not isinstance(data, dict)
+            or data.get("uploaded") is not True
+            or data.get("file_size") != size
+            or data.get("sha256") != sha256
+        ):
+            raise self._http_error(
+                "知识 ZIP 上传状态校验失败", "POST", "/upload/status/", {"json": payload}, data
+            )
+        return data
+
+    def import_knowledge_archive(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/knowledges/archive/import/", json=payload)
+
+    def knowledge_status(self, space_id: str, anchor_path: str) -> dict[str, Any]:
+        return self._request(
+            "GET", "/knowledges/status_info/", params={"space_id": space_id, "anchor_path": anchor_path}
+        )
+
+    def list_skills(self, space_id: str, code: str) -> list[dict[str, Any]]:
+        return self._listed(
+            "GET",
+            "/skills/",
+            params={"space_id": space_id, "fuzzy": code, "page": 1, "page_size": 200},
+        )
+
+    def get_skill(self, skill_id: int, space_id: str, version: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"space_id": space_id}
+        if version:
+            params["version"] = version
+        return self._request("GET", f"/skills/{skill_id}/", params=params)
+
+    def list_agents(self, space_id: str, code: str) -> list[dict[str, Any]]:
+        return self._listed(
+            "GET",
+            "/agents/",
+            params={"space_id": space_id, "agent_code": code, "page": 1, "page_size": 200},
+        )
+
+    def get_agent(self, agent_id: int, space_id: str, version: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"space_id": space_id}
+        if version:
+            params["version"] = version
+        return self._request("GET", f"/agents/{agent_id}/", params=params)
+
+    def create_agent(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/agents/", json=payload)
+
+    def update_agent(self, agent_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("PUT", f"/agents/{agent_id}/update/", json=payload)
+
+    def publish_agent(self, agent_id: int, space_id: str, *, publish_config_only: bool = True) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"/agents/{agent_id}/publish/",
+            json={
+                "space_id": space_id,
+                "publish_config_only": publish_config_only,
+            },
+        )
+
+    def list_mcps(self, space_id: str, code: str, mcp_type: str) -> list[dict[str, Any]]:
+        return self._listed(
+            "GET",
+            "/mcps/",
+            params={
+                "space_id": space_id,
+                "mcp_code": code,
+                "mcp_type": mcp_type,
+                "page": 1,
+                "page_size": 200,
+            },
+        )
+
+    def get_mcp_by_code(
+        self, space_id: str | None, code: str, *, mcp_type: str = "apigw", agent_code: str | None = None
+    ) -> dict[str, Any]:
+        if not code or any(
+            char not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-" for char in code
+        ):
+            raise APIError("MCP code 只能包含字母、数字、下划线和减号")
+        if mcp_type not in {"apigw", "resource"}:
+            raise APIError("mcp_type 必须为 apigw 或 resource")
+        params = {"mcp_type": mcp_type}
+        if space_id is not None:
+            params["space_id"] = space_id
+        if agent_code is not None:
+            params["agent_code"] = agent_code
+        return self._request("GET", f"/mcps/by-code/{code}/", params=params)
+
+    def list_collections(self, space_id: str, code: str) -> list[dict[str, Any]]:
+        return self._listed(
+            "GET",
+            "/collections/",
+            params={
+                "space_id": space_id,
+                "collection_code": code,
+                "page": 1,
+                "page_size": 200,
+            },
+        )
+
+    def get_collection(self, collection_id: int, space_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/collections/{collection_id}/", params={"space_id": space_id})
+
+    def upsert_collection(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/collections/upsert/", json=payload)
+
+    def list_knowledgebases(self, space_id: str, code: str) -> list[dict[str, Any]]:
+        return self._listed(
+            "POST",
+            "/knowledgebase/list/",
+            json={
+                "space_id": space_id,
+                "knowledgebase_code": code,
+                "generate_type": "all",
+                "page": 1,
+                "page_size": 200,
+            },
+        )
+
+    def create_knowledgebase(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/knowledgebase/", json=payload)
+
+    def update_knowledgebase(self, knowledgebase_id: int, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("PATCH", f"/knowledgebase/{knowledgebase_id}/update/", json=payload)
+
+    def _listed(self, method: str, path: str, **kwargs: Any) -> list[dict[str, Any]]:
+        data = self._request(method, path, **kwargs)
+        try:
+            return _results(data)
+        except APIError as exc:
+            raise self._http_error(exc.args[0], method, path, kwargs, data) from None
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if not path.startswith("/") or any(token in path for token in ("..", ":", "?", "#", "%", "//")):
+            raise APIError("仅允许调用 app 下的相对资源路径")
+        url = f"{self.api_root}{path}"
+        try:
+            response = self.session.request(method, url, timeout=self.timeout, allow_redirects=False, **kwargs)
+        except requests.RequestException as exc:
+            raise self._http_error(
+                f"请求 AIDEV app OpenAPI 失败：{type(exc).__name__}",
+                method,
+                path,
+                kwargs,
+                str(exc),
+            ) from None
+
+        if 300 <= response.status_code < 400:
+            raise self._http_error(
+                "app OpenAPI 返回重定向，已拒绝携带凭据跳转",
+                method,
+                path,
+                kwargs,
+                {"status": response.status_code},
+                status=response.status_code,
+            )
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        if not response.ok:
+            detail = self._redact(_error_detail(payload) or response.text[:500])
+            raise self._http_error(
+                f"AIDEV OpenAPI 返回 {response.status_code}：{detail}",
+                method,
+                path,
+                kwargs,
+                payload if payload is not None else response.text[:500],
+                status=response.status_code,
+            )
+        if isinstance(payload, dict) and payload.get("result") is False:
+            raise self._http_error(
+                f"AIDEV OpenAPI 业务失败：{self._redact(_error_detail(payload))}",
+                method,
+                path,
+                kwargs,
+                payload,
+            )
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        return payload
+
+    def _http_error(
+        self,
+        message: str,
+        method: str,
+        path: str,
+        kwargs: dict[str, Any],
+        output: Any,
+        *,
+        status: int | None = None,
+    ) -> APIError:
+        return APIError(
+            message,
+            url=f"{self.api_root}{path}",
+            method=method,
+            params=self._redact_value(_request_params(kwargs)),
+            output=self._redact_value(output),
+            hint=_error_hint(path, status, message),
+        )
+
+    def _redact_value(self, value: Any) -> Any:
+        if isinstance(value, str):
+            return self._redact(value)
+        if isinstance(value, dict):
+            return {key: self._redact_value(item) for key, item in value.items()}
+        if isinstance(value, list):
+            return [self._redact_value(item) for item in value]
+        return value
+
+    def _redact(self, message: str) -> str:
+        for secret in self._secrets:
+            message = message.replace(secret, "[REDACTED]")
+        return message
+
+
+def _latin1_header(name: str, value: str) -> str:
+    try:
+        value.encode("latin-1")
+    except UnicodeEncodeError:
+        raise ConfigurationError(f"请求头 {name} 包含非 Latin-1 字符") from None
+    return value
+
+
+def _api_root(base_url: str) -> str:
+    normalized = base_url.rstrip("/")
+    parsed = urlsplit(normalized)
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.netloc
+        or parsed.username
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError("base_url 必须是无凭据、查询参数和片段的 HTTP(S) 地址")
+    if "/private" in parsed.path or ".." in parsed.path or "%" in parsed.path:
+        raise ValueError("base_url 不允许 private 接口或路径跳转")
+    if normalized.endswith(settings.DEFAULT_API_PREFIX):
+        return normalized
+    return f"{normalized}{settings.DEFAULT_API_PREFIX}"
+
+
+def _results(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, dict) and isinstance(data.get("results"), list):
+        items = data["results"]
+        count = data.get("count", len(items))
+        if type(count) is not int or count < 0:
+            raise APIError("列表接口 count 无效")
+        if count > len(items):
+            raise APIError("列表超过单页上限，无法保证 code 唯一；已停止操作")
+        if any(not isinstance(item, dict) for item in items):
+            raise APIError("列表响应包含无效资源对象")
+        return items
+    if isinstance(data, list):
+        if any(not isinstance(item, dict) for item in data):
+            raise APIError("列表响应包含无效资源对象")
+        return data
+    raise APIError("列表接口响应结构无效，不能按资源不存在处理")
+
+
+def _error_detail(payload: Any) -> str:
+    if not isinstance(payload, dict):
+        return ""
+    error = payload.get("error")
+    if isinstance(error, dict) and error.get("message"):
+        return str(error["message"])
+    return str(payload.get("message") or error or payload)
+
+
+def _request_params(kwargs: dict[str, Any]) -> Any:
+    snapshot = {key: kwargs[key] for key in ("params", "json", "data") if kwargs.get(key) is not None}
+    if len(snapshot) == 1:
+        return next(iter(snapshot.values()))
+    return snapshot or None
+
+
+def _error_hint(path: str, status: int | None, detail: str) -> str | None:
+    lowered = detail.lower()
+    if "/mcps/by-code/" in path:
+        code = path.rstrip("/").rsplit("/", 1)[-1]
+        if status == 404 or "not found" in lowered:
+            return (
+                f"bkai-init 不会创建 MCP。请先在平台创建并发布 APIGW MCP {code}，"
+                "完成当前应用授权，并确认 Agent YAML 中的 code 与线上 mcp_code 一致后再重试。"
+            )
+        if status in {401, 403}:
+            return (
+                "查询 MCP 需要应用已获目标空间授权。"
+                "非公开 MCP 还需智能体已存在并完成网关授权；plan 不会为此提前创建智能体。"
+            )
+    if status in {401, 403}:
+        return "请检查应用凭据，以及应用是否已获目标空间和相关资源授权。"
+    if status is not None and 300 <= status < 400:
+        return "请求被重定向，已拒绝跟随以免泄露凭据。请使用可直接访问的 app OpenAPI 地址。"
+    return None

bkai_init/api/uploads.py

@@ -0,0 +1,63 @@
+"""Raw BKRepo transport. Never reuse the application-authenticated session."""
+
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+import requests
+
+from ..utils.exceptions import APIError
+
+
+def upload_archive(archive: Path, grant: dict, timeout: float) -> None:
+    try:
+        url = grant["upload_url"]
+        parsed = urlsplit(url)
+        headers = grant["headers"]
+        if (
+            grant.get("method") != "PUT"
+            or parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username
+            or parsed.password
+            or parsed.fragment
+            or any(ord(c) < 32 for c in url)
+            or not isinstance(headers, dict)
+            or set(headers) - {"Content-Type", "X-BKREPO-OVERWRITE", "X-Checksum-Sha256"}
+        ):
+            raise ValueError
+    except (KeyError, TypeError, ValueError):
+        raise APIError("平台返回的直传授权不合法") from None
+    public_url = urlunsplit((parsed.scheme, parsed.netloc, parsed.path, "", ""))
+    # trust_env=False prevents implicit .netrc authentication and proxy credentials.
+    with requests.Session() as session:
+        session.trust_env = False
+        try:
+            with archive.open("rb") as content:
+                response = session.put(url, data=content, headers=headers, timeout=timeout, allow_redirects=False)
+            if not 200 <= response.status_code < 300:
+                raise APIError(
+                    f"BKRepo 直传失败（HTTP {response.status_code}）",
+                    url=public_url,
+                    method="PUT",
+                    output={"status": response.status_code},
+                    hint="直传失败。请查询上传状态确认是否已成功，不要直接重试 PUT。",
+                )
+            if response.content:
+                payload = response.json()
+                if not isinstance(payload, dict) or payload.get("code") != 0:
+                    raise APIError(
+                        "BKRepo 直传业务失败",
+                        url=public_url,
+                        method="PUT",
+                        output=payload,
+                        hint="直传业务失败。请查询上传状态确认是否已成功，不要直接重试 PUT。",
+                    )
+        except APIError:
+            raise
+        except (requests.RequestException, ValueError):
+            raise APIError(
+                "BKRepo 直传失败或结果未知，请查询上传状态",
+                url=public_url,
+                method="PUT",
+                hint="请查询上传状态确认是否已成功，不要直接重试 PUT。",
+            ) from None