@zhin.js/adapter-onebot12 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @zhin.js/adapter-onebot12
 
+## 1.1.2
+
+### Patch Changes
+
+- a9e4a40: Derive Command user routes only from explicit `commands/**/*/index.ts(x)` entry paths instead of prepending the plugin owner. Child plugins can now publish top-level static or dynamic commands, while duplicate routes across owners fail during generation construction. Adapter endpoint commands move to explicit paths such as `commands/qq/endpoint/list/index.ts` and are invoked as `qq endpoint list`.
+- 8740059: Standardize TypeScript capabilities on named module directories such as `commands/foo/index.ts`, `middlewares/audit/index.ts`, `handlers/message-receive/index.ts`, `pages/workroom/index.tsx`, and `mcps/filesystem/index.ts`. Only the fixed `index` entry is discovered; sibling files remain private helpers.
+
+  Command route segments come from directories, while `[name]`, `[[name]]`, `[...name]`, and `[[...name]]` directories declare dynamic parameters. Plugin owners do not enter the route unless their config explicitly sets `commandNamespace`; Endpoint `commandPrefix` remains platform-owned and defaults to an empty string.
+
+  Migrate the built-in adapters, plugins, examples, generators, migration tooling, hot reload classification, Agent authoring surfaces, documentation, and release artifacts to the explicit entry convention.
+
+  Make Tool ownership and progressive disclosure explicit across all four supported locations: plugin-public `tools/`, Agent-private `agents/<name>/tools/`, Skill-private `skills/<name>/tools/`, and Agent-Skill-private `agents/<name>/skills/<name>/tools/`. Move adapter and group-suite operations that require domain instructions into their owning Skills so `load_skill` is the only path that unlocks their schemas.
+
+  Remove the package-root `agent/` convention. Public capabilities now use named package-root directories, schedules use `schedules/<name>/index.ts` or `plugin.ts` injection, MCP connections use `mcps/<name>/index.ts`, Prompt Sections use `prompt-sections/<name>/index.ts`, Agent definitions use `agents/<name>/`, and permission vocabulary is published as `PERMITS.md`.
+
+- 25a845a: Unify Skills on `skills/<name>/SKILL.md`, support Agent-private Skills and nested Skill-private Tools, publish and mount existing plugin Skills, add governed Skill metadata and Turn access filtering, unlock only already-admitted same-owner Tools, and make `on-risk` and `once` approval behavior precise.
+- 4380cf9: Colocate adapter command definitions and Agent Skill handlers with their owning capabilities, and provide a shared validated platform permission constructor.
+- bfb646b: Require one canonical expanded OneBot 12 endpoint configuration and a complete Webhook `api_url`. Remove nested endpoint and environment compatibility, centralize WebSocket request correlation, and route reverse WebSocket replacement, heartbeat, pending actions, and stale-event admission through the endpoint lifecycle.
+- 5c3858e: Make `@zhin.js/im-contract` the explicit zero-dependency owner of transport identities, canonical segments, media guards, conversation facts, stores, and delivery contracts. Platform adapters now read media contracts from that foundation instead of reaching through Core.
+- Updated dependencies [c861789]
+- Updated dependencies [1414ccb]
+- Updated dependencies [743d470]
+- Updated dependencies [62dee52]
+- Updated dependencies [cd54131]
+- Updated dependencies [244e475]
+- Updated dependencies [a9e4a40]
+- Updated dependencies [5855db7]
+- Updated dependencies [ec921d2]
+- Updated dependencies [8740059]
+- Updated dependencies [25a845a]
+- Updated dependencies [103f2c3]
+- Updated dependencies [9110ab8]
+- Updated dependencies [cd2a888]
+- Updated dependencies [eb3227a]
+- Updated dependencies [b853dba]
+- Updated dependencies [e561309]
+- Updated dependencies [d4c6175]
+- Updated dependencies [7a0e1ca]
+- Updated dependencies [103b5d3]
+- Updated dependencies [5a7a7f7]
+- Updated dependencies [b076eae]
+- Updated dependencies [73a24b7]
+- Updated dependencies [2dbbc15]
+- Updated dependencies [1cb1163]
+- Updated dependencies [be3061e]
+- Updated dependencies [75f8332]
+- Updated dependencies [81935e2]
+- Updated dependencies [f9ed01b]
+- Updated dependencies [ac0ab50]
+- Updated dependencies [5140ce1]
+- Updated dependencies [522d75f]
+- Updated dependencies [a7611b3]
+- Updated dependencies [8823044]
+- Updated dependencies [379439b]
+- Updated dependencies [11c9352]
+- Updated dependencies [6b70e46]
+- Updated dependencies [135ac91]
+- Updated dependencies [140cf0f]
+- Updated dependencies [251e4d2]
+- Updated dependencies [203ad34]
+- Updated dependencies [e6c5113]
+- Updated dependencies [e0f6478]
+- Updated dependencies [baef56b]
+- Updated dependencies [da0a8e3]
+- Updated dependencies [2fd8017]
+- Updated dependencies [5c3858e]
+- Updated dependencies [507d602]
+- Updated dependencies [df9f76b]
+  - @zhin.js/core@1.1.37
+  - @zhin.js/host-http@1.1.1
+  - @zhin.js/adapter@1.1.14
+  - @zhin.js/feature-kit@1.1.1
+  - @zhin.js/skill@1.1.1
+  - @zhin.js/logger@1.1.1
+  - @zhin.js/im-contract@1.1.1
+
+## 1.1.1
+
+### Patch Changes
+
+- 33b1582: Update vulnerable dependencies and replace unsafe HTML and protocol-text regular expressions with bounded scanners.
+- Updated dependencies [769e67f]
+  - @zhin.js/adapter@1.1.13
+  - @zhin.js/core@1.1.36
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -18,11 +18,13 @@ pnpm add @zhin.js/adapter-onebot12
 
 ## Plugin Runtime
 
