@zhin.js/adapter-satori 5.0.1 → 5.0.4

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @zhin.js/adapter-satori
 
+## 5.0.4
+
+### Patch Changes
+
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [162fa34]
+- Updated dependencies [e40b048]
+- Updated dependencies [f1708c3]
+- Updated dependencies [e53444f]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [a7df753]
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 5.0.3
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - zhin.js@6.0.2
+
 ## 5.0.1
 
 ### Patch Changes

package/README.md

@@ -27,8 +27,8 @@ pnpm add @zhin.js/adapter-satori
 - `@zhin.js/host-http` — Webhook 模式需 `httpHostToken` 注册 POST 路由
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`baseUrl` / `token` / …）
 
-入站：`gateway.receive({ adapter, target: channelId, content: text, sender, id, metadata })`  
-出站：`send({ target: channelId, payload })` → Satori `message.create`（payload 已由 gateway/core 渲染；无 segment-mapper）
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef：DIRECT 频道 → kind `private`，其余 → kind `group`、所属 guild 进 `parent`）  
+出站：`send({ conversation, payload })` → Satori `message.create`（`channel_id = conversation.id`；payload 已由 gateway/core 渲染；无 segment-mapper）
 
 入站 `metadata.mentioned`：消息 content 中 `<at id="…"/>` 元素的 id 等于登录 selfId（READY/事件 `login.user.id`）时置 `true`。
 

package/adapters/satori.js

