@zhin.js/adapter-napcat 4.0.1 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @zhin.js/adapter-napcat
 
+## 5.0.1
+
+### Patch Changes
+
+- cdf64e7: 多方向审计修复批（8 面 30+ bug）：
+
+  - **安全**：钉钉 webhook 验签绕过修复（缺 timestamp/sign 一律 403 + ±1h 防重放）；exec-policy fail-closed（换行/`$(`/反引号拒绝、管道逐段过白名单、env dump 复合拆段）；wecom 验签改 timingSafeEqual；config:set 拒绝 `__proto__` 等魔术键、host 键优先防覆写。
+  - **P0 功能**：`zhin packages` scoped 包名解析为空导致 rm -rf 风险；命令数字参数解析失败炸断消息链路（dispatch 捕获 continue）；TaskQueue 监听器首个事件自摘除导致 assistant 队列挂死（+超时后完成不覆盖终态）；DatabaseHost 跨世代共享崩溃（define 幂等 + stop 改进程级）；rss 按不存在 id 列删除改业务键。
+  - **Runtime/HMR**：native watcher 过滤忽略目录（lib/.zhin 不再触发重载风暴）；host 段配置 patch（http.port 等）存在 installResources 时全量重建；capability 目录非 entry 支持文件升级进程重启；documentTransaction 失败回滚。
+  - **CLI 写侧**：config/setup 对 toml 静默假成功改统一 config-file（不支持格式报错）；doctor/onboard 默认配置改新形态 plugins 映射；schedule add 改 --prompt；migrate engines/中文模板误伤/覆盖前备份。
+  - **适配器生命周期**：napcat/milky start 失败竞态与僵尸连接、心跳 close 清理、stop-during-connect settle；slack webhook 二次 writeHead + messageChannelMap LRU。
+  - **Host/向导**：logs/stats 与 inbox 查询改 DB 侧 count/orderBy/limit 下推；save-yaml 写入前校验；zhipu/moonshot baseUrl 必填预填；.env 写入转义 + 幂等合并；setup 数据库密码不再明文落 config；60s fetch 超时与 JSON 守卫。
+
+- 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
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 4.0.1
 
 ### Patch Changes

package/README.md

@@ -34,11 +34,12 @@ pnpm add @zhin.js/adapter-napcat
 plugins:
   napcat:
     connection: ws
-    name: my-bot
-    url: "ws://127.0.0.1:3001"
-    access_token: "${NAPCAT_TOKEN}"
     reconnect_interval: 5000
     heartbeat_interval: 30000
+    endpoints:
+      - name: my-bot
+        url: "ws://127.0.0.1:3001"
+        access_token: "${NAPCAT_TOKEN}"
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-napcat`（`instanceKey: napcat`）。

package/adapters/napcat.ts

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

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

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

package/commands/endpoint/list.ts

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

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

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

package/lib/endpoint-management.d.ts

@@ -0,0 +1,15 @@
+/**
+ * NapCat 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/http 三种传输各自实现）。 */
+export interface NapCatManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createNapCatEndpointManagement(endpoint: NapCatManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createNapCatEndpointManagement(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(`napcat ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/http-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';
@@ -12,6 +12,7 @@ export interface NapCatHttpEndpointOptions {
 }
 export declare class NapCatHttpEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: NapCatHttpEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/http-endpoint.js

