@zhin.js/adapter-milky 6.0.14 → 7.0.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @zhin.js/adapter-milky
 
+## 7.0.1
+
+### Patch Changes
+
+- 4e8117c: Expose the published imhelper protocol Clients from every Endpoint, preserve native action responses, and route host-owned HTTP, WebSocket, and raw ingress through the Client APIs. Add the shared `ClientEndpoint` deep base so concrete transports inherit one open-gated Client event bridge, and move reverse WebSocket lifecycle and heartbeat cleanup onto the common lifecycle state machine.
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- 2ca9a52: Upgrade the protocol Clients to imhelper 1.0.7, keep receiver ownership exclusively in Endpoint through manual mode, expose structured protocol errors, and support canonical non-message Client events.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+
+## 7.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
 ## 6.0.14
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器（Plugin Runtime）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连协议端 `ws(s)://baseUrl/event`
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `messageGatewayToken`；出站 `send({ conversation, payload })` → HTTP `send_*_message`
+- 入站经 `Endpoint.emit(...)`；出站 `send({ conversation, payload })` → HTTP `send_*_message`
 
 ## 安装
 
@@ -19,13 +19,24 @@ pnpm add @zhin.js/adapter-milky
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/milky.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
 入站：`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）
 
+每个 Endpoint 的 `$client` 是 `@imhelper/milky-v1` 的 `MilkyV1Client`。插件可直接调用
+`$client.call()`、`getGroupList()` 等公开能力；`defineHandler({ adapter: 'milky', event: ... })`
+使用 imhelper 的精确事件名与 payload 类型。HTTP、纯事件 WS/WSS 和 `ingest()` 都汇入同一个
+Client 事件流，Endpoint 仍独占账号连接、鉴权、重连和心跳。
+
+## 前置条件
+
+1. 启动兼容 Milky 的实现，并记录 HTTP API 与事件连接地址。
+2. 正向 WS/SSE 需 Zhin 主动可达实现端；Webhook/反向 WS 需实现端可达 Zhin HTTP Host。
+3. 两端配置相同的 `access_token`，生产环境不要暴露无鉴权接口。
+
 ## 最小配置
 
 ```yaml
@@ -48,7 +59,8 @@ plugins:
 | connection | 状态 |
 |------------|------|
 | `ws` | 已实现（推荐） |
-| `sse` | HTTP GET `/event`（`Accept: text/event-stream`） || `webhook` | 已实现：POST 入站 + baseUrl HTTP API 出站 |
+| `sse` | HTTP GET `/event`（`Accept: text/event-stream`） |
+| `webhook` | 已实现：POST 入站 + baseUrl HTTP API 出站 |
 | `wss` | 已实现：反向 WS（httpHostToken） |
 
 ## 鉴权
