@zhin.js/adapter-onebot11 5.0.0 → 5.0.1

package/CHANGELOG.md

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

package/adapters/onebot11.ts

@@ -10,6 +10,7 @@ import {
   resolveOneBot11Config,
   type OneBot11AdapterConfig,
 } from '../src/protocol.js';
+import { onebot11RuntimeStateToken } from '../src/onebot11-runtime-state.js';
 
 export { OneBot11WsEndpoint } from '../src/ws-endpoint.js';
 export type { OneBot11WsEndpointOptions } from '../src/ws-endpoint.js';
@@ -19,9 +20,19 @@ export type { OneBot11WsSocket, OneBot11WsCreateOptions } from '../src/ws-types.
 
 export default defineAdapter<OneBot11AdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // OneBot file 参数原生消费 url / base64:// 媒体；无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'base64'],
+    interactive: 'text',
+  },
   create(context) {
     const config = resolveOneBot11Config(context.config);
     const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（onebot11 endpoint list 的"运行中"数据源）
+    context.use(onebot11RuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.connection,
+    });
     if (config.connection === 'wss') {
       return new OneBot11WssEndpoint({
         id: context.id,

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

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

package/commands/endpoint/list.ts

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

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

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

package/lib/endpoint-management.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OneBot11 endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OneBot11 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from '@zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss 两种传输各自实现）。 */
+export interface OneBot11ManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createOneBot11EndpointManagement(endpoint: OneBot11ManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createOneBot11EndpointManagement(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.nickname ?? ''),
+                    remark: String(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: toNumberId(groupId, 'group_id'),
+            });
+            return toArray(data);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`onebot11 ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, isOneBot11BotMentioned, parseSendTarget, resolveOneBot11Config, senderDisplayName, senderNickname, senderUserId, type OneBot11ActionRequest, type OneBot11ActionResponse, type OneBot11AdapterConfig, type OneBot11ConfigBase, type OneBot11EndpointConfig, type OneBot11Event, type OneBot11Segment, type OneBot11Sender, type OneBot11WireSegment, type OneBot11WsConfig, type OneBot11WssConfig, type ParsedSendTarget, type ResolvedOneBot11Config, } from './protocol.js';
+export { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, isOneBot11BotMentioned, mediaRefToOneBotFile, parseSendTarget, resolveOneBot11Config, senderDisplayName, senderNickname, senderUserId, type OneBot11ActionRequest, type OneBot11ActionResponse, type OneBot11AdapterConfig, type OneBot11ConfigBase, type OneBot11EndpointConfig, type OneBot11Event, type OneBot11Segment, type OneBot11Sender, type OneBot11WireSegment, type OneBot11WsConfig, type OneBot11WssConfig, type ParsedSendTarget, type ResolvedOneBot11Config, } from './protocol.js';
 export { OneBot11WsEndpoint, type OneBot11WsEndpointOptions, } from './ws-endpoint.js';
 export { OneBot11WssEndpoint, type OneBot11WssEndpointOptions, } from './wss-endpoint.js';
 export type { OneBot11WsSocket, OneBot11WsCreateOptions } from './ws-types.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, isOneBot11BotMentioned, parseSendTarget, resolveOneBot11Config, senderDisplayName, senderNickname, senderUserId, } from './protocol.js';
+export { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, isOneBot11BotMentioned, mediaRefToOneBotFile, parseSendTarget, resolveOneBot11Config, senderDisplayName, senderNickname, senderUserId, } from './protocol.js';
 export { OneBot11WsEndpoint, } from './ws-endpoint.js';
 export { OneBot11WssEndpoint, } from './wss-endpoint.js';
 export { callOneBot11WsAction, decodeWsPayload, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';

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

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

package/lib/onebot11-endpoint-commands.js

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

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

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

package/lib/onebot11-runtime-state.js

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

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
+import { type MediaRef } from '@zhin.js/core';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot11`). */
 export interface OneBot11LegacyEndpointRow {
     readonly context?: string;
@@ -127,9 +128,15 @@ export declare function isOneBot11BotMentioned(input: {
 }): boolean;
 /** 构造 gateway.receive 的 metadata（ws / wss 两个 endpoint 共用）。 */
 export declare function formatInboundMetadata(ev: OneBot11Event, endpoint: string): Readonly<Record<string, unknown>>;
+/**
+ * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）。
+ */
+export declare function mediaRefToOneBotFile(media: MediaRef): string;
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
  */
 export declare function formatOutboundSegments(payload: unknown): OneBot11Segment[];
 export declare function buildSendAction(target: string, message: OneBot11Segment[]): {

package/lib/protocol.js

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
 function normalizeConnection(connection, legacyType) {
     if (connection === 'ws' || connection === 'wss')
         return connection;
@@ -169,9 +170,74 @@ export function formatInboundMetadata(ev, endpoint) {
         ...(mentioned ? { mentioned: true } : {}),
     });
 }
+/**
+ * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）。
+ */
+export function mediaRefToOneBotFile(media) {
+    if (media.kind === 'base64') {
+        return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+    }
+    if (media.kind === 'path') {
+        return media.value.startsWith('file://') ? media.value : `file://${media.value}`;
+    }
+    return media.value;
+}
+/** 媒体段 data 里的 canonical-only 字段，不进 OneBot wire。 */
+const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt', 'url', 'base64', 'file', 'mime_type']);
+function oneBotMediaSegment(type, data) {
+    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+    if (!media)
+        return { type, data };
+    const extra = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (!MEDIA_DATA_SKIP_KEYS.has(key))
+            extra[key] = value;
+    }
+    return { type, data: { ...extra, file: mediaRefToOneBotFile(media) } };
+}
+/**
+ * canonical Segment → OneBot 11 数组段：
+ * - mention → at（`qq: target`）；
+ * - reply（`message_id`）→ reply（`id`）；
+ * - image / audio→record / video 的 MediaRef → `file`（url / base64:// / file://）；
+ * - face 取 `id`；
+ * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
+ */
+function canonicalToOneBotSegment(segment) {
+    const data = segment.data ?? {};
+    switch (segment.type) {
+        case 'mention': {
+            const target = data.target ?? data.qq ?? data.id;
+            if (target == null)
+                return { type: segment.type, data };
+            return { type: 'at', data: { qq: String(target) } };
+        }
+        case 'reply': {
+            const messageId = data.message_id ?? data.id;
+            if (messageId == null)
+                return { type: segment.type, data };
+            return { type: 'reply', data: { id: String(messageId) } };
+        }
+        case 'face': {
+            if (data.id == null)
+                return { type: segment.type, data };
+            return { type: 'face', data: { id: data.id } };
+        }
+        case 'image':
+        case 'record':
+        case 'video':
+            return oneBotMediaSegment(segment.type, data);
+        case 'audio':
+            return oneBotMediaSegment('record', data);
+        default:
+            return { type: segment.type, data };
+    }
+}
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
  */
 export function formatOutboundSegments(payload) {
     if (typeof payload === 'string') {
@@ -196,7 +262,7 @@ export function formatOutboundSegments(payload) {
             segs.push({ type: 'text', data: { text: item } });
             continue;
         }
-        segs.push({ type: item.type, data: item.data ?? {} });
+        segs.push(canonicalToOneBotSegment(item));
     }
     return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }

package/lib/ws-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type OneBot11Event, type OneBot11WsConfig } from './protocol.js';
@@ -11,6 +11,7 @@ export interface OneBot11WsEndpointOptions {
 }
 export declare class OneBot11WsEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: OneBot11WsEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/ws-endpoint.js

@@ -2,37 +2,58 @@
  * OneBot11 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { clearInterval, clearTimeout, setTimeout } from 'node:timers';
+import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderUserId, } from './protocol.js';
-import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
+import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, } from './ws-transport.js';
 const logger = getLogger('onebot11');
 export class OneBot11WsEndpoint {
     #options;
+    management = createOneBot11EndpointManagement(this);
+    #lifecycle;
     #ws;
-    #reconnectTimer;
-    #heartbeatTimer;
     #requestId = { value: 0 };
     #pending = new Map();
     #open = false;
-    #started = false;
-    #stopping = false;
     #unregisterAgent;
     constructor(options) {
         this.#options = options;
+        const { config } = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: config.name,
+            reconnect: {
+                initialIntervalMs: config.reconnect_interval,
+                // 固定间隔（multiplier 1、无抖动），对齐旧 reconnect_interval 语义
+                multiplier: 1,
+                maxIntervalMs: config.reconnect_interval,
+                jitterMs: 0,
+            },
+            heartbeat: { intervalMs: config.heartbeat_interval },
+        });
     }
     async start() {
-        if (this.#started)
+        if (this.#lifecycle.started)
             return;
-        this.#started = true;
-        this.#stopping = false;
+        // agent 注册/反注册是适配器专有依赖，留在适配器侧（见 endpoint-lifecycle 迁移指引）
         this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.name, this);
         try {
-            await this.#connect();
+            await this.#lifecycle.start((handle) => this.#connect(handle));
         }
         catch (err) {
-            this.#started = false;
+            // start 失败必须清理现场（状态复位由基座保证），避免 agent 注册泄漏
+            if (this.#ws) {
+                try {
+                    this.#ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = undefined;
+            }
+            this.#unregisterAgent?.();
+            this.#unregisterAgent = undefined;
             throw err;
         }
     }
@@ -44,29 +65,12 @@ export class OneBot11WsEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#stopping = true;
-        this.#started = false;
+        // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+        await this.#lifecycle.stop();
         this.#unregisterAgent?.();
         this.#unregisterAgent = undefined;
-        if (this.#reconnectTimer) {
-            clearTimeout(this.#reconnectTimer);
-            this.#reconnectTimer = undefined;
-        }
-        if (this.#heartbeatTimer) {
-            clearInterval(this.#heartbeatTimer);
-            this.#heartbeatTimer = undefined;
-        }
         rejectAllPending(this.#pending);
-        if (this.#ws) {
-            try {
-                this.#ws.close();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#ws = undefined;
-        }
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#ws = undefined;
     }
     async send({ target, payload }) {
         const message = formatOutboundSegments(payload);
@@ -115,7 +119,7 @@ export class OneBot11WsEndpoint {
             }));
         });
     }
-    async #connect() {
+    async #connect(handle) {
         const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
         const create = this.#options.createWebSocket
             ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
@@ -123,6 +127,14 @@ export class OneBot11WsEndpoint {
             let settled = false;
             const ws = create(url, { headers });
             this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
             ws.on('open', () => {
                 if (settled)
                     return;
@@ -139,9 +151,7 @@ export class OneBot11WsEndpoint {
                     mode: 'ws',
                     url: safeUrl,
                 }));
-                this.#heartbeatTimer = this.#stopping
-                    ? this.#heartbeatTimer
-                    : startOneBot11Heartbeat(this.#ws, this.#options.config.heartbeat_interval, this.#heartbeatTimer);
+                this.#lifecycle.startHeartbeat(() => this.#ws?.ping?.());
                 resolve();
             });
             ws.on('message', (data) => {
@@ -163,18 +173,13 @@ export class OneBot11WsEndpoint {
                     : codeNum === 1006
                         ? ' [异常关闭]'
                         : '';
-                logger.warn(formatCompact({
-                    op: 'disconnect',
-                    endpoint: this.#options.config.name,
-                    code: codeNum,
-                    error: `${reasonStr || 'closed'}${codeHint}`,
-                    reconnect_ms: this.#options.config.reconnect_interval,
-                }));
                 if (!settled) {
                     settled = true;
                     reject(new Error(`OneBot11 WS 关闭: ${codeNum} ${reasonStr}`));
                 }
-                this.#scheduleReconnect();
+                // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+                // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
+                handle.notifyClosed(`OneBot11 WS 关闭: ${codeNum} ${reasonStr || 'closed'}${codeHint}`);
             });
             ws.on('error', (err) => {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -191,20 +196,4 @@ export class OneBot11WsEndpoint {
             });
         });
     }
