openclaw-weixin 2.4.6 → 3.0.0

package/dist/src/messaging/approval-quick-replies.js

@@ -0,0 +1,170 @@
+const APPROVAL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const FORWARDED_EXEC_APPROVAL_HEADING = "🔒 Exec approval required";
+const QUICK_REPLIES_HEADING = "Quick replies (short ID):";
+const OTHER_OPTIONS_HEADER = "Other options:\n\n";
+const TXT_FENCE_OPEN = "```txt\n";
+const FENCE_CLOSE = "\n```";
+const EXEC_APPROVAL_DECISIONS = ["allow-once", "allow-always", "deny"];
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readExecApprovalDetails(payload) {
+    if (!isRecord(payload.channelData)) {
+        return null;
+    }
+    const metadata = payload.channelData.execApproval;
+    if (!isRecord(metadata) || metadata.approvalKind !== "exec") {
+        return null;
+    }
+    const approvalId = typeof metadata.approvalId === "string" ? metadata.approvalId.trim() : "";
+    const approvalSlug = typeof metadata.approvalSlug === "string" ? metadata.approvalSlug.trim() : "";
+    if (!APPROVAL_ID_RE.test(approvalId) ||
+        !APPROVAL_ID_RE.test(approvalSlug) ||
+        !Array.isArray(metadata.allowedDecisions)) {
+        return null;
+    }
+    const allowed = new Set(metadata.allowedDecisions);
+    const allowedDecisions = EXEC_APPROVAL_DECISIONS.filter((decision) => allowed.has(decision));
+    return allowedDecisions.length > 0 ? { approvalId, approvalSlug, allowedDecisions } : null;
+}
+function formatApprovalCommandBlock(command) {
+    return `${TXT_FENCE_OPEN}${command}${FENCE_CLOSE}`;
+}
+function isExecApprovalDecision(value) {
+    return EXEC_APPROVAL_DECISIONS.some((decision) => decision === value);
+}
+function parseApprovalCommand(command) {
+    const match = command.match(/^\/approve ([A-Za-z0-9][A-Za-z0-9._:-]*) (allow-once|allow-always|deny)$/);
+    if (!match || !isExecApprovalDecision(match[2])) {
+        return null;
+    }
+    return {
+        approvalCommandId: match[1],
+        decision: match[2],
+    };
+}
+function readPrimaryApprovalCommand(text) {
+    const marker = `Approval required.\n\nRun:\n\n${TXT_FENCE_OPEN}`;
+    const markerStart = text.startsWith(marker) ? 0 : text.indexOf(`\n\n${marker}`);
+    if (markerStart < 0) {
+        return null;
+    }
+    const commandStart = markerStart + marker.length + (markerStart === 0 ? 0 : 2);
+    const commandEnd = text.indexOf(FENCE_CLOSE, commandStart);
+    if (commandEnd < 0) {
+        return null;
+    }
+    const command = parseApprovalCommand(text.slice(commandStart, commandEnd));
+    return command ? { command, blockEnd: commandEnd + FENCE_CLOSE.length } : null;
+}
+function readPendingCommandBlockEnd(text, start) {
+    const marker = "\n\nPending command:\n\n";
+    if (!text.startsWith(marker, start)) {
+        return null;
+    }
+    const fenceStart = start + marker.length;
+    const openerEnd = text.indexOf("\n", fenceStart);
+    if (openerEnd < 0) {
+        return null;
+    }
+    const opener = text.slice(fenceStart, openerEnd);
+    const openerMatch = opener.match(/^(`{3,})sh$/);
+    if (!openerMatch) {
+        return null;
+    }
+    const closingFence = `\n${openerMatch[1]}`;
+    const closingStart = text.indexOf(closingFence, openerEnd + 1);
+    return closingStart < 0 ? null : closingStart + closingFence.length;
+}
+function splitOtherOptionsText(text, approvalId, allowedDecisions) {
+    if (!text.endsWith(`Full id: \`${approvalId}\``)) {
+        return null;
+    }
+    const primary = readPrimaryApprovalCommand(text);
+    if (!primary) {
+        return null;
+    }
+    const pendingBlockEnd = readPendingCommandBlockEnd(text, primary.blockEnd);
+    if (pendingBlockEnd === null) {
+        return null;
+    }
+    const sectionMarker = `\n\n${OTHER_OPTIONS_HEADER}${TXT_FENCE_OPEN}`;
+    if (!text.startsWith(sectionMarker, pendingBlockEnd)) {
+        return null;
+    }
+    const blockStart = pendingBlockEnd + 2 + OTHER_OPTIONS_HEADER.length;
+    const commandsStart = blockStart + TXT_FENCE_OPEN.length;
+    const commandsEnd = text.indexOf(FENCE_CLOSE, commandsStart);
+    if (commandsEnd < 0) {
+        return null;
+    }
+    const blockEnd = commandsEnd + FENCE_CLOSE.length;
+    const suffix = text.slice(blockEnd);
+    if (suffix && !suffix.startsWith("\n\n")) {
+        return null;
+    }
+    const commands = text.slice(commandsStart, commandsEnd).split("\n");
+    if (commands.length < 2 || commands.some((command) => !command)) {
+        return null;
+    }
+    const parsedCommands = commands.map(parseApprovalCommand);
+    if (parsedCommands.some((command) => command === null)) {
+        return null;
+    }
+    const validCommands = parsedCommands.filter((command) => command !== null);
+    const allowed = new Set(allowedDecisions);
+    if (!allowed.has(primary.command.decision) ||
+        validCommands.some((command) => !allowed.has(command.decision)) ||
+        validCommands.some((command) => command.approvalCommandId !== primary.command.approvalCommandId) ||
+        validCommands.some((command) => command.decision === primary.command.decision) ||
+        new Set(validCommands.map((command) => command.decision)).size !== validCommands.length) {
+        return null;
+    }
+    return [text.slice(0, blockStart), commands.map(formatApprovalCommandBlock).join("\n\n"), text.slice(blockEnd)].join("");
+}
+/**
+ * Add copy-friendly commands to forwarded exec approval prompts.
+ *
+ * OpenClaw supplies the collision-aware short ID and the request-scoped decision
+ * set in channel metadata, so the channel never derives either value from text.
+ */
+export function appendWeixinExecApprovalQuickReplies(params) {
+    if (params.hint?.kind !== "approval-pending" ||
+        params.hint.approvalKind !== "exec" ||
+        !params.payload.text?.startsWith(`${FORWARDED_EXEC_APPROVAL_HEADING}\n`)) {
+        return;
+    }
+    const details = readExecApprovalDetails(params.payload);
+    if (!details) {
+        return;
+    }
+    const forwardedPrefix = `${FORWARDED_EXEC_APPROVAL_HEADING}\nID: ${details.approvalId}`;
+    if (params.payload.text !== forwardedPrefix && !params.payload.text.startsWith(`${forwardedPrefix}\n`)) {
+        return;
+    }
+    const commandBlocks = details.allowedDecisions
+        .map((decision) => formatApprovalCommandBlock(`/approve ${details.approvalSlug} ${decision}`))
+        .join("\n\n");
+    const quickReplies = `${QUICK_REPLIES_HEADING}\n\n${commandBlocks}`;
+    const text = params.payload.text.trimEnd();
+    if (text.endsWith(quickReplies)) {
+        return;
+    }
+    params.payload.text = `${text}\n\n${quickReplies}`;
+}
+/**
+ * Split OpenClaw's direct exec-approval alternatives into individually copyable
+ * code blocks while preserving the exact command IDs rendered by OpenClaw.
+ */
+export function splitWeixinExecApprovalOtherOptions(payload) {
+    if (!payload.text) {
+        return payload;
+    }
+    const details = readExecApprovalDetails(payload);
+    if (!details) {
+        return payload;
+    }
+    const text = splitOtherOptionsText(payload.text, details.approvalId, details.allowedDecisions);
+    return text ? { ...payload, text } : payload;
+}
+//# sourceMappingURL=approval-quick-replies.js.map

