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

taco/services/tool_service.py

@@ -0,0 +1,482 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from taco.core.api_client import ApiClient
+from taco.core.errors import TacoError
+
+
+class ToolService:
+    def __init__(self, api_client: ApiClient | None = None) -> None:
+        self.api_client = api_client or ApiClient()
+
+    def list_providers(self, *, profile: str | None = None) -> dict[str, Any]:
+        providers = self._list_builtin(profile=profile)
+        return {
+            "items": [
+                {
+                    "provider_id": provider["id"],
+                    "provider_name": provider.get("name"),
+                    "provider_type": "builtin",
+                    "label": provider.get("label"),
+                    "credential_configured": bool(
+                        provider.get("is_team_authorization")
+                    ),
+                    "credential_fields": sorted(
+                        (provider.get("team_credentials") or {}).keys()
+                    ),
+                    "allow_delete": bool(provider.get("allow_delete")),
+                    "tools_count": len(provider.get("tools") or []),
+                }
+                for provider in providers
+            ]
+        }
+
+    def list_tools(
+        self,
+        *,
+        provider: str | None = None,
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        items: list[dict[str, Any]] = []
+        providers = self._list_builtin(profile=profile)
+        for provider_payload in providers:
+            provider_id = provider_payload["id"]
+            if provider is not None and provider_id != provider:
+                continue
+            for tool in provider_payload.get("tools") or []:
+                if not isinstance(tool, dict) or not isinstance(
+                    tool.get("name"),
+                    str,
+                ):
+                    raise _invalid_tool_response()
+                items.append(
+                    {
+                        "author": tool.get("author"),
+                        "name": tool["name"],
+                        "label": tool.get("label"),
+                        "description": tool.get("description"),
+                        "labels": tool.get("labels") or [],
+                        "provider_id": provider_id,
+                        "provider_type": "builtin",
+                        "provider_label": provider_payload.get("label"),
+                        "tool_name": tool["name"],
+                    }
+                )
+        if provider is not None and not any(
+            item["provider_id"] == provider for item in items
+        ):
+            self._find_provider(providers, provider)
+        return {"provider": provider, "items": items}
+
+    def describe_tool(
+        self,
+        *,
+        provider: str,
+        tool: str,
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        providers = self._list_builtin(profile=profile)
+        provider_payload = self._find_provider(providers, provider)
+        tool_payload = self._find_tool(provider_payload, tool)
+        return {
+            **tool_payload,
+            "provider_id": provider,
+            "provider_type": "builtin",
+            "tool_name": tool,
+            "provider_label": provider_payload.get("label"),
+            "credentials_schema": self.credential_schema(
+                provider,
+                profile=profile,
+            ),
+        }
+
+    def credential_schema(
+        self,
+        provider: str,
+        *,
+        profile: str | None = None,
+    ) -> list[dict[str, Any]]:
+        payload = self.api_client.get(
+            self._provider_path(provider, "credentials_schema"),
+            profile=profile,
+        )
+        if not isinstance(payload, list) or any(
+            not isinstance(item, dict)
+            or not isinstance(item.get("name"), str)
+            or not item["name"]
+            for item in payload
+        ):
+            raise _invalid_tool_response()
+        return payload
+
+    def credential_status(
+        self,
+        provider: str,
+        *,
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        schema = self.credential_schema(provider, profile=profile)
+        credentials = self.api_client.get(
+            self._provider_path(provider, "credentials"),
+            profile=profile,
+        )
+        if not isinstance(credentials, dict):
+            raise _invalid_tool_response()
+        return {
+            "provider": provider,
+            "configured": not schema or bool(credentials),
+            "credentials": _mask_credentials(credentials),
+            "schema": schema,
+        }
+
+    def set_credentials(
+        self,
+        provider: str,
+        credentials: dict[str, Any],
+        *,
+        profile: str | None = None,
+    ) -> Any:
+        try:
+            return self.api_client.post(
+                self._provider_path(provider, "update"),
+                json={"credentials": credentials},
+                profile=profile,
+            )
+        except TacoError as error:
+            raise TacoError(
+                code="CREDENTIAL_UPDATE_FAILED",
+                message="Provider 凭据写入失败，服务端未接受该配置。",
+                exit_code=error.exit_code,
+                status=error.status,
+                hint="请核对 credential schema、权限和网络状态后重试。",
+            ) from error
+
+    def delete_credentials(
+        self,
+        provider: str,
+        *,
+        profile: str | None = None,
+    ) -> Any:
+        return self.api_client.post(
+            self._provider_path(provider, "delete"),
+            json={},
+            profile=profile,
+        )
+
+    def resolve_agent_tool(
+        self,
+        *,
+        provider: str,
+        tool: str,
+        parameters: dict[str, Any],
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        provider_payload = self._find_provider(
+            self._list_builtin(profile=profile),
+            provider,
+        )
+        tool_payload = self._find_tool(provider_payload, tool)
+        return self.build_agent_tool(
+            provider=provider_payload,
+            tool=tool_payload,
+            parameters=parameters,
+        )
+
+    @staticmethod
+    def build_agent_tool(
+        *,
+        provider: dict[str, Any],
+        tool: dict[str, Any],
+        parameters: dict[str, Any],
+    ) -> dict[str, Any]:
+        tool_parameters = tool.get("parameters") or []
+        if not isinstance(tool_parameters, list) or any(
+            not isinstance(item, dict) for item in tool_parameters
+        ):
+            raise _invalid_tool_response()
+        for definition in tool_parameters:
+            if (
+                definition.get("required")
+                and definition.get("type")
+                in {"file", "files", "system-files"}
+            ):
+                name = definition.get("name") or "<unknown>"
+                raise TacoError(
+                    code="TOOL_FILE_PARAMETER_UNSUPPORTED",
+                    message=(
+                        f"工具参数 {name} 是必填文件参数，"
+                        "当前 Agent 工具调用不支持。"
+                    ),
+                    exit_code=6,
+                    hint="请选择不含必填文件参数的工具。",
+                )
+        form_parameters = {
+            item.get("name"): item
+            for item in tool_parameters
+            if isinstance(item, dict)
+            and item.get("form") == "form"
+            and isinstance(item.get("name"), str)
+        }
+        unknown = sorted(set(parameters) - set(form_parameters))
+        if unknown:
+            raise TacoError(
+                code="TOOL_PARAMETERS_INVALID",
+                message="工具参数包含未发现字段：" + ", ".join(unknown),
+                exit_code=6,
+                hint="请先执行 taco tool describe 获取 form 参数。",
+            )
+        resolved: dict[str, Any] = {}
+        for name, definition in form_parameters.items():
+            if definition.get("type") in {"file", "files", "system-files"}:
+                if (
+                    name in parameters
+                    or definition.get("default") is not None
+                    or definition.get("required")
+                ):
+                    raise TacoError(
+                        code="TOOL_FILE_PARAMETER_UNSUPPORTED",
+                        message=(
+                            f"工具参数 {name} 需要文件，"
+                            "当前 Agent 本地 DSL 挂载不支持此类 form 参数。"
+                        ),
+                        exit_code=6,
+                        hint="请选择不需要文件 form 参数的工具。",
+                    )
+                continue
+            if definition.get("type") == "secret-input":
+                if name in parameters or definition.get("required"):
+                    raise TacoError(
+                        code="TOOL_SECRET_PARAMETER_UNSUPPORTED",
+                        message=(
+                            f"工具参数 {name} 是 secret-input，"
+                            "不能写入本地 Agent DSL。"
+                        ),
+                        exit_code=6,
+                        hint="请改用 Provider 凭据管理，或选择不含本地密钥的工具。",
+                    )
+                continue
+            if name in parameters:
+                value = parameters[name]
+            elif definition.get("default") is not None:
+                value = definition["default"]
+            elif definition.get("required"):
+                raise TacoError(
+                    code="TOOL_PARAMETERS_INVALID",
+                    message=f"缺少必填工具参数：{name}",
+                    exit_code=6,
+                )
+            else:
+                continue
+            resolved[name] = _normalize_tool_parameter(name, definition, value)
+
+        provider_id = provider.get("id")
+        tool_name = tool.get("name")
+        if not isinstance(provider_id, str) or not isinstance(tool_name, str):
+            raise _invalid_tool_response()
+        payload: dict[str, Any] = {
+            "provider_type": "builtin",
+            "provider_id": provider_id,
+            "provider_name": provider.get("name") or provider_id,
+            "tool_name": tool_name,
+            "tool_label": _localized_label(tool.get("label")) or tool_name,
+            "tool_parameters": resolved,
+            "enabled": True,
+        }
+        plugin_identifier = provider.get("plugin_unique_identifier")
+        if isinstance(plugin_identifier, str) and plugin_identifier:
+            payload["plugin_unique_identifier"] = plugin_identifier
+        return payload
+
+    @staticmethod
+    def validate_credentials_payload(
+        credentials: dict[str, Any],
+        schema: list[dict[str, Any]],
+    ) -> None:
+        validate_credentials_payload(credentials, schema)
+
+    def _list_builtin(
+        self,
+        *,
+        profile: str | None = None,
+    ) -> list[dict[str, Any]]:
+        payload = self.api_client.get(
+            "/workspaces/current/tools/builtin",
+            profile=profile,
+        )
+        if not isinstance(payload, list) or any(
+            not isinstance(item, dict)
+            or not isinstance(item.get("id"), str)
+            or not isinstance(item.get("tools"), list)
+            for item in payload
+        ):
+            raise _invalid_tool_response()
+        return payload
+
+    @staticmethod
+    def _find_provider(
+        providers: list[dict[str, Any]],
+        provider: str,
+    ) -> dict[str, Any]:
+        result = next((item for item in providers if item.get("id") == provider), None)
+        if result is None:
+            raise TacoError(
+                code="TOOL_PROVIDER_NOT_FOUND",
+                message=f"未找到内置工具 Provider：{provider}",
+                exit_code=6,
+                hint="请先执行 taco tool provider list。",
+            )
+        return result
+
+    @staticmethod
+    def _find_tool(provider: dict[str, Any], tool: str) -> dict[str, Any]:
+        result = next(
+            (
+                item
+                for item in provider.get("tools") or []
+                if isinstance(item, dict) and item.get("name") == tool
+            ),
+            None,
+        )
+        if result is None:
+            raise TacoError(
+                code="TOOL_NOT_FOUND",
+                message=f"Provider 中未找到工具：{tool}",
+                exit_code=6,
+                hint="请先执行 taco tool list --provider <provider>。",
+            )
+        return result
+
+    @staticmethod
+    def _provider_path(provider: str, operation: str) -> str:
+        return (
+            "/workspaces/current/tool-provider/builtin/"
+            f"{quote(provider, safe='')}/{operation}"
+        )
+
+
+def _localized_label(label: Any) -> str | None:
+    if isinstance(label, str):
+        return label
+    if isinstance(label, dict):
+        for locale in ("zh_Hans", "en_US"):
+            value = label.get(locale)
+            if isinstance(value, str) and value:
+                return value
+    return None
+
+
+def _mask_credentials(credentials: dict[str, Any]) -> dict[str, str]:
+    return {
+        name: "********" if value is not None and value != "" else ""
+        for name, value in credentials.items()
+    }
+
+
+def _normalize_tool_parameter(
+    name: str,
+    definition: dict[str, Any],
+    value: Any,
+) -> Any:
+    parameter_type = definition.get("type")
+    valid = True
+    if parameter_type == "number":
+        valid = isinstance(value, int | float) and not isinstance(value, bool)
+    elif parameter_type == "boolean":
+        valid = isinstance(value, bool) or (
+            isinstance(value, int) and value in {0, 1}
+        )
+        if isinstance(value, str):
+            valid = False
+            normalized = value.lower()
+            if normalized in {"true", "yes", "y", "1"}:
+                value = True
+                valid = True
+            elif normalized in {"false", "no", "n", "0"}:
+                value = False
+                valid = True
+        if valid:
+            value = bool(value)
+    elif parameter_type == "string":
+        valid = isinstance(value, str)
+    elif parameter_type == "select":
+        options = definition.get("options") or []
+        choices = {
+            option.get("value") if isinstance(option, dict) else option
+            for option in options
+        }
+        if not isinstance(value, str):
+            direct_value = str(value).lower()
+            boolean_value = None
+            if isinstance(value, bool) or (
+                isinstance(value, int) and value in {0, 1}
+            ):
+                boolean_value = "true" if bool(value) else "false"
+            if direct_value in choices or not choices:
+                value = direct_value
+            elif boolean_value in choices:
+                value = boolean_value
+        valid = isinstance(value, str)
+    elif parameter_type == "file":
+        valid = isinstance(value, dict)
+    elif parameter_type in {"files", "system-files"}:
+        valid = isinstance(value, list)
+    elif parameter_type in {"app-selector", "model-selector"}:
+        valid = isinstance(value, dict)
+
+    if valid and parameter_type == "select":
+        valid = not choices or value in choices
+    if valid and parameter_type == "number":
+        minimum = definition.get("min")
+        maximum = definition.get("max")
+        valid = not (
+            isinstance(minimum, int | float) and value < minimum
+            or isinstance(maximum, int | float) and value > maximum
+        )
+
+    if not valid:
+        raise TacoError(
+            code="TOOL_PARAMETERS_INVALID",
+            message=f"工具参数 {name} 不符合发现到的 {parameter_type} 类型或选项。",
+            exit_code=6,
+            hint="请先执行 taco tool describe 获取参数 schema。",
+        )
+    return value
+
+
+def validate_credentials_payload(
+    credentials: dict[str, Any],
+    schema: list[dict[str, Any]],
+) -> None:
+    field_names = {
+        field.get("name")
+        for field in schema
+        if isinstance(field.get("name"), str)
+    }
+    unknown = sorted(set(credentials) - field_names)
+    missing = sorted(
+        field["name"]
+        for field in schema
+        if field.get("required") and field.get("name") not in credentials
+    )
+    if unknown or missing:
+        parts = []
+        if unknown:
+            parts.append("未知字段：" + ", ".join(unknown))
+        if missing:
+            parts.append("缺少字段：" + ", ".join(missing))
+        raise TacoError(
+            code="CREDENTIAL_INPUT_INVALID",
+            message="；".join(parts),
+            exit_code=6,
+            hint="请先执行 taco credential status 查看 schema。",
+        )
+
+
+def _invalid_tool_response() -> TacoError:
+    return TacoError(
+        code="TOOL_RESPONSE_INVALID",
+        message="工具接口返回结构不合法。",
+        exit_code=4,
+    )