@zhin.js/adapter-satori 1.0.1 → 1.1.2

package/README.md

@@ -1,63 +1,81 @@
 # @zhin.js/adapter-satori
 
-Zhin.js [Satori](https://satori.chat/zh-CN/introduction.html) **聊天协议**适配器，**一个适配器**支持 WebSocket 正向与 Webhook 两种连接方式，由配置项 `connection` 区分；支持 HTTP API 与 Bearer Token 鉴权。
+Zhin.js [Satori](https://satori.chat/zh-CN/introduction.html) **聊天协议**适配器（Plugin Runtime）。支持 **WebSocket 正向客户端**（`connection: ws`）与 **Webhook 入站**（`connection: webhook`，经 `httpHostToken` POST 路由）。
 
 > **勿与本仓库的 `@zhin.js/satori` 混淆**：后者是 [Vercel satori](https://github.com/vercel/satori) 的 **SVG 图片渲染**工具包（`packages/toolkit/satori`），用于把 HTML/React 画成 SVG，**不是**聊天协议。参见 [@zhin.js/satori README](https://github.com/zhinjs/zhin/tree/main/packages/toolkit/satori)。
 
 ## 功能特性
 
 - 🔌 [Satori 协议](https://satori.chat/zh-CN/introduction.html) 兼容
-- 📦 **单一适配器**：`context: satori`，通过 `connection` 选择连接方式
-- 🌐 **WebSocket 正向**（`connection: ws`）：应用连 SDK `ws(s)://baseUrl/v1/events`
-- 📮 **Webhook**（`connection: webhook`）：应用提供 POST 端点收事件
+- 🌐 **WebSocket 正向**（`connection: ws`，默认）：应用连 SDK `ws(s)://baseUrl`，IDENTIFY + 心跳
 - 🔐 Bearer Token 鉴权（API 与 WS IDENTIFY）
 - 📨 频道 / 私聊消息收发，消息 id 格式为 `channelId:messageId`
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- **Webhook**（`connection: webhook`）：SDK POST `Satori-Opcode: 0` 事件到 `path`
 
 ## 安装
 
 ```bash
-pnpm add @zhin.js/adapter-satori ws
+pnpm add @zhin.js/adapter-satori
 ```
 
-Webhook 方式需启用 `@zhin.js/host-router`（适配器依赖 router 注册）：
+## Plugin Runtime
 
-```bash
-pnpm add @zhin.js/host-router
-```
+- `@zhin.js/adapter` — 约定式 `adapters/satori/index.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- `@zhin.js/host-http` — Webhook 模式需 `httpHostToken` 注册 POST 路由
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`baseUrl` / `token` / …）
+
+入站：`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`。
+
+每个 Endpoint 的 `$client` 是 `@imhelper/satori-v1` 的 `SatoriV1Client`。业务代码直接调用
+`$client.call(resource, method, params)` 或其公开便捷方法；Client 负责协议事件变换，Endpoint
+只负责 Satori IDENTIFY/心跳、Webhook 鉴权和 Zhin 投影。
 
-## 配置
+## 前置条件
 
-所有 Endpoint 使用 **同一 context：`satori`**，通过 **`connection`** 区分连接方式。
+1. 准备兼容 Satori 的服务端，记录 API Base、平台标识和用户标识。
+2. 正向 WS 需 Zhin 可达 Satori 服务；Webhook 需服务端可达 Zhin HTTP Host。
+3. 若服务启用鉴权，在两端配置相同的 Bearer token。
 
-### WebSocket 正向
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-satori"
-
-endpoints:
-  - context: satori
+  satori:
     connection: ws
-    name: satori-bot
-    baseUrl: "http://127.0.0.1:5140"
-    token: "${SATORI_TOKEN}"
     heartbeat_interval: 10000
+    endpoints:
+      - id: satori-bot
+        baseUrl: "http://127.0.0.1:5140"
+        token: "${SATORI_TOKEN}"
 ```
 
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-satori`（`instanceKey: satori`）。
+
+### 可选字段
+
+| 字段 | 说明 |
+|------|------|
+| `heartbeat_interval` | WS PING 间隔（毫秒），默认 `10000` |
+| `token` | Bearer；可在 YAML 中引用 `${SATORI_TOKEN}` |
+
 ### Webhook
 
 ```yaml
 plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-satori"
-
-endpoints:
-  - context: satori
+  satori:
     connection: webhook
-    name: satori-webhook-bot
-    baseUrl: "http://satori-sdk 地址"
-    path: "/satori/webhook"
-    token: "${SATORI_TOKEN}"
+    endpoints:
+      - id: satori-bot
+        baseUrl: "http://127.0.0.1:5140"
+        path: "/satori/webhook"
+        token: "${SATORI_TOKEN}"
 ```
 
 SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；适配器从首个事件的 `login` 取得 platform / userId 用于后续 API 调用。
@@ -67,22 +85,26 @@ SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；适
 - **API**：请求头 `Authorization: Bearer {token}`
 - **WebSocket**：IDENTIFY 时 body 中传 `token`
 
-配置 `token` 并与 Satori SDK 端一致即可。
-
-## 连接方式对比
-
-| connection | 说明 |
-|------------|------|
-| `ws` | 应用主动连 SDK `/v1/events`，IDENTIFY + 心跳 |
-| `webhook` | 应用提供 POST path，SDK 推送事件 |
-
 ## 消息 id 与撤回
 
-- 消息 `$id` 格式为 `channelId:messageId`，便于发消息 / 撤回时解析。
+- 消息 id 格式为 `channelId:messageId`，便于发消息 / 撤回时解析。
 - 撤回时需 `channel_id` + `message_id`，适配器已按上述格式解析。
 
+## AI 工具
+
+技能说明见 `skills/satori/SKILL.md`。
+
 ## 协议文档
 
 - [介绍](https://satori.chat/zh-CN/introduction.html)
 - [总览](https://satori.chat/zh-CN/protocol/overview.html)
 - [API](https://satori.chat/zh-CN/protocol/api.html)
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| WS IDENTIFY 失败 | 检查 `baseUrl`、平台/用户标识与 token |
+| Webhook 无事件 | 确认路径、`Satori-Opcode: 0` 与 HTTP Host |
+| 401 | 检查 API、WS IDENTIFY 与 Webhook 使用的 token 是否一致 |
+| 发送目标错误 | 核对 `channel_id` 与 Conversation kind；DIRECT 才映射为 private |

package/adapters/satori/index.js

@@ -0,0 +1,38 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/satori/index.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { SatoriWebhookEndpoint, SatoriWsEndpoint } from "../../lib/endpoint.js";
+import { resolveSatoriConfig, } from "../../lib/protocol.js";
+import { satoriRuntimeStateToken } from "../../lib/satori-runtime-state.js";
+export { SatoriWebhookEndpoint, SatoriWsEndpoint } from "../../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // Satori 协议 img/file 元素消费 url 与 base64 内联数据；无卡片交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url', 'base64'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveSatoriConfig(context.config);
+        // 注册到插件运行时状态（satori endpoint list 的"运行中"数据源）
+        context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: config.connection,
+        });
+        if (config.connection === 'webhook') {
+            return new SatoriWebhookEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        return new SatoriWsEndpoint({
+            id: context.id,
+            config,
+        });
+    },
+});

package/adapters/satori/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Convention entry: discover `adapters/satori/index.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { SatoriWebhookEndpoint, SatoriWsEndpoint } from '../../src/endpoint.js';
+import {
+  resolveSatoriConfig,
+  type SatoriEndpointConfig,
+} from '../../src/protocol.js';
+import { satoriRuntimeStateToken } from '../../src/satori-runtime-state.js';
+
+export { SatoriWebhookEndpoint, SatoriWsEndpoint } from '../../src/endpoint.js';
+export type {
+  CreateSatoriWebSocket,
+  SatoriApiCaller,
+  SatoriWebhookEndpointOptions,
+  SatoriWsEndpointOptions,
+  SatoriWsSocket,
+} from '../../src/endpoint.js';
+
+export default defineAdapter<SatoriEndpointConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // Satori 协议 img/file 元素消费 url 与 base64 内联数据；无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'base64'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveSatoriConfig(context.config);
+    // 注册到插件运行时状态（satori endpoint list 的"运行中"数据源）
+    context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: config.connection,
+    });
+    if (config.connection === 'webhook') {
+      return new SatoriWebhookEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new SatoriWsEndpoint({
+      id: context.id,
+      config,
+    });
+  },
+});

