@zhin.js/adapter-onebot12 1.1.18 → 1.1.19

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @zhin.js/adapter-onebot12
 
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+- Updated dependencies [2c3610a]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/host-http@1.1.12
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/skill@1.1.11
+
 ## 1.1.18
 
 ### Patch Changes

package/README.md

@@ -2,13 +2,15 @@
 
 Zhin.js [OneBot 12](https://12.onebot.dev/) 适配器（Plugin Runtime）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **HTTP Webhook** 与 **反向 WS**（经 `httpHostToken` 注册路由）。
 
+账号由 `Onebot12Adapter` 管理。Endpoint 直接继承实际 `OneBotV12Client`，保留原生方法与事件；框架生命周期、规范入站与发送经 `endpointSpec` 和 AdapterIndex 接入，不占用 Client 的原生 `start` / `stop` / `send` 方法。
+
 ## 功能特性
 
 - [OneBot 12 标准](https://12.onebot.dev/) 兼容（事件 + 动作）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连 OneBot 实现的 WS 服务器
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `Endpoint.emit(...)`；出站 `send({ conversation, payload })`
+- 入站经 `endpointSpec.events`；出站 `send({ conversation, payload })`
 
 ## 安装
 
@@ -19,19 +21,26 @@ pnpm add @zhin.js/adapter-onebot12
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/onebot12/index.ts`（`defineAdapter`）
-- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/core` — `endpointSpec.events` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 
 `AdapterIndex` 会把实例默认值与 `endpoints[]` 的逐项覆盖合并；协议层只接收一个已经展开的 endpoint 配置，不再读取嵌套 endpoint 或从进程环境推断身份。Webhook 配置必须同时提供 `path` 与 `api_url`，从而在启动前建立完整的双向能力。
 
-入站：`gateway.receive({ conversation: ConversationRef, message: { conversation, id }, content, sender, metadata })`  
+入站：`endpoint[endpointSpec].events.emit('message.receive', { conversation: ConversationRef, message: { conversation, id }, content, sender, metadata })`
+
 出站：`send({ conversation, payload })` → WS `send_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
-每个 Endpoint 的 `$client` 是 `@imhelper/onebot-v12` 的 `OneBotV12Client`。业务代码直接调用
+Endpoint 直接继承 `@imhelper/onebot-v12` 的 `OneBotV12Client`；当前操作的 `$client` 就是该实际实例。业务代码直接调用
 `$client.call(action, params)` 和 Client 的公开平台能力；Webhook 使用 Client 的
 `acceptHttp()`，双工 WS 则由 Endpoint 分离 `echo` 响应后把事件交给 `ingest()`。
 
+## 操作生命周期
+
+每个实际 Client 的请求关联、定时器与取消由同一个实例级 RPC 模块持有。停止、删除或替换账号时，先取消该实例的等待，再关闭连接；已提交但未收到结果的请求保持“结果未知”，不会重试。框架发送与内容读取还绑定各自的操作信号，取消单个操作不影响其他操作或账号。原生 SDK 方法和事件重载保持不变。
+
+图片上传和发送使用同一操作信号，取消上传后不会继续提交 `send_message`；WS、反向 WS 与 HTTP 出站遵循相同规则。好友、群与成员 ID 保持协议字符串，不转为 JavaScript 数字。
+
 ## 前置条件
 
 1. 启动兼容 OneBot 12 的实现，并确认其支持所选 WS 或 Webhook 模式。
@@ -51,6 +60,8 @@ onebot12:
   heartbeat_interval: 30000
   endpoints:
     - id: ob12-bot
+      platform: qq
+      userId: "123456789"
       url: "ws://127.0.0.1:6700"
       access_token: "${ONEBOT12_ACCESS_TOKEN}"
 ```
@@ -70,6 +81,14 @@ onebot12:
 - **Bearer**：`Authorization: Bearer <access_token>`
 - 正向 WS 在 Upgrade 时附带请求头，并在 URL query 写入 `access_token`
 
+## 账号选择
+
+每个 Endpoint 必填 `platform` 和 `userId`，精确对应 OneBot12 的 `self.platform` 和 `self.user_id`；`id` 只是本地账号名称。已有配置需明确补齐这两个字段，不能从名称或服务端首个 bot 推断。修改 selector 使用显式账号替换，新身份先停用，旧历史保留。
+
+WS、反向 WS 和 Webhook 都在进入原生 SDK 前过滤其他 bot 的事件。每个动作（包括 `$client.call()` 和 SDK 便捷操作）都在顶层携带固定 `self: { platform, user_id }`；调用参数中的 `params.self` 不会改变该目标。服务级无 `self` 帧只处理原有连接/echo 语义，不归入某个 bot 的聊天 Session。
+
+只读身份核验从 `get_status.bots` 中精确选择目标，再以相同 `self` 调用 `get_self_info`。同一服务可以承载多个 bot；缺少所选 bot 或无法核验时要求显式替换，接口/HTTP 失败仍是失败，不自动换账号。
+
 ## 动作与事件
 
 - 事件：`type`（meta/message/notice/request）、`detail_type`、`message` 等，见 [事件](https://12.onebot.dev/connect/data-protocol/event/)。
@@ -90,7 +109,7 @@ onebot12:
 启动后打开 Console 的「OneBot 12」页（地址 `/onebot12`），可以：
 
 - 查看运行中的连接、点「测试连接」做连通性诊断；
-- 增删 `plugins.onebot12.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
+- 经所属 Adapter 增删持久化账号、启停单个 Endpoint；凭据由 Host 加密仓储保存，不改启动 YAML 或 `.env`，不重启进程；
 - 如果适配器要求登录，页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办；
 
 读取需要 `onebot12:read`，写操作需要 `onebot12:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `onebot12 endpoint add`。

package/adapters/onebot12/index.js

@@ -3,12 +3,8 @@
  * Convention entry: discover `adapters/onebot12/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-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";
+import { Onebot12Adapter } from "../../lib/adapter.js";
+import {} from "../../lib/protocol.js";
 export { OneBot12WebhookEndpoint } from "../../lib/webhook.js";
 export { OneBot12WsEndpoint } from "../../lib/ws-endpoint.js";
 export { OneBot12WssEndpoint } from "../../lib/wss-endpoint.js";
@@ -21,30 +17,5 @@ export default defineAdapter({
         outboundMedia: ['url', 'path', 'base64', 'upload'],
         interactive: 'text',
     },
-    create(context) {
-        const config = resolveOneBot12Config(context.config);
-        // 注册到插件运行时状态（onebot12 endpoint list 的"运行中"数据源）
-        context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
-            id: config.id,
-            mode: config.connection,
-        });
-        if (config.connection === 'webhook') {
-            return new OneBot12WebhookEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        if (config.connection === 'wss') {
-            return new OneBot12WssEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        return new OneBot12WsEndpoint({
-            id: context.id,
-            config,
-        });
-    },
+    createAdapter: context => new Onebot12Adapter(context),
 });

package/adapters/onebot12/index.ts

@@ -2,15 +2,10 @@
  * Convention entry: discover `adapters/onebot12/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
-import { OneBot12WebhookEndpoint } from '../../src/webhook.js';
-import { OneBot12WsEndpoint } from '../../src/ws-endpoint.js';
-import { OneBot12WssEndpoint } from '../../src/wss-endpoint.js';
+import { Onebot12Adapter } from '../../src/adapter.js';
 import {
-  resolveOneBot12Config,
   type OneBot12EndpointConfig,
 } 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';
@@ -20,12 +15,6 @@ export { OneBot12WssEndpoint } from '../../src/wss-endpoint.js';
 export type { OneBot12WssEndpointOptions } from '../../src/wss-endpoint.js';
 export type { OneBot12WsSocket, OneBot12WsCreateOptions } from '../../src/ws-types.js';
 
-declare module '@zhin.js/core' {
-  interface AdapterEndpoints {
-    onebot12: import('../../src/ws-endpoint.js').OneBot12WsEndpoint;
-  }
-}
-
 export default defineAdapter<OneBot12EndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
@@ -35,30 +24,5 @@ export default defineAdapter<OneBot12EndpointConfig>({
     outboundMedia: ['url', 'path', 'base64', 'upload'],
     interactive: 'text',
   },
-  create(context) {
-    const config = resolveOneBot12Config(context.config);
-    // 注册到插件运行时状态（onebot12 endpoint list 的"运行中"数据源）
-    context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
-      id: config.id,
-      mode: config.connection,
-    });
-    if (config.connection === 'webhook') {
-      return new OneBot12WebhookEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    if (config.connection === 'wss') {
-      return new OneBot12WssEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    return new OneBot12WsEndpoint({
-      id: context.id,
-      config,
-    });
-  },
+  createAdapter: context => new Onebot12Adapter(context),
 });

package/commands/onebot12/endpoint/definition.js

@@ -5,17 +5,17 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { onebot12RuntimeStateToken } from "../../../lib/onebot12-runtime-state.js";
 export const onebot12EndpointCommands = createEndpointCommands({
     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)" } },
         { 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)}`;

package/commands/onebot12/endpoint/definition.ts

@@ -4,18 +4,18 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { onebot12RuntimeStateToken } from '../../../src/onebot12-runtime-state.js';
 
 export const onebot12EndpointCommands = createEndpointCommands({
   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)" } },
     { 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)}`;

package/lib/adapter.d.ts

@@ -0,0 +1,21 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { type OneBot12EndpointConfig } from './protocol.js';
+import { OneBot12WsEndpoint } from './ws-endpoint.js';
+import { OneBot12WssEndpoint } from './wss-endpoint.js';
+import { OneBot12WebhookEndpoint } from './webhook.js';
+import type { Onebot12ClientEventMap } from './client.js';
+export declare class Onebot12Adapter extends Adapter<OneBot12WsEndpoint | OneBot12WssEndpoint | OneBot12WebhookEndpoint, OneBot12EndpointConfig, Onebot12ClientEventMap> {
+    #private;
+    constructor(context: AdapterContext<OneBot12EndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    get configurationIdentityProbeFields(): readonly string[];
+    get configurationUpdateFields(): readonly string[];
+    protected validateConfiguration(config: OneBot12EndpointConfig): void;
+    protected identifyConfiguration(input: OneBot12EndpointConfig, signal: AbortSignal): Promise<string | undefined>;
+    protected createEndpoint(input: OneBot12EndpointConfig, execution: EndpointCreationContext): OneBot12WsEndpoint | OneBot12WssEndpoint | OneBot12WebhookEndpoint;
+}
+declare module '@zhin.js/feature-kit' {
+    interface AdapterRegistry {
+        readonly onebot12: Onebot12Adapter;
+    }
+}

package/lib/adapter.js

@@ -0,0 +1,34 @@
+import { Adapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { resolveOneBot12Config } 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';
+export class Onebot12Adapter extends Adapter {
+    #context;
+    constructor(context) { super(); this.#context = context; }
+    get configurationIdentityFields() { return ['id', 'platform', 'userId']; }
+    get configurationIdentityProbeFields() { return ['connection', 'access_token', 'url', 'api_url']; }
+    get configurationUpdateFields() {
+        return ['connection', 'url', 'path', 'api_url', 'access_token', 'reconnect_interval', 'heartbeat_interval'];
+    }
+    validateConfiguration(config) { resolveOneBot12Config(config); }
+    async identifyConfiguration(input, signal) {
+        const config = resolveOneBot12Config(input);
+        if (config.connection === 'ws')
+            return probeOnebot12Identity(config, signal);
+        if (config.connection === 'webhook')
+            return probeOnebot12HttpIdentity(config, signal);
+        return undefined;
+    }
+    createEndpoint(input, execution) {
+        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 });
+    }
+}

package/lib/client.d.ts

@@ -1,3 +1,4 @@
+export { readOnebot12Response } from './response.js';
 import { OneBotV12Client, type OneBotV12Event as ImHelperOneBot12Event, type OneBotV12Response } from '@imhelper/onebot-v12';
 import { type EventMap, type ImHelperEventMap } from 'imhelper';
 import { type ClientEventPayloads } from 'zhin.js/adapter';
@@ -6,15 +7,12 @@ export { OneBotV12Client as Onebot12Client } from '@imhelper/onebot-v12';
 export type Onebot12ApiCall = (action: string, params?: Record<string, unknown>) => Promise<OneBotV12Response>;
 type Onebot12ClientEvents = ImHelperEventMap<string, ImHelperOneBot12Event, EventMap<string>>;
 export type Onebot12ClientEventMap = ClientEventPayloads<Onebot12ClientEvents>;
-export declare function createOnebot12EndpointClient(config: ResolvedOneBot12Config, request: Onebot12ApiCall): OneBotV12Client;
-export declare function callOnebot12Client<T = unknown>(client: OneBotV12Client, action: string, params?: Record<string, unknown>): Promise<T | undefined>;
-export declare function forwardOnebot12ClientEvents(client: OneBotV12Client, receive: (name: string, payload: unknown) => void): () => void;
-declare module '@zhin.js/feature-kit' {
-    interface AdapterClientRegistry {
-        readonly onebot12: {
-            readonly client: OneBotV12Client;
-            readonly events: Onebot12ClientEventMap;
-        };
-    }
+export declare function onebot12ClientOptions(config: ResolvedOneBot12Config, request: Onebot12ApiCall): ConstructorParameters<typeof OneBotV12Client>[0];
+export interface Onebot12ClientRequest {
+    readonly client: OneBotV12Client;
+    readonly action: string;
+    readonly params?: Record<string, unknown>;
 }
-export declare const onebot12Client: import("@zhin.js/adapter").EndpointClientToken<OneBotV12Client, ClientEventPayloads<Onebot12ClientEvents>>;
+/** Native methods retain ProtocolError; framework ports preserve the underlying delivery evidence. */
+export declare function callOnebot12Client<T = unknown>(request: Onebot12ClientRequest): Promise<T | undefined>;
+export declare function forwardOnebot12ClientEvents(client: OneBotV12Client, receive: (name: string, payload: unknown) => void): () => void;

package/lib/client.js

@@ -1,27 +1,38 @@
-import { OneBotV12Client, } from '@imhelper/onebot-v12';
-import { EventFactory } from 'imhelper';
-import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+import { readOnebot12Response } from './response.js';
+export { readOnebot12Response } from './response.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { ProtocolError, EventFactory } from 'imhelper';
+import { forwardEndpointClientEvents, } from 'zhin.js/adapter';
 export { OneBotV12Client as Onebot12Client } from '@imhelper/onebot-v12';
-export function createOnebot12EndpointClient(config, request) {
+export function onebot12ClientOptions(config, request) {
     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(client, action, params) {
-    const response = await client.call(action, params);
-    if (response.status !== 'ok') {
-        throw new Error(`OneBot 12 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`);
+/** Native methods retain ProtocolError; framework ports preserve the underlying delivery evidence. */
+export async function callOnebot12Client(request) {
+    try {
+        return readOnebot12Response(await request.client.call(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(),
@@ -30,4 +41,3 @@ const onebot12ClientEventNames = Object.freeze([
 export function forwardOnebot12ClientEvents(client, receive) {
     return forwardEndpointClientEvents(client, onebot12ClientEventNames, receive);
 }
-export const onebot12Client = defineEndpointClient('onebot12');

package/lib/console-spec.js

@@ -2,6 +2,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/lib/console.d.ts

@@ -5,4 +5,4 @@
  */
 import { type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-export declare function createOnebot12ConsoleRpc(resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;
+export declare function createOnebot12ConsoleRpc(_resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -4,13 +4,10 @@
  * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
  */
 import { createAdapterConsoleRpc } from 'zhin.js/adapter';
-import { onebot12RuntimeStateToken } from './onebot12-runtime-state.js';
 import { onebot12ConsoleSpec } from './console-spec.js';
-export function createOnebot12ConsoleRpc(resources, getConfig) {
-    const state = resources.use(onebot12RuntimeStateToken);
+export function createOnebot12ConsoleRpc(_resources, getConfig) {
     return createAdapterConsoleRpc({
         ...onebot12ConsoleSpec,
-        running: () => state.endpoints.values(),
         getConfig,
-    }, resources);
+    });
 }

package/lib/content-port.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointContentPort } from 'zhin.js/adapter';
-type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+import type { EndpointContentPort, PendingRpcRequest } from 'zhin.js/adapter';
+type CallApi = (request: PendingRpcRequest) => Promise<unknown>;
 export declare function createOneBot12ContentPort(callApi: CallApi): EndpointContentPort;
 export {};

package/lib/content-port.js

@@ -11,7 +11,7 @@ export function createOneBot12ContentPort(callApi) {
                         ? Object.freeze({ status: 'unsupported', code: 'onebot12_opaque_media' })
                         : Object.freeze({ status: 'resolved', reference, value: reference.media });
                 }
-                const row = await callApi('get_message', { message_id: reference.message.id });
+                const row = await callApi({ action: 'get_message', params: { message_id: reference.message.id }, signal: context.signal });
                 context.signal.throwIfAborted();
                 const message = (row.message && typeof row.message === 'object' ? row.message : row);
                 const segments = normalizeSegments(message.message ?? message.content);

package/lib/endpoint-management.d.ts

@@ -3,14 +3,14 @@
  * 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 { EndpointManagement } from 'zhin.js/adapter';
+import { type EndpointManagement, 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 declare function createOneBot12EndpointManagement(endpoint: OneBot12ManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -1,30 +1,30 @@
 export function createOneBot12EndpointManagement(endpoint) {
     return Object.freeze({
-        async listFriends() {
-            const data = await endpoint.callApi('get_friend_list');
+        async listFriends(request = {}) {
+            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() {
-            const data = await endpoint.callApi('get_group_list');
+        async listGroups(request = {}) {
+            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) {
-            const data = await endpoint.callApi('get_group_member_list', {
-                group_id: groupId,
-            });
+        async listGroupMembers({ groupId, signal }) {
+            const data = await endpoint.callApi({ action: 'get_group_member_list', signal, params: {
+                    group_id: groupId,
+                } });
             return toArray(data);
         },
     });
@@ -37,11 +37,11 @@ function asRecord(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;
+/** Platform IDs are addresses, including nonnumeric IDs and integers beyond Number precision. */
+function readOpaqueId(value, label) {
+    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/lib/identity.d.ts

@@ -0,0 +1,4 @@
+import { type OneBot12WebhookConfig, type OneBot12WsConfig } from './protocol.js';
+/** Separate read-only connection: never changes credentials or state of the running Endpoint. */
+export declare function probeOnebot12Identity(config: OneBot12WsConfig, signal: AbortSignal): Promise<string | undefined>;
+export declare function probeOnebot12HttpIdentity(config: OneBot12WebhookConfig, signal: AbortSignal): Promise<string | undefined>;

package/lib/identity.js

@@ -0,0 +1,53 @@
+import WebSocket from 'ws';
+import { buildWsConnectOptions, callOneBot12Action } 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, signal) {
+    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 = () => 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((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, signal) {
+    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 });
+}
+async function identifySelectedBot({ selected, query, signal }) {
+    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) => {
+        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])}`;
+}