@zhin.js/adapter-qq 6.0.7 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @zhin.js/adapter-qq
 
+## 7.0.0
+
+### Patch Changes
+
+- 7c1e63a: feat(command)!: 命令名前缀分隔符由空格改为点号（BREAKING）
+
+  非 root 插件命令的自动前缀从空格改为点号：`qq endpoint list` → `qq.endpoint list`，多级挂载 `b a foo` → `b.a.foo`；root 插件命令不变。点号前缀同时消除了旧规则下 root 目录段与子插件 owner 段的命名冲突（`child status` vs `child.status` 现在可共存）。配套的 endpoint 管理命令套件（`createEndpointCommands`）及 QQ/ICQQ 适配器的用户可见用法文案同步更新为新风格。迁移：用户与文档中所有 `<adapter> <command>` 形式的指令改为 `<adapter>.<command>`。
+
+- 4fbff5d: feat!: 多模态双向 Segment 一贯制（BREAKING，无兼容层）
+
+  全框架唯一媒体表达统一为 canonical `Segment` + `MediaRef{kind: url|path|base64|file, value, mime_type?, file_name?, size?}`，新增 audio/video/file 段类型；所有第二形状（legacy `data.url/file/base64` 字段、`mediaRefFromLegacyData`/`mediaRefToLegacyFields` 桥、双写）全部删除。
+
+  - **core**：`SendContent` 一等支持 `Segment[]`；endpoint 出站载荷只含 canonical 段；`resolveOutboundMediaPolicy` 改为纯声明驱动（adapter definition `segments.outboundMedia`），内置策略表删除，未声明回退 `url-or-text`；`ImageContent` 旧桥删除。
+  - **ai**：新增 `MediaContentBlock`/`MediaBlockRef`（Segment 同构）与 `UserMessage.media`（当前 turn 媒体，**不持久化**——存储层自动剥离）；`createUserMessage(text, media?)` 签名变更（`ImageContent` 删除）；provider 边界序列化器 `filterMediaBlocksForProvider` + 能力表（缺省 image-only，不支持类型降级占位文本）；ai-sdk 桥媒体块 → SDK image/file parts。
+  - **agent**：入站 turn 注入（`turn/inbound-media.ts`）——commMessage 媒体段 → 当前 turn `UserMessage.media`；图片 path 物化、音频默认 STT（`@zhin.js/speech` 可选，失败降级占位）、视频/文件占位；`publishOutboundElements` 产出 canonical Segment；`transcribeAudioPayload` 导出。
+  - **cli**：`bridgeRuntimeMessage` 回复链路媒体段透传，不再压平为文本（`$reply` 直达 normalize → adapter）。
+  - **全部 20 个平台适配器**：出站媒体只消费 `data.media`（url 直发 / base64 直发 / 平台上传 / 读盘），入站媒体产出 canonical `data.media`；`segments.outboundMedia` 声明与实际消费逐一核对修正；QQ 入站新增 canonical segments（image/audio/video/file/mention/face/reply），图片/语音/视频不再丢失。
+
+  迁移：适配器/插件产媒体一律用 `{ type, data: { media: MediaRef } }`；发送 legacy `data.url/file/base64` 形状的段会被 warn 丢弃。
+
+- Updated dependencies [7c1e63a]
+- Updated dependencies [4fbff5d]
+- Updated dependencies [5b94d9c]
+  - @zhin.js/command@1.0.5
+  - @zhin.js/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - @zhin.js/agent@1.1.0
+  - zhin.js@6.0.0
+
 ## 6.0.7
 
 ### Patch Changes

package/README.md

@@ -71,14 +71,14 @@ plugins:
 
 ## Endpoint 管理命令
 
