@zhin.js/adapter-milky 0.0.0

package/src/adapter.ts

@@ -0,0 +1,115 @@
+/**
+ * Milky 适配器：单一适配器支持 WS 正向 / SSE / Webhook / 反向 WS，由 config.connection 区分
+ */
+import type { Router } from '@zhin.js/http';
+import {
+  Adapter,
+  Plugin,
+  createGroupManagementTools,
+  GROUP_MANAGEMENT_SKILL_KEYWORDS,
+  GROUP_MANAGEMENT_SKILL_TAGS,
+  type IGroupManagement,
+} from 'zhin.js';
+import { MilkyWsClient } from './bot-ws.js';
+import { MilkySseClient } from './bot-sse.js';
+import { MilkyWebhookBot } from './bot-webhook.js';
+import { MilkyWssServer } from './bot-wss.js';
+import type {
+  MilkyBotConfig,
+  MilkyWsConfig,
+  MilkySseConfig,
+  MilkyWebhookConfig,
+  MilkyWssConfig,
+} from './types.js';
+
+export type MilkyBot = MilkyWsClient | MilkySseClient | MilkyWebhookBot | MilkyWssServer;
+
+export class MilkyAdapter extends Adapter<MilkyBot> {
+  #router?: Router;
+
+  constructor(plugin: Plugin) {
+    super(plugin, 'milky', []);
+  }
+
+  createBot(config: MilkyBotConfig): MilkyBot {
+    switch (config.connection) {
+      case 'ws':
+        return new MilkyWsClient(this, config as MilkyWsConfig);
+      case 'sse':
+        return new MilkySseClient(this, config as MilkySseConfig);
+      case 'webhook':
+        if (!this.#router) throw new Error('Milky connection: webhook 需要 router，请安装并在配置中启用 @zhin.js/http');
+        return new MilkyWebhookBot(this, this.#router, config as MilkyWebhookConfig);
+      case 'wss':
+        if (!this.#router) throw new Error('Milky connection: wss 需要 router，请安装并在配置中启用 @zhin.js/http');
+        return new MilkyWssServer(this, this.#router, config as MilkyWssConfig);
+      default:
+        throw new Error(`Unknown Milky connection: ${(config as MilkyBotConfig).connection}`);
+    }
+  }
+
+  async kickMember(botId: string, sceneId: string, userId: string) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.kickMember(Number(sceneId), Number(userId), false);
+  }
+
+  async muteMember(botId: string, sceneId: string, userId: string, duration = 600) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.muteMember(Number(sceneId), Number(userId), duration);
+  }
+
+  async muteAll(botId: string, sceneId: string, enable = true) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.muteAll(Number(sceneId), enable);
+  }
+
+  async setAdmin(botId: string, sceneId: string, userId: string, enable = true) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.setAdmin(Number(sceneId), Number(userId), enable);
+  }
+
+  async setMemberNickname(botId: string, sceneId: string, userId: string, nickname: string) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.setCard(Number(sceneId), Number(userId), nickname);
+  }
+
+  async setGroupName(botId: string, sceneId: string, name: string) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.setGroupName(Number(sceneId), name);
+  }
+
+  async listMembers(botId: string, sceneId: string) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    const members = await bot.getMemberList(Number(sceneId));
+    return { members: Array.isArray(members) ? members : [], count: Array.isArray(members) ? members.length : 0 };
+  }
+
+  async getGroupInfo(botId: string, sceneId: string) {
+    const bot = this.bots.get(botId);
+    if (!bot) throw new Error(`Bot ${botId} 不存在`);
+    return bot.getGroupInfo(Number(sceneId));
+  }
+
+  async start(): Promise<void> {
+    // 同步获取已就绪的 router，或通过 useContext 在 router 挂载后赋值
+    this.#router = (this.plugin.inject as (key: string) => Router | undefined)('router');
+    (this.plugin.useContext as (key: string, fn: (router: Router) => void) => void)('router', (router: Router) => {
+      this.#router = router;
+    });
+    const groupTools = createGroupManagementTools(this as unknown as IGroupManagement, this.name);
+    groupTools.forEach((t) => this.addTool(t));
+    this.declareSkill({
+      description: 'Milky 协议群管理：踢人、禁言、全员禁言、设管理员、改群名、查成员等。',
+      keywords: GROUP_MANAGEMENT_SKILL_KEYWORDS,
+      tags: GROUP_MANAGEMENT_SKILL_TAGS,
+    });
+    await super.start();
+  }
+}

