@dsh-overdrive/gateway 0.1.0

package/src/index.ts

@@ -0,0 +1,220 @@
+import { GatewayClient, type ServerEvent } from '@dsh-overdrive/sdk';
+import type { Adapter, OutboundPayload } from './adapter.js';
+import { Allowlist, buildSessionKey } from './session.js';
+import { adapterEnvFromProcess, createAdapter, parseAdapterIds } from './config.js';
+import { CliAdapter } from './adapters/cli.js';
+import { parseCommand, HELP_TEXT, type ParsedCommand } from './commands.js';
+import { TrajectoryAggregator, formatTrajectorySummary } from './trajectory.js';
+import { createStatusServer } from './status.js';
+
+/**
+ * message.delta → 打字指示去重：同一 turn 内首个 delta 触发一次 typing，
+ * complete 后复位，下一 turn 可再次触发。纯逻辑，便于单测。
+ */
+export class DeltaTracker {
+  private readonly fired = new Set<string>();
+
+  onDelta(sessionId: string, fireTyping: () => void): void {
+    if (this.fired.has(sessionId)) return;
+    this.fired.add(sessionId);
+    fireTyping();
+  }
+
+  /** turn 结束（message.complete / error）时复位，允许下一 turn 再次触发 typing。 */
+  onComplete(sessionId: string): void {
+    this.fired.delete(sessionId);
+  }
+}
+
+/** 事件 → 平台输出。纯函数，便于单测。返回 null 表示该事件不产出消息。 */
+export function planOutbound(ev: ServerEvent): { payload: OutboundPayload } | null {
+  switch (ev.type) {
+    case 'message.complete':
+      return { payload: { text: ev.text } };
+    case 'message.delta':
+      return null; // 流式渲染走 sendTyping（见 wireAdapter），不产出文本
+    case 'trajectory.step': {
+      const icon = ev.step.kind === 'tool' ? '🛠️' : ev.step.kind === 'subagent' ? '🤖' : '🧠';
+      return { payload: { text: `${icon} ${ev.step.label}` } };
+    }
+    case 'trajectory.summary':
+      return { payload: { text: formatTrajectorySummary(ev.steps) } };
+    case 'approval.request':
+      return {
+        payload: {
+          text: `⚠️ 需要批准：${ev.summary}（${Math.round(ev.timeoutMs / 1000)}s 内有效）`,
+          buttons: [
+            { id: `approve:${ev.reqId}`, label: '✅ 同意' },
+            { id: `reject:${ev.reqId}`, label: '🚫 拒绝' },
+          ],
+        },
+      };
+    case 'agent.status':
+      return ev.status === 'subagent-spawned'
+        ? { payload: { text: '🤖 派生子任务…' } }
+        : null;
+    case 'task.done':
+      return { payload: { text: ev.ok ? `✅ 任务完成 ${ev.taskId}` : `❌ 任务失败 ${ev.taskId}` } };
+    case 'error':
+      return { payload: { text: `❌ 出错了：${ev.message}` } };
+    default:
+      return null;
+  }
+}
+
+export interface WireOptions {
+  allowlist: string[];
+}
+
+/** 命令面分发：/trace /new /task /cron /agents /help（M4）。 */
+async function handleCommand(
+  adapter: Adapter,
+  client: GatewayClient,
+  command: ParsedCommand,
+  sessionId: string,
+  chatId: string,
+  aggregator: TrajectoryAggregator,
+): Promise<void> {
+  switch (command.kind) {
+    case 'trace': {
+      const summary = aggregator.recentSummary(sessionId);
+      await adapter.send(chatId, { text: summary ?? '暂无轨迹（尚未运行或已重置）。' });
+      return;
+    }
+    case 'new': {
+      await client.resetSession(sessionId);
+      await adapter.send(chatId, { text: '🆕 会话已重置' });
+      return;
+    }
+    case 'task': {
+      await client.createTask({ sessionId, kind: 'subagent', prompt: command.prompt });
+      await adapter.send(chatId, { text: '🤖 子任务已派出' });
+      return;
+    }
+    case 'cron': {
+      await client.createTask({ sessionId, kind: 'cron', prompt: command.prompt, schedule: command.schedule });
+      await adapter.send(chatId, { text: '⏰ 定时任务已注册' });
+      return;
+    }
+    case 'agents': {
+      await adapter.send(chatId, { text: '（M4 简化）子任务状态由 agent 汇报，/task 派发' });
+      return;
+    }
+    case 'help': {
+      await adapter.send(chatId, { text: HELP_TEXT });
+      return;
+    }
+  }
+}
+
+/** 单个适配器的接线：白名单 → 命令面/upsert → sendMessage；按钮 → resolveApproval；事件流经轨迹聚合。 */
+export async function wireAdapter(
+  adapter: Adapter,
+  client: GatewayClient,
+  opts: WireOptions,
+): Promise<void> {
+  const allow = new Allowlist(opts.allowlist);
+  const chatIds = new Map<string, string>();
+  const aggregator = new TrajectoryAggregator();
+  const deltas = new DeltaTracker();
+
+  adapter.onMessage(async (msg) => {
+    const key = buildSessionKey(adapter.id, msg);
+    console.log(`[gateway][${adapter.id}] 收到消息 chat=${msg.chatId} user=${msg.userId} text="${msg.text.slice(0, 40)}"`);
+    try {
+      if (!allow.allows(key)) {
+        await adapter.send(msg.chatId, { text: '⛔ 你不在白名单里。' });
+        return;
+      }
+      chatIds.set(key, msg.chatId);
+
+      const command = parseCommand(msg.text);
+      if (command) {
+        console.log(`[gateway][${adapter.id}] 命令: ${JSON.stringify(command)}`);
+        await handleCommand(adapter, client, command, key, msg.chatId, aggregator);
+        return;
+      }
+
+      await client.upsertSession({ platform: adapter.id, channel: msg.chatId, user: msg.userId });
+      console.log(`[gateway][${adapter.id}] upsertSession OK -> ${key}`);
+      await client.sendMessage(key, { text: msg.text, media: msg.media });
+      console.log(`[gateway][${adapter.id}] sendMessage OK`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`[gateway][${adapter.id}] 处理失败: ${message}`);
+      await adapter.send(msg.chatId, { text: `❌ 出错了：${message}` }).catch(() => undefined);
+    }
+  });
+
+  adapter.onReply(async (buttonId) => {
+    try {
+      const idx = buttonId.indexOf(':');
+      if (idx < 0) return;
+      const action = buttonId.slice(0, idx) as 'approve' | 'reject';
+      const reqId = buttonId.slice(idx + 1);
+      if ((action === 'approve' || action === 'reject') && reqId) {
+        await client.resolveApproval(reqId, action);
+      }
+    } catch (error) {
+      console.error(`[gateway] resolveApproval 失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+
+  const chatIdFor = (sessionId: string): string => {
+    const known = chatIds.get(sessionId);
+    if (known) return known;
+    return sessionId.split(':')[1] ?? sessionId;
+  };
+
+  await client.connect((ev) => {
+    // 流式渲染：delta → 打字指示（去重），complete/error → 复位（下一 turn 可再触发）
+    if (ev.type === 'message.delta') {
+      deltas.onDelta(ev.sessionId, () => void adapter.sendTyping?.(chatIdFor(ev.sessionId)));
+    } else if (ev.type === 'message.complete' || ev.type === 'error') {
+      deltas.onComplete(ev.sessionId);
+    }
+
+    // 轨迹聚合：trajectory.step 攒批，idle 时产出 trajectory.summary（减少刷屏）
+    aggregator.onEvent(ev, (out) => {
+      const planned = planOutbound(out);
+      if (!planned) return;
+      const chatId = chatIdFor(out.sessionId);
+      console.log(`[gateway][${adapter.id}] 事件 ${out.type} -> 发送到 ${chatId}`);
+      void adapter.send(chatId, planned.payload).then(
+        () => console.log(`[gateway][${adapter.id}] 已发送 ${out.type} 到 ${chatId}`),
+        (error) => console.error(`[gateway][${adapter.id}] 发送失败 ${out.type}: ${error instanceof Error ? error.message : String(error)}`),
+      );
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  const dshBaseUrl = process.env.DSH_BASE_URL ?? 'http://127.0.0.1:3191';
+  const dshToken = process.env.DSH_TOKEN ?? 'dev-token';
+  const allowlist = (process.env.ALLOWLIST ?? '')
+    .split(',').map((s) => s.trim()).filter(Boolean);
+  const adapterIds = parseAdapterIds(process.env.GATEWAY_ADAPTERS ?? 'cli');
+  const env = adapterEnvFromProcess();
+
+  const client = new GatewayClient(dshBaseUrl, dshToken);
+  await client.health(); // 确认 DSH 侧（或 mock）活着
+
+  const adapters: Adapter[] = adapterIds.map((id) => createAdapter(id, env));
+  for (const adapter of adapters) {
+    await adapter.connect();
+    await wireAdapter(adapter, client, { allowlist });
+    console.log(`[gateway] ${adapter.id} 适配器已就绪`);
+  }
+
+  const consolePort = Number(process.env.GATEWAY_CONSOLE_PORT ?? 3190);
+  const status = createStatusServer({ adapters, client, version: '0.1.0' });
+  await status.listen(consolePort);
+  console.log(`[gateway] 控制台 http://0.0.0.0:${consolePort}/`);
+
+  process.stdout.write(`[gateway] 就绪（适配器: ${adapterIds.join(', ')}）。Ctrl+C 退出。\n`);
+}
+
+if (process.argv[1]?.endsWith('index.js')) void main();
+
+// 保留 CLI 的直接导入（E2E 用）
+export { CliAdapter };

package/src/session.ts

@@ -0,0 +1,17 @@
+import { sessionKey } from '@dsh-overdrive/sdk';
+
+export function buildSessionKey(
+  adapterId: string,
+  msg: { chatId: string; userId: string },
+): string {
+  return sessionKey(adapterId, msg.chatId, msg.userId);
+}
+
+/** 空列表 = 开发模式放行所有；生产环境必须显式配置。 */
+export class Allowlist {
+  constructor(private readonly entries: string[]) {}
+
+  allows(key: string): boolean {
+    return this.entries.length === 0 || this.entries.includes(key);
+  }
+}

package/src/status.ts

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import { createServer, type Server } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import type { Adapter } from './adapter.js';
+import type { GatewayClient } from '@dsh-overdrive/sdk';
+
+export interface StatusServerOptions {
+  adapters: Adapter[];
+  client: GatewayClient;
+  version: string;
+}
+
+/**
+ * 健康控制台：GET / 与 /console 返回静态页，GET /api/status 返回 DSH 健康 + 适配器状态。
+ *
+ * console.html 读取路径说明（与 dist 产物核对过）：
+ * - src 运行（vitest）：import.meta.url = packages/gateway/src/status.ts → ../../web/console.html = packages/web/console.html
+ * - dist 运行（node packages/gateway/dist/index.js）：import.meta.url = packages/gateway/dist/status.js → ../../web/console.html = packages/web/console.html
+ * 两种形态下 `../../web/console.html` 均解析到 packages/web/console.html（plan 中的
+ * ../../../web/console.html 会多上一级到仓库根目录，不正确，已修正）。
+ */
+export function createStatusServer(opts: StatusServerOptions): {
+  server: Server;
+  listen(port: number): Promise<number>;
+  close(): Promise<void>;
+} {
+  const http = createServer(async (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname === '/api/status') {
+      let dsh: { status: string } | { error: string };
+      try {
+        dsh = await opts.client.health();
+      } catch (error) {
+        dsh = { error: error instanceof Error ? error.message : String(error) };
+      }
+      const adapters = opts.adapters.map((a) => ({
+        id: a.id,
+        connected: a.status?.().connected ?? null,
+      }));
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ version: opts.version, dsh, adapters }));
+      return;
+    }
+    if (url.pathname === '/' || url.pathname === '/console') {
+      const html = await readFile(
+        fileURLToPath(new URL('../../web/console.html', import.meta.url)),
+        'utf8',
+      ).catch(() => '<h1>console.html not found</h1>');
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      res.end(html);
+      return;
+    }
+    res.writeHead(404, { 'content-type': 'text/plain' });
+    res.end('not found');
+  });
+  return {
+    server: http,
+    listen: (port: number) =>
+      new Promise<number>((resolve) =>
+        http.listen(port, '0.0.0.0', () => resolve((http.address() as { port: number }).port)),
+      ),
+    close: () => new Promise<void>((resolve) => http.close(() => resolve())),
+  };
+}

