feat: 优化 Agent 运行时与聊天设置体验

docs/protocols/agent/api-endpoints.md

@@ -112,7 +112,10 @@ Base URL: `/api/v1/agent`
     seq: number;
     role: "user" | "assistant" | "tool";
     content: string;
-    url?: string | null;       // user 附件签名链接
+    attachments?: Array<{       // user 附件签名链接列表
+      mimeType: string;
+      url: string;
+    }>;
     ui_schema?: object | null; // assistant/tool 的编译后 UI
     timestamp: string;         // ISO-8601
   }>;

docs/protocols/agent/run-agent-input.md

@@ -163,19 +163,14 @@ interface Tool {
 }
 ```
 
-### Backend Processing
+### Frontend Tool Channel Semantics
 
-Backend 使用 `build_tools_prompt` 函数将 tools 转换为 prompt 格式：
+- `RunAgentInput.tools` 用于前端工具通道（供前端/HITL 审批链路透传与回放）。
+- 当前后端 AgentScope 执行阶段**不**使用该字段来注册或筛选后端工具。
+- 后端可调用工具以 `toolkit.register_tool_function(...)` 注册结果为准（例如 `calendar_write`）。
+- 因此 `tools` 可为空数组，不影响后端已注册工具的调用能力。
 
-```
-<!-- TOOLS_START -->
-- get_weather: Get current weather for a location
-  - args_schema: {"type":"object","properties":{"location":{"type":"string","description":"City name"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}
-- searchDocuments: Search for documents
-  - args_schema: {"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}
-Note: tool arguments must strictly match args_schema.
-<!-- TOOLS_END -->
-```
+> 注意：请勿把后端已注册工具重复写入 `RunAgentInput.tools`，避免命名/参数描述冲突。
 
 ---
 
@@ -206,6 +201,7 @@ Backend 实现了以下验证规则：
 | binary 必须是 image/* | `binary content requires image mimeType` |
 | binary 必须有 url | `binary content requires url` |
 | binary 不允许使用 data | `binary content data is not allowed` |
+| 单条消息最多 3 张附件 | `Too many attachments` |
 
 ---
 
@@ -349,10 +345,15 @@ interface HistoryMessageUser {
   seq: number;
   role: "user";
   content: string;
-  url: string | null;        // 附件临时访问 URL
+  attachments: HistoryAttachment[];
   timestamp: string;        // ISO-8601 timestamp
 }
 
+interface HistoryAttachment {
+  mimeType: string;
+  url: string;
+}
+
 // role = "tool"
 interface HistoryMessageTool {
   id: string;
@@ -410,7 +411,12 @@ interface UiSchemaRenderer {
       "seq": 1,
       "role": "user",
       "content": "帮我创建一个日程",
-      "url": null,
+      "attachments": [
+        {
+          "mimeType": "image/png",
+          "url": "https://project.supabase.co/storage/v1/object/sign/agent-inputs/..."
+        }
+      ],
       "timestamp": "2026-03-15T10:00:00Z"
     },
     {
@@ -446,5 +452,5 @@ interface UiSchemaRenderer {
 - `UserMessage.content` 支持 string 或 array 格式，前端优先使用 array 格式以支持多模态
 - binary content 的 url 必须是有效的 signed URL，由 `/api/v1/agent/attachments` 端点生成
 - backend 验证通过后，会将 binary url 转换为内部存储路径
-- tools 为空数组时，prompt 中不会包含工具说明
+- `tools` 是前端工具通道字段；当前后端运行时不基于该字段构造后端工具 prompt
 - `RunAgentInput` 同时接受 camelCase 与 snake_case 别名输入（推荐统一使用 camelCase）