@zhin.js/adapter-milky 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @zhin.js/adapter-milky
 
+## 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.
+- 86087cf: Require one canonical expanded Milky endpoint configuration. The protocol no longer reinterprets nested `endpoints` or reads endpoint identity from `process.env`, and reverse WebSocket connection replacement, heartbeat, and cleanup now use the shared endpoint lifecycle.
+- 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

@@ -18,11 +18,13 @@ pnpm add @zhin.js/adapter-milky
 
 ## Plugin Runtime
 
-- `@zhin.js/adapter` — 约定式 `adapters/milky.ts`（`defineAdapter`）
+- `@zhin.js/adapter` — 约定式 `adapters/milky/index.ts`（`defineAdapter`）
 - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
+`AdapterIndex` 会把实例默认值与 `endpoints[]` 的逐项覆盖合并；协议层只接收一个已经展开的 endpoint 配置，不再读取嵌套 endpoint 或从进程环境推断 endpoint 身份。
+
 入站：`gateway.receive({ conversation: ConversationRef(kind: "private"|"group", id), message, content, sender, metadata })`  
 出站：`send({ conversation, payload })` → HTTP `send_private_message` / `send_group_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
@@ -47,7 +49,7 @@ plugins:
     reconnect_interval: 5000
     heartbeat_interval: 30000
     endpoints:
-      - name: milky-bot
+      - id: milky-bot
         baseUrl: "http://127.0.0.1:8080"
         access_token: "${MILKY_ACCESS_TOKEN}"
 ```
@@ -77,8 +79,8 @@ plugins:
 
 | 类别 | 路径 |
 |------|------|
-| Permit 词汇 | `agent/PERMITS.md` |
-| 技能说明 | `agent/skills/milky.md` |
+| Permit 词汇 | `PERMITS.md` |
+| 技能说明 | `skills/milky/SKILL.md` |
 
 ## 文档链接
 

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