package/src/trajectory.ts

@@ -0,0 +1,45 @@
+import type { ServerEvent, TrajectoryStep } from '@dsh-overdrive/sdk';
+
+/** turn 级轨迹聚合：收集 trajectory.step，turn/end（idle）时产出 trajectory.summary 摘要卡片。 */
+export class TrajectoryAggregator {
+  private readonly buffer = new Map<string, TrajectoryStep[]>();
+  private readonly summaries = new Map<string, string>();
+
+  onEvent(ev: ServerEvent, emit: (ev: ServerEvent) => void): void {
+    if (ev.type === 'agent.status' && ev.status === 'idle') {
+      const steps = this.buffer.get(ev.sessionId) ?? [];
+      this.buffer.delete(ev.sessionId);
+      if (steps.length > 0) {
+        this.summaries.set(ev.sessionId, formatTrajectorySummary(steps));
+        emit({ type: 'trajectory.summary', sessionId: ev.sessionId, ts: Date.now(), steps });
+      }
+      emit(ev);
+      return;
+    }
+    if (ev.type === 'agent.status' && ev.status === 'busy') {
+      this.buffer.set(ev.sessionId, []);
+      emit(ev);
+      return;
+    }
+    if (ev.type === 'trajectory.step') {
+      const list = this.buffer.get(ev.sessionId);
+      if (list) list.push(ev.step);
+      else this.buffer.set(ev.sessionId, [ev.step]);
+      return; // 单步不实时推，等摘要（减少刷屏）
+    }
+    emit(ev);
+  }
+
+  /** 最近一次 turn 的轨迹摘要文本（/trace 命令用），无则 null。 */
+  recentSummary(sessionId: string): string | null {
+    return this.summaries.get(sessionId) ?? null;
+  }
+}
+
+export function formatTrajectorySummary(steps: TrajectoryStep[]): string {
+  const lines = steps.map((s) => {
+    const icon = s.kind === 'tool' ? '🛠️' : s.kind === 'subagent' ? '🤖' : '🧠';
+    return `${icon} ${s.label}`;
+  });
+  return `📋 轨迹（${lines.length} 步）\n${lines.join('\n')}`;
+}

