@zhin.js/core 1.4.2 → 1.5.0

package/lib/plugin-runtime/im/outbound-segments.d.ts

@@ -20,34 +20,33 @@ export interface OutboundSegment {
 }
 /**
  * 出站媒体能力策略（html→image 渲染产物与 base64/path 媒体段的投递方式）：
- * - `base64`：平台接受 base64 直发（qq / icqq / slack / weixin-ilink）；
+ * - `base64`：平台接受 base64 直发；
  * - `url-or-text`：平台仅接受 URL 媒体；本层无上传通道，base64/path → 文本降级；
- * - `passthrough`：adapter 自行物化媒体（napcat / onebot11 / onebot12），本层不动。
+ * - `passthrough`：adapter 自行物化媒体，本层不动。
  */
 export type OutboundMediaPolicy = 'base64' | 'url-or-text' | 'passthrough';
 /**
- * 任务 C `defineAdapter` segments policy 挂载形状（duck-typed 读取）。
- * 契约形状为 `outboundMedia: readonly ('url'|'path'|'base64'|'upload')[]`
- * （端点可消费的媒体来源形式，见 `@zhin.js/adapter` 的 AdapterSegmentPolicy）；
- * 兼容过渡期的单值策略字符串。Adapter 在 definition 上声明
- * `segments: { outboundMedia }` 即覆盖内置表。
+ * adapter definition 的 segments policy 声明（必选能力面）。
+ * `outboundMedia` 为端点可消费的媒体来源形式数组
+ * （'url' | 'path' | 'base64' | 'upload'），映射到投递策略：
+ * base64 可直发；无 base64 但端点可自行物化（upload/path）→ passthrough；
+ * 仅 url → 非 URL 媒体文本降级。未声明的 adapter 按 ['url'] 兜底。
  */
 export interface OutboundSegmentsPolicy {
-    readonly outboundMedia?: OutboundMediaPolicy | readonly ('url' | 'path' | 'base64' | 'upload')[];
+    readonly outboundMedia: readonly ('url' | 'path' | 'base64' | 'upload')[];
     readonly interactive?: InteractivePolicy;
 }
 export interface NormalizeOutboundOptions {
-    /** 缺省 `base64`（保持历史行为：html→image base64 直发）。 */
+    /** 缺省 `url-or-text`（未声明 adapter 的保守兜底：仅 URL 媒体可达）。 */
     readonly mediaPolicy?: OutboundMediaPolicy;
 }
-export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
 /**
- * 解析端点的出站媒体策略：优先读 adapter definition 上声明的
- * `segments.outboundMedia`（任务 C 挂载点；多 endpoint 展开的 `slot~entry`
- * id 回退到 slot id 查声明），否则按平台名查内置表，
- * 未知平台回退 `base64`（历史行为）。
+ * 解析端点的出站媒体策略：读 adapter definition 声明的 `segments.outboundMedia`
+ * （多 endpoint 展开的 `slot~entry` id 回退到 slot id 查声明）；
+ * 未声明回退 `url-or-text`（仅 URL 媒体可达，其余文本降级）。
  */
 export declare function resolveOutboundMediaPolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): OutboundMediaPolicy;
