@zhin.js/adapter-onebot12 1.1.18 → 1.1.20

package/schema.json

@@ -52,7 +52,7 @@
     "endpoints": {
       "type": "array",
       "minItems": 1,
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "description": "多账号：每项明确选择 platform/userId，id 为本地账号名称，其余连接字段覆盖实例默认值",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -121,15 +121,27 @@
           "id": {
             "type": "string",
             "description": "OneBot12 bot name"
+          },
+          "platform": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Selected OneBot12 bot platform"
+          },
+          "userId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Selected OneBot12 bot user ID"
           }
         },
         "required": [
-          "id"
+          "id",
+          "platform",
+          "userId"
         ]
       },
       "x-i18n": {
         "en": {
-          "description": "Multiple accounts: mount multiple endpoints in one plugin instance. Each entry uses the top-level fields; id is required and other fields override defaults."
+          "description": "Each endpoint explicitly selects platform and userId. id is the local account name; other connection fields override instance defaults."
         }
       }
     },

package/src/adapter.ts

@@ -0,0 +1,36 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { resolveOneBot12Config, type OneBot12EndpointConfig } from './protocol.js';
+import { OneBot12WsEndpoint } from './ws-endpoint.js';
+import { OneBot12WssEndpoint } from './wss-endpoint.js';
+import { OneBot12WebhookEndpoint } from './webhook.js';
+import { probeOnebot12Identity, probeOnebot12HttpIdentity } from './identity.js';
+import type { Onebot12ClientEventMap } from './client.js';
+
+export class Onebot12Adapter extends Adapter<OneBot12WsEndpoint | OneBot12WssEndpoint | OneBot12WebhookEndpoint, OneBot12EndpointConfig, Onebot12ClientEventMap> {
+  readonly #context: AdapterContext<OneBot12EndpointConfig>;
+  constructor(context: AdapterContext<OneBot12EndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id', 'platform', 'userId']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['connection', 'access_token', 'url', 'api_url']; }
+  override get configurationUpdateFields(): readonly string[] {
+    return ['connection', 'url', 'path', 'api_url', 'access_token', 'reconnect_interval', 'heartbeat_interval'];
+  }
+  protected override validateConfiguration(config: OneBot12EndpointConfig): void { resolveOneBot12Config(config); }
+  protected override async identifyConfiguration(input: OneBot12EndpointConfig, signal: AbortSignal): Promise<string | undefined> {
+    const config = resolveOneBot12Config(input);
+    if (config.connection === 'ws') return probeOnebot12Identity(config, signal);
+    if (config.connection === 'webhook') return probeOnebot12HttpIdentity(config, signal);
+    return undefined;
+  }
+  protected createEndpoint(input: OneBot12EndpointConfig, execution: EndpointCreationContext): OneBot12WsEndpoint | OneBot12WssEndpoint | OneBot12WebhookEndpoint {
+    const config = resolveOneBot12Config(input);
+    const id = execution.canonicalId;
+    if (config.connection === 'webhook') return new OneBot12WebhookEndpoint({ id, signal: execution.signal, http: this.#context.use(httpHostToken), config });
+    if (config.connection === 'wss') return new OneBot12WssEndpoint({ id, signal: execution.signal, http: this.#context.use(httpHostToken), config });
+    return new OneBot12WsEndpoint({ id, signal: execution.signal, config });
+  }
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly onebot12: Onebot12Adapter; }
+}

package/src/client.ts

@@ -1,11 +1,13 @@
+import { readOnebot12Response } from './response.js';
+export { readOnebot12Response } from './response.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import {
   OneBotV12Client,
   type OneBotV12Event as ImHelperOneBot12Event,
   type OneBotV12Response,
 } from '@imhelper/onebot-v12';
-import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import { ProtocolError, EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
 import {
-  defineEndpointClient,
   forwardEndpointClientEvents,
   type ClientEventPayloads,
 } from 'zhin.js/adapter';
@@ -25,38 +27,44 @@ type Onebot12ClientEvents = ImHelperEventMap<
 >;
 export type Onebot12ClientEventMap = ClientEventPayloads<Onebot12ClientEvents>;
 
-export function createOnebot12EndpointClient(
+export function onebot12ClientOptions(
   config: ResolvedOneBot12Config,
   request: Onebot12ApiCall,
-): OneBotV12Client {
+): ConstructorParameters<typeof OneBotV12Client>[0] {
   const baseUrl = config.connection === 'ws'
     ? config.url.replace(/^ws(s?):/, 'http$1:')
     : config.connection === 'webhook'
       ? config.api_url
       : 'http://localhost';
-  return new OneBotV12Client({
+  return {
     baseUrl,
-    selfId: config.id,
+    platform: config.platform,
+    selfId: config.userId,
     accessToken: config.access_token,
     receiveMode: 'manual',
     call: request,
-  });
+  };
 }
 
-export async function callOnebot12Client<T = unknown>(
-  client: OneBotV12Client,
-  action: string,
-  params?: Record<string, unknown>,
-): Promise<T | undefined> {
-  const response: OneBotV12Response<T> = await client.call<T>(action, params);
-  if (response.status !== 'ok') {
-    throw new Error(
-      `OneBot 12 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`,
-    );
+export interface Onebot12ClientRequest {
+  readonly client: OneBotV12Client;
+  readonly action: string;
+  readonly params?: Record<string, unknown>;
+}
+/** Native methods retain ProtocolError; framework ports preserve the underlying delivery evidence. */
+export async function callOnebot12Client<T = unknown>(request: Onebot12ClientRequest): Promise<T | undefined> {
+  try {
+    return readOnebot12Response<T>(await request.client.call<T>(request.action, request.params));
+  } catch (error) {
+    if (error instanceof ProtocolError) {
+      if (error.cause instanceof EndpointDeliveryError) throw error.cause;
+      if (error.response !== undefined) readOnebot12Response(error.response);
+    }
+    throw error;
   }
-  return response.data;
 }
 
+
 const onebot12ClientEventNames = Object.freeze([
   ...EventFactory.getSupportedEventTypes<string>(),
   'event',
@@ -68,14 +76,3 @@ export function forwardOnebot12ClientEvents(
 ): () => void {
   return forwardEndpointClientEvents(client, onebot12ClientEventNames, receive);
 }
-
-declare module '@zhin.js/feature-kit' {
-  interface AdapterClientRegistry {
-    readonly onebot12: {
-      readonly client: OneBotV12Client;
-      readonly events: Onebot12ClientEventMap;
-    };
-  }
-}
-
-export const onebot12Client = defineEndpointClient<OneBotV12Client, Onebot12ClientEventMap>('onebot12');

package/src/console-spec.ts

@@ -7,6 +7,8 @@ export const onebot12ConsoleSpec = {
   adapterKey: 'onebot12',
   adapterDisplayName: 'OneBot 12',
   fields: [
+    { key: 'platform', required: true, description: 'Selected OneBot12 bot platform' },
+    { key: 'userId', required: true, description: 'Selected OneBot12 bot user ID' },
     { key: 'url', description: 'OneBot 实现 WebSocket URL（connection: ws 必填）', descriptionI18n: { en: 'OneBot WebSocket URL (required for connection: ws)' } },
     { key: 'path', description: 'HTTP/WS 路径（webhook / reverse-wss）', descriptionI18n: { en: 'HTTP/WS path (webhook / reverse-wss)' } },
     { key: 'api_url', description: 'HTTP action 端点（connection: webhook 出站必填）', descriptionI18n: { en: 'HTTP action endpoint (required for outbound connection: webhook)' } },

package/src/console.ts

@@ -5,17 +5,14 @@
  */
 import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-import { onebot12RuntimeStateToken } from './onebot12-runtime-state.js';
 import { onebot12ConsoleSpec } from './console-spec.js';
 
 export function createOnebot12ConsoleRpc(
-  resources: AdapterConsoleResources,
+  _resources: AdapterConsoleResources,
   getConfig: () => unknown,
 ): PluginConsoleRpc {
-  const state = resources.use(onebot12RuntimeStateToken);
   return createAdapterConsoleRpc({
     ...onebot12ConsoleSpec,
-    running: () => state.endpoints.values(),
     getConfig,
-  }, resources);
+  });
 }

package/src/content-port.ts

@@ -1,7 +1,7 @@
-import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { EndpointContentPort, EndpointContentResolveContext, PendingRpcRequest } from 'zhin.js/adapter';
 import type { ConversationMessage, ConversationReference } from '@zhin.js/im-contract';
 
-type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+type CallApi = (request: PendingRpcRequest) => Promise<unknown>;
 
 export function createOneBot12ContentPort(callApi: CallApi): EndpointContentPort {
   return Object.freeze({
@@ -16,7 +16,7 @@ export function createOneBot12ContentPort(callApi: CallApi): EndpointContentPort
             ? Object.freeze({ status: 'unsupported' as const, code: 'onebot12_opaque_media' })
             : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
         }
-        const row = await callApi('get_message', { message_id: reference.message.id }) as Record<string, unknown>;
+        const row = await callApi({ action: 'get_message', params: { message_id: reference.message.id }, signal: context.signal }) as Record<string, unknown>;
         context.signal.throwIfAborted();
         const message = (row.message && typeof row.message === 'object' ? row.message : row) as Record<string, unknown>;
         const segments = normalizeSegments(message.message ?? message.content);

package/src/endpoint-management.ts

@@ -3,51 +3,54 @@
  * 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 账号与会话 ID 始终保留为不透明字符串：
+ * - friend → {user_id:string, nickname: user_name, remark: user_displayname ?? ''}
+ * - group → {group_id:string, name: group_name ?? name}
  * - 群成员列表保持 OB12 原生形状，仅保证数组
  */
-import type {
-  EndpointFriend,
-  EndpointGroup,
-  EndpointManagement,
+import {
+  type EndpointFriend,
+  type EndpointGroup,
+  type EndpointManagement,
+  type EndpointManagementRequest,
+  type EndpointGroupRequest,
+  type PendingRpcRequest,
 } from 'zhin.js/adapter';
 
 /** 管理面只依赖 endpoint 的 callApi（ws/wss/webhook 三种传输各自实现）。 */
 export interface OneBot12ManagementCaller {
-  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+  callApi(request: PendingRpcRequest): Promise<unknown>;
 }
 
 export function createOneBot12EndpointManagement(
   endpoint: OneBot12ManagementCaller,
 ): EndpointManagement {
   return Object.freeze<EndpointManagement>({
-    async listFriends(): Promise<readonly EndpointFriend[]> {
-      const data = await endpoint.callApi('get_friend_list');
+    async listFriends(request: EndpointManagementRequest = {}): Promise<readonly EndpointFriend[]> {
+      const data = await endpoint.callApi({ action: 'get_friend_list', signal: request.signal });
       return toArray(data).map((value) => {
         const friend = asRecord(value);
         return {
-          user_id: toNumberId(friend.user_id, 'user_id'),
+          user_id: readOpaqueId(friend.user_id, 'user_id'),
           nickname: String(friend.user_name ?? friend.nickname ?? ''),
           remark: String(friend.user_displayname ?? friend.remark ?? ''),
         };
       });
     },
-    async listGroups(): Promise<readonly EndpointGroup[]> {
-      const data = await endpoint.callApi('get_group_list');
+    async listGroups(request: EndpointManagementRequest = {}): Promise<readonly EndpointGroup[]> {
+      const data = await endpoint.callApi({ action: 'get_group_list', signal: request.signal });
       return toArray(data).map((value) => {
         const group = asRecord(value);
         return {
-          group_id: toNumberId(group.group_id, 'group_id'),
+          group_id: readOpaqueId(group.group_id, 'group_id'),
           name: String(group.group_name ?? group.name ?? ''),
         };
       });
     },
-    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
-      const data = await endpoint.callApi('get_group_member_list', {
+    async listGroupMembers({ groupId, signal }: EndpointGroupRequest): Promise<readonly unknown[]> {
+      const data = await endpoint.callApi({ action: 'get_group_member_list', signal, params: {
         group_id: groupId,
-      });
+      } });
       return toArray(data);
     },
   });
@@ -63,11 +66,9 @@ function toArray(value: unknown): readonly unknown[] {
   return Array.isArray(value) ? value : [];
 }
 
-/** OB12 id 是字符串；QQ 系实现均为数字串，统一收敛为数字。 */
-function toNumberId(value: unknown, label: string): number {
-  const n = Number(value);
-  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
-    throw new TypeError(`onebot12 ${label} 必须是数字: ${String(value)}`);
-  }
-  return n;
+/** Platform IDs are addresses, including nonnumeric IDs and integers beyond Number precision. */
+function readOpaqueId(value: unknown, label: string): string {
+  if (typeof value === 'string' && value.trim()) return value;
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return String(value);
+  throw new TypeError(`onebot12 ${label} must be an opaque string or safe integer platform ID`);
 }

package/src/identity.ts

@@ -0,0 +1,52 @@
+import WebSocket from 'ws';
+import { buildWsConnectOptions, callOneBot12Action, type OneBot12ActionResponse, type OneBot12WebhookConfig, type OneBot12WsConfig } from './protocol.js';
+import { createOneBot12Rpc } from './ws-transport.js';
+
+/** Separate read-only connection: never changes credentials or state of the running Endpoint. */
+export async function probeOnebot12Identity(config: OneBot12WsConfig, signal: AbortSignal): Promise<string | undefined> {
+  signal.throwIfAborted();
+  const { url, headers } = buildWsConnectOptions(config);
+  const socket = new WebSocket(url, { headers });
+  const rpc = createOneBot12Rpc({ endpointId: config.id, signal, socket: () => socket, self: { platform: config.platform, user_id: config.userId }, });
+  let rejectOpen: (error: unknown) => void = () => undefined;
+  const abort = () => { rejectOpen(signal.reason); rpc.disconnect(); socket.terminate(); };
+  signal.addEventListener('abort', abort, { once: true });
+  socket.on('message', data => rpc.receive(data, () => undefined));
+  socket.on('close', () => { rejectOpen(new Error('Identity connection closed')); rpc.disconnect(); });
+  try {
+    await new Promise<void>((resolve, reject) => { rejectOpen = reject; socket.once('open', resolve); socket.on('error', reject); });
+    signal.throwIfAborted();
+    const self = { platform: config.platform, user_id: config.userId };
+    return await identifySelectedBot({ selected: self, query: action => rpc.call({ action }), signal });
+  } finally {
+    signal.removeEventListener('abort', abort); rpc.dispose(); socket.terminate();
+  }
+}
+
+export async function probeOnebot12HttpIdentity(config: OneBot12WebhookConfig, signal: AbortSignal): Promise<string | undefined> {
+  const self = { platform: config.platform, user_id: config.userId };
+  return identifySelectedBot({ selected: self, query: action => callOneBot12Action({ url: config.api_url, access_token: config.access_token, signal, self, action }), signal });
+}
+
+interface OneBot12IdentityProbe {
+  readonly selected: Readonly<{ platform: string; user_id: string }>;
+  readonly query: (action: string) => Promise<OneBot12ActionResponse>;
+  readonly signal: AbortSignal;
+}
+async function identifySelectedBot({ selected, query, signal }: OneBot12IdentityProbe): Promise<string | undefined> {
+    const status = await query('get_status');
+    signal.throwIfAborted();
+    if (status.status !== 'ok' || status.retcode !== 0) throw new Error('OneBot12 identity status lookup failed');
+    const data = status.data;
+    if (!data || typeof data !== 'object' || !('bots' in data) || !Array.isArray(data.bots)) return undefined;
+    const match = data.bots.some((bot: unknown) => {
+      if (!bot || typeof bot !== 'object' || !('self' in bot) || !bot.self || typeof bot.self !== 'object') return false;
+      return 'platform' in bot.self && 'user_id' in bot.self && bot.self.platform === selected.platform && bot.self.user_id === selected.user_id;
+    });
+    if (!match) return undefined;
+    const account = await query('get_self_info');
+    signal.throwIfAborted();
+    if (account.status !== 'ok' || account.retcode !== 0) throw new Error('OneBot12 account identity lookup failed');
+    if (!account.data || typeof account.data !== 'object' || !('user_id' in account.data) || account.data.user_id !== selected.user_id) return undefined;
+    return `onebot12:${JSON.stringify([selected.platform, selected.user_id])}`;
+}

package/src/index.ts

@@ -21,6 +21,9 @@ export {
   type OneBot12EndpointConfig,
   type OneBot12Event,
   type OneBot12HttpOptions,
+  type OneBot12HttpRequest,
+  type OneBot12MediaUpload,
+  type OneBot12MediaSource,
   type OneBot12Segment,
   type OneBot12Self,
   type OneBot12WebhookConfig,
@@ -50,7 +53,6 @@ export type { OneBot12WsSocket, OneBot12WsCreateOptions } from './ws-types.js';
 export { verifyOneBotAccessToken } from './wss-auth.js';
 export {
   Onebot12Client,
-  onebot12Client,
   type Onebot12ClientEventMap,
 } from './client.js';
 
@@ -64,3 +66,4 @@ export type {
 } from '@imhelper/onebot-v12';
 export { ProtocolError } from '@imhelper/onebot-v12';
 export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';
+export { Onebot12Adapter } from './adapter.js';

package/src/protocol.ts

@@ -1,15 +1,18 @@
+import { readOnebot12Response } from './response.js';
 /**
  * OneBot 12 protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
-import { isMediaRef, type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef, type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('onebot12');
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface OneBot12EndpointConfig {
+  readonly platform: string;
+  readonly userId: string;
   readonly connection?: 'ws' | 'webhook' | 'wss';
   readonly id: string;
   readonly access_token?: string;
@@ -21,6 +24,8 @@ export interface OneBot12EndpointConfig {
 }
 
 export interface OneBot12ConfigBase {
+  readonly platform: string;
+  readonly userId: string;
   readonly context: 'onebot12';
   readonly id: string;
   readonly access_token?: string;
@@ -78,10 +83,10 @@ export interface OneBot12Segment {
 }
 
 export interface OneBot12ActionRequest {
+  readonly self: OneBot12Self;
   action: string;
   params: Record<string, unknown>;
   echo?: string;
-  self?: OneBot12Self;
 }
 
 export interface OneBot12ActionResponse {
@@ -93,6 +98,8 @@ export interface OneBot12ActionResponse {
 }
 
 export interface OneBot12HttpOptions {
+  readonly self: OneBot12Self;
+  readonly signal?: AbortSignal;
   readonly url: string;
   readonly access_token?: string;
 }
@@ -105,12 +112,14 @@ export interface OneBot12WireSegment {
 export function resolveOneBot12Config(config: OneBot12EndpointConfig): ResolvedOneBot12Config {
   const connection = config.connection ?? 'ws';
   const id = requiredEndpointField(config.id, 'id');
+  const platform = requiredEndpointField(config.platform, 'platform');
+  const userId = requiredEndpointField(config.userId, 'userId');
   const access_token = optionalEndpointField(config.access_token);
 
   if (connection === 'ws') {
     const url = requiredEndpointField(config.url, 'url');
     return {
-      context: 'onebot12',
+      context: 'onebot12', platform, userId,
       connection: 'ws',
       id,
       access_token,
@@ -124,7 +133,7 @@ export function resolveOneBot12Config(config: OneBot12EndpointConfig): ResolvedO
     const path = requiredEndpointField(config.path, 'path');
     const api_url = requiredEndpointField(config.api_url, 'api_url');
     return {
-      context: 'onebot12',
+      context: 'onebot12', platform, userId,
       connection: 'webhook',
       id,
       access_token,
@@ -136,7 +145,7 @@ export function resolveOneBot12Config(config: OneBot12EndpointConfig): ResolvedO
   if (connection === 'wss') {
     const path = requiredEndpointField(config.path, 'path');
     return {
-      context: 'onebot12',
+      context: 'onebot12', platform, userId,
       connection: 'wss',
       id,
       access_token,
@@ -150,7 +159,7 @@ export function resolveOneBot12Config(config: OneBot12EndpointConfig): ResolvedO
 
 function requiredEndpointField(
   value: unknown,
-  field: 'id' | 'url' | 'path' | 'api_url',
+  field: 'id' | 'url' | 'path' | 'api_url' | 'platform' | 'userId',
 ): string {
   const resolved = optionalEndpointField(value);
   if (!resolved) {
@@ -398,11 +407,12 @@ export type OneBot12CallAction = (
 ) => Promise<unknown>;
 
 /** upload_file 文件名：优先段 data.name/filename，URL/路径取 basename，再按 mime 给默认名。 */
-function oneBot12UploadName(
-  segmentType: string,
-  data: Record<string, unknown>,
-  media: MediaRef,
-): string {
+export interface OneBot12MediaSource {
+  readonly type: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly media: MediaRef;
+}
+function oneBot12UploadName({ type, data, media }: OneBot12MediaSource): string {
   const named = data.name ?? data.filename;
   if (typeof named === 'string' && named) return named;
   if (media.kind === 'url') {
@@ -418,16 +428,13 @@ function oneBot12UploadName(
     if (base) return base;
   }
   const ext = media.mime_type?.split('/')[1]?.split(';')[0];
-  return `${segmentType}.${ext || 'bin'}`;
+  return `${type}.${ext || 'bin'}`;
 }
 
 /** canonical MediaRef → OB12 `upload_file` 动作参数（spec: type url/path/data）。 */
-export function mediaRefToOneBot12UploadParams(
-  segmentType: string,
-  data: Record<string, unknown>,
-  media: MediaRef,
-): Record<string, unknown> | undefined {
-  const name = oneBot12UploadName(segmentType, data, media);
+export function mediaRefToOneBot12UploadParams(source: OneBot12MediaSource): Record<string, unknown> | undefined {
+  const { media } = source;
+  const name = oneBot12UploadName(source);
   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;
@@ -444,8 +451,7 @@ export function mediaRefToOneBot12UploadParams(
 
 async function uploadOneMediaSegment(
   item: unknown,
-  callAction: OneBot12CallAction,
-  onUploadFailed?: (error: unknown) => void,
+  request: OneBot12MediaUpload,
 ): Promise<unknown> {
   if (!item || typeof item !== 'object' || Array.isArray(item)) return item;
   const segment = item as OneBot12WireSegment;
@@ -460,17 +466,18 @@ async function uploadOneMediaSegment(
   if (media.kind === 'file') {
     return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: media.value } };
   }
-  const params = mediaRefToOneBot12UploadParams(segment.type, data, media);
+  const params = mediaRefToOneBot12UploadParams({ type: segment.type, data, media });
   if (!params) return item;
   try {
-    const result = await callAction('upload_file', params) as { file_id?: unknown } | undefined;
+    const result = await request.callAction('upload_file', params) as { file_id?: unknown } | undefined;
     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) {
+    if (request.signal?.aborted) throw error;
     // 上传失败降级：保留原段，由 formatOutboundSegments 走扩展字段（url/data/path）
-    onUploadFailed?.(error);
+    request.onUploadFailed?.(error);
     return item;
   }
 }
@@ -481,15 +488,17 @@ async function uploadOneMediaSegment(
  * {@link formatOutboundSegments} 编码；kind=file 的 MediaRef 直接按 file_id 复投。
  * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
  */
-export async function uploadOneBot12MediaSegments(
-  payload: unknown,
-  callAction: OneBot12CallAction,
-  onUploadFailed?: (error: unknown) => void,
-): Promise<unknown> {
-  if (Array.isArray(payload)) {
-    return Promise.all(payload.map((item) => uploadOneMediaSegment(item, callAction, onUploadFailed)));
+export interface OneBot12MediaUpload {
+  readonly payload: unknown;
+  readonly callAction: OneBot12CallAction;
+  readonly signal?: AbortSignal;
+  readonly onUploadFailed?: (error: unknown) => void;
+}
+export async function uploadOneBot12MediaSegments(request: OneBot12MediaUpload): Promise<unknown> {
+  if (Array.isArray(request.payload)) {
+    return Promise.all(request.payload.map(item => uploadOneMediaSegment(item, request)));
   }
-  return uploadOneMediaSegment(payload, callAction, onUploadFailed);
+  return uploadOneMediaSegment(request.payload, request);
 }
 
 /**
@@ -519,40 +528,34 @@ export function buildSendMessageParams(
  * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。
  * 供 webhook 出站与纯协议测试使用；WS 路径走 WebSocket echo 请求。
  */
-export async function callOneBot12Action(
-  options: OneBot12HttpOptions,
-  action: string,
-  params: Record<string, unknown> = {},
-  echo?: string,
-): Promise<OneBot12ActionResponse> {
+export interface OneBot12HttpRequest extends OneBot12HttpOptions {
+  readonly action: string;
+  readonly params?: Record<string, unknown>;
+  readonly echo?: string;
+}
+/** HTTP owns submission evidence and cancellation for both SDK and framework callers. */
+export async function callOneBot12Action(request: OneBot12HttpRequest): Promise<OneBot12ActionResponse> {
+  if (request.signal?.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation cancelled', 'not_sent');
   const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-  if (options.access_token) {
-    headers.Authorization = `Bearer ${options.access_token}`;
-  }
-  const body: OneBot12ActionRequest = { action, params };
-  if (echo) body.echo = echo;
-
-  const res = await fetch(options.url, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify(body),
-    signal: AbortSignal.timeout(30_000),
-  });
-
-  const text = await res.text();
-  if (res.status === 401) throw new Error(`OneBot12 鉴权失败: ${text}`);
-  if (res.status !== 200) throw new Error(`OneBot12 HTTP ${res.status}: ${text}`);
-
-  let data: OneBot12ActionResponse;
+  if (request.access_token) headers.Authorization = `Bearer ${request.access_token}`;
+  const body: OneBot12ActionRequest = { action: request.action, params: request.params ?? {}, self: request.self,
+    ...(request.echo !== undefined ? { echo: request.echo } : {}) };
   try {
-    data = JSON.parse(text) as OneBot12ActionResponse;
-  } catch {
-    throw new Error(`OneBot12 无效响应: ${text.slice(0, 200)}`);
-  }
-  if (data.status === 'failed' && data.retcode !== 0) {
-    throw new Error(`OneBot12 动作失败 retcode=${data.retcode}: ${data.message}`);
+    const response = await fetch(request.url, { method: 'POST', headers, body: JSON.stringify(body),
+      signal: request.signal ? AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) });
+    const text = await response.text();
+    if (response.status === 401) throw new EndpointDeliveryError('platform_rejected', `OneBot12 鉴权失败: ${text}`, 'rejected');
+    if (response.status !== 200) throw new EndpointDeliveryError('endpoint_http_failed', `OneBot12 HTTP ${response.status}: ${text}`, 'unknown');
+    let data: OneBot12ActionResponse;
+    try { data = JSON.parse(text) as OneBot12ActionResponse; }
+    catch { throw new EndpointDeliveryError('delivery_unconfirmed', `OneBot12 无效响应: ${text.slice(0, 200)}`, 'unknown'); }
+    readOnebot12Response(data);
+    return data;
+  } catch (cause) {
+    if (cause instanceof EndpointDeliveryError) throw cause;
+    throw new EndpointDeliveryError(request.signal?.aborted ? 'endpoint_inactive' : 'endpoint_transport_failed',
+      cause instanceof Error ? cause.message : String(cause), 'unknown', { cause });
   }
-  return data;
 }
 
 /** Build WS connect URL + headers (access_token via Bearer + query). */
@@ -573,3 +576,9 @@ export function buildWsConnectOptions(config: OneBot12WsConfig): {
   safeUrl.searchParams.delete('access_token');
   return { url: connectUrl, headers, safeUrl: safeUrl.toString() };
 }
+
+/** Route only the explicitly selected bot; service-wide frames carry no account authority. */
+export function matchesOneBot12Self(config: Pick<OneBot12ConfigBase, 'platform' | 'userId'>,
+  event: OneBot12Event): event is OneBot12Event & { readonly self: OneBot12Self } {
+  return event.self?.platform === config.platform && event.self?.user_id === config.userId;
+}