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

taco/commands/workflow.py

@@ -0,0 +1,714 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import typer
+import yaml
+
+from taco.core.assets import load_json_asset
+from taco.core.context import get_cli_context
+from taco.core.errors import TacoError
+from taco.core.output import emit_success, exit_with_error, to_json_line
+from taco.core.secure_file import SecureFileReadError, read_regular_file
+from taco.services.workflow_compiler import (
+    compile_workflow,
+    compile_workflow_file,
+    load_workflow_file,
+    summarize_graph,
+)
+from taco.services.workflow_service import WorkflowService
+from taco.services.workflow_tool_service import WorkflowToolService
+
+
+workflow_app = typer.Typer(help="HTTP Workflow 本地 DSL 工具")
+workflow_secret_app = typer.Typer(help="Workflow secret 管理")
+workflow_tool_app = typer.Typer(help="Workflow Tool 发布、更新与查询")
+workflow_app.add_typer(workflow_secret_app, name="secret")
+workflow_app.add_typer(workflow_tool_app, name="tool")
+_MAX_INPUTS_FILE_SIZE = 1024 * 1024
+_MAX_INPUTS_DEPTH = 50
+_SECRET_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,29}$")
+
+
+@workflow_app.command("create", help="创建远端 Workflow 并初始化本地 YAML DSL。")
+def create_workflow(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", help="Workflow 名称。"),
+    description: str = typer.Option(
+        ...,
+        "--description",
+        help="Workflow 描述。",
+    ),
+    output: Path = typer.Option(
+        ...,
+        "--output",
+        help="本地 Workflow YAML 输出路径。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认创建远端 Workflow。"),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="允许覆盖已存在的本地 Workflow YAML。",
+    ),
+) -> None:
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_CREATE_CONFIRM_REQUIRED",
+                message="创建远端 Workflow 前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    temporary: Path | None = None
+    try:
+        _prepare_workflow_output(output, overwrite=overwrite)
+        workflow = load_json_asset("examples", "workflow-http")
+        workflow["name"] = name
+        workflow["description"] = description
+        temporary = _stage_workflow_yaml(output, workflow)
+        app = WorkflowService().create_workflow_app(
+            name,
+            description,
+            profile=cli_context.profile,
+        )
+        app_id = app.get("id")
+        if not isinstance(app_id, str) or not app_id.strip():
+            raise TacoError(
+                code="WORKFLOW_CREATE_RESPONSE_INVALID",
+                message="创建 Workflow 的响应缺少有效应用 ID。",
+                exit_code=4,
+            )
+        _commit_workflow_yaml(
+            temporary,
+            output,
+            overwrite=overwrite,
+            app_id=app_id,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    finally:
+        _cleanup_workflow_temporary(temporary)
+
+    emit_success(
+        ctx,
+        {
+            "app_id": app_id,
+            "name": app.get("name") if isinstance(app.get("name"), str) else name,
+            "path": str(output),
+        },
+        json_default=True,
+    )
+
+
+@workflow_app.command("apply", help="预览或同步本地 Workflow graph 到远端 draft。")
+def apply_workflow(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    file: Path = typer.Option(
+        ...,
+        "-f",
+        "--file",
+        help="本地 HTTP Workflow YAML 文件。",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="仅获取 draft 并输出变更计划。",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        help="确认同步远端 draft。",
+    ),
+) -> None:
+    if dry_run == yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_APPLY_MODE_REQUIRED",
+                message="workflow apply 必须且只能传入 --dry-run 或 --yes 之一。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    try:
+        graph = compile_workflow_file(file)
+        service = WorkflowService()
+        if dry_run:
+            result = service.plan_apply(
+                app_id,
+                graph,
+                profile=cli_context.profile,
+            )
+        else:
+            result = service.apply_draft(
+                app_id,
+                graph,
+                profile=cli_context.profile,
+            )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_app.command("run", help="通过 SSE 调试远端 Workflow draft。")
+def run_workflow(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    inputs_file: Path | None = typer.Option(
+        None,
+        "--inputs-file",
+        help="Workflow inputs JSON 对象文件。",
+    ),
+    query: str | None = typer.Option(
+        None,
+        "--query",
+        help="Chatflow（advanced-chat）调试时的用户问题。",
+    ),
+    stream_events: bool = typer.Option(
+        False,
+        "--stream-events",
+        help="实时输出 NDJSON 事件，便于获取 task_id。",
+    ),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    try:
+        inputs = _read_workflow_inputs(inputs_file) if inputs_file else {}
+        on_event = None
+        if stream_events:
+            on_event = _emit_workflow_stream_event
+        result = WorkflowService().run_draft(
+            app_id,
+            inputs,
+            on_event=on_event,
+            profile=cli_context.profile,
+            query=query,
+        )
+        if stream_events:
+            result = dict(result)
+            result.pop("events", None)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_app.command("stop", help="使用 task_id 停止 Workflow draft 调试任务。")
+def stop_workflow(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    task_id: str = typer.Option(..., "--task-id", help="SSE 返回的任务 ID。"),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    try:
+        result = WorkflowService().stop_run(
+            app_id,
+            task_id,
+            profile=cli_context.profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_app.command("publish", help="发布当前 Workflow draft。")
+def publish_workflow(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    title: str | None = typer.Option(
+        None,
+        "--title",
+        help="发布版本名称。",
+    ),
+    notes: str | None = typer.Option(
+        None,
+        "--notes",
+        help="发布说明。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认发布 Workflow。"),
+) -> None:
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_PUBLISH_CONFIRM_REQUIRED",
+                message="发布 Workflow 前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    try:
+        result = WorkflowService().publish(
+            app_id,
+            title,
+            notes,
+            profile=cli_context.profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_tool_app.command("get", help="按应用 ID 或 Tool ID 查询 Workflow Tool。")
+def get_workflow_tool(
+    ctx: typer.Context,
+    app_id: str | None = typer.Option(
+        None,
+        "--app-id",
+        help="已发布 Workflow 的应用 ID。",
+    ),
+    tool_id: str | None = typer.Option(
+        None,
+        "--tool-id",
+        help="Workflow Tool ID。",
+    ),
+) -> None:
+    if (app_id is None) == (tool_id is None):
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_TOOL_QUERY_INVALID",
+                message="查询 Workflow Tool 必须且只能提供 --app-id 或 --tool-id。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    try:
+        result = WorkflowToolService().get_tool(
+            workflow_app_id=app_id,
+            workflow_tool_id=tool_id,
+            profile=cli_context.profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_tool_app.command(
+    "publish",
+    help="把已发布 Workflow 注册为 Tool；不会自动发布 Workflow。",
+)
+def publish_workflow_tool(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="已发布 Workflow 的应用 ID。"),
+    file: Path = typer.Option(
+        ...,
+        "-f",
+        "--file",
+        help="本地 HTTP Workflow YAML 文件。",
+    ),
+    name: str = typer.Option(
+        ...,
+        "--name",
+        help="ASCII 字母、数字或下划线组成的 Tool 机器名。",
+    ),
+    label: str | None = typer.Option(
+        None,
+        "--label",
+        help="Tool 展示名，默认使用 DSL name。",
+    ),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="Tool 描述，默认使用 DSL description。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认发布 Workflow Tool。"),
+) -> None:
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_TOOL_PUBLISH_CONFIRM_REQUIRED",
+                message="发布 Workflow Tool 前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    try:
+        workflow = load_workflow_file(file)
+        compile_workflow(workflow)
+        result = WorkflowToolService().publish_tool(
+            app_id,
+            workflow,
+            name,
+            workflow["name"] if label is None else label,
+            workflow.get("description", "") if description is None else description,
+            profile=cli_context.profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_tool_app.command(
+    "update",
+    help="用本地 Workflow DSL 更新 Tool 配置；不会自动发布 Workflow。",
+)
+def update_workflow_tool(
+    ctx: typer.Context,
+    tool_id: str = typer.Argument(..., help="Workflow Tool ID。"),
+    file: Path = typer.Option(
+        ...,
+        "-f",
+        "--file",
+        help="本地 HTTP Workflow YAML 文件。",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        help="新的 Tool 机器名；省略时保留远端值。",
+    ),
+    label: str | None = typer.Option(
+        None,
+        "--label",
+        help="新的 Tool 展示名；省略时保留远端值。",
+    ),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="新的 Tool 描述；省略时保留远端值。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认更新 Workflow Tool。"),
+) -> None:
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_TOOL_UPDATE_CONFIRM_REQUIRED",
+                message="更新 Workflow Tool 前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    try:
+        workflow = load_workflow_file(file)
+        compile_workflow(workflow)
+        result = WorkflowToolService().update_tool(
+            tool_id,
+            workflow,
+            name=name,
+            label=label,
+            description=description,
+            profile=cli_context.profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(ctx, result, json_default=True)
+
+
+@workflow_secret_app.command("set", help="从环境变量设置远端 Workflow secret。")
+def set_workflow_secret(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    name: str = typer.Argument(..., help="Dify 环境变量 selector。"),
+    from_env: str = typer.Option(
+        ...,
+        "--from-env",
+        help="读取 secret 值的本地环境变量名。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认更新远端 secret。"),
+) -> None:
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_SECRET_CONFIRM_REQUIRED",
+                message="更新 Workflow secret 前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+    if _SECRET_NAME.fullmatch(name) is None:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_SECRET_NAME_INVALID",
+                message="Workflow secret name 不符合 Dify selector 规则。",
+                exit_code=2,
+                hint="请使用字母或下划线开头、最长 30 位的字母数字下划线。",
+            ),
+            json_default=True,
+        )
+
+    value = os.environ.get(from_env)
+    if value is None or value == "":
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="WORKFLOW_SECRET_ENV_REQUIRED",
+                message="指定环境变量不存在或值为空。",
+                exit_code=2,
+                hint="请先在当前进程环境中设置 --from-env 指定的变量。",
+            ),
+            json_default=True,
+        )
+
+    cli_context = get_cli_context(ctx)
+    try:
+        result = WorkflowService().set_secret(
+            app_id,
+            name,
+            value,
+            profile=cli_context.profile,
+        )
+        action = result.get("action") if isinstance(result, dict) else None
+        if action not in {"created", "updated"}:
+            raise TacoError(
+                code="WORKFLOW_SECRET_RESPONSE_INVALID",
+                message="Workflow secret 更新响应格式不合法。",
+                exit_code=4,
+            )
+    except TacoError as error:
+        exit_with_error(
+            ctx,
+            _redact_secret_error(error, value),
+            json_default=True,
+        )
+
+    emit_success(
+        ctx,
+        {
+            "app_id": app_id,
+            "name": name,
+            "action": action,
+        },
+        json_default=True,
+    )
+
+
+@workflow_app.command("validate", help="校验 YAML DSL 并本地编译为 Dify graph。")
+def validate_workflow(
+    ctx: typer.Context,
+    file: Path = typer.Option(
+        ...,
+        "-f",
+        "--file",
+        help="本地 HTTP Workflow YAML 文件。",
+    ),
+) -> None:
+    try:
+        graph = compile_workflow_file(file)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(
+        ctx,
+        {
+            "valid": True,
+            "path": str(file),
+            "graph_summary": summarize_graph(graph),
+        },
+        json_default=True,
+    )
+
+
+def _prepare_workflow_output(path: Path, *, overwrite: bool) -> None:
+    if path.is_symlink():
+        raise TacoError(
+            code="WORKFLOW_DSL_PATH_INVALID",
+            message="Workflow DSL 输出不能是符号链接。",
+            exit_code=2,
+            hint="请使用普通文件路径。",
+        )
+    if path.exists():
+        if not path.is_file():
+            raise TacoError(
+                code="WORKFLOW_DSL_PATH_INVALID",
+                message="Workflow DSL 输出必须是普通文件路径。",
+                exit_code=2,
+            )
+        if not overwrite:
+            raise TacoError(
+                code="WORKFLOW_DSL_EXISTS",
+                message="本地 Workflow DSL 已存在。",
+                exit_code=2,
+                hint="确认覆盖后传入 --overwrite --yes。",
+            )
+        if not os.access(path, os.W_OK):
+            raise TacoError(
+                code="WORKFLOW_DSL_PATH_INVALID",
+                message="本地 Workflow DSL 不可覆盖。",
+                exit_code=2,
+            )
+
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            dir=path.parent,
+            prefix=".taco-workflow-write-check-",
+        ):
+            pass
+    except OSError as error:
+        raise TacoError(
+            code="WORKFLOW_DSL_WRITE_FAILED",
+            message="创建远端 Workflow 前无法确认本地 DSL 目录可写。",
+            exit_code=2,
+            hint="请检查输出目录权限和磁盘空间。",
+        ) from error
+
+
+def _emit_workflow_stream_event(event: dict[str, Any]) -> None:
+    typer.echo(to_json_line({"type": "event", "event": event}))
+
+
+def _stage_workflow_yaml(path: Path, payload: dict[str, Any]) -> Path:
+    temporary: Path | None = None
+    try:
+        content = yaml.safe_dump(
+            payload,
+            allow_unicode=True,
+            sort_keys=False,
+        )
+        descriptor, temporary_name = tempfile.mkstemp(
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            text=True,
+        )
+        temporary = Path(temporary_name)
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as file:
+            file.write(content)
+            file.flush()
+            os.fsync(file.fileno())
+        return temporary
+    except (OSError, yaml.YAMLError) as error:
+        _cleanup_workflow_temporary(temporary)
+        raise TacoError(
+            code="WORKFLOW_DSL_WRITE_FAILED",
+            message="无法准备 Workflow DSL 临时文件。",
+            exit_code=2,
+            hint="请检查输出目录权限和磁盘空间。",
+        ) from error
+
+
+def _commit_workflow_yaml(
+    temporary: Path,
+    path: Path,
+    *,
+    overwrite: bool,
+    app_id: str,
+) -> None:
+    try:
+        if overwrite:
+            os.replace(temporary, path)
+        else:
+            os.link(temporary, path)
+    except OSError as error:
+        raise TacoError(
+            code="WORKFLOW_DSL_WRITE_FAILED",
+            message="远端 Workflow 已创建，但本地 DSL 提交失败。",
+            exit_code=2,
+            hint="请使用错误中的 app_id 恢复本地文件，避免重复创建应用。",
+            app_id=app_id,
+        ) from error
+
+
+def _cleanup_workflow_temporary(temporary: Path | None) -> None:
+    if temporary is None:
+        return
+    try:
+        temporary.unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _read_workflow_inputs(path: Path) -> dict[str, Any]:
+    try:
+        raw_content = read_regular_file(
+            path,
+            max_bytes=_MAX_INPUTS_FILE_SIZE,
+        )
+        content = raw_content.decode("utf-8")
+        payload = json.loads(
+            content,
+            parse_constant=_reject_json_constant,
+        )
+        if not isinstance(payload, dict):
+            raise _inputs_error("inputs JSON 必须是对象。")
+        _validate_inputs_structure(payload)
+        return payload
+    except SecureFileReadError as error:
+        reasons = {
+            "symlink": "输入文件不能是符号链接。",
+            "not_regular": "输入路径不是普通文件。",
+            "too_large": "输入文件最大允许 1 MiB。",
+            "changed": "输入文件在安全打开期间发生变化。",
+            "unreadable": "输入文件不存在或不可读。",
+        }
+        raise _inputs_error(
+            reasons.get(error.reason, "输入文件不可安全读取。")
+        ) from error
+    except TacoError:
+        raise
+    except (OSError, UnicodeError, ValueError, RecursionError) as error:
+        raise _inputs_error("文件不可读或不是合法 JSON。") from error
+
+
+def _validate_inputs_structure(value: Any, *, depth: int = 0) -> None:
+    if depth > _MAX_INPUTS_DEPTH:
+        raise _inputs_error("inputs JSON 嵌套层级过深。")
+    if value is None or isinstance(value, (str, bool, int)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise _inputs_error("inputs JSON 包含非有限数值。")
+        return
+    if isinstance(value, list):
+        for item in value:
+            _validate_inputs_structure(item, depth=depth + 1)
+        return
+    if isinstance(value, dict):
+        for item in value.values():
+            _validate_inputs_structure(item, depth=depth + 1)
+        return
+    raise _inputs_error("inputs JSON 包含不支持的数据类型。")
+
+
+def _reject_json_constant(_: str) -> None:
+    raise ValueError("non-standard JSON constant")
+
+
+def _inputs_error(reason: str) -> TacoError:
+    return TacoError(
+        code="WORKFLOW_INPUTS_INVALID",
+        message=f"Workflow inputs 无效：{reason}",
+        exit_code=2,
+        hint="请提供不超过 1 MiB 的普通 JSON object 文件。",
+    )
+
+
+def _redact_secret_error(error: TacoError, value: str) -> TacoError:
+    if value not in error.message and (
+        error.hint is None or value not in error.hint
+    ):
+        return error
+    return TacoError(
+        code="WORKFLOW_SECRET_UPDATE_FAILED",
+        message="Workflow secret 更新失败。",
+        exit_code=error.exit_code,
+        status=error.status,
+        hint="请检查认证、网络和 draft 状态后重试。",
+    )

taco/core/__init__.py

@@ -0,0 +1 @@
+"""Core primitives for TACO."""