@zhin.js/adapter-milky 1.1.17 → 1.1.19

package/lib/wss-endpoint.js

@@ -1,20 +1,21 @@
 /**
  * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
  */
-import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { verifyMilkyAccessToken } from './milky-auth.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents } from './client.js';
+import { createMilkyActionCaller, readMilkyResponse, milkyClientOptions, forwardMilkyClientEvents, MilkyClient } from './client.js';
 import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const WS_OPEN = 1;
-export class MilkyWssEndpoint extends ClientEndpoint {
-    client;
+export class MilkyWssEndpoint extends MilkyClient {
+    [endpointSpec];
+    #open = false;
     #logger;
     #options;
-    #callApi;
-    management;
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    #management;
+    #call;
+    #control = createRecallEndpointControl((id, signal) => this.#recallMessage({ id, signal }));
     #ws;
     #wsRelease;
     #clientSocketRelease;
@@ -22,24 +23,38 @@ export class MilkyWssEndpoint extends ClientEndpoint {
     #connectionTask = Promise.resolve();
     #started = false;
     constructor(options) {
-        super();
+        const call = createMilkyActionCaller({ config: options.config, request: options.callApi ?? callApi, signal: options.signal });
+        super(milkyClientOptions({ config: options.config, call }));
+        this.#call = call;
         this.#logger = getAdapterLogger('milky', options.config.id);
         this.#options = options;
-        this.#callApi = options.callApi ?? callApi;
         this.#connectionLifecycle = createEndpointLifecycle({
             name: `${options.config.id}:inbound`,
             reconnect: false,
         });
-        this.client = createMilkyEndpointClient(options.config, this.#callApi);
-        this.management = createMilkyEndpointManagement({
-            callApi: (action, params) => callMilkyClient(this.client, action, params),
+        this.#management = createMilkyEndpointManagement({
+            callApi: request => call(request).then(response => readMilkyResponse(response, request.action)),
+        });
+        const readTransportState = () => this.#connectionLifecycle.state;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            name: options.config.id,
+            start: () => this.#start(), open: () => { this.#open = true; },
+            close: () => { this.#open = false; }, stop: () => this.#stop(),
+            send: request => this.#send(request),
+            management: this.#management, control: this.#control,
+            get transportState() { return readTransportState(); },
+        });
+        forwardMilkyClientEvents(this, (name, payload) => {
+            void this[endpointSpec].events.run(() => {
+                if (!this.#open && !this.#started)
+                    return;
+                void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
+                if (name === 'event')
+                    this.#admitRaw(payload);
+            }).catch(error => this.#warnPlatformEvent(error));
         });
-        this.bindClientEvents((receive) => forwardMilkyClientEvents(this.client, receive), (name, payload) => {
-            if (name === 'event')
-                this.#admitRaw(payload);
-        }, (_name, error) => this.#warnPlatformEvent(error));
     }
-    async start() {
+    async #start() {
         if (this.#started)
             return;
         this.#started = true;
@@ -62,8 +77,8 @@ export class MilkyWssEndpoint extends ClientEndpoint {
             path: this.#options.config.path,
         }));
     }
-    async stop() {
-        this.close();
+    async #stop() {
+        this.#open = false;
         this.#wsRelease?.();
         this.#wsRelease = undefined;
         await this.#connectionTask;
@@ -71,10 +86,10 @@ export class MilkyWssEndpoint extends ClientEndpoint {
         this.#ws = undefined;
         this.#started = false;
     }
-    async send({ conversation, payload }) {
+    async #send({ conversation, payload, signal }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await callMilkyClient(this.client, action, params);
+        const data = readMilkyResponse(await this.#call({ action, params, signal }), action);
         const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         this.#logger.debug(formatCompact({
             op: 'milky_send',
@@ -84,24 +99,26 @@ export class MilkyWssEndpoint extends ClientEndpoint {
         }));
         return messageId;
     }
-    async recallMessage(id) {
+    async #recallMessage({ id, signal }) {
         const parsed = parseMilkyMessageId(id);
         if (!parsed)
             throw new Error(`Invalid message id: ${id}`);
         if (parsed.message_scene === 'group') {
-            await callMilkyClient(this.client, 'recall_group_message', {
-                group_id: parsed.peer_id,
-                message_seq: parsed.message_seq,
-            });
+            readMilkyResponse(await this.#call({ action: 'recall_group_message', signal, params: {
+                    group_id: parsed.peer_id,
+                    message_seq: parsed.message_seq,
+                } }), 'recall_group_message');
         }
         else {
-            await callMilkyClient(this.client, 'recall_private_message', {
-                user_id: parsed.peer_id,
-                message_seq: parsed.message_seq,
-            });
+            readMilkyResponse(await this.#call({ action: 'recall_private_message', signal, params: {
+                    user_id: parsed.peer_id,
+                    message_seq: parsed.message_seq,
+                } }), 'recall_private_message');
         }
     }
     #admitRaw(event) {