@@ -74,6 +86,15 @@ plugins:
 - [Milky 通信](https://milky.ntqqrev.org/guide/communication)
 - [适配器概览](https://zhin.js.org/essentials/adapters)
 
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| WS/SSE 无事件 | 核对 `baseUrl`、连接模式与实现端事件服务 |
+| 401 或握手失败 | 确认 Bearer/query 中的 `access_token` 与实现端一致 |
+| Webhook/WSS 无法连接 | 检查 HTTP Host、网络可达性与回调路径 |
+| 能收不能发 | 检查 HTTP API 与发送动作支持情况 |
+
 ## 许可证
 
 MIT License

package/adapters/milky.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/milky.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, } from "../lib/endpoint.js";
 import { resolveMilkyConfig, } from "../lib/protocol.js";
@@ -11,6 +10,7 @@ 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'],
     // Milky 协议资源 uri 消费 http(s):// 与 base64:// 形式；无卡片交互面，交互段降级纯文本。
     segments: {
         outboundMedia: ['url', 'base64'],
@@ -18,8 +18,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveMilkyConfig(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（milky.endpoint list 的"运行中"数据源）
         context.use(milkyRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -28,8 +26,6 @@ export default defineAdapter({
         if (config.connection === 'webhook') {
             return new MilkyWebhookEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -37,8 +33,6 @@ export default defineAdapter({
         if (config.connection === 'wss') {
             return new MilkyWssEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -46,15 +40,11 @@ export default defineAdapter({
         if (config.connection === 'sse') {
             return new MilkySseEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 config,
             });
         }
         return new MilkyWsEndpoint({
             id: context.id,
-            gateway,
-            sideEvents,
             config,
         });
     },

package/adapters/milky.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/milky.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   MilkySseEndpoint,
@@ -34,6 +33,7 @@ export type {
 
 export default defineAdapter<MilkyAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // Milky 协议资源 uri 消费 http(s):// 与 base64:// 形式；无卡片交互面，交互段降级纯文本。
   segments: {
     outboundMedia: ['url', 'base64'],
@@ -41,8 +41,6 @@ export default defineAdapter<MilkyAdapterConfig>({
   },
   create(context) {
     const config = resolveMilkyConfig(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（milky.endpoint list 的"运行中"数据源）
     context.use(milkyRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -51,8 +49,6 @@ export default defineAdapter<MilkyAdapterConfig>({
     if (config.connection === 'webhook') {
       return new MilkyWebhookEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -60,8 +56,6 @@ export default defineAdapter<MilkyAdapterConfig>({
     if (config.connection === 'wss') {
       return new MilkyWssEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -69,15 +63,11 @@ export default defineAdapter<MilkyAdapterConfig>({
     if (config.connection === 'sse') {
       return new MilkySseEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         config,
       });
     }
     return new MilkyWsEndpoint({
       id: context.id,
-      gateway,
-      sideEvents,
       config,
     });
   },

package/lib/client.d.ts

@@ -0,0 +1,21 @@
+import { MilkyV1Client, type MilkyV1Event } from '@imhelper/milky-v1';
+import { type EventMap, type ImHelperEventMap } from 'imhelper';
+import { type ClientEventPayloads } 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;
+        };
+    }
+}
+export declare const milkyClient: import("@zhin.js/adapter").EndpointClientToken<MilkyV1Client, ClientEventPayloads<MilkyClientEvents>>;

package/lib/client.js

@@ -0,0 +1,33 @@
+import { MilkyV1Client, } from '@imhelper/milky-v1';
+import { EventFactory, } from 'imhelper';
+import { defineEndpointClient, 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),
+    });
+}
+/** 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}` : ''}`);
+    }
+    return response.data;
+}
+const milkyClientEventNames = Object.freeze([
+    ...EventFactory.getSupportedEventTypes(),
+    'event',
+]);
+export function forwardMilkyClientEvents(client, receive) {
+    return forwardEndpointClientEvents(client, milkyClientEventNames, receive);
+}
+export const milkyClient = defineEndpointClient('milky');

package/lib/endpoint.d.ts

@@ -3,5 +3,5 @@ export { MilkyWebhookEndpoint, type MilkyWebhookEndpointOptions, } from './webho
 export { MilkyWssEndpoint, type MilkyWssEndpointOptions, } from './wss-endpoint.js';
 export { MilkySseEndpoint, type MilkySseEndpointOptions, type CreateMilkySseStream, } from './sse-endpoint.js';
 export type { MilkyWsSocket, MilkyWsCreateOptions } from './ws-types.js';
-export { verifyMilkyAccessToken, readRequestBody } from './milky-auth.js';
+export { verifyMilkyAccessToken } from './milky-auth.js';
 export { openSseStream, consumeSseBuffer } from './sse-client.js';

package/lib/endpoint.js

@@ -2,5 +2,5 @@ export { MilkyWsEndpoint, } from './ws-endpoint.js';
 export { MilkyWebhookEndpoint, } from './webhook-endpoint.js';
 export { MilkyWssEndpoint, } from './wss-endpoint.js';
 export { MilkySseEndpoint, } from './sse-endpoint.js';
-export { verifyMilkyAccessToken, readRequestBody } from './milky-auth.js';
+export { verifyMilkyAccessToken } from './milky-auth.js';
 export { openSseStream, consumeSseBuffer } from './sse-client.js';

package/lib/index.d.ts

@@ -1,3 +1,6 @@
 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 { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, consumeSseBuffer, openSseStream, readRequestBody, verifyMilkyAccessToken, type CreateMilkySseStream, type MilkySseEndpointOptions, type MilkyWebhookEndpointOptions, type MilkyWssEndpointOptions, type MilkyWsCreateOptions, type MilkyWsEndpointOptions, type MilkyWsSocket, } from './endpoint.js';
-export { getMilkyAgentDeps, registerMilkyAgentEndpoint, setMilkyAgentDeps, type MilkyAgentDeps, type MilkyAgentEndpoint, } from './milky-agent-deps.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';
+export { ProtocolError } from '@imhelper/milky-v1';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/lib/index.js

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

package/lib/milky-auth.d.ts

@@ -1,3 +1,2 @@
 import type { IncomingMessage } from 'node:http';
 export declare function verifyMilkyAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean;
-export declare function readRequestBody(request: IncomingMessage): Promise<string>;

package/lib/milky-auth.js

@@ -14,17 +14,3 @@ export function verifyMilkyAccessToken(accessToken, request) {
     }
     return false;
 }
-export async function readRequestBody(request) {
-    const chunks = [];
-    let size = 0;
-    for await (const chunk of request) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buffer.length;
-        if (size > 1_048_576) {
-            request.destroy();
-            throw new Error('Request body exceeds 1MB');
-        }
-        chunks.push(buffer);
-    }
-    return Buffer.concat(chunks).toString('utf8');
-}

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

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

package/lib/protocol.d.ts

@@ -59,7 +59,7 @@ export interface MilkyWssConfig extends MilkyConfigBase {
 export type ResolvedMilkyConfig = MilkyWsConfig | MilkySseConfig | MilkyWebhookConfig | MilkyWssConfig;
 export type MilkyEndpointConfig = ResolvedMilkyConfig;
 export interface MilkyApiResponse<T = unknown> {
-    status: string;
+    status: 'ok' | 'failed';
     retcode: number;
     data?: T;
     message?: string;
@@ -111,9 +111,9 @@ export interface MilkyApiClientOptions {
 export declare function resolveMilkyConfig(config?: MilkyAdapterConfig): ResolvedMilkyConfig;
 /**
  * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
- * 非 200 或 retcode !== 0 时抛错。
+ * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。
  */
-export declare function callApi<T = unknown>(options: MilkyApiClientOptions, apiName: string, params?: Record<string, unknown>): Promise<T>;
+export declare function callApi<T = unknown>(options: MilkyApiClientOptions, apiName: string, params?: Record<string, unknown>): 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

@@ -80,7 +80,7 @@ function authQuery(access_token) {
 }
 /**
  * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
- * 非 200 或 retcode !== 0 时抛错。
+ * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。
  */
 export async function callApi(options, apiName, params = {}) {
     const { baseUrl, access_token } = options;
@@ -107,10 +107,7 @@ export async function callApi(options, apiName, params = {}) {
     if (res.status !== 200) {
         throw new Error(`Milky API ${apiName}: HTTP ${res.status} ${body.message ?? text}`);
     }
-    if (body.retcode !== 0) {
-        throw new Error(`Milky API ${apiName}: retcode=${body.retcode} ${body.message ?? ''}`);
-    }
-    return (body.data ?? {});
+    return body;
 }
 /** 根据 event_type 判断是否为 message_receive，并解析 data */
 export function parseMessageReceiveData(event) {

package/lib/sse-endpoint.d.ts

@@ -1,10 +1,10 @@
 /**
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
-import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
-import { callApi, type MilkyEvent, type MilkySseConfig } from './protocol.js';
+import { type MilkyClient } from './client.js';
+import { callApi, type MilkySseConfig } from './protocol.js';
 import { type SseClientHandle } from './sse-client.js';
 export type CreateMilkySseStream = (options: {
     readonly url: string;
@@ -15,35 +15,18 @@ export type CreateMilkySseStream = (options: {
 }) => SseClientHandle;
 export interface MilkySseEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: MilkySseConfig;
     readonly createSseStream?: CreateMilkySseStream;
     readonly callApi?: typeof callApi;
 }
-export declare class MilkySseEndpoint implements EndpointInstance {
+export declare class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
     #private;
+    readonly client: MilkyClient;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: MilkySseEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     recallMessage(id: string): Promise<void>;
-    kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;
-    muteMember(groupId: number, userId: number, duration?: number): Promise<boolean>;
-    muteAll(groupId: number, enable?: boolean): Promise<boolean>;
-    setAdmin(groupId: number, userId: number, enable?: boolean): Promise<boolean>;
-    setCard(groupId: number, userId: number, card: string): Promise<boolean>;
-    setTitle(groupId: number, userId: number, title: string): Promise<boolean>;
-    setGroupName(groupId: number, name: string): Promise<boolean>;
-    getMemberList(groupId: number): Promise<unknown[]>;
-    getGroupInfo(groupId: number): Promise<unknown>;
-    admit(event: MilkyEvent): void;
-    apiOptions(): {
-        baseUrl: string;
-        access_token?: string;
-    };
 }

package/lib/sse-endpoint.js

@@ -1,25 +1,34 @@
 /**
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
-import { createEndpointLifecycle, } from 'zhin.js/adapter';
+import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents } from './client.js';
 import { buildSendAction, buildSseConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 import { openSseStream } from './sse-client.js';
-export class MilkySseEndpoint {
+export class MilkySseEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
     #callApi;
-    management = createMilkyEndpointManagement(this);
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     #lifecycle;
     #stream;
-    #open = false;
-    #unregisterAgent;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('milky', options.config.id);
         this.#options = options;
         this.#callApi = options.callApi ?? callApi;
+        this.client = createMilkyEndpointClient(options.config, this.#callApi);
+        this.management = createMilkyEndpointManagement({
+            callApi: (action, params) => callMilkyClient(this.client, action, params),
+        });
+        this.bindClientEvents((receive) => forwardMilkyClientEvents(this.client, receive), (name, payload) => {
+            if (name === 'event')
+                this.#admitRaw(payload);
+        }, (_name, error) => this.#warnPlatformEvent(error));
         this.#lifecycle = createEndpointLifecycle({
             name: options.config.id,
             // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
@@ -34,35 +43,24 @@ export class MilkySseEndpoint {
     async start() {
         if (this.#lifecycle.started)
             return;
-        this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.id, this);
         try {
             await this.#lifecycle.start((handle) => this.#connect(handle));
         }
         catch (err) {
             // 与 WS 对齐：start 失败复位由基座保证；agent 反注册留在适配器侧，允许重试
-            this.#unregisterAgent?.();
-            this.#unregisterAgent = undefined;
             throw err;
         }
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
+        this.close();
         await this.#lifecycle.stop();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         this.#stream?.close();
         this.#stream = undefined;
     }
     async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await this.callApi(action, params);
+        const data = await callMilkyClient(this.client, action, params);
         const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         this.#logger.debug(formatCompact({
             op: 'milky_send',
@@ -73,91 +71,31 @@ export class MilkySseEndpoint {
         }));
         return messageId;
     }
-    callApi(action, params = {}) {
-        return this.#callApi(this.apiOptions(), action, params);
-    }
     async recallMessage(id) {
         const parsed = parseMilkyMessageId(id);
         if (!parsed)
             throw new Error(`Invalid message id: ${id}`);
         if (parsed.message_scene === 'group') {
-            await this.callApi('recall_group_message', {
+            await callMilkyClient(this.client, 'recall_group_message', {
                 group_id: parsed.peer_id,
                 message_seq: parsed.message_seq,
             });
         }
         else {
-            await this.callApi('recall_private_message', {
+            await callMilkyClient(this.client, 'recall_private_message', {
                 user_id: parsed.peer_id,
                 message_seq: parsed.message_seq,
             });
         }
     }
-    async kickMember(groupId, userId, rejectAddRequest = false) {
-        await this.callApi('kick_group_member', {
-            group_id: groupId,
-            user_id: userId,
-            reject_add_request: rejectAddRequest,
-        });
-        return true;
-    }
-    async muteMember(groupId, userId, duration = 600) {
-        await this.callApi('set_group_member_mute', {
-            group_id: groupId,
-            user_id: userId,
-            duration,
-        });
-        return true;
-    }
-    async muteAll(groupId, enable = true) {
-        await this.callApi('set_group_whole_mute', { group_id: groupId, is_mute: enable });
-        return true;
-    }
-    async setAdmin(groupId, userId, enable = true) {
-        await this.callApi('set_group_member_admin', {
-            group_id: groupId,
-            user_id: userId,
-            is_set: enable,
-        });
-        return true;
-    }
-    async setCard(groupId, userId, card) {
-        await this.callApi('set_group_member_card', {
-            group_id: groupId,
-            user_id: userId,
-            card,
-        });
-        return true;
-    }
-    async setTitle(groupId, userId, title) {
-        await this.callApi('set_group_member_special_title', {
-            group_id: groupId,
-            user_id: userId,
-            special_title: title,
-        });
-        return true;
-    }
-    async setGroupName(groupId, name) {
-        await this.callApi('set_group_name', { group_id: groupId, new_group_name: name });
-        return true;
-    }
-    async getMemberList(groupId) {
-        return this.callApi('get_group_member_list', { group_id: groupId });
-    }
-    async getGroupInfo(groupId) {
-        return this.callApi('get_group_info', { group_id: groupId });
-    }
-    admit(event) {
+    #admitRaw(event) {
         const data = parseMessageReceiveData(event);
-        if (!this.#open || !data)
+        if (!data)
             return;
         this.#admitMessage(data, event);
     }
-    apiOptions() {
-        return {
-            baseUrl: this.#options.config.baseUrl,
-            access_token: this.#options.config.access_token,
-        };
+    #warnPlatformEvent(error) {
+        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);
@@ -167,7 +105,7 @@ export class MilkySseEndpoint {
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: formatInboundMessageId(data) },
             content,
@@ -255,7 +193,7 @@ export class MilkySseEndpoint {
     #onMessage(data) {
         try {
             const event = JSON.parse(data);
-            this.admit(event);
+            this.client.ingest(event);
         }
         catch (error) {
             this.#logger.warn(formatCompact({