-    #scheduleReconnect() {
-        if (this.#stopping || !this.#started || this.#reconnectTimer)
-            return;
-        const delay = this.#options.config.reconnect_interval;
-        this.#reconnectTimer = setTimeout(() => {
-            this.#reconnectTimer = undefined;
-            void this.#connect().catch((err) => {
-                logger.warn(formatCompact({
-                    op: 'reconnect',
-                    endpoint: this.#options.config.name,
-                    ok: false,
-                    error: err instanceof Error ? err.message : String(err),
-                }));
-            });
-        }, delay);
-    }
 }

package/lib/wss-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -11,6 +11,7 @@ export interface OneBot11WssEndpointOptions {
 }
 export declare class OneBot11WssEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: OneBot11WssEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/wss-endpoint.js

@@ -3,6 +3,7 @@
  */
 import { clearInterval } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import { buildSendAction, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderUserId, } from './protocol.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
@@ -10,6 +11,7 @@ import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, startO
 const logger = getLogger('onebot11');
 export class OneBot11WssEndpoint {
     #options;
+    management = createOneBot11EndpointManagement(this);
     #ws;
     #wsRelease;
     #heartbeatTimer;
@@ -25,6 +27,15 @@ export class OneBot11WssEndpoint {
         if (this.#started)
             return;
         this.#started = true;
+        if (!this.#options.config.access_token) {
+            // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
+            logger.warn(formatCompact({
+                endpoint: this.#options.config.name,
+                mode: 'wss',
+                ok: false,
+                error: 'missing access_token',
+            }));
+        }
         this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.name, this);
         const handle = this.#options.http.ws(this.#options.config.path);
         this.#wsRelease = handle.onConnection((connection) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -40,11 +41,12 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "@zhin.js/logger": "1.0.75"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
@@ -52,16 +54,16 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/host-http": "1.0.2"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0",
-    "@zhin.js/agent": "1.0.5"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1",
+    "@zhin.js/agent": "1.0.6"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -96,6 +98,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,16 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerDefaultScenePlatformPermitChecker } from '@zhin.js/core';
+import { onebot11RuntimeStateToken } from './src/onebot11-runtime-state.js';
 
 export default definePlugin({
   name: 'onebot11',
   metadata: {
     displayName: 'OneBot 11 Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（onebot11 endpoint list 的"运行中"数据源）
+    context.resources.provide(onebot11RuntimeStateToken, createEndpointRuntimeState());
     // 平台权限门禁：scene_admin / scene_owner 由 sender role 判定（见 ws/wss-endpoint admit metadata）
     return registerDefaultScenePlatformPermitChecker('onebot11');
   },

package/src/endpoint-management.ts

@@ -0,0 +1,72 @@
+/**
+ * OneBot11 endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OneBot11 原生形状，仅保证数组
+ */
+import type {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointManagement,
+} from '@zhin.js/adapter';
+
+/** 管理面只依赖 endpoint 的 callApi（ws/wss 两种传输各自实现）。 */
+export interface OneBot11ManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createOneBot11EndpointManagement(
+  endpoint: OneBot11ManagementCaller,
+): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listFriends(): Promise<readonly EndpointFriend[]> {
+      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.nickname ?? ''),
+          remark: String(friend.remark ?? ''),
+        };
+      });
+    },
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      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: string): Promise<readonly unknown[]> {
+      const data = await endpoint.callApi('get_group_member_list', {
+        group_id: toNumberId(groupId, 'group_id'),
+      });
+      return toArray(data);
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function toArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+    throw new TypeError(`onebot11 ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   getChannelId,
   isMessageEvent,
   isOneBot11BotMentioned,
+  mediaRefToOneBotFile,
   parseSendTarget,
   resolveOneBot11Config,
   senderDisplayName,

package/src/onebot11-endpoint-commands.ts

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

package/src/onebot11-runtime-state.ts

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

package/src/protocol.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
+import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
 
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot11`). */
 export interface OneBot11LegacyEndpointRow {
@@ -292,9 +293,76 @@ export function formatInboundMetadata(
   });
 }
 