package/test/adapters.dingtalk.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { buildReplyBody, parseBotMessage } from '../src/adapters/dingtalk.js';
+
+describe('parseBotMessage（RobotMessage → NormalizedMessage）', () => {
+  it('文本消息', () => {
+    const data = {
+      conversationId: 'cid1',
+      senderStaffId: 'u1',
+      msgtype: 'text',
+      text: { content: 'hello' },
+      sessionWebhook: 'https://hook.dingtalk.com/x',
+    };
+    const out = parseBotMessage(data);
+    expect(out).toMatchObject({ chatId: 'cid1', userId: 'u1', text: 'hello' });
+  });
+  it('非文本返回 null', () => {
+    expect(parseBotMessage({ conversationId: 'c', msgtype: 'picture' })).toBeNull();
+  });
+});
+
+describe('buildReplyBody（sessionWebhook 回发载荷）', () => {
+  it('文本消息体', () => {
+    expect(buildReplyBody('hi')).toEqual({ msgtype: 'text', text: { content: 'hi' } });
+  });
+});

package/test/adapters.discord.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { discordAttachmentUrl, discordComponents, normalizeDiscordMessage } from '../src/adapters/discord.js';
+
+describe('normalizeDiscordMessage', () => {
+  it('文本消息 → NormalizedMessage', () => {
+    const raw = { channelId: '111', author: { id: '222', bot: false }, content: 'hello' };
+    const out = normalizeDiscordMessage(raw);
+    expect(out).toMatchObject({ chatId: '111', userId: '222', text: 'hello' });
+  });
+  it('bot 消息返回 null', () => {
+    expect(normalizeDiscordMessage({ channelId: '1', author: { id: '2', bot: true }, content: 'x' })).toBeNull();
+  });
+  it('含附件 → media: { kind: "image", url }（纯函数 discordAttachmentUrl 取第一条）', () => {
+    const raw = {
+      channelId: '111',
+      author: { id: '222', bot: false },
+      content: '',
+      attachments: [{ url: 'https://cdn.discordapp.com/a.png', contentType: 'image/png' }],
+    };
+    expect(discordAttachmentUrl(raw)).toBe('https://cdn.discordapp.com/a.png');
+    expect(normalizeDiscordMessage(raw)).toMatchObject({
+      chatId: '111', userId: '222', text: '', media: { kind: 'image', url: 'https://cdn.discordapp.com/a.png' },
+    });
+  });
+});
+
+describe('discordComponents（按钮 action row 数据）', () => {
+  it('按钮 → discord components 结构', () => {
+    const comps = discordComponents([
+      { id: 'approve:r1', label: '✅ 同意' },
+      { id: 'reject:r1', label: '🚫 拒绝' },
+    ]);
+    expect(comps).toEqual([{
+      type: 1,
+      components: [
+        { type: 2, custom_id: 'approve:r1', label: '✅ 同意', style: 1 },
+        { type: 2, custom_id: 'reject:r1', label: '🚫 拒绝', style: 1 },
+      ],
+    }]);
+  });
+});