-适配器自带 `qq endpoint` 命令组（聊天内直接使用，默认无前缀；受 `commandPrefix` 影响）：
+适配器自带 `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` 键保留，可手动清理） |
+| `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）。二维码当前以链接文本下发

package/adapters/qq.js

@@ -20,7 +20,7 @@ export default defineAdapter({
     create(context) {
         const config = resolveQqConfig(context.config);
         const gateway = context.use(messageGatewayToken);
-        // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
         const state = context.use(qqRuntimeStateToken);
         state.endpoints.set(config.name, {
             name: config.name,
@@ -38,7 +38,7 @@ export default defineAdapter({
                 gateway,
                 config,
             });
-        // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 endpoint list 仍显示运行中。
+        // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq.endpoint list 仍显示运行中。
         const stopEndpoint = endpoint.stop.bind(endpoint);
         endpoint.stop = async () => {
             state.endpoints.delete(config.name);

package/adapters/qq.ts

@@ -35,7 +35,7 @@ export default defineAdapter<QqAdapterConfig>({
   create(context) {
     const config = resolveQqConfig(context.config);
     const gateway = context.use(messageGatewayToken);
-    // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
     const state = context.use(qqRuntimeStateToken);
     state.endpoints.set(config.name, {
       name: config.name,
@@ -53,7 +53,7 @@ export default defineAdapter<QqAdapterConfig>({
         gateway,
         config,
       });
-    // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 endpoint list 仍显示运行中。
+    // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq.endpoint list 仍显示运行中。
     const stopEndpoint = endpoint.stop.bind(endpoint);
     endpoint.stop = async () => {
       state.endpoints.delete(config.name);

package/lib/endpoint.js

@@ -132,6 +132,7 @@ export class QqWebsocketEndpoint {
             adapter: this.#options.id,
             target,
             content: formatInboundContent(msg),
+            ...(msg.segments?.length ? { segments: msg.segments } : {}),
             sender: senderDisplayName(msg),
             id: msg.id,
             metadata: Object.freeze({
@@ -311,6 +312,7 @@ export class QqHttpEndpoint {
             adapter: this.#options.id,
             target,
             content: formatInboundContent(msg),
+            ...(msg.segments?.length ? { segments: msg.segments } : {}),
             sender: senderDisplayName(msg),
             id: msg.id,
             metadata: Object.freeze({

package/lib/outbound.d.ts

@@ -5,9 +5,9 @@ export interface QqOutboundElem {
 }
 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。
+ * 解析 image/audio/video/file 段的投递源（canonical MediaRef 唯一来源）：
+ * - kind=url → data.url 直发；
+ * - kind=base64 / path / file → data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
  */
 export declare function resolveMediaFile(data: Record<string, unknown>): string | undefined;
 /**

package/lib/outbound.js

@@ -13,55 +13,48 @@
  * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
  */
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { isMediaRef } from '@zhin.js/core';
 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。
+ * 解析 image/audio/video/file 段的投递源（canonical MediaRef 唯一来源）：
+ * - kind=url → data.url 直发；
+ * - kind=base64 / path / file → data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
  */
 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;
+    const media = data.media;
+    if (!isMediaRef(media))
+        return undefined;
+    if (media.kind === 'url')
+        return undefined;
+    if (media.kind === 'base64') {
+        return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+    }
+    return media.value;
 }
 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 media = (seg.data ?? {}).media;
+    if (!isMediaRef(media)) {
+        // 无 canonical 媒体引用：无法投递，降级留痕
+        logger.warn(formatCompact({
+            op: 'qq_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_media_ref',
+        }));
+        return null;
     }
-    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 } };
+    if (media.kind === 'url') {
+        return { type: seg.type, data: { url: media.value } };
+    }
+    const file = resolveMediaFile(seg.data ?? {});
+    if (!file) {
+        logger.warn(formatCompact({
+            op: 'qq_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_source',
+        }));
+        return null;
     }
-    // 既无远程 URL 也无本地上传源：无法投递，降级留痕
-    logger.warn(formatCompact({
-        op: 'qq_outbound_media_dropped',
-        type: seg.type,
-        reason: 'missing_source',
-    }));
-    return null;
+    return { type: seg.type, data: { file } };
 }
 function normalizeMarkdownSegment(seg) {
     const data = seg.data ?? {};

package/lib/protocol.d.ts

@@ -65,6 +65,8 @@ export interface QqInboundMessage {
     readonly timestamp: number;
     readonly guildId?: string;
     readonly rawMessage?: string;
+    /** canonical 入站段（text/mention/face/image/audio/video/file/reply），与 content 同源 */
+    readonly segments?: readonly import('@zhin.js/core').Segment[];
     /**
      * 入站是否 @ 当前机器人：统一按 mentions 判定。群场景只认 is_you（@ 另一个
      * 机器人时 bot:true 但无 is_you，不误判）；bot 回退仅限频道 AT 事件。

package/lib/qq-endpoint-commands.d.ts

@@ -1,5 +1,5 @@
 /**
- * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * `qq.endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
  * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
  * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
  * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