package/commands/satori/endpoint/add/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { satoriEndpointCommands } from '../../definition.js';
+export default satoriEndpointCommands.add;

package/commands/satori/endpoint/add/[id]/index.ts

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

package/commands/satori/endpoint/definition.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `satori endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/satori/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { satoriRuntimeStateToken } from "../../../lib/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/commands/satori/endpoint/definition.ts

@@ -0,0 +1,19 @@
+/**
+ * `satori endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/satori/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { satoriRuntimeStateToken } from '../../../src/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/commands/satori/endpoint/list/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { satoriEndpointCommands } from '../definition.js';
+export default satoriEndpointCommands.list;

package/commands/satori/endpoint/list/index.ts

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

package/commands/satori/endpoint/remove/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { satoriEndpointCommands } from '../../definition.js';
+export default satoriEndpointCommands.remove;

package/commands/satori/endpoint/remove/[id]/index.ts

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

package/lib/client.d.ts

@@ -0,0 +1,18 @@
+import { SatoriV1Client, type SatoriV1Event } from '@imhelper/satori-v1';
+import { type EventMap, type ImHelperEventMap } from 'imhelper';
+import { type ClientEventPayloads } from 'zhin.js/adapter';
+import type { ResolvedSatoriConfig, SatoriApiOptions, callSatoriApi } from './protocol.js';
+export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
+type SatoriClientEvents = ImHelperEventMap<string, SatoriV1Event, EventMap<string>>;
+export type SatoriClientEventMap = ClientEventPayloads<SatoriClientEvents>;
+export declare function createSatoriEndpointClient(config: ResolvedSatoriConfig, request: typeof callSatoriApi, apiOptions: () => SatoriApiOptions): SatoriV1Client;
+export declare function forwardSatoriClientEvents(client: SatoriV1Client, receive: (name: string, payload: unknown) => void): () => void;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly satori: {
+            readonly client: SatoriV1Client;
+            readonly events: SatoriClientEventMap;
+        };
+    }
+}
+export declare const satoriClient: import("@zhin.js/adapter").EndpointClientToken<SatoriV1Client, ClientEventPayloads<SatoriClientEvents>>;