package/src/api.ts

@@ -0,0 +1,63 @@
+/**
+ * Milky HTTP API 封装：鉴权 + POST /api/:api
+ */
+import type { MilkyApiResponse } from './types.js';
+
+export interface MilkyApiClientOptions {
+  baseUrl: string;
+  access_token?: string;
+}
+
+/** 鉴权：Header Authorization: Bearer {token} 或 URL query access_token=xxx */
+function authHeaders(access_token?: string): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (access_token) {
+    headers['Authorization'] = `Bearer ${access_token}`;
+  }
+  return headers;
+}
+
+function authQuery(access_token?: string): string {
+  if (!access_token) return '';
+  return `access_token=${encodeURIComponent(access_token)}`;
+}
+
+/**
+ * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
+ * 非 200 或 retcode !== 0 时抛错。
+ */
+export async function callApi<T = unknown>(
+  options: MilkyApiClientOptions,
+  apiName: string,
+  params: Record<string, unknown> = {},
+): Promise<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 : {}),
+  });
+
+  const text = await res.text();
+  let body: MilkyApiResponse<T>;
+  try {
+    body = JSON.parse(text) as MilkyApiResponse<T>;
+  } catch {
+    throw new Error(`Milky API ${apiName}: invalid JSON response (${res.status}) ${text.slice(0, 200)}`);
+  }
+
+  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 ?? {}) as T;
+}

package/src/bot-sse.ts