@@ -19,17 +19,17 @@ export declare const QQ_ENDPOINT_FORBIDDEN: string;
  * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
  */
 export declare function extractQqCommandReply(input: unknown): QqCommandReply;
-/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+/** `qq.endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
 export declare function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string;
 /**
- * `qq endpoint add [name]`：启动扫码绑定流程。
+ * `qq.endpoint add [name]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
  */
 export declare function runQqEndpointAdd(state: QqRuntimeState, name: string | undefined, reply: QqCommandReply, projectRoot?: string): Promise<string>;
-/** `qq endpoint cancel`：中止进行中的绑定流程 */
+/** `qq.endpoint cancel`：中止进行中的绑定流程 */
 export declare function runQqEndpointCancel(state: QqRuntimeState): string;
-/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+/** `qq.endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
 export declare function runQqEndpointRemove(_state: QqRuntimeState, name: string, projectRoot?: string): string;
 /**
  * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。

package/lib/qq-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * `qq.endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
  * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
  * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
  * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
@@ -26,12 +26,12 @@ export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
 export function extractQqCommandReply(input) {
     return extractEndpointCommandReply(input);
 }
-/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+/** `qq.endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
 export function runQqEndpointList(state, projectRoot) {
     return formatEndpointList(qqEndpointListSpec, {
         running: state.endpoints.values(),
         configured: listQqEndpointEntries(projectRoot),
-        footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined,
+        footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined,
     });
 }
 const qqEndpointListSpec = {
@@ -40,13 +40,13 @@ const qqEndpointListSpec = {
     describeEntry: (entry) => `appid: ${String(entry.appid)}`,
 };
 /**
- * `qq endpoint add [name]`：启动扫码绑定流程。
+ * `qq.endpoint add [name]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
  */
 export function runQqEndpointAdd(state, name, reply, projectRoot) {
     if (state.bindFlow) {
-        return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+        return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq.endpoint cancel 取消后再试');
     }
     const endpointName = name?.trim() || undefined;
     return new Promise((resolve) => {
@@ -89,7 +89,7 @@ export function runQqEndpointAdd(state, name, reply, projectRoot) {
         state.bindFlow = { name: endpointName, stop };
     });
 }
-/** `qq endpoint cancel`：中止进行中的绑定流程 */
+/** `qq.endpoint cancel`：中止进行中的绑定流程 */
 export function runQqEndpointCancel(state) {
     if (!state.bindFlow) {
         return '当前没有进行中的 QQ 绑定流程';
@@ -98,7 +98,7 @@ export function runQqEndpointCancel(state) {
     state.bindFlow = null;
     return '已取消进行中的 QQ 绑定流程';
 }
-/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+/** `qq.endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
 export function runQqEndpointRemove(_state, name, projectRoot) {
     return removeEndpointByName(qqEndpointListSpec, name, projectRoot);
 }
@@ -115,7 +115,7 @@ export const qqEndpointCommands = createEndpointCommands({
     running: (use) => use(qqRuntimeStateToken).endpoints.values(),
     listFooter: (use) => {
         const state = use(qqRuntimeStateToken);
-        return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined;
+        return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined;
     },
     addDescription: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
     bindFlow: ({ name, reply, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), name, reply),

package/lib/ws.js

@@ -61,6 +61,7 @@ export function normalizeQqMessage(raw) {
         ?? msg.author?.id
         ?? '');
     const content = extractTextContent(msg.message) || msg.raw_message || '';
+    const segments = extractCanonicalSegments(msg.message);
     const rawRoles = msg.member?.roles ?? msg.sender?.roles;
     const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
     // 统一按 mentions 判定 @：is_you 精确标识当前机器人（群载荷实测字段）。
@@ -80,9 +81,92 @@ export function normalizeQqMessage(raw) {
         timestamp: Date.now(),
         guildId: msg.guild_id != null ? String(msg.guild_id) : undefined,
         rawMessage: msg.raw_message,
+        ...(segments.length > 0 ? { segments } : {}),
         ...(mentioned ? { mentioned: true } : {}),
     };
 }
+/**
+ * SDK 解析后的消息段（text/at/face/image/video/audio/file/reply）→ canonical Segment[]。
+ * 附件段的 url 已由 SDK 归一（补 https:// 前缀）；mime 无法从载荷得知时按类型给默认。
+ */
+function extractCanonicalSegments(message) {
+    if (!Array.isArray(message))
+        return [];
+    const out = [];
+    for (const seg of message) {
+        if (!seg || typeof seg !== 'object')
+            continue;
+        const item = seg;
+        const type = item.type ?? '';
+        const data = item.data ?? {};
+        switch (type) {
+            case 'text': {
+                const text = String(data.text ?? '');
+                if (text)
+                    out.push({ type: 'text', data: { text } });
+                break;
+            }
+            case 'at': {
+                const target = String(data.user_id ?? data.id ?? '');
+                if (!target)
+                    break;
+                const name = typeof data.username === 'string' && data.username
+                    ? data.username
+                    : undefined;
+                out.push({ type: 'mention', data: name ? { target, name } : { target } });
+                break;
+            }
+            case 'face': {
+                const id = data.id;
+                if (id == null)
+                    break;
+                out.push({ type: 'face', data: { id: id } });
+                break;
+            }
+            case 'image':
+            case 'video':
+            case 'audio':
+            case 'file': {
+                const url = typeof data.url === 'string' ? data.url : '';
+                if (!url)
+                    break;
+                const media = {
+                    kind: 'url',
+                    value: url,
+                    mime_type: defaultMimeForSegment(type),
+                    ...(typeof data.name === 'string' && data.name ? { file_name: data.name } : {}),
+                    ...(typeof data.size === 'number' ? { size: data.size } : {}),
+                };
+                if (type === 'image')
+                    out.push({ type: 'image', data: { media } });
+                else if (type === 'video')
+                    out.push({ type: 'video', data: { media } });
+                else if (type === 'audio')
+                    out.push({ type: 'audio', data: { media } });
+                else
+                    out.push({ type: 'file', data: { media, ...(media.file_name ? { name: media.file_name } : {}) } });
+                break;
+            }
+            case 'reply': {
+                const messageId = String(data.id ?? data.message_id ?? '');
+                if (messageId)
+                    out.push({ type: 'reply', data: { message_id: messageId } });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function defaultMimeForSegment(type) {
+    switch (type) {
+        case 'image': return 'image/jpeg';
+        case 'video': return 'video/mp4';
+        case 'audio': return 'audio/mpeg';
+        default: return undefined;
+    }
+}
 function extractTextContent(message) {
     if (typeof message === 'string')
         return message;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "6.0.7",
+  "version": "7.0.0",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,20 +35,20 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
+    "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent": "1.0.10",
-    "@zhin.js/core": "1.4.3",
-    "zhin.js": "5.0.3",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
+    "@zhin.js/core": "1.5.0",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,9 +66,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
+    "@zhin.js/agent": "1.1.0",
     "@zhin.js/host-http": "1.0.4",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -8,7 +8,7 @@ export default definePlugin({
         displayName: 'QQ Official WebSocket Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表 + 扫码绑定单例，供 adapter create 与 `qq endpoint` 命令共享
+        // 运行中 endpoint 注册表 + 扫码绑定单例，供 adapter create 与 `qq.endpoint` 命令共享
         context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
         // 平台权限门禁：guild_owner / guild_admin / manage_roles / manage_channels（agent 工具 platformPermit）
         return registerQqPlatformPermitChecker();

package/src/endpoint.ts

@@ -183,6 +183,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target,
       content: formatInboundContent(msg),
+      ...(msg.segments?.length ? { segments: msg.segments } : {}),
       sender: senderDisplayName(msg),
       id: msg.id,
       metadata: Object.freeze({
@@ -387,6 +388,7 @@ export class QqHttpEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target,
       content: formatInboundContent(msg),
+      ...(msg.segments?.length ? { segments: msg.segments } : {}),
       sender: senderDisplayName(msg),
       id: msg.id,
       metadata: Object.freeze({

package/src/outbound.ts

@@ -13,6 +13,7 @@
  * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
  */
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { isMediaRef } from '@zhin.js/core';
 import type { QqWireSegment } from './protocol.js';
 
 const logger = getLogger('qq');
@@ -34,54 +35,45 @@ interface QqOutboundButtonSpec {
   readonly command?: { readonly enter?: boolean; readonly reply?: boolean };
 }
 
-function isRemoteUrl(value: string): boolean {
-  return /^https?:\/\//i.test(value);
-}
-
-function isInlineBase64(value: string): boolean {
-  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。
+ * 解析 image/audio/video/file 段的投递源（canonical MediaRef 唯一来源）：
+ * - kind=url → data.url 直发；
+ * - kind=base64 / path / file → data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
  */
 export function resolveMediaFile(data: Record<string, unknown>): string | undefined {
-  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;
+  const media = data.media;
+  if (!isMediaRef(media)) return undefined;
+  if (media.kind === 'url') return undefined;
+  if (media.kind === 'base64') {
+    return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+  }
+  return media.value;
 }
 
 function normalizeMediaSegment(seg: QqWireSegment): QqOutboundElem | null {
-  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 media = (seg.data ?? {}).media;
+  if (!isMediaRef(media)) {
+    // 无 canonical 媒体引用：无法投递，降级留痕
+    logger.warn(formatCompact({
+      op: 'qq_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
   }
-  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 } };
+  if (media.kind === 'url') {
+    return { type: seg.type, data: { url: media.value } };
+  }
+  const file = resolveMediaFile(seg.data ?? {});
+  if (!file) {
+    logger.warn(formatCompact({
+      op: 'qq_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_source',
+    }));
+    return null;
   }
-  // 既无远程 URL 也无本地上传源：无法投递，降级留痕
-  logger.warn(formatCompact({
-    op: 'qq_outbound_media_dropped',
-    type: seg.type,
-    reason: 'missing_source',
-  }));
-  return null;
+  return { type: seg.type, data: { file } };
 }
 
 function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {

package/src/protocol.ts

@@ -76,6 +76,8 @@ export interface QqInboundMessage {
   readonly timestamp: number;
   readonly guildId?: string;
   readonly rawMessage?: string;
+  /** canonical 入站段（text/mention/face/image/audio/video/file/reply），与 content 同源 */
+  readonly segments?: readonly import('@zhin.js/core').Segment[];
   /**
    * 入站是否 @ 当前机器人：统一按 mentions 判定。群场景只认 is_you（@ 另一个
    * 机器人时 bot:true 但无 is_you，不误判）；bot 回退仅限频道 AT 事件。

package/src/qq-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * `qq.endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
  * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
  * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
  * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
@@ -41,12 +41,12 @@ export function extractQqCommandReply(input: unknown): QqCommandReply {
   return extractEndpointCommandReply(input);
 }
 
-/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+/** `qq.endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
 export function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string {
   return formatEndpointList(qqEndpointListSpec, {
     running: state.endpoints.values(),
     configured: listQqEndpointEntries(projectRoot),
-    footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined,
+    footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined,
   });
 }
 
@@ -57,7 +57,7 @@ const qqEndpointListSpec = {
 } as const;
 
 /**
- * `qq endpoint add [name]`：启动扫码绑定流程。
+ * `qq.endpoint add [name]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
  */
@@ -68,7 +68,7 @@ export function runQqEndpointAdd(
   projectRoot?: string,
 ): Promise<string> {
   if (state.bindFlow) {
-    return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+    return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq.endpoint cancel 取消后再试');
   }
   const endpointName = name?.trim() || undefined;
   return new Promise<string>((resolve) => {
@@ -121,7 +121,7 @@ export function runQqEndpointAdd(
   });
 }
 
-/** `qq endpoint cancel`：中止进行中的绑定流程 */
+/** `qq.endpoint cancel`：中止进行中的绑定流程 */
 export function runQqEndpointCancel(state: QqRuntimeState): string {
   if (!state.bindFlow) {
     return '当前没有进行中的 QQ 绑定流程';
@@ -131,7 +131,7 @@ export function runQqEndpointCancel(state: QqRuntimeState): string {
   return '已取消进行中的 QQ 绑定流程';
 }
 
-/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+/** `qq.endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
 export function runQqEndpointRemove(
   _state: QqRuntimeState,
   name: string,
@@ -153,7 +153,7 @@ export const qqEndpointCommands = createEndpointCommands({
   running: (use) => use(qqRuntimeStateToken).endpoints.values(),
   listFooter: (use) => {
     const state = use(qqRuntimeStateToken);
-    return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined;
+    return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消' : undefined;
   },
   addDescription: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
   bindFlow: ({ name, reply, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), name, reply),

package/src/ws.ts

@@ -4,6 +4,7 @@
 import path from 'node:path';
 import { Bot, ReceiverMode, type Sendable } from 'qq-official-bot';
 import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
+import type { MediaRef, Segment } from '@zhin.js/core';
 import type { QqOutboundMessage } from './outbound.js';
 import type { QqChannelKind, QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 
@@ -130,6 +131,7 @@ export function normalizeQqMessage(raw: unknown): QqInboundMessage | null {
     ?? '',
   );
   const content = extractTextContent(msg.message) || msg.raw_message || '';
+  const segments = extractCanonicalSegments(msg.message);
   const rawRoles = msg.member?.roles ?? msg.sender?.roles;
   const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
   // 统一按 mentions 判定 @：is_you 精确标识当前机器人（群载荷实测字段）。
@@ -150,10 +152,84 @@ export function normalizeQqMessage(raw: unknown): QqInboundMessage | null {
     timestamp: Date.now(),
     guildId: msg.guild_id != null ? String(msg.guild_id) : undefined,
     rawMessage: msg.raw_message,
+    ...(segments.length > 0 ? { segments } : {}),
     ...(mentioned ? { mentioned: true } : {}),
   };
 }
 
+/**
+ * SDK 解析后的消息段（text/at/face/image/video/audio/file/reply）→ canonical Segment[]。
+ * 附件段的 url 已由 SDK 归一（补 https:// 前缀）；mime 无法从载荷得知时按类型给默认。
+ */
+function extractCanonicalSegments(message: unknown): Segment[] {
+  if (!Array.isArray(message)) return [];
+  const out: Segment[] = [];
+  for (const seg of message) {
+    if (!seg || typeof seg !== 'object') continue;
+    const item = seg as { type?: string; data?: Record<string, unknown> };
+    const type = item.type ?? '';
+    const data = item.data ?? {};
+    switch (type) {
+      case 'text': {
+        const text = String(data.text ?? '');
+        if (text) out.push({ type: 'text', data: { text } });
+        break;
+      }
+      case 'at': {
+        const target = String(data.user_id ?? data.id ?? '');
+        if (!target) break;
+        const name = typeof data.username === 'string' && data.username
+          ? data.username
+          : undefined;
+        out.push({ type: 'mention', data: name ? { target, name } : { target } });
+        break;
+      }
+      case 'face': {
+        const id = data.id;
+        if (id == null) break;
+        out.push({ type: 'face', data: { id: id as string | number } });
+        break;
+      }
+      case 'image':
+      case 'video':
+      case 'audio':
+      case 'file': {
+        const url = typeof data.url === 'string' ? data.url : '';
+        if (!url) break;
+        const media: MediaRef = {
+          kind: 'url',
+          value: url,
+          mime_type: defaultMimeForSegment(type),
+          ...(typeof data.name === 'string' && data.name ? { file_name: data.name } : {}),
+          ...(typeof data.size === 'number' ? { size: data.size } : {}),
+        };
+        if (type === 'image') out.push({ type: 'image', data: { media } });
+        else if (type === 'video') out.push({ type: 'video', data: { media } });
+        else if (type === 'audio') out.push({ type: 'audio', data: { media } });
+        else out.push({ type: 'file', data: { media, ...(media.file_name ? { name: media.file_name } : {}) } });
+        break;
+      }
+      case 'reply': {
+        const messageId = String(data.id ?? data.message_id ?? '');
+        if (messageId) out.push({ type: 'reply', data: { message_id: messageId } });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+function defaultMimeForSegment(type: string): string | undefined {
+  switch (type) {
+    case 'image': return 'image/jpeg';
+    case 'video': return 'video/mp4';
+    case 'audio': return 'audio/mpeg';
+    default: return undefined;
+  }
+}
+
 function extractTextContent(message: unknown): string {
   if (typeof message === 'string') return message;
   if (!Array.isArray(message)) return '';