@zhin.js/adapter-qq 5.0.3 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @zhin.js/adapter-qq
 
+## 6.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- 9c997b2: 通用 endpoint 管理命令套件：`@zhin.js/adapter` 新增 `createEndpointCommands(spec, defineCommand)`——`<adapter> endpoint list / add <name> key=value... / remove <name>` 三件套，含 kv 解析、`.env` 凭据派生（`<ADAPTER>_<NAME>_<FIELD>`）、yaml 写回保留注释、master 权限门禁（通用 `isEndpointOperator`）、自定义 bindFlow 钩子。QQ 迁移至套件（行为与扫码绑定流程不变）；napcat / onebot11 / onebot12 / milky / slack / telegram 接入（字段对齐各自 schema，features 补 @zhin.js/command）。
+- 3e925d0: QQ 出站富媒体移植（自 legacy）：`image` 段支持 http(s) URL 直发与 base64/本地路径经 SDK `/files` 上传；`markdown` 段（原文与 custom_template_id+params 模板）；`keyboard` 段（按钮矩阵 callback/command，自动合并为 markdown+keyboard 载荷）；`at`/`reply` 段透传。文本行为不变，不可映射段降级文本并 warn。
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 6.0.0
+
+### Minor Changes
+
+- 3ea88d8: 恢复 legacy 的聊天命令添加 endpoint 能力（随适配器发布）：`qq endpoint add [name]`（手机 QQ 扫码绑定 → 凭据写 `.env` 的 `QQ_<NAME>_APPID/SECRET` → 追加 `plugins.qq.endpoints` 配置，重启生效）、`qq endpoint cancel`（中止绑定）、`qq endpoint list`（运行中 + 配置内 endpoints）、`qq endpoint remove <name>`（移除配置项）。add/cancel/remove 受 `master` 限制（顶层或 `endpoints[i]` 声明时仅 master 可执行，未配置则放行）；schema 新增顶层共享字段 `master`。绑定协议（create_bind_task / poll_bind_result / AES-256-GCM 解密）自 legacy 移植，二维码当前以链接文本下发（QQ 出站富媒体待迁移）。
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- e5c84ed: Adapter 多账号：插件实例 config 支持 `endpoints: [{name, ...覆盖}]` 数组，`expandEndpointConfigs` 将一个实例展开为多个 endpoint record（id 为 `<slotId>~<name>`，顶层字段共享、逐项覆盖），替代多 `instanceKey` 方案；Console `/api/plugins` 收敛为一个插件卡片 + 多 endpoint。icqq / qq schema 与 README 补 `endpoints` 配置。
+
+  Plugin Runtime Console Host：补 `/esm/*` React/router ESM 代理路由（legacy `consoleApiRouter` 对齐），TypeScriptClientBuilder 裸导入改写为 `/esm/<enc>.mjs`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+  - @zhin.js/command@1.0.2
+
 ## 5.0.3
 
 ### Patch Changes

package/README.md

@@ -36,7 +36,7 @@ pnpm add @zhin.js/adapter-qq
 | **WebSocket（默认）** | `qq-official-bot` 正向连接；无需公网回调 |
 | **host-http** | WebSocket **不需要**；Webhook / middleware 模式需要（经 `httpHostToken`） |
 
-必填字段：`appid`、`secret`。
+必填字段（`endpoints[i]`）：`name`、`appid`、`secret`。
 
 ## 最小配置
 
@@ -44,14 +44,46 @@ pnpm add @zhin.js/adapter-qq
 # zhin.config.yml（Plugin Runtime）
 plugins:
   qq:
-    name: my-qq-bot
-    appid: ${QQ_APPID}
-    secret: ${QQ_SECRET}
     # mode: websocket   # 默认
