@zhin.js/adapter-milky 1.0.1 → 1.1.2

package/schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": [
+        "ws",
+        "sse",
+        "webhook",
+        "wss"
+      ],
+      "default": "ws",
+      "description": "ws (default), sse (EventSource client), webhook or wss (webhook/wss via httpHostToken)"
+    },
+    "reconnect_interval": {
+      "type": "number",
+      "default": 5000
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 30000
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（QQ uin；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted QQ uin"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（QQ uin）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted QQ uin"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "connection": {
+            "type": "string",
+            "enum": [
+              "ws",
+              "sse",
+              "webhook",
+              "wss"
+            ]
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Milky HTTP API base URL (required); WS event path is derived as ws(s)://host/event"
+          },
+          "path": {
+            "type": "string",
+            "description": "Path for webhook / reverse-wss"
+          },
+          "access_token": {
+            "type": "string",
+            "description": "Milky access token"
+          },
+          "reconnect_interval": {
+            "type": "number"
+          },
+          "heartbeat_interval": {
+            "type": "number"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string",
+            "description": "Milky bot name"
+          }
+        },
+        "required": [
+          "id",
+          "baseUrl"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,80 @@
+import {
+  MilkyV1Client,
+  type MilkyV1Event,
+  type MilkyV1Response,
+} from '@imhelper/milky-v1';
+import {
+  EventFactory,
+  type EventMap,
+  type ImHelperEventMap,
+} from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  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 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,
+    ),
+  });
+}
+
+/** 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}` : ''}`,
+    );
+  }
+  return response.data;
+}
+
+const milkyClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<string>(),
+  'event',
+]);
+
+export function forwardMilkyClientEvents(
+  client: MilkyV1Client,
+  receive: (name: string, payload: unknown) => void,
+): () => 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/endpoint-management.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointManagement,
+} from 'zhin.js/adapter';
+
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/sse/webhook 四种传输各自实现）。 */
+export interface MilkyManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): 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'));
+      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(): Promise<readonly EndpointGroup[]> {
+      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: string): Promise<readonly unknown[]> {
+      const data = asRecord(await endpoint.callApi('get_group_member_list', {
+        group_id: toNumberId(groupId, 'group_id'),
+      }));
+      return toArray(data.members);
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function toArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+    throw new TypeError(`milky ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}

package/src/endpoint.ts

@@ -0,0 +1,26 @@
+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/src/index.ts

@@ -1,50 +1,65 @@
-/**
- * Milky 适配器入口：单一适配器，支持 WS/SSE/Webhook/反向 WS，依赖 router 注册
- */
-import { usePlugin, type Plugin, type Context, createGroupManagementTools, registerDefaultGroupPlatformPermitChecker, type ToolFeature } from 'zhin.js';
-import type { Router } from '@zhin.js/host-router';
-import { MilkyAdapter } from './adapter.js';
-import type { IGroupManagement } from 'zhin.js';
+export {
+  buildSendAction,
+  buildSseConnectOptions,
+  buildWsConnectOptions,
+  callApi,
+  extractInboundAudioUrl,
+  formatInboundContent,
+  formatOutboundSegments,
+  isMentioned,
+  isMessageReceiveEvent,
+  milkyInboundConversation,
+  parseMessageReceiveData,
+  resolveMilkyConfig,
+  senderNickname,
+  type MilkyApiClientOptions,
+  type MilkyApiResponse,
+  type MilkyConfigBase,
+  type MilkyEndpointConfig,
+  type MilkyEvent,
+  type MilkyIncomingMessage,
+  type MilkyIncomingSegment,
+  type MilkyOutgoingSegment,
+  type MilkySseConfig,
+  type MilkyWebhookConfig,
+  type MilkyWireSegment,
+  type MilkyWsConfig,
+  type MilkyWssConfig,
+  type ResolvedMilkyConfig,
+} from './protocol.js';
 
-export * 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';
+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';
 
-declare module 'zhin.js' {
-  namespace Plugin {
-    interface Contexts {
-      router: import('@zhin.js/host-router').Router;
-    }
-  }
-  interface Adapters {
-    milky: MilkyAdapter;
-  }
-}
+export {
+  MilkyClient,
+  milkyClient,
+  type MilkyClientEventMap,
+} from './client.js';
 
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-provide({
-  name: 'milky',
-  description: 'Milky Adapter（WS 正向 / SSE / Webhook / 反向 WS）',
-  mounted: async (p: Plugin) => {
-    const adapter = new MilkyAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: MilkyAdapter) => {
-    await adapter.stop();
-  },
-} as unknown as Context<'milky'>);
-
-useContext('tool', 'milky', (toolService: ToolFeature, milky: MilkyAdapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerDefaultGroupPlatformPermitChecker('milky'));
-  const groupTools = createGroupManagementTools(milky as unknown as IGroupManagement, 'milky');
-  disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
-  return () => disposers.forEach(d => d());
-});
+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/src/milky-auth.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage } from 'node:http';
+
+export function verifyMilkyAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean {
+  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/src/milky-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * 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');