@zhin.js/adapter-onebot12 1.0.1 → 1.1.2

package/README.md

@@ -1,105 +1,97 @@
 # @zhin.js/adapter-onebot12
 
-Zhin.js [OneBot 12](https://12.onebot.dev/) 协议适配器，**一个适配器**支持正向 WebSocket、HTTP Webhook、反向 WebSocket 三种连接方式，由配置项 `connection` 区分。
+Zhin.js [OneBot 12](https://12.onebot.dev/) 适配器（Plugin Runtime）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **HTTP Webhook** 与 **反向 WS**（经 `httpHostToken` 注册路由）。
 
 ## 功能特性
 
-- 🔌 [OneBot 12 标准](https://12.onebot.dev/) 兼容（OneBot Connect + 接口定义）
-- 📦 **单一适配器**：`context: onebot12`，通过 `connection` 选择连接方式
-- 🌐 **正向 WebSocket**（`connection: ws`）：应用连 OneBot 实现的 WS 服务器
-- 📮 **HTTP Webhook**（`connection: webhook`）：OneBot 实现 POST 事件到应用提供的 path，可选 `api_url` 用于发消息/撤回
-- 🔄 **反向 WebSocket**（`connection: wss`）：应用开 WS 服务端，OneBot 实现连上来
-- 🔐 `access_token` 鉴权（Bearer）
-- 📨 私聊 / 群聊 / 频道消息收发，消息段与 OneBot 12 标准一致
+- [OneBot 12 标准](https://12.onebot.dev/) 兼容（事件 + 动作）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- **正向 WebSocket**（`connection: ws`）：应用连 OneBot 实现的 WS 服务器
+- `access_token` 鉴权（Bearer + query）
+- 入站经 `Endpoint.emit(...)`；出站 `send({ conversation, payload })`
 
 ## 安装
 
 ```bash
-pnpm add @zhin.js/adapter-onebot12 ws
+pnpm add @zhin.js/adapter-onebot12
 ```
 
-Webhook / 反向 WS 需启用 `@zhin.js/host-router`：
+## Plugin Runtime
 
-```bash
-pnpm add @zhin.js/host-router
-```
+- `@zhin.js/adapter` — 约定式 `adapters/onebot12/index.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+
+`AdapterIndex` 会把实例默认值与 `endpoints[]` 的逐项覆盖合并；协议层只接收一个已经展开的 endpoint 配置，不再读取嵌套 endpoint 或从进程环境推断身份。Webhook 配置必须同时提供 `path` 与 `api_url`，从而在启动前建立完整的双向能力。
 
-## 配置
+入站：`gateway.receive({ conversation: ConversationRef, message: { conversation, id }, content, sender, metadata })`  
+出站：`send({ conversation, payload })` → WS `send_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
-所有 Endpoint 使用 **同一 context：`onebot12`**，通过 **`connection`** 区分连接方式。
+每个 Endpoint 的 `$client` 是 `@imhelper/onebot-v12` 的 `OneBotV12Client`。业务代码直接调用
+`$client.call(action, params)` 和 Client 的公开平台能力；Webhook 使用 Client 的
+`acceptHttp()`，双工 WS 则由 Endpoint 分离 `echo` 响应后把事件交给 `ingest()`。
 
-### 正向 WebSocket
+## 前置条件
+
+1. 启动兼容 OneBot 12 的实现，并确认其支持所选 WS 或 Webhook 模式。
+2. Webhook 出站还需要可用的 `api_url`；反向连接需要实现端可达 Zhin HTTP Host。
+3. 两端配置相同的 `access_token`，生产环境必须启用鉴权。
+
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-onebot12"
-
-endpoints:
-  - context: onebot12
+  onebot12:
     connection: ws
-    name: ob12-bot
-    url: "ws://127.0.0.1:6700"
-    access_token: "${ONEBOT12_ACCESS_TOKEN}"
     reconnect_interval: 5000
     heartbeat_interval: 30000
+    endpoints:
+      - id: ob12-bot
+        url: "ws://127.0.0.1:6700"
+        access_token: "${ONEBOT12_ACCESS_TOKEN}"
 ```
 
-### HTTP Webhook
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-onebot12`（`instanceKey: onebot12`）。
 
-OneBot 实现会向你的 `path` 发送 POST 事件；若需发消息/撤回，请配置实现提供的 HTTP 端点 `api_url`。
+## 连接方式
 
-```yaml
-plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-onebot12"
-
-endpoints:
-  - context: onebot12
-    connection: webhook
-    name: ob12-webhook-bot
-    path: "/onebot12/webhook"
-    api_url: "http://127.0.0.1:6700"   # 可选，用于 send_message / delete_message
-    access_token: "${ONEBOT12_ACCESS_TOKEN}"
-```
+| connection | 状态 |
+|------------|------|
+| `ws` | 已实现（推荐） |
+| `webhook` | 已实现：POST 入站 + `api_url` HTTP 出站 |
+| `wss` | 已实现：反向 WS（httpHostToken） |
+
+## 鉴权
 
-### 反向 WebSocket
+- **Bearer**：`Authorization: Bearer <access_token>`
+- 正向 WS 在 Upgrade 时附带请求头，并在 URL query 写入 `access_token`
 
-```yaml
-plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-onebot12"
-
-endpoints:
-  - context: onebot12
-    connection: wss
-    name: ob12-wss-bot
-    path: "/onebot12/event"
-    access_token: "${ONEBOT12_ACCESS_TOKEN}"
-    heartbeat_interval: 30000
-```
+## 动作与事件
 
-## 鉴权
+- 事件：`type`（meta/message/notice/request）、`detail_type`、`message` 等，见 [事件](https://12.onebot.dev/connect/data-protocol/event/)。
+- 动作：`send_message`、`delete_message`、`get_status` 等，见 [动作请求](https://12.onebot.dev/connect/data-protocol/action-request/)。
 
-- **Bearer**：请求头 `Authorization: Bearer <access_token>`
-- 正向 WS 在建立连接时通过 HTTP Upgrade 头鉴权；Webhook / 反向 WS 同上
+## AI 工具
 
-配置 `access_token` 并与 OneBot 实现端一致即可。
+技能说明见 `skills/onebot12/SKILL.md`。
 
-## 连接方式对比
+## 文档链接
 
-| connection | 说明 |
-|------------|------|
-| `ws` | 应用连实现的 WebSocket 服务器 |
-| `webhook` | 实现 POST 事件到应用 path；发消息需配置 `api_url` |
-| `wss` | 应用开 WS 服务端，实现连上来 |
+- [OneBot 12 标准](https://12.onebot.dev/)
+- [OneBot Connect WebSocket](https://12.onebot.dev/connect/communication/websocket/)
+- [适配器概览](https://zhin.js.org/essentials/adapters)
 
-## 动作与事件
+## 故障排查
 
-- 事件：`type`（meta/message/notice/request）、`detail_type`、`message`（消息段数组）等，见 [事件](https://12.onebot.dev/connect/data-protocol/event/)。
-- 动作：`send_message`（params: detail_type, user_id/group_id/channel_id, message）、`delete_message` 等，见 [动作请求](https://12.onebot.dev/connect/data-protocol/action-request/)。
+| 现象 | 排查 |
+| --- | --- |
+| WS 连接失败 | 核对 OneBot 版本、连接方向、URL 与端口 |
+| Webhook 能收不能发 | 检查 `api_url` 可达性与 `send_message` 支持 |
+| 401 或握手失败 | 确认 Header/query token 与实现端一致 |
+| 事件字段无法识别 | 确认实现端发送的是 OneBot 12 而非 v11 结构 |
 
-## 协议文档
+## 许可证
 
-- [OneBot 12 标准](https://12.onebot.dev/)
-- [OneBot Connect 通信方式](https://12.onebot.dev/connect/communication/websocket/)
-- [数据协议（事件 / 动作）](https://12.onebot.dev/connect/data-protocol/event/)
+MIT License

package/adapters/onebot12/index.js

@@ -0,0 +1,50 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * 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";
+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'],
+    operations: ['recall'],
+    // 媒体段经 upload_file 物化为 file_id（spec 正式投递）；上传失败降级扩展字段透传。
+    // 无卡片交互面，交互段降级纯文本。
+    segments: {
+        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,
+        });
+    },
+});

package/adapters/onebot12/index.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 {
+  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';
+export { OneBot12WsEndpoint } from '../../src/ws-endpoint.js';
+export type { OneBot12WsEndpointOptions } from '../../src/ws-endpoint.js';
+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'],
+  // 媒体段经 upload_file 物化为 file_id（spec 正式投递）；上传失败降级扩展字段透传。
+  // 无卡片交互面，交互段降级纯文本。
+  segments: {
+    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,
+    });
+  },
+});

package/commands/onebot12/endpoint/add/[id]/index.js

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

package/commands/onebot12/endpoint/add/[id]/index.ts

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

package/commands/onebot12/endpoint/definition.js

@@ -0,0 +1,26 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `onebot12 endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/onebot12/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+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: '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/commands/onebot12/endpoint/definition.ts

@@ -0,0 +1,24 @@
+/**
+ * `onebot12 endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/onebot12/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+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: '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/commands/onebot12/endpoint/list/index.js

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

package/commands/onebot12/endpoint/list/index.ts

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

package/commands/onebot12/endpoint/remove/[id]/index.js

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

package/commands/onebot12/endpoint/remove/[id]/index.ts

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

package/lib/client.d.ts

@@ -0,0 +1,20 @@
+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';
+import type { ResolvedOneBot12Config } from './protocol.js';
+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 const onebot12Client: import("@zhin.js/adapter").EndpointClientToken<OneBotV12Client, ClientEventPayloads<Onebot12ClientEvents>>;

package/lib/client.js

@@ -0,0 +1,33 @@
+import { OneBotV12Client, } from '@imhelper/onebot-v12';
+import { EventFactory } from 'imhelper';
+import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+export { OneBotV12Client as Onebot12Client } from '@imhelper/onebot-v12';
+export function createOnebot12EndpointClient(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({
+        baseUrl,
+        selfId: config.id,
+        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}` : ''}`);
+    }
+    return response.data;
+}
+const onebot12ClientEventNames = Object.freeze([
+    ...EventFactory.getSupportedEventTypes(),
+    'event',
+]);
+export function forwardOnebot12ClientEvents(client, receive) {
+    return forwardEndpointClientEvents(client, onebot12ClientEventNames, receive);
+}
+export const onebot12Client = defineEndpointClient('onebot12');

package/lib/content-port.d.ts

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

package/lib/content-port.js

@@ -0,0 +1,45 @@
+export function createOneBot12ContentPort(callApi) {
+    return Object.freeze({
+        async resolve(reference, context) {
+            try {
+                context.signal.throwIfAborted();
+                if (reference.kind === 'forward') {
+                    return Object.freeze({ status: 'unsupported', code: 'onebot12_forward_lookup_not_standardized' });
+                }
+                if (reference.kind === 'media') {
+                    return reference.media.kind === 'file'
+                        ? 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 });
+                context.signal.throwIfAborted();
+                const message = (row.message && typeof row.message === 'object' ? row.message : row);
+                const segments = normalizeSegments(message.message ?? message.content);
+                const value = Object.freeze({
+                    ref: reference.message,
+                    ...(message.user_id != null ? { actor: Object.freeze({ id: String(message.user_id) }) } : {}),
+                    segments,
+                    timestamp: toMillis(message.time),
+                });
+                return Object.freeze({ status: 'resolved', reference, value });
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+                return Object.freeze({ status: 'failed', code: 'onebot12_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+}
+function normalizeSegments(value) {
+    if (!Array.isArray(value))
+        return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+    return Object.freeze(value.map((item) => {
+        const row = item;
+        return Object.freeze({ type: String(row.type ?? 'text'), data: Object.freeze((row.data ?? {})) });
+    }));
+}
+function toMillis(value) {
+    const time = Number(value);
+    return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}

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,19 +1,10 @@
-import { OneBot12Adapter } from './adapter.js';
-export * from './types.js';
-export { callOneBot12Action } from './api.js';
-export * from './utils.js';
-export { OneBot12WsClient } from './endpoint-ws.js';
-export { OneBot12WebhookEndpoint } from './endpoint-webhook.js';
-export { OneBot12WssServer } from './endpoint-wss.js';
-export { OneBot12Adapter, type OneBot12Bot } from './adapter.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Adapters {
-        onebot12: OneBot12Adapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12CallAction, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, 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';
+export type { OneBot12WsSocket, OneBot12WsCreateOptions } from './ws-types.js';
+export { verifyOneBotAccessToken } from './wss-auth.js';
+export { Onebot12Client, onebot12Client, type Onebot12ClientEventMap, } from './client.js';
+export type { OneBotV12ActionUrlResolver, OneBotV12AdapterConfig as ImHelperOneBotV12AdapterConfig, OneBotV12Call, OneBotV12ClientConfig, OneBotV12Event as ImHelperOneBotV12Event, OneBotV12Response, } from '@imhelper/onebot-v12';
+export { ProtocolError } from '@imhelper/onebot-v12';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/lib/index.js

@@ -1,27 +1,7 @@
-/**
- * OneBot 12 适配器入口：单一适配器，支持正向 WS / Webhook / 反向 WS
- * 协议文档 https://12.onebot.dev/
- */
-import { usePlugin } from 'zhin.js';
-import { OneBot12Adapter } from './adapter.js';
-export * from './types.js';
-export { callOneBot12Action } from './api.js';
-export * from './utils.js';
-export { OneBot12WsClient } from './endpoint-ws.js';
-export { OneBot12WebhookEndpoint } from './endpoint-webhook.js';
-export { OneBot12WssServer } from './endpoint-wss.js';
-export { OneBot12Adapter } from './adapter.js';
-const { provide } = usePlugin();
-provide({
-    name: 'onebot12',
-    description: 'OneBot 12 协议适配器（正向 WS / Webhook / 反向 WS）',
-    mounted: async (p) => {
-        const adapter = new OneBot12Adapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-//# sourceMappingURL=index.js.map
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+export { OneBot12WebhookEndpoint, } from './webhook.js';
+export { OneBot12WsEndpoint, } from './ws-endpoint.js';
+export { OneBot12WssEndpoint, } from './wss-endpoint.js';
+export { verifyOneBotAccessToken } from './wss-auth.js';
+export { Onebot12Client, onebot12Client, } from './client.js';
+export { ProtocolError } from '@imhelper/onebot-v12';

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

@@ -0,0 +1 @@
+export declare const onebot12RuntimeStateToken: import("zhin.js").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');