+/**
+ * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）。
+ */
+export function mediaRefToOneBotFile(media: MediaRef): string {
+  if (media.kind === 'base64') {
+    return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+  }
+  if (media.kind === 'path') {
+    return media.value.startsWith('file://') ? media.value : `file://${media.value}`;
+  }
+  return media.value;
+}
+
+/** 媒体段 data 里的 canonical-only 字段，不进 OneBot wire。 */
+const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt', 'url', 'base64', 'file', 'mime_type']);
+
+function oneBotMediaSegment(
+  type: 'image' | 'record' | 'video',
+  data: Record<string, unknown>,
+): OneBot11Segment {
+  const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+  if (!media) return { type, data };
+  const extra: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!MEDIA_DATA_SKIP_KEYS.has(key)) extra[key] = value;
+  }
+  return { type, data: { ...extra, file: mediaRefToOneBotFile(media) } };
+}
+
+/**
+ * canonical Segment → OneBot 11 数组段：
+ * - mention → at（`qq: target`）；
+ * - reply（`message_id`）→ reply（`id`）；
+ * - image / audio→record / video 的 MediaRef → `file`（url / base64:// / file://）；
+ * - face 取 `id`；
+ * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
+ */
+function canonicalToOneBotSegment(segment: OneBot11WireSegment): OneBot11Segment {
+  const data = segment.data ?? {};
+  switch (segment.type) {
+    case 'mention': {
+      const target = data.target ?? data.qq ?? data.id;
+      if (target == null) return { type: segment.type, data };
+      return { type: 'at', data: { qq: String(target) } };
+    }
+    case 'reply': {
+      const messageId = data.message_id ?? data.id;
+      if (messageId == null) return { type: segment.type, data };
+      return { type: 'reply', data: { id: String(messageId) } };
+    }
+    case 'face': {
+      if (data.id == null) return { type: segment.type, data };
+      return { type: 'face', data: { id: data.id } };
+    }
+    case 'image':
+    case 'record':
+    case 'video':
+      return oneBotMediaSegment(segment.type, data);
+    case 'audio':
+      return oneBotMediaSegment('record', data);
+    default:
+      return { type: segment.type, data };
+  }
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
  */
 export function formatOutboundSegments(payload: unknown): OneBot11Segment[] {
   if (typeof payload === 'string') {
@@ -322,7 +390,7 @@ export function formatOutboundSegments(payload: unknown): OneBot11Segment[] {
       segs.push({ type: 'text', data: { text: item } });
       continue;
     }
-    segs.push({ type: item.type, data: item.data ?? {} });
+    segs.push(canonicalToOneBotSegment(item));
   }
   return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }

package/src/ws-endpoint.ts

@@ -2,11 +2,17 @@
  * OneBot11 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { clearInterval, clearTimeout, setTimeout } from 'node:timers';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import {
+  createEndpointLifecycle,
+  type EndpointConnectHandle,
+  type EndpointInstance,
+  type EndpointLifecycle,
+  type EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import {
   buildSendAction,
@@ -24,7 +30,6 @@ import {
   callOneBot11WsAction,
   handleOneBot11WsMessage,
   rejectAllPending,
-  startOneBot11Heartbeat,
 } from './ws-transport.js';
 import {
   type OneBot11PendingAction,
@@ -46,29 +51,48 @@ export interface OneBot11WsEndpointOptions {
 
 export class OneBot11WsEndpoint implements EndpointInstance {
   readonly #options: OneBot11WsEndpointOptions;
+  readonly management: EndpointManagement = createOneBot11EndpointManagement(this);
+  readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot11WsSocket;
-  #reconnectTimer?: NodeJS.Timeout;
-  #heartbeatTimer?: NodeJS.Timeout;
   #requestId = { value: 0 };
   #pending = new Map<string, OneBot11PendingAction>();
   #open = false;
-  #started = false;
-  #stopping = false;
   #unregisterAgent?: () => void;
 
   constructor(options: OneBot11WsEndpointOptions) {
     this.#options = options;
+    const { config } = options;
+    this.#lifecycle = createEndpointLifecycle({
+      name: config.name,
+      reconnect: {
+        initialIntervalMs: config.reconnect_interval,
+        // 固定间隔（multiplier 1、无抖动），对齐旧 reconnect_interval 语义
+        multiplier: 1,
+        maxIntervalMs: config.reconnect_interval,
+        jitterMs: 0,
+      },
+      heartbeat: { intervalMs: config.heartbeat_interval },
+    });
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#stopping = false;
+    if (this.#lifecycle.started) return;
+    // agent 注册/反注册是适配器专有依赖，留在适配器侧（见 endpoint-lifecycle 迁移指引）
     this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.name, this);
     try {
-      await this.#connect();
+      await this.#lifecycle.start((handle) => this.#connect(handle));
     } catch (err) {
-      this.#started = false;
+      // start 失败必须清理现场（状态复位由基座保证），避免 agent 注册泄漏
+      if (this.#ws) {
+        try {
+          this.#ws.close();
+        } catch {
+          /* ignore */
+        }
+        this.#ws = undefined;
+      }
+      this.#unregisterAgent?.();
+      this.#unregisterAgent = undefined;
       throw err;
     }
   }
@@ -83,28 +107,12 @@ export class OneBot11WsEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
-    this.#stopping = true;
-    this.#started = false;
+    // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+    await this.#lifecycle.stop();
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
-    if (this.#reconnectTimer) {
-      clearTimeout(this.#reconnectTimer);
-      this.#reconnectTimer = undefined;
-    }
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-      this.#heartbeatTimer = undefined;
-    }
     rejectAllPending(this.#pending);
-    if (this.#ws) {
-      try {
-        this.#ws.close();
-      } catch {
-        /* ignore */
-      }
-      this.#ws = undefined;
-    }
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#ws = undefined;
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
@@ -162,7 +170,7 @@ export class OneBot11WsEndpoint implements EndpointInstance {
     });
   }
 
-  async #connect(): Promise<void> {
+  async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
     const create = this.#options.createWebSocket
       ?? ((connectUrl: string, options: OneBot11WsCreateOptions) =>
@@ -172,6 +180,13 @@ export class OneBot11WsEndpoint implements EndpointInstance {
       let settled = false;
       const ws = create(url, { headers });
       this.#ws = ws;
+      handle.onForceClose(() => {
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+      });
 
       ws.on('open', () => {
         if (settled) return;
@@ -188,13 +203,7 @@ export class OneBot11WsEndpoint implements EndpointInstance {
           mode: 'ws',
           url: safeUrl,
         }));
-        this.#heartbeatTimer = this.#stopping
-          ? this.#heartbeatTimer
-          : startOneBot11Heartbeat(
-            this.#ws,
-            this.#options.config.heartbeat_interval,
-            this.#heartbeatTimer,
-          );
+        this.#lifecycle.startHeartbeat(() => this.#ws?.ping?.());
         resolve();
       });
 
@@ -218,18 +227,13 @@ export class OneBot11WsEndpoint implements EndpointInstance {
           : codeNum === 1006
             ? ' [异常关闭]'
             : '';
-        logger.warn(formatCompact({
-          op: 'disconnect',
-          endpoint: this.#options.config.name,
-          code: codeNum,
-          error: `${reasonStr || 'closed'}${codeHint}`,
-          reconnect_ms: this.#options.config.reconnect_interval,
-        }));
         if (!settled) {
           settled = true;
           reject(new Error(`OneBot11 WS 关闭: ${codeNum} ${reasonStr}`));
         }
-        this.#scheduleReconnect();
+        // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+        // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
+        handle.notifyClosed(`OneBot11 WS 关闭: ${codeNum} ${reasonStr || 'closed'}${codeHint}`);
       });
 
       ws.on('error', (err) => {
@@ -247,20 +251,4 @@ export class OneBot11WsEndpoint implements EndpointInstance {
       });
     });
   }