@@ -1,4 +1,5 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
@@ -8,6 +9,7 @@ const logger = getLogger('napcat');
 export class NapCatHttpEndpoint {
     #options;
     #inboundDeduper = new InboundMessageDeduper();
+    management = createNapCatEndpointManagement(this);
     #callHttpAction;
     #routeReleases = [];
     #open = false;

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, type NapCatAdapterConfig, type NapCatConfigBase, type NapCatEndpointConfig, type NapCatEvent, type NapCatHttpConfig, type NapCatMessageEvent, type NapCatSender, type NapCatWireSegment, type NapCatWsConfig, type NapCatWssConfig, type ParsedSendTarget, type ResolvedNapCatConfig, } from './protocol.js';
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, type NapCatAdapterConfig, type NapCatConfigBase, type NapCatEndpointConfig, type NapCatEvent, type NapCatHttpConfig, type NapCatMessageEvent, type NapCatSender, type NapCatWireSegment, type NapCatWsConfig, type NapCatWssConfig, type ParsedSendTarget, type ResolvedNapCatConfig, } from './protocol.js';
 export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 export { getEndpoint, getNapcatAgentDeps, registerNapcatAgentEndpoint, setNapcatAgentDeps, type NapcatAgentDeps, type NapcatAgentEndpoint, } from './napcat-agent-deps.js';
 export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
 export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 export { getEndpoint, getNapcatAgentDeps, registerNapcatAgentEndpoint, setNapcatAgentDeps, } from './napcat-agent-deps.js';
 export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';

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

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

package/lib/napcat-endpoint-commands.js

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

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

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

package/lib/napcat-runtime-state.js

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

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import { type MediaRef } from '@zhin.js/core';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: napcat`). */
 export interface NapCatLegacyEndpointRow {
     readonly context?: string;
@@ -125,9 +126,15 @@ export declare function formatInboundContent(ev: NapCatEvent): string;
 export declare function senderUserId(ev: NapCatEvent): string;
 /** 显示名（群名片 card 优先于 nickname），没有则 undefined。 */
 export declare function senderNickname(ev: NapCatEvent): string | undefined;
+/**
+ * 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 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
  */
 export declare function formatOutboundSegments(payload: unknown): MessageSegment[];
 export declare function buildSendAction(target: string, message: MessageSegment[]): {

package/lib/protocol.js

@@ -3,6 +3,7 @@
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
 function normalizeConnection(connection) {
     if (connection === 'wss' || connection === 'http')
         return connection;
@@ -118,9 +119,74 @@ export function senderNickname(ev) {
     const name = ev.sender?.card || ev.sender?.nickname;
     return typeof name === 'string' && name ? name : undefined;
 }
+/**
+ * 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`；
+ * - 其余（NapCat 扩展段、已是 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 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') {
@@ -145,7 +211,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 NapCatEvent, type NapCatWsConfig } from './protocol.js';
@@ -11,6 +11,7 @@ export interface NapCatWsEndpointOptions {
 }
 export declare class NapCatWsEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: NapCatWsEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/ws-endpoint.js

@@ -2,39 +2,48 @@
  * NapCat WS client endpoint — outbound connect to NapCat.
  */
 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 { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
-import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
+import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, } from './ws-transport.js';
 const logger = getLogger('napcat');
 export class NapCatWsEndpoint {
     #options;
     #inboundDeduper = new InboundMessageDeduper();
+    management = createNapCatEndpointManagement(this);
+    #lifecycle;
     #ws;
-    #reconnectTimer;
-    #heartbeatTimer;
     #requestId = { value: 0 };
     #pending = new Map();
     #open = false;
-    #started = false;
-    #stopping = false;
     #unregisterAgent;
     constructor(options) {
         this.#options = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.name,
+            // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+            reconnect: {
+                initialIntervalMs: options.config.reconnect_interval,
+                multiplier: 1,
+                maxIntervalMs: Number.MAX_SAFE_INTEGER,
+                jitterMs: 0,
+            },
+        });
     }
     async start() {
-        if (this.#started)
+        if (this.#lifecycle.started)
             return;
-        this.#started = true;
-        this.#stopping = false;
         this.#unregisterAgent = registerNapcatAgentEndpoint(this.#options.config.name, this);
         try {
-            await this.#connect();
+            await this.#lifecycle.start((handle) => this.#connect(handle));
         }
         catch (err) {
-            this.#started = false;
+            // start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，留在适配器侧
+            this.#unregisterAgent?.();
+            this.#unregisterAgent = undefined;
             throw err;
         }
     }
@@ -46,18 +55,9 @@ export class NapCatWsEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#stopping = true;
-        this.#started = false;
+        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);
         this.#inboundDeduper.clear();
         if (this.#ws) {
@@ -69,7 +69,6 @@ export class NapCatWsEndpoint {
             }
             this.#ws = undefined;
         }
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
         const message = formatOutboundSegments(payload);
@@ -262,7 +261,7 @@ export class NapCatWsEndpoint {
             }));
         });
     }