package/dist/src/messaging/approval-quick-replies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-quick-replies.js","sourceRoot":"","sources":["../../../src/messaging/approval-quick-replies.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,132 @@
+# Architecture
+
+`openclaw-weixin` adapts the Weixin HTTP/CDN protocol to the OpenClaw channel
+runtime. The plugin owns login, account state, long polling, message conversion,
+and outbound media transfer. OpenClaw owns routing, sessions, command
+authorization, reply generation, hooks, and the unified media store.
+
+The wire-level endpoint and message shapes are documented in the
+[backend API protocol](./backend-api.md).
+
+## Component map
+
+| Component | Responsibility |
+| --- | --- |
+| `index.ts` | Validate host compatibility and register the channel |
+| `src/channel.ts` | Implement the OpenClaw channel contract and account lifecycle |
+| `src/auth/` | QR login, account persistence, ID compatibility, and pairing |
+| `src/api/` | Build authenticated backend requests and classify failures |
+| `src/monitor/monitor.ts` | Poll updates, persist cursors, and schedule inbound work |
+| `src/messaging/process-message.ts` | Authorize, route, record, and dispatch one inbound message |
+| `src/messaging/send*.ts` | Convert outbound text/media to backend message items |
+| `src/cdn/`, `src/media/` | Encrypt, upload, download, decrypt, and transcode media |
+| `src/storage/` | Resolve state paths and persist the polling cursor |
+
+## Plugin and account lifecycle
+
+```mermaid
+flowchart TD
+  A[index.ts register] --> B[Check OpenClaw host version]
+  B --> C[Register weixinPlugin]
+  C --> D{Operation}
+  D -->|login| E[Start QR session]
+  E --> F[Wait for confirmation]
+  F --> G[Persist account and pairing state]
+  G --> H[Trigger channel reload]
+  D -->|start account| I[Restore context tokens]
+  I --> J[Notify backend start]
+  J --> K[Run monitor loop]
+  D -->|stop or reload| L[Abort active poll]
+  L --> M[Notify backend stop]
+```
+
+The plugin/channel ID and state layout are compatibility surfaces. A successful
+login may replace stale account records for the same Weixin user, but it must not
+silently merge unrelated accounts.
+
+## Inbound flow
+
+```mermaid
+sequenceDiagram
+  participant Backend as Weixin backend
+  participant Monitor as monitorWeixinProvider
+  participant Processor as processOneMessage
+  participant Runtime as OpenClaw channel runtime
+
+  Monitor->>Backend: getUpdates(cursor, abort signal)
+  Backend-->>Monitor: messages + next cursor
+  Monitor->>Monitor: persist cursor and account-scoped context token
+  Monitor->>Processor: schedule message
+  Processor->>Processor: handle slash command or download media
+  Processor->>Runtime: authorize sender and resolve agent route
+  Processor->>Runtime: record inbound session
+  Processor->>Runtime: dispatch reply
+  Runtime-->>Processor: text, media, and item lifecycle events
+```
+
+Ordinary messages are serialized until OpenClaw accepts the turn, after which
+polling can admit the next message. Plugin approval commands use a separate lane
+so an active ordinary turn cannot block approval.
+
+## Outbound flow
+
+```mermaid
+flowchart LR
+  A[OpenClaw outbound request] --> B{Account ID supplied?}
+  B -->|yes| C[Resolve configured account]
+  B -->|no| D[Resolve by account-scoped context token]
+  D --> C
+  C --> E[Check active session]
+  E --> F[Run message_sending hook]
+  F -->|cancelled| G[Return without backend send]
+  F -->|continue| H{Text or media?}
+  H -->|text| I[Filter markdown and call sendMessage]
+  H -->|media| J[Download if remote]
+  J --> K[Encrypt and upload to CDN]
+  K --> L[Build media message item]
+  I --> M[Emit message_sent hook]
+  L --> M
+```
+
+With multiple accounts, an omitted account ID is valid only when exactly one
+account can be selected. Ambiguous or missing context must fail rather than risk
+sending from the wrong bot.
+
+## Persistent state
+
+Paths are relative to the OpenClaw state directory unless an existing framework
+override applies.
+
+| Path | Contents |
+| --- | --- |
+| `openclaw-weixin/accounts.json` | Registered normalized account IDs |
+| `openclaw-weixin/accounts/<accountId>.json` | Token, backend URL, save time, and linked user ID |
+| `openclaw-weixin/accounts/<accountId>.sync.json` | `getUpdates` cursor |
+| `openclaw-weixin/accounts/<accountId>.context-tokens.json` | Recipient context tokens for that account |
+| `credentials/openclaw-weixin-<accountId>-allowFrom.json` | Framework pairing allow-list |
+| `openclaw.json` | Channel configuration and account overrides |
+
+Loaders retain fallbacks for legacy raw IDs, a legacy single-account credential
+file, and older sync-buffer paths. Changes to these fallbacks require migration
+tests.
+
+## Failure and privacy boundaries
+
+- Backend HTTP errors are surfaced with actionable context but without raw
+  authorization or context tokens.
+- A stale token pauses all requests for that account before polling resumes.
+- Long polls receive the gateway abort signal so stop/reload does not wait for a
+  server timeout.
+- Media logs must redact URLs and encrypted query parameters.
+- Tests and examples use synthetic IDs such as `account-1` and `user-1`.
+
+## Test seams
+
+- API tests replace `fetch` and assert request/response boundaries.
+- Monitor tests mock polling, cursor persistence, context storage, and message
+  processing.
+- Message-processing tests use a minimal typed channel-runtime fake.
+- Account and storage tests point `OPENCLAW_STATE_DIR` to isolated temporary
+  directories.
+- Shared builders live under `test/helpers/`; test-only files must not be emitted
+  into `dist/`.

