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

taco/services/workflow_service.py

@@ -0,0 +1,652 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Mapping
+from uuid import uuid4
+
+from taco.core.api_client import ApiClient
+from taco.core.errors import TacoError
+from taco.services.workflow_compiler import summarize_graph
+
+
+_DEFAULT_FEATURES = {"retriever_resource": {"enabled": True}}
+_SAFE_APPLY_RESPONSE_FIELDS = ("result", "hash", "updated_at")
+_HIDDEN_SECRET_VALUE = "[__HIDDEN__]"
+_MAX_STORED_EVENTS = 1000
+_SAFE_EVENT_TOP_LEVEL_FIELDS = ("event", "task_id", "workflow_run_id")
+_SAFE_EVENT_DATA_FIELDS = (
+    "id",
+    "workflow_id",
+    "node_id",
+    "node_execution_id",
+    "node_type",
+    "status",
+    "index",
+    "sequence",
+    "sequence_number",
+    "iteration_id",
+    "iteration_index",
+    "loop_id",
+    "loop_index",
+    "parallel_id",
+    "parallel_start_node_id",
+    "predecessor_node_id",
+    "retry_index",
+    "created_at",
+    "started_at",
+    "finished_at",
+    "elapsed_time",
+    "total_steps",
+    "total_tokens",
+)
+
+
+class WorkflowService:
+    def __init__(self, api_client: ApiClient | None = None) -> None:
+        self.api_client = api_client or ApiClient()
+
+    def create_workflow_app(
+        self,
+        name: str,
+        description: str,
+        profile: str | None = None,
+        *,
+        mode: str = "workflow",
+    ) -> dict[str, Any]:
+        if mode not in {"workflow", "advanced-chat"}:
+            raise TacoError(
+                code="WORKFLOW_MODE_INVALID",
+                message="应用 mode 仅支持 workflow 或 advanced-chat。",
+                exit_code=2,
+            )
+        icon = "💬" if mode == "advanced-chat" else "🔀"
+        app = self.api_client.post(
+            "/apps",
+            json={
+                "name": name,
+                "description": description,
+                "mode": mode,
+                "icon_type": "emoji",
+                "icon": icon,
+                "icon_background": "#E4FBCC",
+            },
+            profile=profile,
+        )
+        if (
+            not isinstance(app, dict)
+            or not isinstance(app.get("id"), str)
+            or not app["id"].strip()
+        ):
+            raise TacoError(
+                code="WORKFLOW_CREATE_RESPONSE_INVALID",
+                message="创建 Workflow 的响应缺少有效应用 ID。",
+                exit_code=4,
+                hint="请检查 Console API 版本和响应格式。",
+            )
+        return app
+
+    def get_app(
+        self,
+        app_id: str,
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        app = self.api_client.get(f"/apps/{app_id}", profile=profile)
+        if not isinstance(app, dict):
+            raise TacoError(
+                code="WORKFLOW_APP_RESPONSE_INVALID",
+                message="读取应用详情的响应格式不合法。",
+                exit_code=4,
+            )
+        return app
+
+    def get_draft(
+        self,
+        app_id: str,
+        profile: str | None = None,
+    ) -> dict[str, Any] | None:
+        try:
+            draft = self.api_client.get(
+                f"/apps/{app_id}/workflows/draft",
+                profile=profile,
+            )
+        except TacoError as error:
+            if (
+                error.status == 400
+                and error.remote_code == "draft_workflow_not_exist"
+            ):
+                return None
+            raise
+        if not isinstance(draft, dict):
+            raise _invalid_draft_response()
+        return draft
+
+    def plan_apply(
+        self,
+        app_id: str,
+        graph: Mapping[str, Any],
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        proposed_graph = _validated_graph(graph)
+        draft = self.get_draft(app_id, profile=profile)
+        current_graph = None if draft is None else _draft_graph(draft)
+        return {
+            "app_id": app_id,
+            "action": "create" if draft is None else "update",
+            "changed": (
+                True
+                if current_graph is None
+                else _canonical_graph(current_graph)
+                != _canonical_graph(proposed_graph)
+            ),
+            "current": (
+                None if current_graph is None else summarize_graph(current_graph)
+            ),
+            "proposed": summarize_graph(proposed_graph),
+            "draft_hash": draft.get("hash") if draft is not None else None,
+        }
+
+    def apply_draft(
+        self,
+        app_id: str,
+        graph: Mapping[str, Any],
+        profile: str | None = None,
+    ) -> dict[str, Any]:
+        proposed_graph = _validated_graph(graph)
+        initial_draft = self.get_draft(app_id, profile=profile)
+        initial_snapshot = _draft_metadata_snapshot(initial_draft)
+        _build_apply_payload(proposed_graph, initial_draft)
+
+        confirmed_draft = self.get_draft(app_id, profile=profile)
+        _verify_draft_metadata_unchanged(
+            initial_snapshot,
+            confirmed_draft,
+        )
+        payload = _build_apply_payload(proposed_graph, confirmed_draft)
+
+        # Dify metadata has no CAS token. This second read only narrows the race
+        # window; the hash sent below still provides server-side graph/features CAS.
+        response = self.api_client.post(
+            f"/apps/{app_id}/workflows/draft",
+            json=payload,
+            profile=profile,
+        )
+        if not isinstance(response, dict):
+            raise TacoError(
+                code="WORKFLOW_APPLY_RESPONSE_INVALID",
+                message="同步 Workflow draft 的响应格式不合法。",
+                exit_code=4,
+                hint="请检查 Console API 版本和响应格式。",
+            )
+        result = {
+            "app_id": app_id,
+            "applied": True,
+            "graph_summary": summarize_graph(proposed_graph),
+        }
+        for key in _SAFE_APPLY_RESPONSE_FIELDS:
+            value = response.get(key)
+            if key in response and _is_safe_metadata_value(value):
+                result[key] = value
+        return result
+
+    def run_draft(
+        self,
+        app_id: str,
+        inputs: dict[str, Any],
+        on_event: Callable[[dict[str, Any]], None] | None = None,
+        profile: str | None = None,
+        *,
+        query: str | None = None,
+    ) -> dict[str, Any]:
+        if not isinstance(inputs, dict):
+            raise TacoError(
+                code="WORKFLOW_INPUTS_INVALID",
+                message="Workflow inputs 必须是 JSON 对象。",
+                exit_code=2,
+            )
+
+        app = self.get_app(app_id, profile=profile)
+        mode = app.get("mode")
+        if mode == "advanced-chat":
+            run_path = f"/apps/{app_id}/advanced-chat/workflows/draft/run"
+            payload: dict[str, Any] = {
+                "inputs": inputs,
+                "query": query if query is not None else "",
+                "files": [],
+            }
+        else:
+            run_path = f"/apps/{app_id}/workflows/draft/run"
+            payload = {"inputs": inputs, "files": []}
+
+        stream = self.api_client.stream(
+            "POST",
+            run_path,
+            json=payload,
+            profile=profile,
+        )
+        events: list[dict[str, Any]] = []
+        events_truncated = False
+        identifiers: dict[str, Any] = {}
+        finished_data: dict[str, Any] | None = None
+        try:
+            for sse_event in stream:
+                event = _normalize_sse_event(sse_event)
+                event_type = event.get("event")
+                if event_type == "error":
+                    raise _run_failed_error()
+
+                if event_type == "workflow_started":
+                    for key in ("task_id", "workflow_run_id"):
+                        if _is_safe_metadata_value(event.get(key)) and event.get(key):
+                            identifiers[key] = event[key]
+
+                if event_type == "workflow_finished":
+                    data = event.get("data")
+                    finished_data = dict(data) if isinstance(data, dict) else {}
+                    status = finished_data.get("status")
+                    if status not in {"succeeded", "success"}:
+                        raise _run_failed_error()
+
+                safe_event = _safe_sse_event(event)
+                if len(events) < _MAX_STORED_EVENTS:
+                    events.append(safe_event)
+                else:
+                    events_truncated = True
+                if on_event is not None:
+                    on_event(safe_event)
+                if finished_data is not None:
+                    break
+        except TacoError as error:
+            if error.code == "WORKFLOW_RUN_FAILED" or _is_local_preflight_error(
+                error
+            ):
+                raise
+            raise _run_failed_error() from None
+        finally:
+            close = getattr(stream, "close", None)
+            if callable(close):
+                close()
+
+        if finished_data is None:
+            raise TacoError(
+                code="WORKFLOW_RUN_INCOMPLETE",
+                message="Workflow 调试流在 workflow_finished 前结束。",
+                exit_code=5,
+                hint="请检查网络和服务端日志后重试。",
+            )
+
+        result = _safe_sse_data(finished_data)
+        if "outputs" in finished_data:
+            result["outputs"] = finished_data["outputs"]
+        result.update(identifiers)
+        result["events"] = events
+        result["events_truncated"] = events_truncated
+        return result
+
+    def stop_run(
+        self,
+        app_id: str,
+        task_id: str,
+        profile: str | None = None,
+    ) -> Any:
+        return self.api_client.post(
+            f"/apps/{app_id}/workflow-runs/tasks/{task_id}/stop",
+            profile=profile,
+        )
+
+    def publish(
+        self,
+        app_id: str,
+        title: str | None = None,
+        notes: str | None = None,
+        profile: str | None = None,
+    ) -> Any:
+        return self.api_client.post(
+            f"/apps/{app_id}/workflows/publish",
+            json={
+                "marked_name": title or "",
+                "marked_comment": notes or "",
+            },
+            profile=profile,
+        )
+
+    def set_secret(
+        self,
+        app_id: str,
+        name: str,
+        value: str,
+        profile: str | None = None,
+    ) -> dict[str, str]:
+        if value == _HIDDEN_SECRET_VALUE:
+            raise TacoError(
+                code="WORKFLOW_SECRET_VALUE_RESERVED",
+                message="该 Workflow secret 值是 Dify 保留占位符，不能用于更新。",
+                exit_code=2,
+                hint="请提供真实的新 secret 值。",
+            )
+
+        try:
+            draft = self.get_draft(app_id, profile=profile)
+        except TacoError as error:
+            if _is_local_preflight_error(error):
+                raise
+            raise _secret_update_failed_error() from None
+
+        if draft is None:
+            raise TacoError(
+                code="WORKFLOW_DRAFT_REQUIRED",
+                message="Workflow 尚无 draft，请先执行 workflow apply。",
+                exit_code=6,
+            )
+
+        try:
+            initial_snapshot = _draft_metadata_snapshot(draft)
+            _, action, new_secret_id = _build_secret_update_payload(
+                draft,
+                name,
+                value,
+            )
+
+            confirmed_draft = self.get_draft(app_id, profile=profile)
+            _verify_draft_metadata_unchanged(
+                initial_snapshot,
+                confirmed_draft,
+            )
+            if confirmed_draft is None:
+                raise _draft_out_of_sync_error()
+            payload, action, _ = _build_secret_update_payload(
+                confirmed_draft,
+                name,
+                value,
+                new_secret_id=new_secret_id,
+            )
+
+            # The hash protects graph/features on POST. Dify offers no metadata
+            # CAS, so environment/conversation changes after this GET remain possible.
+            self.api_client.post(
+                f"/apps/{app_id}/workflows/draft",
+                json=payload,
+                profile=profile,
+            )
+        except TacoError as error:
+            if error.code in {
+                "WORKFLOW_SECRET_NAME_CONFLICT",
+                "WORKFLOW_DRAFT_OUT_OF_SYNC",
+            }:
+                raise
+            if _is_local_preflight_error(error):
+                raise
+            raise _secret_update_failed_error() from None
+
+        return {
+            "app_id": app_id,
+            "name": name,
+            "action": action,
+        }
+
+
+def _validated_graph(graph: Mapping[str, Any]) -> dict[str, Any]:
+    if not isinstance(graph, dict):
+        raise TacoError(
+            code="WORKFLOW_GRAPH_INVALID",
+            message="Workflow graph 必须是对象。",
+            exit_code=6,
+        )
+    _canonical_graph(graph)
+    return graph
+
+
+def _canonical_graph(graph: Mapping[str, Any]) -> str:
+    try:
+        return json.dumps(
+            graph,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+            allow_nan=False,
+        )
+    except (TypeError, ValueError, RecursionError) as error:
+        raise TacoError(
+            code="WORKFLOW_GRAPH_INVALID",
+            message="Workflow graph 不是合法 JSON 对象。",
+            exit_code=6,
+        ) from error
+
+
+def _build_apply_payload(
+    graph: dict[str, Any],
+    draft: dict[str, Any] | None,
+) -> dict[str, Any]:
+    if draft is None:
+        return {
+            "graph": graph,
+            "features": _DEFAULT_FEATURES,
+            "environment_variables": [],
+            "conversation_variables": [],
+        }
+    payload = {
+        "graph": graph,
+        "features": _draft_mapping(draft, "features"),
+        "environment_variables": _safe_environment_variables(
+            _draft_environment_variables(draft),
+        ),
+        "conversation_variables": _draft_list(
+            draft,
+            "conversation_variables",
+        ),
+    }
+    if draft.get("hash") is not None:
+        payload["hash"] = draft["hash"]
+    return payload
+
+
+def _build_secret_update_payload(
+    draft: dict[str, Any],
+    name: str,
+    value: str,
+    *,
+    new_secret_id: str | None = None,
+) -> tuple[dict[str, Any], str, str | None]:
+    graph = _draft_graph(draft)
+    features = _draft_mapping(draft, "features")
+    environment_variables = _draft_environment_variables(draft)
+    conversation_variables = _draft_list(draft, "conversation_variables")
+    matching = [
+        variable
+        for variable in environment_variables
+        if variable.get("name") == name
+    ]
+    if len(matching) > 1 or any(
+        variable.get("value_type") != "secret" for variable in matching
+    ):
+        raise TacoError(
+            code="WORKFLOW_SECRET_NAME_CONFLICT",
+            message="同名环境变量不唯一或不是 secret。",
+            exit_code=6,
+            hint="请更换 secret 名称，或先在 Dify 中处理同名变量。",
+        )
+
+    action = "updated" if matching else "created"
+    if matching:
+        updated_variables = _safe_environment_variables(
+            environment_variables,
+            target=matching[0],
+            target_value=value,
+        )
+    else:
+        if new_secret_id is None:
+            new_secret_id = str(uuid4())
+        updated_variables = [
+            *_safe_environment_variables(environment_variables),
+            {
+                "id": new_secret_id,
+                "name": name,
+                "value": value,
+                "value_type": "secret",
+            },
+        ]
+
+    payload: dict[str, Any] = {
+        "graph": graph,
+        "features": features,
+        "environment_variables": updated_variables,
+        "conversation_variables": conversation_variables,
+    }
+    if draft.get("hash") is not None:
+        payload["hash"] = draft["hash"]
+    return payload, action, new_secret_id
+
+
+def _draft_metadata_snapshot(draft: dict[str, Any] | None) -> str | None:
+    if draft is None:
+        return None
+    metadata = {
+        "hash_present": "hash" in draft,
+        "hash": draft.get("hash"),
+        "environment_variables": _draft_environment_variables(draft),
+        "conversation_variables": _draft_list(draft, "conversation_variables"),
+    }
+    try:
+        return json.dumps(
+            metadata,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+            allow_nan=False,
+        )
+    except (TypeError, ValueError, RecursionError) as error:
+        raise _invalid_draft_response() from error
+
+
+def _verify_draft_metadata_unchanged(
+    initial_snapshot: str | None,
+    confirmed_draft: dict[str, Any] | None,
+) -> None:
+    if initial_snapshot != _draft_metadata_snapshot(confirmed_draft):
+        raise _draft_out_of_sync_error()
+
+
+def _draft_graph(draft: dict[str, Any]) -> dict[str, Any]:
+    graph = draft.get("graph")
+    if not isinstance(graph, dict):
+        raise _invalid_draft_response()
+    return graph
+
+
+def _draft_mapping(draft: dict[str, Any], field: str) -> dict[str, Any]:
+    value = draft.get(field)
+    if not isinstance(value, dict):
+        raise _invalid_draft_response()
+    return value
+
+
+def _draft_list(draft: dict[str, Any], field: str) -> list[Any]:
+    value = draft.get(field)
+    if not isinstance(value, list):
+        raise _invalid_draft_response()
+    return value
+
+
+def _draft_environment_variables(
+    draft: dict[str, Any],
+) -> list[dict[str, Any]]:
+    variables = _draft_list(draft, "environment_variables")
+    if any(not isinstance(variable, dict) for variable in variables):
+        raise _invalid_draft_response()
+    return variables
+
+
+def _safe_environment_variables(
+    variables: list[dict[str, Any]],
+    *,
+    target: dict[str, Any] | None = None,
+    target_value: str | None = None,
+) -> list[dict[str, Any]]:
+    safe_variables: list[dict[str, Any]] = []
+    for variable in variables:
+        if variable.get("value_type") != "secret":
+            safe_variables.append(variable)
+            continue
+        safe_variable = dict(variable)
+        safe_variable["value"] = (
+            target_value if variable is target else _HIDDEN_SECRET_VALUE
+        )
+        safe_variables.append(safe_variable)
+    return safe_variables
+
+
+def _is_safe_metadata_value(value: Any) -> bool:
+    return value is None or isinstance(value, (str, bool, int, float))
+
+
+def _normalize_sse_event(sse_event: Any) -> dict[str, Any]:
+    if isinstance(sse_event.data, dict):
+        event = dict(sse_event.data)
+    else:
+        event = {"data": sse_event.data}
+    if sse_event.event and "event" not in event:
+        event["event"] = sse_event.event
+    if sse_event.id is not None:
+        event["sse_id"] = sse_event.id
+    return event
+
+
+def _safe_sse_event(event: dict[str, Any]) -> dict[str, Any]:
+    safe_event = {
+        key: event[key]
+        for key in _SAFE_EVENT_TOP_LEVEL_FIELDS
+        if key in event and _is_safe_metadata_value(event[key])
+    }
+    data = event.get("data")
+    if isinstance(data, dict):
+        safe_data = _safe_sse_data(data)
+        if safe_data:
+            safe_event["data"] = safe_data
+    return safe_event
+
+
+def _safe_sse_data(data: dict[str, Any]) -> dict[str, Any]:
+    return {
+        key: data[key]
+        for key in _SAFE_EVENT_DATA_FIELDS
+        if key in data and _is_safe_metadata_value(data[key])
+    }
+
+
+def _run_failed_error() -> TacoError:
+    return TacoError(
+        code="WORKFLOW_RUN_FAILED",
+        message="Workflow draft 调试失败。",
+        exit_code=5,
+        hint="请检查 draft 配置和服务端日志。",
+    )
+
+
+def _secret_update_failed_error() -> TacoError:
+    return TacoError(
+        code="WORKFLOW_SECRET_UPDATE_FAILED",
+        message="Workflow secret 更新失败。",
+        exit_code=4,
+        hint="请检查认证、网络和 draft 状态后重试。",
+    )
+
+
+def _draft_out_of_sync_error() -> TacoError:
+    return TacoError(
+        code="WORKFLOW_DRAFT_OUT_OF_SYNC",
+        message="Workflow draft 在写入前已发生变化，本次未同步。",
+        exit_code=7,
+        hint="请重新获取 draft 后重试。",
+    )
+
+
+def _is_local_preflight_error(error: TacoError) -> bool:
+    return error.code.startswith(("AUTH_", "CONFIG_"))
+
+
+def _invalid_draft_response() -> TacoError:
+    return TacoError(
+        code="WORKFLOW_DRAFT_RESPONSE_INVALID",
+        message="Workflow draft 响应格式不合法。",
+        exit_code=4,
+        hint="请检查 Console API 版本和响应格式。",
+    )