-    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 }));
@@ -270,6 +269,14 @@ export class NapCatWsEndpoint {
             let settled = false;
             const ws = create(url, { headers });
             this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
             ws.on('open', () => {
                 if (settled)
                     return;
@@ -286,9 +293,17 @@ export class NapCatWsEndpoint {
                     mode: 'ws',
                     url: safeUrl,
                 }));
-                this.#heartbeatTimer = this.#stopping
-                    ? this.#heartbeatTimer
-                    : startNapCatHeartbeat(this.#ws, this.#options.config.heartbeat_interval, this.#heartbeatTimer);
+                // stop-during-connect 竞态：已停止则不再武装心跳（基座 stop 已清理定时器）
+                if (this.#lifecycle.started) {
+                    this.#lifecycle.startHeartbeat(() => {
+                        try {
+                            ws.ping?.();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }, this.#options.config.heartbeat_interval);
+                }
                 resolve();
             });
             ws.on('message', (data) => {
@@ -317,11 +332,12 @@ export class NapCatWsEndpoint {
                     error: `${reasonStr || 'closed'}${codeHint}`,
                     reconnect_ms: this.#options.config.reconnect_interval,
                 }));
+                // 基座语义：仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+                handle.notifyClosed(new Error(`NapCat WS closed: ${codeNum} ${reasonStr}`));
                 if (!settled) {
                     settled = true;
                     reject(new Error(`NapCat WS closed: ${codeNum} ${reasonStr}`));
                 }
-                this.#scheduleReconnect();
             });
             ws.on('error', (err) => {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -338,20 +354,4 @@ export class NapCatWsEndpoint {
             });
         });
     }