+        if (event.self_id != null)
+            this[endpointSpec].reportSelfUserId(String(event.self_id));
         const data = parseMessageReceiveData(event);
         if (!data)
             return;
@@ -111,14 +128,16 @@ export class MilkyWssEndpoint extends ClientEndpoint {
         this.#logger.warn(formatCompact({ op: 'milky_platform_event_failed', error: error instanceof Error ? error.message : String(error) }));
     }
     #admitMessage(data, event) {
-        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const conversation = { ...milkyInboundConversation(String(this.#options.id), data), endpoint: this[endpointSpec].identity };
         const target = `${conversation.kind}:${conversation.id}`;
         const content = formatInboundContent(data);
         const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event,
+            ...(typeof event.time === 'number' ? { platformSentAt: event.time * 1000 } : {}),
             conversation,
             message: { conversation, id: formatInboundMessageId(data) },
             content,
@@ -152,7 +171,7 @@ export class MilkyWssEndpoint extends ClientEndpoint {
         await this.#connectionLifecycle.stop();
         await this.#connectionLifecycle.start(async (lifecycleHandle) => {
             this.#ws = socket;
-            const releaseClientSocket = this.client.acceptWebSocket(socket);
+            const releaseClientSocket = this.acceptWebSocket(socket);
             this.#clientSocketRelease = releaseClientSocket;
             lifecycleHandle.onForceClose(() => {
                 if (this.#clientSocketRelease === releaseClientSocket) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js Milky adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -42,13 +43,16 @@
     "@imhelper/milky-v1": "1.0.7",
     "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/client": "1.1.22",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/skill": "1.1.10"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/skill": "1.1.11"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -56,17 +60,17 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.43",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.17"
+    "@zhin.js/agent": "1.1.45",
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/agent": "^1.1.43",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/agent": "^1.1.45",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -103,7 +107,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -112,6 +116,10 @@
       {
         "package": "@zhin.js/skill",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'Milky',
+    titleI18n: { en: 'Milky' },
+    icon: 'Milk',
+    order: 68,
+    requiredPermissions: ['milky:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/milky`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('milky');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'Milky',
+  titleI18n: { en: 'Milky' },
+  icon: 'Milk',
+  order: 68,
+  requiredPermissions: ['milky:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/milky`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('milky');

package/plugin.js

@@ -1,14 +1,12 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
-import { definePlugin } from 'zhin.js';
-import { milkyRuntimeStateToken } from "./lib/milky-runtime-state.js";
+import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
+import { createMilkyConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'milky',
     metadata: {
         displayName: 'Milky Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（milky endpoint list 的"运行中"数据源）
-        context.resources.provide(milkyRuntimeStateToken, createEndpointRuntimeState());
+        context.resources.provide(pluginConsoleRpcToken, createMilkyConsoleRpc(context.resources, () => context.config.get()));
     },
 });

package/src/adapter.ts

@@ -0,0 +1,39 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { callApi, resolveMilkyConfig, type MilkyEndpointConfig } from './protocol.js';
+import { MilkyWsEndpoint, MilkyWssEndpoint, MilkySseEndpoint, MilkyWebhookEndpoint } from './endpoint.js';
+import { readMilkyResponse, type MilkyClientEventMap } from './client.js';
+
+type MilkyEndpoint = MilkyWsEndpoint | MilkyWssEndpoint | MilkySseEndpoint | MilkyWebhookEndpoint;
+export class MilkyAdapter extends Adapter<MilkyEndpoint, MilkyEndpointConfig, MilkyClientEventMap> {
+  readonly #context: AdapterContext<MilkyEndpointConfig>;
+  constructor(context: AdapterContext<MilkyEndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['access_token', 'baseUrl']; }
+  override get configurationUpdateFields(): readonly string[] {
+    return ['connection', 'baseUrl', 'path', 'access_token', 'reconnect_interval', 'heartbeat_interval'];
+  }
+  protected override validateConfiguration(config: MilkyEndpointConfig): void { resolveMilkyConfig(config); }
+  protected override async identifyConfiguration(input: MilkyEndpointConfig, signal: AbortSignal): Promise<string | undefined> {
+    const config = resolveMilkyConfig(input);
+    signal.throwIfAborted();
+    const response = await callApi<{ uin?: unknown }>({ ...config, signal, action: 'get_login_info' });
+    signal.throwIfAborted();
+    const userId = readMilkyResponse<{ uin?: unknown }>(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}`;
+  }
+  protected createEndpoint(input: MilkyEndpointConfig, execution: EndpointCreationContext): MilkyEndpoint {
+    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 });
+    }
+  }
+}
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly milky: MilkyAdapter; }
+}

package/src/client.ts

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import {
   MilkyV1Client,
   type MilkyV1Event,
@@ -9,9 +10,9 @@ import {
   type ImHelperEventMap,
 } from 'imhelper';
 import {
-  defineEndpointClient,
   forwardEndpointClientEvents,
   type ClientEventPayloads,
+  type PendingRpcRequest,
 } from 'zhin.js/adapter';
 import type { ResolvedMilkyConfig, callApi } from './protocol.js';
 
@@ -20,40 +21,44 @@ 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 function createMilkyEndpointClient(
-  config: ResolvedMilkyConfig,
-  request: typeof callApi,
-): MilkyV1Client {
-  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,
-    ),
-  });
+/** 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 type MilkyActionCaller = (request: PendingRpcRequest) => Promise<MilkyV1Response>;
+export function createMilkyActionCaller({ config, request, signal }: MilkyClientBinding): MilkyActionCaller {
+  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 });
+  };
+}
+export function milkyClientOptions({ config, call }: {
+  readonly config: ResolvedMilkyConfig;
+  readonly call: MilkyActionCaller;
+}): ConstructorParameters<typeof MilkyV1Client>[0] {
+  return { baseUrl: config.baseUrl, selfId: config.id, accessToken: config.access_token, receiveMode: 'manual',
+    call: (action, params) => call({ action, params }),
+  };
 }
 
-/** Use the Client's complete protocol response while keeping Endpoint internals data-oriented. */
-export async function callMilkyClient<T = unknown>(
-  client: MilkyV1Client,
-  action: string,
-  params?: Record<string, unknown>,
-): Promise<T | undefined> {
-  const response: MilkyV1Response<T> = await client.call<T>(action, params);
-  if (response.status !== 'ok') {
-    throw new Error(
-      `Milky API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`,
-    );
+/**
+ * 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<T = unknown>(response: unknown, action: string): T | undefined {
+  if (response && typeof response === 'object') {
+    const result = response as Partial<MilkyV1Response<unknown>>;
+    if (result.status === 'ok' && result.retcode === 0) return result.data as T | undefined;
+    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([
@@ -67,14 +72,3 @@ export function forwardMilkyClientEvents(
 ): () => void {
   return forwardEndpointClientEvents(client, milkyClientEventNames, receive);
 }
-
-declare module '@zhin.js/feature-kit' {
-  interface AdapterClientRegistry {
-    readonly milky: {
-      readonly client: MilkyV1Client;
-      readonly events: MilkyClientEventMap;
-    };
-  }
-}
-
-export const milkyClient = defineEndpointClient<MilkyV1Client, MilkyClientEventMap>('milky');

package/src/console-spec.ts

@@ -0,0 +1,17 @@
+/**
+ * Milky Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const milkyConsoleSpec = {
+  adapterKey: 'milky',
+  adapterDisplayName: 'Milky',
+  fields: [
+    { key: 'baseUrl', required: true, description: 'Milky HTTP API base URL' },
+    { key: 'path', description: 'webhook / reverse-wss 路径', descriptionI18n: { en: 'Webhook / reverse-wss path' } },
+    { key: 'access_token', env: true, description: 'Milky access token' },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/milky',
+  readPermission: 'milky:read',
+  writePermission: 'milky:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,18 @@
+/**
+ * Milky Console RPC：运行状态 + endpoint 增删（原 `milky endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { milkyConsoleSpec } from './console-spec.js';
+
+export function createMilkyConsoleRpc(
+  _resources: AdapterConsoleResources,
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  return createAdapterConsoleRpc({
+    ...milkyConsoleSpec,
+    getConfig,
+  });
+}

package/src/endpoint-management.ts

@@ -9,23 +9,26 @@
  * - group → {group_id:number, name: group_name ?? name}
  * - 群成员列表保持 Milky 原生形状，仅保证数组
  */
-import type {
-  EndpointFriend,
-  EndpointGroup,
-  EndpointManagement,
+import {
+  type EndpointFriend,
+  type EndpointGroup,
+  type EndpointManagement,
+  type EndpointManagementRequest,
+  type EndpointGroupRequest,
+  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 function createMilkyEndpointManagement(
   endpoint: MilkyManagementCaller,
 ): EndpointManagement {
   return Object.freeze<EndpointManagement>({
-    async listFriends(): Promise<readonly EndpointFriend[]> {
-      const data = asRecord(await endpoint.callApi('get_friend_list'));
+    async listFriends(request: EndpointManagementRequest = {}): Promise<readonly EndpointFriend[]> {
+      const data = asRecord(await endpoint.callApi({ action: 'get_friend_list', signal: request.signal }));
       return toArray(data.friends).map((value) => {
         const friend = asRecord(value);
         return {
@@ -35,8 +38,8 @@ export function createMilkyEndpointManagement(
         };
       });
     },
-    async listGroups(): Promise<readonly EndpointGroup[]> {
-      const data = asRecord(await endpoint.callApi('get_group_list'));
+    async listGroups(request: EndpointManagementRequest = {}): Promise<readonly EndpointGroup[]> {
+      const data = asRecord(await endpoint.callApi({ action: 'get_group_list', signal: request.signal }));
       return toArray(data.groups).map((value) => {
         const group = asRecord(value);
         return {
@@ -45,10 +48,10 @@ export function createMilkyEndpointManagement(
         };
       });
     },
-    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
-      const data = asRecord(await endpoint.callApi('get_group_member_list', {
+    async listGroupMembers({ groupId, signal }: EndpointGroupRequest): Promise<readonly unknown[]> {
+      const data = asRecord(await endpoint.callApi({ action: 'get_group_member_list', signal, params: {
         group_id: toNumberId(groupId, 'group_id'),
-      }));
+      } }));
       return toArray(data.members);
     },
   });

package/src/index.ts

@@ -13,6 +13,7 @@ export {
   resolveMilkyConfig,
   senderNickname,
   type MilkyApiClientOptions,
+  type MilkyApiRequest,
   type MilkyApiResponse,
   type MilkyConfigBase,
   type MilkyEndpointConfig,
@@ -47,7 +48,6 @@ export {
 
 export {
   MilkyClient,
-  milkyClient,
   type MilkyClientEventMap,
 } from './client.js';
 
@@ -63,3 +63,4 @@ export type {
 } from '@imhelper/milky-v1';
 export { ProtocolError } from '@imhelper/milky-v1';
 export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';
+export { MilkyAdapter } from './adapter.js';

package/src/protocol.ts

@@ -4,7 +4,7 @@
  * Spec: https://milky.ntqqrev.org/
  */
 
-import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
@@ -104,6 +104,7 @@ export interface MilkyOutgoingSegment {
 export interface MilkyApiClientOptions {
   readonly baseUrl: string;
   readonly access_token?: string;
+  readonly signal?: AbortSignal;
 }
 
 function normalizeConnection(connection: string | undefined): 'ws' | 'sse' | 'webhook' | 'wss' {
@@ -191,24 +192,29 @@ function authQuery(access_token?: string): string {
  * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
  * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。
  */
+export interface MilkyApiRequest extends MilkyApiClientOptions {
+  readonly action: string;
+  readonly params?: Record<string, unknown>;
+}
 export async function callApi<T = unknown>(
-  options: MilkyApiClientOptions,
-  apiName: string,
-  params: Record<string, unknown> = {},
+  { action: apiName, params = {}, ...options }: MilkyApiRequest,
 ): Promise<MilkyApiResponse<T>> {
   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: Response;
+  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: MilkyApiResponse<T>;