@@ -0,0 +1,226 @@
+/**
+ * Milky SSE Bot：应用 GET 协议端 /event，Accept: text/event-stream，解析 SSE 的 milky_event
+ */
+import EventSource from 'eventsource';
+import { EventEmitter } from 'events';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import { callApi } from './api.js';
+import type { MilkySseConfig, MilkyEvent } from './types.js';
+import type { MilkyAdapter } from './adapter.js';
+import {
+  formatMilkyMessagePayload,
+  parseMessageReceiveData,
+  toMilkyOutgoingSegments,
+  parseMilkyMessageId,
+} from './utils.js';
+
+export class MilkySseClient extends EventEmitter implements Bot<MilkySseConfig, MilkyEvent> {
+  $connected: boolean;
+  private es?: EventSource;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(public adapter: MilkyAdapter, public $config: MilkySseConfig) {
+    super();
+    this.$connected = false;
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private get eventUrl(): string {
+    const base = this.$config.baseUrl.replace(/\/$/, '');
+    const url = `${base}/event`;
+    const token = this.$config.access_token;
+    if (token) return `${url}${url.includes('?') ? '&' : '?'}access_token=${encodeURIComponent(token)}`;
+    return url;
+  }
+
+  private apiOptions() {
+    return { baseUrl: this.$config.baseUrl, access_token: this.$config.access_token };
+  }
+
+  async $connect(): Promise<void> {
+    const headers: Record<string, string> = { Accept: 'text/event-stream' };
+    if (this.$config.access_token) {
+      headers['Authorization'] = `Bearer ${this.$config.access_token}`;
+    }
+    this.es = new EventSource(this.eventUrl, { headers });
+    this.$connected = true;
+    if (!this.$config.access_token) this.logger.warn('missing access_token, SSE connection is not secured');
+
+    this.es.addEventListener('milky_event', (e: MessageEvent) => {
+      try {
+        const event = JSON.parse(e.data) as MilkyEvent;
+        this.handleEvent(event);
+      } catch (err: unknown) {
+        this.emit('error', err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+
+    this.es.onerror = (err: unknown) => {
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
+    };
+  }
+
+  async $disconnect(): Promise<void> {
+    if (this.es) {
+      this.es.close();
+      this.es = undefined;
+    }
+    this.$connected = false;
+  }
+
+  $formatMessage(event: MilkyEvent): Message<MilkyEvent> {
+    const data = parseMessageReceiveData(event);
+    if (!data) {
+      return Message.from(event, {
+        $id: '',
+        $adapter: 'milky',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: event.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatMilkyMessagePayload(
+      event,
+      data,
+      (id) => this.$recallMessage(id),
+      (channel, content) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'milky',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+      'milky',
+      this.$config.name,
+    );
+    return Message.from(event, payload);
+  }
+
+  private handleEvent(event: MilkyEvent): void {
+    const data = parseMessageReceiveData(event);
+    if (data) {
+      const message = this.$formatMessage(event);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    }
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const content = Array.isArray(options.content) ? options.content : [options.content];
+    const segments = content.map((c) =>
+      typeof c === 'string' ? { type: 'text' as const, data: { text: c } } : (c as { type: string; data?: Record<string, unknown> }),
+    );
+    const message = toMilkyOutgoingSegments(segments);
+    if (options.type === 'group') {
+      const result = await callApi(this.apiOptions(), 'send_group_message', {
+        group_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      this.logger.debug(`${this.$config.name} send group(${options.id}):${segment.raw(options.content)}`);
+      return seq != null ? `group:${options.id}:${seq}` : '';
+    }
+    if (options.type === 'private') {
+      const result = await callApi(this.apiOptions(), 'send_private_message', {
+        user_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      this.logger.debug(`${this.$config.name} send private(${options.id}):${segment.raw(options.content)}`);
+      return seq != null ? `friend:${options.id}:${seq}` : '';
+    }
+    throw new Error('Either group or private must be provided');
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const parsed = parseMilkyMessageId(id);
+    if (!parsed) throw new Error(`Invalid message id: ${id}`);
+    if (parsed.message_scene === 'group') {
+      await callApi(this.apiOptions(), 'recall_group_message', {
+        group_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    } else {
+      await callApi(this.apiOptions(), 'recall_private_message', {
+        user_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    }
+  }
+
+  async kickMember(groupId: number, userId: number, rejectAddRequest = false): Promise<boolean> {
+    await callApi(this.apiOptions(), 'kick_group_member', {
+      group_id: groupId,
+      user_id: userId,
+      reject_add_request: rejectAddRequest,
+    });
+    return true;
+  }
+
+  async muteMember(groupId: number, userId: number, duration = 600): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_mute', {
+      group_id: groupId,
+      user_id: userId,
+      duration,
+    });
+    return true;
+  }
+
+  async muteAll(groupId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_whole_mute', { group_id: groupId, is_mute: enable });
+    return true;
+  }
+
+  async setAdmin(groupId: number, userId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_admin', {
+      group_id: groupId,
+      user_id: userId,
+      is_set: enable,
+    });
+    return true;
+  }
+
+  async setCard(groupId: number, userId: number, card: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_card', {
+      group_id: groupId,
+      user_id: userId,
+      card,
+    });
+    return true;
+  }
+
+  async setTitle(groupId: number, userId: number, title: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_special_title', {
+      group_id: groupId,
+      user_id: userId,
+      special_title: title,
+    });
+    return true;
+  }
+
+  async setGroupName(groupId: number, name: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_name', { group_id: groupId, new_group_name: name });
+    return true;
+  }
+
+  async getMemberList(groupId: number): Promise<unknown[]> {
+    return callApi(this.apiOptions(), 'get_group_member_list', { group_id: groupId }) as Promise<unknown[]>;
+  }
+
+  async getGroupInfo(groupId: number): Promise<unknown> {
+    return callApi(this.apiOptions(), 'get_group_info', { group_id: groupId });
+  }
+}

package/src/bot-webhook.ts

@@ -0,0 +1,222 @@
+/**
+ * Milky Webhook Bot：无长连接，在 router.post(path) 接收 POST 事件，鉴权后转 Message
+ */
+import { EventEmitter } from 'events';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import type { Router, RouterContext } from '@zhin.js/http';
+import { callApi } from './api.js';
+import type { MilkyWebhookConfig, MilkyEvent } from './types.js';
+import type { MilkyAdapter } from './adapter.js';
+import {
+  formatMilkyMessagePayload,
+  parseMessageReceiveData,
+  toMilkyOutgoingSegments,
+  parseMilkyMessageId,
+} from './utils.js';
+
+function getAccessTokenFromRequest(ctx: RouterContext): string | undefined {
+  const auth = ctx.headers['authorization'];
+  if (typeof auth === 'string' && auth.startsWith('Bearer ')) return auth.slice(7);
+  const q = ctx.request.query?.access_token;
+  return typeof q === 'string' ? q : undefined;
+}
+
+export class MilkyWebhookBot extends EventEmitter implements Bot<MilkyWebhookConfig, MilkyEvent> {
+  $connected: boolean = true;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(
+    public adapter: MilkyAdapter,
+    public router: Router,
+    public $config: MilkyWebhookConfig,
+  ) {
+    super();
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  async $connect(): Promise<void> {
+    const path = this.$config.path.startsWith('/') ? this.$config.path : `/${this.$config.path}`;
+    const token = this.$config.access_token;
+    this.router.post(path, async (ctx: RouterContext) => {
+      const received = getAccessTokenFromRequest(ctx);
+      if (token && received !== token) {
+        ctx.status = 401;
+        ctx.body = { retcode: 401, message: 'Unauthorized' };
+        return;
+      }
+      const body = ctx.request.body;
+      if (!body || typeof body !== 'object') {
+        ctx.status = 400;
+        ctx.body = { retcode: 400, message: 'Invalid JSON' };
+        return;
+      }
+      const event = body as MilkyEvent;
+      this.handleEvent(event);
+      ctx.status = 200;
+      ctx.body = { retcode: 0 };
+    });
+    this.logger.info(`Milky Webhook 注册路径: ${path}`);
+  }
+
+  async $disconnect(): Promise<void> {
+    this.$connected = false;
+  }
+
+  $formatMessage(event: MilkyEvent): Message<MilkyEvent> {
+    const data = parseMessageReceiveData(event);
+    if (!data) {
+      return Message.from(event, {
+        $id: '',
+        $adapter: 'milky',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: event.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatMilkyMessagePayload(
+      event,
+      data,
+      (id) => this.$recallMessage(id),
+      (channel, content) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'milky',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+      'milky',
+      this.$config.name,
+    );
+    return Message.from(event, payload);
+  }
+
+  private handleEvent(event: MilkyEvent): void {
+    const data = parseMessageReceiveData(event);
+    if (data) {
+      const message = this.$formatMessage(event);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    }
+  }
+
+  private apiOptions() {
+    return { baseUrl: this.$config.baseUrl, access_token: this.$config.access_token };
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const content = Array.isArray(options.content) ? options.content : [options.content];
+    const segments = content.map((c) =>
+      typeof c === 'string' ? { type: 'text' as const, data: { text: c } } : (c as { type: string; data?: Record<string, unknown> }),
+    );
+    const message = toMilkyOutgoingSegments(segments);
+    if (options.type === 'group') {
+      const result = await callApi(this.apiOptions(), 'send_group_message', {
+        group_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      return seq != null ? `group:${options.id}:${seq}` : '';
+    }
+    if (options.type === 'private') {
+      const result = await callApi(this.apiOptions(), 'send_private_message', {
+        user_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      return seq != null ? `friend:${options.id}:${seq}` : '';
+    }
+    throw new Error('Either group or private must be provided');
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const parsed = parseMilkyMessageId(id);
+    if (!parsed) throw new Error(`Invalid message id: ${id}`);
+    if (parsed.message_scene === 'group') {
+      await callApi(this.apiOptions(), 'recall_group_message', {
+        group_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    } else {
+      await callApi(this.apiOptions(), 'recall_private_message', {
+        user_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    }
+  }
+
+  async kickMember(groupId: number, userId: number, rejectAddRequest = false): Promise<boolean> {
+    await callApi(this.apiOptions(), 'kick_group_member', {
+      group_id: groupId,
+      user_id: userId,
+      reject_add_request: rejectAddRequest,
+    });
+    return true;
+  }
+
+  async muteMember(groupId: number, userId: number, duration = 600): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_mute', {
+      group_id: groupId,
+      user_id: userId,
+      duration,
+    });
+    return true;
+  }
+
+  async muteAll(groupId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_whole_mute', { group_id: groupId, is_mute: enable });
+    return true;
+  }
+
+  async setAdmin(groupId: number, userId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_admin', {
+      group_id: groupId,
+      user_id: userId,
+      is_set: enable,
+    });
+    return true;
+  }
+
+  async setCard(groupId: number, userId: number, card: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_card', {
+      group_id: groupId,
+      user_id: userId,
+      card,
+    });
+    return true;
+  }
+
+  async setTitle(groupId: number, userId: number, title: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_special_title', {
+      group_id: groupId,
+      user_id: userId,
+      special_title: title,
+    });
+    return true;
+  }
+
+  async setGroupName(groupId: number, name: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_name', { group_id: groupId, new_group_name: name });
+    return true;
+  }
+
+  async getMemberList(groupId: number): Promise<unknown[]> {
+    return callApi(this.apiOptions(), 'get_group_member_list', { group_id: groupId }) as Promise<unknown[]>;
+  }
+
+  async getGroupInfo(groupId: number): Promise<unknown> {
+    return callApi(this.apiOptions(), 'get_group_info', { group_id: groupId });
+  }
+}