package/test/adapters.feishu.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { buildNumberedText, parseFeishuTextMessage } from '../src/adapters/feishu.js';
+
+describe('parseFeishuTextMessage（im.message.receive_v1 载荷 → NormalizedMessage）', () => {
+  it('文本私聊消息', () => {
+    const data = {
+      event: {
+        message: { message_id: 'om_1', chat_id: 'oc_1', message_type: 'text', content: JSON.stringify({ text: 'hello' }) },
+        sender: { sender_id: { open_id: 'ou_1' } },
+      },
+    };
+    const out = parseFeishuTextMessage(data);
+    expect(out).toMatchObject({ chatId: 'oc_1', userId: 'ou_1', text: 'hello' });
+  });
+  it('非文本消息返回 null', () => {
+    const data = { event: { message: { message_type: 'image', content: '{}' }, sender: { sender_id: { open_id: 'ou_1' } } } };
+    expect(parseFeishuTextMessage(data)).toBeNull();
+  });
+});
+
+describe('buildNumberedText（审批编号回复）', () => {
+  it('生成 1/2 选项文本', () => {
+    const text = buildNumberedText('需要批准', [
+      { id: 'approve:r1', label: '✅ 同意' },
+      { id: 'reject:r1', label: '🚫 拒绝' },
+    ]);
+    expect(text).toContain('1) ✅ 同意');
+    expect(text).toContain('2) 🚫 拒绝');
+  });
+});

