@zhin.js/adapter-qq 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @zhin.js/adapter-qq
 
+## 6.0.2
+
+### Patch Changes
+
+- d5cd4aa: Publish Plugin Runtime entry points and convention modules as JavaScript so
+  installed npm plugins load on Node without TypeScript stripping. Workspace
+  development continues to prefer TypeScript sources for local HMR.
+
+  Remove the unconsumed legacy game hub APIs from game-kit; game navigation and
+  records now use ordinary convention commands owned by the game hub plugin.
+
+- Updated dependencies [d5cd4aa]
+  - @zhin.js/command@1.0.4
+  - zhin.js@5.0.2
+  - @zhin.js/adapter@1.1.2
+  - @zhin.js/core@1.4.2
+  - @zhin.js/agent@1.0.7
+
+## 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

package/adapters/qq.js

@@ -0,0 +1,49 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/qq.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from "../lib/endpoint.js";
+import { resolveQqConfig, } from "../lib/protocol.js";
+import { qqRuntimeStateToken } from "../lib/qq-runtime-state.js";
+export { QqHttpEndpoint, QqWebsocketEndpoint, } from "../lib/endpoint.js";
+export default defineAdapter({
+    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);
+        // 注册到插件运行时状态（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,
+            });
+        // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 endpoint list 仍显示运行中。
+        const stopEndpoint = endpoint.stop.bind(endpoint);
+        endpoint.stop = async () => {
+            state.endpoints.delete(config.name);
+            await stopEndpoint();
+        };
+        return endpoint;
+    },
+});

package/adapters/qq.ts

@@ -26,26 +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);
     // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
