bkai-init 0.1.0__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,465 @@
+"""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 .logging import log_exchange, log_mcp_query, log_result, redact, request_diagnostics
+from .retry import request_with_retry
+from .uploads import upload_archive
+from .users import lookup_username
+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._app_code, self._app_secret = app_code, app_secret
+        self._login_name = username or settings.DEFAULT_ADMIN_LOGIN_NAME
+        self._username_resolved = False
+        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 resolve_username(self, bk_user_base_url: str | None) -> None:
+        if not self._username_resolved:
+            self.session.headers["X-BKAIDEV-USER"] = lookup_username(
+                bk_user_base_url, self._app_code, self._app_secret, self.tenant_id, self.timeout, self._login_name
+            )
+            self._username_resolved = True
+
+    def add_agent_admins(self, agent_id: int, space_id: str, admins: list[str]) -> dict[str, Any]:
+        return self._request("POST", f"/agents/{agent_id}/admins/", json={"space_id": space_id, "admins": admins})
+
+    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 = settings.DEFAULT_PUBLISH_CONFIG_ONLY
+    ) -> 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
+        try:
+            result = self._request("GET", f"/mcps/by-code/{code}/", show_url=False, params=params)
+        except APIError as exc:
+            exc.request_logged = False
+            raise
+        log_mcp_query(code, agent_code, secrets=self._secrets)
+        return result
+
+    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, *, show_url: bool = True, **kwargs: Any) -> Any:
+        if not path.startswith("/") or any(token in path for token in ("..", ":", "?", "#", "%", "//")):
+            raise APIError("仅允许调用 app 下的相对资源路径")
+        url = f"{self.api_root}{path}"
+        inputs = {key: kwargs[key] for key in ("params", "json", "data") if key in kwargs}
+        if kwargs.get("files"):
+            inputs["files"] = {key: item[0] for key, item in kwargs["files"].items()}
+        log_exchange(
+            "请求",
+            method,
+            url,
+            next(iter(inputs.values())) if len(inputs) == 1 else inputs,
+            secrets=self._secrets,
+            show_url=show_url,
+        )
+        try:
+            response = request_with_retry(
+                lambda: self.session.request(method, url, timeout=self.timeout, allow_redirects=False, **kwargs),
+                query=method == "GET" or (method == "POST" and path == "/upload/status/"),
+            )
+        except requests.RequestException as exc:
+            log_exchange("失败", method, url, {"error": type(exc).__name__}, secrets=self._secrets)
+            raise self._http_error(
+                f"请求 AIDEV app OpenAPI 失败：{type(exc).__name__}",
+                method,
+                path,
+                kwargs,
+                str(exc),
+            ) from None
+
+        if 300 <= response.status_code < 400:
+            log_exchange(
+                "响应", method, url, {"error": "拒绝重定向"}, status=response.status_code, secrets=self._secrets
+            )
+            log_result(False, "接口返回重定向，已拒绝跟随", secrets=self._secrets)
+            raise self._http_error(
+                "app OpenAPI 返回重定向，已拒绝携带凭据跳转",
+                method,
+                path,
+                kwargs,
+                {"status": response.status_code},
+                status=response.status_code,
+                response=response,
+            )
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        log_exchange(
+            "响应",
+            method,
+            url,
+            payload if payload is not None else response.text[:500],
+            status=response.status_code,
+            secrets=self._secrets,
+            success=response.ok and not (isinstance(payload, dict) and payload.get("result") is False),
+        )
+        if not response.ok:
+            detail = self._redact(_error_detail(self._redact_value(payload)) or response.text[:500])
+            log_result(False, f"HTTP {response.status_code}：{detail}", secrets=self._secrets)
+            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,
+                response=response,
+            )
+        if isinstance(payload, dict) and payload.get("result") is False:
+            log_result(False, _error_detail(self._redact_value(payload)), secrets=self._secrets)
+            raise self._http_error(
+                f"AIDEV OpenAPI 业务失败：{self._redact(_error_detail(payload))}",
+                method,
+                path,
+                kwargs,
+                payload,
+                response=response,
+            )
+        log_result(True)
+        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,
+        response=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, output),
+            diagnostics=self._redact_value(request_diagnostics(response, output)),
+            status=status if status is not None else getattr(response, "status_code", None),
+            request_logged=True,
+        )
+
+    def _redact_value(self, value: Any) -> Any:
+        return redact(value, self._secrets)
+
+    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, output: Any = None) -> str | None:
+    lowered = detail.lower()
+    route_missing = isinstance(output, dict) and (
+        output.get("code_name") == "API_NOT_FOUND" or str(output.get("code")) == "1640401"
+    )
+    if route_missing or (status == 404 and "api not found" in lowered):
+        return (
+            "网关未找到接口路由，尚未到达业务服务，不能据此判断 MCP 或其他资源是否存在。"
+            "请检查 BKAI_BASE_URL / BK_API_URL_TMPL 中的网关名称和 stage，"
+            "并确认请求路径及方法已同步、发布到该 APIGW stage。"
+        )
+    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 "incorrect string value" in lowered and "skill_markdown" in lowered:
+        return "请检查平台 Skill Markdown 字段及数据库连接字符集是否支持 utf8mb4，并提供请求标识排查。"
+    if "初始化应用成员信息失败" in detail:
+        return "请联系平台管理员检查 BK IAM 用户组创建接口，并提供请求标识与错误详情。"
+    if status in {401, 403}:
+        return "请检查应用凭据，以及应用是否已获目标空间和相关资源授权。"
+    if status is not None and 300 <= status < 400:
+        return "请求被重定向，已拒绝跟随以免泄露凭据。请使用可直接访问的 app OpenAPI 地址。"
+    return None

bkai_init/api/logging.py

@@ -0,0 +1,105 @@
+"""Readable transport logs with credentials removed before formatting."""
+
+import json
+import logging
+import re
+from collections.abc import Mapping
+from textwrap import indent
+from urllib.parse import urlsplit, urlunsplit
+
+logger = logging.getLogger(__name__)
+
+
+def _is_sensitive_key(key):
+    return any(
+        word in str(key).lower() for word in ("secret", "token", "password", "authorization", "cookie", "signature")
+    )
+
+
+def redact(value, secrets=()):
+    if isinstance(value, dict):
+        return {
+            key: "[REDACTED]"
+            if _is_sensitive_key(key) or (key == "value" and _is_sensitive_key(value.get("key", "")))
+            else redact(item, secrets)
+            for key, item in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [redact(item, secrets) for item in value]
+    if isinstance(value, str):
+        for secret in secrets:
+            if secret:
+                value = value.replace(secret, "[REDACTED]")
+
+        def public_url(match):
+            try:
+                url = urlsplit(match.group())
+                host = url.netloc.rsplit("@", 1)[-1]
+                return urlunsplit((url.scheme, host, url.path, "[REDACTED]" if url.query else "", ""))
+            except ValueError:
+                return "[REDACTED URL]"
+
+        return re.sub(r"https?://[^\s\"<>]+", public_url, value)
+    return value
+
+
+def log_result(success, reason="", *, secrets=()):
+    outcome = "成功" if success else "失败"
+    suffix = f"：{redact(str(reason), secrets)}" if reason else ""
+    logger.debug("      - 处理结果：%s%s\n", outcome, suffix)
+
+
+def log_exchange(label, method, url, payload, *, status=None, secrets=(), success=False, show_url=True):
+    if label == "响应" and success:
+        logger.debug("      - 接口响应： [HTTP %s]\n", status)
+        return
+    detail = json.dumps(redact(payload, secrets), ensure_ascii=False, indent=2, default=lambda _: "<binary/file>")
+    formatted = indent(detail, "          ")
+    if label == "请求":
+        from ..services.progress import current_progress
+        from ..services.progress import logger as progress_logger
+
+        target_logger = progress_logger if current_progress() else logger
+        if show_url:
+            target_logger.info("      接口请求：%s %s", method, redact(url, secrets))
+        logger.debug("%s", formatted)
+    elif label == "失败":
+        reason = payload.get("error", "请求失败") if isinstance(payload, dict) else payload
+        log_result(False, reason, secrets=secrets)
+    else:
+        http = f" [HTTP {status}]" if status is not None else ""
+        logger.debug("      - 接口%s：%s\n%s\n", label, http, formatted)
+
+
+def request_diagnostics(response, output):
+    result = {}
+    headers = getattr(response, "headers", {})
+    if isinstance(headers, Mapping):
+        result.update(
+            {
+                key: value
+                for key, value in headers.items()
+                if key.lower() in {"x-request-id", "x-bkapi-request-id", "x-bk-request-id", "x-trace-id", "traceparent"}
+            }
+        )
+    if isinstance(output, dict):
+        for body in (output, output.get("error"), output.get("data")):
+            if isinstance(body, dict):
+                result.update(
+                    {
+                        key: body[key]
+                        for key in ("request_id", "trace_id", "code", "code_name")
+                        if body.get(key) is not None
+                    }
+                )
+    return result
+
+
+def log_mcp_query(code, agent_code, *, secrets=()):
+    from ..services.progress import current_progress
+    from ..services.progress import logger as progress_logger
+
+    target_logger = progress_logger if current_progress() else logger
+    target_logger.info(
+        "      【正在查询 MCP】%s agent_code: %s 成功", redact(code, secrets), redact(agent_code or "-", secrets)
+    )

bkai_init/api/retry.py

@@ -0,0 +1,31 @@
+"""Bounded retries for read-only requests."""
+
+import time
+
+import requests
+
+from .logging import logger
+
+
+def request_with_retry(send, *, query=False):
+    delays = (1, 2, 4) if query else ()
+    for attempt in range(len(delays) + 1):
+        try:
+            response = send()
+        except (requests.ConnectionError, requests.Timeout) as exc:
+            if attempt == len(delays):
+                raise
+            reason = type(exc).__name__
+        else:
+            if attempt == len(delays) or not (response.status_code == 429 or 500 <= response.status_code < 600):
+                return response
+            reason = f"HTTP {response.status_code}"
+            response.close()
+        from ..services.progress import current_progress
+
+        progress = current_progress()
+        if progress:
+            progress.retries += 1
+        delay = delays[attempt]
+        logger.info("      - 查询重试：%s，%s 秒后重试（%s/3）", reason, delay, attempt + 1)
+        time.sleep(delay)