@@ -20,8 +20,8 @@ export default defineAdapter({
         const config = resolveSatoriConfig(context.config);
         const gateway = context.use(messageGatewayToken);
         // 注册到插件运行时状态（satori.endpoint list 的"运行中"数据源）
-        context.use(satoriRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: config.connection,
         });
         if (config.connection === 'webhook') {

package/adapters/satori.ts

@@ -31,8 +31,8 @@ export default defineAdapter<SatoriAdapterConfig>({
     const config = resolveSatoriConfig(context.config);
     const gateway = context.use(messageGatewayToken);
     // 注册到插件运行时状态（satori.endpoint list 的"运行中"数据源）
-    context.use(satoriRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: config.connection,
     });
     if (config.connection === 'webhook') {

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } 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';
@@ -23,10 +23,7 @@ export declare class SatoriWsEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a gateway event when the endpoint is open. */
     admit(body: SatoriEventBody): void;
     recall(id: string): Promise<void>;
@@ -51,10 +48,7 @@ export declare class SatoriWebhookEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     admit(body: SatoriEventBody): void;
     recall(id: string): Promise<void>;
     /** Test helper: inject login without a live webhook push. */

package/lib/endpoint.js

@@ -2,12 +2,12 @@
  * 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 { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isSelfMentioned, parseMessageRef, resolveInboundSender, satoriInboundConversation, } from './protocol.js';
 import { registerSatoriWebhookRoutes } from './webhook.js';
 import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
-const logger = getLogger('satori');
 export class SatoriWsEndpoint {
+    #logger;
     #options;
     #lifecycle;
     #ws = null;
@@ -16,10 +16,11 @@ export class SatoriWsEndpoint {
     #open = false;
     management = createSatoriEndpointManagement((resource, method, params) => this.#api(resource, method, params));
     constructor(options) {
+        this.#logger = getAdapterLogger('satori', options.config.id);
         this.#options = options;
         const { config } = options;
         this.#lifecycle = createEndpointLifecycle({
-            name: config.name,
+            name: config.id,
             reconnect: {
                 initialIntervalMs: 5_000,
                 // 固定间隔（multiplier 1、无抖动），对齐旧 5s 固定重连语义
@@ -64,20 +65,20 @@ export class SatoriWsEndpoint {
         await this.#lifecycle.stop();
         this.#ws = null;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const content = formatSatoriOutbound(payload);
         const result = await this.#api('message', 'create', {
-            channel_id: target,
+            channel_id: conversation.id,
             content,
         });
         const msgId = extractCreatedMessageId(result);
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
             op: 'satori_send',
-            endpoint: this.#options.config.name,
-            target,
+            endpoint: this.#options.config.id,
+            channel: conversation.id,
             messageId: msgId || undefined,
         }));
-        return msgId ? formatMessageId(target, msgId) : '';
+        return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
     /** Test / internal: admit a gateway event when the endpoint is open. */
     admit(body) {
@@ -87,30 +88,28 @@ export class SatoriWsEndpoint {
             this.#login = body.login;
         if (!isMessageEvent(body))
             return;
-        const target = resolveInboundTarget(body);
+        const conversation = satoriInboundConversation(String(this.#options.id), body);
         const content = formatInboundContent(body);
         const sender = resolveInboundSender(body);
-        const messageId = formatMessageId(target, body.message.id);
         const selfId = this.#login?.user?.id ?? body.login?.user?.id;
         const mentioned = isSelfMentioned(body, selfId);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: body.message.id },
             content,
             sender,
-            id: messageId,
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
             metadata: Object.freeze({
                 type: body.type,
                 channelType: isPrivateChannelType(body) ? 'private' : 'group',
                 sn: body.sn,
                 platform: this.#login?.platform,
-                endpoint: this.#options.config.name,
-                ...(mentioned ? { mentioned: true } : {}),
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'satori_gateway_receive_failed',
-                target,
+                channel: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -145,7 +144,7 @@ export class SatoriWsEndpoint {
                 }
             });
             ws.on('open', () => {
-                logger.debug(formatCompact({ endpoint: config.name, mode: 'ws' }));
+                this.#logger.debug(formatCompact({ mode: 'ws' }));
                 this.#sendSignal(SatoriOpcode.IDENTIFY, {
                     token: config.token,
                     sn: this.#lastSn,
@@ -167,9 +166,9 @@ export class SatoriWsEndpoint {
                     this.#handleSignal(signal);
                 }
                 catch (error) {
-                    logger.warn(formatCompact({
+                    this.#logger.warn(formatCompact({
                         op: 'ws_parse_error',
-                        endpoint: config.name,
+                        endpoint: config.id,
                         error: error instanceof Error ? error.message : String(error),
                     }));
                 }
@@ -190,9 +189,9 @@ export class SatoriWsEndpoint {
                 handle.notifyClosed(`Satori WS closed: ${numericCode} ${reasonStr || 'closed'}`);
             });
             ws.on('error', (error) => {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'ws_error',
-                    endpoint: config.name,
+                    endpoint: config.id,
                     ok: false,
                     error: error instanceof Error ? error.message : String(error),
                 }));
@@ -213,7 +212,7 @@ export class SatoriWsEndpoint {
             const logins = signal.body.logins;
             this.#login = logins[0];
             if (!this.#login?.platform || !this.#login?.user?.id) {
-                logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
+                this.#logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
             }
             return;
         }
@@ -242,6 +241,7 @@ export class SatoriWsEndpoint {
     }
 }
 export class SatoriWebhookEndpoint {
+    #logger;
     #options;
     #login;
     #routeReleases = [];
@@ -249,6 +249,7 @@ export class SatoriWebhookEndpoint {
     #started = false;
     management = createSatoriEndpointManagement((resource, method, params) => this.#api(resource, method, params));
     constructor(options) {
+        this.#logger = getAdapterLogger('satori', options.config.id);
         this.#options = options;
     }
     /** Used by webhook handler. */
@@ -264,17 +265,17 @@ export class SatoriWebhookEndpoint {
         this.#started = true;
         if (!this.#options.config.token) {
             // 未配 token 时 webhook 无鉴权：任何人知道 path 即可注入假事件。
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'webhook_no_token',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 path: this.#options.config.path,
                 hint: 'set token to authenticate Satori webhook callbacks',
             }));
         }
         this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
-        logger.info(formatCompact({
+        this.#logger.info(formatCompact({
             op: 'listen',
-            endpoint: this.#options.config.name,
+            endpoint: this.#options.config.id,
             mode: 'webhook',
             path: this.#options.config.path,
         }));
@@ -290,25 +291,24 @@ export class SatoriWebhookEndpoint {
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
             op: 'disconnect',
-            endpoint: this.#options.config.name,
         }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const content = formatSatoriOutbound(payload);
         const result = await this.#api('message', 'create', {
-            channel_id: target,
+            channel_id: conversation.id,
             content,
         });
         const msgId = extractCreatedMessageId(result);
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
             op: 'satori_send',
-            endpoint: this.#options.config.name,
-            target,
+            endpoint: this.#options.config.id,
+            channel: conversation.id,
             messageId: msgId || undefined,
         }));
-        return msgId ? formatMessageId(target, msgId) : '';
+        return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
     admit(body) {
         if (!this.#open)
@@ -317,30 +317,28 @@ export class SatoriWebhookEndpoint {
             this.#login = body.login;
         if (!isMessageEvent(body))
             return;
-        const target = resolveInboundTarget(body);
+        const conversation = satoriInboundConversation(String(this.#options.id), body);
         const content = formatInboundContent(body);
         const sender = resolveInboundSender(body);
-        const messageId = formatMessageId(target, body.message.id);
         const selfId = this.#login?.user?.id ?? body.login?.user?.id;
         const mentioned = isSelfMentioned(body, selfId);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: body.message.id },
             content,
             sender,
-            id: messageId,
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
             metadata: Object.freeze({
                 type: body.type,
                 channelType: isPrivateChannelType(body) ? 'private' : 'group',
                 sn: body.sn,
                 platform: this.#login?.platform,
-                endpoint: this.#options.config.name,
-                ...(mentioned ? { mentioned: true } : {}),
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'satori_gateway_receive_failed',
-                target,
+                channel: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isPrivateChannel, parseMessageRef, resolveInboundSender, resolveInboundTarget, resolveSatoriConfig, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriAdapterConfig, type SatoriApiOptions, type SatoriChannel, type SatoriEventBody, type SatoriLogin, type SatoriMessage, type SatoriSignal, type SatoriUser, type SatoriWireSegment, } from './protocol.js';
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriAdapterConfig, type SatoriApiOptions, type SatoriChannel, type SatoriEventBody, type SatoriLogin, type SatoriMessage, type SatoriSignal, type SatoriUser, type SatoriWireSegment, } from './protocol.js';
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, type CreateSatoriWebSocket, type SatoriApiCaller, type SatoriWebhookEndpointOptions, type SatoriWsEndpointOptions, type SatoriWsSocket, } from './endpoint.js';
 export { handleSatoriWebhookRequest, readRequestBody, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, type SatoriWebhookHandler, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isPrivateChannel, parseMessageRef, resolveInboundSender, resolveInboundTarget, resolveSatoriConfig, } from './protocol.js';
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, } from './protocol.js';
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, } from './endpoint.js';
 export { handleSatoriWebhookRequest, readRequestBody, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://satori.chat/zh-CN/protocol/overview.html
  */
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
 export declare const SatoriOpcode: {
     readonly EVENT: 0;
@@ -77,7 +78,7 @@ export interface SatoriWireSegment {
 }
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface SatoriAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly connection?: 'ws' | 'webhook';
     readonly baseUrl?: string;
     readonly token?: string;
@@ -94,7 +95,7 @@ export interface SatoriAdapterConfig {
 export interface ResolvedSatoriWsConfig {
     readonly context: 'satori';
     readonly connection: 'ws';
-    readonly name: string;
+    readonly id: string;
     readonly baseUrl: string;
     readonly token?: string;
     readonly heartbeat_interval: number;
@@ -102,7 +103,7 @@ export interface ResolvedSatoriWsConfig {
 export interface ResolvedSatoriWebhookConfig {
     readonly context: 'satori';
     readonly connection: 'webhook';
-    readonly name: string;
+    readonly id: string;
     readonly baseUrl: string;
     readonly token?: string;
     readonly path: string;
@@ -124,12 +125,19 @@ export declare function callSatoriApi<T = unknown>(options: SatoriApiOptions, re
 export declare function formatInboundContent(body: SatoriEventBody & {
     message: SatoriMessage;
 }): string;
-export declare function resolveInboundTarget(body: SatoriEventBody & {
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export declare function satoriInboundConversation(endpointKey: string, body: SatoriEventBody & {
     message: SatoriMessage;
-}): string;
+}): ConversationRef;
 export declare function resolveInboundSender(body: SatoriEventBody & {
     message: SatoriMessage;
-}): string;
+}): {
+    id: string;
+    name?: string;
+};
 /**
  * Detect `<at id="…"/>` elements in message content targeting the bot selfId.
  * selfId 来源：READY/事件携带的 `login.user.id`。

package/lib/protocol.js

@@ -23,8 +23,8 @@ export function resolveSatoriConfig(config = {}) {
     if (!baseUrl) {
         throw new TypeError('Satori adapter requires baseUrl (plugins.<key>.baseUrl or endpoints with context: satori)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.SATORI_BOT_NAME
         || 'satori-bot';
     const token = (typeof config.token === 'string' && config.token)
@@ -39,7 +39,7 @@ export function resolveSatoriConfig(config = {}) {
         return {
             context: 'satori',
             connection: 'webhook',
-            name,
+            id,
             baseUrl,
             token,
             path,
@@ -51,7 +51,7 @@ export function resolveSatoriConfig(config = {}) {
     return {
         context: 'satori',
         connection: 'ws',
-        name,
+        id,
         baseUrl,
         token,
         heartbeat_interval: heartbeat,
@@ -113,13 +113,27 @@ export function formatInboundContent(body) {
     const content = body.message.content ?? '';
     return typeof content === 'string' ? content : String(content);
 }
-export function resolveInboundTarget(body) {
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export function satoriInboundConversation(endpointKey, body) {
     const channel = body.channel ?? body.message.channel;
-    return channel?.id ?? '';
+    const kind = isPrivateChannel(channel) ? 'private' : 'group';
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind,
+        id: channel?.id ?? '',
+        ...(kind === 'group' && body.guild?.id
+            ? { parent: { kind: 'channel', id: body.guild.id } }
+            : {}),
+    };
 }
 export function resolveInboundSender(body) {
     const user = body.user ?? body.message.user ?? body.message.member?.user;
-    return user?.name ?? body.message.member?.nick ?? user?.id ?? '';
+    const name = user?.name ?? body.message.member?.nick;
+    const id = user?.id ?? name ?? '';
+    return name && name !== id ? { id, name } : { id };
 }
 /**
  * Detect `<at id="…"/>` elements in message content targeting the bot selfId.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "5.0.1",
+  "version": "5.0.4",
   "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,25 +39,26 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.5"
+    "@zhin.js/host-http": "1.0.8"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/schema.json

@@ -17,16 +17,48 @@
       "default": 10000,
       "description": "WS PING interval in milliseconds"
     },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（platform user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted platform user id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "Satori bot name"
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（platform user id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted platform user id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
           },
           "baseUrl": {
             "type": "string",
@@ -39,10 +71,14 @@
           "path": {
             "type": "string",
             "description": "Webhook POST path (connection: webhook)"
+          },
+          "id": {
+            "type": "string",
+            "description": "Satori bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "baseUrl"
         ]
       }

package/src/endpoint.ts

@@ -9,10 +9,11 @@ import {
   type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
+  type EndpointSendRequest,
 } 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 { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import {
   SatoriOpcode,
@@ -26,7 +27,7 @@ import {
   isSelfMentioned,
   parseMessageRef,
   resolveInboundSender,
-  resolveInboundTarget,
+  satoriInboundConversation,
   type ResolvedSatoriWebhookConfig,
   type ResolvedSatoriWsConfig,
   type SatoriApiOptions,
@@ -42,8 +43,6 @@ import {
   type SatoriWsSocket,
 } from './ws.js';
 
-const logger = getLogger('satori');
-
 export type SatoriApiCaller = typeof callSatoriApi;
 
 export interface SatoriWsEndpointOptions {
@@ -55,6 +54,8 @@ export interface SatoriWsEndpointOptions {
 }
 
 export class SatoriWsEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: SatoriWsEndpointOptions;
   readonly #lifecycle: EndpointLifecycle;
   #ws: SatoriWsSocket | null = null;
@@ -66,10 +67,11 @@ export class SatoriWsEndpoint implements EndpointInstance {
   );
 
   constructor(options: SatoriWsEndpointOptions) {
+    this.#logger = getAdapterLogger('satori', options.config.id);
     this.#options = options;
     const { config } = options;
     this.#lifecycle = createEndpointLifecycle({
-      name: config.name,
+      name: config.id,
       reconnect: {
         initialIntervalMs: 5_000,
         // 固定间隔（multiplier 1、无抖动），对齐旧 5s 固定重连语义
@@ -117,20 +119,20 @@ export class SatoriWsEndpoint implements EndpointInstance {
     this.#ws = null;
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const content = formatSatoriOutbound(payload);
     const result = await this.#api('message', 'create', {
-      channel_id: target,
+      channel_id: conversation.id,
       content,
     });
     const msgId = extractCreatedMessageId(result);
-    logger.debug(formatCompact({
+    this.#logger.debug(formatCompact({
       op: 'satori_send',
-      endpoint: this.#options.config.name,
-      target,
+      endpoint: this.#options.config.id,
+      channel: conversation.id,
       messageId: msgId || undefined,
     }));
-    return msgId ? formatMessageId(target, msgId) : '';
+    return msgId ? formatMessageId(conversation.id, msgId) : '';
   }
 
   /** Test / internal: admit a gateway event when the endpoint is open. */
@@ -138,30 +140,28 @@ export class SatoriWsEndpoint implements EndpointInstance {
     if (!this.#open) return;
     if (body.login && !this.#login) this.#login = body.login;
     if (!isMessageEvent(body)) return;
-    const target = resolveInboundTarget(body);
+    const conversation = satoriInboundConversation(String(this.#options.id), body);
     const content = formatInboundContent(body);
     const sender = resolveInboundSender(body);
-    const messageId = formatMessageId(target, body.message.id);
     const selfId = this.#login?.user?.id ?? body.login?.user?.id;
     const mentioned = isSelfMentioned(body, selfId);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: body.message.id },
       content,
       sender,
-      id: messageId,
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
         type: body.type,
         channelType: isPrivateChannelType(body) ? 'private' : 'group',
         sn: body.sn,
         platform: this.#login?.platform,
-        endpoint: this.#options.config.name,
-        ...(mentioned ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'satori_gateway_receive_failed',
-        target,
+        channel: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -199,7 +199,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
       });
 
       ws.on('open', () => {
-        logger.debug(formatCompact({ endpoint: config.name, mode: 'ws' }));
+        this.#logger.debug(formatCompact({ mode: 'ws' }));
         this.#sendSignal(SatoriOpcode.IDENTIFY, {
           token: config.token,
           sn: this.#lastSn,
@@ -221,9 +221,9 @@ export class SatoriWsEndpoint implements EndpointInstance {
           const signal = JSON.parse(raw) as SatoriSignal;
           this.#handleSignal(signal);
         } catch (error) {
-          logger.warn(formatCompact({
+          this.#logger.warn(formatCompact({
             op: 'ws_parse_error',
-            endpoint: config.name,
+            endpoint: config.id,
             error: error instanceof Error ? error.message : String(error),
           }));
         }
@@ -246,9 +246,9 @@ export class SatoriWsEndpoint implements EndpointInstance {
       });
 
       ws.on('error', (error) => {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'ws_error',
-          endpoint: config.name,
+          endpoint: config.id,
           ok: false,
           error: error instanceof Error ? error.message : String(error),
         }));
@@ -270,7 +270,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
       const logins = signal.body.logins as SatoriLogin[];
       this.#login = logins[0];
       if (!this.#login?.platform || !this.#login?.user?.id) {
-        logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
+        this.#logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
       }
       return;
     }
@@ -313,6 +313,8 @@ export interface SatoriWebhookEndpointOptions {
 }
 
 export class SatoriWebhookEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: SatoriWebhookEndpointOptions;
   #login: SatoriLogin | undefined;
   #routeReleases: HttpRouteRegistration[] = [];
@@ -323,6 +325,7 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
   );
 
   constructor(options: SatoriWebhookEndpointOptions) {
+    this.#logger = getAdapterLogger('satori', options.config.id);
     this.#options = options;
   }
 
@@ -340,17 +343,17 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     this.#started = true;
     if (!this.#options.config.token) {
       // 未配 token 时 webhook 无鉴权：任何人知道 path 即可注入假事件。
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'webhook_no_token',
-        endpoint: this.#options.config.name,
+        endpoint: this.#options.config.id,
         path: this.#options.config.path,
         hint: 'set token to authenticate Satori webhook callbacks',
       }));
     }
     this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
-    logger.info(formatCompact({
+    this.#logger.info(formatCompact({
       op: 'listen',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       mode: 'webhook',
       path: this.#options.config.path,
     }));
@@ -368,56 +371,53 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
-    logger.debug(formatCompact({
-      op: 'disconnect',
-      endpoint: this.#options.config.name,
+    this.#logger.debug(formatCompact({
+          op: 'disconnect',
     }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const content = formatSatoriOutbound(payload);
     const result = await this.#api('message', 'create', {
-      channel_id: target,
+      channel_id: conversation.id,
       content,
     });
     const msgId = extractCreatedMessageId(result);
-    logger.debug(formatCompact({
+    this.#logger.debug(formatCompact({
       op: 'satori_send',
-      endpoint: this.#options.config.name,
-      target,
+      endpoint: this.#options.config.id,
+      channel: conversation.id,
       messageId: msgId || undefined,
     }));
-    return msgId ? formatMessageId(target, msgId) : '';
+    return msgId ? formatMessageId(conversation.id, msgId) : '';
   }
 
   admit(body: SatoriEventBody): void {
     if (!this.#open) return;
     if (body.login && !this.#login) this.#login = body.login;
     if (!isMessageEvent(body)) return;
-    const target = resolveInboundTarget(body);
+    const conversation = satoriInboundConversation(String(this.#options.id), body);
     const content = formatInboundContent(body);
     const sender = resolveInboundSender(body);
-    const messageId = formatMessageId(target, body.message.id);
     const selfId = this.#login?.user?.id ?? body.login?.user?.id;
     const mentioned = isSelfMentioned(body, selfId);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: body.message.id },
       content,
       sender,
-      id: messageId,
+      endpointId: this.#options.config.id,
+      ...(mentioned ? { mentioned: true } : {}),
       metadata: Object.freeze({
         type: body.type,
         channelType: isPrivateChannelType(body) ? 'private' : 'group',
         sn: body.sn,
         platform: this.#login?.platform,
-        endpoint: this.#options.config.name,
-        ...(mentioned ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'satori_gateway_receive_failed',
-        target,
+        channel: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/index.ts

@@ -4,14 +4,12 @@ export {
   callSatoriApi,
   extractCreatedMessageId,
   formatInboundContent,
-  formatMessageId,
   formatSatoriOutbound,
   isMessageEvent,
   isPrivateChannel,
-  parseMessageRef,
   resolveInboundSender,
-  resolveInboundTarget,
   resolveSatoriConfig,
+  satoriInboundConversation,
   type ResolvedSatoriWebhookConfig,
   type ResolvedSatoriWsConfig,
   type SatoriAdapterConfig,

package/src/protocol.ts

@@ -6,6 +6,7 @@
 
 import { pickCredential } from '@zhin.js/adapter';
 import { isMediaRef } from '@zhin.js/core';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('satori');
@@ -83,7 +84,7 @@ export interface SatoriWireSegment {
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface SatoriAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly connection?: 'ws' | 'webhook';
   readonly baseUrl?: string;
   readonly token?: string;
@@ -101,7 +102,7 @@ export interface SatoriAdapterConfig {
 export interface ResolvedSatoriWsConfig {
   readonly context: 'satori';
   readonly connection: 'ws';
-  readonly name: string;
+  readonly id: string;
   readonly baseUrl: string;
   readonly token?: string;
   readonly heartbeat_interval: number;
@@ -110,7 +111,7 @@ export interface ResolvedSatoriWsConfig {
 export interface ResolvedSatoriWebhookConfig {
   readonly context: 'satori';
   readonly connection: 'webhook';
-  readonly name: string;
+  readonly id: string;
   readonly baseUrl: string;
   readonly token?: string;
   readonly path: string;
@@ -127,8 +128,8 @@ export function resolveSatoriConfig(config: SatoriAdapterConfig = {}): ResolvedS
       'Satori adapter requires baseUrl (plugins.<key>.baseUrl or endpoints with context: satori)',
     );
   }
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.SATORI_BOT_NAME
     || 'satori-bot';
   const token = (typeof config.token === 'string' && config.token)
@@ -144,7 +145,7 @@ export function resolveSatoriConfig(config: SatoriAdapterConfig = {}): ResolvedS
     return {
       context: 'satori',
       connection: 'webhook',
-      name,
+      id,
       baseUrl,
       token,
       path,
@@ -157,7 +158,7 @@ export function resolveSatoriConfig(config: SatoriAdapterConfig = {}): ResolvedS
   return {
     context: 'satori',
     connection: 'ws',
-    name,
+    id,
     baseUrl,
     token,
     heartbeat_interval: heartbeat,
@@ -227,14 +228,34 @@ export function formatInboundContent(body: SatoriEventBody & { message: SatoriMe
   return typeof content === 'string' ? content : String(content);
 }
 
-export function resolveInboundTarget(body: SatoriEventBody & { message: SatoriMessage }): string {
+
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export function satoriInboundConversation(
+  endpointKey: string,
+  body: SatoriEventBody & { message: SatoriMessage },
+): ConversationRef {
   const channel = body.channel ?? body.message.channel;
-  return channel?.id ?? '';
+  const kind: ConversationKind = isPrivateChannel(channel) ? 'private' : 'group';
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind,
+    id: channel?.id ?? '',
+    ...(kind === 'group' && body.guild?.id
+      ? { parent: { kind: 'channel' as const, id: body.guild.id } }
+      : {}),
+  };
 }
 
-export function resolveInboundSender(body: SatoriEventBody & { message: SatoriMessage }): string {
+export function resolveInboundSender(
+  body: SatoriEventBody & { message: SatoriMessage },
+): { id: string; name?: string } {
   const user = body.user ?? body.message.user ?? body.message.member?.user;
-  return user?.name ?? body.message.member?.nick ?? user?.id ?? '';
+  const name = user?.name ?? body.message.member?.nick;
+  const id = user?.id ?? name ?? '';
+  return name && name !== id ? { id, name } : { id };
 }
 
 /**