tinet-agent-cli 0.1.0.dev36__py3-none-any.whl

taco/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0.dev36"

taco/agent_openapi/__init__.py

@@ -0,0 +1 @@
+"""Developer-center Agent data OpenAPI support."""

taco/agent_openapi/catalog.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import json
+import re
+from importlib import resources
+from pathlib import Path, PurePosixPath
+from types import MappingProxyType
+from typing import Any
+from urllib.parse import urlsplit
+
+from jsonschema import Draft202012Validator
+
+from taco.agent_openapi.models import AgentCatalog, AgentOperation, freeze
+from taco.core.errors import TacoError
+
+
+_ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_ZH_PATTERN = re.compile(r"[\u3400-\u9fff]")
+_RESERVED = {"accesskeyid", "expires", "timestamp", "signature", "authorization"}
+
+
+def load_catalog(root: Path | None = None) -> AgentCatalog:
+    try:
+        if root is None:
+            package_root = resources.files("taco.assets").joinpath("agent_openapi")
+            payload = json.loads(package_root.joinpath("catalog.json").read_text("utf-8"))
+            entries = _entries(payload)
+            operation_payloads = {
+                entry: json.loads(package_root.joinpath("operations", f"{entry}.json").read_text("utf-8"))
+                for entry in entries
+            }
+            actual = sorted(_resource_entries(package_root.joinpath("operations")))
+        else:
+            payload = json.loads((root / "catalog.json").read_text("utf-8"))
+            entries = _entries(payload)
+            operation_payloads = {
+                entry: json.loads((root / "operations" / f"{entry}.json").read_text("utf-8"))
+                for entry in entries
+            }
+            actual = sorted(
+                path.relative_to(root / "operations").as_posix()[:-5]
+                for path in (root / "operations").rglob("*.json")
+            )
+        if sorted(entries) != actual:
+            raise _catalog_error("catalog 登记项与 operation 文件不一致")
+        operations = tuple(_build_operation(entry, operation_payloads[entry]) for entry in entries)
+        if len({item.id for item in operations}) != len(operations):
+            raise _catalog_error("operation id 重复")
+        return AgentCatalog(
+            catalog_version=payload["catalog_version"],
+            source=freeze(payload.get("source", {})),
+            operations=operations,
+            by_id=MappingProxyType({item.id: item for item in operations}),
+        )
+    except TacoError:
+        raise
+    except (OSError, ValueError, TypeError, KeyError) as error:
+        raise _catalog_error(str(error)) from error
+
+
+def operation_not_found(operation_id: str) -> TacoError:
+    return TacoError(
+        code="AGENT_OPENAPI_OPERATION_NOT_FOUND",
+        message=f"未知 Agent OpenAPI operation：{operation_id}",
+        exit_code=2,
+        hint="请执行 taco agent operation search 或 list 查找候选接口。",
+    )
+
+
+def _entries(payload: Any) -> list[str]:
+    if not isinstance(payload, dict):
+        raise _catalog_error("catalog 必须是对象")
+    version = payload.get("catalog_version")
+    if not isinstance(version, str) or version.split(".", 1)[0] != "1":
+        raise _catalog_error("不支持的 catalog_version")
+    if payload.get("json_schema_dialect") != "https://json-schema.org/draft/2020-12/schema":
+        raise _catalog_error("不支持的 JSON Schema 方言")
+    entries = payload.get("operations")
+    if not isinstance(entries, list) or any(not isinstance(item, str) for item in entries):
+        raise _catalog_error("operations 必须是字符串数组")
+    if len(entries) != len(set(entries)):
+        raise _catalog_error("catalog operation 重复")
+    for entry in entries:
+        path = PurePosixPath(entry)
+        if path.is_absolute() or len(path.parts) != 2 or not all(_ID_PATTERN.fullmatch(part) for part in path.parts):
+            raise _catalog_error(f"非法 operation 路径：{entry}")
+    return entries
+
+
+def _resource_entries(root: Any, prefix: str = "") -> list[str]:
+    result: list[str] = []
+    for child in root.iterdir() if root.is_dir() else ():
+        relative = f"{prefix}/{child.name}" if prefix else child.name
+        if child.is_dir():
+            result.extend(_resource_entries(child, relative))
+        elif child.name.endswith(".json"):
+            result.append(relative[:-5])
+    return result
+
+
+def _build_operation(entry: str, payload: Any) -> AgentOperation:
+    if not isinstance(payload, dict) or str(payload.get("schema_version", "")).split(".", 1)[0] != "1":
+        raise _catalog_error(f"{entry} schema 不受支持")
+    group, filename = entry.split("/")
+    if payload.get("id") != filename or payload.get("group") != group:
+        raise _catalog_error(f"{entry} 的 id/group 与文件名不一致")
+    for field in ("title", "description"):
+        if not isinstance(payload.get(field), str) or not payload[field].strip():
+            raise _catalog_error(f"{entry} 缺少 {field}")
+    keywords = payload.get("keywords")
+    source = payload.get("source")
+    if not isinstance(keywords, list) or any(not isinstance(item, str) for item in keywords):
+        raise _catalog_error(f"{entry} keywords 不合法")
+    if not isinstance(source, dict) or not all(isinstance(source.get(key), str) and source[key] for key in ("url", "anchor", "snapshot_date")):
+        raise _catalog_error(f"{entry} source 不完整")
+    http = payload.get("http")
+    if not isinstance(http, dict) or http.get("method") != "POST" or not _safe_path(http.get("path")):
+        raise _catalog_error(f"{entry} HTTP method/path 不合法")
+    query_schema = http.get("query_schema")
+    body_schema = http.get("body_schema")
+    for name, schema in (("query", query_schema), ("body", body_schema)):
+        if not isinstance(schema, dict) or schema.get("type") != "object" or schema.get("additionalProperties") is not False:
+            raise _catalog_error(f"{entry} {name}_schema 不合法")
+        Draft202012Validator.check_schema(schema)
+        _validate_descriptions(schema, request=True, root=True)
+    fields = set(query_schema.get("properties", {})) | set(body_schema.get("properties", {}))
+    if set(query_schema.get("properties", {})) & set(body_schema.get("properties", {})):
+        raise _catalog_error(f"{entry} query/body 参数重名")
+    if any(field.lower() in _RESERVED for field in fields):
+        raise _catalog_error(f"{entry} 声明了保留认证参数")
+    response = payload.get("response")
+    if not isinstance(response, dict) or not isinstance(response.get("schema"), dict):
+        raise _catalog_error(f"{entry} response 不合法")
+    Draft202012Validator.check_schema(response["schema"])
+    _validate_descriptions(response["schema"], request=False, root=True)
+    risk = payload.get("risk")
+    if risk != {"level": "read", "requires_confirmation": False, "target_fields": []}:
+        raise _catalog_error(f"{entry} 只允许只读风险")
+    if payload.get("execution") != {"kind": "http"}:
+        raise _catalog_error(f"{entry} execution 不合法")
+    examples = payload.get("examples")
+    if not isinstance(examples, list) or any(not isinstance(item, dict) for item in examples):
+        raise _catalog_error(f"{entry} examples 不合法")
+    allowed = fields
+    for example in examples:
+        params = example.get("params")
+        if not isinstance(example.get("title"), str) or not isinstance(params, dict) or set(params) - allowed:
+            raise _catalog_error(f"{entry} example 含未知参数")
+        query = {key: value for key, value in params.items() if key in query_schema.get("properties", {})}
+        body = {key: value for key, value in params.items() if key in body_schema.get("properties", {})}
+        if next(Draft202012Validator(query_schema).iter_errors(query), None) or next(Draft202012Validator(body_schema).iter_errors(body), None):
+            raise _catalog_error(f"{entry} example 未通过 schema")
+    return AgentOperation(
+        id=filename,
+        title=payload["title"],
+        description=payload["description"],
+        group=group,
+        keywords=tuple(keywords),
+        source=freeze(source),
+        http=freeze(http),
+        response=freeze(response),
+        risk=freeze(risk),
+        execution=freeze(payload["execution"]),
+        examples=tuple(freeze(examples)),
+    )
+
+
+def _safe_path(value: Any) -> bool:
+    if not isinstance(value, str) or not value.startswith("/agent/v1/data/"):
+        return False
+    parsed = urlsplit(value)
+    return not parsed.scheme and not parsed.netloc and not parsed.query and not parsed.fragment and ".." not in PurePosixPath(parsed.path).parts
+
+
+def _validate_descriptions(schema: dict[str, Any], *, request: bool, root: bool = False) -> None:
+    if not root:
+        required = ("title", "description") if request else ("description",)
+        if not all(isinstance(schema.get(field), str) and schema[field].strip() for field in required):
+            raise _catalog_error("schema 字段缺少说明")
+        if not _ZH_PATTERN.search(schema["description"]):
+            raise _catalog_error("schema description 必须包含中文")
+    if "enum" in schema:
+        descriptions = schema.get("x-enum-descriptions")
+        if not isinstance(descriptions, dict) or set(map(str, schema["enum"])) != set(descriptions):
+            raise _catalog_error("enum 缺少完整说明")
+    for child in schema.get("properties", {}).values():
+        _validate_descriptions(child, request=request)
+    if isinstance(schema.get("items"), dict):
+        _validate_descriptions(schema["items"], request=request)
+
+
+def _catalog_error(detail: str) -> TacoError:
+    return TacoError(
+        code="AGENT_OPENAPI_CATALOG_INVALID",
+        message="内置 Agent OpenAPI operation catalog 不合法。",
+        exit_code=2,
+        hint=detail,
+    )

