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

taco/commands/agent.py

@@ -0,0 +1,760 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from json import JSONDecodeError
+from pathlib import Path
+from typing import Any
+from uuid import UUID, uuid4
+
+import typer
+
+from taco.commands.app import app_app
+from taco.commands.category import category_app
+from taco.commands.chatflow import chatflow_app
+from taco.commands.credential import credential_app
+from taco.commands.discovery import example_app, scenario_app, schema_app, skills_app
+from taco.commands.model import model_app
+from taco.commands.tool import tool_app
+from taco.commands.workflow import workflow_app
+from taco.agent_openapi.catalog import load_catalog, operation_not_found
+from taco.agent_openapi.models import thaw
+from taco.agent_openapi.parameters import parse_parameters
+from taco.agent_openapi.service import AgentOpenApiService
+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.services.agent_service import (
+    AgentService,
+    validate_agent_config,
+    validate_completion_params,
+)
+from taco.services.model_service import ModelService
+from taco.services.tool_service import ToolService
+from taco.services.workflow_tool_service import WorkflowToolService
+
+
+agent_app = typer.Typer(help="Agent 智能体管理")
+agent_tool_app = typer.Typer(help="本地 Agent DSL 工具挂载")
+agent_operation_app = typer.Typer(help="发现 Agent 数据 OpenAPI operation")
+agent_app.add_typer(agent_tool_app, name="tool")
+agent_app.add_typer(agent_operation_app, name="operation")
+agent_app.add_typer(app_app, name="app")
+agent_app.add_typer(category_app, name="category")
+agent_app.add_typer(model_app, name="model")
+agent_app.add_typer(workflow_app, name="workflow")
+agent_app.add_typer(chatflow_app, name="chatflow")
+agent_app.add_typer(example_app, name="example")
+agent_app.add_typer(scenario_app, name="scenario")
+agent_app.add_typer(skills_app, name="skills")
+agent_app.add_typer(schema_app, name="schema")
+agent_tool_app.add_typer(tool_app, name="catalog")
+agent_tool_app.add_typer(credential_app, name="credential")
+
+
+@agent_operation_app.command("list", help="列出 Agent 数据 OpenAPI operation。")
+def list_agent_operations(
+    ctx: typer.Context,
+    group: str | None = typer.Option(None, "--group", help="按分组筛选。"),
+) -> None:
+    operations = [
+        _agent_operation_summary(item)
+        for item in load_catalog().operations
+        if group is None or item.group == group
+    ]
+    emit_success(ctx, operations, json_default=True)
+
+
+@agent_operation_app.command("search", help="按关键词搜索 Agent 数据 OpenAPI operation。")
+def search_agent_operations(ctx: typer.Context, query: str = typer.Argument(...)) -> None:
+    needle = query.casefold()
+    matches = []
+    for operation in load_catalog().operations:
+        haystack = " ".join(
+            [operation.id, operation.title, operation.description, *operation.keywords]
+        ).casefold()
+        if needle in haystack:
+            matches.append(_agent_operation_summary(operation))
+    emit_success(ctx, matches[:10], json_default=True)
+
+
+@agent_operation_app.command("describe", help="查看 Agent 数据 OpenAPI operation 完整契约。")
+def describe_agent_operation(
+    ctx: typer.Context,
+    operation_id: str = typer.Argument(...),
+) -> None:
+    operation = load_catalog().by_id.get(operation_id)
+    if operation is None:
+        exit_with_error(ctx, operation_not_found(operation_id), json_default=True)
+    emit_success(
+        ctx,
+        {
+            **_agent_operation_summary(operation),
+            "description": operation.description,
+            "keywords": list(operation.keywords),
+            "http": thaw(operation.http),
+            "response": thaw(operation.response),
+            "risk": thaw(operation.risk),
+            "execution": thaw(operation.execution),
+            "examples": thaw(operation.examples),
+        },
+        json_default=True,
+    )
+
+
+@agent_app.command("call", help="校验参数并执行 Agent 数据 OpenAPI operation。")
+def call_agent_operation(
+    ctx: typer.Context,
+    operation_id: str = typer.Argument(...),
+    param: list[str] | None = typer.Option(
+        None,
+        "--param",
+        help="语义参数 key=value，可重复。",
+    ),
+    params_file: Path | None = typer.Option(
+        None,
+        "--params-file",
+        help="语义参数 JSON 文件。",
+    ),
+    body_file: Path | None = typer.Option(
+        None,
+        "--body-file",
+        help="JSON body 文件。",
+    ),
+) -> None:
+    operation = load_catalog().by_id.get(operation_id)
+    if operation is None:
+        exit_with_error(ctx, operation_not_found(operation_id), json_default=True)
+    try:
+        query, body = parse_parameters(
+            operation,
+            params=param,
+            params_file=params_file,
+            body_file=body_file,
+        )
+        result = AgentOpenApiService().call(
+            operation_id,
+            query=query,
+            body=body,
+            profile=get_cli_context(ctx).profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(ctx, result, json_default=True)
+
+
+def _agent_operation_summary(operation) -> dict[str, Any]:
+    return {
+        "id": operation.id,
+        "title": operation.title,
+        "group": operation.group,
+        "method": operation.http["method"],
+        "path": operation.http["path"],
+        "risk": operation.risk["level"],
+    }
+
+
+@agent_app.command("create", help="创建 Agent 并把服务端默认配置写入本地 DSL。")
+def create_agent(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", help="智能体名称。"),
+    category: str = typer.Option(..., "--category", help="服务端分类 code。"),
+    description: str = typer.Option("", "--description", help="智能体描述。"),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        help="本地 Agent DSL JSON 输出路径，默认生成唯一文件名。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认创建远端 Agent。"),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="允许覆盖已存在的本地 DSL，仍需 --yes。",
+    ),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="AGENT_CREATE_CONFIRM_REQUIRED",
+                message="创建远端 Agent 前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+    try:
+        target = output or Path(f"taco-agent-{uuid4()}.json")
+        _prepare_agent_output(target, overwrite=overwrite)
+        app = AgentService().create_agent(
+            name=name,
+            category=category,
+            description=description,
+            profile=cli_context.profile,
+        )
+        app_id = app.get("id")
+        model_config = app.get("model_config")
+        if not isinstance(app_id, str) or not isinstance(model_config, dict):
+            raise TacoError(
+                code="AGENT_CREATE_RESPONSE_INVALID",
+                message="创建响应缺少应用 ID 或 model_config。",
+                exit_code=4,
+            )
+        _write_json_file(target, model_config)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(
+        ctx,
+        {
+            "app_id": app_id,
+            "name": app.get("name"),
+            "category": category,
+            "path": str(target),
+        },
+        json_default=True,
+    )
+
+
+@agent_app.command("pull", help="从服务端拉取 Agent model_config 到本地 DSL。")
+def pull_agent(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    output: Path = typer.Option(..., "--output", help="本地 Agent DSL JSON 输出路径。"),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="允许覆盖已存在的本地 DSL。",
+    ),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    try:
+        _prepare_agent_output(output, overwrite=overwrite)
+        model_config = AgentService().pull_agent_config(
+            app_id,
+            profile=cli_context.profile,
+        )
+        _write_json_file(output, model_config)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    emit_success(ctx, {"path": str(output)}, json_default=True)
+
+
+@agent_app.command("validate", help="校验本地 Agent DSL 及可选分类模型契约。")
+def validate_agent(
+    ctx: typer.Context,
+    dsl: Path = typer.Option(..., "--dsl", help="本地 Agent DSL JSON 文件。"),
+    category: str | None = typer.Option(
+        None,
+        "--category",
+        help="通过服务端确认模型支持该分类。",
+    ),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    try:
+        model_config = _read_json_object(dsl)
+        result = validate_agent_config(model_config)
+        parameter_rules: list[dict[str, Any]] = []
+        if category is not None:
+            model = model_config["model"]
+            model_description = ModelService().describe_model(
+                provider=model["provider"],
+                model=model["name"],
+                category=category,
+                profile=cli_context.profile,
+            )
+            parameter_rules = model_description["parameter_rules"]
+            result["model_verified"] = True
+        validate_completion_params(
+            model_config["model"]["completion_params"],
+            parameter_rules,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(ctx, result, json_default=True)
+
+
+@agent_app.command("run", help="使用本地 DSL 通过 SSE 调试 Agent。")
+def run_agent(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    dsl: Path = typer.Option(..., "--dsl", help="本地 Agent DSL JSON 文件。"),
+    query: str = typer.Option(..., "--query", help="调试问题。"),
+    inputs: Path | None = typer.Option(None, "--inputs", help="调试 inputs JSON 文件。"),
+    conversation_id: str | None = typer.Option(
+        None,
+        "--conversation-id",
+        help="续聊会话 ID。",
+    ),
+    parent_message_id: str | None = typer.Option(
+        None,
+        "--parent-message-id",
+        help="父消息 ID。",
+    ),
+    files: Path | None = typer.Option(
+        None,
+        "--files",
+        help="Dify 消息文件数组 JSON。",
+    ),
+    stream_events: bool = typer.Option(
+        False,
+        "--stream-events",
+        help="实时输出 NDJSON 事件，便于获取 task_id 后调用 stop。",
+    ),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    try:
+        model_config = _read_json_object(dsl)
+        input_payload = _read_json_object(inputs) if inputs else {}
+        run_options: dict[str, Any] = {
+            "model_config": model_config,
+            "query": query,
+            "inputs": input_payload,
+            "profile": cli_context.profile,
+        }
+        if conversation_id is not None:
+            run_options["conversation_id"] = conversation_id
+        if parent_message_id is not None:
+            run_options["parent_message_id"] = parent_message_id
+        if files is not None:
+            run_options["files"] = _read_json_array(files)
+        if stream_events:
+            run_options["on_event"] = lambda event: typer.echo(
+                to_json_line({"type": "event", "event": event})
+            )
+        result = AgentService().run_agent(app_id, **run_options)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    emit_success(ctx, result, json_default=True)
+
+
+@agent_app.command("stop", help="使用 task_id 停止正在运行的 Agent 调试任务。")
+def stop_agent(
+    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 = AgentService().stop_agent(
+            app_id,
+            task_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)
+
+
+@agent_tool_app.command("list", help="列出本地 Agent DSL 已挂载工具。")
+def list_agent_tools(
+    ctx: typer.Context,
+    dsl: Path = typer.Option(..., "--dsl", help="本地 Agent DSL JSON 文件。"),
+) -> None:
+    try:
+        model_config = _read_json_object(dsl)
+        tools = _agent_tools(model_config)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(ctx, {"path": str(dsl), "items": tools}, json_default=True)
+
+
+@agent_tool_app.command("add", help="发现工具并挂载到本地 Agent DSL。")
+def add_agent_tool(
+    ctx: typer.Context,
+    tool_type: str = typer.Option(
+        "builtin",
+        "--type",
+        help="工具类型：builtin|workflow；默认 builtin。",
+    ),
+    dsl: Path = typer.Option(..., "--dsl", help="本地 Agent DSL JSON 文件。"),
+    provider: str = typer.Option(
+        ...,
+        "--provider",
+        help="builtin Provider ID；workflow 时为 workflow_tool_id（不是 app ID）。",
+    ),
+    tool: str = typer.Option(
+        ...,
+        "--tool",
+        help="builtin action 名称或 Workflow Tool 机器名。",
+    ),
+    parameters: Path | None = typer.Option(
+        None,
+        "--parameters",
+        help="工具 form 参数 JSON 对象，不得包含 Provider 凭据。",
+    ),
+    replace: bool = typer.Option(
+        False,
+        "--replace",
+        help="替换同类型、同 Provider、同名称的已挂载工具。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认修改本地 DSL。"),
+) -> None:
+    _require_agent_tool_confirmation(ctx, yes)
+    if tool_type not in {"builtin", "workflow"}:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="AGENT_TOOL_TYPE_INVALID",
+                message="Agent 工具类型必须是 builtin 或 workflow。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+    cli_context = get_cli_context(ctx)
+    try:
+        _ensure_mutable_agent_dsl(dsl)
+        model_config = _read_json_object(dsl)
+        tools = _agent_tools(model_config)
+        parameter_values = _read_json_object(parameters) if parameters else {}
+        if tool_type == "builtin":
+            resolved = ToolService().resolve_agent_tool(
+                provider=provider,
+                tool=tool,
+                parameters=parameter_values,
+                profile=cli_context.profile,
+            )
+        else:
+            resolved = WorkflowToolService().resolve_agent_tool(
+                workflow_tool_id=provider,
+                tool_name=tool,
+                parameters=parameter_values,
+                profile=cli_context.profile,
+            )
+        matching_indices = [
+            position
+            for position, item in enumerate(tools)
+            if _same_agent_tool(item, tool_type, provider, tool)
+        ]
+        if matching_indices and not replace:
+            raise TacoError(
+                code="AGENT_TOOL_EXISTS",
+                message="本地 DSL 已挂载同一个工具。",
+                exit_code=6,
+                hint="确认替换后传入 --replace --yes。",
+            )
+        replaced_count = len(matching_indices)
+        if not matching_indices:
+            tools.append(resolved)
+        else:
+            first_index = matching_indices[0]
+            tools[:] = [
+                item
+                for item in tools
+                if not _same_agent_tool(item, tool_type, provider, tool)
+            ]
+            tools.insert(first_index, resolved)
+        validate_agent_config(model_config)
+        _write_json_file(dsl, model_config)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(
+        ctx,
+        {
+            "path": str(dsl),
+            "tool": resolved,
+            "tools_count": len(tools),
+            "replaced_count": replaced_count,
+        },
+        json_default=True,
+    )
+
+
+@agent_tool_app.command("remove", help="从本地 Agent DSL 移除已挂载工具。")
+def remove_agent_tool(
+    ctx: typer.Context,
+    tool_type: str = typer.Option(
+        "builtin",
+        "--type",
+        help="工具类型：builtin|workflow；默认 builtin。",
+    ),
+    dsl: Path = typer.Option(..., "--dsl", help="本地 Agent DSL JSON 文件。"),
+    provider: str = typer.Option(
+        ...,
+        "--provider",
+        help="builtin Provider ID；workflow 时为 workflow_tool_id（不是 app ID）。",
+    ),
+    tool: str = typer.Option(
+        ...,
+        "--tool",
+        help="builtin action 名称或 Workflow Tool 机器名。",
+    ),
+    yes: bool = typer.Option(False, "--yes", help="确认修改本地 DSL。"),
+) -> None:
+    _require_agent_tool_confirmation(ctx, yes)
+    if tool_type not in {"builtin", "workflow"}:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="AGENT_TOOL_TYPE_INVALID",
+                message="Agent 工具类型必须是 builtin 或 workflow。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+    try:
+        _ensure_mutable_agent_dsl(dsl)
+        model_config = _read_json_object(dsl)
+        tools = _agent_tools(model_config)
+        remaining = [
+            item
+            for item in tools
+            if not _same_agent_tool(item, tool_type, provider, tool)
+        ]
+        if len(remaining) == len(tools):
+            raise TacoError(
+                code="AGENT_TOOL_NOT_FOUND",
+                message="本地 DSL 未挂载指定工具。",
+                exit_code=6,
+            )
+        model_config["agent_mode"]["tools"] = remaining
+        validate_agent_config(model_config)
+        _write_json_file(dsl, model_config)
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+    emit_success(
+        ctx,
+        {"path": str(dsl), "tools_count": len(remaining)},
+        json_default=True,
+    )
+
+
+@agent_app.command("publish", help="发布本地 Agent DSL 并可在成功后删除文件。")
+def publish_agent(
+    ctx: typer.Context,
+    app_id: str = typer.Argument(..., help="应用 ID。"),
+    dsl: Path = typer.Option(..., "--dsl", help="本地 Agent DSL JSON 文件。"),
+    yes: bool = typer.Option(False, "--yes", help="确认发布本地 DSL。"),
+    keep_dsl: bool = typer.Option(False, "--keep-dsl", help="发布成功后保留本地 DSL 文件。"),
+) -> None:
+    cli_context = get_cli_context(ctx)
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="AGENT_PUBLISH_CONFIRM_REQUIRED",
+                message="发布 Agent 前必须显式传入 --yes。",
+                exit_code=2,
+                hint="确认本地 DSL 已调试通过后，重新执行 taco agent publish --yes。",
+            ),
+            json_default=True,
+        )
+
+    try:
+        model_config = _read_json_object(dsl)
+        result = AgentService().publish_agent(
+            app_id,
+            model_config=model_config,
+            profile=cli_context.profile,
+        )
+    except TacoError as error:
+        exit_with_error(ctx, error, json_default=True)
+
+    dsl_deleted = False
+    if not keep_dsl:
+        try:
+            dsl.unlink()
+        except OSError:
+            exit_with_error(
+                ctx,
+                TacoError(
+                    code="AGENT_DSL_CLEANUP_FAILED",
+                    message="Agent 已发布，但本地 DSL 删除失败。",
+                    exit_code=2,
+                    hint=f"请手动删除文件：{dsl}",
+                ),
+                json_default=True,
+            )
+        dsl_deleted = True
+
+    data = dict(result) if isinstance(result, dict) else {"result": result}
+    data.update({"dsl_deleted": dsl_deleted, "path": str(dsl)})
+    emit_success(ctx, data, json_default=True)
+
+
+def _read_json_object(path: Path | None) -> dict[str, Any]:
+    if path is None:
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, JSONDecodeError) as error:
+        raise TacoError(
+            code="AGENT_DSL_INVALID",
+            message="Agent DSL 文件不存在或不是合法 JSON。",
+            exit_code=2,
+            hint="请确认 --dsl/--inputs 指向有效 JSON 文件。",
+        ) from error
+
+    if not isinstance(payload, dict):
+        raise TacoError(
+            code="AGENT_DSL_INVALID",
+            message="Agent DSL JSON 必须是对象。",
+            exit_code=2,
+            hint="请将本地 DSL 调整为 JSON object。",
+        )
+
+    return payload
+
+
+def _read_json_array(path: Path) -> list[dict[str, Any]]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, JSONDecodeError) as error:
+        raise TacoError(
+            code="AGENT_FILES_INVALID",
+            message="Agent files 文件不存在或不是合法 JSON。",
+            exit_code=2,
+        ) from error
+    if not isinstance(payload, list) or any(
+        not isinstance(item, dict) for item in payload
+    ):
+        raise TacoError(
+            code="AGENT_FILES_INVALID",
+            message="Agent files JSON 必须是对象数组。",
+            exit_code=2,
+        )
+    return payload
+
+
+def _agent_tools(model_config: dict[str, Any]) -> list[dict[str, Any]]:
+    agent_mode = model_config.get("agent_mode")
+    tools = agent_mode.get("tools") if isinstance(agent_mode, dict) else None
+    if not isinstance(tools, list) or any(
+        not isinstance(item, dict) for item in tools
+    ):
+        raise TacoError(
+            code="AGENT_DSL_VALIDATION_FAILED",
+            message="Agent DSL 的 agent_mode.tools 必须是对象数组。",
+            exit_code=6,
+        )
+    return tools
+
+
+def _same_agent_tool(
+    tool: dict[str, Any],
+    provider_type: str,
+    provider: str,
+    tool_name: str,
+) -> bool:
+    return (
+        tool.get("provider_type") == provider_type
+        and _provider_ids_match(
+            provider_type,
+            tool.get("provider_id"),
+            provider,
+        )
+        and tool.get("tool_name") == tool_name
+    )
+
+
+def _provider_ids_match(
+    provider_type: str,
+    actual: Any,
+    expected: str,
+) -> bool:
+    if not isinstance(actual, str) or provider_type != "workflow":
+        return actual == expected
+    try:
+        return UUID(actual) == UUID(expected)
+    except ValueError:
+        return actual == expected
+
+
+def _ensure_mutable_agent_dsl(path: Path) -> None:
+    if path.is_symlink():
+        raise TacoError(
+            code="AGENT_DSL_SYMLINK_UNSUPPORTED",
+            message="修改 Agent 工具时不允许 DSL 路径是符号链接。",
+            exit_code=2,
+            hint="请使用普通文件路径。",
+        )
+
+
+def _require_agent_tool_confirmation(ctx: typer.Context, yes: bool) -> None:
+    if not yes:
+        exit_with_error(
+            ctx,
+            TacoError(
+                code="AGENT_TOOL_CONFIRM_REQUIRED",
+                message="修改本地 Agent 工具前必须显式传入 --yes。",
+                exit_code=2,
+            ),
+            json_default=True,
+        )
+
+
+def _prepare_agent_output(path: Path | None, *, overwrite: bool) -> None:
+    parent = (path.parent if path is not None else Path.cwd()).resolve()
+    if path is not None and path.is_symlink():
+        raise TacoError(
+            code="AGENT_DSL_PATH_INVALID",
+            message=f"Agent DSL 输出不能是符号链接：{path}",
+            exit_code=2,
+        )
+    if path is not None and path.exists():
+        if not path.is_file():
+            raise TacoError(
+                code="AGENT_DSL_PATH_INVALID",
+                message=f"Agent DSL 输出必须是普通文件路径：{path}",
+                exit_code=2,
+            )
+        if not overwrite:
+            raise TacoError(
+                code="AGENT_DSL_EXISTS",
+                message=f"本地 Agent DSL 已存在：{path}",
+                exit_code=2,
+                hint="请显式传入 --overwrite；Agent create 还需 --yes。",
+            )
+        if not os.access(path, os.W_OK):
+            raise TacoError(
+                code="AGENT_DSL_PATH_INVALID",
+                message=f"本地 Agent DSL 不可覆盖：{path}",
+                exit_code=2,
+            )
+    try:
+        parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            dir=parent,
+            prefix=".taco-write-check-",
+        ):
+            pass
+    except OSError as error:
+        raise TacoError(
+            code="AGENT_DSL_WRITE_FAILED",
+            message="创建远端 Agent 前无法确认本地 DSL 目录可写。",
+            exit_code=2,
+            hint=f"请检查目录权限和磁盘空间：{parent}",
+        ) from error
+
+
+def _write_json_file(path: Path, payload: Any) -> None:
+    temporary: Path | None = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary_name = tempfile.mkstemp(
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            text=True,
+        )
+        temporary = Path(temporary_name)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as file:
+            file.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+            file.flush()
+            os.fsync(file.fileno())
+        temporary.replace(path)
+    except OSError as error:
+        raise TacoError(
+            code="AGENT_DSL_WRITE_FAILED",
+            message="无法写入 Agent DSL 文件。",
+            exit_code=2,
+            hint=f"请检查目录权限和磁盘空间：{path}",
+        ) from error
+    finally:
+        if temporary is not None and temporary.exists():
+            try:
+                temporary.unlink()
+            except OSError:
+                pass