@zhin.js/adapter-weixin-ilink 4.0.3 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @zhin.js/adapter-weixin-ilink
 
+## 5.0.1
+
+### Patch Changes
+
+- Updated dependencies [c8f4d45]
+  - @zhin.js/plugin-runtime@1.1.2
+  - @zhin.js/adapter@1.1.4
+  - @zhin.js/command@1.0.6
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
+## 5.0.0
+
+### Patch Changes
+
+- 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@6.0.0
+
 ## 4.0.3
 
 ### Patch Changes

package/adapters/weixin-ilink.js

@@ -10,14 +10,15 @@ import { weixinIlinkRuntimeStateToken } from "../lib/weixin-ilink-runtime-state.
 export { WeixinIlinkEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // base64 / 远程 URL 落盘后走 CDN 上传（sendWeixinMediaFile）；微信无卡片交互面，交互段降级纯文本。
+    // 所有媒体（url 下载 / base64 落盘 / 本地 path）统一物化后走 CDN 上传（sendWeixinMediaFile），
+    // 无直发面；微信无卡片交互面，交互段降级纯文本。
     segments: {
-        outboundMedia: ['base64', 'url', 'upload'],
+        outboundMedia: ['upload'],
         interactive: 'text',
     },
     create(context) {
         const config = resolveWeixinIlinkConfig(context.config);
-        // 注册到插件运行时状态（weixin-ilink endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（weixin-ilink.endpoint list 的"运行中"数据源）
         context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.connection,

package/adapters/weixin-ilink.ts

@@ -21,14 +21,15 @@ export type {
 
 export default defineAdapter<WeixinIlinkAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // base64 / 远程 URL 落盘后走 CDN 上传（sendWeixinMediaFile）；微信无卡片交互面，交互段降级纯文本。
+  // 所有媒体（url 下载 / base64 落盘 / 本地 path）统一物化后走 CDN 上传（sendWeixinMediaFile），
+  // 无直发面；微信无卡片交互面，交互段降级纯文本。
   segments: {
-    outboundMedia: ['base64', 'url', 'upload'],
+    outboundMedia: ['upload'],
     interactive: 'text',
   },
   create(context) {
     const config = resolveWeixinIlinkConfig(context.config);
-    // 注册到插件运行时状态（weixin-ilink endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（weixin-ilink.endpoint list 的"运行中"数据源）
     context.use(weixinIlinkRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: config.connection,

package/lib/outbound-media.d.ts

@@ -1,5 +1,4 @@
 import type { WeixinWireSegment } from './protocol.js';
 export type OutboundWireContent = string | WeixinWireSegment | ReadonlyArray<string | WeixinWireSegment>;
-export declare function segmentMediaRef(seg: WeixinWireSegment): string | undefined;
-/** 将 base64 / 远程图落盘，供 sendWeixinMediaFile 上传 */
+/** 将 canonical MediaRef 媒体段物化为本地文件（kind=path），供 sendWeixinMediaFile 上传 */
 export declare function materializeOutboundMedia(content: OutboundWireContent, outboundDir: string): Promise<OutboundWireContent>;

package/lib/outbound-media.js

@@ -1,59 +1,37 @@
 /**
- * 微信 iLink 出站媒体：base64 / 远程 URL 须落盘后再走 CDN 上传。
+ * 微信 iLink 出站媒体物化：canonical MediaRef（`data.media`，MediaRef-only）→ 本地文件，
+ * 再由 sendWeixinMediaFile 走 CDN 上传。
+ * - kind=url    → 下载落盘后上传；
+ * - kind=base64 → 解码落盘后上传；
+ * - kind=path   → 本地文件直接上传；
+ * - kind=file   → 微信无不透明平台引用投递面，warn 丢弃。
+ * 无 media 或物化失败的媒体段 warn 丢弃（weixin_ilink_outbound_media_dropped）。
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
 import { downloadRemoteImageToTemp } from './upload.js';
 import { getExtensionFromMime } from './mime.js';
+const logger = getLogger('weixin-ilink');
 const MEDIA_TYPES = new Set(['image', 'video', 'file', 'record', 'audio']);
-function isRemoteUrl(value) {
-    return /^https?:\/\//i.test(value);
+function dropMediaSegment(type, reason) {
+    logger.warn(formatCompact({
+        op: 'weixin_ilink_outbound_media_dropped',
+        type,
+        reason,
+    }));
+    return null;
 }
-function isInlineMediaRef(value) {
-    return value.startsWith('base64://') || /^data:[^/]+\/[^;]+;base64,/i.test(value);
-}
-function normalizeLocalPath(value) {
-    return value.replace(/^file:\/\//, '');
-}
-export function segmentMediaRef(seg) {
-    const data = seg.data;
-    if (!data)
-        return undefined;
-    const candidates = [data.file, data.path, data.url].filter((v) => typeof v === 'string' && Boolean(v));
-    return candidates[0];
-}
-function extractBase64Buffer(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 (url?.startsWith('base64://')) {
-        return Buffer.from(url.slice(9), 'base64');
-    }
-    if (url && /^data:[^/]+\/[^;]+;base64,/i.test(url)) {
-        return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ''), 'base64');
-    }
-    if (file?.startsWith('base64://')) {
-        return Buffer.from(file.slice(9), 'base64');
-    }
-    if (base64) {
-        const raw = base64.startsWith('base64://') ? base64.slice(9) : base64;
-        return Buffer.from(raw, 'base64');
-    }
-    return undefined;
-}
-function resolveExt(seg, mime) {
-    const data = (seg.data ?? {});
-    const name = typeof data.name === 'string' ? data.name : undefined;
-    if (name) {
-        const ext = path.extname(name);
+function resolveExt(seg, media) {
+    if (media.file_name) {
+        const ext = path.extname(media.file_name);
         if (ext)
             return ext;
     }
-    const mimeHint = mime
-        ?? (typeof data.mime === 'string' ? data.mime : typeof data.mimeType === 'string' ? data.mimeType : undefined);
-    if (mimeHint) {
-        return getExtensionFromMime(mimeHint) ?? '.bin';
+    if (media.mime_type) {
+        return getExtensionFromMime(media.mime_type) ?? '.bin';
     }
     if (seg.type === 'image')
         return '.png';
@@ -63,14 +41,15 @@ function resolveExt(seg, mime) {
         return '.mp3';
     return '.bin';
 }
-function withLocalFile(seg, filePath) {
-    const data = { ...(seg.data ?? {}), file: filePath };
-    delete data.base64;
-    return { type: seg.type, data };
+function withLocalPath(seg, media, filePath) {
+    return {
+        type: seg.type,
+        data: { ...(seg.data ?? {}), media: { ...media, kind: 'path', value: filePath } },
+    };
 }
-function writeOutboundBuffer(buffer, outboundDir, seg) {
+function writeOutboundBuffer(buffer, outboundDir, seg, media) {
     fs.mkdirSync(outboundDir, { recursive: true });
-    const ext = resolveExt(seg);
+    const ext = resolveExt(seg, media);
     const filePath = path.join(outboundDir, `out-${seg.type}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}${ext}`);
     fs.writeFileSync(filePath, buffer);
     return filePath;
@@ -78,22 +57,38 @@ function writeOutboundBuffer(buffer, outboundDir, seg) {
 async function materializeSegment(seg, outboundDir) {
     if (!MEDIA_TYPES.has(seg.type))
         return seg;
-    const ref = segmentMediaRef(seg);
-    if (ref && !isInlineMediaRef(ref)) {
-        const local = normalizeLocalPath(ref);
-        if (isRemoteUrl(local)) {
-            const downloaded = await downloadRemoteImageToTemp(local, outboundDir);
-            return withLocalFile(seg, downloaded);
+    const media = (seg.data ?? {}).media;
+    if (!isMediaRef(media)) {
+        return dropMediaSegment(seg.type, 'missing_media_ref');
+    }
+    switch (media.kind) {
+        case 'url': {
+            try {
+                const downloaded = await downloadRemoteImageToTemp(media.value, outboundDir);
+                return withLocalPath(seg, media, downloaded);
+            }
+            catch (err) {
+                logger.warn(formatCompact({
+                    op: 'weixin_ilink_outbound_media_dropped',
+                    type: seg.type,
+                    reason: 'download_failed',
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+                return null;
+            }
         }
-        if (fs.existsSync(local)) {
-            return withLocalFile(seg, local);
+        case 'base64':
+            return withLocalPath(seg, media, writeOutboundBuffer(Buffer.from(media.value, 'base64'), outboundDir, seg, media));
+        case 'path': {
+            if (!fs.existsSync(media.value)) {
+                return dropMediaSegment(seg.type, 'missing_source');
+            }
+            return withLocalPath(seg, media, media.value);
         }
+        case 'file':
+            // 平台不透明引用（如 Telegram file_id）：微信 iLink 无对应投递面
+            return dropMediaSegment(seg.type, 'unsupported_media_kind');
     }
-    const buffer = extractBase64Buffer((seg.data ?? {}));
-    if (buffer) {
-        return withLocalFile(seg, writeOutboundBuffer(buffer, outboundDir, seg));
-    }
-    return seg;
 }
 function asSegments(content) {
     if (typeof content === 'string') {
@@ -110,15 +105,17 @@ function asSegments(content) {
         return typeof item === 'object' && item !== null && 'type' in item ? [item] : [];
     });
 }
-/** 将 base64 / 远程图落盘，供 sendWeixinMediaFile 上传 */
+/** 将 canonical MediaRef 媒体段物化为本地文件（kind=path），供 sendWeixinMediaFile 上传 */
 export async function materializeOutboundMedia(content, outboundDir) {
     const segments = asSegments(content);
-    const out = await Promise.all(segments.map((seg) => materializeSegment(seg, outboundDir)));
+    const out = (await Promise.all(segments.map((seg) => materializeSegment(seg, outboundDir))))
+        .filter((seg) => seg !== null);
     if (typeof content === 'string') {
         return out[0]?.type === 'text' ? String(out[0].data?.text ?? content) : content;
     }
     if (!Array.isArray(content)) {
-        return out[0] ?? content;
+        // 单个媒体段被丢弃时降级为空文本，避免未物化段漏到 endpoint
+        return out[0] ?? { type: 'text', data: { text: '' } };
     }
     return out;
 }

package/lib/protocol.d.ts

@@ -48,5 +48,6 @@ export declare function inboundMessageId(msg: WeixinMessage): string;
  * Segment canonicalization is intentionally not done here.
  */
 export declare function formatOutboundSegments(payload: unknown): WeixinWireSegment[];
+/** 物化后的媒体段（data.media kind=path）→ 本地文件路径；其余返回 undefined。 */
 export declare function segmentLocalPath(seg: WeixinWireSegment): string | undefined;
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/lib/protocol.js

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
 import { bodyFromItemList, isMediaItem } from './weixin-inbound.js';
 import { DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL } from './ilink-meta.js';
 const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
@@ -85,14 +86,12 @@ export function formatOutboundSegments(payload) {
     }
     return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }
+/** 物化后的媒体段（data.media kind=path）→ 本地文件路径；其余返回 undefined。 */
 export function segmentLocalPath(seg) {
-    const data = seg.data ?? {};
-    const candidates = [data.file, data.path, data.url].filter((value) => typeof value === 'string' && Boolean(value));
-    const ref = candidates[0];
-    if (!ref || ref.startsWith('base64://') || /^data:/.test(ref) || /^https?:\/\//i.test(ref)) {
+    const media = (seg.data ?? {}).media;
+    if (!isMediaRef(media) || media.kind !== 'path')
         return undefined;
-    }
-    return ref.replace(/^file:\/\//, '');
+    return media.value;
 }
 export function sleep(ms, signal) {
     return new Promise((resolve) => {

package/lib/weixin-ilink-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `weixin-ilink endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `weixin-ilink.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/lib/weixin-ilink-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * Weixin iLink 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `weixin-ilink endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `weixin-ilink.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 export const weixinIlinkRuntimeStateToken = defineEndpointRuntimeStateToken('weixin-ilink');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-weixin-ilink",
-  "version": "4.0.3",
+  "version": "5.0.1",
   "type": "module",
   "description": "Zhin.js Weixin iLink (ClawBot) adapter for Plugin Runtime (long-poll)",
   "main": "./lib/index.js",
@@ -48,17 +48,17 @@
     }
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/command": "1.0.6",
+    "@zhin.js/core": "1.5.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/plugin-runtime": "1.1.2"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/core": "1.5.1",
+    "@zhin.js/plugin-runtime": "1.1.2",
+    "zhin.js": "6.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,7 +66,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },

package/plugin.js

@@ -8,7 +8,7 @@ export default definePlugin({
         displayName: 'Weixin iLink Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（weixin-ilink endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（weixin-ilink.endpoint list 的"运行中"数据源）
         context.resources.provide(weixinIlinkRuntimeStateToken, createEndpointRuntimeState());
     },
 });

package/src/outbound-media.ts

@@ -1,70 +1,43 @@
 /**
- * 微信 iLink 出站媒体：base64 / 远程 URL 须落盘后再走 CDN 上传。
+ * 微信 iLink 出站媒体物化：canonical MediaRef（`data.media`，MediaRef-only）→ 本地文件，
+ * 再由 sendWeixinMediaFile 走 CDN 上传。
+ * - kind=url    → 下载落盘后上传；
+ * - kind=base64 → 解码落盘后上传；
+ * - kind=path   → 本地文件直接上传；
+ * - kind=file   → 微信无不透明平台引用投递面，warn 丢弃。
+ * 无 media 或物化失败的媒体段 warn 丢弃（weixin_ilink_outbound_media_dropped）。
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { isMediaRef, type MediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
 import { downloadRemoteImageToTemp } from './upload.js';
 import { getExtensionFromMime } from './mime.js';
 import type { WeixinWireSegment } from './protocol.js';
 
+const logger = getLogger('weixin-ilink');
+
 const MEDIA_TYPES = new Set(['image', 'video', 'file', 'record', 'audio']);
 
 export type OutboundWireContent = string | WeixinWireSegment | ReadonlyArray<string | WeixinWireSegment>;
 
-function isRemoteUrl(value: string): boolean {
-  return /^https?:\/\//i.test(value);
-}
-
-function isInlineMediaRef(value: string): boolean {
-  return value.startsWith('base64://') || /^data:[^/]+\/[^;]+;base64,/i.test(value);
-}
-
-function normalizeLocalPath(value: string): string {
-  return value.replace(/^file:\/\//, '');
-}
-
-export function segmentMediaRef(seg: WeixinWireSegment): string | undefined {
-  const data = seg.data as Record<string, unknown> | undefined;
-  if (!data) return undefined;
-  const candidates = [data.file, data.path, data.url].filter(
-    (v): v is string => typeof v === 'string' && Boolean(v),
-  );
-  return candidates[0];
-}
-
-function extractBase64Buffer(data: Record<string, unknown>): Buffer | 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 (url?.startsWith('base64://')) {
-    return Buffer.from(url.slice(9), 'base64');
-  }
-  if (url && /^data:[^/]+\/[^;]+;base64,/i.test(url)) {
-    return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ''), 'base64');
-  }
-  if (file?.startsWith('base64://')) {
-    return Buffer.from(file.slice(9), 'base64');
-  }
-  if (base64) {
-    const raw = base64.startsWith('base64://') ? base64.slice(9) : base64;
-    return Buffer.from(raw, 'base64');
-  }
-  return undefined;
+function dropMediaSegment(type: string, reason: string): null {
+  logger.warn(formatCompact({
+    op: 'weixin_ilink_outbound_media_dropped',
+    type,
+    reason,
+  }));
+  return null;
 }
 
-function resolveExt(seg: WeixinWireSegment, mime?: string): string {
-  const data = (seg.data ?? {}) as Record<string, unknown>;
-  const name = typeof data.name === 'string' ? data.name : undefined;
-  if (name) {
-    const ext = path.extname(name);
+function resolveExt(seg: WeixinWireSegment, media: MediaRef): string {
+  if (media.file_name) {
+    const ext = path.extname(media.file_name);
     if (ext) return ext;
   }
-  const mimeHint = mime
-    ?? (typeof data.mime === 'string' ? data.mime : typeof data.mimeType === 'string' ? data.mimeType : undefined);
-  if (mimeHint) {
-    return getExtensionFromMime(mimeHint) ?? '.bin';
+  if (media.mime_type) {
+    return getExtensionFromMime(media.mime_type) ?? '.bin';
   }
   if (seg.type === 'image') return '.png';
   if (seg.type === 'video') return '.mp4';
@@ -72,15 +45,16 @@ function resolveExt(seg: WeixinWireSegment, mime?: string): string {
   return '.bin';
 }
 
-function withLocalFile(seg: WeixinWireSegment, filePath: string): WeixinWireSegment {
-  const data = { ...(seg.data ?? {}), file: filePath } as Record<string, unknown>;
-  delete data.base64;
-  return { type: seg.type, data };
+function withLocalPath(seg: WeixinWireSegment, media: MediaRef, filePath: string): WeixinWireSegment {
+  return {
+    type: seg.type,
+    data: { ...(seg.data ?? {}), media: { ...media, kind: 'path', value: filePath } },
+  };
 }
 
-function writeOutboundBuffer(buffer: Buffer, outboundDir: string, seg: WeixinWireSegment): string {
+function writeOutboundBuffer(buffer: Buffer, outboundDir: string, seg: WeixinWireSegment, media: MediaRef): string {
   fs.mkdirSync(outboundDir, { recursive: true });
-  const ext = resolveExt(seg);
+  const ext = resolveExt(seg, media);
   const filePath = path.join(
     outboundDir,
     `out-${seg.type}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}${ext}`,
@@ -92,27 +66,45 @@ function writeOutboundBuffer(buffer: Buffer, outboundDir: string, seg: WeixinWir
 async function materializeSegment(
   seg: WeixinWireSegment,
   outboundDir: string,
-): Promise<WeixinWireSegment> {
+): Promise<WeixinWireSegment | null> {
   if (!MEDIA_TYPES.has(seg.type)) return seg;
 
-  const ref = segmentMediaRef(seg);
-  if (ref && !isInlineMediaRef(ref)) {
-    const local = normalizeLocalPath(ref);
-    if (isRemoteUrl(local)) {
-      const downloaded = await downloadRemoteImageToTemp(local, outboundDir);
-      return withLocalFile(seg, downloaded);
-    }
-    if (fs.existsSync(local)) {
-      return withLocalFile(seg, local);
-    }
+  const media = (seg.data ?? {}).media;
+  if (!isMediaRef(media)) {
+    return dropMediaSegment(seg.type, 'missing_media_ref');
   }
 
-  const buffer = extractBase64Buffer((seg.data ?? {}) as Record<string, unknown>);
-  if (buffer) {
-    return withLocalFile(seg, writeOutboundBuffer(buffer, outboundDir, seg));
+  switch (media.kind) {
+    case 'url': {
+      try {
+        const downloaded = await downloadRemoteImageToTemp(media.value, outboundDir);
+        return withLocalPath(seg, media, downloaded);
+      } catch (err) {
+        logger.warn(formatCompact({
+          op: 'weixin_ilink_outbound_media_dropped',
+          type: seg.type,
+          reason: 'download_failed',
+          error: err instanceof Error ? err.message : String(err),
+        }));
+        return null;
+      }
+    }
+    case 'base64':
+      return withLocalPath(
+        seg,
+        media,
+        writeOutboundBuffer(Buffer.from(media.value, 'base64'), outboundDir, seg, media),
+      );
+    case 'path': {
+      if (!fs.existsSync(media.value)) {
+        return dropMediaSegment(seg.type, 'missing_source');
+      }
+      return withLocalPath(seg, media, media.value);
+    }
+    case 'file':
+      // 平台不透明引用（如 Telegram file_id）：微信 iLink 无对应投递面
+      return dropMediaSegment(seg.type, 'unsupported_media_kind');
   }
-
-  return seg;
 }
 
 function asSegments(content: OutboundWireContent): WeixinWireSegment[] {
@@ -130,18 +122,20 @@ function asSegments(content: OutboundWireContent): WeixinWireSegment[] {
   });
 }
 
-/** 将 base64 / 远程图落盘，供 sendWeixinMediaFile 上传 */
+/** 将 canonical MediaRef 媒体段物化为本地文件（kind=path），供 sendWeixinMediaFile 上传 */
 export async function materializeOutboundMedia(
   content: OutboundWireContent,
   outboundDir: string,
 ): Promise<OutboundWireContent> {
   const segments = asSegments(content);
-  const out = await Promise.all(segments.map((seg) => materializeSegment(seg, outboundDir)));
+  const out = (await Promise.all(segments.map((seg) => materializeSegment(seg, outboundDir))))
+    .filter((seg): seg is WeixinWireSegment => seg !== null);
   if (typeof content === 'string') {
     return out[0]?.type === 'text' ? String((out[0].data as { text?: string })?.text ?? content) : content;
   }
   if (!Array.isArray(content)) {
-    return out[0] ?? content;
+    // 单个媒体段被丢弃时降级为空文本，避免未物化段漏到 endpoint
+    return out[0] ?? { type: 'text', data: { text: '' } };
   }
   return out;
 }

package/src/protocol.ts

@@ -4,6 +4,7 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
 import { bodyFromItemList, isMediaItem } from './weixin-inbound.js';
 import { DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL } from './ilink-meta.js';
 import type { WeixinMessage } from './ilink-types.js';
@@ -141,16 +142,11 @@ export function formatOutboundSegments(payload: unknown): WeixinWireSegment[] {
   return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }
 
+/** 物化后的媒体段（data.media kind=path）→ 本地文件路径；其余返回 undefined。 */
 export function segmentLocalPath(seg: WeixinWireSegment): string | undefined {
-  const data = seg.data ?? {};
-  const candidates = [data.file, data.path, data.url].filter(
-    (value): value is string => typeof value === 'string' && Boolean(value),
-  );
-  const ref = candidates[0];
-  if (!ref || ref.startsWith('base64://') || /^data:/.test(ref) || /^https?:\/\//i.test(ref)) {
-    return undefined;
-  }
-  return ref.replace(/^file:\/\//, '');
+  const media = (seg.data ?? {}).media;
+  if (!isMediaRef(media) || media.kind !== 'path') return undefined;
+  return media.value;
 }
 
 export function sleep(ms: number, signal?: AbortSignal): Promise<void> {

package/src/weixin-ilink-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `weixin-ilink endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `weixin-ilink.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/src/weixin-ilink-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * Weixin iLink 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `weixin-ilink endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `weixin-ilink.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';