taco/agent_openapi/models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Mapping
+
+
+JsonMapping = Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentOperation:
+    id: str
+    title: str
+    description: str
+    group: str
+    keywords: tuple[str, ...]
+    source: JsonMapping
+    http: JsonMapping
+    response: JsonMapping
+    risk: JsonMapping
+    execution: JsonMapping
+    examples: tuple[JsonMapping, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentCatalog:
+    catalog_version: str
+    source: JsonMapping
+    operations: tuple[AgentOperation, ...]
+    by_id: Mapping[str, AgentOperation]
+
+
+def freeze(value: Any) -> Any:
+    if isinstance(value, dict):
+        return MappingProxyType({key: freeze(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(freeze(item) for item in value)
+    return value
+
+
+def thaw(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: thaw(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [thaw(item) for item in value]
+    return value

taco/agent_openapi/parameters.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from jsonschema import Draft202012Validator
+
+from taco.agent_openapi.models import AgentOperation, thaw
+from taco.core.errors import TacoError
+
+
+_RESERVED = {"accesskeyid", "expires", "timestamp", "signature", "authorization"}
+_MAX_QUERY_SPAN_SECONDS = 90 * 24 * 60 * 60
+
+
+def parse_parameters(
+    operation: AgentOperation,
+    *,
+    params: list[str] | None = None,
+    params_file: Path | None = None,
+    body_file: Path | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    query_schema = operation.http["query_schema"]
+    body_schema = operation.http["body_schema"]
+    query_fields = query_schema.get("properties", {})
+    body_fields = body_schema.get("properties", {})
+    values: dict[str, Any] = {}
+    for expression in params or []:
+        key, separator, raw = expression.partition("=")
+        if not separator or not key:
+            raise _parameter_error("--param 必须使用 key=value 格式。")
+        if key in values:
+            raise _parameter_error(f"参数重复：/{key}")
+        schema = query_fields.get(key) or body_fields.get(key)
+        if schema is None:
+            raise _parameter_error(f"未知参数：/{key}")
+        values[key] = _parse_value(raw, schema, key)
+    if params_file is not None:
+        file_values = _read_object(params_file)
+        conflicts = set(values) & set(file_values)
+        if conflicts:
+            raise _parameter_error(f"参数重复：/{sorted(conflicts)[0]}")
+        values.update(file_values)
+    if any(key.lower() in _RESERVED for key in values):
+        raise _parameter_error("不能传入公共签名或认证参数。")
+    unknown = set(values) - set(query_fields) - set(body_fields)
+    if unknown:
+        raise _parameter_error(f"未知参数：/{sorted(unknown)[0]}")
+    query = {key: value for key, value in values.items() if key in query_fields}
+    body = {key: value for key, value in values.items() if key in body_fields}
+    if body_file is not None:
+        if body:
+            raise _parameter_error("--body-file 不能与映射到 body 的 --param 同时使用。")
+        body = _read_object(body_file)
+    _validate(query_schema, query)
+    _validate(body_schema, body)
+    _validate_conversation_range(operation, body)
+    return query, body
+
+
+def _parse_value(raw: str, schema: Mapping[str, Any], key: str) -> Any:
+    expected = schema.get("type")
+    try:
+        if expected == "string":
+            return raw
+        if expected == "integer":
+            return int(raw, 10)
+        if expected == "number":
+            return float(raw)
+        if expected == "boolean":
+            if raw.casefold() in {"true", "1"}:
+                return True
+            if raw.casefold() in {"false", "0"}:
+                return False
+            raise ValueError
+        if expected in {"array", "object"}:
+            return json.loads(raw)
+    except (ValueError, json.JSONDecodeError):
+        raise _parameter_error(f"参数 /{key} 类型错误，期望 {expected}。") from None
+    raise _parameter_error(f"参数 /{key} 使用了不支持的类型。")
+
+
+def _read_object(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text("utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        raise _parameter_error(f"参数文件不是合法 UTF-8 JSON 对象：{path}") from None
+    if not isinstance(payload, dict):
+        raise _parameter_error(f"参数文件必须是 JSON 对象：{path}")
+    return payload
+
+
+def _validate(schema: Mapping[str, Any], value: Any) -> None:
+    error = next(Draft202012Validator(thaw(schema)).iter_errors(value), None)
+    if error is not None:
+        pointer = "/" + "/".join(str(part) for part in error.absolute_path)
+        raise _parameter_error(f"参数 {pointer or '/'} 校验失败，期望 {error.validator}。")
+
+
+def _validate_conversation_range(operation: AgentOperation, body: dict[str, Any]) -> None:
+    if operation.id != "list-conversations":
+        return
+    start = body["created_at_start"]
+    end = body["created_at_end"]
+    if end < start or end - start > _MAX_QUERY_SPAN_SECONDS:
+        raise _parameter_error("会话创建时间范围必须正序且不能超过 90 天。")
+
+
+def _parameter_error(message: str) -> TacoError:
+    return TacoError(code="AGENT_OPENAPI_PARAMETER_INVALID", message=message, exit_code=2)

taco/agent_openapi/service.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from jsonschema import Draft202012Validator
+
+from taco.agent_openapi.catalog import load_catalog, operation_not_found
+from taco.agent_openapi.models import AgentOperation, thaw
+from taco.core.config_store import ConfigStore
+from taco.core.developer_center_client import DeveloperCenterClient
+from taco.core.errors import TacoError
+from taco.core.profile_resolver import ProfileResolver
+
+
+class AgentOpenApiService:
+    def __init__(
+        self,
+        store: ConfigStore | None = None,
+        *,
+        profile_resolver: ProfileResolver | None = None,
+        developer_http_client: httpx.Client | None = None,
+    ) -> None:
+        self.store = store or ConfigStore()
+        self.profile_resolver = profile_resolver or ProfileResolver(self.store)
+        self.catalog = load_catalog()
+        self.developer_http_client = developer_http_client
+
+    def call(
+        self,
+        operation_id: str,
+        *,
+        query: dict[str, Any],
+        body: dict[str, Any],
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        operation = self.catalog.by_id.get(operation_id)
+        if operation is None:
+            raise operation_not_found(operation_id)
+        resolved = self.profile_resolver.resolve(profile)
+        client = DeveloperCenterClient(
+            endpoint=resolved.endpoint,
+            access_key_id=resolved.access_key_id,
+            access_key_secret=resolved.access_key_secret,
+            http_client=self.developer_http_client,
+        )
+        try:
+            payload = client.request_json(
+                operation.http["method"],
+                operation.http["path"],
+                query=query or None,
+                json_body=body or None,
+            )
+            return validate_response(operation, payload)
+        finally:
+            client.close()
+
+
+def validate_response(operation: AgentOperation, payload: Any) -> dict[str, Any]:
+    request_id = payload.get("requestId") if isinstance(payload, dict) and isinstance(payload.get("requestId"), str) else None
+    error = next(Draft202012Validator(thaw(operation.response["schema"])).iter_errors(payload), None)
+    if error is not None:
+        pointer = "/" + "/".join(str(part) for part in error.absolute_path)
+        raise TacoError(
+            code="AGENT_OPENAPI_RESPONSE_INVALID",
+            message=f"Agent OpenAPI 响应 {pointer or '/'} 校验失败，期望 {error.validator}。",
+            exit_code=4,
+            request_id=request_id,
+            path=operation.http["path"],
+        )
+    business = dict(payload)
+    business.pop("requestId", None)
+    return {"request_id": request_id, "data": business}

taco/aikb/__init__.py

@@ -0,0 +1,4 @@
+from taco.aikb.catalog import load_catalog
+from taco.aikb.models import AikbCatalog, AikbOperation
+
+__all__ = ["AikbCatalog", "AikbOperation", "load_catalog"]