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

taco/aikb/parameters.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from jsonschema import Draft202012Validator
+
+from taco.aikb.models import AikbOperation
+from taco.core.errors import TacoError
+
+
+RESERVED = {"accesskeyid", "expires", "timestamp", "signature", "authorization"}
+
+
+def parse_parameters(
+    operation: AikbOperation,
+    *,
+    params: list[str] | None = None,
+    params_file: Path | None = None,
+    body_file: Path | None = None,
+    has_file: bool = False,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    query_schema = operation.http["query_schema"]
+    body_schema = operation.http["body_schema"]
+    query_fields = query_schema.get("properties", {})
+    body_fields = body_schema.get("properties", {})
+    values: dict[str, Any] = {}
+    for expression in params or []:
+        key, separator, raw = expression.partition("=")
+        if not separator or not key:
+            raise _parameter_error("--param 必须使用 key=value 格式。")
+        if key in values:
+            raise _parameter_error(f"参数重复：/{key}")
+        schema = query_fields.get(key) or body_fields.get(key)
+        if schema is None:
+            raise _parameter_error(f"未知参数：/{key}")
+        values[key] = _parse_value(raw, schema, key)
+    if params_file is not None:
+        file_values = _read_json_object(params_file)
+        conflicts = set(values) & set(file_values)
+        if conflicts:
+            raise _parameter_error(f"参数重复：/{sorted(conflicts)[0]}")
+        values.update(file_values)
+    if any(key.lower() in RESERVED for key in values):
+        raise _parameter_error("不能传入公共签名或认证参数。")
+    unknown = set(values) - set(query_fields) - set(body_fields)
+    if unknown:
+        raise _parameter_error(f"未知参数：/{sorted(unknown)[0]}")
+
+    query = {key: value for key, value in values.items() if key in query_fields}
+    body_values = {key: value for key, value in values.items() if key in body_fields}
+    if body_file is not None:
+        if body_values:
+            raise _parameter_error("--body-file 不能与映射到 body 的 --param 同时使用。")
+        body_values = _read_json_object(body_file)
+    bound_targets = {
+        binding["target"].removeprefix("/")
+        for binding in operation.execution.get("request_bindings", ())
+    }
+    if bound_targets & set(body_values):
+        raise _parameter_error("文件名和大小只能由 --file 自动生成。")
+    if operation.file_input is not None:
+        if not has_file:
+            raise _parameter_error("该 operation 必须传入 --file。")
+        if body_file is not None:
+            raise _parameter_error("文件 operation 不接受 --body-file。")
+    elif has_file:
+        raise _parameter_error("该 operation 不支持 --file。")
+
+    _validate(query_schema, query, ignore_required=set())
+    _validate(body_schema, body_values, ignore_required=bound_targets)
+    return query, body_values
+
+
+def _parse_value(raw: str, schema: Mapping[str, Any], key: str) -> Any:
+    expected = schema.get("type")
+    try:
+        if expected == "string":
+            return raw
+        if expected == "integer":
+            return int(raw, 10)
+        if expected == "number":
+            return float(raw)
+        if expected == "boolean":
+            if raw.lower() in {"true", "1"}:
+                return True
+            if raw.lower() in {"false", "0"}:
+                return False
+            raise ValueError
+        if expected in {"array", "object"}:
+            return json.loads(raw)
+    except (ValueError, json.JSONDecodeError):
+        raise _parameter_error(f"参数 /{key} 类型错误，期望 {expected}。") from None
+    raise _parameter_error(f"参数 /{key} 使用了不支持的类型。")
+
+
+def _read_json_object(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        raise _parameter_error(f"参数文件不是合法 UTF-8 JSON 对象：{path}") from None
+    if not isinstance(payload, dict):
+        raise _parameter_error(f"参数文件必须是 JSON 对象：{path}")
+    return payload
+
+
+def _validate(schema: Mapping[str, Any], value: Any, *, ignore_required: set[str]) -> None:
+    mutable = _thaw(schema)
+    if ignore_required:
+        mutable["required"] = [
+            key for key in mutable.get("required", []) if key not in ignore_required
+        ]
+    error = next(Draft202012Validator(mutable).iter_errors(value), None)
+    if error is not None:
+        pointer = "/" + "/".join(str(part) for part in error.absolute_path)
+        raise _parameter_error(
+            f"参数 {pointer or '/'} 校验失败，期望 {error.validator}。"
+        )
+
+
+def thaw(value: Any) -> Any:
+    return _thaw(value)
+
+
+def _thaw(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _thaw(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw(item) for item in value]
+    return value
+
+
+def _parameter_error(message: str) -> TacoError:
+    return TacoError(code="AIKB_PARAMETER_INVALID", message=message, exit_code=2)

taco/aikb/service.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from taco.aikb.catalog import load_catalog
+from taco.aikb.executors import execute_http, execute_presigned_put
+from taco.aikb.file_input import OpenFileInput
+from taco.core.config_store import ConfigStore
+from taco.core.developer_center_client import DeveloperCenterClient
+from taco.core.errors import TacoError
+from taco.core.profile_resolver import ProfileResolver
+
+
+class AikbService:
+    def __init__(
+        self,
+        store: ConfigStore | None = None,
+        *,
+        profile_resolver: ProfileResolver | None = None,
+        developer_http_client: httpx.Client | None = None,
+        upload_http_client: httpx.Client | None = None,
+    ) -> None:
+        self.store = store or ConfigStore()
+        self.profile_resolver = profile_resolver or ProfileResolver(self.store)
+        self.catalog = load_catalog()
+        self.developer_http_client = developer_http_client
+        self.upload_http_client = upload_http_client
+
+    def call(
+        self,
+        operation_id: str,
+        *,
+        query: dict[str, Any],
+        body: dict[str, Any],
+        profile: str | None = None,
+        file_path: Path | None = None,
+        upload_timeout: float | None = None,
+    ) -> dict[str, Any]:
+        operation = self.catalog.by_id.get(operation_id)
+        if operation is None:
+            raise TacoError(code="AIKB_OPERATION_NOT_FOUND", message=f"未知 operation：{operation_id}", exit_code=2)
+        resolved = self.profile_resolver.resolve(profile)
+        client = DeveloperCenterClient(
+            endpoint=resolved.endpoint,
+            access_key_id=resolved.access_key_id,
+            access_key_secret=resolved.access_key_secret,
+            http_client=self.developer_http_client,
+        )
+        try:
+            if operation.execution["kind"] == "http":
+                return execute_http(operation, client, query=query, body=body)
+            if file_path is None:
+                raise TacoError(code="AIKB_FILE_REQUIRED", message="该 operation 必须传入 --file。", exit_code=2)
+            with OpenFileInput.open(file_path) as file:
+                return execute_presigned_put(
+                    operation,
+                    client,
+                    query=query,
+                    body=body,
+                    file=file,
+                    upload_http_client=self.upload_http_client,
+                    upload_timeout=upload_timeout,
+                )
+        finally:
+            client.close()

taco/assets/__init__.py

@@ -0,0 +1 @@
+"""Packaged schemas, scenarios, examples, and Agent skills."""

taco/assets/agent_openapi/catalog.json

@@ -0,0 +1,14 @@
+{
+  "catalog_version": "1.0",
+  "json_schema_dialect": "https://json-schema.org/draft/2020-12/schema",
+  "source": {
+    "name": "天润开发者中心智能体 API",
+    "url": "https://develop.clink.cn/develop/api/agent.html",
+    "snapshot_date": "2026-08-31"
+  },
+  "operations": [
+    "conversation/list-conversations",
+    "message/list-conversation-messages",
+    "trace/list-message-traces"
+  ]
+}

taco/assets/agent_openapi/operations/conversation/list-conversations.json

@@ -0,0 +1,67 @@
+{
+  "schema_version": "1.0",
+  "id": "list-conversations",
+  "title": "查询会话记录",
+  "description": "按查询条件游标读取智能体会话记录，单次查询时间跨度最大为 90 天。",
+  "group": "conversation",
+  "keywords": ["查询会话记录", "会话记录", "conversation", "list-conversations", "list_conversations"],
+  "source": {"url": "https://develop.clink.cn/develop/api/agent.html", "anchor": "查询会话记录", "snapshot_date": "2026-08-31"},
+  "http": {
+    "method": "POST",
+    "path": "/agent/v1/data/list-conversations",
+    "content_type": "application/json",
+    "query_schema": {"type": "object", "properties": {}, "additionalProperties": false},
+    "body_schema": {
+      "type": "object",
+      "properties": {
+        "app_id": {"type": "string", "title": "智能体应用 ID", "description": "智能体应用 ID。", "minLength": 1},
+        "conversation_id": {"type": "string", "title": "会话 ID", "description": "可选，按指定会话 ID 查询。", "minLength": 1},
+        "created_at_start": {"type": "integer", "title": "创建开始时间", "description": "会话创建时间范围的开始时间，Unix 秒级正整数时间戳。", "minimum": 1},
+        "created_at_end": {"type": "integer", "title": "创建结束时间", "description": "会话创建时间范围的结束时间，Unix 秒级正整数时间戳，闭区间且跨度不超过 90 天。", "minimum": 1},
+        "invoke_from": {"type": "string", "title": "会话来源", "description": "会话来源，可选生产环境或调试环境。", "enum": ["PROD", "DEBUG"], "x-enum-descriptions": {"PROD": "生产环境", "DEBUG": "调试环境"}},
+        "is_transfer_human": {"type": "boolean", "title": "是否转人工", "description": "筛选是否发生过转人工。"},
+        "limit": {"type": "integer", "title": "每页条数", "description": "每次返回条数，范围 1 到 100，默认 10。", "minimum": 1, "maximum": 100, "default": 10},
+        "cursor": {"type": "string", "title": "下一页游标", "description": "首次请求不传；后续传入上次响应的 next_cursor，并保持其他参数不变。", "minLength": 1}
+      },
+      "required": ["app_id", "created_at_start", "created_at_end"],
+      "additionalProperties": false
+    }
+  },
+  "response": {
+    "request_id_pointer": "/requestId",
+    "schema": {
+      "type": "object",
+      "required": ["data", "limit", "has_more", "next_cursor"],
+      "properties": {
+        "requestId": {"type": ["string", "null"], "description": "开发者中心请求 ID，部分成功响应可能不返回。"},
+        "data": {
+          "type": "array", "description": "会话记录列表。",
+          "items": {
+            "type": "object", "description": "一条会话记录。",
+            "properties": {
+              "id": {"type": "string", "description": "会话 ID。"},
+              "main_unique_id": {"type": ["string", "null"], "description": "接入方的会话 ID。"},
+              "duration": {"type": "integer", "description": "会话持续时间，单位秒。"},
+              "dialogue_count": {"type": "integer", "description": "对话轮次。"},
+              "app_id": {"type": "string", "description": "智能体应用 ID。"},
+              "inputs": {"type": ["string", "null"], "description": "会话输入变量的 JSON 字符串。"},
+              "created_at": {"type": "integer", "description": "创建时间，Unix 秒级时间戳。"},
+              "updated_at": {"type": "integer", "description": "更新时间，Unix 秒级时间戳。"},
+              "invoke_from": {"type": "string", "description": "会话来源。"},
+              "is_transfer_human": {"type": "boolean", "description": "是否发生转人工。"}
+            },
+            "additionalProperties": true
+          }
+        },
+        "limit": {"type": "integer", "description": "本次查询的每页条数。"},
+        "has_more": {"type": "boolean", "description": "是否还有下一页。"},
+        "next_cursor": {"type": ["string", "null"], "description": "下一页游标，无下一页时为 null。"}
+      },
+      "additionalProperties": true
+    },
+    "sensitive_pointers": []
+  },
+  "risk": {"level": "read", "requires_confirmation": false, "target_fields": []},
+  "execution": {"kind": "http"},
+  "examples": [{"title": "查询生产环境会话", "params": {"app_id": "1-407259aa-393c-4858-bc64-220a44d177e9", "created_at_start": 1782835200, "created_at_end": 1785168000, "invoke_from": "PROD", "limit": 10}}]
+}

taco/assets/agent_openapi/operations/message/list-conversation-messages.json

@@ -0,0 +1,80 @@
+{
+  "schema_version": "1.0",
+  "id": "list-conversation-messages",
+  "title": "查询会话消息",
+  "description": "按创建时间正序游标读取指定会话的消息列表。",
+  "group": "message",
+  "keywords": ["查询会话消息", "会话消息", "对话记录", "message", "list-conversation-messages", "list_conversation_messages"],
+  "source": {"url": "https://develop.clink.cn/develop/api/agent.html", "anchor": "查询会话消息", "snapshot_date": "2026-08-31"},
+  "http": {
+    "method": "POST",
+    "path": "/agent/v1/data/list-conversation-messages",
+    "content_type": "application/json",
+    "query_schema": {"type": "object", "properties": {}, "additionalProperties": false},
+    "body_schema": {
+      "type": "object",
+      "properties": {
+        "app_id": {"type": "string", "title": "智能体应用 ID", "description": "智能体应用 ID。", "minLength": 1},
+        "conversation_id": {"type": "string", "title": "会话 ID", "description": "需要查询的会话 ID。", "minLength": 1},
+        "conversation_created_at": {"type": "integer", "title": "会话创建时间", "description": "会话创建时间的 Unix 秒级正整数时间戳。", "minimum": 1},
+        "limit": {"type": "integer", "title": "每页条数", "description": "每次返回条数，范围 1 到 100，默认 10。", "minimum": 1, "maximum": 100, "default": 10},
+        "cursor": {"type": "string", "title": "下一页游标", "description": "首次请求不传；后续传入上次响应的 next_cursor，并保持其他参数不变。", "minLength": 1}
+      },
+      "required": ["app_id", "conversation_id", "conversation_created_at"],
+      "additionalProperties": false
+    }
+  },
+  "response": {
+    "request_id_pointer": "/requestId",
+    "schema": {
+      "type": "object",
+      "required": ["data", "limit", "has_more", "next_cursor"],
+      "properties": {
+        "requestId": {"type": ["string", "null"], "description": "开发者中心请求 ID，部分成功响应可能不返回。"},
+        "data": {
+          "type": "array", "description": "消息列表，不包含系统内部记忆消息。",
+          "items": {
+            "type": "object", "description": "一条会话消息。",
+            "properties": {
+              "conversation_id": {"type": "string", "description": "会话 ID。"},
+              "main_unique_id": {"type": ["string", "null"], "description": "接入方的会话 ID。"},
+              "id": {"type": "string", "description": "消息 ID。"},
+              "query": {"type": ["string", "null"], "description": "用户输入。"},
+              "answer": {"type": ["string", "null"], "description": "智能体回答。"},
+              "knowledge_sources": {
+                "type": "array", "description": "回答引用的知识来源。",
+                "items": {
+                  "type": "object", "description": "一条知识来源。",
+                  "properties": {
+                    "name": {"type": "string", "description": "知识名称。"},
+                    "type": {"type": "string", "description": "知识类型，如 FAQ、FILE 或 CONVERSATION。"}
+                  },
+                  "additionalProperties": true
+                }
+              },
+              "answer_type": {"type": ["string", "null"], "description": "回复类型，如 EXACT、RECOMMEND 或 UNKNOWN。"},
+              "created_at": {"type": "integer", "description": "消息创建时间，Unix 秒级时间戳。"},
+              "first_token_latency": {"type": ["number", "null"], "description": "首 Token 生成时间，单位秒。"},
+              "total_latency": {"type": ["number", "null"], "description": "完整回复生成时间，单位秒。"},
+              "user_feedback": {"type": ["string", "null"], "description": "用户评价状态。"},
+              "user_feedback_tags": {"type": ["array", "null"], "description": "用户评价标签。", "items": {"type": "string", "description": "一条用户评价标签。"}},
+              "user_feedback_content": {"type": ["string", "null"], "description": "用户评价内容。"},
+              "manager_feedback": {"type": ["string", "null"], "description": "管理员评价状态。"},
+              "inputs": {"type": ["string", "null"], "description": "消息输入变量的 JSON 字符串。"},
+              "content_moderation_result": {"type": ["string", "null"], "description": "内容审查结果。"}
+            },
+            "additionalProperties": true
+          }
+        },
+        "limit": {"type": "integer", "description": "本次查询的每页条数。"},
+        "has_more": {"type": "boolean", "description": "是否还有下一页。"},
+        "next_cursor": {"type": ["string", "null"], "description": "下一页游标，无下一页时为 null。"}
+      },
+      "additionalProperties": true
+    },
+    "sensitive_pointers": []
+  },
+  "risk": {"level": "read", "requires_confirmation": false, "target_fields": []},
+  "execution": {"kind": "http"},
+  "examples": [{"title": "查询指定会话消息", "params": {"app_id": "1-407259aa-393c-4858-bc64-220a44d177e9", "conversation_id": "0fcac847-ba6a-4d74-b9ac-02d35b9911b5", "conversation_created_at": 1785118530, "limit": 10}}]
+}

taco/assets/agent_openapi/operations/trace/list-message-traces.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": "1.0",
+  "id": "list-message-traces",
+  "title": "查询消息追踪",
+  "description": "游标读取指定消息的详细日志追踪。",
+  "group": "trace",
+  "keywords": ["查询消息追踪", "消息追踪", "节点日志", "trace", "list-message-traces", "list_message_traces"],
+  "source": {"url": "https://develop.clink.cn/develop/api/agent.html", "anchor": "查询消息追踪", "snapshot_date": "2026-08-31"},
+  "http": {
+    "method": "POST",
+    "path": "/agent/v1/data/list-message-traces",
+    "content_type": "application/json",
+    "query_schema": {"type": "object", "properties": {}, "additionalProperties": false},
+    "body_schema": {
+      "type": "object",
+      "properties": {
+        "app_id": {"type": "string", "title": "智能体应用 ID", "description": "智能体应用 ID。", "minLength": 1},
+        "conversation_id": {"type": "string", "title": "会话 ID", "description": "消息所属的会话 ID。", "minLength": 1},
+        "conversation_created_at": {"type": "integer", "title": "会话创建时间", "description": "会话创建时间的 Unix 秒级正整数时间戳，用于定位数据索引。", "minimum": 1},
+        "message_id": {"type": "string", "title": "消息 ID", "description": "需要查询追踪的消息 ID。", "minLength": 1},
+        "limit": {"type": "integer", "title": "每页条数", "description": "每次返回条数，范围 1 到 100，默认 10。", "minimum": 1, "maximum": 100, "default": 10},
+        "cursor": {"type": "string", "title": "下一页游标", "description": "首次请求不传；后续传入上次响应的 next_cursor，并保持其他参数不变。", "minLength": 1}
+      },
+      "required": ["app_id", "conversation_id", "conversation_created_at", "message_id"],
+      "additionalProperties": false
+    }
+  },
+  "response": {
+    "request_id_pointer": "/requestId",
+    "schema": {
+      "type": "object",
+      "required": ["message_id", "traces", "limit", "has_more", "next_cursor"],
+      "properties": {
+        "requestId": {"type": ["string", "null"], "description": "开发者中心请求 ID，部分成功响应可能不返回。"},
+        "message_id": {"type": "string", "description": "消息 ID。"},
+        "traces": {
+          "type": "array", "description": "详细日志追踪列表。",
+          "items": {
+            "type": "object", "description": "一条节点执行追踪。",
+            "properties": {
+              "id": {"type": "string", "description": "节点执行 ID。"},
+              "index": {"type": "integer", "description": "节点执行顺序。"},
+              "predecessor_node_id": {"type": ["string", "null"], "description": "前置节点 ID。"},
+              "node_id": {"type": "string", "description": "工作流节点 ID。"},
+              "node_type": {"type": "string", "description": "节点类型。"},
+              "title": {"type": "string", "description": "节点标题。"},
+              "inputs": {"description": "节点输入；JSON 内容返回对象，否则可能返回原始值。"},
+              "process_data": {"description": "节点处理过程数据。"},
+              "outputs": {"description": "节点输出；JSON 内容返回对象，否则可能返回原始值。"},
+              "status": {"type": "string", "description": "节点执行状态。"},
+              "error": {"type": ["string", "null"], "description": "节点执行错误信息。"},
+              "elapsed_time": {"type": ["number", "null"], "description": "节点执行耗时，单位秒。"},
+              "execution_metadata": {"type": ["object", "null"], "description": "节点执行元数据。", "additionalProperties": true},
+              "extras": {"type": ["object", "null"], "description": "节点额外信息。", "additionalProperties": true},
+              "created_at": {"type": "integer", "description": "节点开始执行的 Unix 秒级时间戳。"},
+              "finished_at": {"type": ["integer", "null"], "description": "节点完成执行的 Unix 秒级时间戳。"}
+            },
+            "additionalProperties": true
+          }
+        },
+        "limit": {"type": "integer", "description": "本次查询的每页条数。"},
+        "has_more": {"type": "boolean", "description": "是否还有下一页。"},
+        "next_cursor": {"type": ["string", "null"], "description": "下一页游标，无下一页时为 null。"}
+      },
+      "additionalProperties": true
+    },
+    "sensitive_pointers": []
+  },
+  "risk": {"level": "read", "requires_confirmation": false, "target_fields": []},
+  "execution": {"kind": "http"},
+  "examples": [{"title": "查询指定消息追踪", "params": {"app_id": "1-407259aa-393c-4858-bc64-220a44d177e9", "conversation_id": "0fcac847-ba6a-4d74-b9ac-02d35b9911b5", "conversation_created_at": 1785118530, "message_id": "29831f179-ea7c-49d5-1257-69f15d1e4ed4", "limit": 10}}]
+}

taco/assets/aikb/catalog.json

@@ -0,0 +1,41 @@
+{
+  "catalog_version": "1.0",
+  "json_schema_dialect": "https://json-schema.org/draft/2020-12/schema",
+  "source": {
+    "name": "天润开发者中心 AIKB",
+    "url": "https://develop.clink.cn/develop/api/aikb.html",
+    "snapshot_date": "2026-08-14"
+  },
+  "defaults": {
+    "endpoint_scope": "/aikb/",
+    "content_type": "application/json",
+    "query_array_style": "indexed",
+    "additional_request_properties": false,
+    "additional_response_properties": true
+  },
+  "operations": [
+    "repository/list-public-repositories",
+    "repository/list-private-repositories",
+    "repository/describe-bot-repository",
+    "directory/list-directory-tree",
+    "directory/save-directory",
+    "directory/edit-directory",
+    "directory/delete-directory",
+    "faq/list-faqs",
+    "faq/create-faq",
+    "faq/edit-faq",
+    "faq/delete-faq",
+    "faq/describe-faq",
+    "file/list-files",
+    "file/describe-file",
+    "file/get-file-upload-url",
+    "file/create-file",
+    "file/delete-files",
+    "recycle-bin/list-recycled-items",
+    "conversation/chat-conversation-on-open",
+    "search/search-knowledge-on-open",
+    "media/describe-file-media-url",
+    "media/describe-faq-media-url",
+    "oss/signature-for-upload"
+  ]
+}

taco/assets/aikb/operations/conversation/chat-conversation-on-open.json

@@ -0,0 +1,99 @@
+{
+  "schema_version": "1.0",
+  "id": "chat-conversation-on-open",
+  "title": "会话问答",
+  "description": "会话问答，参数和返回结构依据开发者中心 AIKB 文档快照。",
+  "group": "conversation",
+  "keywords": [
+    "会话问答",
+    "chat-conversation-on-open",
+    "chat_conversation_on_open"
+  ],
+  "source": {
+    "url": "https://develop.clink.cn/develop/api/aikb.html",
+    "anchor": "会话问答",
+    "snapshot_date": "2026-08-14"
+  },
+  "http": {
+    "method": "POST",
+    "path": "/aikb/chat_conversation_on_open",
+    "content_type": "application/json",
+    "query_schema": {
+      "type": "object",
+      "properties": {
+        "username": {
+          "type": "string",
+          "title": "用户登录名",
+          "description": "发起提问的用户登录名。",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "username"
+      ],
+      "additionalProperties": false
+    },
+    "body_schema": {
+      "type": "object",
+      "properties": {
+        "content": {
+          "type": "string",
+          "title": "消息内容",
+          "description": "本轮对话的提问内容。",
+          "minLength": 1
+        },
+        "conversationId": {
+          "type": "string",
+          "title": "会话 ID",
+          "description": "新对话不传，后续消息传服务端返回的 ID。"
+        }
+      },
+      "required": [
+        "content"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "response": {
+    "request_id_pointer": "/requestId",
+    "schema": {
+      "type": "object",
+      "required": [
+        "result"
+      ],
+      "properties": {
+        "requestId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "开发者中心请求 ID；部分接口可能返回 null。"
+        },
+        "result": {
+          "type": "object",
+          "description": "接口返回的业务结果。",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "sensitive_pointers": []
+  },
+  "risk": {
+    "level": "write",
+    "requires_confirmation": true,
+    "target_fields": []
+  },
+  "execution": {
+    "kind": "http"
+  },
+  "examples": [
+    {
+      "title": "发起新会话",
+      "params": {
+        "username": "agent-user",
+        "content": "呼叫中心是什么？"
+      }
+    }
+  ]
+}