@zhin.js/adapter-slack 5.0.6 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 6.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/agent@1.1.0
+  - zhin.js@6.0.0
+
 ## 5.0.6
 
 ### Patch Changes

package/adapters/slack.js

@@ -11,15 +11,16 @@ import { slackRuntimeStateToken } from "../lib/slack-runtime-state.js";
 export { SlackEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // 媒体由端点物化（url 拉取 / 本地读取）经 files.uploadV2 上传；
-    // Block Kit 原生按钮承载交互段。
+    // 媒体段（canonical MediaRef）：kind=url 直发（image 走 attachment image_url，
+    // 其余拉取后上传）；kind=base64 解码后经 files.uploadV2 上传；kind=path 读盘上传；
+    // kind=file 无 Slack 对应物，丢弃留痕。Block Kit 原生按钮承载交互段。
     segments: {
-        outboundMedia: ['url', 'upload'],
+        outboundMedia: ['url', 'upload', 'path'],
         interactive: 'native',
     },
     create(context) {
         const config = resolveSlackConfig(context.config);
-        // 注册到插件运行时状态（slack endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（slack.endpoint list 的"运行中"数据源）
         context.use(slackRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.mode,

package/adapters/slack.ts

@@ -16,15 +16,16 @@ export type { SlackEndpointOptions, SlackSocketLike, SlackWebClientLike } from '
 
 export default defineAdapter<SlackAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // 媒体由端点物化（url 拉取 / 本地读取）经 files.uploadV2 上传；
-  // Block Kit 原生按钮承载交互段。
+  // 媒体段（canonical MediaRef）：kind=url 直发（image 走 attachment image_url，
+  // 其余拉取后上传）；kind=base64 解码后经 files.uploadV2 上传；kind=path 读盘上传；
+  // kind=file 无 Slack 对应物，丢弃留痕。Block Kit 原生按钮承载交互段。
   segments: {
-    outboundMedia: ['url', 'upload'],
+    outboundMedia: ['url', 'upload', 'path'],
     interactive: 'native',
   },
   create(context) {
     const config = resolveSlackConfig(context.config);
-    // 注册到插件运行时状态（slack endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（slack.endpoint list 的"运行中"数据源）
     context.use(slackRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: config.mode,

package/lib/protocol.js

@@ -3,7 +3,14 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
 import { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';
+const logger = getLogger('slack');
+/** 无 canonical MediaRef 或不可投递时留痕（对齐 QQ `*_outbound_media_dropped` 风格）。 */
+function dropOutboundMedia(type, reason) {
+    logger.warn(formatCompact({ op: 'slack_outbound_media_dropped', type, reason }));
+}
 const SLACK_SIG_VERSION = 'v0';
 const MAX_TIMESTAMP_DRIFT_SECONDS = 300;
 export function resolveSlackConfig(config = {}) {
@@ -129,31 +136,42 @@ export function formatOutboundWire(payload) {
                     text += `<${String(data.url ?? '')}>`;
                 }
                 break;
-            case 'image':
-                if (typeof data.url === 'string' && data.url) {
+            case 'image': {
+                // canonical MediaRef 唯一来源；kind=url 走 attachment 直发，其余物化后 files.uploadV2 上传
+                const media = data.media;
+                if (!isMediaRef(media)) {
+                    dropOutboundMedia(item.type, 'missing_media_ref');
+                    break;
+                }
+                if (media.kind === 'url') {
                     attachments.push({
-                        image_url: data.url,
-                        title: String(data.name ?? data.title ?? ''),
+                        image_url: media.value,
+                        title: String(data.alt ?? data.title ?? media.file_name ?? ''),
                     });
+                    break;
                 }
-                else if (data.media && typeof data.media === 'object') {
-                    files.push(resolveMediaToFile(data.media, String(data.alt ?? 'image')));
-                }
+                const imageFile = resolveMediaToFile(media, String(data.alt ?? media.file_name ?? 'image'));
+                if (imageFile)
+                    files.push(imageFile);
+                else
+                    dropOutboundMedia(item.type, 'unsupported_media_kind');
                 break;
+            }
             case 'audio':
             case 'video':
-            case 'file':
-                if (data.media && typeof data.media === 'object') {
-                    files.push(resolveMediaToFile(data.media, String(data.name ?? item.type)));
-                }
-                else if (data.file || data.url) {
-                    files.push({
-                        path: typeof data.file === 'string' ? data.file : undefined,
-                        url: typeof data.url === 'string' ? data.url : undefined,
-                        name: String(data.name ?? item.type),
-                    });
+            case 'file': {
+                const media = data.media;
+                if (!isMediaRef(media)) {
+                    dropOutboundMedia(item.type, 'missing_media_ref');
+                    break;
                 }
+                const mediaFile = resolveMediaToFile(media, String(data.name ?? media.file_name ?? item.type));
+                if (mediaFile)
+                    files.push(mediaFile);
+                else
+                    dropOutboundMedia(item.type, 'unsupported_media_kind');
                 break;
+            }
             case 'keyboard':
                 blocks.push(...keyboardToBlockKitBlocks(data));
                 break;
@@ -183,11 +201,27 @@ export function keyboardToBlockKitBlocks(data) {
     }
     return blocks;
 }
+/**
+ * MediaRef → 待上传文件描述：
+ * - kind=url → 记录 URL，由 files.uploadV2 前拉取物化；
+ * - kind=base64 → 解码为 buffer 直传；
+ * - kind=path → 记录本地路径，上传前读盘；
+ * - kind=file → Slack 无平台不透明文件引用可直发，返回 undefined 由调用方丢弃留痕。
+ */
 function resolveMediaToFile(media, name) {
-    if (media.kind === 'base64') {
-        return { buffer: Buffer.from(media.value, 'base64'), name };
+    switch (media.kind) {
+        case 'base64':
+            return {
+                buffer: Buffer.from(media.value.replace(/^base64:\/\//, ''), 'base64'),
+                name,
+            };
+        case 'url':
+            return { url: media.value, name };
+        case 'path':
+            return { path: media.value, name };
+        default:
+            return undefined;
     }
-    return { url: media.value, name };
 }
 export function verifySlackSignature(signingSecret, rawBody, timestamp, signature) {
     const now = Math.floor(Date.now() / 1000);

package/lib/slack-endpoint-commands.js

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

package/lib/slack-runtime-state.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-slack",
-  "version": "5.0.6",
+  "version": "6.0.0",
   "description": "Zhin.js Slack adapter for Plugin Runtime (Socket Mode / HTTP Events)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,21 @@
   "dependencies": {
     "@slack/socket-mode": "^2.0.7",
     "@slack/web-api": "^7.19.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@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/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
     "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,8 +66,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
-    "zhin.js": "5.0.3"
+    "@zhin.js/agent": "1.1.0",
+    "zhin.js": "6.0.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'Slack Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（slack endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（slack.endpoint list 的"运行中"数据源）
         context.resources.provide(slackRuntimeStateToken, createEndpointRuntimeState());
         // 平台权限门禁：workspace_owner / channel_manager 等（agent 工具 platformPermit）
         return registerSlackPlatformPermitChecker();

package/src/protocol.ts

@@ -4,8 +4,17 @@
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
+import { isMediaRef, type MediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
 import { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';
 
+const logger = getLogger('slack');
+
+/** 无 canonical MediaRef 或不可投递时留痕（对齐 QQ `*_outbound_media_dropped` 风格）。 */
+function dropOutboundMedia(type: string, reason: string): void {
+  logger.warn(formatCompact({ op: 'slack_outbound_media_dropped', type, reason }));
+}
+
 const SLACK_SIG_VERSION = 'v0';
 const MAX_TIMESTAMP_DRIFT_SECONDS = 300;
 
@@ -266,29 +275,38 @@ export function formatOutboundWire(payload: unknown): {
           text += `<${String(data.url ?? '')}>`;
         }
         break;
-      case 'image':
-        if (typeof data.url === 'string' && data.url) {
+      case 'image': {
+        // canonical MediaRef 唯一来源；kind=url 走 attachment 直发，其余物化后 files.uploadV2 上传
+        const media = data.media;
+        if (!isMediaRef(media)) {
+          dropOutboundMedia(item.type, 'missing_media_ref');
+          break;
+        }
+        if (media.kind === 'url') {
           attachments.push({
-            image_url: data.url,
-            title: String(data.name ?? data.title ?? ''),
+            image_url: media.value,
+            title: String(data.alt ?? data.title ?? media.file_name ?? ''),
           });
-        } else if (data.media && typeof data.media === 'object') {
-          files.push(resolveMediaToFile(data.media as { kind: string; value: string }, String(data.alt ?? 'image')));
+          break;
         }
+        const imageFile = resolveMediaToFile(media, String(data.alt ?? media.file_name ?? 'image'));
+        if (imageFile) files.push(imageFile);
+        else dropOutboundMedia(item.type, 'unsupported_media_kind');
         break;
+      }
       case 'audio':
       case 'video':
-      case 'file':
-        if (data.media && typeof data.media === 'object') {
-          files.push(resolveMediaToFile(data.media as { kind: string; value: string }, String(data.name ?? item.type)));
-        } else if (data.file || data.url) {
-          files.push({
-            path: typeof data.file === 'string' ? data.file : undefined,
-            url: typeof data.url === 'string' ? data.url : undefined,
-            name: String(data.name ?? item.type),
-          });
+      case 'file': {
+        const media = data.media;
+        if (!isMediaRef(media)) {
+          dropOutboundMedia(item.type, 'missing_media_ref');
+          break;
         }
+        const mediaFile = resolveMediaToFile(media, String(data.name ?? media.file_name ?? item.type));
+        if (mediaFile) files.push(mediaFile);
+        else dropOutboundMedia(item.type, 'unsupported_media_kind');
         break;
+      }
       case 'keyboard':
         blocks.push(...keyboardToBlockKitBlocks(data));
         break;
@@ -321,14 +339,30 @@ export function keyboardToBlockKitBlocks(data: Record<string, unknown>): Record<
   return blocks;
 }
 
+/**
+ * MediaRef → 待上传文件描述：
+ * - kind=url → 记录 URL，由 files.uploadV2 前拉取物化；
+ * - kind=base64 → 解码为 buffer 直传；
+ * - kind=path → 记录本地路径，上传前读盘；
+ * - kind=file → Slack 无平台不透明文件引用可直发，返回 undefined 由调用方丢弃留痕。
+ */
 function resolveMediaToFile(
-  media: { kind: string; value: string },
+  media: MediaRef,
   name: string,
-): { buffer?: Buffer; url?: string; name: string } {
-  if (media.kind === 'base64') {
-    return { buffer: Buffer.from(media.value, 'base64'), name };
+): { buffer?: Buffer; url?: string; path?: string; name: string } | undefined {
+  switch (media.kind) {
+    case 'base64':
+      return {
+        buffer: Buffer.from(media.value.replace(/^base64:\/\//, ''), 'base64'),
+        name,
+      };
+    case 'url':
+      return { url: media.value, name };
+    case 'path':
+      return { path: media.value, name };
+    default:
+      return undefined;
   }
-  return { url: media.value, name };
 }
 
 export function verifySlackSignature(

package/src/slack-endpoint-commands.ts

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

package/src/slack-runtime-state.ts

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