-- `@zhin.js/adapter` — 约定式 `adapters/onebot12.ts`（`defineAdapter`）
+- `@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）
 
@@ -46,7 +48,7 @@ plugins:
     reconnect_interval: 5000
     heartbeat_interval: 30000
     endpoints:
-      - name: ob12-bot
+      - id: ob12-bot
         url: "ws://127.0.0.1:6700"
         access_token: "${ONEBOT12_ACCESS_TOKEN}"
 ```
@@ -73,7 +75,7 @@ plugins:
 
 ## AI 工具
 
-技能说明见 `agent/skills/onebot12.md`。
+技能说明见 `skills/onebot12/SKILL.md`。
 
 ## 文档链接
 

package/adapters/{onebot12.js → onebot12/index.js}

@@ -1,17 +1,17 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/onebot12.ts` → defineAdapter.
+ * 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";
+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'],
@@ -23,7 +23,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveOneBot12Config(context.config);
-        // 注册到插件运行时状态（onebot12.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（onebot12 endpoint list 的"运行中"数据源）
         context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: config.connection,

package/adapters/{onebot12.ts → onebot12/index.ts}

@@ -1,32 +1,32 @@
 /**
- * Convention entry: discover `adapters/onebot12.ts` → defineAdapter.
+ * 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 { OneBot12WebhookEndpoint } from '../../src/webhook.js';
+import { OneBot12WsEndpoint } from '../../src/ws-endpoint.js';
+import { OneBot12WssEndpoint } from '../../src/wss-endpoint.js';
 import {
   resolveOneBot12Config,
-  type OneBot12AdapterConfig,
-} from '../src/protocol.js';
-import { onebot12RuntimeStateToken } from '../src/onebot12-runtime-state.js';
+  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';
+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;
+    onebot12: import('../../src/ws-endpoint.js').OneBot12WsEndpoint;
   }
 }
 
-export default defineAdapter<OneBot12AdapterConfig>({
+export default defineAdapter<OneBot12EndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
   // 媒体段经 upload_file 物化为 file_id（spec 正式投递）；上传失败降级扩展字段透传。
@@ -37,7 +37,7 @@ export default defineAdapter<OneBot12AdapterConfig>({
   },
   create(context) {
     const config = resolveOneBot12Config(context.config);
-    // 注册到插件运行时状态（onebot12.endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（onebot12 endpoint list 的"运行中"数据源）
     context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       mode: config.connection,

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

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { onebot12EndpointCommands } from "../../../lib/onebot12-endpoint-commands.js";
+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/{lib/onebot12-endpoint-commands.js → commands/onebot12/endpoint/definition.js}

@@ -1,10 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * `onebot12.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `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 './onebot12-runtime-state.js';
+import { onebot12RuntimeStateToken } from "../../../lib/onebot12-runtime-state.js";
 export const onebot12EndpointCommands = createEndpointCommands({
     adapterKey: 'onebot12',
     adapterDisplayName: 'OneBot 12',

package/{src/onebot12-endpoint-commands.ts → commands/onebot12/endpoint/definition.ts}

@@ -1,10 +1,10 @@
 /**
- * `onebot12.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `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 './onebot12-runtime-state.js';
+import { onebot12RuntimeStateToken } from '../../../src/onebot12-runtime-state.js';
 
 export const onebot12EndpointCommands = createEndpointCommands({
   adapterKey: 'onebot12',

package/commands/{endpoint/list.js → onebot12/endpoint/list/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { onebot12EndpointCommands } from "../../lib/onebot12-endpoint-commands.js";
+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/{endpoint/remove/[id].js → onebot12/endpoint/remove/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { onebot12EndpointCommands } from "../../../lib/onebot12-endpoint-commands.js";
+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.js

@@ -5,7 +5,7 @@ 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
+        : config.connection === 'webhook'
             ? config.api_url
             : 'http://localhost';
     return new OneBotV12Client({

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, 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 ResolvedOneBot12Config, } from './protocol.js';
+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';

package/lib/onebot12-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * OneBot12 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `onebot12.endpoint` 命令共享（同一 owner generation）。
+ * 由 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,32 +3,17 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
-import { type MediaRef } from '@zhin.js/core';
-import type { ConversationRef } from '@zhin.js/im-contract';
-/** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
-export interface OneBot12LegacyEndpointRow {
-    readonly context?: string;
+import { type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface OneBot12EndpointConfig {
     readonly connection?: 'ws' | 'webhook' | 'wss';
-    readonly id?: string;
-    readonly access_token?: string;
-    readonly url?: string;
-    readonly path?: string;
-    readonly api_url?: string;
-    readonly reconnect_interval?: number;
-    readonly heartbeat_interval?: number;
-}
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface OneBot12AdapterConfig {
-    readonly connection?: 'ws' | 'webhook' | 'wss';
-    readonly id?: string;
+    readonly id: string;
     readonly access_token?: string;
     readonly url?: string;
     readonly path?: string;
     readonly api_url?: string;
     readonly reconnect_interval?: number;
     readonly heartbeat_interval?: number;
-    /** Transitional: legacy root `endpoints[]` with `context: onebot12`. */
-    readonly endpoints?: ReadonlyArray<OneBot12LegacyEndpointRow>;
 }
 export interface OneBot12ConfigBase {
     readonly context: 'onebot12';
@@ -46,7 +31,7 @@ export interface OneBot12WsConfig extends OneBot12ConfigBase {
 export interface OneBot12WebhookConfig extends OneBot12ConfigBase {
     readonly connection: 'webhook';
     readonly path: string;
-    readonly api_url?: string;
+    readonly api_url: string;
 }
 /** 反向 WebSocket：httpHostToken WS upgrade 入站/出站 */
 export interface OneBot12WssConfig extends OneBot12ConfigBase {
@@ -55,7 +40,6 @@ export interface OneBot12WssConfig extends OneBot12ConfigBase {
     readonly heartbeat_interval: number;
 }
 export type ResolvedOneBot12Config = OneBot12WsConfig | OneBot12WebhookConfig | OneBot12WssConfig;
-export type OneBot12EndpointConfig = ResolvedOneBot12Config;
 export interface OneBot12Self {
     readonly platform: string;
     readonly user_id: string;
@@ -101,7 +85,7 @@ export interface OneBot12WireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
 }
-export declare function resolveOneBot12Config(config?: OneBot12AdapterConfig): ResolvedOneBot12Config;
+export declare function resolveOneBot12Config(config: OneBot12EndpointConfig): ResolvedOneBot12Config;
 /** 判断是否为消息事件（type=message） */
 export declare function isMessageEvent(ev: OneBot12Event): ev is OneBot12Event & {
     message_id: string;

package/lib/protocol.js

@@ -3,64 +3,60 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('onebot12');
-export function resolveOneBot12Config(config = {}) {
-    const entry = config.endpoints?.find((item) => item.context === 'onebot12');
-    const connection = config.connection
-        ?? entry?.connection
-        ?? 'ws';
-    const id = (typeof config.id === 'string' && config.id)
-        || (typeof entry?.id === 'string' && entry.id)
-        || process.env.ONEBOT12_BOT_NAME
-        || 'onebot12-bot';
-    const access_token = config.access_token ?? entry?.access_token;
+export function resolveOneBot12Config(config) {
+    const connection = config.connection ?? 'ws';
+    const id = requiredEndpointField(config.id, 'id');
+    const access_token = optionalEndpointField(config.access_token);
     if (connection === 'ws') {
-        const url = config.url ?? entry?.url;
-        if (!url) {
-            throw new TypeError('OneBot12 connection:ws requires url (plugins.<key>.url or endpoints with context: onebot12)');
-        }
+        const url = requiredEndpointField(config.url, 'url');
         return {
             context: 'onebot12',
             connection: 'ws',
             id,
             access_token,
             url,
-            reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
-            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+            reconnect_interval: config.reconnect_interval ?? 5000,
+            heartbeat_interval: config.heartbeat_interval ?? 30_000,
         };
     }
     if (connection === 'webhook') {
-        const path = config.path ?? entry?.path;
-        if (!path) {
-            throw new TypeError('OneBot12 connection:webhook requires path');
-        }
+        const path = requiredEndpointField(config.path, 'path');
+        const api_url = requiredEndpointField(config.api_url, 'api_url');
         return {
             context: 'onebot12',
             connection: 'webhook',
             id,
             access_token,
             path,
-            api_url: config.api_url ?? entry?.api_url,
+            api_url,
         };
     }
     if (connection === 'wss') {
-        const path = config.path ?? entry?.path;
-        if (!path) {
-            throw new TypeError('OneBot12 connection:wss requires path');
-        }
+        const path = requiredEndpointField(config.path, 'path');
         return {
             context: 'onebot12',
             connection: 'wss',
             id,
             access_token,
             path,
-            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+            heartbeat_interval: config.heartbeat_interval ?? 30_000,
         };
     }
     throw new TypeError(`Unknown OneBot12 connection: ${String(connection)}`);
 }
+function requiredEndpointField(value, field) {
+    const resolved = optionalEndpointField(value);
+    if (!resolved) {
+        throw new TypeError(`OneBot12 endpoint requires a non-empty ${field}`);
+    }
+    return resolved;
+}
+function optionalEndpointField(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
 /** 判断是否为消息事件（type=message） */
 export function isMessageEvent(ev) {
     return ev.type === 'message' && !!ev.message_id;
@@ -111,9 +107,29 @@ export function formatInboundContent(ev) {
             .join('');
     }
     return typeof ev.alt_message === 'string'
-        ? ev.alt_message.replace(/\[[^\]]*(?:image|audio|video|file)[^\]]*\]/gi, '').trim()
+        ? stripMediaPlaceholders(ev.alt_message).trim()
         : '';
 }
+function stripMediaPlaceholders(input) {
+    const mediaNames = ['image', 'audio', 'video', 'file'];
+    let result = '';
+    let cursor = 0;
+    while (cursor < input.length) {
+        const start = input.indexOf('[', cursor);
+        if (start < 0)
+            return result + input.slice(cursor);
+        const end = input.indexOf(']', start + 1);
+        if (end < 0)
+            return result + input.slice(cursor);
+        result += input.slice(cursor, start);
+        const placeholder = input.slice(start + 1, end).toLowerCase();
+        if (!mediaNames.some((name) => placeholder.includes(name))) {
+            result += input.slice(start, end + 1);
+        }
+        cursor = end + 1;
+    }
+    return result;
+}
 /**
  * Runtime Message sender 必须是用户 ID（agent bridge 以 sender 与 endpointMaster 比对）。
  * 显示名经 {@link senderNickname} 放入 metadata.nickname。

package/lib/webhook.js

@@ -84,11 +84,7 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint {
         await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
     }
     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');
-        }
-        return this.#callAction({ url: apiUrl, access_token: this.#options.config.access_token }, action, params);
+        return this.#callAction({ url: this.#options.config.api_url, access_token: this.#options.config.access_token }, action, params);
     }
     #admitRaw(ev) {
         if (!isMessageEvent(ev)) {

package/lib/ws-endpoint.js

@@ -2,7 +2,6 @@
  * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { clearTimeout } from 'node:timers';
 import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
@@ -10,7 +9,7 @@ import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, fo
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
 import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents } from './client.js';
-import { WS_OPEN, } from './ws-types.js';
+import { callOneBot12WsAction, handleOneBot12WsMessage, rejectAllPending, } from './ws-transport.js';
 export class OneBot12WsEndpoint extends ClientEndpoint {
     client;
     #logger;
@@ -20,7 +19,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint {
     content;
     #lifecycle;
     #ws;
-    #requestId = 0;
+    #requestId = { value: 0 };
     #pending = new Map();
     constructor(options) {
         super();
@@ -71,11 +70,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint {
         this.close();
         // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
         await this.#lifecycle.stop();
-        for (const [, pending] of this.#pending) {
-            clearTimeout(pending.timeout);
-            pending.reject(new Error('连接已关闭'));
-        }
-        this.#pending.clear();
+        rejectAllPending(this.#pending);
         this.#ws = undefined;
     }
     async send({ conversation, payload }) {
@@ -175,7 +170,14 @@ export class OneBot12WsEndpoint extends ClientEndpoint {
                 resolve();
             });
             ws.on('message', (data) => {
-                this.#onMessage(data);
+                if (this.#ws !== ws)
+                    return;
+                this.#lifecycle.notifyHeartbeatAck();
+                handleOneBot12WsMessage(data, {
+                    endpointId: this.#options.config.id,
+                    pending: this.#pending,
+                    ingest: (event) => this.client.ingest(event),
+                });
             });
             ws.on('close', (code, reason) => {
                 const reasonStr = typeof reason === 'string'
@@ -188,6 +190,10 @@ export class OneBot12WsEndpoint extends ClientEndpoint {
                     settled = true;
                     reject(new Error(`OneBot12 WS 关闭: ${codeNum} ${reasonStr}`));
                 }
+                if (this.#ws === ws) {
+                    this.#ws = undefined;
+                    rejectAllPending(this.#pending);
+                }
                 // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
                 // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
                 handle.notifyClosed(`OneBot12 WS 关闭: ${codeNum} ${reasonStr || 'closed'}`);
@@ -207,49 +213,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint {
             });
         });
     }
-    #onMessage(data) {
-        try {
-            const raw = typeof data === 'string'
-                ? data
-                : Buffer.isBuffer(data)
-                    ? data.toString()
-                    : data instanceof ArrayBuffer
-                        ? new TextDecoder().decode(data)
-                        : String(data ?? '');
-            const msg = JSON.parse(raw);
-            if ('echo' in msg && typeof msg.echo === 'string') {
-                const resp = msg;
-                const pending = this.#pending.get(resp.echo);
-                if (pending) {
-                    this.#pending.delete(resp.echo);
-                    clearTimeout(pending.timeout);
-                    pending.resolve(resp);
-                }
-                return;
-            }
-            this.client.ingest(msg);
-        }
-        catch (error) {
-            this.#logger.warn(formatCompact({
-                op: 'onebot12_parse_failed',
-                endpoint: this.#options.config.id,
-                error: error instanceof Error ? error.message : String(error),
-            }));
-        }
-    }
     #callAction(action, params) {
-        if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
-            return Promise.reject(new Error('WebSocket 未连接'));
-        }
-        const echo = `ob12_${++this.#requestId}`;
-        const req = { action, params, echo };
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                this.#pending.delete(echo);
-                reject(new Error(`OneBot12 动作超时: ${action}`));
-            }, 30_000);
-            this.#pending.set(echo, { resolve, reject, timeout });
-            this.#ws.send(JSON.stringify(req));
-        });
+        return callOneBot12WsAction(this.#ws, this.#pending, this.#requestId, action, params);
     }
 }

package/lib/ws-transport.d.ts

@@ -0,0 +1,12 @@
+import type { OneBot12ActionResponse, OneBot12Event } from './protocol.js';
+import { type OneBot12PendingAction, type OneBot12WsSocket } from './ws-types.js';
+export interface OneBot12WsMessageOptions {
+    readonly endpointId: string;
+    readonly pending: Map<string, OneBot12PendingAction>;
+    readonly ingest: (event: OneBot12Event) => void;
+}
+export declare function handleOneBot12WsMessage(data: unknown, options: OneBot12WsMessageOptions): void;
+export declare function callOneBot12WsAction(ws: OneBot12WsSocket | undefined, pending: Map<string, OneBot12PendingAction>, requestId: {
+    value: number;
+}, action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse>;
+export declare function rejectAllPending(pending: Map<string, OneBot12PendingAction>, message?: string): void;