+export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
 /**
  * 解析端点的出站 interactive 策略：优先读 adapter definition 上声明的
  * `segments.interactive`，否则按平台名查内置表，未知平台回退 'text'。

package/lib/plugin-runtime/im/outbound-segments.js

@@ -5,48 +5,16 @@ import { DEFAULT_INTERACTIVE_POLICY, isKeyboardSegment, } from '../../built/inte
 import { isMediaRef } from '../../built/segment-contract/index.js';
 const DEFAULT_CARD_WIDTH = 540;
 const DEFAULT_CARD_FILENAME = 'card.png';
-const DEFAULT_MEDIA_POLICY = 'base64';
-/** 平台名 → 出站媒体策略（任务 C 声明式 policy 落地前的内置来源）。 */
-const OUTBOUND_MEDIA_POLICY_BY_ADAPTER = { qq: 'base64',
-    icqq: 'base64',
-    slack: 'base64',
-    'weixin-ilink': 'base64',
-    telegram: 'url-or-text',
-    line: 'url-or-text',
-    lark: 'url-or-text',
-    kook: 'url-or-text',
-    dingtalk: 'url-or-text',
-    'wechat-mp': 'url-or-text',
-    wecom: 'url-or-text',
-    email: 'url-or-text',
-    github: 'url-or-text',
-    milky: 'url-or-text',
-    napcat: 'passthrough',
-    onebot11: 'passthrough',
-    onebot12: 'passthrough',
-};
-export function isOutboundSegment(value) {
-    return typeof value === 'object'
-        && value !== null
-        && !Array.isArray(value)
-        && typeof value.type === 'string';
-}
+const DEFAULT_MEDIA_POLICY = 'url-or-text';
 /**
- * 解析端点的出站媒体策略：优先读 adapter definition 上声明的
- * `segments.outboundMedia`（任务 C 挂载点；多 endpoint 展开的 `slot~entry`
- * id 回退到 slot id 查声明），否则按平台名查内置表，
- * 未知平台回退 `base64`（历史行为）。
+ * 解析端点的出站媒体策略：读 adapter definition 声明的 `segments.outboundMedia`
+ * （多 endpoint 展开的 `slot~entry` id 回退到 slot id 查声明）；
+ * 未声明回退 `url-or-text`（仅 URL 媒体可达，其余文本降级）。
  */
 export function resolveOutboundMediaPolicy(adapter, snapshot) {
     const slot = snapshot.capabilities.get(adapter)
         ?? snapshot.capabilities.get(baseSlotCapabilityId(adapter));
-    const declared = readDeclaredMediaPolicy(slot?.definition);
-    if (declared)
-        return declared;
-    const packageName = slot ? snapshot.tree.get(slot.owner)?.packageName : undefined;
-    const adapterType = adapterTypeName(packageName);
-    return (adapterType ? OUTBOUND_MEDIA_POLICY_BY_ADAPTER[adapterType] : undefined)
-        ?? DEFAULT_MEDIA_POLICY;
+    return readDeclaredMediaPolicy(slot?.definition) ?? DEFAULT_MEDIA_POLICY;
 }
 function readDeclaredMediaPolicy(definition) {
     if (!definition || typeof definition !== 'object')
@@ -55,23 +23,22 @@ function readDeclaredMediaPolicy(definition) {
     if (!segments || typeof segments !== 'object')
         return undefined;
     const declared = segments.outboundMedia;
-    // 过渡期单值策略字符串
-    if (declared === 'base64' || declared === 'url-or-text' || declared === 'passthrough') {
-        return declared;
-    }
-    // 任务 C 契约：媒体来源形式数组 → 投递策略。
-    // base64 可直发；无 base64 但端点可自行物化（upload/path）→ passthrough；
-    // 仅 url → 非 URL 媒体文本降级。
-    if (Array.isArray(declared)) {
-        if (declared.includes('base64'))
-            return 'base64';
-        if (declared.includes('upload') || declared.includes('path'))
-            return 'passthrough';
-        if (declared.includes('url'))
-            return 'url-or-text';
-    }
+    if (!Array.isArray(declared))
+        return undefined;
+    if (declared.includes('base64'))
+        return 'base64';
+    if (declared.includes('upload') || declared.includes('path'))
+        return 'passthrough';
+    if (declared.includes('url'))
+        return 'url-or-text';
     return undefined;
 }
+export function isOutboundSegment(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && typeof value.type === 'string';
+}
 /**
  * 平台名 → 出站 interactive 策略（adapter 未声明 `segments.interactive` 时
  * 的内置来源）：telegram / discord 端点自行把 keyboard 编码为原生按钮；
@@ -181,11 +148,12 @@ async function renderHtmlSegment(segment, renderer, mediaPolicy) {
                 return {
                     type: 'image',
                     data: {
-                        // canonical MediaRef 为主，legacy `base64`/`name` 双写保持旧 adapter 可读
-                        // （Wave 2 适配器迁移完成后移除 legacy 字段）。
-                        media: { kind: 'base64', value: base64, mime_type: 'image/png' },
-                        base64,
-                        name: typeof data.fileName === 'string' ? data.fileName : DEFAULT_CARD_FILENAME,
+                        media: {
+                            kind: 'base64',
+                            value: base64,
+                            mime_type: 'image/png',
+                            file_name: typeof data.fileName === 'string' ? data.fileName : DEFAULT_CARD_FILENAME,
+                        },
                     },
                 };
             }
@@ -197,22 +165,26 @@ async function renderHtmlSegment(segment, renderer, mediaPolicy) {
     return { type: 'text', data: { text: htmlSegmentFallbackText(data, html) } };
 }
 /**
- * 媒体协商：仅 `url-or-text` 需要在本层动作——image 段的非 URL MediaRef
- * （base64 / 本地路径）无法投递，降级为文本（alt 优先）。
+ * 媒体协商：仅 `url-or-text` 需要在本层动作——媒体段的非 URL MediaRef
+ * （base64 / 本地路径）无法投递，降级为文本（alt / file_name 优先）。
  */
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
 function applyOutboundMediaPolicy(segments, mediaPolicy) {
     if (mediaPolicy !== 'url-or-text')
         return segments;
     return segments.map((segment) => {
-        if (segment.type !== 'image')
+        if (!MEDIA_SEGMENT_TYPES.has(segment.type))
             return segment;
-        const media = segment.data.media;
+        const data = segment.data;
+        const media = data.media;
         if (!isMediaRef(media) || media.kind === 'url')
             return segment;
-        const alt = typeof segment.data.alt === 'string' && segment.data.alt
-            ? segment.data.alt
-            : '[image]';
-        return { type: 'text', data: { text: alt } };
+        const label = typeof data.alt === 'string' && data.alt
+            ? data.alt
+            : typeof data.name === 'string' && data.name
+                ? data.name
+                : media.file_name ?? `[${segment.type}]`;
+        return { type: 'text', data: { text: label } };
     });
 }
 function htmlSegmentFallbackText(data, html) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -68,12 +68,13 @@
   "dependencies": {
     "qrcode": "^1.5.4",
     "segment-matcher": "^1.0.5",
-    "smol-toml": "^1.7.0",
+    "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
     "@zhin.js/component": "1.0.4",
     "@zhin.js/database": "1.0.78",
+    "@zhin.js/im-contract": "1.0.0",
     "@zhin.js/kernel": "1.0.5",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/middleware": "1.0.4",
@@ -89,11 +90,11 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "@types/qrcode": "^1.5.5",
+    "@types/node": "^26.1.2",
+    "@types/qrcode": "^1.5.6",
     "ajv": "8.18.0",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.4.6"
+    "@zhin.js/ai": "1.5.0"
   },
   "repository": {
     "type": "git",