package/test/adapters.slack.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeSlackMessage, slackBlocks, slackFileUrl } from '../src/adapters/slack.js';
+
+describe('normalizeSlackMessage', () => {
+  it('文本消息 → NormalizedMessage', () => {
+    const raw = { channel: 'C123', user: 'U456', text: 'hello', subtype: undefined };
+    const out = normalizeSlackMessage(raw);
+    expect(out).toMatchObject({ chatId: 'C123', userId: 'U456', text: 'hello' });
+  });
+  it('bot 自己的消息（subtype=bot_message）返回 null', () => {
+    expect(normalizeSlackMessage({ channel: 'C1', user: 'U2', text: 'x', subtype: 'bot_message' })).toBeNull();
+  });
+  it('含文件 → media: { kind: "image", url }（纯函数 slackFileUrl 取 files[0].url_private）', () => {
+    const raw = {
+      channel: 'C1',
+      user: 'U2',
+      text: '',
+      files: [{ url_private: 'https://files.slack.com/files/x.png', mimetype: 'image/png' }],
+    };
+    expect(slackFileUrl(raw)).toBe('https://files.slack.com/files/x.png');
+    expect(normalizeSlackMessage(raw)).toMatchObject({
+      chatId: 'C1', userId: 'U2', text: '', media: { kind: 'image', url: 'https://files.slack.com/files/x.png' },
+    });
+  });
+});
+
+describe('slackBlocks', () => {
+  it('纯文本 → 一个 section', () => {
+    const blocks = slackBlocks('hi', []);
+    expect(blocks).toEqual([{ type: 'section', text: { type: 'mrkdwn', text: 'hi' } }]);
+  });
+  it('带按钮 → section + actions', () => {
+    const blocks = slackBlocks('需要批准', [
+      { id: 'approve:r1', label: '✅ 同意' },
+      { id: 'reject:r1', label: '🚫 拒绝' },
+    ]);
+    expect(blocks[1]).toMatchObject({
+      type: 'actions',
+      elements: [
+        { type: 'button', value: 'approve:r1', text: { type: 'plain_text', text: '✅ 同意' } },
+        { type: 'button', value: 'reject:r1', text: { type: 'plain_text', text: '🚫 拒绝' } },
+      ],
+    });
+  });
+});

