@zhin.js/adapter-onebot12 4.0.0 → 4.0.2

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @zhin.js/adapter-onebot12
 
+## 4.0.2
+
+### Patch Changes
+
+- d5cd4aa: Publish Plugin Runtime entry points and convention modules as JavaScript so
+  installed npm plugins load on Node without TypeScript stripping. Workspace
+  development continues to prefer TypeScript sources for local HMR.
+
+  Remove the unconsumed legacy game hub APIs from game-kit; game navigation and
+  records now use ordinary convention commands owned by the game hub plugin.
+
+- Updated dependencies [d5cd4aa]
+  - @zhin.js/command@1.0.4
+  - zhin.js@5.0.2
+  - @zhin.js/adapter@1.1.2
+  - @zhin.js/core@1.4.2
+
+## 4.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- 078e3f7: 架构统一批（AURA）：
+
+  - **EndpointLifecycle 基座**（@zhin.js/adapter 新增 `createEndpointLifecycle`）：WS/SSE 端点的 start 失败复位、仅曾 open 才退避重连（指数+jitter 可配）、stop 不重连、PONG 看门狗、定时器集中清理、陈旧事件防叠套；napcat/milky/onebot11/onebot12/satori 已迁移（删除各自手写状态机），从此同类竞态在结构上不可能再犯。
+  - **Generation-store**（@zhin.js/plugin-runtime 新增 `createGenerationStore`）：模块级运行时状态的一等能力，provide 自动挂 lifecycle 反注册（代际结束自动清理）；lottery deps 与 rss db 已迁移，公开 API 兼容。
+  - **Resolver 管线收敛**（@zhin.js/runtime）：解析规则统一为 local path → workspace → node_modules 单管线；optional 引用对所有 PackageResolutionError 容错（消除 message 前缀补丁）。
+  - **工具目录准入统一**（@zhin.js/agent）：RegisteredToolSource 与 ExternalToolSource 共用同一 `canAccessTool` 准入（platforms/scopes/permissions/hidden 四元组全链路透传），同名覆盖 warn；AgentToolRegistration 补 platforms/scopes。两条注册通道（静态约定 vs 动态注册）职责边界已文档化。
+
+- 9c997b2: 通用 endpoint 管理命令套件：`@zhin.js/adapter` 新增 `createEndpointCommands(spec, defineCommand)`——`<adapter> endpoint list / add <name> key=value... / remove <name>` 三件套，含 kv 解析、`.env` 凭据派生（`<ADAPTER>_<NAME>_<FIELD>`）、yaml 写回保留注释、master 权限门禁（通用 `isEndpointOperator`）、自定义 bindFlow 钩子。QQ 迁移至套件（行为与扫码绑定流程不变）；napcat / onebot11 / onebot12 / milky / slack / telegram 接入（字段对齐各自 schema，features 补 @zhin.js/command）。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
 ## 4.0.0
 
 ### Patch Changes

package/adapters/onebot12.js