-    #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 NapCatWssEndpointOptions {
 }
 export declare class NapCatWssEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: NapCatWssEndpointOptions);
     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 { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
@@ -12,6 +13,7 @@ const logger = getLogger('napcat');
 export class NapCatWssEndpoint {
     #options;
     #inboundDeduper = new InboundMessageDeduper();
+    management = createNapCatEndpointManagement(this);
     #ws;
     #wsRelease;
     #heartbeatTimer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "4.0.1",
+  "version": "5.0.1",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -42,11 +43,12 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@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.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
@@ -54,16 +56,16 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/host-http": "1.0.1"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3",
-    "@zhin.js/agent": "1.0.4"
+    "@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": {
@@ -98,6 +100,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 { napcatRuntimeStateToken } from './src/napcat-runtime-state.js';
 
 export default definePlugin({
   name: 'napcat',
   metadata: {
     displayName: 'NapCat Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（napcat endpoint list 的"运行中"数据源）
+    context.resources.provide(napcatRuntimeStateToken, createEndpointRuntimeState());
     // 平台权限门禁：scene_admin / scene_owner 由 sender role 判定（见各 endpoint admit metadata）
     return registerDefaultScenePlatformPermitChecker('napcat');
   },

package/schema.json

@@ -5,33 +5,14 @@
   "properties": {
     "connection": {
       "type": "string",
-      "enum": ["ws", "wss", "http"],
+      "enum": [
+        "ws",
+        "wss",
+        "http"
+      ],
       "default": "ws",
       "description": "ws (default), wss (reverse WS), or http (POST webhook + HTTP API outbound)"
     },
-    "name": {
-      "type": "string",
-      "default": "napcat-bot"
-    },
-    "url": {
-      "type": "string",
-      "description": "NapCat WebSocket URL (required for connection: ws)"
-    },
-    "path": {
-      "type": "string",
-      "description": "WS path for reverse-wss"
-    },
-    "http_url": {
-      "type": "string",
-      "description": "HTTP API base URL (connection: http outbound)"
-    },
-    "post_path": {
-      "type": "string",
-      "description": "HTTP POST event path (connection: http inbound)"
-    },
-    "access_token": {
-      "type": "string"
-    },
     "reconnect_interval": {
       "type": "number",
       "default": 5000
@@ -43,6 +24,51 @@
     "poll_interval": {
       "type": "number",
       "default": 30000
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "NapCat bot name"
+          },
+          "url": {
+            "type": "string",
+            "description": "NapCat WebSocket URL (required for connection: ws)"
+          },
+          "path": {
+            "type": "string",
+            "description": "WS path for reverse-wss"
+          },
+          "http_url": {
+            "type": "string",
+            "description": "HTTP API base URL (connection: http outbound)"
+          },
+          "post_path": {
+            "type": "string",
+            "description": "HTTP POST event path (connection: http inbound)"
+          },
+          "access_token": {
+            "type": "string",
+            "description": "NapCat access token"
+          }
+        },
+        "required": [
+          "name"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
-  }
+  },
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint-management.ts

@@ -0,0 +1,72 @@
+/**
+ * NapCat 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/http 三种传输各自实现）。 */
+export interface NapCatManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createNapCatEndpointManagement(
+  endpoint: NapCatManagementCaller,
+): 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(`napcat ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}

package/src/http-endpoint.ts

@@ -2,11 +2,12 @@
  * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-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, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import {
   InboundMessageDeduper,
@@ -43,6 +44,7 @@ export interface NapCatHttpEndpointOptions {
 export class NapCatHttpEndpoint implements EndpointInstance {
   readonly #options: NapCatHttpEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly management: EndpointManagement = createNapCatEndpointManagement(this);
   readonly #callHttpAction: typeof callNapCatHttpAction;
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;

package/src/index.ts

@@ -7,6 +7,7 @@ export {
   formatOutboundSegments,
   getChannelId,
   isMessageEvent,
+  mediaRefToOneBotFile,
   parseSendTarget,
   resolveNapCatConfig,
   senderNickname,

package/src/napcat-endpoint-commands.ts

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

package/src/napcat-runtime-state.ts

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

package/src/protocol.ts

@@ -3,6 +3,7 @@
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
 
 /** Transitional legacy endpoint row (`endpoints[]` with `context: napcat`). */
 export interface NapCatLegacyEndpointRow {
@@ -253,9 +254,76 @@ export function senderNickname(ev: NapCatEvent): string | undefined {
   return typeof name === 'string' && name ? name : undefined;
 }
 
+/**
+ * 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>,
+): MessageSegment {
+  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`；
+ * - 其余（NapCat 扩展段、已是 wire 形状的段）原样透传。
+ */
+function canonicalToOneBotSegment(segment: NapCatWireSegment): MessageSegment {
+  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 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
  */
 export function formatOutboundSegments(payload: unknown): MessageSegment[] {
   if (typeof payload === 'string') {
@@ -283,7 +351,7 @@ export function formatOutboundSegments(payload: unknown): MessageSegment[] {
       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 @@
  * NapCat WS client endpoint — outbound connect to NapCat.
  */
 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 { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import {
   InboundMessageDeduper,
@@ -30,7 +36,6 @@ import {
   callNapCatWsAction,
   handleNapCatWsMessage,
   rejectAllPending,
-  startNapCatHeartbeat,
 } from './ws-transport.js';
 import {
   type NapCatPendingAction,
@@ -53,29 +58,37 @@ export interface NapCatWsEndpointOptions {
 export class NapCatWsEndpoint implements EndpointInstance {
   readonly #options: NapCatWsEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly management: EndpointManagement = createNapCatEndpointManagement(this);
+  readonly #lifecycle: EndpointLifecycle;
   #ws?: NapCatWsSocket;
-  #reconnectTimer?: NodeJS.Timeout;
-  #heartbeatTimer?: NodeJS.Timeout;
   #requestId = { value: 0 };
   #pending = new Map<string, NapCatPendingAction>();
   #open = false;
-  #started = false;
-  #stopping = false;
   #unregisterAgent?: () => void;
 
   constructor(options: NapCatWsEndpointOptions) {
     this.#options = options;
+    this.#lifecycle = createEndpointLifecycle({
+      name: options.config.name,
+      // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+      reconnect: {
+        initialIntervalMs: options.config.reconnect_interval,
+        multiplier: 1,
+        maxIntervalMs: Number.MAX_SAFE_INTEGER,
+        jitterMs: 0,
+      },
+    });
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#stopping = false;
+    if (this.#lifecycle.started) return;
     this.#unregisterAgent = registerNapcatAgentEndpoint(this.#options.config.name, this);
     try {
-      await this.#connect();
+      await this.#lifecycle.start((handle) => this.#connect(handle));
     } catch (err) {
-      this.#started = false;
+      // start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，留在适配器侧
+      this.#unregisterAgent?.();
+      this.#unregisterAgent = undefined;
       throw err;
     }
   }
@@ -90,18 +103,9 @@ export class NapCatWsEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
-    this.#stopping = true;
-    this.#started = false;
+    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);
     this.#inboundDeduper.clear();
     if (this.#ws) {
@@ -112,7 +116,6 @@ export class NapCatWsEndpoint implements EndpointInstance {
       }
       this.#ws = undefined;
     }
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
@@ -348,7 +351,7 @@ export class NapCatWsEndpoint 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: NapCatWsCreateOptions) =>
@@ -358,6 +361,13 @@ export class NapCatWsEndpoint 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;
@@ -374,13 +384,16 @@ export class NapCatWsEndpoint implements EndpointInstance {
           mode: 'ws',
           url: safeUrl,
         }));
-        this.#heartbeatTimer = this.#stopping
-          ? this.#heartbeatTimer
-          : startNapCatHeartbeat(
-            this.#ws,
-            this.#options.config.heartbeat_interval,
-            this.#heartbeatTimer,
-          );
+        // stop-during-connect 竞态：已停止则不再武装心跳（基座 stop 已清理定时器）
+        if (this.#lifecycle.started) {
+          this.#lifecycle.startHeartbeat(() => {
+            try {
+              ws.ping?.();
+            } catch {
+              /* ignore */
+            }
+          }, this.#options.config.heartbeat_interval);
+        }
         resolve();
       });
 
@@ -411,11 +424,12 @@ export class NapCatWsEndpoint implements EndpointInstance {
           error: `${reasonStr || 'closed'}${codeHint}`,
           reconnect_ms: this.#options.config.reconnect_interval,
         }));
+        // 基座语义：仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+        handle.notifyClosed(new Error(`NapCat WS closed: ${codeNum} ${reasonStr}`));
         if (!settled) {
           settled = true;
           reject(new Error(`NapCat WS closed: ${codeNum} ${reasonStr}`));
         }
-        this.#scheduleReconnect();
       });
 
       ws.on('error', (err) => {
@@ -433,20 +447,4 @@ export class NapCatWsEndpoint 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 @@
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 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 { createNapCatEndpointManagement } from './endpoint-management.js';
 import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
 import {
   InboundMessageDeduper,
@@ -50,6 +51,7 @@ export interface NapCatWssEndpointOptions {
 export class NapCatWssEndpoint implements EndpointInstance {
   readonly #options: NapCatWssEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
+  readonly management: EndpointManagement = createNapCatEndpointManagement(this);
   #ws?: NapCatWsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;