package/test/adapters.telegram.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { buttonRows, normalizeTelegramMessage, telegramImageUrl, telegramPhotoFileId } from '../src/adapters/telegram.js';
+
+describe('normalizeTelegramMessage', () => {
+  it('文本消息 → NormalizedMessage（chatId/userId 字符串化）', () => {
+    const ctx = { chat: { id: 12345 }, from: { id: 678 }, message: { text: 'hello' } };
+    const out = normalizeTelegramMessage(ctx as never);
+    expect(out).toMatchObject({ chatId: '12345', userId: '678', text: 'hello' });
+  });
+  it('无文本返回 null', () => {
+    expect(normalizeTelegramMessage({ chat: { id: 1 }, from: { id: 2 }, message: { photo: [] } } as never)).toBeNull();
+  });
+  it('含 photo 的消息 → media: { kind: "image" }，file_id → 下载 URL 模板（真实 getFile 在 adapter）', () => {
+    const ctx = {
+      chat: { id: 1 },
+      from: { id: 2 },
+      message: { photo: [{ file_id: 'small' }, { file_id: 'large' }] },
+    };
+    expect(normalizeTelegramMessage(ctx as never)).toMatchObject({
+      chatId: '1', userId: '2', text: '', media: { kind: 'image' },
+    });
+    expect(telegramPhotoFileId(ctx.message.photo)).toBe('large');
+    expect(telegramImageUrl('SECRET', 'photos/file_10.jpg')).toBe('https://api.telegram.org/file/botSECRET/photos/file_10.jpg');
+  });
+});
+
+describe('buttonRows（InlineKeyboard 数据）', () => {
+  it('按钮 → [label, id] 行', () => {
+    expect(buttonRows([
+      { id: 'approve:r1', label: '✅ 同意' },
+      { id: 'reject:r1', label: '🚫 拒绝' },
+    ])).toEqual([
+      ['✅ 同意', 'approve:r1'],
+      ['🚫 拒绝', 'reject:r1'],
+    ]);
+  });
+});

package/test/adapters.wecom.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildNumberedText,
+  decryptWeComPayload,
+  encryptWeComPayload,
+  matchNumberedButton,
+  parseWeComXmlMessage,
+} from '../src/adapters/wecom.js';
+
+const KEY = 'abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG'; // 43 位 EncodingAESKey
+
+describe('企业微信 AES 加解密（往返）', () => {
+  it('encrypt → decrypt 还原原文（含 receiveId）', () => {
+    const { encrypted } = encryptWeComPayload(KEY, 'hello', 'corpid123');
+    const out = decryptWeComPayload(KEY, encrypted);
+    expect(out.message).toBe('hello');
+    expect(out.receiveId).toBe('corpid123');
+  });
+
+  it('中文消息往返', () => {
+    const { encrypted } = encryptWeComPayload(KEY, '你好，世界', 'ww1234567890');
+    const out = decryptWeComPayload(KEY, encrypted);
+    expect(out.message).toBe('你好，世界');
+    expect(out.receiveId).toBe('ww1234567890');
+  });
+});
+
+describe('parseWeComXmlMessage（回调 XML → NormalizedMessage）', () => {
+  it('文本消息', () => {
+    const xml = `<xml><ToUserName><![CDATA[ww1]]></ToUserName><FromUserName><![CDATA[user1]]></FromUserName><MsgType><![CDATA[text]]></MsgType><Content><![CDATA[你好]]></Content></xml>`;
+    const out = parseWeComXmlMessage(xml);
+    expect(out).toMatchObject({ chatId: 'user1', userId: 'user1', text: '你好' });
+  });
+  it('非文本返回 null', () => {
+    const xml = `<xml><FromUserName><![CDATA[u]]></FromUserName><MsgType><![CDATA[image]]></MsgType></xml>`;
+    expect(parseWeComXmlMessage(xml)).toBeNull();
+  });
+});
+
+describe('buildNumberedText（审批编号回复）', () => {
+  it('生成 1/2 选项文本', () => {
+    const text = buildNumberedText('需要批准', [
+      { id: 'approve:r1', label: '同意' },
+      { id: 'reject:r1', label: '拒绝' },
+    ]);
+    expect(text).toContain('1) 同意');
+    expect(text).toContain('2) 拒绝');
+    expect(text).toContain('回复数字选择');
+  });
+  it('无按钮时原样返回', () => {
+    expect(buildNumberedText('plain', [])).toBe('plain');
+  });
+  it('matchNumberedButton 命中选项', () => {
+    const buttons = [
+      { id: 'approve:r1', label: '同意' },
+      { id: 'reject:r1', label: '拒绝' },
+    ];
+    expect(matchNumberedButton('2', buttons)).toEqual(buttons[1]);
+    expect(matchNumberedButton('3', buttons)).toBeUndefined();
+    expect(matchNumberedButton('abc', buttons)).toBeUndefined();
+  });
+});