-
-  #scheduleReconnect(): void {
-    if (this.#stopping || !this.#started || this.#reconnectTimer) return;
-    const delay = this.#options.config.reconnect_interval;
-    this.#reconnectTimer = setTimeout(() => {
-      this.#reconnectTimer = undefined;
-      void this.#connect().catch((err) => {
-        logger.warn(formatCompact({
-          op: 'reconnect',
-          endpoint: this.#options.config.name,
-          ok: false,
-          error: err instanceof Error ? err.message : String(err),
-        }));
-      });
-    }, delay);
-  }
 }

package/src/wss-endpoint.ts

@@ -2,11 +2,12 @@
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
 import { clearInterval } from 'node:timers';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import {
   buildSendAction,
@@ -43,6 +44,7 @@ export interface OneBot11WssEndpointOptions {
 
 export class OneBot11WssEndpoint implements EndpointInstance {
   readonly #options: OneBot11WssEndpointOptions;
+  readonly management: EndpointManagement = createOneBot11EndpointManagement(this);
   #ws?: OneBot11WsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;
@@ -59,6 +61,15 @@ export class OneBot11WssEndpoint implements EndpointInstance {
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
+    if (!this.#options.config.access_token) {
+      // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
+      logger.warn(formatCompact({
+        endpoint: this.#options.config.name,
+        mode: 'wss',
+        ok: false,
+        error: 'missing access_token',
+      }));
+    }
     this.#unregisterAgent = registerOnebot11AgentEndpoint(
       this.#options.config.name,
       this as unknown as OneBot11WsEndpoint,