@@ -1,13 +1,13 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/milky.ts` → defineAdapter.
+ * Convention entry: discover `adapters/milky/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { httpHostToken } from '@zhin.js/host-http';
-import { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, } from "../lib/endpoint.js";
-import { resolveMilkyConfig, } from "../lib/protocol.js";
-import { milkyRuntimeStateToken } from "../lib/milky-runtime-state.js";
-export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, } from "../lib/endpoint.js";
+import { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, } from "../../lib/endpoint.js";
+import { resolveMilkyConfig, } from "../../lib/protocol.js";
+import { milkyRuntimeStateToken } from "../../lib/milky-runtime-state.js";
+export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['recall'],
@@ -18,7 +18,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveMilkyConfig(context.config);
-        // 注册到插件运行时状态（milky.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（milky endpoint list 的"运行中"数据源）
         context.use(milkyRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: config.connection,

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

@@ -1,5 +1,5 @@
 /**
- * Convention entry: discover `adapters/milky.ts` → defineAdapter.
+ * Convention entry: discover `adapters/milky/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { httpHostToken } from '@zhin.js/host-http';
@@ -8,19 +8,19 @@ import {
   MilkyWebhookEndpoint,
   MilkyWssEndpoint,
   MilkyWsEndpoint,
-} from '../src/endpoint.js';
+} from '../../src/endpoint.js';
 import {
   resolveMilkyConfig,
-  type MilkyAdapterConfig,
-} from '../src/protocol.js';
-import { milkyRuntimeStateToken } from '../src/milky-runtime-state.js';
+  type MilkyEndpointConfig,
+} from '../../src/protocol.js';
+import { milkyRuntimeStateToken } from '../../src/milky-runtime-state.js';
 
 export {
   MilkySseEndpoint,
   MilkyWebhookEndpoint,
   MilkyWssEndpoint,
   MilkyWsEndpoint,
-} from '../src/endpoint.js';
+} from '../../src/endpoint.js';
 export type {
   CreateMilkySseStream,
   MilkySseEndpointOptions,
@@ -29,9 +29,9 @@ export type {
   MilkyWsEndpointOptions,
   MilkyWsCreateOptions,
   MilkyWsSocket,
-} from '../src/endpoint.js';
+} from '../../src/endpoint.js';
 
-export default defineAdapter<MilkyAdapterConfig>({
+export default defineAdapter<MilkyEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
   // Milky 协议资源 uri 消费 http(s):// 与 base64:// 形式；无卡片交互面，交互段降级纯文本。
@@ -41,7 +41,7 @@ export default defineAdapter<MilkyAdapterConfig>({
   },
   create(context) {
     const config = resolveMilkyConfig(context.config);
-    // 注册到插件运行时状态（milky.endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（milky endpoint list 的"运行中"数据源）
     context.use(milkyRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       mode: config.connection,

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

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { milkyEndpointCommands } from "../../../lib/milky-endpoint-commands.js";
+import { milkyEndpointCommands } from '../../definition.js';
 export default milkyEndpointCommands.add;

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

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

package/{lib/milky-endpoint-commands.js → commands/milky/endpoint/definition.js}

@@ -1,10 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * `milky.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `milky endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/milky/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { milkyRuntimeStateToken } from './milky-runtime-state.js';
+import { milkyRuntimeStateToken } from "../../../lib/milky-runtime-state.js";
 export const milkyEndpointCommands = createEndpointCommands({
     adapterKey: 'milky',
     adapterDisplayName: 'Milky',

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

@@ -1,10 +1,10 @@
 /**
- * `milky.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `milky endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/milky/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { milkyRuntimeStateToken } from './milky-runtime-state.js';
+import { milkyRuntimeStateToken } from '../../../src/milky-runtime-state.js';
 
 export const milkyEndpointCommands = createEndpointCommands({
   adapterKey: 'milky',

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

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { milkyEndpointCommands } from "../../lib/milky-endpoint-commands.js";
+import { milkyEndpointCommands } from '../definition.js';
 export default milkyEndpointCommands.list;

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

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

package/commands/{endpoint/remove/[id].js → milky/endpoint/remove/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { milkyEndpointCommands } from "../../../lib/milky-endpoint-commands.js";
+import { milkyEndpointCommands } from '../../definition.js';
 export default milkyEndpointCommands.remove;

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

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

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatOutboundSegments, isMentioned, isMessageReceiveEvent, milkyInboundConversation, parseMessageReceiveData, resolveMilkyConfig, senderNickname, type MilkyAdapterConfig, type MilkyApiClientOptions, type MilkyApiResponse, type MilkyConfigBase, type MilkyEndpointConfig, type MilkyEvent, type MilkyIncomingMessage, type MilkyIncomingSegment, type MilkyOutgoingSegment, type MilkySseConfig, type MilkyWebhookConfig, type MilkyWireSegment, type MilkyWsConfig, type MilkyWssConfig, type ResolvedMilkyConfig, } from './protocol.js';
+export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatOutboundSegments, isMentioned, isMessageReceiveEvent, milkyInboundConversation, parseMessageReceiveData, resolveMilkyConfig, senderNickname, type MilkyApiClientOptions, type MilkyApiResponse, type MilkyConfigBase, type MilkyEndpointConfig, type MilkyEvent, type MilkyIncomingMessage, type MilkyIncomingSegment, type MilkyOutgoingSegment, type MilkySseConfig, type MilkyWebhookConfig, type MilkyWireSegment, type MilkyWsConfig, type MilkyWssConfig, type ResolvedMilkyConfig, } from './protocol.js';
 export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, consumeSseBuffer, openSseStream, verifyMilkyAccessToken, type CreateMilkySseStream, type MilkySseEndpointOptions, type MilkyWebhookEndpointOptions, type MilkyWssEndpointOptions, type MilkyWsCreateOptions, type MilkyWsEndpointOptions, type MilkyWsSocket, } from './endpoint.js';
 export { MilkyClient, milkyClient, type MilkyClientEventMap, } from './client.js';
 export type { MilkyAdapterConfig as ImHelperMilkyAdapterConfig, MilkyActionUrlResolver, MilkyCall, MilkyMessageReceiveEvent, MilkyMessageRecallEvent, MilkyV1ClientConfig, MilkyV1Event, MilkyV1Response, } from '@imhelper/milky-v1';

package/lib/milky-runtime-state.js

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

package/lib/protocol.d.ts

@@ -3,30 +3,17 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://milky.ntqqrev.org/
  */
+import { type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
-import type { ConversationRef } from '@zhin.js/im-contract';
-/** Transitional legacy endpoint row (`endpoints[]` with `context: milky`). */
-export interface MilkyLegacyEndpointRow {
-    readonly context?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface MilkyEndpointConfig {
     readonly connection?: 'ws' | 'sse' | 'webhook' | 'wss';
-    readonly id?: string;
-    readonly baseUrl?: string;
-    readonly access_token?: string;
-    readonly path?: string;
-    readonly reconnect_interval?: number;
-    readonly heartbeat_interval?: number;
-}
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface MilkyAdapterConfig {
-    readonly connection?: 'ws' | 'sse' | 'webhook' | 'wss';
-    readonly id?: string;
-    readonly baseUrl?: string;
+    readonly id: string;
+    readonly baseUrl: string;
     readonly access_token?: string;
     readonly path?: string;
     readonly reconnect_interval?: number;
     readonly heartbeat_interval?: number;
-    /** Transitional: legacy root `endpoints[]` with `context: milky`. */
-    readonly endpoints?: ReadonlyArray<MilkyLegacyEndpointRow>;
 }
 export interface MilkyConfigBase {
     readonly context: 'milky';
@@ -57,7 +44,6 @@ export interface MilkyWssConfig extends MilkyConfigBase {
     readonly heartbeat_interval: number;
 }
 export type ResolvedMilkyConfig = MilkyWsConfig | MilkySseConfig | MilkyWebhookConfig | MilkyWssConfig;
-export type MilkyEndpointConfig = ResolvedMilkyConfig;
 export interface MilkyApiResponse<T = unknown> {
     status: 'ok' | 'failed';
     retcode: number;
@@ -108,7 +94,7 @@ export interface MilkyApiClientOptions {
     readonly baseUrl: string;
     readonly access_token?: string;
 }
-export declare function resolveMilkyConfig(config?: MilkyAdapterConfig): ResolvedMilkyConfig;
+export declare function resolveMilkyConfig(config: MilkyEndpointConfig): ResolvedMilkyConfig;
 /**
  * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
  * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。

package/lib/protocol.js

@@ -3,7 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://milky.ntqqrev.org/
  */
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('milky');
 function normalizeConnection(connection) {
@@ -11,18 +11,11 @@ function normalizeConnection(connection) {
         return connection;
     return 'ws';
 }
-export function resolveMilkyConfig(config = {}) {
-    const entry = config.endpoints?.find((item) => item.context === 'milky');
-    const connection = normalizeConnection(config.connection ?? entry?.connection);
-    const id = (typeof config.id === 'string' && config.id)
-        || (typeof entry?.id === 'string' && entry.id)
-        || process.env.MILKY_BOT_NAME
-        || 'milky-bot';
-    const baseUrl = config.baseUrl ?? entry?.baseUrl;
-    if (!baseUrl) {
-        throw new TypeError('Milky requires baseUrl (plugins.<key>.baseUrl or endpoints with context: milky)');
-    }
-    const access_token = config.access_token ?? entry?.access_token;
+export function resolveMilkyConfig(config) {
+    const connection = normalizeConnection(config.connection);
+    const id = requiredEndpointField(config.id, 'id');
+    const baseUrl = requiredEndpointField(config.baseUrl, 'baseUrl');
+    const access_token = optionalEndpointField(config.access_token);
     const base = {
         context: 'milky',
         id,
@@ -33,38 +26,42 @@ export function resolveMilkyConfig(config = {}) {
         return {
             ...base,
             connection: 'ws',
-            reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
-            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+            reconnect_interval: config.reconnect_interval ?? 5000,
+            heartbeat_interval: config.heartbeat_interval ?? 30_000,
         };
     }
     if (connection === 'sse') {
         return {
             ...base,
             connection: 'sse',
-            reconnect_interval: config.reconnect_interval
-                ?? entry?.reconnect_interval
-                ?? 5_000,
+            reconnect_interval: config.reconnect_interval ?? 5_000,
         };
     }
     if (connection === 'webhook') {
-        const path = config.path ?? entry?.path;
-        if (!path)
-            throw new TypeError('Milky connection:webhook requires path');
+        const path = requiredEndpointField(config.path, 'path');
         return { ...base, connection: 'webhook', path };
     }
     if (connection === 'wss') {
-        const path = config.path ?? entry?.path;
-        if (!path)
-            throw new TypeError('Milky connection:wss requires path');
+        const path = requiredEndpointField(config.path, 'path');
         return {
             ...base,
             connection: 'wss',
             path,
-            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+            heartbeat_interval: config.heartbeat_interval ?? 30_000,
         };
     }
     throw new TypeError(`Unknown Milky connection: ${String(connection)}`);
 }
+function requiredEndpointField(value, field) {
+    const resolved = optionalEndpointField(value);
+    if (!resolved) {
+        throw new TypeError(`Milky endpoint requires a non-empty ${field}`);
+    }
+    return resolved;
+}
+function optionalEndpointField(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
 /** 鉴权：Header Authorization: Bearer {token} 或 URL query access_token=xxx */
 function authHeaders(access_token) {
     const headers = {};

package/lib/wss-endpoint.js

@@ -18,16 +18,17 @@ export class MilkyWssEndpoint extends ClientEndpoint {
     #ws;
     #wsRelease;
     #clientSocketRelease;
-    #lifecycle;
+    #connectionLifecycle;
+    #connectionTask = Promise.resolve();
+    #started = false;
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('milky', options.config.id);
         this.#options = options;
         this.#callApi = options.callApi ?? callApi;
-        this.#lifecycle = createEndpointLifecycle({
-            name: options.config.id,
+        this.#connectionLifecycle = createEndpointLifecycle({
+            name: `${options.config.id}:inbound`,
             reconnect: false,
-            heartbeat: { intervalMs: options.config.heartbeat_interval },
         });
         this.client = createMilkyEndpointClient(options.config, this.#callApi);
         this.management = createMilkyEndpointManagement({
@@ -39,23 +40,19 @@ export class MilkyWssEndpoint extends ClientEndpoint {
         }, (_name, error) => this.#warnPlatformEvent(error));
     }
     async start() {
-        await this.#lifecycle.start(async (lifecycleHandle) => {
-            const handle = this.#options.http.ws(this.#options.config.path);
-            this.#wsRelease = handle.onConnection((connection) => {
-                this.#acceptConnection(connection);
-            });
-            lifecycleHandle.onForceClose(() => {
-                this.#wsRelease?.();
-                this.#wsRelease = undefined;
-                this.#clientSocketRelease?.();
-                this.#clientSocketRelease = undefined;
-                try {
-                    this.#ws?.close();
-                }
-                catch {
-                    /* ignore */
-                }
-                this.#ws = undefined;
+        if (this.#started)
+            return;
+        this.#started = true;
+        const handle = this.#options.http.ws(this.#options.config.path);
+        this.#wsRelease = handle.onConnection((connection) => {
+            this.#connectionTask = this.#connectionTask
+                .then(() => this.#acceptConnection(connection))
+                .catch((error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'wss_connection_failed',
+                    endpoint: this.#options.config.id,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
             });
         });
         this.#logger.info(formatCompact({
@@ -67,7 +64,12 @@ export class MilkyWssEndpoint extends ClientEndpoint {
     }
     async stop() {
         this.close();
-        await this.#lifecycle.stop();
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        await this.#connectionTask;
+        await this.#connectionLifecycle.stop();
+        this.#ws = undefined;
+        this.#started = false;
     }
     async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
@@ -141,39 +143,52 @@ export class MilkyWssEndpoint extends ClientEndpoint {
             }));
         });
     }
-    #acceptConnection(connection) {
+    async #acceptConnection(connection) {
         if (!verifyMilkyAccessToken(this.#options.config.access_token, connection.request)) {
             connection.socket.close(4003, 'Unauthorized');
             return;
         }
         const socket = connection.socket;
-        if (this.#ws) {
-            try {
-                this.#ws.close();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        this.#ws = socket;
-        this.#lifecycle.startHeartbeat(() => {
-            try {
-                if (this.#ws?.readyState === WS_OPEN)
-                    this.#ws.ping?.();
-            }
-            catch {
-                /* ignore */
-            }
-        });
-        this.#clientSocketRelease?.();
-        this.#clientSocketRelease = this.client.acceptWebSocket(socket);
-        socket.on('close', () => {
-            this.#clientSocketRelease?.();
-            this.#clientSocketRelease = undefined;
-            if (this.#ws === socket) {
-                this.#ws = undefined;
-                this.#lifecycle.stopHeartbeat();
-            }
+        await this.#connectionLifecycle.stop();
+        await this.#connectionLifecycle.start(async (lifecycleHandle) => {
+            this.#ws = socket;
+            const releaseClientSocket = this.client.acceptWebSocket(socket);
+            this.#clientSocketRelease = releaseClientSocket;
+            lifecycleHandle.onForceClose(() => {
+                if (this.#clientSocketRelease === releaseClientSocket) {
+                    releaseClientSocket();
+                    this.#clientSocketRelease = undefined;
+                }
+                try {
+                    socket.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                if (this.#ws === socket)
+                    this.#ws = undefined;
+            });
+            this.#connectionLifecycle.startHeartbeat(() => {
+                try {
+                    if (socket.readyState === WS_OPEN)
+                        socket.ping?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            }, this.#options.config.heartbeat_interval);
+            socket.on('message', () => {
+                this.#connectionLifecycle.notifyHeartbeatAck();
+            });
+            socket.on('close', () => {
+                if (this.#clientSocketRelease === releaseClientSocket) {
+                    releaseClientSocket();
+                    this.#clientSocketRelease = undefined;
+                }
+                if (this.#ws === socket)
+                    this.#ws = undefined;
+                lifecycleHandle.notifyClosed(new Error('Milky reverse WebSocket closed'));
+            });
         });
         this.#logger.debug(formatCompact({
             endpoint: this.#options.config.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Zhin.js Milky adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,9 +19,10 @@
     "schema.json",
     "src",
     "lib",
-    "agent",
+    "skills",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "PERMITS.md"
   ],
   "keywords": [
     "zhin",
@@ -42,12 +43,13 @@
     "@imhelper/milky-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.14",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/skill": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -55,17 +57,17 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.23",
-    "@zhin.js/host-http": "1.1.0",
-    "zhin.js": "1.1.0"
+    "@zhin.js/agent": "1.1.26",
+    "@zhin.js/host-http": "1.1.1",
+    "zhin.js": "1.1.2"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.12",
-    "@zhin.js/agent": "^1.1.23",
-    "@zhin.js/command": "^1.1.0",
-    "@zhin.js/core": "^1.1.35",
-    "zhin.js": "^1.1.0"
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/agent": "^1.1.26",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -107,6 +109,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: 'Milky Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（milky.endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（milky endpoint list 的"运行中"数据源）
         context.resources.provide(milkyRuntimeStateToken, createEndpointRuntimeState());
     },
 });

package/schema.json

@@ -42,10 +42,11 @@
     },
     "endpoints": {
       "type": "array",
+      "minItems": 1,
       "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": false,
         "properties": {
           "master": {
             "type": [
@@ -65,6 +66,15 @@
             },
             "description": "本 endpoint 的 trusted 列表"
           },
+          "connection": {
+            "type": "string",
+            "enum": [
+              "ws",
+              "sse",
+              "webhook",
+              "wss"
+            ]
+          },
           "baseUrl": {
             "type": "string",
             "description": "Milky HTTP API base URL (required); WS event path is derived as ws(s)://host/event"
@@ -77,6 +87,15 @@
             "type": "string",
             "description": "Milky access token"
           },
+          "reconnect_interval": {
+            "type": "number"
+          },
+          "heartbeat_interval": {
+            "type": "number"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
           "id": {
             "type": "string",
             "description": "Milky bot name"

package/src/index.ts

@@ -12,7 +12,6 @@ export {
   parseMessageReceiveData,
   resolveMilkyConfig,
   senderNickname,
-  type MilkyAdapterConfig,
   type MilkyApiClientOptions,
   type MilkyApiResponse,
   type MilkyConfigBase,

package/src/milky-runtime-state.ts

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

package/src/protocol.ts

@@ -4,36 +4,21 @@
  * Spec: https://milky.ntqqrev.org/
  */
 
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
-import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('milky');
 
-/** Transitional legacy endpoint row (`endpoints[]` with `context: milky`). */
-export interface MilkyLegacyEndpointRow {
-  readonly context?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface MilkyEndpointConfig {
   readonly connection?: 'ws' | 'sse' | 'webhook' | 'wss';
-  readonly id?: string;
-  readonly baseUrl?: string;
-  readonly access_token?: string;
-  readonly path?: string;
-  readonly reconnect_interval?: number;
-  readonly heartbeat_interval?: number;
-}
-
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface MilkyAdapterConfig {
-  readonly connection?: 'ws' | 'sse' | 'webhook' | 'wss';
-  readonly id?: string;
-  readonly baseUrl?: string;
+  readonly id: string;
+  readonly baseUrl: string;
   readonly access_token?: string;
   readonly path?: string;
   readonly reconnect_interval?: number;
   readonly heartbeat_interval?: number;
-  /** Transitional: legacy root `endpoints[]` with `context: milky`. */
-  readonly endpoints?: ReadonlyArray<MilkyLegacyEndpointRow>;
 }
 
 export interface MilkyConfigBase {
@@ -74,7 +59,6 @@ export type ResolvedMilkyConfig =
   | MilkySseConfig
   | MilkyWebhookConfig
   | MilkyWssConfig;
-export type MilkyEndpointConfig = ResolvedMilkyConfig;
 
 export interface MilkyApiResponse<T = unknown> {
   status: 'ok' | 'failed';
@@ -127,20 +111,11 @@ function normalizeConnection(connection: string | undefined): 'ws' | 'sse' | 'we
   return 'ws';
 }
 
-export function resolveMilkyConfig(config: MilkyAdapterConfig = {}): ResolvedMilkyConfig {
-  const entry = config.endpoints?.find((item) => item.context === 'milky');
-  const connection = normalizeConnection(config.connection ?? entry?.connection);
-  const id = (typeof config.id === 'string' && config.id)
-    || (typeof entry?.id === 'string' && entry.id)
-    || process.env.MILKY_BOT_NAME
-    || 'milky-bot';
-  const baseUrl = config.baseUrl ?? entry?.baseUrl;
-  if (!baseUrl) {
-    throw new TypeError(
-      'Milky requires baseUrl (plugins.<key>.baseUrl or endpoints with context: milky)',
-    );
-  }
-  const access_token = config.access_token ?? entry?.access_token;
+export function resolveMilkyConfig(config: MilkyEndpointConfig): ResolvedMilkyConfig {
+  const connection = normalizeConnection(config.connection);
+  const id = requiredEndpointField(config.id, 'id');
+  const baseUrl = requiredEndpointField(config.baseUrl, 'baseUrl');
+  const access_token = optionalEndpointField(config.access_token);
   const base = {
     context: 'milky' as const,
     id,
@@ -152,8 +127,8 @@ export function resolveMilkyConfig(config: MilkyAdapterConfig = {}): ResolvedMil
     return {
       ...base,
       connection: 'ws',
-      reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
-      heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+      reconnect_interval: config.reconnect_interval ?? 5000,
+      heartbeat_interval: config.heartbeat_interval ?? 30_000,
     };
   }
 
@@ -161,32 +136,43 @@ export function resolveMilkyConfig(config: MilkyAdapterConfig = {}): ResolvedMil
     return {
       ...base,
       connection: 'sse',
-      reconnect_interval: config.reconnect_interval
-        ?? entry?.reconnect_interval
-        ?? 5_000,
+      reconnect_interval: config.reconnect_interval ?? 5_000,
     };
   }
 
   if (connection === 'webhook') {
-    const path = config.path ?? entry?.path;
-    if (!path) throw new TypeError('Milky connection:webhook requires path');
+    const path = requiredEndpointField(config.path, 'path');
     return { ...base, connection: 'webhook', path };
   }
 
   if (connection === 'wss') {
-    const path = config.path ?? entry?.path;
-    if (!path) throw new TypeError('Milky connection:wss requires path');
+    const path = requiredEndpointField(config.path, 'path');
     return {
       ...base,
       connection: 'wss',
       path,
-      heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+      heartbeat_interval: config.heartbeat_interval ?? 30_000,
     };
   }
 
   throw new TypeError(`Unknown Milky connection: ${String(connection)}`);
 }
 
+function requiredEndpointField(
+  value: unknown,
+  field: 'id' | 'baseUrl' | 'path',
+): string {
+  const resolved = optionalEndpointField(value);
+  if (!resolved) {
+    throw new TypeError(`Milky endpoint requires a non-empty ${field}`);
+  }
+  return resolved;
+}
+
+function optionalEndpointField(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
 /** 鉴权：Header Authorization: Bearer {token} 或 URL query access_token=xxx */
 function authHeaders(access_token?: string): Record<string, string> {
   const headers: Record<string, string> = {};

package/src/wss-endpoint.ts

@@ -56,17 +56,18 @@ export class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
   #ws?: MilkyWsSocket;
   #wsRelease?: () => void;
   #clientSocketRelease?: () => void;
-  readonly #lifecycle: EndpointLifecycle;
+  readonly #connectionLifecycle: EndpointLifecycle;
+  #connectionTask = Promise.resolve();
+  #started = false;
 
   constructor(options: MilkyWssEndpointOptions) {
     super();
     this.#logger = getAdapterLogger('milky', options.config.id);
     this.#options = options;
     this.#callApi = options.callApi ?? callApi;
-    this.#lifecycle = createEndpointLifecycle({
-      name: options.config.id,
+    this.#connectionLifecycle = createEndpointLifecycle({
+      name: `${options.config.id}:inbound`,
       reconnect: false,
-      heartbeat: { intervalMs: options.config.heartbeat_interval },
     });
     this.client = createMilkyEndpointClient(options.config, this.#callApi);
     this.management = createMilkyEndpointManagement({
@@ -82,23 +83,19 @@ export class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
   }
 
   async start(): Promise<void> {
-    await this.#lifecycle.start(async (lifecycleHandle) => {
-      const handle = this.#options.http.ws(this.#options.config.path);
-      this.#wsRelease = handle.onConnection((connection) => {
-        this.#acceptConnection(connection);
-      });
-      lifecycleHandle.onForceClose(() => {
-        this.#wsRelease?.();
-        this.#wsRelease = undefined;
-        this.#clientSocketRelease?.();
-        this.#clientSocketRelease = undefined;
-        try {
-          this.#ws?.close();
-        } catch {
-          /* ignore */
-        }
-        this.#ws = undefined;
-      });
+    if (this.#started) return;
+    this.#started = true;
+    const handle = this.#options.http.ws(this.#options.config.path);
+    this.#wsRelease = handle.onConnection((connection) => {
+      this.#connectionTask = this.#connectionTask
+        .then(() => this.#acceptConnection(connection))
+        .catch((error) => {
+          this.#logger.warn(formatCompact({
+            op: 'wss_connection_failed',
+            endpoint: this.#options.config.id,
+            error: error instanceof Error ? error.message : String(error),
+          }));
+        });
     });
     this.#logger.info(formatCompact({
       op: 'listen',
@@ -110,7 +107,12 @@ export class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
 
   async stop(): Promise<void> {
     this.close();
-    await this.#lifecycle.stop();
+    this.#wsRelease?.();
+    this.#wsRelease = undefined;
+    await this.#connectionTask;
+    await this.#connectionLifecycle.stop();
+    this.#ws = undefined;
+    this.#started = false;
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
@@ -187,36 +189,47 @@ export class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
     });
   }
 
-  #acceptConnection(connection: WsConnection): void {
+  async #acceptConnection(connection: WsConnection): Promise<void> {
     if (!verifyMilkyAccessToken(this.#options.config.access_token, connection.request)) {
       connection.socket.close(4003, 'Unauthorized');
       return;
     }
     const socket = connection.socket as unknown as MilkyWsSocket;
-    if (this.#ws) {
-      try {
-        this.#ws.close();
-      } catch {
-        /* ignore */
-      }
-    }
-    this.#ws = socket;
-    this.#lifecycle.startHeartbeat(() => {
-      try {
-        if (this.#ws?.readyState === WS_OPEN) this.#ws.ping?.();
-      } catch {
-        /* ignore */
-      }
-    });
-    this.#clientSocketRelease?.();
-    this.#clientSocketRelease = this.client.acceptWebSocket(socket);
-    socket.on('close', () => {
-      this.#clientSocketRelease?.();
-      this.#clientSocketRelease = undefined;
-      if (this.#ws === socket) {
-        this.#ws = undefined;
-        this.#lifecycle.stopHeartbeat();
-      }
+    await this.#connectionLifecycle.stop();
+    await this.#connectionLifecycle.start(async (lifecycleHandle) => {
+      this.#ws = socket;
+      const releaseClientSocket = this.client.acceptWebSocket(socket);
+      this.#clientSocketRelease = releaseClientSocket;
+      lifecycleHandle.onForceClose(() => {
+        if (this.#clientSocketRelease === releaseClientSocket) {
+          releaseClientSocket();
+          this.#clientSocketRelease = undefined;
+        }
+        try {
+          socket.close();
+        } catch {
+          /* ignore */
+        }
+        if (this.#ws === socket) this.#ws = undefined;
+      });
+      this.#connectionLifecycle.startHeartbeat(() => {
+        try {
+          if (socket.readyState === WS_OPEN) socket.ping?.();
+        } catch {
+          /* ignore */
+        }
+      }, this.#options.config.heartbeat_interval);
+      socket.on('message', () => {
+        this.#connectionLifecycle.notifyHeartbeatAck();
+      });
+      socket.on('close', () => {
+        if (this.#clientSocketRelease === releaseClientSocket) {
+          releaseClientSocket();
+          this.#clientSocketRelease = undefined;
+        }
+        if (this.#ws === socket) this.#ws = undefined;
+        lifecycleHandle.notifyClosed(new Error('Milky reverse WebSocket closed'));
+      });
     });
     this.#logger.debug(formatCompact({
       endpoint: this.#options.config.id,

package/agent/skills/milky.md

@@ -1,65 +0,0 @@
----
-name: milky
-platforms:
-  - milky
-description: >-
-  Milky 协议群管理能力。当用户在 Milky 协议的 QQ 群中请求踢人、禁言、设管理员、
-  改名片/群名或查成员/群信息时使用。即使用户没有提到 Milky，只要 Endpoint 平台是
-  Milky 协议且涉及群管理操作，就应触发。仅有昵称时必须先查成员列表获取 user_id。
-keywords:
-  - milky
-  - adapter:milky
-  - 群管理
-  - 禁言
-  - 踢人
-  - 管理员
-  - list_members
-tags:
-  - group
-  - management
-  - im
-tools:
-  - milky_kick_member
-  - milky_mute_member
-  - milky_mute_all
-  - milky_set_admin
-  - milky_set_nickname
-  - milky_set_group_name
-  - milky_list_members
-  - milky_get_group_info
----
-
-# Milky 群管理技能
-
-Milky 是 QQ 生态中的一种协议实现，提供标准群管理工具集。
-
-## 核心原则
-
-### 先查后操作
-
-只有昵称时，先 `milky_list_members` 获取 QQ 号再操作。
-
-**Example:**
-```
-用户: 禁言那个叫"阿强"的
-步骤1: milky_list_members → 找到 user_id = 654321
-步骤2: milky_mute_member(user_id=654321, duration=600)
-```
-
-## 工具详解
-
-| 工具 | 用途 | 权限 | 关键参数 |
-|------|------|------|----------|
-| `milky_kick_member` | 踢出成员 | admin | `user_id` |
-| `milky_mute_member` | 禁言/解禁 | admin | `user_id`, `duration`（秒，**0=解禁**） |
-| `milky_mute_all` | 全员禁言/解除 | admin | `enable` |
-| `milky_set_admin` | 设/取消管理员 | owner | `user_id`, `enable` |
-| `milky_set_nickname` | 改群名片 | admin | `user_id`, `nickname` |
-| `milky_set_group_name` | 改群名 | admin | `name` |
-| `milky_list_members` | 成员列表 | user | — |
-| `milky_get_group_info` | 群信息 | user | — |
-
-## 易错点
-
-1. **禁言 duration=0 是解禁**，不是永久禁言。
-2. **管理员设置需要群主权限**（owner），管理员无法设置其他管理员。

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

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

package/commands/endpoint/list.ts

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

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

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

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

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