package/docs/backend-api.md

@@ -0,0 +1,347 @@
+# Backend API Protocol
+
+[Back to detailed guide](./guide.md) |
+[简体中文](./backend-api.zh_CN.md)
+
+This document covers every Weixin backend endpoint used by the plugin for QR
+login, lifecycle notifications, messaging, and media. The two QR login requests
+always use Tencent's fixed service. A backend selected by the account's
+post-login `baseurl` must implement the lifecycle, messaging, and media
+endpoints.
+
+QR creation and all post-login endpoints use `POST`; QR status polling uses
+`GET`. All requests include:
+
+| Header | Description |
+|--------|-------------|
+| `iLink-App-Id` | Plugin application ID |
+| `iLink-App-ClientVersion` | Plugin version encoded as an unsigned integer |
+| `SKRouteTag` | Optional configured route tag |
+
+`POST` requests additionally include `Content-Type: application/json`,
+`AuthorizationType: ilink_bot_token`, and a random base64-encoded
+`X-WECHAT-UIN`. Authenticated post-login requests also include
+`Authorization: Bearer <bot-token>`; QR status `GET` requests do not include
+these `POST`-specific headers.
+
+Authenticated post-login `POST` bodies include `base_info`; QR creation does
+not. The message examples below omit it for readability.
+
+```json
+{
+  "base_info": {
+    "channel_version": "<plugin version>",
+    "bot_agent": "OpenClaw"
+  }
+}
+```
+
+`bot_agent` is for observability only. Its supported format and configuration
+are documented in the [detailed guide](./guide.md#custom-botagent-optional).
+
+## Endpoint List
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/ilink/bot/get_bot_qrcode?bot_type=3` | Create a QR login session |
+| `GET` | `/ilink/bot/get_qrcode_status?qrcode=<opaque-id>` | Poll QR login status; accepts optional `verify_code` |
+| `POST` | `/ilink/bot/msg/notifystart` | Notify backend that the channel started |
+| `POST` | `/ilink/bot/msg/notifystop` | Notify backend that the channel stopped |
+| `POST` | `/ilink/bot/getupdates` | Long-poll for new messages |
+| `POST` | `/ilink/bot/sendmessage` | Send a message (text/image/video/file) |
+| `POST` | `/ilink/bot/getuploadurl` | Get CDN upload pre-signed parameters |
+| `POST` | `/ilink/bot/getconfig` | Get account config (typing ticket, etc.) |
+| `POST` | `/ilink/bot/sendtyping` | Send/cancel typing status |
+
+The first two rows describe the fixed QR login service. They are not sent to the
+account's post-login `baseurl`.
+
+## QR Login and Lifecycle
+
+Create a QR session with:
+
+```http
+POST /ilink/bot/get_bot_qrcode?bot_type=3
+Content-Type: application/json
+```
+
+```json
+{
+  "local_token_list": []
+}
+```
+
+The response contains an opaque `qrcode` identifier and
+`qrcode_img_content`, the URL rendered as the QR code. Poll
+`GET /ilink/bot/get_qrcode_status?qrcode=<opaque-id>` until it reaches a
+terminal state. The optional `verify_code` query parameter handles verification
+challenges.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `string` | `wait`, `scaned`, `need_verifycode`, `verify_code_blocked`, `expired`, `scaned_but_redirect`, `binded_redirect`, or `confirmed` |
+| `bot_token` | `string?` | Bot credential returned after confirmation |
+| `ilink_bot_id` | `string?` | Required account ID after confirmation |
+| `baseurl` | `string?` | Account API base URL |
+| `ilink_user_id` | `string?` | ID of the user who scanned the QR code |
+| `redirect_host` | `string?` | New polling host for `scaned_but_redirect` |
+
+After authentication, call `/ilink/bot/msg/notifystart` when the channel starts
+and `/ilink/bot/msg/notifystop` when it stops. Both receive the standard
+`base_info` body and return:
+
+```json
+{
+  "ret": 0,
+  "errmsg": ""
+}
+```
+
+QR identifiers, verification codes, bot tokens, account IDs, user IDs, and
+context tokens are sensitive. Never place real values in logs or examples.
+
+## getUpdates
+
+Long-polling endpoint. The server responds when new messages arrive or on
+timeout.
+
+**Request body:**
+
+```json
+{
+  "get_updates_buf": ""
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `get_updates_buf` | `string` | Sync cursor from the previous response; empty string for the first request |
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "msgs": [],
+  "get_updates_buf": "<new cursor>",
+  "longpolling_timeout_ms": 35000
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ret` | `number` | Return code, `0` = success |
+| `errcode` | `number?` | Error code (e.g., `-14` = stale token) |
+| `errmsg` | `string?` | Error description |
+| `msgs` | `WeixinMessage[]` | Message list (structure below) |
+| `get_updates_buf` | `string` | New sync cursor to pass in the next request |
+| `longpolling_timeout_ms` | `number?` | Server-suggested long-poll timeout for the next request (ms) |
+
+## sendMessage
+
+Send a message to a user.
+
+**Request body:**
+
+```json
+{
+  "msg": {
+    "to_user_id": "<target user ID>",
+    "context_token": "<conversation context token>",
+    "item_list": [
+      {
+        "type": 1,
+        "text_item": { "text": "Hello" }
+      }
+    ]
+  }
+}
+```
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "errmsg": ""
+}
+```
+
+## getUploadUrl
+
+Get CDN upload pre-signed parameters. Call this endpoint before uploading a file
+to obtain `upload_param` and `thumb_upload_param`.
+
+**Request body:**
+
+```json
+{
+  "filekey": "<file identifier>",
+  "media_type": 1,
+  "to_user_id": "<target user ID>",
+  "rawsize": 12345,
+  "rawfilemd5": "<plaintext MD5>",
+  "filesize": 12352,
+  "no_need_thumb": true,
+  "aeskey": "<32-character hex AES key>"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `filekey` | `string` | Per-upload file identifier |
+| `media_type` | `number` | `1` = IMAGE, `2` = VIDEO, `3` = FILE, `4` = VOICE |
+| `to_user_id` | `string` | Target user ID |
+| `rawsize` | `number` | Original file plaintext size |
+| `rawfilemd5` | `string` | Original file plaintext MD5 |
+| `filesize` | `number` | Ciphertext size after AES-128-ECB encryption |
+| `no_need_thumb` | `boolean?` | Set `true` to omit thumbnail upload parameters |
+| `aeskey` | `string?` | AES-128 key as 32 hexadecimal characters |
+| `thumb_rawsize` | `number?` | Thumbnail plaintext size when a thumbnail is requested |
+| `thumb_rawfilemd5` | `string?` | Thumbnail plaintext MD5 when requested |
+| `thumb_filesize` | `number?` | Thumbnail ciphertext size when requested |
+
+**Response body:**
+
+```json
+{
+  "upload_param": "<original image upload encrypted parameters>",
+  "upload_full_url": "https://cdn.example.test/upload",
+  "thumb_upload_param": "<optional thumbnail upload parameters>"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `upload_param` | `string?` | Parameters used to construct the CDN upload URL |
+| `upload_full_url` | `string?` | Complete CDN upload URL; takes precedence over `upload_param` |
+| `thumb_upload_param` | `string?` | Optional thumbnail upload parameters |
+
+## getConfig
+
+Get account configuration, including the typing ticket.
+
+**Request body:**
+
+```json
+{
+  "ilink_user_id": "<user ID>",
+  "context_token": "<optional, conversation context token>"
+}
+```
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "errmsg": "",
+  "typing_ticket": "<base64-encoded typing ticket>"
+}
+```
+
+## sendTyping
+
+Send or cancel the typing status indicator.
+
+**Request body:**
+
+```json
+{
+  "ilink_user_id": "<user ID>",
+  "typing_ticket": "<obtained from getConfig>",
+  "status": 1
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `number` | `1` = typing, `2` = cancel typing |
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "errmsg": ""
+}
+```
+
+## Message Structure
+
+### WeixinMessage
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `seq` | `number?` | Message sequence number |
+| `message_id` | `number?` | Unique message ID |
+| `from_user_id` | `string?` | Sender ID |
+| `to_user_id` | `string?` | Receiver ID |
+| `client_id` | `string?` | Client-generated message ID |
+| `create_time_ms` | `number?` | Creation timestamp (ms) |
+| `update_time_ms` | `number?` | Update timestamp (ms) |
+| `delete_time_ms` | `number?` | Deletion timestamp (ms) |
+| `session_id` | `string?` | Session ID |
+| `group_id` | `string?` | Group ID |
+| `message_type` | `number?` | `1` = USER, `2` = BOT |
+| `message_state` | `number?` | `0` = NEW, `1` = GENERATING, `2` = FINISH |
+| `item_list` | `MessageItem[]?` | Message content list |
+| `context_token` | `string?` | Conversation context token, must be passed back when replying |
+| `run_id` | `string?` | OpenClaw run ID for generated replies |
+
+### MessageItem
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `number` | `1` TEXT, `2` IMAGE, `3` VOICE, `4` FILE, `5` VIDEO, `11` TOOL_CALL_START, `12` TOOL_CALL_RESULT |
+| `create_time_ms` | `number?` | Item creation timestamp |
+| `update_time_ms` | `number?` | Item update timestamp |
+| `is_completed` | `boolean?` | Whether a progress item is complete |
+| `msg_id` | `string?` | Item message ID |
+| `text_item` | `{ text: string }?` | Text content |
+| `image_item` | `ImageItem?` | Image (with CDN reference and AES key) |
+| `voice_item` | `VoiceItem?` | Voice (SILK encoded) |
+| `file_item` | `FileItem?` | File attachment |
+| `video_item` | `VideoItem?` | Video |
+| `ref_msg` | `RefMessage?` | Referenced message |
+| `tool_call_start_item` | `{ tool_name?: string; tool_call_id?: string }?` | Tool invocation metadata |
+| `tool_call_result_item` | `{ tool_name?: string; tool_call_id?: string; status?: string }?` | Tool completion metadata |
+
+### Nested Item Structures
+
+| Structure | Fields |
+|-----------|--------|
+| `RefMessage` | `message_item?: MessageItem`, `title?: string` |
+| `ImageItem` | `media?: CDNMedia`, `thumb_media?: CDNMedia`, `aeskey?: string`, `url?: string`, `mid_size?: number`, `thumb_size?: number`, `thumb_height?: number`, `thumb_width?: number`, `hd_size?: number` |
+| `VoiceItem` | `media?: CDNMedia`, `encode_type?: number`, `bits_per_sample?: number`, `sample_rate?: number`, `playtime?: number`, `text?: string` |
+| `FileItem` | `media?: CDNMedia`, `file_name?: string`, `md5?: string`, `len?: string` |
+| `VideoItem` | `media?: CDNMedia`, `video_size?: number`, `play_length?: number`, `video_md5?: string`, `thumb_media?: CDNMedia`, `thumb_size?: number`, `thumb_height?: number`, `thumb_width?: number` |
+| `ToolCallStartItem` | `tool_name?: string`, `tool_call_id?: string` |
+| `ToolCallResultItem` | `tool_name?: string`, `tool_call_id?: string`, `status?: string` |
+
+### CDN Media Reference (CDNMedia)
+
+All media types (image/voice/file/video) are transferred via CDN using
+AES-128-ECB encryption:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `encrypt_query_param` | `string?` | Encrypted parameters for CDN download/upload |
+| `aes_key` | `string?` | Base64-encoded AES-128 key |
+| `encrypt_type` | `number?` | Encryption metadata mode |
+| `full_url` | `string?` | Complete download URL returned by the backend |
+
+## CDN Upload Flow
+
+1. Calculate the file's plaintext size, MD5, and ciphertext size after
+   AES-128-ECB encryption
+2. If a thumbnail is needed (image/video), calculate the thumbnail's plaintext
+   and ciphertext parameters as well
+3. Call `getUploadUrl` to get `upload_full_url` or `upload_param` (and optional
+   `thumb_upload_param`)
+4. Encrypt the file content with AES-128-ECB and `POST` it to the CDN URL as
+   `application/octet-stream`
+5. Encrypt and upload the thumbnail in the same way when requested
+6. Read `x-encrypted-param` from the CDN response and use it as
+   `encrypt_query_param` in the `CDNMedia` reference
+7. Include the reference in the `MessageItem` and send