@zhin.js/adapter-satori 1.1.0 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # @zhin.js/adapter-satori
 
+## 1.1.3
+
+### Patch Changes
+
+- Updated dependencies [5b5d270]
+- Updated dependencies [36c2eb9]
+  - @zhin.js/im-contract@1.1.2
+  - @zhin.js/core@1.1.38
+  - @zhin.js/adapter@1.1.15
+  - @zhin.js/host-http@1.1.2
+  - @zhin.js/feature-kit@1.1.2
+  - @zhin.js/skill@1.1.2
+
+## 1.1.2
+
+### Patch Changes
+
+- a9e4a40: Derive Command user routes only from explicit `commands/**/*/index.ts(x)` entry paths instead of prepending the plugin owner. Child plugins can now publish top-level static or dynamic commands, while duplicate routes across owners fail during generation construction. Adapter endpoint commands move to explicit paths such as `commands/qq/endpoint/list/index.ts` and are invoked as `qq endpoint list`.
+- 8740059: Standardize TypeScript capabilities on named module directories such as `commands/foo/index.ts`, `middlewares/audit/index.ts`, `handlers/message-receive/index.ts`, `pages/workroom/index.tsx`, and `mcps/filesystem/index.ts`. Only the fixed `index` entry is discovered; sibling files remain private helpers.
+
+  Command route segments come from directories, while `[name]`, `[[name]]`, `[...name]`, and `[[...name]]` directories declare dynamic parameters. Plugin owners do not enter the route unless their config explicitly sets `commandNamespace`; Endpoint `commandPrefix` remains platform-owned and defaults to an empty string.
+
+  Migrate the built-in adapters, plugins, examples, generators, migration tooling, hot reload classification, Agent authoring surfaces, documentation, and release artifacts to the explicit entry convention.
+
+  Make Tool ownership and progressive disclosure explicit across all four supported locations: plugin-public `tools/`, Agent-private `agents/<name>/tools/`, Skill-private `skills/<name>/tools/`, and Agent-Skill-private `agents/<name>/skills/<name>/tools/`. Move adapter and group-suite operations that require domain instructions into their owning Skills so `load_skill` is the only path that unlocks their schemas.
+
+  Remove the package-root `agent/` convention. Public capabilities now use named package-root directories, schedules use `schedules/<name>/index.ts` or `plugin.ts` injection, MCP connections use `mcps/<name>/index.ts`, Prompt Sections use `prompt-sections/<name>/index.ts`, Agent definitions use `agents/<name>/`, and permission vocabulary is published as `PERMITS.md`.
+
+- 25a845a: Unify Skills on `skills/<name>/SKILL.md`, support Agent-private Skills and nested Skill-private Tools, publish and mount existing plugin Skills, add governed Skill metadata and Turn access filtering, unlock only already-admitted same-owner Tools, and make `on-risk` and `once` approval behavior precise.
+- 4380cf9: Colocate adapter command definitions and Agent Skill handlers with their owning capabilities, and provide a shared validated platform permission constructor.
+- 2acae54: Require the canonical expanded Satori endpoint configuration. The protocol no longer reinterprets nested `endpoints` or reads endpoint identity, base URL, and token from `process.env`. The public config type is now `SatoriEndpointConfig`, and each schema entry uses `id` as its identity.
+- 5c3858e: Make `@zhin.js/im-contract` the explicit zero-dependency owner of transport identities, canonical segments, media guards, conversation facts, stores, and delivery contracts. Platform adapters now read media contracts from that foundation instead of reaching through Core.
+- Updated dependencies [c861789]
+- Updated dependencies [1414ccb]
+- Updated dependencies [743d470]
+- Updated dependencies [62dee52]
+- Updated dependencies [cd54131]
+- Updated dependencies [244e475]
+- Updated dependencies [a9e4a40]
+- Updated dependencies [5855db7]
+- Updated dependencies [ec921d2]
+- Updated dependencies [8740059]
+- Updated dependencies [25a845a]
+- Updated dependencies [103f2c3]
+- Updated dependencies [9110ab8]
+- Updated dependencies [cd2a888]
+- Updated dependencies [eb3227a]
+- Updated dependencies [b853dba]
+- Updated dependencies [e561309]
+- Updated dependencies [d4c6175]
+- Updated dependencies [7a0e1ca]
+- Updated dependencies [103b5d3]
+- Updated dependencies [5a7a7f7]
+- Updated dependencies [b076eae]
+- Updated dependencies [73a24b7]
+- Updated dependencies [2dbbc15]
+- Updated dependencies [1cb1163]
+- Updated dependencies [be3061e]
+- Updated dependencies [75f8332]
+- Updated dependencies [81935e2]
+- Updated dependencies [f9ed01b]
+- Updated dependencies [ac0ab50]
+- Updated dependencies [5140ce1]
+- Updated dependencies [522d75f]
+- Updated dependencies [a7611b3]
+- Updated dependencies [8823044]
+- Updated dependencies [379439b]
+- Updated dependencies [11c9352]
+- Updated dependencies [6b70e46]
+- Updated dependencies [135ac91]
+- Updated dependencies [140cf0f]
+- Updated dependencies [251e4d2]
+- Updated dependencies [203ad34]
+- Updated dependencies [e6c5113]
+- Updated dependencies [e0f6478]
+- Updated dependencies [baef56b]
+- Updated dependencies [da0a8e3]
+- Updated dependencies [2fd8017]
+- Updated dependencies [5c3858e]
+- Updated dependencies [507d602]
+- Updated dependencies [df9f76b]
+  - @zhin.js/core@1.1.37
+  - @zhin.js/host-http@1.1.1
+  - @zhin.js/adapter@1.1.14
+  - @zhin.js/feature-kit@1.1.1
+  - @zhin.js/skill@1.1.1
+  - @zhin.js/logger@1.1.1
+  - @zhin.js/im-contract@1.1.1
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [769e67f]
+  - @zhin.js/adapter@1.1.13
+  - @zhin.js/core@1.1.36
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -21,7 +21,7 @@ pnpm add @zhin.js/adapter-satori
 
 ## Plugin Runtime
 
-- `@zhin.js/adapter` — 约定式 `adapters/satori.ts`（`defineAdapter`）
+- `@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 路由
@@ -51,7 +51,7 @@ plugins:
     connection: ws
     heartbeat_interval: 10000
     endpoints:
-      - name: satori-bot
+      - id: satori-bot
         baseUrl: "http://127.0.0.1:5140"
         token: "${SATORI_TOKEN}"
 ```
@@ -63,7 +63,7 @@ plugins:
 | 字段 | 说明 |
 |------|------|
 | `heartbeat_interval` | WS PING 间隔（毫秒），默认 `10000` |
-| `token` | Bearer；也可设环境变量 `SATORI_TOKEN` |
+| `token` | Bearer；可在 YAML 中引用 `${SATORI_TOKEN}` |
 
 ### Webhook
 
@@ -72,7 +72,7 @@ plugins:
   satori:
     connection: webhook
     endpoints:
-      - name: satori-bot
+      - id: satori-bot
         baseUrl: "http://127.0.0.1:5140"
         path: "/satori/webhook"
         token: "${SATORI_TOKEN}"
@@ -92,7 +92,7 @@ SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；适
 
 ## AI 工具
 
-技能说明见 `agent/skills/satori.md`。
+技能说明见 `skills/satori/SKILL.md`。
 
 ## 协议文档
 

package/adapters/{satori.js → satori/index.js}

@@ -1,13 +1,13 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/satori.ts` → defineAdapter.
+ * 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";
+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'],
@@ -18,7 +18,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveSatoriConfig(context.config);
-        // 注册到插件运行时状态（satori.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（satori endpoint list 的"运行中"数据源）
         context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: config.connection,

package/adapters/{satori.ts → satori/index.ts}

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

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

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { satoriEndpointCommands } from "../../../lib/satori-endpoint-commands.js";
+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/{lib/satori-endpoint-commands.js → commands/satori/endpoint/definition.js}

@@ -1,10 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * `satori.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `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 './satori-runtime-state.js';
+import { satoriRuntimeStateToken } from "../../../lib/satori-runtime-state.js";
 export const satoriEndpointCommands = createEndpointCommands({
     adapterKey: 'satori',
     adapterDisplayName: 'Satori',

package/{src/satori-endpoint-commands.ts → commands/satori/endpoint/definition.ts}

@@ -1,10 +1,10 @@
 /**
- * `satori.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `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 './satori-runtime-state.js';
+import { satoriRuntimeStateToken } from '../../../src/satori-runtime-state.js';
 
 export const satoriEndpointCommands = createEndpointCommands({
   adapterKey: 'satori',

package/commands/{endpoint/list.js → satori/endpoint/list/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { satoriEndpointCommands } from "../../lib/satori-endpoint-commands.js";
+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/{endpoint/remove/[id].js → satori/endpoint/remove/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { satoriEndpointCommands } from "../../../lib/satori-endpoint-commands.js";
+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/index.d.ts

@@ -1,4 +1,4 @@
-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 { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriEndpointConfig, 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, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, type SatoriWebhookHandler, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';

package/lib/protocol.d.ts

@@ -1,9 +1,5 @@
-/**
- * Satori protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
- * 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';
+/** Satori protocol helpers. 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;
@@ -76,21 +72,15 @@ export interface SatoriWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
 }
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface SatoriAdapterConfig {
-    readonly id?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface SatoriEndpointConfig {
+    readonly id: string;
     readonly connection?: 'ws' | 'webhook';
-    readonly baseUrl?: string;
+    readonly baseUrl: string;
     readonly token?: string;
     readonly heartbeat_interval?: number;
     /** Webhook POST path (connection: webhook). */
     readonly path?: string;
-    /** Transitional: legacy root `endpoints[]` with `context: satori`. */
-    readonly endpoints?: ReadonlyArray<Partial<ResolvedSatoriWsConfig> & {
-        readonly context?: string;
-        readonly connection?: 'ws' | 'webhook';
-        readonly path?: string;
-    }>;
 }
 export interface ResolvedSatoriWsConfig {
     readonly context: 'satori';
@@ -109,7 +99,7 @@ export interface ResolvedSatoriWebhookConfig {
     readonly path: string;
 }
 export type ResolvedSatoriConfig = ResolvedSatoriWsConfig | ResolvedSatoriWebhookConfig;
-export declare function resolveSatoriConfig(config?: SatoriAdapterConfig): ResolvedSatoriConfig;
+export declare function resolveSatoriConfig(config: SatoriEndpointConfig): ResolvedSatoriConfig;
 /** Channel.type 1 = DIRECT (private). */
 export declare function isPrivateChannel(channel?: SatoriChannel): boolean;
 export declare function isMessageEvent(body: SatoriEventBody): body is SatoriEventBody & {

package/lib/protocol.js

@@ -1,10 +1,5 @@
-/**
- * Satori protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
- * Canonicalization is owned by gateway/core before endpoint.send.
- * Spec: https://satori.chat/zh-CN/protocol/overview.html
- */
-import { pickCredential } from 'zhin.js/adapter';
-import { isMediaRef } from '@zhin.js/core';
+/** Satori protocol helpers. Spec: https://satori.chat/zh-CN/protocol/overview.html */
+import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('satori');
 /** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
@@ -16,26 +11,15 @@ export const SatoriOpcode = {
     READY: 4,
     META: 5,
 };
-export function resolveSatoriConfig(config = {}) {
-    const entry = config.endpoints?.find((item) => item.context === 'satori');
-    const connection = config.connection ?? entry?.connection ?? 'ws';
-    const baseUrl = pickCredential(config.baseUrl, entry?.baseUrl, process.env.SATORI_BASE_URL);
-    if (!baseUrl) {
-        throw new TypeError('Satori adapter requires baseUrl (plugins.<key>.baseUrl or endpoints with context: satori)');
-    }
-    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)
-        || (typeof entry?.token === 'string' && entry.token)
-        || process.env.SATORI_TOKEN
-        || undefined;
+export function resolveSatoriConfig(config) {
+    const connection = config.connection ?? 'ws';
+    const id = requiredEndpointField(config.id, 'id');
+    const baseUrl = requiredEndpointField(config.baseUrl, 'baseUrl');
+    const token = typeof config.token === 'string' && config.token.trim()
+        ? config.token.trim()
+        : undefined;
     if (connection === 'webhook') {
-        const path = config.path ?? entry?.path;
-        if (!path) {
-            throw new TypeError('Satori connection:webhook requires path');
-        }
+        const path = requiredEndpointField(config.path, 'path');
         return {
             context: 'satori',
             connection: 'webhook',
@@ -45,9 +29,7 @@ export function resolveSatoriConfig(config = {}) {
             path,
         };
     }
-    const heartbeat = config.heartbeat_interval
-        ?? entry?.heartbeat_interval
-        ?? 10_000;
+    const heartbeat = config.heartbeat_interval ?? 10_000;
     return {
         context: 'satori',
         connection: 'ws',
@@ -57,6 +39,12 @@ export function resolveSatoriConfig(config = {}) {
         heartbeat_interval: heartbeat,
     };
 }
+function requiredEndpointField(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Satori endpoint requires a non-empty ${field}`);
+    }
+    return value.trim();
+}
 /** Channel.type 1 = DIRECT (private). */
 export function isPrivateChannel(channel) {
     return channel?.type === 1;

package/lib/satori-runtime-state.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "1.1.0",
+  "version": "1.1.3",
   "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,7 +19,7 @@
     "schema.json",
     "src",
     "lib",
-    "agent",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -41,26 +41,27 @@
     "@imhelper/satori-v1": "1.0.7",
     "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.12",
-    "@zhin.js/core": "1.1.35",
-    "@zhin.js/feature-kit": "1.1.0",
-    "@zhin.js/host-http": "1.1.0",
-    "@zhin.js/im-contract": "1.1.0",
-    "@zhin.js/logger": "1.1.0"
+    "@zhin.js/adapter": "1.1.15",
+    "@zhin.js/core": "1.1.38",
+    "@zhin.js/feature-kit": "1.1.2",
+    "@zhin.js/host-http": "1.1.2",
+    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/skill": "1.1.2"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.1.0",
-    "zhin.js": "1.1.0"
+    "@zhin.js/host-http": "1.1.2",
+    "zhin.js": "1.1.3"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "^1.1.12",
-    "@zhin.js/command": "^1.1.0",
-    "@zhin.js/core": "^1.1.35",
-    "zhin.js": "^1.1.0"
+    "@zhin.js/adapter": "^1.1.15",
+    "@zhin.js/command": "^1.1.2",
+    "@zhin.js/core": "^1.1.38",
+    "zhin.js": "^1.1.3"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -96,6 +97,10 @@
       {
         "package": "@zhin.js/command",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.js

@@ -8,7 +8,7 @@ export default definePlugin({
         displayName: 'Satori Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（satori.endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（satori endpoint list 的"运行中"数据源）
         context.resources.provide(satoriRuntimeStateToken, createEndpointRuntimeState());
     },
 });

package/schema.json

@@ -37,10 +37,11 @@
     },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "minItems": 1,
+      "description": "多账号：每项定义一个 endpoint，id/baseUrl 必填，其余字段覆盖实例默认值",
       "items": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": false,
         "properties": {
           "master": {
             "type": [
@@ -64,6 +65,13 @@
             "type": "string",
             "description": "Satori SDK HTTP/WS base URL (e.g. http://127.0.0.1:5140)"
           },
+          "connection": {
+            "type": "string",
+            "enum": [
+              "ws",
+              "webhook"
+            ]
+          },
           "token": {
             "type": "string",
             "description": "Bearer token for API and WS IDENTIFY"
@@ -72,6 +80,12 @@
             "type": "string",
             "description": "Webhook POST path (connection: webhook)"
           },
+          "heartbeat_interval": {
+            "type": "number"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
           "id": {
             "type": "string",
             "description": "Satori bot name"

package/src/index.ts

@@ -12,7 +12,7 @@ export {
   satoriInboundConversation,
   type ResolvedSatoriWebhookConfig,
   type ResolvedSatoriWsConfig,
-  type SatoriAdapterConfig,
+  type SatoriEndpointConfig,
   type SatoriApiOptions,
   type SatoriChannel,
   type SatoriEventBody,

package/src/protocol.ts

@@ -1,12 +1,6 @@
-/**
- * Satori protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
- * Canonicalization is owned by gateway/core before endpoint.send.
- * Spec: https://satori.chat/zh-CN/protocol/overview.html
- */
+/** Satori protocol helpers. Spec: https://satori.chat/zh-CN/protocol/overview.html */
 
-import { pickCredential } from 'zhin.js/adapter';
-import { isMediaRef } from '@zhin.js/core';
-import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
+import { isMediaRef, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('satori');
@@ -82,21 +76,15 @@ export interface SatoriWireSegment {
   readonly data?: Record<string, unknown>;
 }
 
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface SatoriAdapterConfig {
-  readonly id?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface SatoriEndpointConfig {
+  readonly id: string;
   readonly connection?: 'ws' | 'webhook';
-  readonly baseUrl?: string;
+  readonly baseUrl: string;
   readonly token?: string;
   readonly heartbeat_interval?: number;
   /** Webhook POST path (connection: webhook). */
   readonly path?: string;
-  /** Transitional: legacy root `endpoints[]` with `context: satori`. */
-  readonly endpoints?: ReadonlyArray<Partial<ResolvedSatoriWsConfig> & {
-    readonly context?: string;
-    readonly connection?: 'ws' | 'webhook';
-    readonly path?: string;
-  }>;
 }
 
 export interface ResolvedSatoriWsConfig {
@@ -119,29 +107,16 @@ export interface ResolvedSatoriWebhookConfig {
 
 export type ResolvedSatoriConfig = ResolvedSatoriWsConfig | ResolvedSatoriWebhookConfig;
 
-export function resolveSatoriConfig(config: SatoriAdapterConfig = {}): ResolvedSatoriConfig {
-  const entry = config.endpoints?.find((item) => item.context === 'satori');
-  const connection = config.connection ?? entry?.connection ?? 'ws';
-  const baseUrl = pickCredential(config.baseUrl, entry?.baseUrl, process.env.SATORI_BASE_URL);
-  if (!baseUrl) {
-    throw new TypeError(
-      'Satori adapter requires baseUrl (plugins.<key>.baseUrl or endpoints with context: satori)',
-    );
-  }
-  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)
-    || (typeof entry?.token === 'string' && entry.token)
-    || process.env.SATORI_TOKEN
-    || undefined;
+export function resolveSatoriConfig(config: SatoriEndpointConfig): ResolvedSatoriConfig {
+  const connection = config.connection ?? 'ws';
+  const id = requiredEndpointField(config.id, 'id');
+  const baseUrl = requiredEndpointField(config.baseUrl, 'baseUrl');
+  const token = typeof config.token === 'string' && config.token.trim()
+    ? config.token.trim()
+    : undefined;
 
   if (connection === 'webhook') {
-    const path = config.path ?? entry?.path;
-    if (!path) {
-      throw new TypeError('Satori connection:webhook requires path');
-    }
+    const path = requiredEndpointField(config.path, 'path');
     return {
       context: 'satori',
       connection: 'webhook',
@@ -152,9 +127,7 @@ export function resolveSatoriConfig(config: SatoriAdapterConfig = {}): ResolvedS
     };
   }
 
-  const heartbeat = config.heartbeat_interval
-    ?? entry?.heartbeat_interval
-    ?? 10_000;
+  const heartbeat = config.heartbeat_interval ?? 10_000;
   return {
     context: 'satori',
     connection: 'ws',
@@ -165,6 +138,16 @@ export function resolveSatoriConfig(config: SatoriAdapterConfig = {}): ResolvedS
   };
 }
 
+function requiredEndpointField(
+  value: unknown,
+  field: 'id' | 'baseUrl' | 'path',
+): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`Satori endpoint requires a non-empty ${field}`);
+  }
+  return value.trim();
+}
+
 /** Channel.type 1 = DIRECT (private). */
 export function isPrivateChannel(channel?: SatoriChannel): boolean {
   return channel?.type === 1;

package/src/satori-runtime-state.ts

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

package/agent/skills/satori.md

@@ -1,33 +0,0 @@
----
-name: satori
-platforms:
-  - satori
-description: >-
-  Satori 协议适配器：支持 WebSocket（正向）和 Webhook 两种连接方式，
-  实现 Satori 标准协议的消息收发。纯消息通道，无额外 AI 工具。
-  Satori 是跨平台的统一协议，可对接多种 IM 后端。
-keywords:
-  - satori
-  - adapter:satori
-  - protocol
-  - websocket
-  - webhook
-  - 协议
-  - 跨平台
-tags:
-  - satori
-  - protocol
-  - adapter
-tools: []
----
-
-# Satori 协议适配器
-
-纯协议适配器，收发消息。无 AI 工具可调用。
-
-## 连接模式
-
-- **WS 正向**：Bot 主动连接 Satori 服务端
-- **Webhook**：Satori 向配置的 URL 推送事件
-
-Satori 是跨平台统一协议，可作为中间层对接 QQ、Discord、Telegram 等后端。

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

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

package/commands/endpoint/list.ts

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

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

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

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

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