+    endpoints:
+      - name: my-qq-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+```
+
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  qq:
+    mode: websocket
+    intents: [GUILDS, GROUP_AND_C2C_EVENT]
+    endpoints:
+      - name: main-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+      - name: second-bot
+        appid: ${QQ_APPID_2}
+        secret: ${QQ_SECRET_2}
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
 
+## Endpoint 管理命令
+
+适配器自带 `qq endpoint` 命令组（聊天内直接使用，默认无前缀；受 `commandPrefix` 影响）：
+
+| 命令 | 说明 |
+|------|------|
+| `qq endpoint add [name]` | 手机 QQ 扫码绑定：下发二维码链接 → 确认后凭据写入 `.env`（`QQ_<NAME>_APPID/SECRET`），并追加 `plugins.qq.endpoints`（重启生效） |
+| `qq endpoint cancel` | 取消进行中的扫码绑定（同时只允许一个流程） |
+| `qq endpoint list` | 列出运行中与配置中的 endpoints |
+| `qq endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |
+
+add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i]`）时仅
+master 可执行；未配置则放行（首个扫码绑定者即 owner）。二维码当前以链接文本下发
+（出站富媒体待迁移），用手机 QQ 打开链接即可扫码。
+
 ## 环境变量
 
 | 变量 | 说明 |

package/adapters/qq.ts

@@ -9,6 +9,7 @@ import {
   resolveQqConfig,
   type QqAdapterConfig,
 } from '../src/protocol.js';
+import { qqRuntimeStateToken } from '../src/qq-runtime-state.js';
 
 export {
   QqHttpEndpoint,
@@ -25,21 +26,39 @@ export type {
 
 export default defineAdapter<QqAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
+  // markdown/keyboard 原生按钮承载交互段。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
+  },
   create(context) {
     const config = resolveQqConfig(context.config);
     const gateway = context.use(messageGatewayToken);
-    if (config.mode === 'webhook' || config.mode === 'middleware') {
-      return new QqHttpEndpoint({
+    // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
+    const state = context.use(qqRuntimeStateToken);
+    state.endpoints.set(config.name, {
+      name: config.name,
+      mode: config.mode,
+    });
+    const endpoint = (config.mode === 'webhook' || config.mode === 'middleware')
+      ? new QqHttpEndpoint({
         id: context.id,
         gateway,
         http: context.use(httpHostToken),
         config,
+      })
+      : new QqWebsocketEndpoint({
+        id: context.id,
+        gateway,
+        config,
       });
-    }
-    return new QqWebsocketEndpoint({
-      id: context.id,
-      gateway,
-      config,
-    });
+    // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 endpoint list 仍显示运行中。
+    const stopEndpoint = endpoint.stop.bind(endpoint);
+    endpoint.stop = async () => {
+      state.endpoints.delete(config.name);
+      await stopEndpoint();
+    };
+    return endpoint;
   },
 });

package/commands/endpoint/add/[name:string=].ts

@@ -0,0 +1,3 @@
+import { qqEndpointCommands } from '../../../src/qq-endpoint-commands.js';
+
+export default qqEndpointCommands.add;

package/commands/endpoint/cancel.ts

@@ -0,0 +1,15 @@
+import { defineCommand } from '@zhin.js/command';
+import {
+  isQqEndpointOperator,
+  QQ_ENDPOINT_FORBIDDEN,
+  runQqEndpointCancel,
+} from '../../src/qq-endpoint-commands.js';
+import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
+
+export default defineCommand({
+  description: '取消进行中的 QQ 扫码绑定流程',
+  execute({ config, input, use }) {
+    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
+    return runQqEndpointCancel(use(qqRuntimeStateToken));
+  },
+});

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { qqEndpointCommands } from '../../src/qq-endpoint-commands.js';
+
+export default qqEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { qqEndpointCommands } from '../../../src/qq-endpoint-commands.js';
+
+export default qqEndpointCommands.remove;

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -18,7 +18,10 @@ export interface QqEndpointOptions {
 }
 export declare class QqWebsocketEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: QqEndpointOptions);
+    /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
+    get name(): string;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -48,7 +51,10 @@ export interface QqHttpEndpointOptions {
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
 export declare class QqHttpEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: QqHttpEndpointOptions);
+    /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+    get name(): string;
     start(): Promise<void>;
     open(): void;
     close(): void;

package/lib/endpoint.js

@@ -1,6 +1,7 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatOutbound } from './outbound.js';
 import { registerQqAgentEndpoint } from './qq-agent-deps.js';
-import { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
+import { formatInboundContent, formatInboundTarget, parseSendTarget, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
 const logger = getLogger('qq');
@@ -11,10 +12,15 @@ export class QqWebsocketEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createQqEndpointManagement(this);
     constructor(options) {
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateBot;
     }
+    /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
+    get name() {
+        return this.#options.config.name;
+    }
     async start() {
         if (this.#started)
             return;
@@ -34,7 +40,8 @@ export class QqWebsocketEndpoint {
         catch (error) {
             await this.stop();
             logger.error('Failed to connect QQ websocket:', error);
-            throw error;
+            const raw = error instanceof Error ? error.message : String(error);
+            throw new Error(`QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`, { cause: error });
         }
     }
     open() {
@@ -61,7 +68,7 @@ export class QqWebsocketEndpoint {
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
-        const body = formatOutboundText(payload);
+        const body = formatOutbound(payload);
         const parsed = parseSendTarget(target);
         const bot = this.#requireBot();
         let result;
@@ -166,10 +173,15 @@ export class QqHttpEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createQqEndpointManagement(this);
     constructor(options) {
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateHttpBot;
     }
+    /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+    get name() {
+        return this.#options.config.name;
+    }
     async start() {
         if (this.#started)
             return;
@@ -219,7 +231,7 @@ export class QqHttpEndpoint {
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
-        const body = formatOutboundText(payload);
+        const body = formatOutbound(payload);
         const parsed = parseSendTarget(target);
         const bot = this.#requireBot();
         let result;
@@ -313,3 +325,36 @@ export class QqHttpEndpoint {
         return this.#bot;
     }
 }
+function createQqEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listChannels() {
+            const channels = [];
+            const guilds = await endpoint.getGuilds();
+            for (const guildValue of Array.isArray(guilds) ? guilds : []) {
+                const guild = asRecord(guildValue);
+                const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
+                if (!guildId)
+                    continue;
+                const guildName = String(guild.name ?? guild.guild_name ?? guildId);
+                const rows = await endpoint.getChannels(guildId);
+                for (const channelValue of Array.isArray(rows) ? rows : []) {
+                    const channel = asRecord(channelValue);
+                    const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');
+                    if (!id)
+                        continue;
+                    channels.push({
+                        id,
+                        name: String(channel.name ?? channel.channel_name ?? id),
+                        parent: { type: 'guild', id: guildId, name: guildName },
+                    });
+                }
+            }
+            return channels;
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, type ParsedSendTarget, type QqAdapterConfig, type QqChannelKind, type QqInboundMessage, type QqWireSegment, type ResolvedQqConfig, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig, } from './protocol.js';
+export { formatOutbound, resolveMediaFile, type QqOutboundElem, type QqOutboundMessage, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, type QqWebhookHandler, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export { formatInboundContent, formatInboundTarget, formatOutboundText, parseSendTarget, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
+export { formatOutbound, resolveMediaFile, } from './outbound.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';

package/lib/outbound.d.ts

@@ -0,0 +1,17 @@
+/** qq-official-bot Sendable 的最小结构子集（字符串模板或消息段）。 */
+export interface QqOutboundElem {
+    readonly type: string;
+    readonly data: Record<string, unknown>;
+}
+export type QqOutboundMessage = string | QqOutboundElem | readonly (string | QqOutboundElem)[];
+/**
+ * 解析 image/audio/video/file 段的本地或内联 payload。
+ * qq-official-bot 的 formatMediaData 对 data.url 直接当远程 URL；
+ * base64:// / data:...;base64 / 本地路径须走 data.file 才会解析为 file_data。
+ */
+export declare function resolveMediaFile(data: Record<string, unknown>): string | undefined;
+/**
+ * 渲染后 payload → QQ Sendable。
+ * 纯文本输入原样返回（与既有行为一致）；含富媒体段时返回段数组。
+ */
+export declare function formatOutbound(payload: unknown): QqOutboundMessage;

package/lib/outbound.js

@@ -0,0 +1,241 @@
+/**
+ * QQ 官方出站富媒体归一化：把渲染后的 payload 转为 qq-official-bot 可识别的
+ * Sendable 结构（文本串 + 消息段）。移植自 legacy 版 outbound-media /
+ * outbound-markdown / outbound-keyboard。
+ *
+ * 移植面：
+ * - image：http(s) URL 直发（data.url）；base64://、data:...;base64、本地路径
+ *   归一到 data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
+ * - markdown：data.content 原文，或 custom_template_id + params 模板。
+ * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
+ *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
+ *   data.id 模板键盘原样透传。
+ * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('qq');
+function isRemoteUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function isInlineBase64(value) {
+    return value.startsWith('base64://') || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+}
+/**
+ * 解析 image/audio/video/file 段的本地或内联 payload。
+ * qq-official-bot 的 formatMediaData 对 data.url 直接当远程 URL；
+ * base64:// / data:...;base64 / 本地路径须走 data.file 才会解析为 file_data。
+ */
+export function resolveMediaFile(data) {
+    const url = typeof data.url === 'string' ? data.url : undefined;
+    const file = typeof data.file === 'string' ? data.file : undefined;
+    const base64 = typeof data.base64 === 'string' ? data.base64 : undefined;
+    if (file && !isRemoteUrl(file))
+        return file;
+    if (url && isInlineBase64(url))
+        return url;
+    if (url && !isRemoteUrl(url) && (url.startsWith('file://') || url.startsWith('/')))
+        return url;
+    if (base64)
+        return base64.startsWith('base64://') ? base64 : `base64://${base64}`;
+    return undefined;
+}
+function normalizeMediaSegment(seg) {
+    const data = { ...(seg.data ?? {}) };
+    const file = resolveMediaFile(data);
+    if (file) {
+        delete data.url;
+        delete data.base64;
+        data.file = file;
+        return { type: seg.type, data };
+    }
+    const url = typeof data.url === 'string' ? data.url
+        : typeof data.file === 'string' ? data.file
+            : undefined;
+    if (url && isRemoteUrl(url)) {
+        delete data.base64;
+        return { type: seg.type, data: { ...data, url } };
+    }
+    // 既无远程 URL 也无本地上传源：无法投递，降级留痕
+    logger.warn(formatCompact({
+        op: 'qq_outbound_media_dropped',
+        type: seg.type,
+        reason: 'missing_source',
+    }));
+    return null;
+}
+function normalizeMarkdownSegment(seg) {
+    const data = seg.data ?? {};
+    const templateId = typeof data.custom_template_id === 'string' && data.custom_template_id
+        ? data.custom_template_id
+        : typeof data.template_id === 'string' && data.template_id
+            ? data.template_id
+            : undefined;
+    if (templateId) {
+        return {
+            type: 'markdown',
+            data: {
+                custom_template_id: templateId,
+                params: Array.isArray(data.params) ? data.params : [],
+            },
+        };
+    }
+    const content = String(data.content ?? data.text ?? '');
+    if (!content.trim()) {
+        logger.warn(formatCompact({ op: 'qq_outbound_markdown_dropped', reason: 'empty_content' }));
+        return null;
+    }
+    return { type: 'markdown', data: { content } };
+}
+function coreButtonToQq(btn) {
+    const isCommand = btn.mode === 'command';
+    const action = {
+        type: isCommand ? 2 : 1,
+        permission: { type: 2 },
+        data: btn.payload ?? '',
+        click_limit: btn.disabled ? 0 : 10,
+        unsupport_tips: btn.disabled ? '该按钮不可用' : '',
+    };
+    if (isCommand) {
+        if (btn.command?.enter != null)
+            action.enter = btn.command.enter;
+        if (btn.command?.reply != null)
+            action.reply = btn.command.reply;
+    }
+    return {
+        id: btn.id ?? '',
+        render_data: {
+            label: btn.label ?? '',
+            visited_label: btn.label ?? '',
+            style: 0,
+        },
+        action,
+    };
+}
+/** keyboard 段 → 模板键盘（data.id）或 button 行段（data.rows） */
+function expandKeyboardSegment(seg) {
+    const data = seg.data ?? {};
+    if (typeof data.id === 'string' && data.id) {
+        return [{ type: 'keyboard', data: { id: data.id } }];
+    }
+    if (!Array.isArray(data.rows)) {
+        logger.warn(formatCompact({ op: 'qq_outbound_keyboard_dropped', reason: 'missing_rows' }));
+        return [];
+    }
+    const out = [];
+    for (const row of data.rows) {
+        if (!Array.isArray(row))
+            continue;
+        out.push({
+            type: 'button',
+            data: {
+                buttons: row.map((btn) => coreButtonToQq((btn ?? {}))),
+            },
+        });
+    }
+    return out;
+}
+function toSegmentList(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    if (payload && typeof payload === 'object' && 'type' in payload) {
+        return [payload];
+    }
+    return [];
+}
+function textFromUnknownSegment(seg) {
+    const data = seg.data ?? {};
+    return data.text != null ? String(data.text) : '';
+}
+/**
+ * 渲染后 payload → QQ Sendable。
+ * 纯文本输入原样返回（与既有行为一致）；含富媒体段时返回段数组。
+ */
+export function formatOutbound(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    const segments = toSegmentList(payload);
+    if (segments.length === 0) {
+        return payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+    }
+    // QQ 按钮消息必须携带 markdown（msg_type=2），keyboard 存在时文本合并为 markdown 段
+    const hasKeyboard = segments.some((item) => typeof item !== 'string' && item.type === 'keyboard');
+    const parts = [];
+    let textBuf = '';
+    const flushText = () => {
+        if (!textBuf)
+            return;
+        parts.push(hasKeyboard
+            ? { type: 'markdown', data: { content: textBuf } }
+            : textBuf);
+        textBuf = '';
+    };
+    for (const item of segments) {
+        if (typeof item === 'string') {
+            textBuf += item;
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                textBuf += String(data.text ?? data.content ?? '');
+                break;
+            case 'at': {
+                const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+                if (!id)
+                    break;
+                flushText();
+                parts.push({ type: 'at', data: { user_id: id } });
+                break;
+            }
+            case 'image':
+            case 'audio':
+            case 'video':
+            case 'file': {
+                flushText();
+                const media = normalizeMediaSegment(item);
+                if (media)
+                    parts.push(media);
+                break;
+            }
+            case 'markdown': {
+                flushText();
+                const markdown = normalizeMarkdownSegment(item);
+                if (markdown)
+                    parts.push(markdown);
+                break;
+            }
+            case 'keyboard': {
+                flushText();
+                parts.push(...expandKeyboardSegment(item));
+                break;
+            }
+            case 'reply': {
+                const id = data.id ?? data.event_id;
+                if (id == null || id === '')
+                    break;
+                flushText();
+                parts.push({
+                    type: 'reply',
+                    data: data.event_id != null
+                        ? { event_id: String(data.event_id) }
+                        : { id: String(id) },
+                });
+                break;
+            }
+            default:
+                // 未识别段：保持既有文本降级
+                textBuf += textFromUnknownSegment(item);
+                break;
+        }
+    }
+    flushText();
+    if (parts.length === 0)
+        return '';
+    if (parts.length === 1)
+        return parts[0];
+    return parts;
+}

package/lib/protocol.js

@@ -3,6 +3,8 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { pickCredential } from '@zhin.js/adapter';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('qq');
 export function resolveQqConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
     const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
@@ -96,8 +98,19 @@ export function formatOutboundText(payload) {
                 const id = String(data.user_id ?? data.qq ?? data.id ?? '');
                 return id ? `<@!${id}>` : '';
             }
-            case 'image':
-                return String(data.url || data.file || '');
+            case 'image': {
+                const src = String(data.url || data.file || '');
+                // base64/本地路径由 formatOutbound 走媒体上传，文本视图静默省略；
+                // 仅当彻底缺少来源时留痕，避免出站静默降级排障无头绪。
+                if (!src) {
+                    logger.warn(formatCompact({
+                        op: 'qq_outbound_image_dropped',
+                        reason: 'missing_source',
+                    }));
+                    return '';
+                }
+                return /^https?:\/\//.test(src) ? src : '';
+            }
             case 'reply':
                 return '';
             default: