@zhin.js/adapter-milky 1.1.18 → 1.1.20

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @zhin.js/adapter-milky
 
+## 1.1.20
+
+### Patch Changes
+
+- Updated dependencies [5e878ba]
+  - @zhin.js/page@1.1.12
+
+## 1.1.19
+
+### Patch Changes
+
+- 2c3610a: Move account lifecycle ownership into the generic Adapter base and let native Endpoints retain their SDK Client inheritance. Infer platform-specific operation Sessions from a single adapter registry while preserving command parameter, option, configuration and factory inference.
+
+  Bind message replies, management ports, login challenges and Agent cancellation to the captured account incarnation. Persist runtime account intent with encrypted, revision-checked Host storage; keep account management independent of Root process restarts. Require explicit operator confirmation before importing existing accounts, and give replacement accounts a new identity without inheriting previous Sessions.
+
+  Expose account save, start, stop, update and replacement through the existing adapter Console, with exact account ownership, truthful pending/unknown outcomes and no startup configuration or environment-file rewrites.
+
+  Complete the target migration across every adapter, the public authoring API, generators, examples and Console. This intentionally removes the old create factory, inheritable Endpoint/ClientEndpoint classes, Client descriptors and file-rewrite account management; plugin authors must use createAdapter, native Client inheritance and the single AdapterRegistry. Satori and OneBot12 require explicit platform/userId selection, and WeCom requires a separate agentId.
+
+  Verify opaque credential changes before the same configuration snapshot is committed. Drain admitted native callbacks across close/rollback, cancel target work on stop, and keep raw transport parsing, platform ACK timing and SDK native methods under their existing owners. Account metadata conceals credentials carried in URLs.
+
+- a9f4e48: PATCH COMPATIBILITY CUTOVER: this batch intentionally changes plugin APIs. The maintainer explicitly chose patch releases with declared version boundaries. Upgrade the complete tested dependency set; patch numbering does not promise compatibility with the removed interfaces.
+
+  The first planned floors are zhin.js 1.1.19, Core 1.1.54, Adapter 1.1.26, FeatureKit 1.1.10, Plugin Runtime 1.1.18, Runtime/Isolate 1.1.16 and Agent 1.1.45. Keep old-interface plugins with the earlier locked stack until they are migrated. Adapter's independent Feature API changes from 1.0.0 to 2.0.0; official consumers declare ^2.0.0. Existing Feature API admission rejects explicitly incompatible ranges; omitted API metadata keeps its existing behavior and does not certify compatibility. Runtime engine and patch-only release gates remain unchanged.
+
+  Use the native-Client Adapter target contract, canonical FeatureKit AdapterRegistry augmentation and named Endpoint control/management requests. Route message controls from canonical message/conversation refs; retain exact source authority and propagate caller/account/explicit-Root-stop cancellation. Replace removed Agent activity feedback exports with source-bound feedback. HMR pause/resume belongs to concrete plugin instances; plugins choose accepted-work policy without changing Controller commit/rollback authority. Cooperative worker/process control cancellation does not kill an isolate or reopen retired business admission.
+
+  Provide authenticated historical-data preview, exact selected binding, transactional application, authoritative inspection and explicit resumption, including active games. Preserve before-images and journals; never replay an unconfirmed effect, infer an account from an alias, or reuse historical permission grants. Owner V2 approvals remain inactive legacy data, while new writes use V3. Rollback requires matching software, lockfile and verified data; installing old code alone cannot read a new V3 approval file. Conflicting after-images are never overwritten.
+
+  See docs/plans/adapter-operation-version-boundaries.md and the Chinese/English upgrade guide for the complete version inventory, custom-plugin changes, acceptance and recovery sequence. These code and metadata changes do not authorize merging, publication, deployment, login, production migration or removal of installed workspace patches.
+
+- Updated dependencies [2c3610a]
+- Updated dependencies [a9f4e48]
+- Updated dependencies [f8505b0]
+- Updated dependencies [2c3610a]
+  - @zhin.js/adapter@1.1.26
+  - @zhin.js/feature-kit@1.1.10
+  - @zhin.js/core@1.1.54
+  - @zhin.js/host-http@1.1.12
+  - @zhin.js/client@1.1.22
+  - @zhin.js/page@1.1.11
+  - @zhin.js/skill@1.1.11
+
 ## 1.1.18
 
 ### Patch Changes

package/README.md

@@ -2,13 +2,15 @@
 
 Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器（Plugin Runtime）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **Webhook**、**反向 WS**（经 `httpHostToken`）与 **SSE**（HTTP GET `/event`，fetch 解析 `text/event-stream`）。
 
+账号由 `MilkyAdapter` 管理。Endpoint 直接继承实际 `MilkyV1Client`，保留原生方法与事件；框架生命周期、规范入站与发送经 `endpointSpec` 和 AdapterIndex 接入，不占用 Client 的原生 `start` / `stop` / `send` 方法。
+
 ## 功能特性
 
 - [Milky 协议](https://milky.ntqqrev.org/guide/communication) 兼容（事件 + HTTP API）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连协议端 `ws(s)://baseUrl/event`
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `Endpoint.emit(...)`；出站 `send({ conversation, payload })` → HTTP `send_*_message`
+- 入站经 `endpointSpec.events`；出站 `send({ conversation, payload })` → HTTP `send_*_message`
 
 ## 安装
 
@@ -19,19 +21,20 @@ pnpm add @zhin.js/adapter-milky
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/milky/index.ts`（`defineAdapter`）
-- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/core` — `endpointSpec.events` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 
 `AdapterIndex` 会把实例默认值与 `endpoints[]` 的逐项覆盖合并；协议层只接收一个已经展开的 endpoint 配置，不再读取嵌套 endpoint 或从进程环境推断 endpoint 身份。
 
-入站：`gateway.receive({ conversation: ConversationRef(kind: "private"|"group", id), message, content, sender, metadata })`  
+入站：`endpoint[endpointSpec].events.emit('message.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）
 
-每个 Endpoint 的 `$client` 是 `@imhelper/milky-v1` 的 `MilkyV1Client`。插件可直接调用
+Endpoint 直接继承 `@imhelper/milky-v1` 的 `MilkyV1Client`；当前操作的 `$client` 就是该实际实例。插件可直接调用
 `$client.call()`、`getGroupList()` 等公开能力；`defineHandler({ adapter: 'milky', event: ... })`
 使用 imhelper 的精确事件名与 payload 类型。HTTP、纯事件 WS/WSS 和 `ingest()` 都汇入同一个
-Client 事件流，Endpoint 仍独占账号连接、鉴权、重连和心跳。
+原生 Client 事件流；所属 `MilkyAdapter` 管理账号与运行实例，协议连接、鉴权、重连和心跳保留在该实际 Client 中。
 
 ## 前置条件
 
@@ -95,7 +98,7 @@ milky:
 启动后打开 Console 的「Milky」页（地址 `/milky`），可以：
 
 - 查看运行中的连接、点「测试连接」做连通性诊断；
-- 增删 `plugins.milky.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
+- 经所属 Adapter 增删持久化账号、启停单个 Endpoint；凭据由 Host 加密仓储保存，不改启动 YAML 或 `.env`，不重启进程；
 - 如果适配器要求登录，页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办；
 
 读取需要 `milky:read`，写操作需要 `milky:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `milky endpoint add`。

package/adapters/milky/index.js

@@ -3,10 +3,8 @@
  * 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";
+import { MilkyAdapter } from "../../lib/adapter.js";
+import {} from "../../lib/protocol.js";
 export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
@@ -16,36 +14,5 @@ export default defineAdapter({
         outboundMedia: ['url', 'base64'],
         interactive: 'text',
     },
-    create(context) {
-        const config = resolveMilkyConfig(context.config);
-        // 注册到插件运行时状态（milky endpoint list 的"运行中"数据源）
-        context.use(milkyRuntimeStateToken).endpoints.set(config.id, {
-            id: config.id,
-            mode: config.connection,
-        });
-        if (config.connection === 'webhook') {
-            return new MilkyWebhookEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        if (config.connection === 'wss') {
-            return new MilkyWssEndpoint({
-                id: context.id,
-                http: context.use(httpHostToken),
-                config,
-            });
-        }
-        if (config.connection === 'sse') {
-            return new MilkySseEndpoint({
-                id: context.id,
-                config,
-            });
-        }
-        return new MilkyWsEndpoint({
-            id: context.id,
-            config,
-        });
-    },
+    createAdapter: context => new MilkyAdapter(context),
 });

package/adapters/milky/index.ts

@@ -2,18 +2,10 @@
  * Convention entry: discover `adapters/milky/index.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { httpHostToken } from '@zhin.js/host-http';
+import { MilkyAdapter } from '../../src/adapter.js';
 import {
-  MilkySseEndpoint,
-  MilkyWebhookEndpoint,
-  MilkyWssEndpoint,
-  MilkyWsEndpoint,
-} from '../../src/endpoint.js';
-import {
-  resolveMilkyConfig,
   type MilkyEndpointConfig,
 } from '../../src/protocol.js';
-import { milkyRuntimeStateToken } from '../../src/milky-runtime-state.js';
 
 export {
   MilkySseEndpoint,
@@ -39,36 +31,5 @@ export default defineAdapter<MilkyEndpointConfig>({
     outboundMedia: ['url', 'base64'],
     interactive: 'text',
   },
-  create(context) {
-    const config = resolveMilkyConfig(context.config);
-    // 注册到插件运行时状态（milky endpoint list 的"运行中"数据源）
-    context.use(milkyRuntimeStateToken).endpoints.set(config.id, {
-      id: config.id,
-      mode: config.connection,
-    });
-    if (config.connection === 'webhook') {
-      return new MilkyWebhookEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    if (config.connection === 'wss') {
-      return new MilkyWssEndpoint({
-        id: context.id,
-        http: context.use(httpHostToken),
-        config,
-      });
-    }
-    if (config.connection === 'sse') {
-      return new MilkySseEndpoint({
-        id: context.id,
-        config,
-      });
-    }
-    return new MilkyWsEndpoint({
-      id: context.id,
-      config,
-    });
-  },
+  createAdapter: context => new MilkyAdapter(context),
 });

package/commands/milky/endpoint/definition.js

@@ -5,7 +5,6 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { milkyRuntimeStateToken } from "../../../lib/milky-runtime-state.js";
 export const milkyEndpointCommands = createEndpointCommands({
     adapterKey: 'milky',
     adapterDisplayName: 'Milky',
@@ -14,6 +13,5 @@ export const milkyEndpointCommands = createEndpointCommands({
         { key: 'path', description: 'webhook / reverse-wss 路径', descriptionI18n: { en: "Webhook / reverse-wss path" } },
         { key: 'access_token', env: true, description: 'Milky access token' },
     ],
-    running: (use) => use(milkyRuntimeStateToken).endpoints.values(),
     describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
 }, defineCommand);

package/commands/milky/endpoint/definition.ts

@@ -4,7 +4,6 @@
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { milkyRuntimeStateToken } from '../../../src/milky-runtime-state.js';
 
 export const milkyEndpointCommands = createEndpointCommands({
   adapterKey: 'milky',
@@ -14,6 +13,5 @@ export const milkyEndpointCommands = createEndpointCommands({
     { key: 'path', description: 'webhook / reverse-wss 路径', descriptionI18n: { en: "Webhook / reverse-wss path" } },
     { key: 'access_token', env: true, description: 'Milky access token' },
   ],
-  running: (use) => use(milkyRuntimeStateToken).endpoints.values(),
   describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
 }, defineCommand);

package/lib/adapter.d.ts

@@ -0,0 +1,21 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { type MilkyEndpointConfig } from './protocol.js';
+import { MilkyWsEndpoint, MilkyWssEndpoint, MilkySseEndpoint, MilkyWebhookEndpoint } from './endpoint.js';
+import { type MilkyClientEventMap } from './client.js';
+type MilkyEndpoint = MilkyWsEndpoint | MilkyWssEndpoint | MilkySseEndpoint | MilkyWebhookEndpoint;
+export declare class MilkyAdapter extends Adapter<MilkyEndpoint, MilkyEndpointConfig, MilkyClientEventMap> {
+    #private;
+    constructor(context: AdapterContext<MilkyEndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    get configurationIdentityProbeFields(): readonly string[];
+    get configurationUpdateFields(): readonly string[];
+    protected validateConfiguration(config: MilkyEndpointConfig): void;
+    protected identifyConfiguration(input: MilkyEndpointConfig, signal: AbortSignal): Promise<string | undefined>;
+    protected createEndpoint(input: MilkyEndpointConfig, execution: EndpointCreationContext): MilkyEndpoint;
+}
+declare module '@zhin.js/feature-kit' {
+    interface AdapterRegistry {
+        readonly milky: MilkyAdapter;
+    }
+}
+export {};

package/lib/adapter.js

@@ -0,0 +1,36 @@
+import { Adapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { callApi, resolveMilkyConfig } from './protocol.js';
+import { MilkyWsEndpoint, MilkyWssEndpoint, MilkySseEndpoint, MilkyWebhookEndpoint } from './endpoint.js';
+import { readMilkyResponse } from './client.js';
+export class MilkyAdapter extends Adapter {
+    #context;
+    constructor(context) { super(); this.#context = context; }
+    get configurationIdentityFields() { return ['id']; }
+    get configurationIdentityProbeFields() { return ['access_token', 'baseUrl']; }
+    get configurationUpdateFields() {
+        return ['connection', 'baseUrl', 'path', 'access_token', 'reconnect_interval', 'heartbeat_interval'];
+    }
+    validateConfiguration(config) { resolveMilkyConfig(config); }
+    async identifyConfiguration(input, signal) {
+        const config = resolveMilkyConfig(input);
+        signal.throwIfAborted();
+        const response = await callApi({ ...config, signal, action: 'get_login_info' });
+        signal.throwIfAborted();
+        const userId = readMilkyResponse(response, 'get_login_info')?.uin;
+        if (userId === 0 || userId === '0' || (typeof userId === 'string' && !userId.trim()))
+            return undefined;
+        if ((typeof userId !== 'number' && typeof userId !== 'string') || !String(userId).trim())
+            throw new Error('Milky login identity is unavailable');
+        return `qq:${userId}`;
+    }
+    createEndpoint(input, execution) {
+        const config = resolveMilkyConfig(input), id = execution.canonicalId, signal = execution.signal;
+        switch (config.connection) {
+            case 'wss': return new MilkyWssEndpoint({ id, config, signal, http: this.#context.use(httpHostToken) });
+            case 'webhook': return new MilkyWebhookEndpoint({ id, config, signal, http: this.#context.use(httpHostToken) });
+            case 'sse': return new MilkySseEndpoint({ id, config, signal });
+            case 'ws': return new MilkyWsEndpoint({ id, config, signal });
+        }
+    }
+}

package/lib/client.d.ts

@@ -1,21 +1,26 @@
-import { MilkyV1Client, type MilkyV1Event } from '@imhelper/milky-v1';
+import { MilkyV1Client, type MilkyV1Event, type MilkyV1Response } from '@imhelper/milky-v1';
 import { type EventMap, type ImHelperEventMap } from 'imhelper';
-import { type ClientEventPayloads } from 'zhin.js/adapter';
+import { type ClientEventPayloads, type PendingRpcRequest } from 'zhin.js/adapter';
 import type { ResolvedMilkyConfig, callApi } from './protocol.js';
 export { MilkyV1Client as MilkyClient } from '@imhelper/milky-v1';
 type MilkyClientEvents = ImHelperEventMap<string, MilkyV1Event, EventMap<string>>;
 export type MilkyClientEventMap = ClientEventPayloads<MilkyClientEvents>;
-/** Construct the exact public imhelper Client without handing it transport ownership. */
-export declare function createMilkyEndpointClient(config: ResolvedMilkyConfig, request: typeof callApi): MilkyV1Client;
-/** Use the Client's complete protocol response while keeping Endpoint internals data-oriented. */
-export declare function callMilkyClient<T = unknown>(client: MilkyV1Client, action: string, params?: Record<string, unknown>): Promise<T | undefined>;
-export declare function forwardMilkyClientEvents(client: MilkyV1Client, receive: (name: string, payload: unknown) => void): () => void;
-declare module '@zhin.js/feature-kit' {
-    interface AdapterClientRegistry {
-        readonly milky: {
-            readonly client: MilkyV1Client;
-            readonly events: MilkyClientEventMap;
-        };
-    }
+/** One account-bound transport, shared by native SDK and semantic requests. */
+export interface MilkyClientBinding {
+    readonly config: ResolvedMilkyConfig;
+    readonly request: typeof callApi;
+    readonly signal?: AbortSignal;
 }
-export declare const milkyClient: import("@zhin.js/adapter").EndpointClientToken<MilkyV1Client, ClientEventPayloads<MilkyClientEvents>>;
+export type MilkyActionCaller = (request: PendingRpcRequest) => Promise<MilkyV1Response>;
+export declare function createMilkyActionCaller({ config, request, signal }: MilkyClientBinding): MilkyActionCaller;
+export declare function milkyClientOptions({ config, call }: {
+    readonly config: ResolvedMilkyConfig;
+    readonly call: MilkyActionCaller;
+}): ConstructorParameters<typeof MilkyV1Client>[0];
+/**
+ * Semantic ports must retain the SDK's status + retcode check when using its shared HTTP caller.
+ * A contradictory envelope proves neither success nor rejection.
+ * @see https://milky.ntqqrev.org/guide/communication
+ */
+export declare function readMilkyResponse<T = unknown>(response: unknown, action: string): T | undefined;
+export declare function forwardMilkyClientEvents(client: MilkyV1Client, receive: (name: string, payload: unknown) => void): () => void;

package/lib/client.js

@@ -1,27 +1,35 @@
-import { MilkyV1Client, } from '@imhelper/milky-v1';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { EventFactory, } from 'imhelper';
-import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+import { forwardEndpointClientEvents, } from 'zhin.js/adapter';
 export { MilkyV1Client as MilkyClient } from '@imhelper/milky-v1';
-/** Construct the exact public imhelper Client without handing it transport ownership. */
-export function createMilkyEndpointClient(config, request) {
-    return new MilkyV1Client({
-        baseUrl: config.baseUrl,
-        selfId: config.id,
-        accessToken: config.access_token,
-        receiveMode: 'manual',
-        call: (action, params) => request({
-            baseUrl: config.baseUrl,
-            access_token: config.access_token,
-        }, action, params),
-    });
+export function createMilkyActionCaller({ config, request, signal }) {
+    return action => {
+        const operationSignal = signal && action.signal ? AbortSignal.any([signal, action.signal]) : signal ?? action.signal;
+        if (operationSignal?.aborted)
+            throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint request ended before submission', 'not_sent', { cause: operationSignal.reason });
+        return request({ baseUrl: config.baseUrl, access_token: config.access_token, ...action, signal: operationSignal });
+    };
 }
-/** Use the Client's complete protocol response while keeping Endpoint internals data-oriented. */
-export async function callMilkyClient(client, action, params) {
-    const response = await client.call(action, params);
-    if (response.status !== 'ok') {
-        throw new Error(`Milky API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`);
+export function milkyClientOptions({ config, call }) {
+    return { baseUrl: config.baseUrl, selfId: config.id, accessToken: config.access_token, receiveMode: 'manual',
+        call: (action, params) => call({ action, params }),
+    };
+}
+/**
+ * Semantic ports must retain the SDK's status + retcode check when using its shared HTTP caller.
+ * A contradictory envelope proves neither success nor rejection.
+ * @see https://milky.ntqqrev.org/guide/communication
+ */
+export function readMilkyResponse(response, action) {
+    if (response && typeof response === 'object') {
+        const result = response;
+        if (result.status === 'ok' && result.retcode === 0)
+            return result.data;
+        if (result.status === 'failed' && Number.isSafeInteger(result.retcode) && result.retcode !== 0) {
+            throw new EndpointDeliveryError('platform_rejected', `Milky API ${action}: retcode=${result.retcode}${typeof result.message === 'string' && result.message ? ` ${result.message}` : ''}`, 'rejected');
+        }
     }
-    return response.data;
+    throw new EndpointDeliveryError('delivery_unconfirmed', `Milky API ${action} did not confirm the action result`, 'unknown');
 }
 const milkyClientEventNames = Object.freeze([
     ...EventFactory.getSupportedEventTypes(),
@@ -30,4 +38,3 @@ const milkyClientEventNames = Object.freeze([
 export function forwardMilkyClientEvents(client, receive) {
     return forwardEndpointClientEvents(client, milkyClientEventNames, receive);
 }
-export const milkyClient = defineEndpointClient('milky');

package/lib/console.d.ts

@@ -5,4 +5,4 @@
  */
 import { type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-export declare function createMilkyConsoleRpc(resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;
+export declare function createMilkyConsoleRpc(_resources: AdapterConsoleResources, getConfig: () => unknown): PluginConsoleRpc;

package/lib/console.js

@@ -4,13 +4,10 @@
  * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
  */
 import { createAdapterConsoleRpc } from 'zhin.js/adapter';
-import { milkyRuntimeStateToken } from './milky-runtime-state.js';
 import { milkyConsoleSpec } from './console-spec.js';
-export function createMilkyConsoleRpc(resources, getConfig) {
-    const state = resources.use(milkyRuntimeStateToken);
+export function createMilkyConsoleRpc(_resources, getConfig) {
     return createAdapterConsoleRpc({
         ...milkyConsoleSpec,
-        running: () => state.endpoints.values(),
         getConfig,
-    }, resources);
+    });
 }

package/lib/endpoint-management.d.ts

@@ -9,9 +9,9 @@
  * - group → {group_id:number, name: group_name ?? name}
  * - 群成员列表保持 Milky 原生形状，仅保证数组
  */
-import type { EndpointManagement } from 'zhin.js/adapter';
+import { type EndpointManagement, type PendingRpcRequest } from 'zhin.js/adapter';
 /** 管理面只依赖 endpoint 的 callApi（ws/wss/sse/webhook 四种传输各自实现）。 */
 export interface MilkyManagementCaller {
-    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    callApi(request: PendingRpcRequest): Promise<unknown>;
 }
 export declare function createMilkyEndpointManagement(endpoint: MilkyManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -1,7 +1,7 @@
 export function createMilkyEndpointManagement(endpoint) {
     return Object.freeze({
-        async listFriends() {
-            const data = asRecord(await endpoint.callApi('get_friend_list'));
+        async listFriends(request = {}) {
+            const data = asRecord(await endpoint.callApi({ action: 'get_friend_list', signal: request.signal }));
             return toArray(data.friends).map((value) => {
                 const friend = asRecord(value);
                 return {
@@ -11,8 +11,8 @@ export function createMilkyEndpointManagement(endpoint) {
                 };
             });
         },
-        async listGroups() {
-            const data = asRecord(await endpoint.callApi('get_group_list'));
+        async listGroups(request = {}) {
+            const data = asRecord(await endpoint.callApi({ action: 'get_group_list', signal: request.signal }));
             return toArray(data.groups).map((value) => {
                 const group = asRecord(value);
                 return {
@@ -21,10 +21,10 @@ export function createMilkyEndpointManagement(endpoint) {
                 };
             });
         },
-        async listGroupMembers(groupId) {
-            const data = asRecord(await endpoint.callApi('get_group_member_list', {
-                group_id: toNumberId(groupId, 'group_id'),
-            }));
+        async listGroupMembers({ groupId, signal }) {
+            const data = asRecord(await endpoint.callApi({ action: 'get_group_member_list', signal, params: {
+                    group_id: toNumberId(groupId, 'group_id'),
+                } }));
             return toArray(data.members);
         },
     });

package/lib/index.d.ts

@@ -1,6 +1,7 @@
-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 { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatOutboundSegments, isMentioned, isMessageReceiveEvent, milkyInboundConversation, parseMessageReceiveData, resolveMilkyConfig, senderNickname, type MilkyApiClientOptions, type MilkyApiRequest, 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 { MilkyClient, type MilkyClientEventMap, } from './client.js';
 export type { MilkyAdapterConfig as ImHelperMilkyAdapterConfig, MilkyActionUrlResolver, MilkyCall, MilkyMessageReceiveEvent, MilkyMessageRecallEvent, MilkyV1ClientConfig, MilkyV1Event, MilkyV1Response, } from '@imhelper/milky-v1';
 export { ProtocolError } from '@imhelper/milky-v1';
 export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';
+export { MilkyAdapter } from './adapter.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatOutboundSegments, isMentioned, isMessageReceiveEvent, milkyInboundConversation, parseMessageReceiveData, resolveMilkyConfig, senderNickname, } from './protocol.js';
 export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, consumeSseBuffer, openSseStream, verifyMilkyAccessToken, } from './endpoint.js';
-export { MilkyClient, milkyClient, } from './client.js';
+export { MilkyClient, } from './client.js';
 export { ProtocolError } from '@imhelper/milky-v1';
+export { MilkyAdapter } from './adapter.js';

package/lib/protocol.d.ts

@@ -93,13 +93,18 @@ export interface MilkyOutgoingSegment {
 export interface MilkyApiClientOptions {
     readonly baseUrl: string;
     readonly access_token?: string;
+    readonly signal?: AbortSignal;
 }
 export declare function resolveMilkyConfig(config: MilkyEndpointConfig): ResolvedMilkyConfig;
 /**
  * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
  * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。
  */
-export declare function callApi<T = unknown>(options: MilkyApiClientOptions, apiName: string, params?: Record<string, unknown>): Promise<MilkyApiResponse<T>>;
+export interface MilkyApiRequest extends MilkyApiClientOptions {
+    readonly action: string;
+    readonly params?: Record<string, unknown>;
+}
+export declare function callApi<T = unknown>({ action: apiName, params, ...options }: MilkyApiRequest): Promise<MilkyApiResponse<T>>;
 /** 根据 event_type 判断是否为 message_receive，并解析 data */
 export declare function parseMessageReceiveData(event: MilkyEvent): MilkyIncomingMessage | null;
 export declare function isMessageReceiveEvent(event: MilkyEvent): event is MilkyEvent & {

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/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('milky');
 function normalizeConnection(connection) {
@@ -75,24 +75,25 @@ function authQuery(access_token) {
         return '';
     return `access_token=${encodeURIComponent(access_token)}`;
 }
-/**
- * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
- * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。
- */
-export async function callApi(options, apiName, params = {}) {
+export async function callApi({ action: apiName, params = {}, ...options }) {
     const { baseUrl, access_token } = options;
     const url = new URL(`/api/${apiName}`, baseUrl.replace(/\/$/, ''));
     const q = authQuery(access_token);
     if (q)
         url.search = (url.search ? `${url.search}&` : '') + q;
-    const res = await fetch(url.toString(), {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            ...authHeaders(access_token),
-        },
-        body: JSON.stringify(Object.keys(params).length ? params : {}),
-    });
+    if (options.signal?.aborted)
+        throw new EndpointDeliveryError('endpoint_inactive', 'Milky request ended before submission', 'not_sent', { cause: options.signal.reason });
+    const payload = JSON.stringify(Object.keys(params).length ? params : {});
+    let res;
+    try {
+        res = await fetch(url.toString(), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', ...authHeaders(access_token) },
+            body: payload, signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'Milky HTTP request outcome is unknown', 'unknown', { cause });
+    }
     const text = await res.text();
     let body;
     try {

package/lib/sse-endpoint.d.ts

@@ -1,9 +1,9 @@
 /**
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
-import { type MilkyClient } from './client.js';
+import { MilkyClient } from './client.js';
 import { callApi, type MilkySseConfig } from './protocol.js';
 import { type SseClientHandle } from './sse-client.js';
 export type CreateMilkySseStream = (options: {
@@ -15,18 +15,13 @@ export type CreateMilkySseStream = (options: {
 }) => SseClientHandle;
 export interface MilkySseEndpointOptions {
     readonly id: CapabilityId;
+    readonly signal?: AbortSignal;
     readonly config: MilkySseConfig;
     readonly createSseStream?: CreateMilkySseStream;
     readonly callApi?: typeof callApi;
 }
-export declare class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
+export declare class MilkySseEndpoint extends MilkyClient implements Endpoint {
     #private;
-    readonly client: MilkyClient;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: MilkySseEndpointOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recallMessage(id: string): Promise<void>;
 }