-    context.use(qqRuntimeStateToken).endpoints.set(config.name, {
+    const state = context.use(qqRuntimeStateToken);
+    state.endpoints.set(config.name, {
       name: config.name,
       mode: config.mode,
     });
-    if (config.mode === 'webhook' || config.mode === 'middleware') {
-      return new QqHttpEndpoint({
+    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=].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { qqEndpointCommands } from "../../../lib/qq-endpoint-commands.js";
+export default qqEndpointCommands.add;

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

@@ -1,21 +1,3 @@
-import { defineCommand } from '@zhin.js/command';
-import {
-  extractQqCommandReply,
-  isQqEndpointOperator,
-  QQ_ENDPOINT_FORBIDDEN,
-  runQqEndpointAdd,
-} from '../../../src/qq-endpoint-commands.js';
-import { qqRuntimeStateToken } from '../../../src/qq-runtime-state.js';
+import { qqEndpointCommands } from '../../../src/qq-endpoint-commands.js';
 
-export default defineCommand({
-  description: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
-  execute({ config, input, params, use }) {
-    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
-    const name = typeof params.name === 'string' && params.name.trim() ? params.name.trim() : undefined;
-    return runQqEndpointAdd(
-      use(qqRuntimeStateToken),
-      name,
-      extractQqCommandReply(input),
-    );
-  },
-});
+export default qqEndpointCommands.add;

package/commands/endpoint/cancel.js

@@ -0,0 +1,12 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from '@zhin.js/command';
+import { isQqEndpointOperator, QQ_ENDPOINT_FORBIDDEN, runQqEndpointCancel, } from "../../lib/qq-endpoint-commands.js";
+import { qqRuntimeStateToken } from "../../lib/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.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { qqEndpointCommands } from "../../lib/qq-endpoint-commands.js";
+export default qqEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -1,10 +1,3 @@
-import { defineCommand } from '@zhin.js/command';
-import { runQqEndpointList } from '../../src/qq-endpoint-commands.js';
-import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
+import { qqEndpointCommands } from '../../src/qq-endpoint-commands.js';
 
-export default defineCommand({
-  description: '列出 QQ endpoints（运行中 + zhin.config.yml 配置）',
-  execute({ use }) {
-    return runQqEndpointList(use(qqRuntimeStateToken));
-  },
-});
+export default qqEndpointCommands.list;

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

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { qqEndpointCommands } from "../../../lib/qq-endpoint-commands.js";
+export default qqEndpointCommands.remove;

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

@@ -1,15 +1,3 @@
-import { defineCommand } from '@zhin.js/command';
-import {
-  isQqEndpointOperator,
-  QQ_ENDPOINT_FORBIDDEN,
-  runQqEndpointRemove,
-} from '../../../src/qq-endpoint-commands.js';
-import { qqRuntimeStateToken } from '../../../src/qq-runtime-state.js';
+import { qqEndpointCommands } from '../../../src/qq-endpoint-commands.js';
 
-export default defineCommand({
-  description: '从 zhin.config.yml 的 plugins.qq.endpoints 移除指定 endpoint（重启生效）',
-  execute({ config, input, params, use }) {
-    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
-    return runQqEndpointRemove(use(qqRuntimeStateToken), String(params.name ?? ''));
-  },
-});
+export default qqEndpointCommands.remove;

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');
@@ -39,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() {
@@ -66,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;
@@ -229,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;

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:

package/lib/qq-bind-persist.d.ts

@@ -1,3 +1,5 @@
+import { resolveProjectRoot } from '@zhin.js/adapter';
+export { resolveProjectRoot };
 export interface QqCredentialEnvKeys {
     appidKey: string;
     secretKey: string;
@@ -6,7 +8,5 @@ export interface QqCredentialEnvKeys {
 }
 /** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
 export declare function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys;
-/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
-export declare function resolveProjectRoot(): string;
 /** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
 export declare function persistQqCredentialsToEnv(endpointName: string, appId: string, appSecret: string, projectRoot?: string): QqCredentialEnvKeys;

package/lib/qq-bind-persist.js

@@ -1,10 +1,9 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import { buildEndpointEnvKey, persistEndpointEnvValues, resolveProjectRoot, } from '@zhin.js/adapter';
+export { resolveProjectRoot };
 /** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
 export function buildQqCredentialEnvKeys(endpointName) {
-    const slug = endpointName.replace(/[^a-zA-Z0-9_]/g, '_').toUpperCase();
-    const appidKey = `QQ_${slug}_APPID`;
-    const secretKey = `QQ_${slug}_SECRET`;
+    const appidKey = buildEndpointEnvKey('qq', endpointName, 'appid');
+    const secretKey = buildEndpointEnvKey('qq', endpointName, 'secret');
     return {
         appidKey,
         secretKey,
@@ -12,40 +11,12 @@ export function buildQqCredentialEnvKeys(endpointName) {
         secretRef: `\${${secretKey}}`,
     };
 }
-/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
-export function resolveProjectRoot() {
-    const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
-    return path.resolve(envRoot || process.cwd());
-}
-function escapeRegExp(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function upsertEnvLine(content, key, value) {
-    const lineRe = new RegExp(`^${escapeRegExp(key)}\\s*=.*$`, 'm');
-    const newLine = `${key}=${value}`;
-    if (lineRe.test(content)) {
-        return content.replace(lineRe, newLine);
-    }
-    const trimmed = content.replace(/\s*$/, '');
-    if (trimmed.length === 0) {
-        return `${newLine}\n`;
-    }
-    return `${trimmed}\n${newLine}\n`;
-}
 /** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
 export function persistQqCredentialsToEnv(endpointName, appId, appSecret, projectRoot) {
     const keys = buildQqCredentialEnvKeys(endpointName);
-    const root = projectRoot ?? resolveProjectRoot();
-    const envPath = path.join(root, '.env');
-    let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
-    const entries = {
+    persistEndpointEnvValues({
         [keys.appidKey]: appId,
         [keys.secretKey]: appSecret,
-    };
-    for (const [key, value] of Object.entries(entries)) {
-        content = upsertEnvLine(content, key, value);
-        process.env[key] = value;
-    }
-    fs.writeFileSync(envPath, content);
+    }, projectRoot);
     return keys;
 }