@zhin.js/adapter-satori 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @zhin.js/adapter-satori
 
+## 4.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 动态注册）职责边界已文档化。
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 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 注明平台无列表面暂不接。
+- 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/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
+
 ## 4.0.0
 
 ### Patch Changes

package/adapters/satori.ts

@@ -9,6 +9,7 @@ import {
   resolveSatoriConfig,
   type SatoriAdapterConfig,
 } from '../src/protocol.js';
+import { satoriRuntimeStateToken } from '../src/satori-runtime-state.js';
 
 export { SatoriWebhookEndpoint, SatoriWsEndpoint } from '../src/endpoint.js';
 export type {
@@ -21,9 +22,19 @@ export type {
 
 export default defineAdapter<SatoriAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // Satori 协议 img/file 元素消费 url 与 base64 内联数据；无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'base64'],
+    interactive: 'text',
+  },
   create(context) {
     const config = resolveSatoriConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（satori endpoint list 的"运行中"数据源）
+    context.use(satoriRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.connection,
+    });
     if (config.connection === 'webhook') {
       return new SatoriWebhookEndpoint({
         id: context.id,

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

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

package/commands/endpoint/list.ts

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

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

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

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-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 { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -17,6 +17,7 @@ export interface SatoriWsEndpointOptions {
 }
 export declare class SatoriWsEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: SatoriWsEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -41,6 +42,7 @@ export interface SatoriWebhookEndpointOptions {
 }
 export declare class SatoriWebhookEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: SatoriWebhookEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
@@ -58,4 +60,10 @@ export declare class SatoriWebhookEndpoint implements EndpointInstance {
     /** Test helper: inject login without a live webhook push. */
     setLogin(login: SatoriLogin): void;
 }
+export type SatoriManagementApi = (resource: string, method: string, params: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
+ * 数据走协议 API：guild.list / channel.list / guild-member.list。
+ */
+export declare function createSatoriEndpointManagement(api: SatoriManagementApi): EndpointManagement;
 export type { CreateSatoriWebSocket, SatoriWsSocket } from './ws.js';

package/lib/endpoint.js

@@ -1,3 +1,7 @@
+/**
+ * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
+ */
+import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isSelfMentioned, parseMessageRef, resolveInboundSender, resolveInboundTarget, } from './protocol.js';
 import { registerSatoriWebhookRoutes } from './webhook.js';
@@ -5,23 +9,48 @@ import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
 const logger = getLogger('satori');
 export class SatoriWsEndpoint {
     #options;
+    #lifecycle;
     #ws = null;
     #login;
     #lastSn;
-    #reconnectTimer = null;
-    #heartbeatTimer = null;
     #open = false;
-    #started = false;
-    #stopping = false;
+    management = createSatoriEndpointManagement((resource, method, params) => this.#api(resource, method, params));
     constructor(options) {
         this.#options = options;
+        const { config } = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: config.name,
+            reconnect: {
+                initialIntervalMs: 5_000,
+                // 固定间隔（multiplier 1、无抖动），对齐旧 5s 固定重连语义
+                multiplier: 1,
+                maxIntervalMs: 5_000,
+                jitterMs: 0,
+            },
+            heartbeat: {
+                intervalMs: config.heartbeat_interval,
+                // PONG 看门狗：连续 2 轮无回包，下一轮心跳由基座强关连接触发重连
+                watchdogMisses: 2,
+            },
+        });
     }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
-        this.#stopping = false;
-        await this.#connect();
+        try {
+            await this.#lifecycle.start((handle) => this.#connect(handle));
+        }
+        catch (err) {
+            // start 失败清理现场（状态复位由基座保证）
+            if (this.#ws) {
+                try {
+                    this.#ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = null;
+            }
+            throw err;
+        }
     }
     open() {
         this.#open = true;
@@ -31,23 +60,9 @@ export class SatoriWsEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#stopping = true;
-        this.#clearReconnect();
-        this.#clearHeartbeat();
-        if (this.#ws) {
-            try {
-                this.#ws.close();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#ws = null;
-        }
-        this.#started = false;
-        logger.debug(formatCompact({
-            op: 'disconnect',
-            endpoint: this.#options.config.name,
-        }));
+        // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+        await this.#lifecycle.stop();
+        this.#ws = null;
     }
     async send({ target, payload }) {
         const content = formatSatoriOutbound(payload);
@@ -111,7 +126,7 @@ export class SatoriWsEndpoint {
     setLogin(login) {
         this.#login = login;
     }
-    async #connect() {
+    async #connect(handle) {
         const { config } = this.#options;
         const createWs = this.#options.createWebSocket ?? defaultCreateWebSocket;
         const headers = {};
@@ -121,13 +136,21 @@ export class SatoriWsEndpoint {
             let settled = false;
             const ws = createWs(buildWsUrl(config.baseUrl, config.token), { headers });
             this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            });
             ws.on('open', () => {
                 logger.debug(formatCompact({ endpoint: config.name, mode: 'ws' }));
                 this.#sendSignal(SatoriOpcode.IDENTIFY, {
                     token: config.token,
                     sn: this.#lastSn,
                 });
-                this.#startHeartbeat();
+                this.#lifecycle.startHeartbeat(() => this.#sendSignal(SatoriOpcode.PING));
                 if (!settled) {
                     settled = true;
                     resolve();
@@ -152,27 +175,19 @@ export class SatoriWsEndpoint {
                 }
             });
             ws.on('close', (code, reason) => {
-                this.#clearHeartbeat();
                 const reasonStr = typeof reason === 'string'
                     ? reason
                     : Buffer.isBuffer(reason)
                         ? reason.toString('utf8')
                         : String(reason ?? '');
                 const numericCode = typeof code === 'number' ? code : 0;
-                logger.warn(formatCompact({
-                    op: 'disconnect',
-                    endpoint: config.name,
-                    code: numericCode,
-                    error: reasonStr || 'closed',
-                    reconnect_ms: this.#stopping ? undefined : 5000,
-                }));
                 if (!settled) {
                     settled = true;
                     reject(new Error(`Satori WS closed: ${numericCode} ${reasonStr}`));
-                    return;
                 }
-                if (!this.#stopping)
-                    this.#scheduleReconnect();
+                // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+                // 初始连接失败由 start() 的拒绝路径复位。
+                handle.notifyClosed(`Satori WS closed: ${numericCode} ${reasonStr || 'closed'}`);
             });
             ws.on('error', (error) => {
                 logger.warn(formatCompact({
@@ -189,6 +204,11 @@ export class SatoriWsEndpoint {
         });
     }
     #handleSignal(signal) {
+        if (signal.op === SatoriOpcode.PONG) {
+            // 喂狗：复位基座看门狗计数
+            this.#lifecycle.notifyHeartbeatAck();
+            return;
+        }
         if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
             const logins = signal.body.logins;
             this.#login = logins[0];
@@ -208,40 +228,6 @@ export class SatoriWsEndpoint {
             return;
         this.#ws.send(JSON.stringify({ op, body: body ?? {} }));
     }
-    #startHeartbeat() {
-        this.#clearHeartbeat();
-        const interval = this.#options.config.heartbeat_interval;
-        this.#heartbeatTimer = setInterval(() => {
-            this.#sendSignal(SatoriOpcode.PING);
-        }, interval);
-    }
-    #scheduleReconnect() {
-        if (this.#reconnectTimer || this.#stopping)
-            return;
-        this.#reconnectTimer = setTimeout(() => {
-            this.#reconnectTimer = null;
-            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),
-                }));
-            });
-        }, 5000);
-    }
-    #clearReconnect() {
-        if (this.#reconnectTimer) {
-            clearTimeout(this.#reconnectTimer);
-            this.#reconnectTimer = null;
-        }
-    }
-    #clearHeartbeat() {
-        if (this.#heartbeatTimer) {
-            clearInterval(this.#heartbeatTimer);
-            this.#heartbeatTimer = null;
-        }
-    }
     #apiOptions() {
         return {
             baseUrl: this.#options.config.baseUrl,
@@ -261,6 +247,7 @@ export class SatoriWebhookEndpoint {
     #routeReleases = [];
     #open = false;
     #started = false;
+    management = createSatoriEndpointManagement((resource, method, params) => this.#api(resource, method, params));
     constructor(options) {
         this.#options = options;
     }
@@ -275,6 +262,15 @@ export class SatoriWebhookEndpoint {
         if (this.#started)
             return;
         this.#started = true;
+        if (!this.#options.config.token) {
+            // 未配 token 时 webhook 无鉴权：任何人知道 path 即可注入假事件。
+            logger.warn(formatCompact({
+                op: 'webhook_no_token',
+                endpoint: this.#options.config.name,
+                path: this.#options.config.path,
+                hint: 'set token to authenticate Satori webhook callbacks',
+            }));
+        }
         this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
         logger.info(formatCompact({
             op: 'listen',
@@ -377,3 +373,83 @@ function isPrivateChannelType(body) {
     const channel = body.channel ?? body.message?.channel;
     return channel?.type === 1;
 }
+/**
+ * Satori guild id 是平台相关字符串（多数平台为雪花号，超
+ * Number.MAX_SAFE_INTEGER）。Console 社交面只把 group_id 当 JSON 值透传、
+ * 并以字符串回传给 listGroupMembers，因此保留原始字符串（仅按契约类型
+ * 声明强转）是全链路最不丢信息的方案。
+ */
+function toGroupId(id) {
+    return id;
+}
+/** Satori 分页列表（{data, next?}）聚合；兼容直接返回数组的实现。 */
+async function listSatoriPages(api, resource, params) {
+    const items = [];
+    let next;
+    do {
+        const page = await api(resource, 'list', next ? { ...params, next } : params);
+        if (Array.isArray(page)) {
+            items.push(...page);
+            break;
+        }
+        const typed = (page ?? {});
+        if (Array.isArray(typed.data))
+            items.push(...typed.data);
+        next = typeof typed.next === 'string' && typed.next ? typed.next : undefined;
+    } while (next);
+    return items;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+/**
+ * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
+ * 数据走协议 API：guild.list / channel.list / guild-member.list。
+ */
+export function createSatoriEndpointManagement(api) {
+    return Object.freeze({
+        async listGroups() {
+            const groups = [];
+            for (const value of await listSatoriPages(api, 'guild', {})) {
+                const guild = asRecord(value);
+                if (guild.id == null)
+                    continue;
+                groups.push({
+                    group_id: toGroupId(String(guild.id)),
+                    name: String(guild.name ?? guild.id),
+                });
+            }
+            return groups;
+        },
+        async listChannels() {
+            const channels = [];
+            for (const value of await listSatoriPages(api, 'guild', {})) {
+                const guild = asRecord(value);
+                if (guild.id == null)
+                    continue;
+                const guildId = String(guild.id);
+                const guildName = String(guild.name ?? guildId);
+                for (const channelValue of await listSatoriPages(api, 'channel', { guild_id: guildId })) {
+                    const channel = asRecord(channelValue);
+                    if (channel.id == null)
+                        continue;
+                    // Channel.type: 0=TEXT 1=DIRECT 2=CATEGORY 3=VOICE；缺省按 TEXT 处理
+                    if (channel.type != null && Number(channel.type) !== 0)
+                        continue;
+                    channels.push({
+                        id: String(channel.id),
+                        name: channel.name != null ? String(channel.name) : undefined,
+                        parent: { type: 'guild', id: guildId, name: guildName },
+                    });
+                }
+            }
+            return channels;
+        },
+        async listGroupMembers(groupId) {
+            // 平台形状（GuildMember[]）原样返回
+            return listSatoriPages(api, 'guild-member', { guild_id: groupId });
+        },
+    });
+}

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

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

package/lib/satori-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `satori endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { satoriRuntimeStateToken } from './satori-runtime-state.js';
+export const satoriEndpointCommands = createEndpointCommands({
+    adapterKey: 'satori',
+    adapterDisplayName: 'Satori',
+    fields: [
+        { key: 'baseUrl', required: true, description: 'Satori 服务 base URL' },
+        { key: 'path', description: 'webhook 路径（connection: webhook）' },
+        { key: 'token', env: true, description: 'Satori access token' },
+    ],
+    running: (use) => use(satoriRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
+}, defineCommand);

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

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

package/lib/satori-runtime-state.js

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

package/lib/webhook.d.ts

@@ -1,6 +1,3 @@
-/**
- * Satori webhook HTTP: token → opcode → parse → admit.
- */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { type ResolvedSatoriWebhookConfig, type SatoriEventBody, type SatoriLogin } from './protocol.js';

package/lib/webhook.js

@@ -1,3 +1,7 @@
+/**
+ * Satori webhook HTTP: token → opcode → parse → admit.
+ */
+import { timingSafeEqual } from 'node:crypto';
 import { getLogger } from '@zhin.js/logger';
 import { SatoriOpcode, } from './protocol.js';
 const logger = getLogger('satori');
@@ -61,7 +65,9 @@ export function verifySatoriToken(token, request) {
     if (!token)
         return true;
     const auth = request.headers.authorization ?? '';
-    return auth === `Bearer ${token}`;
+    const expected = Buffer.from(`Bearer ${token}`, 'utf8');
+    const actual = Buffer.from(auth, 'utf8');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
 }
 export async function readRequestBody(request) {
     const chunks = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -38,24 +39,25 @@
   },
   "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/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.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.2"
+    "@zhin.js/host-http": "1.0.3"
   },
   "peerDependencies": {
-    "@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/adapter": "1.1.1",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -84,6 +86,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,8 +1,14 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
+import { satoriRuntimeStateToken } from './src/satori-runtime-state.js';
 
 export default definePlugin({
   name: 'satori',
   metadata: {
     displayName: 'Satori Adapter',
   },
+  setup(context) {
+    // 运行中 endpoint 注册表（satori endpoint list 的"运行中"数据源）
+    context.resources.provide(satoriRuntimeStateToken, createEndpointRuntimeState());
+  },
 });

package/src/endpoint.ts

@@ -1,7 +1,15 @@
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import {
+  createEndpointLifecycle,
+  type EndpointChannel,
+  type EndpointConnectHandle,
+  type EndpointGroup,
+  type EndpointInstance,
+  type EndpointLifecycle,
+  type 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';
@@ -48,24 +56,50 @@ export interface SatoriWsEndpointOptions {
 
 export class SatoriWsEndpoint implements EndpointInstance {
   readonly #options: SatoriWsEndpointOptions;
+  readonly #lifecycle: EndpointLifecycle;
   #ws: SatoriWsSocket | null = null;
   #login: SatoriLogin | undefined;
   #lastSn: number | undefined;
-  #reconnectTimer: NodeJS.Timeout | null = null;
-  #heartbeatTimer: NodeJS.Timeout | null = null;
   #open = false;
-  #started = false;
-  #stopping = false;
+  readonly management: EndpointManagement = createSatoriEndpointManagement(
+    (resource, method, params) => this.#api(resource, method, params),
+  );
 
   constructor(options: SatoriWsEndpointOptions) {
     this.#options = options;
+    const { config } = options;
+    this.#lifecycle = createEndpointLifecycle({
+      name: config.name,
+      reconnect: {
+        initialIntervalMs: 5_000,
+        // 固定间隔（multiplier 1、无抖动），对齐旧 5s 固定重连语义
+        multiplier: 1,
+        maxIntervalMs: 5_000,
+        jitterMs: 0,
+      },
+      heartbeat: {
+        intervalMs: config.heartbeat_interval,
+        // PONG 看门狗：连续 2 轮无回包，下一轮心跳由基座强关连接触发重连
+        watchdogMisses: 2,
+      },
+    });
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#stopping = false;
-    await this.#connect();
+    try {
+      await this.#lifecycle.start((handle) => this.#connect(handle));
+    } catch (err) {
+      // start 失败清理现场（状态复位由基座保证）
+      if (this.#ws) {
+        try {
+          this.#ws.close();
+        } catch {
+          /* ignore */
+        }
+        this.#ws = null;
+      }
+      throw err;
+    }
   }
 
   open(): void {
@@ -78,22 +112,9 @@ export class SatoriWsEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
-    this.#stopping = true;
-    this.#clearReconnect();
-    this.#clearHeartbeat();
-    if (this.#ws) {
-      try {
-        this.#ws.close();
-      } catch {
-        /* ignore */
-      }
-      this.#ws = null;
-    }
-    this.#started = false;
-    logger.debug(formatCompact({
-      op: 'disconnect',
-      endpoint: this.#options.config.name,
-    }));
+    // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+    await this.#lifecycle.stop();
+    this.#ws = null;
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
@@ -159,7 +180,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
     this.#login = login;
   }
 
-  async #connect(): Promise<void> {
+  async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { config } = this.#options;
     const createWs = this.#options.createWebSocket ?? defaultCreateWebSocket;
     const headers: Record<string, string> = {};
@@ -169,6 +190,13 @@ export class SatoriWsEndpoint implements EndpointInstance {
       let settled = false;
       const ws = createWs(buildWsUrl(config.baseUrl, config.token), { headers });
       this.#ws = ws;
+      handle.onForceClose(() => {
+        try {
+          ws.close();
+        } catch {
+          /* already closed */
+        }
+      });
 
       ws.on('open', () => {
         logger.debug(formatCompact({ endpoint: config.name, mode: 'ws' }));
@@ -176,7 +204,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
           token: config.token,
           sn: this.#lastSn,
         });
-        this.#startHeartbeat();
+        this.#lifecycle.startHeartbeat(() => this.#sendSignal(SatoriOpcode.PING));
         if (!settled) {
           settled = true;
           resolve();
@@ -202,26 +230,19 @@ export class SatoriWsEndpoint implements EndpointInstance {
       });
 
       ws.on('close', (code, reason) => {
-        this.#clearHeartbeat();
         const reasonStr = typeof reason === 'string'
           ? reason
           : Buffer.isBuffer(reason)
             ? reason.toString('utf8')
             : String(reason ?? '');
         const numericCode = typeof code === 'number' ? code : 0;
-        logger.warn(formatCompact({
-          op: 'disconnect',
-          endpoint: config.name,
-          code: numericCode,
-          error: reasonStr || 'closed',
-          reconnect_ms: this.#stopping ? undefined : 5000,
-        }));
         if (!settled) {
           settled = true;
           reject(new Error(`Satori WS closed: ${numericCode} ${reasonStr}`));
-          return;
         }
-        if (!this.#stopping) this.#scheduleReconnect();
+        // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+        // 初始连接失败由 start() 的拒绝路径复位。
+        handle.notifyClosed(`Satori WS closed: ${numericCode} ${reasonStr || 'closed'}`);
       });
 
       ws.on('error', (error) => {
@@ -240,6 +261,11 @@ export class SatoriWsEndpoint implements EndpointInstance {
   }
 
   #handleSignal(signal: SatoriSignal): void {
+    if (signal.op === SatoriOpcode.PONG) {
+      // 喂狗：复位基座看门狗计数
+      this.#lifecycle.notifyHeartbeatAck();
+      return;
+    }
     if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
       const logins = signal.body.logins as SatoriLogin[];
       this.#login = logins[0];
@@ -259,43 +285,6 @@ export class SatoriWsEndpoint implements EndpointInstance {
     this.#ws.send(JSON.stringify({ op, body: body ?? {} }));
   }
 
-  #startHeartbeat(): void {
-    this.#clearHeartbeat();
-    const interval = this.#options.config.heartbeat_interval;
-    this.#heartbeatTimer = setInterval(() => {
-      this.#sendSignal(SatoriOpcode.PING);
-    }, interval);
-  }
-
-  #scheduleReconnect(): void {
-    if (this.#reconnectTimer || this.#stopping) return;
-    this.#reconnectTimer = setTimeout(() => {
-      this.#reconnectTimer = null;
-      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),
-        }));
-      });
-    }, 5000);
-  }
-
-  #clearReconnect(): void {
-    if (this.#reconnectTimer) {
-      clearTimeout(this.#reconnectTimer);
-      this.#reconnectTimer = null;
-    }
-  }
-
-  #clearHeartbeat(): void {
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-      this.#heartbeatTimer = null;
-    }
-  }
-
   #apiOptions(): SatoriApiOptions {
     return {
       baseUrl: this.#options.config.baseUrl,
@@ -329,6 +318,9 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
   #started = false;
+  readonly management: EndpointManagement = createSatoriEndpointManagement(
+    (resource, method, params) => this.#api(resource, method, params),
+  );
 
   constructor(options: SatoriWebhookEndpointOptions) {
     this.#options = options;
@@ -346,6 +338,15 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
+    if (!this.#options.config.token) {
+      // 未配 token 时 webhook 无鉴权：任何人知道 path 即可注入假事件。
+      logger.warn(formatCompact({
+        op: 'webhook_no_token',
+        endpoint: this.#options.config.name,
+        path: this.#options.config.path,
+        hint: 'set token to authenticate Satori webhook callbacks',
+      }));
+    }
     this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
     logger.info(formatCompact({
       op: 'listen',
@@ -459,4 +460,98 @@ function isPrivateChannelType(body: SatoriEventBody): boolean {
   return channel?.type === 1;
 }
 
+/**
+ * Satori guild id 是平台相关字符串（多数平台为雪花号，超
+ * Number.MAX_SAFE_INTEGER）。Console 社交面只把 group_id 当 JSON 值透传、
+ * 并以字符串回传给 listGroupMembers，因此保留原始字符串（仅按契约类型
+ * 声明强转）是全链路最不丢信息的方案。
+ */
+function toGroupId(id: string): number {
+  return id as unknown as number;
+}
+
+export type SatoriManagementApi = (
+  resource: string,
+  method: string,
+  params: Record<string, unknown>,
+) => Promise<unknown>;
+
+interface SatoriListPage {
+  readonly data?: unknown[];
+  readonly next?: string;
+}
+
+/** Satori 分页列表（{data, next?}）聚合；兼容直接返回数组的实现。 */
+async function listSatoriPages(
+  api: SatoriManagementApi,
+  resource: string,
+  params: Record<string, unknown>,
+): Promise<unknown[]> {
+  const items: unknown[] = [];
+  let next: string | undefined;
+  do {
+    const page = await api(resource, 'list', next ? { ...params, next } : params);
+    if (Array.isArray(page)) {
+      items.push(...page);
+      break;
+    }
+    const typed = (page ?? {}) as SatoriListPage;
+    if (Array.isArray(typed.data)) items.push(...typed.data);
+    next = typeof typed.next === 'string' && typed.next ? typed.next : undefined;
+  } while (next);
+  return items;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+/**
+ * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
+ * 数据走协议 API：guild.list / channel.list / guild-member.list。
+ */
+export function createSatoriEndpointManagement(api: SatoriManagementApi): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      const groups: EndpointGroup[] = [];
+      for (const value of await listSatoriPages(api, 'guild', {})) {
+        const guild = asRecord(value);
+        if (guild.id == null) continue;
+        groups.push({
+          group_id: toGroupId(String(guild.id)),
+          name: String(guild.name ?? guild.id),
+        });
+      }
+      return groups;
+    },
+    async listChannels(): Promise<readonly EndpointChannel[]> {
+      const channels: EndpointChannel[] = [];
+      for (const value of await listSatoriPages(api, 'guild', {})) {
+        const guild = asRecord(value);
+        if (guild.id == null) continue;
+        const guildId = String(guild.id);
+        const guildName = String(guild.name ?? guildId);
+        for (const channelValue of await listSatoriPages(api, 'channel', { guild_id: guildId })) {
+          const channel = asRecord(channelValue);
+          if (channel.id == null) continue;
+          // Channel.type: 0=TEXT 1=DIRECT 2=CATEGORY 3=VOICE；缺省按 TEXT 处理
+          if (channel.type != null && Number(channel.type) !== 0) continue;
+          channels.push({
+            id: String(channel.id),
+            name: channel.name != null ? String(channel.name) : undefined,
+            parent: { type: 'guild', id: guildId, name: guildName },
+          });
+        }
+      }
+      return channels;
+    },
+    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
+      // 平台形状（GuildMember[]）原样返回
+      return listSatoriPages(api, 'guild-member', { guild_id: groupId });
+    },
+  });
+}
+
 export type { CreateSatoriWebSocket, SatoriWsSocket } from './ws.js';

package/src/satori-endpoint-commands.ts

@@ -0,0 +1,19 @@
+/**
+ * `satori endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { satoriRuntimeStateToken } from './satori-runtime-state.js';
+
+export const satoriEndpointCommands = createEndpointCommands({
+  adapterKey: 'satori',
+  adapterDisplayName: 'Satori',
+  fields: [
+    { key: 'baseUrl', required: true, description: 'Satori 服务 base URL' },
+    { key: 'path', description: 'webhook 路径（connection: webhook）' },
+    { key: 'token', env: true, description: 'Satori access token' },
+  ],
+  running: (use) => use(satoriRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
+}, defineCommand);

package/src/satori-runtime-state.ts

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

package/src/webhook.ts

@@ -1,6 +1,7 @@
 /**
  * Satori webhook HTTP: token → opcode → parse → admit.
  */
+import { timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { getLogger } from '@zhin.js/logger';
@@ -85,7 +86,9 @@ export function resolveSatoriOpcode(request: IncomingMessage): number | undefine
 export function verifySatoriToken(token: string | undefined, request: IncomingMessage): boolean {
   if (!token) return true;
   const auth = request.headers.authorization ?? '';
-  return auth === `Bearer ${token}`;
+  const expected = Buffer.from(`Bearer ${token}`, 'utf8');
+  const actual = Buffer.from(auth, 'utf8');
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
 }
 
 export async function readRequestBody(request: IncomingMessage): Promise<string> {