@zhin.js/adapter-github 4.0.5 → 5.0.0

package/CHANGELOG.md

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

package/adapters/github.js

@@ -29,7 +29,7 @@ export default defineAdapter({
     create(context) {
         const config = resolveGithubConfig(context.config);
         const database = optionalDatabase(context);
-        // 注册到插件运行时状态（github endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
         context.use(githubRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.webhookSecret ? 'webhook' : 'api',

package/adapters/github.ts

@@ -37,7 +37,7 @@ export default defineAdapter<GithubAdapterConfig>({
   create(context) {
     const config = resolveGithubConfig(context.config);
     const database = optionalDatabase(context);
-    // 注册到插件运行时状态（github endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
     context.use(githubRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: config.webhookSecret ? 'webhook' : 'api',

package/lib/github-endpoint-commands.js

@@ -1,10 +1,10 @@
 /**
- * `github endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `github.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  *
  * 字段说明：private_key 内容长且含换行，不适合 kv 直传——运行时（gh-client
  * resolvePrivateKey）本就支持 PEM 内容或文件路径，故 add 采用**内联路径**形式：
- * `github endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
+ * `github.endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';
 import { defineCommand } from '@zhin.js/command';

package/lib/github-runtime-state.js

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

package/lib/protocol.js

@@ -4,6 +4,9 @@
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('github');
 import { buildChannelId, } from './types.js';
 export { buildChannelId, parseChannelId } from './types.js';
 export function resolveGithubConfig(config = {}) {
@@ -94,7 +97,10 @@ export function formatOutboundBody(payload) {
             case 'at':
                 return `@${item.data?.name || item.data?.id || item.data?.target || ''}`;
             case 'image':
-                return item.data?.url ? `![image](${item.data.url})` : '[image]';
+            case 'audio':
+            case 'video':
+            case 'file':
+                return formatMediaSegment(item);
             case 'link':
                 return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
             default:
@@ -102,6 +108,38 @@ export function formatOutboundBody(payload) {
         }
     }).join('');
 }
+/**
+ * 媒体段 → GitHub markdown（canonical MediaRef 唯一来源）。
+ * GitHub 评论只能消费远程 URL（无上传面），kind=url 直发；
+ * base64 / path / file 不可投递，warn + 丢弃。
+ */
+function formatMediaSegment(seg) {
+    const media = seg.data?.media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'github_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_media_ref',
+        }));
+        return '';
+    }
+    if (media.kind !== 'url') {
+        logger.warn(formatCompact({
+            op: 'github_outbound_media_dropped',
+            type: seg.type,
+            reason: `unsupported_kind:${media.kind}`,
+        }));
+        return '';
+    }
+    if (seg.type === 'image') {
+        const alt = typeof seg.data?.alt === 'string' && seg.data.alt
+            ? seg.data.alt
+            : media.file_name || 'image';
+        return `![${alt}](${media.value})`;
+    }
+    const label = media.file_name || seg.type;
+    return `[${label}](${media.value})`;
+}
 export function verifyWebhookSignature(secret, rawBody, signatureHeader) {
     if (!signatureHeader?.startsWith('sha256='))
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "4.0.5",
+  "version": "5.0.0",
   "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,21 +41,21 @@
     "directory": "plugins/adapters/github"
   },
   "dependencies": {
-    "@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/plugin-runtime": "1.1.1",
-    "@zhin.js/logger": "1.0.75"
+    "@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": {
@@ -73,8 +73,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

@@ -27,7 +27,7 @@ export default definePlugin({
         displayName: 'GitHub Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（github endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（github.endpoint list 的"运行中"数据源）
         context.resources.provide(githubRuntimeStateToken, createEndpointRuntimeState());
         if (context.resources.has(databaseHostToken)) {
             const host = context.resources.use(databaseHostToken);

package/src/github-endpoint-commands.ts

@@ -1,10 +1,10 @@
 /**
- * `github endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `github.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  *
  * 字段说明：private_key 内容长且含换行，不适合 kv 直传——运行时（gh-client
  * resolvePrivateKey）本就支持 PEM 内容或文件路径，故 add 采用**内联路径**形式：
- * `github endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
+ * `github.endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';
 import { defineCommand } from '@zhin.js/command';

package/src/github-runtime-state.ts

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

package/src/protocol.ts

@@ -6,6 +6,10 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('github');
 import {
   buildChannelId,
   type GenericWebhookPayload,
@@ -209,7 +213,10 @@ export function formatOutboundBody(payload: unknown): string {
       case 'at':
         return `@${item.data?.name || item.data?.id || item.data?.target || ''}`;
       case 'image':
-        return item.data?.url ? `![image](${item.data.url})` : '[image]';
+      case 'audio':
+      case 'video':
+      case 'file':
+        return formatMediaSegment(item);
       case 'link':
         return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
       default:
@@ -218,6 +225,39 @@ export function formatOutboundBody(payload: unknown): string {
   }).join('');
 }
 
+/**
+ * 媒体段 → GitHub markdown（canonical MediaRef 唯一来源）。
+ * GitHub 评论只能消费远程 URL（无上传面），kind=url 直发；
+ * base64 / path / file 不可投递，warn + 丢弃。
+ */
+function formatMediaSegment(seg: GithubWireSegment): string {
+  const media = seg.data?.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'github_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_media_ref',
+    }));
+    return '';
+  }
+  if (media.kind !== 'url') {
+    logger.warn(formatCompact({
+      op: 'github_outbound_media_dropped',
+      type: seg.type,
+      reason: `unsupported_kind:${media.kind}`,
+    }));
+    return '';
+  }
+  if (seg.type === 'image') {
+    const alt = typeof seg.data?.alt === 'string' && seg.data.alt
+      ? seg.data.alt
+      : media.file_name || 'image';
+    return `![${alt}](${media.value})`;
+  }
+  const label = media.file_name || seg.type;
+  return `[${label}](${media.value})`;
+}
+
 export function verifyWebhookSignature(
   secret: string,
   rawBody: string,