@@ -0,0 +1,54 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/onebot12.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { OneBot12WebhookEndpoint } from "../lib/webhook.js";
+import { OneBot12WsEndpoint } from "../lib/ws-endpoint.js";
+import { OneBot12WssEndpoint } from "../lib/wss-endpoint.js";
+import { resolveOneBot12Config, } from "../lib/protocol.js";
+import { onebot12RuntimeStateToken } from "../lib/onebot12-runtime-state.js";
+export { OneBot12WebhookEndpoint } from "../lib/webhook.js";
+export { OneBot12WsEndpoint } from "../lib/ws-endpoint.js";
+export { OneBot12WssEndpoint } from "../lib/wss-endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // 媒体段经 upload_file 物化为 file_id（spec 正式投递）；上传失败降级扩展字段透传。
+    // 无卡片交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url', 'path', 'base64', 'upload'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveOneBot12Config(context.config);
+        const gateway = context.use(messageGatewayToken);
+        // 注册到插件运行时状态（onebot12 endpoint list 的"运行中"数据源）
+        context.use(onebot12RuntimeStateToken).endpoints.set(config.name, {
+            name: config.name,
+            mode: config.connection,
+        });
+        if (config.connection === 'webhook') {
+            return new OneBot12WebhookEndpoint({
+                id: context.id,
+                gateway,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        if (config.connection === 'wss') {
+            return new OneBot12WssEndpoint({
+                id: context.id,
+                gateway,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        return new OneBot12WsEndpoint({
+            id: context.id,
+            gateway,
+            config,
+        });
+    },
+});

package/adapters/onebot12.ts

@@ -11,6 +11,7 @@ import {
   resolveOneBot12Config,
   type OneBot12AdapterConfig,
 } from '../src/protocol.js';
+import { onebot12RuntimeStateToken } from '../src/onebot12-runtime-state.js';
 
 export { OneBot12WebhookEndpoint } from '../src/webhook.js';
 export type { OneBot12WebhookEndpointOptions } from '../src/webhook.js';
@@ -22,9 +23,20 @@ export type { OneBot12WsSocket, OneBot12WsCreateOptions } from '../src/ws-types.
 
 export default defineAdapter<OneBot12AdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 媒体段经 upload_file 物化为 file_id（spec 正式投递）；上传失败降级扩展字段透传。
+  // 无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'path', 'base64', 'upload'],
+    interactive: 'text',
+  },
   create(context) {
     const config = resolveOneBot12Config(context.config);
     const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（onebot12 endpoint list 的"运行中"数据源）
+    context.use(onebot12RuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.connection,
+    });
     if (config.connection === 'webhook') {
       return new OneBot12WebhookEndpoint({
         id: context.id,

package/commands/endpoint/add/[name:string].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { onebot12EndpointCommands } from "../../../lib/onebot12-endpoint-commands.js";
+export default onebot12EndpointCommands.add;

package/commands/endpoint/add/[name:string].ts

@@ -0,0 +1,3 @@
+import { onebot12EndpointCommands } from '../../../src/onebot12-endpoint-commands.js';
+
+export default onebot12EndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { onebot12EndpointCommands } from "../../lib/onebot12-endpoint-commands.js";
+export default onebot12EndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { onebot12EndpointCommands } from '../../src/onebot12-endpoint-commands.js';
+
+export default onebot12EndpointCommands.list;

package/commands/endpoint/remove/[name:string].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { onebot12EndpointCommands } from "../../../lib/onebot12-endpoint-commands.js";
+export default onebot12EndpointCommands.remove;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { onebot12EndpointCommands } from '../../../src/onebot12-endpoint-commands.js';
+
+export default onebot12EndpointCommands.remove;

package/lib/endpoint-management.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OneBot12 endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 动作名对齐 OB12 规范：get_friend_list / get_group_list / get_group_member_list。
+ * 归一化取舍（OB12 id 为字符串，收敛为数字）：
+ * - friend → {user_id:number, nickname: user_name, remark: user_displayname ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OB12 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from '@zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/webhook 三种传输各自实现）。 */
+export interface OneBot12ManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createOneBot12EndpointManagement(endpoint: OneBot12ManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createOneBot12EndpointManagement(endpoint) {
+    return Object.freeze({
+        async listFriends() {
+            const data = await endpoint.callApi('get_friend_list');
+            return toArray(data).map((value) => {
+                const friend = asRecord(value);
+                return {
+                    user_id: toNumberId(friend.user_id, 'user_id'),
+                    nickname: String(friend.user_name ?? friend.nickname ?? ''),
+                    remark: String(friend.user_displayname ?? friend.remark ?? ''),
+                };
+            });
+        },
+        async listGroups() {
+            const data = await endpoint.callApi('get_group_list');
+            return toArray(data).map((value) => {
+                const group = asRecord(value);
+                return {
+                    group_id: toNumberId(group.group_id, 'group_id'),
+                    name: String(group.group_name ?? group.name ?? ''),
+                };
+            });
+        },
+        async listGroupMembers(groupId) {
+            const data = await endpoint.callApi('get_group_member_list', {
+                group_id: groupId,
+            });
+            return toArray(data);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** OB12 id 是字符串；QQ 系实现均为数字串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`onebot12 ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, parseSendTarget, resolveOneBot12Config, senderNickname, senderUserId, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12AdapterConfig, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, type ParsedSendTarget, type ResolvedOneBot12Config, } from './protocol.js';
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, parseSendTarget, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12AdapterConfig, type OneBot12CallAction, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, type ParsedSendTarget, type ResolvedOneBot12Config, } from './protocol.js';
 export { OneBot12WebhookEndpoint, type OneBot12WebhookEndpointOptions, } from './webhook.js';
 export { OneBot12WsEndpoint, type OneBot12WsEndpointOptions, } from './ws-endpoint.js';
 export { OneBot12WssEndpoint, type OneBot12WssEndpointOptions, } from './wss-endpoint.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, parseSendTarget, resolveOneBot12Config, senderNickname, senderUserId, } from './protocol.js';
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, parseSendTarget, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 export { OneBot12WebhookEndpoint, } from './webhook.js';
 export { OneBot12WsEndpoint, } from './ws-endpoint.js';
 export { OneBot12WssEndpoint, } from './wss-endpoint.js';

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

@@ -0,0 +1 @@
+export declare const onebot12EndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/onebot12-endpoint-commands.js

@@ -0,0 +1,25 @@
+/**
+ * `onebot12 endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { onebot12RuntimeStateToken } from './onebot12-runtime-state.js';
+export const onebot12EndpointCommands = createEndpointCommands({
+    adapterKey: 'onebot12',
+    adapterDisplayName: 'OneBot 12',
+    fields: [
+        { key: 'url', description: 'OneBot 实现 WebSocket URL（connection: ws 必填）' },
+        { key: 'path', description: 'HTTP/WS 路径（webhook / reverse-wss）' },
+        { key: 'api_url', description: 'HTTP action 端点（connection: webhook 出站必填）' },
+        { key: 'access_token', env: true, description: 'OneBot access token' },
+    ],
+    running: (use) => use(onebot12RuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => {
+        if (entry.url)
+            return `url: ${String(entry.url)}`;
+        if (entry.path)
+            return `path: ${String(entry.path)}`;
+        return '';
+    },
+}, defineCommand);

package/lib/onebot12-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const onebot12RuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/onebot12-runtime-state.js

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

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
+import { type MediaRef } from '@zhin.js/core';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
 export interface OneBot12LegacyEndpointRow {
     readonly context?: string;
@@ -132,11 +133,30 @@ export declare function senderNickname(ev: OneBot12Event): string | undefined;
  * 新 Plugin Runtime 的 Message.content 为纯文本，mention 信息只能经 metadata.mentioned 传递。
  */
 export declare function isBotMentioned(ev: OneBot12Event): boolean;
+/**
+ * canonical MediaRef → OneBot 12 媒体字段（扩展字段降级形状）。
+ * spec 正式投递形状是 `file_id`（先 upload_file 物化，见
+ * {@link uploadOneBot12MediaSegments}）；上传失败时按常见扩展字段
+ * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`。
+ */
+export declare function mediaRefToOneBot12Fields(media: MediaRef): Record<string, unknown>;
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（mention / 裸 `{url,file,base64}`）保持兼容透传。
  */
 export declare function formatOutboundSegments(payload: unknown): OneBot12Segment[];
+/** 端点动作调用签名（WS echo 请求 / webhook api_url HTTP）。 */
+export type OneBot12CallAction = (action: string, params: Record<string, unknown>) => Promise<unknown>;
+/** canonical MediaRef → OB12 `upload_file` 动作参数（spec: type url/path/data）。 */
+export declare function mediaRefToOneBot12UploadParams(segmentType: string, data: Record<string, unknown>, media: MediaRef): Record<string, unknown> | undefined;
+/**
+ * 出站媒体段物化：image/voice/audio/video/file 段的 MediaRef（url/base64/path）
+ * 先经 `upload_file` 换 file_id（spec 正式投递形状），再交给
+ * {@link formatOutboundSegments} 编码；kind=file 的 MediaRef 直接按 file_id 复投。
+ * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
+ */
+export declare function uploadOneBot12MediaSegments(payload: unknown, callAction: OneBot12CallAction, onUploadFailed?: (error: unknown) => void): Promise<unknown>;
 export declare function buildSendMessageParams(target: string, message: OneBot12Segment[]): Record<string, unknown>;
 /**
  * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。

package/lib/protocol.js

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
 export function resolveOneBot12Config(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'onebot12');
     const connection = config.connection
@@ -142,9 +143,82 @@ export function isBotMentioned(ev) {
         return false;
     return ev.message.some((seg) => seg.type === 'mention' && String(seg.data?.['user_id'] ?? '') === selfId);
 }
+/** OneBot 12 携带媒体的段类型。 */
+const ONEBOT12_MEDIA_TYPES = new Set(['image', 'voice', 'audio', 'video', 'file']);
+/** 媒体段 data 里的 canonical-only / legacy 媒体字段，归一后不重复进 wire。 */
+const MEDIA_DATA_SKIP_KEYS = new Set([
+    'media', 'alt', 'mime_type', 'url', 'file', 'base64', 'data', 'path',
+]);
+/**
+ * canonical MediaRef → OneBot 12 媒体字段（扩展字段降级形状）。
+ * spec 正式投递形状是 `file_id`（先 upload_file 物化，见
+ * {@link uploadOneBot12MediaSegments}）；上传失败时按常见扩展字段
+ * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`。
+ */
+export function mediaRefToOneBot12Fields(media) {
+    if (media.kind === 'base64') {
+        const value = media.value.startsWith('base64://')
+            ? media.value.slice('base64://'.length)
+            : media.value;
+        return { data: value };
+    }
+    if (media.kind === 'path') {
+        return { path: media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value };
+    }
+    return { url: media.value };
+}
+function oneBot12MediaExtra(data) {
+    const extra = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (!MEDIA_DATA_SKIP_KEYS.has(key))
+            extra[key] = value;
+    }
+    return extra;
+}
+function oneBot12MediaSegment(type, data) {
+    // 已物化为 file_id 的段是 spec 正式形状，原样透传。
+    if (typeof data.file_id === 'string' && data.file_id)
+        return { type, data };
+    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+    if (!media)
+        return { type, data };
+    return { type, data: { ...oneBot12MediaExtra(data), ...mediaRefToOneBot12Fields(media) } };
+}
+/**
+ * canonical Segment → OneBot 12 数组段：
+ * - mention → mention（`user_id: target`，`target: 'all'` → mention_all）；
+ * - reply（`message_id`）→ reply（`message_id`）；
+ * - image / voice / audio / video / file 的 MediaRef → url/data/path 扩展字段；
+ * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
+ */
+function canonicalToOneBotSegment(segment) {
+    const data = segment.data ?? {};
+    switch (segment.type) {
+        case 'mention': {
+            const target = data.target ?? data.user_id ?? data.id;
+            if (target == null)
+                return { type: segment.type, data };
+            if (String(target) === 'all')
+                return { type: 'mention_all', data: {} };
+            return { type: 'mention', data: { user_id: String(target) } };
+        }
+        case 'reply': {
+            const messageId = data.message_id ?? data.id;
+            if (messageId == null)
+                return { type: segment.type, data };
+            return { type: 'reply', data: { message_id: String(messageId) } };
+        }
+        default:
+            if (ONEBOT12_MEDIA_TYPES.has(segment.type)) {
+                return oneBot12MediaSegment(segment.type, data);
+            }
+            return { type: segment.type, data };
+    }
+}
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（mention / 裸 `{url,file,base64}`）保持兼容透传。
  */
 export function formatOutboundSegments(payload) {
     if (typeof payload === 'string') {
@@ -169,10 +243,94 @@ export function formatOutboundSegments(payload) {
             segs.push({ type: 'text', data: { text: item } });
             continue;
         }
-        segs.push({ type: item.type, data: item.data ?? {} });
+        segs.push(canonicalToOneBotSegment(item));
     }
     return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }
+/** upload_file 文件名：优先段 data.name/filename，URL/路径取 basename，再按 mime 给默认名。 */
+function oneBot12UploadName(segmentType, data, media) {
+    const named = data.name ?? data.filename;
+    if (typeof named === 'string' && named)
+        return named;
+    if (media.kind === 'url') {
+        try {
+            const base = new URL(media.value).pathname.split('/').filter(Boolean).pop();
+            if (base)
+                return base;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (media.kind === 'path') {
+        const base = media.value.split(/[\\/]/).filter(Boolean).pop();
+        if (base)
+            return base;
+    }
+    const ext = media.mime_type?.split('/')[1]?.split(';')[0];
+    return `${segmentType}.${ext || 'bin'}`;
+}
+/** canonical MediaRef → OB12 `upload_file` 动作参数（spec: type url/path/data）。 */
+export function mediaRefToOneBot12UploadParams(segmentType, data, media) {
+    const name = oneBot12UploadName(segmentType, data, media);
+    if (media.kind === 'url')
+        return { type: 'url', name, url: media.value };
+    if (media.kind === 'path') {
+        const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+        return { type: 'path', name, path };
+    }
+    if (media.kind === 'base64') {
+        const value = media.value.startsWith('base64://')
+            ? media.value.slice('base64://'.length)
+            : media.value;
+        return { type: 'data', name, data: value };
+    }
+    return undefined;
+}
+async function uploadOneMediaSegment(item, callAction, onUploadFailed) {
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        return item;
+    const segment = item;
+    if (typeof segment.type !== 'string' || !ONEBOT12_MEDIA_TYPES.has(segment.type))
+        return item;
+    const data = segment.data ?? {};
+    if (typeof data.file_id === 'string' && data.file_id)
+        return item;
+    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+    if (!media)
+        return item;
+    // kind=file：平台不透明引用（OB12 file_id 复投），直接物化为 file_id。
+    if (media.kind === 'file') {
+        return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: media.value } };
+    }
+    const params = mediaRefToOneBot12UploadParams(segment.type, data, media);
+    if (!params)
+        return item;
+    try {
+        const result = await callAction('upload_file', params);
+        if (result && typeof result.file_id === 'string' && result.file_id) {
+            return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: result.file_id } };
+        }
+        throw new Error('upload_file 响应缺少 file_id');
+    }
+    catch (error) {
+        // 上传失败降级：保留原段，由 formatOutboundSegments 走扩展字段（url/data/path）
+        onUploadFailed?.(error);
+        return item;
+    }
+}
+/**
+ * 出站媒体段物化：image/voice/audio/video/file 段的 MediaRef（url/base64/path）
+ * 先经 `upload_file` 换 file_id（spec 正式投递形状），再交给
+ * {@link formatOutboundSegments} 编码；kind=file 的 MediaRef 直接按 file_id 复投。
+ * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
+ */
+export async function uploadOneBot12MediaSegments(payload, callAction, onUploadFailed) {
+    if (Array.isArray(payload)) {
+        return Promise.all(payload.map((item) => uploadOneMediaSegment(item, callAction, onUploadFailed)));
+    }
+    return uploadOneMediaSegment(payload, callAction, onUploadFailed);
+}
 export function buildSendMessageParams(target, message) {
     const parsed = parseSendTarget(target);
     const params = {
@@ -208,6 +366,7 @@ export async function callOneBot12Action(options, action, params = {}, echo) {
         method: 'POST',
         headers,
         body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30_000),
     });
     const text = await res.text();
     if (res.status === 401)

package/lib/webhook.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -12,6 +12,7 @@ export interface OneBot12WebhookEndpointOptions {
 }
 export declare class OneBot12WebhookEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: OneBot12WebhookEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -21,5 +22,7 @@ export declare class OneBot12WebhookEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    /** Public API for management surface / callers；webhook 模式走 api_url。 */
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     admit(ev: OneBot12Event): void;
 }

package/lib/webhook.js

@@ -1,9 +1,11 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
+import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 const logger = getLogger('onebot12');
 export class OneBot12WebhookEndpoint {
     #options;
+    management = createOneBot12EndpointManagement(this);
     #callAction;
     #routeReleases = [];
     #open = false;
@@ -16,6 +18,15 @@ export class OneBot12WebhookEndpoint {
         if (this.#started)
             return;
         this.#started = true;
+        if (!this.#options.config.access_token) {
+            // webhook 模式未配 access_token 时任何 POST 都会被放行（verifyOneBotAccessToken 直接 return true）
+            logger.warn(formatCompact({
+                endpoint: this.#options.config.name,
+                mode: 'webhook',
+                ok: false,
+                error: 'missing access_token',
+            }));
+        }
         this.#setupRoutes();
         logger.info(formatCompact({
             op: 'listen',
@@ -38,14 +49,16 @@ export class OneBot12WebhookEndpoint {
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
-        const apiUrl = this.#options.config.api_url;
-        if (!apiUrl) {
-            throw new Error('OneBot12 connection:webhook requires api_url for outbound send');
-        }
-        const message = formatOutboundSegments(payload);
+        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_upload_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        const message = formatOutboundSegments(materialized);
         const params = buildSendMessageParams(target, message);
-        const resp = await this.#callAction({ url: apiUrl, access_token: this.#options.config.access_token }, 'send_message', params);
-        const data = resp.data;
+        const data = await this.callApi('send_message', params);
         const messageId = data?.message_id ?? '';
         logger.debug(formatCompact({
             op: 'onebot12_send',
@@ -55,6 +68,15 @@ export class OneBot12WebhookEndpoint {
         }));
         return messageId;
     }
+    /** Public API for management surface / callers；webhook 模式走 api_url。 */
+    async callApi(action, params = {}) {
+        const apiUrl = this.#options.config.api_url;
+        if (!apiUrl) {
+            throw new Error('OneBot12 connection:webhook requires api_url for outbound api');
+        }
+        const resp = await this.#callAction({ url: apiUrl, access_token: this.#options.config.access_token }, action, params);
+        return resp.data;
+    }
     admit(ev) {
         if (!this.#open || !isMessageEvent(ev))
             return;