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

taco/services/workflow_tool_service.py

@@ -0,0 +1,439 @@
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+from uuid import UUID
+
+from taco.core.api_client import ApiClient
+from taco.core.errors import TacoError
+
+
+_WORKFLOW_TOOL_PATH = "/workspaces/current/tool-provider/workflow"
+_TOOL_NAME = re.compile(r"^[A-Za-z0-9_]{1,64}$")
+_DIFY_SELECTOR = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,29}$")
+_SUPPORTED_WORKFLOW_INPUT_TYPES = frozenset({"string", "number", "select"})
+_UNSUPPORTED_FILE_TYPES = frozenset({"file", "files", "system-files"})
+_DEFAULT_ICON = {"background": "#E4FBCC", "content": "🔀"}
+
+
+class WorkflowToolService:
+    def __init__(self, api_client: ApiClient | None = None) -> None:
+        self.api_client = api_client or ApiClient()
+
+    def get_tool(
+        self,
+        workflow_app_id: str | None = None,
+        workflow_tool_id: str | None = None,
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        app_id = _non_empty_string(workflow_app_id)
+        tool_id = _non_empty_string(workflow_tool_id)
+        if (app_id is None) == (tool_id is None):
+            raise TacoError(
+                code="WORKFLOW_TOOL_QUERY_INVALID",
+                message="查询 Workflow Tool 必须且只能提供 app ID 或 tool ID。",
+                exit_code=2,
+            )
+
+        params = (
+            {"workflow_app_id": app_id}
+            if app_id is not None
+            else {"workflow_tool_id": tool_id}
+        )
+        payload = self.api_client.get(
+            f"{_WORKFLOW_TOOL_PATH}/get",
+            params=params,
+            profile=profile,
+        )
+        _validate_detail_identity(payload)
+        if (
+            tool_id is not None
+            and not _identifiers_match(tool_id, payload["workflow_tool_id"])
+        ) or (
+            app_id is not None
+            and not _identifiers_match(app_id, payload["workflow_app_id"])
+        ):
+            raise _invalid_response()
+        return payload
+
+    def publish_tool(
+        self,
+        app_id: str,
+        workflow: Mapping[str, Any],
+        name: str,
+        label: str,
+        description: str,
+        profile: str | None = None,
+    ) -> Any:
+        _validate_machine_name(name)
+        _validate_label(label)
+        _validate_description(description)
+        parameters = _derive_parameters(workflow)
+        response = self.api_client.post(
+            f"{_WORKFLOW_TOOL_PATH}/create",
+            json={
+                "workflow_app_id": app_id,
+                "name": name,
+                "label": label,
+                "description": description,
+                "icon": dict(_DEFAULT_ICON),
+                "parameters": parameters,
+                "privacy_policy": "",
+                "labels": [],
+            },
+            profile=profile,
+        )
+        return _validated_write_response(response)
+
+    def update_tool(
+        self,
+        tool_id: str,
+        workflow: Mapping[str, Any],
+        name: str | None = None,
+        label: str | None = None,
+        description: str | None = None,
+        profile: str | None = None,
+    ) -> Any:
+        detail = self.get_tool(workflow_tool_id=tool_id, profile=profile)
+        if not _identifiers_match(tool_id, detail["workflow_tool_id"]):
+            raise _invalid_response()
+        canonical_tool_id = _canonical_identifier(detail["workflow_tool_id"])
+        merged_name = detail["name"] if name is None else name
+        merged_label = _merged_string(detail, "label", label)
+        merged_description = _merged_string(
+            detail,
+            "description",
+            description,
+            allow_empty=True,
+        )
+        _validate_machine_name(merged_name)
+        _validate_label(merged_label)
+        _validate_description(merged_description)
+
+        icon = detail.get("icon")
+        privacy_policy = detail.get("privacy_policy", "")
+        labels = _detail_labels(detail)
+        if not isinstance(icon, dict) or not isinstance(privacy_policy, str):
+            raise _invalid_response()
+
+        response = self.api_client.post(
+            f"{_WORKFLOW_TOOL_PATH}/update",
+            json={
+                "workflow_tool_id": canonical_tool_id,
+                "name": merged_name,
+                "label": merged_label,
+                "description": merged_description,
+                "icon": deepcopy(icon),
+                "parameters": _derive_parameters(workflow),
+                "privacy_policy": privacy_policy,
+                "labels": labels,
+            },
+            profile=profile,
+        )
+        return _validated_write_response(response)
+
+    def resolve_agent_tool(
+        self,
+        workflow_tool_id: str,
+        tool_name: str,
+        parameters: dict[str, Any],
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        detail = self.get_tool(
+            workflow_tool_id=workflow_tool_id,
+            profile=profile,
+        )
+        if (
+            not _identifiers_match(
+                workflow_tool_id,
+                detail["workflow_tool_id"],
+            )
+            or detail["name"] != tool_name
+        ):
+            raise _tool_mismatch()
+
+        tool = detail.get("tool")
+        if tool is not None and not isinstance(tool, dict):
+            raise _invalid_response()
+        if isinstance(tool, dict):
+            discovered_name = tool.get("name")
+            if discovered_name is not None and discovered_name != tool_name:
+                raise _tool_mismatch()
+
+        definitions = (
+            tool.get("parameters")
+            if isinstance(tool, dict) and "parameters" in tool
+            else detail.get("parameters")
+        )
+        resolved_parameters = _resolve_parameters(definitions, parameters)
+        tool_label = _localized_label(
+            tool.get("label") if isinstance(tool, dict) else None
+        )
+        if tool_label is None:
+            tool_label = _non_empty_string(detail.get("label")) or tool_name
+
+        return {
+            "provider_type": "workflow",
+            "provider_id": _canonical_identifier(detail["workflow_tool_id"]),
+            "provider_name": detail["name"],
+            "tool_name": tool_name,
+            "tool_label": tool_label,
+            "tool_parameters": resolved_parameters,
+            "enabled": True,
+        }
+
+
+def _derive_parameters(workflow: Mapping[str, Any]) -> list[dict[str, str]]:
+    if not isinstance(workflow, Mapping):
+        raise _parameters_invalid()
+    inputs = workflow.get("inputs")
+    if not isinstance(inputs, Mapping):
+        raise _parameters_invalid()
+
+    parameters: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for name, configuration in inputs.items():
+        if (
+            not isinstance(name, str)
+            or _DIFY_SELECTOR.fullmatch(name) is None
+            or name in seen
+            or not isinstance(configuration, Mapping)
+            or configuration.get("type") not in _SUPPORTED_WORKFLOW_INPUT_TYPES
+        ):
+            raise _parameters_invalid()
+        description = configuration.get("description")
+        if description is not None and not isinstance(description, str):
+            raise _parameters_invalid()
+        seen.add(name)
+        parameters.append(
+            {
+                "name": name,
+                "description": description or name,
+                "form": "llm",
+                "required": bool(configuration.get("required", False)),
+            }
+        )
+    return parameters
+
+
+def _resolve_parameters(
+    definitions: Any,
+    supplied: dict[str, Any],
+) -> dict[str, Any]:
+    if (
+        not isinstance(definitions, list)
+        or any(not isinstance(item, dict) for item in definitions)
+        or not isinstance(supplied, dict)
+    ):
+        raise _invalid_response()
+
+    normalized_definitions: list[tuple[str, dict[str, Any]]] = []
+    seen: set[str] = set()
+    form_names: set[str] = set()
+    for definition in definitions:
+        name = definition.get("name")
+        form = definition.get("form")
+        parameter_type = definition.get("type", "string")
+        if (
+            not isinstance(name, str)
+            or _DIFY_SELECTOR.fullmatch(name) is None
+            or name in seen
+            or form not in {"llm", "form"}
+        ):
+            raise _invalid_response()
+        if parameter_type in _UNSUPPORTED_FILE_TYPES:
+            raise TacoError(
+                code="WORKFLOW_TOOL_FILE_PARAMETER_UNSUPPORTED",
+                message=f"Workflow Tool 参数 {name} 是不支持的文件类型。",
+                exit_code=6,
+            )
+        if parameter_type == "secret-input":
+            raise TacoError(
+                code="WORKFLOW_TOOL_SECRET_PARAMETER_UNSUPPORTED",
+                message=f"Workflow Tool 参数 {name} 是不能写入 Agent DSL 的密钥类型。",
+                exit_code=6,
+            )
+        seen.add(name)
+        if form == "form":
+            form_names.add(name)
+        normalized_definitions.append((name, definition))
+
+    unknown = sorted(set(supplied) - form_names)
+    if unknown:
+        raise _parameters_invalid("用户参数包含未发现的 form 字段。")
+
+    resolved: dict[str, Any] = {}
+    for name, definition in normalized_definitions:
+        if definition["form"] == "llm":
+            resolved[name] = ""
+            continue
+        if name in supplied:
+            value = supplied[name]
+        elif definition.get("default") is not None:
+            value = definition["default"]
+        elif definition.get("required"):
+            raise _parameters_invalid("缺少必填 form 参数。")
+        else:
+            continue
+        resolved[name] = _normalize_parameter(definition, value)
+    return resolved
+
+
+def _normalize_parameter(definition: dict[str, Any], value: Any) -> Any:
+    parameter_type = definition.get("type", "string")
+    valid = False
+    if parameter_type == "string":
+        valid = isinstance(value, str)
+    elif parameter_type == "number":
+        valid = (
+            isinstance(value, int | float)
+            and not isinstance(value, bool)
+            and (not isinstance(value, float) or math.isfinite(value))
+        )
+    elif parameter_type == "boolean":
+        valid = isinstance(value, bool)
+    elif parameter_type == "select":
+        options = definition.get("options") or []
+        if not isinstance(options, list):
+            raise _invalid_response()
+        choices = [
+            option.get("value") if isinstance(option, dict) else option
+            for option in options
+        ]
+        if any(not isinstance(choice, str) for choice in choices):
+            raise _invalid_response()
+        valid = isinstance(value, str) and (not choices or value in choices)
+    if not valid:
+        raise _parameters_invalid("form 参数类型或选项不合法。")
+    return value
+
+
+def _validate_detail_identity(payload: Any) -> None:
+    if not isinstance(payload, dict) or any(
+        _non_empty_string(payload.get(field)) is None
+        for field in ("workflow_tool_id", "workflow_app_id", "name")
+    ):
+        raise _invalid_response()
+
+
+def _identifiers_match(expected: str, actual: str) -> bool:
+    try:
+        expected_uuid = UUID(expected)
+        actual_uuid = UUID(actual)
+    except ValueError:
+        return expected == actual
+    return expected_uuid == actual_uuid
+
+
+def _canonical_identifier(identifier: str) -> str:
+    try:
+        return str(UUID(identifier))
+    except ValueError:
+        return identifier
+
+
+def _validated_write_response(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, dict) or payload.get("result") != "success":
+        raise _invalid_response()
+    return payload
+
+
+def _detail_labels(detail: dict[str, Any]) -> list[str]:
+    labels = detail.get("labels")
+    if labels is None:
+        tool = detail.get("tool")
+        labels = tool.get("labels") if isinstance(tool, dict) else []
+    if labels is None:
+        labels = []
+    if not isinstance(labels, list) or any(
+        not isinstance(item, str) for item in labels
+    ):
+        raise _invalid_response()
+    return list(labels)
+
+
+def _merged_string(
+    detail: dict[str, Any],
+    field: str,
+    override: str | None,
+    *,
+    allow_empty: bool = False,
+) -> str:
+    value = detail.get(field) if override is None else override
+    if not isinstance(value, str) or (not allow_empty and not value.strip()):
+        raise _invalid_response()
+    return value
+
+
+def _validate_machine_name(name: Any) -> None:
+    if not isinstance(name, str) or _TOOL_NAME.fullmatch(name) is None:
+        raise TacoError(
+            code="WORKFLOW_TOOL_NAME_INVALID",
+            message="Workflow Tool 机器名必须是 1-64 位 ASCII 字母、数字或下划线。",
+            exit_code=2,
+        )
+
+
+def _validate_label(label: Any) -> None:
+    if not isinstance(label, str) or not label.strip():
+        raise TacoError(
+            code="WORKFLOW_TOOL_LABEL_INVALID",
+            message="Workflow Tool label 不能为空。",
+            exit_code=2,
+        )
+
+
+def _validate_description(description: Any) -> None:
+    if not isinstance(description, str):
+        raise TacoError(
+            code="WORKFLOW_TOOL_DESCRIPTION_INVALID",
+            message="Workflow Tool description 必须是字符串。",
+            exit_code=2,
+        )
+
+
+def _localized_label(label: Any) -> str | None:
+    if isinstance(label, str):
+        return label or None
+    if isinstance(label, dict):
+        for locale in ("zh_Hans", "en_US"):
+            value = _non_empty_string(label.get(locale))
+            if value is not None:
+                return value
+    return None
+
+
+def _non_empty_string(value: Any) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    return value
+
+
+def _parameters_invalid(reason: str | None = None) -> TacoError:
+    message = "Workflow Tool 参数配置不合法。"
+    if reason:
+        message = f"{message}{reason}"
+    return TacoError(
+        code="WORKFLOW_TOOL_PARAMETERS_INVALID",
+        message=message,
+        exit_code=6,
+    )
+
+
+def _tool_mismatch() -> TacoError:
+    return TacoError(
+        code="WORKFLOW_TOOL_MISMATCH",
+        message="Workflow Tool 详情与请求的 tool ID 或名称不一致。",
+        exit_code=6,
+    )
+
+
+def _invalid_response() -> TacoError:
+    return TacoError(
+        code="WORKFLOW_TOOL_RESPONSE_INVALID",
+        message="Workflow Tool 接口返回结构不合法。",
+        exit_code=4,
+    )

tinet_agent_cli-0.1.0.dev36.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: tinet-agent-cli
+Version: 0.1.0.dev36
+Summary: Tinet Agent CLI Orchestrator
+Requires-Python: >=3.12
+Requires-Dist: filelock<4.0.0,>=3.32.5
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema<5.0.0,>=4.23.0
+Requires-Dist: pyyaml<7.0.0,>=6.0.2
+Requires-Dist: typer<0.27.0,>=0.26.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TACO：智能体平台 CLI
+
+TACO（Tinet Agent CLI Orchestrator）是天润智能体平台的命令行工具，可供开发者、自动化
+流水线，以及 Cursor、Codex、Claude Code 等 AI Agent 使用。
+
+它将智能体、应用和智能知识库能力组织成稳定、可发现的命令，并同时提供人工可读输出与 JSON
+输出。
+
+## 主要能力
+
+- 使用 profile 管理和切换企业授权
+- 查询、创建和管理智能体应用
+- 从应用模板创建应用
+- 拉取、校验、调试和发布智能体 DSL
+- 管理 Workflow、Chatflow 和智能体工具
+- 发现并调用 Agent OpenAPI
+- 发现并调用智能知识库 OpenAPI，包括文档上传
+- 向 AI Agent 提供命令、参数、场景和 Schema 的结构化说明
+
+## 安装
+
+要求 Python 3.12 或更高版本。推荐使用 `pipx` 安装：
+
+```bash
+pipx install tinet-agent-cli
+taco --version
+```
+
+也可以使用 `pip`：
+
+```bash
+python -m pip install tinet-agent-cli
+```
+
+## 配置授权
+
+使用前需要准备开发者中心 AccessKeyId 和 AccessKeySecret，并为接口密钥分配“智能体 > CLI
+授权”权限。
+
+CLINK2 endpoint 示例：
+
+- 北京平台：`https://api-bj.clink.cn`
+- 上海平台：`https://api-sh.clink.cn`
+
+创建 profile：
+
+```bash
+TACO_ACCESS_KEY_SECRET='<access-key-secret>' taco profile set \
+  --name clink-bj \
+  --endpoint https://api-bj.clink.cn \
+  --access-key-id '<access-key-id>'
+```
+
+列出 Zenava 和 TACO profile。带 `current=true` 的配置会优先展示，Zenava 当前配置排在 TACO
+当前配置之前：
+
+```bash
+taco --json profile list
+```
+
+多企业场景可以列出、切换 profile，或为单次命令指定 profile：
+
+```bash
+taco profile list
+taco profile use clink-bj
+taco --profile clink-sh --json agent app list
+```
+
+## 智能体
+
+### 应用与模板
+
+```bash
+taco agent app list --limit 20
+taco --json agent app get <app-id>
+taco agent app tag list --keyword 客服
+taco agent app template list
+taco agent app template create <template-app-id> --name 新应用 --yes
+```
+
+### 智能体 DSL
+
+```bash
+taco agent create \
+  --name 示例智能体 \
+  --category <category-code> \
+  --output agent.json \
+  --yes
+
+taco agent pull <app-id> --output agent.json
+taco agent validate --dsl agent.json
+taco agent publish <app-id> --dsl agent.json --yes
+```
+
+模型、分类、Workflow、Chatflow、工具和内置示例可以从 `taco agent --help` 继续发现。
+
+### Agent OpenAPI
+
+```bash
+taco agent operation search <关键词>
+taco agent operation describe <operation-id>
+taco --json agent call <operation-id> --param key=value
+```
+
+## 智能知识库
+
+```bash
+taco aikb operation search <关键词>
+taco aikb operation describe <operation-id>
+taco --json aikb call <operation-id> --param key=value
+```
+
+复杂参数可以通过 `--params-file` 或 `--body-file` 提供。文档上传 operation 支持使用 `--file`
+指定本地文件，由 TACO 完成上传流程。
+
+## 提供给 AI Agent 使用
+
+AI Agent 或 CI 推荐使用 `--json --no-input`，避免依赖终端文本或等待交互输入：
+
+```bash
+taco --json --no-input profile list
+taco --json --no-input agent app list --limit 10
+taco --json --no-input aikb operation search 文档
+```
+
+TACO 可以输出完整命令契约及内置场景：
+
+```bash
+taco help -o json
+taco agent scenario list -o json
+taco agent schema list -o json
+```
+
+推荐先搜索候选 operation，再查看参数契约，最后执行调用。远端创建、修改、删除、上传和发布
+操作应先取得用户批准，再显式传入 `--yes`。
+
+## 安全提示
+
+- 不要把 AccessKeySecret 或 token 写入代码、DSL、日志和对话内容。
+- 优先通过隐藏输入、环境变量或 CI 密钥管理提供 AccessKeySecret。
+- 写操作前确认当前 profile、目标资源和变更范围。
+- 自动化程序应判断退出码、`ok` 和 `error.code`。