@zhin.js/adapter-milky 1.0.1 → 1.1.0

package/README.md

@@ -1,158 +1,99 @@
 # @zhin.js/adapter-milky
 
-Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器，**一个适配器**支持 WebSocket 正向/反向、SSE、Webhook 四种连接方式，由配置项 `connection` 区分；支持 HTTP API 调用与 `access_token` 鉴权。
+Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器（Plugin Runtime）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **Webhook**、**反向 WS**（经 `httpHostToken`）与 **SSE**（HTTP GET `/event`，fetch 解析 `text/event-stream`）。
 
 ## 功能特性
 
-- 🔌 Milky 协议兼容（[通信说明](https://milky.ntqqrev.org/guide/communication)）
-- 📦 **单一适配器**：`context: milky`，通过 `connection` 选择连接方式
-- 🌐 **WebSocket 正向**（`connection: ws`）：应用连协议端 `ws(s)://baseUrl/event`
-- 📡 **SSE**（`connection: sse`）：应用 GET 协议端 `/event`
-- 📮 **Webhook**（`connection: webhook`）：应用提供 POST 端点收事件
-- 🔄 **WebSocket 反向**（`connection: wss`）：应用开 WS 服务端，协议端来连
-- 🔐 `access_token` 鉴权（Header 或 query）
-- 📨 群聊 / 私聊消息收发与消息段映射
-- 🛠️ HTTP API 封装，供发消息、撤回、群管等复用
+- [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`
 
 ## 安装
 
 ```bash
-pnpm add @zhin.js/adapter-milky ws eventsource
+pnpm add @zhin.js/adapter-milky
 ```
 
-适配器依赖 `@zhin.js/host-router` 提供的 `router` 才能注册（Webhook/反向 WS 需挂路由），请同时启用 HTTP 服务：
+## Plugin Runtime
 
-```bash
-pnpm add @zhin.js/host-router
-```
+- `@zhin.js/adapter` — 约定式 `adapters/milky.ts`（`defineAdapter`）
+- `@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 仍独占账号连接、鉴权、重连和心跳。
 
-## 配置
+## 前置条件
 
-所有 Endpoint 使用 **同一 context：`milky`**，通过 **`connection`** 区分连接方式。
+1. 启动兼容 Milky 的实现，并记录 HTTP API 与事件连接地址。
+2. 正向 WS/SSE 需 Zhin 主动可达实现端；Webhook/反向 WS 需实现端可达 Zhin HTTP Host。
+3. 两端配置相同的 `access_token`，生产环境不要暴露无鉴权接口。
 
-### WebSocket 正向
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-milky"
-
-endpoints:
-  - context: milky
+  milky:
     connection: ws
-    name: milky-bot
-    baseUrl: "http://127.0.0.1:8080"
-    access_token: "${MILKY_ACCESS_TOKEN}"
     reconnect_interval: 5000
     heartbeat_interval: 30000
+    endpoints:
+      - name: milky-bot
+        baseUrl: "http://127.0.0.1:8080"
+        access_token: "${MILKY_ACCESS_TOKEN}"
 ```
 
-### SSE
-
-```yaml
-endpoints:
-  - context: milky
-    connection: sse
-    name: milky-sse-bot
-    baseUrl: "http://127.0.0.1:8080"
-    access_token: "${MILKY_ACCESS_TOKEN}"
-```
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-milky`（`instanceKey: milky`）。
 
-### Webhook
+## 连接方式
 
-```yaml
-endpoints:
-  - context: milky
-    connection: webhook
-    name: milky-webhook-bot
-    baseUrl: "http://协议端地址"
-    path: "/milky/webhook"               # 应用接收事件的 POST 路径
-    access_token: "${MILKY_ACCESS_TOKEN}"
-```
-
-### WebSocket 反向
-
-```yaml
-endpoints:
-  - context: milky
-    connection: wss
-    name: milky-wss-bot
-    baseUrl: "http://协议端地址"
-    path: "/milky/event"                 # 应用 WS 服务端路径
-    access_token: "${MILKY_ACCESS_TOKEN}"
-    heartbeat_interval: 30000
-```
+| connection | 状态 |
+|------------|------|
+| `ws` | 已实现（推荐） |
+| `sse` | HTTP GET `/event`（`Accept: text/event-stream`） |
+| `webhook` | 已实现：POST 入站 + baseUrl HTTP API 出站 |
+| `wss` | 已实现：反向 WS（httpHostToken） |
 
 ## 鉴权
 
-所有连接方式统一支持：
+- **Bearer**：`Authorization: Bearer <access_token>`
+- 正向 WS 在 Upgrade 时附带请求头，并在 URL query 写入 `access_token`
+- HTTP API 同样使用 Header / query 鉴权
 
-- **Header**：`Authorization: Bearer {access_token}`
-- **Query**：`access_token=xxx`
+## 消息 ID
 
-建议配置 `access_token`，并与协议端一致。
+`{message_scene}:{peer_id}:{message_seq}`（如 `group:123456:10001`）。
 
-## 连接方式对比
+## AI 工具
 
-| connection | 说明                           |
-|------------|--------------------------------|
-| `ws`       | 应用主动连协议端 `/event`      |
-| `sse`      | 应用 GET `/event` 拉取事件流   |
-| `webhook`  | 协议端 POST 到应用配置的 path  |
-| `wss`      | 协议端连应用提供的 WS path     |
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 技能说明 | `agent/skills/milky.md` |
 
-## 使用示例
-
-### 消息处理
-
-```typescript
-import { addCommand, MessageCommand } from 'zhin.js'
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
-```
-
-### 发送消息段
-
-```typescript
-addCommand(new MessageCommand('pic')
-  .action(async () => {
-    return [
-      { type: 'text', data: { text: '图片：' } },
-      { type: 'image', data: { url: 'https://example.com/img.png' } }
-    ]
-  })
-)
-```
-
-发消息、撤回、群管等通过适配器封装的 HTTP API 完成。群管能力通过 `IGroupManagement` 自动注册为工具，详见 [工具与技能](/advanced/tools-skills)。
-
-## 消息 ID 格式
-
-`{message_scene}:{peer_id}:{message_seq}`（如 `group:123456:10001`）。撤回时使用该 ID。
-
-## 协议与 API 参考
+## 文档链接
 
 - [Milky 快速开始](https://milky.ntqqrev.org/)
 - [Milky 通信](https://milky.ntqqrev.org/guide/communication)
-- [事件结构](https://milky.ntqqrev.org/struct/Event)、[接收消息](https://milky.ntqqrev.org/struct/IncomingMessage)、[消息 API](https://milky.ntqqrev.org/api/message)、[群聊 API](https://milky.ntqqrev.org/api/group)
-
-## 依赖项
+- [适配器概览](https://zhin.js.org/essentials/adapters)
 
-- `ws` - WebSocket 客户端/服务端
-- `eventsource` - SSE 客户端
-- `zhin.js` - Zhin 核心
-- `@zhin.js/host-router` - 提供 router，适配器注册依赖
+## 故障排查
 
-## 开发
-
-```bash
-pnpm build   # 构建
-pnpm clean   # 清理
-```
+| 现象 | 排查 |
+| --- | --- |
+| WS/SSE 无事件 | 核对 `baseUrl`、连接模式与实现端事件服务 |
+| 401 或握手失败 | 确认 Bearer/query 中的 `access_token` 与实现端一致 |
+| Webhook/WSS 无法连接 | 检查 HTTP Host、网络可达性与回调路径 |
+| 能收不能发 | 检查 HTTP API 与发送动作支持情况 |
 
 ## 许可证
 

package/adapters/milky.js

@@ -0,0 +1,51 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/milky.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";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // Milky 协议资源 uri 消费 http(s):// 与 base64:// 形式；无卡片交互面，交互段降级纯文本。
+    segments: {
+        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,
+        });
+    },
+});

package/adapters/milky.ts

@@ -0,0 +1,74 @@
+/**
+ * Convention entry: discover `adapters/milky.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  MilkySseEndpoint,
+  MilkyWebhookEndpoint,
+  MilkyWssEndpoint,
+  MilkyWsEndpoint,
+} from '../src/endpoint.js';
+import {
+  resolveMilkyConfig,
+  type MilkyAdapterConfig,
+} from '../src/protocol.js';
+import { milkyRuntimeStateToken } from '../src/milky-runtime-state.js';
+
+export {
+  MilkySseEndpoint,
+  MilkyWebhookEndpoint,
+  MilkyWssEndpoint,
+  MilkyWsEndpoint,
+} from '../src/endpoint.js';
+export type {
+  CreateMilkySseStream,
+  MilkySseEndpointOptions,
+  MilkyWebhookEndpointOptions,
+  MilkyWssEndpointOptions,
+  MilkyWsEndpointOptions,
+  MilkyWsCreateOptions,
+  MilkyWsSocket,
+} from '../src/endpoint.js';
+
+export default defineAdapter<MilkyAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // Milky 协议资源 uri 消费 http(s):// 与 base64:// 形式；无卡片交互面，交互段降级纯文本。
+  segments: {
+    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,
+    });
+  },
+});

package/{skills/milky → agent}/PERMITS.md

@@ -8,7 +8,7 @@
 
 | `platform(milky,…)` | 含义 |
 |---------------------|------|
-| `group_owner` | 群主 |
-| `group_admin` | 群管理员（含群主） |
+| `scene_owner` | 群主 |
+| `scene_admin` | 群管理员（含群主） |
 
 与 OneBot QQ 系相同，使用 core 默认 checker。

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

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

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

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

package/commands/endpoint/list.js

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

package/commands/endpoint/list.ts

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

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

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

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

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

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-management.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Milky endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * Milky 协议响应 data 为包裹对象：get_friend_list → {friends:[...]}、
+ * get_group_list → {groups:[...]}、get_group_member_list → {members:[...]}。
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 Milky 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from 'zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/sse/webhook 四种传输各自实现）。 */
+export interface MilkyManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createMilkyEndpointManagement(endpoint: MilkyManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createMilkyEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listFriends() {
+            const data = asRecord(await endpoint.callApi('get_friend_list'));
+            return toArray(data.friends).map((value) => {
+                const friend = asRecord(value);
+                return {
+                    user_id: toNumberId(friend.user_id, 'user_id'),
+                    nickname: String(friend.nickname ?? ''),
+                    remark: String(friend.remark ?? ''),
+                };
+            });
+        },
+        async listGroups() {
+            const data = asRecord(await endpoint.callApi('get_group_list'));
+            return toArray(data.groups).map((value) => {
+                const group = asRecord(value);
+                return {
+                    group_id: toNumberId(group.group_id, 'group_id'),
+                    name: String(group.group_name ?? group.name ?? ''),
+                };
+            });
+        },
+        async listGroupMembers(groupId) {
+            const data = asRecord(await endpoint.callApi('get_group_member_list', {
+                group_id: toNumberId(groupId, 'group_id'),
+            }));
+            return toArray(data.members);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`milky ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/endpoint.d.ts

@@ -0,0 +1,7 @@
+export { MilkyWsEndpoint, type MilkyWsEndpointOptions, } from './ws-endpoint.js';
+export { MilkyWebhookEndpoint, type MilkyWebhookEndpointOptions, } from './webhook-endpoint.js';
+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 } from './milky-auth.js';
+export { openSseStream, consumeSseBuffer } from './sse-client.js';

package/lib/endpoint.js

@@ -0,0 +1,6 @@
+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 } from './milky-auth.js';
+export { openSseStream, consumeSseBuffer } from './sse-client.js';

package/lib/index.d.ts

@@ -1,20 +1,6 @@
-import { MilkyAdapter } from './adapter.js';
-export * from './types.js';
-export { callApi } from './api.js';
-export * from './utils.js';
-export { MilkyWsClient } from './endpoint-ws.js';
-export { MilkySseClient } from './endpoint-sse.js';
-export { MilkyWebhookEndpoint } from './endpoint-webhook.js';
-export { MilkyWssServer } from './endpoint-wss.js';
-export { MilkyAdapter, type MilkyBot } from './adapter.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Adapters {
-        milky: MilkyAdapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+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, 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,35 +1,4 @@
-/**
- * Milky 适配器入口：单一适配器，支持 WS/SSE/Webhook/反向 WS，依赖 router 注册
- */
-import { usePlugin, createGroupManagementTools, registerDefaultGroupPlatformPermitChecker } from 'zhin.js';
-import { MilkyAdapter } from './adapter.js';
-export * from './types.js';
-export { callApi } from './api.js';
-export * from './utils.js';
-export { MilkyWsClient } from './endpoint-ws.js';
-export { MilkySseClient } from './endpoint-sse.js';
-export { MilkyWebhookEndpoint } from './endpoint-webhook.js';
-export { MilkyWssServer } from './endpoint-wss.js';
-export { MilkyAdapter } from './adapter.js';
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-provide({
-    name: 'milky',
-    description: 'Milky Adapter（WS 正向 / SSE / Webhook / 反向 WS）',
-    mounted: async (p) => {
-        const adapter = new MilkyAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-useContext('tool', 'milky', (toolService, milky) => {
-    const disposers = [];
-    disposers.push(registerDefaultGroupPlatformPermitChecker('milky'));
-    const groupTools = createGroupManagementTools(milky, 'milky');
-    disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
-    return () => disposers.forEach(d => d());
-});
-//# sourceMappingURL=index.js.map
+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 { ProtocolError } from '@imhelper/milky-v1';

package/lib/milky-auth.d.ts

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

package/lib/milky-auth.js

@@ -0,0 +1,16 @@
+export function verifyMilkyAccessToken(accessToken, request) {
+    if (!accessToken)
+        return true;
+    const auth = request.headers.authorization ?? '';
+    if (auth === `Bearer ${accessToken}`)
+        return true;
+    try {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        if (url.searchParams.get('access_token') === accessToken)
+            return true;
+    }
+    catch {
+        /* ignore */
+    }
+    return false;
+}

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

@@ -0,0 +1 @@
+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/milky-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `milky.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { milkyRuntimeStateToken } from './milky-runtime-state.js';
+export const milkyEndpointCommands = createEndpointCommands({
+    adapterKey: 'milky',
+    adapterDisplayName: 'Milky',
+    fields: [
+        { key: 'baseUrl', required: true, description: 'Milky HTTP API base URL' },
+        { key: 'path', description: 'webhook / reverse-wss 路径' },
+        { key: 'access_token', env: true, description: 'Milky access token' },
+    ],
+    running: (use) => use(milkyRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
+}, defineCommand);

package/lib/milky-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const milkyRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/milky-runtime-state.js

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