package/lib/client.js

@@ -0,0 +1,21 @@
+import { SatoriV1Client, } from '@imhelper/satori-v1';
+import { EventFactory } from 'imhelper';
+import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
+export function createSatoriEndpointClient(config, request, apiOptions) {
+    return new SatoriV1Client({
+        baseUrl: config.baseUrl,
+        selfId: config.id,
+        accessToken: config.token,
+        receiveMode: 'manual',
+        call: (resource, method, params) => request(apiOptions(), resource, method, params ?? {}),
+    });
+}
+const satoriClientEventNames = Object.freeze([
+    ...EventFactory.getSupportedEventTypes(),
+    'event',
+]);
+export function forwardSatoriClientEvents(client, receive) {
+    return forwardEndpointClientEvents(client, satoriClientEventNames, receive);
+}
+export const satoriClient = defineEndpointClient('satori');

package/lib/endpoint.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
+ */
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { callSatoriApi, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig } from './protocol.js';
+import { type SatoriClient } from './client.js';
+import { type CreateSatoriWebSocket } from './ws.js';
+export type SatoriApiCaller = typeof callSatoriApi;
+export interface SatoriWsEndpointOptions {
+    readonly id: CapabilityId;
+    readonly config: ResolvedSatoriWsConfig;
+    readonly createWebSocket?: CreateSatoriWebSocket;
+    readonly callApi?: SatoriApiCaller;
+}
+export declare class SatoriWsEndpoint extends ClientEndpoint<SatoriClient> {
+    #private;
+    readonly client: SatoriClient;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    constructor(options: SatoriWsEndpointOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recall(id: string, fallbackChannelId?: string): Promise<void>;
+}
+export interface SatoriWebhookEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: ResolvedSatoriWebhookConfig;
+    readonly callApi?: SatoriApiCaller;
+}
+export declare class SatoriWebhookEndpoint extends ClientEndpoint<SatoriClient> {
+    #private;
+    readonly client: SatoriClient;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    constructor(options: SatoriWebhookEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedSatoriWebhookConfig;
+    acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recall(id: string, fallbackChannelId?: string): Promise<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';