Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

14.1 KB
Raw Blame
/**
 * slack-hook-protocol 阶段 20(msg.op 消息操作动词)测试:
 *   1. 六种动作的构造 → 序列化 → 解析 round-trip
 *   2. 幂等键 opId 与授权锚点 scope.externalKey 缺失即拒收
 *   3. msg.op.result 的 messageId 契约(客户端后续 edit/delete/react 的唯一依据)
 *   4. 能力标识常量 msg-op-v1
 *   5. 老端兼容: 不认识 msg.op 的端按未知类型拒收(丢帧不断连语义)
 */

import { describe, it, expect } from 'vitest';

import {
  HOOK_FEATURE_MESSAGE_OPS,
  HOOK_FEATURE_TELEGRAM_CARD_OPS,
  HOOK_FEATURE_TELEGRAM_COMMANDS,
  HOOK_FEATURE_TELEGRAM_FINAL_OPS,
  HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,
  makeProviderCommandsSet,
  makeTurnEnd,
  MESSAGE_OP_ERROR_OUTCOME_UNKNOWN,
  MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE,
  makeMessageOp,
  makeMessageOpResult,
  parseHookMessage,
  serializeHookMessage,
  type HookMessage,
  type MessageOpAction,
} from '../index';

function roundTrip(message: HookMessage): HookMessage {
  const parsed = parseHookMessage(serializeHookMessage(message));
  if (!parsed.ok) throw new Error(`parse failed: ${parsed.error}`);
  return parsed.message;
}

const SCOPE = { externalKey: 'telegram:group:bot:−100:111:g1' };

function op(action: MessageOpAction, opId = 'op-1') {
  return makeMessageOp({ opId, requestId: 'req-1', scope: SCOPE, action });
}

describe('msg.op 动词集', () => {
  it('能力标识为 msg-op-v1', () => {
    expect(HOOK_FEATURE_MESSAGE_OPS).toBe('msg-op-v1');
  });

  it('六种动作都能 round-trip 且形态原样保留', () => {
    const actions: MessageOpAction[] = [
      {
        kind: 'send',
        text: '已渲染的最终正文',
        replyToMessageId: '42',
        tier: 'rich',
        buttons: [[{ token: 'cdy:abc', label: '同意' }]],
      },
      { kind: 'edit', messageId: '43', text: '改后的正文', tier: 'html' },
      { kind: 'delete', messageId: '44' },
      { kind: 'react', targetMessageId: '45', emoji: '👍', big: true },
      { kind: 'typing' },
      {
        kind: 'media',
        album: true,
        items: [{ name: 'a.png', mimeType: 'image/png', dataBase64: 'AAAA' }],
      },
    ];
    for (const action of actions) {
      const parsed = roundTrip(op(action));
      expect(parsed.type).toBe('msg.op');
      expect(parsed.payload).toMatchObject({ opId: 'op-1', scope: SCOPE, action });
    }
  });

  it('react 的空 emoji 是撤销语义, 合法', () => {
    const parsed = roundTrip(op({ kind: 'react', targetMessageId: '46', emoji: '' }));
    expect((parsed.payload as { action: { emoji: string } }).action.emoji).toBe('');
  });

  it('scope 携带 chatId / threadId 一律拒收(寻址权不在客户端)', () => {
    // 目标 chat 必须由服务端从 lane 记录里取。允许客户端指定, 一台被攻陷或有
    // bug 的桌面就能越过自己 lane 的边界往任意聊天发消息。
    for (const extra of [{ chatId: '-100999' }, { threadId: '7' }]) {
      const frame = JSON.parse(serializeHookMessage(op({ kind: 'typing' }))) as Record<
        string,
        unknown
      >;
      Object.assign((frame.payload as { scope: Record<string, unknown> }).scope, extra);
      const parsed = parseHookMessage(JSON.stringify(frame));
      expect(parsed.ok).toBe(false);
      if (!parsed.ok) expect(parsed.error).toContain('resolves the target from externalKey');
    }
  });

  it('缺 opId 或 scope.externalKey 一律拒收', () => {
    // opId 是断连重发下不产生重复消息的唯一依据(Telegram 无发送端幂等键),
    // externalKey 是多租户授权锚点 —— 两者都不能让服务端"尽力而为"地猜。
    const base = op({ kind: 'typing' });
    const noOpId = JSON.parse(serializeHookMessage(base)) as Record<string, unknown>;
    (noOpId.payload as Record<string, unknown>).opId = '';
    expect(parseHookMessage(JSON.stringify(noOpId)).ok).toBe(false);

    const noKey = JSON.parse(serializeHookMessage(base)) as Record<string, unknown>;
    (noKey.payload as { scope: Record<string, unknown> }).scope = {};
    expect(parseHookMessage(JSON.stringify(noKey)).ok).toBe(false);
  });

  it('未知动作类型拒收', () => {
    const base = op({ kind: 'typing' });
    const bad = JSON.parse(serializeHookMessage(base)) as Record<string, unknown>;
    (bad.payload as { action: Record<string, unknown> }).action = { kind: 'teleport' };
    const parsed = parseHookMessage(JSON.stringify(bad));
    expect(parsed.ok).toBe(false);
  });

  it('msg.op.result 带 messageId 与相册全量 id, 并支持 retryAfterMs', () => {
    const ok = roundTrip(
      makeMessageOpResult({ opId: 'op-1', ok: true, messageId: '99', messageIds: ['99', '100'] }),
    );
    expect(ok.payload).toMatchObject({ ok: true, messageId: '99', messageIds: ['99', '100'] });

    const failed = roundTrip(
      makeMessageOpResult({ opId: 'op-2', ok: false, error: 'flood', retryAfterMs: 26_000 }),
    );
    // retry_after 全值透传, 不在协议层设上限 —— 固定 clamp 会让重试落回 flood 窗口。
    expect(failed.payload).toMatchObject({ ok: false, retryAfterMs: 26_000 });
  });

  it('老端按未知类型拒收整帧(丢帧不断连)', () => {
    const frame = JSON.parse(serializeHookMessage(op({ kind: 'typing' }))) as Record<
      string,
      unknown
    >;
    frame.type = 'msg.op.future-verb';
    const parsed = parseHookMessage(JSON.stringify(frame));
    expect(parsed.ok).toBe(false);
    if (!parsed.ok) expect(parsed.error).toContain('unknown message type');
  });
});

/** 拿一帧合法信封换掉 payload(只让 payload 本身决定解析结果)。 */
function withPayload(message: HookMessage, payload: Record<string, unknown>): string {
  const frame = JSON.parse(serializeHookMessage(message)) as Record<string, unknown>;
  frame.payload = payload;
  return JSON.stringify(frame);
}

describe('telegram-progress-ops-v1: 进度消息由客户端渲染、经 msg.op 驱动', () => {
  it('能力标识与服务端同名', () => {
    expect(HOOK_FEATURE_TELEGRAM_PROGRESS_OPS).toBe('telegram-progress-ops-v1');
  });

  it('purpose=turn-progress 的 send / edit 原样 round-trip', () => {
    for (const action of [
      { kind: 'send', text: '<b>x</b>', tier: 'html', silent: true },
      { kind: 'edit', messageId: '9', text: 'x', tier: 'plain' },
    ] as MessageOpAction[]) {
      const parsed = roundTrip(
        makeMessageOp({ opId: 'req-1:progress:x', requestId: 'req-1', scope: SCOPE, action, purpose: 'turn-progress' }),
      );
      expect(parsed.payload).toMatchObject({ purpose: 'turn-progress', requestId: 'req-1', action });
    }
  });

  it('purpose 缺 requestId、用在非 send/edit、或取未知值一律拒收', () => {
    const cases: Array<Record<string, unknown>> = [
      { opId: 'a', scope: SCOPE, purpose: 'turn-progress', action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-progress', action: { kind: 'react', targetMessageId: '1', emoji: '' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'final', action: { kind: 'send', text: 'x' } },
      // 继承属性名不能当成合法 purpose(查表只认自有键), 也不能让解析器抛异常。
      ...['constructor', '__proto__', 'toString', 'hasOwnProperty'].map((purpose) => ({
        opId: 'a',
        requestId: 'r',
        scope: SCOPE,
        purpose,
        action: { kind: 'send', text: 'x' },
      })),
    ];
    for (const payload of cases) {
      const parsed = parseHookMessage(withPayload(op({ kind: 'typing' }), payload));
      expect(parsed.ok).toBe(false);
    }
  });

  it('不带 purpose 的 msg.op 与本能力出现前逐字相同(老帧照常解析)', () => {
    const parsed = roundTrip(op({ kind: 'send', text: 'x' }));
    expect((parsed.payload as { purpose?: unknown }).purpose).toBeUndefined();
  });

  it('msg.op.result 的 errorCode / channelErrorCode 可选; 类型错误拒收', () => {
    const channel = roundTrip(
      makeMessageOpResult({ opId: 'o', ok: false, error: "Bad Request: can't parse entities", channelErrorCode: 400 }),
    );
    expect(channel.payload).toMatchObject({ channelErrorCode: 400 });
    const server = roundTrip(
      makeMessageOpResult({ opId: 'o', ok: false, errorCode: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE, channelErrorCode: null }),
    );
    expect(server.payload).toMatchObject({ errorCode: 'PROGRESS_UNAVAILABLE', channelErrorCode: null });
    expect(MESSAGE_OP_ERROR_OUTCOME_UNKNOWN).toBe('OUTCOME_UNKNOWN');
    for (const bad of [{ errorCode: '' }, { errorCode: 3 }, { channelErrorCode: '400' }, { channelErrorCode: 4.5 }]) {
      const parsed = parseHookMessage(
        withPayload(makeMessageOpResult({ opId: 'o', ok: false }), { opId: 'o', ok: false, ...bad }),
      );
      expect(parsed.ok).toBe(false);
    }
  });
});

describe('telegram 终稿 / 卡片 / 命令菜单由客户端发布', () => {
  const parseOp = (payload: Record<string, unknown>) =>
    parseHookMessage(withPayload(op({ kind: 'typing' }), payload));

  it('能力标识与服务端同名', () => {
    expect([
      HOOK_FEATURE_TELEGRAM_FINAL_OPS,
      HOOK_FEATURE_TELEGRAM_CARD_OPS,
      HOOK_FEATURE_TELEGRAM_COMMANDS,
    ]).toEqual(['telegram-final-ops-v1', 'telegram-card-ops-v1', 'telegram-commands-v1']);
  });

  it('turn-final: send / media 带 finalPart round-trip; 缺 finalPart 或用在 edit 拒收', () => {
    const sendFinal = roundTrip(
      makeMessageOp({
        opId: 'r:final:0',
        requestId: 'r',
        scope: SCOPE,
        purpose: 'turn-final',
        finalPart: 0,
        action: { kind: 'send', text: '**答案**', tier: 'rich', effectId: '5107584321108051014' },
      }),
    );
    expect(sendFinal.payload).toMatchObject({ purpose: 'turn-final', finalPart: 0 });
    const media = roundTrip(
      makeMessageOp({
        opId: 'r:final:1',
        requestId: 'r',
        scope: SCOPE,
        purpose: 'turn-final',
        finalPart: 1,
        action: { kind: 'media', album: true, items: [{ name: 'a.png', mimeType: 'image/png', dataBase64: 'AA' }] },
      }),
    );
    expect(media.payload).toMatchObject({ finalPart: 1 });

    for (const payload of [
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-final', action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-final', finalPart: -1, action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-final', finalPart: 0, action: { kind: 'edit', messageId: '1', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, finalPart: 0, action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-progress', finalPart: 0, action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, action: { kind: 'edit', messageId: '1', text: 'x', effectId: 'e' } },
    ]) {
      expect(parseOp(payload).ok).toBe(false);
    }
  });

  it('interaction-card: send 带按钮、收口 edit 清键盘; 缺 interactionId 或错位字段拒收', () => {
    const send = roundTrip(
      makeMessageOp({
        opId: 'r:card:i1:send',
        requestId: 'r',
        scope: SCOPE,
        purpose: 'interaction-card',
        interactionId: 'i1',
        action: {
          kind: 'send',
          text: '<b>🔐 权限请求</b>',
          tier: 'html',
          buttons: [[{ token: 'perm:allow', label: '允许一次' }, { token: 'perm:deny', label: '拒绝' }]],
        },
      }),
    );
    expect(send.payload).toMatchObject({ interactionId: 'i1' });
    const close = roundTrip(
      makeMessageOp({
        opId: 'r:card:i1:close',
        requestId: 'r',
        scope: SCOPE,
        purpose: 'interaction-card',
        interactionId: 'i1',
        interactionClosed: true,
        action: { kind: 'edit', messageId: '9', text: '已拒绝', tier: 'html', buttons: [] },
      }),
    );
    expect(close.payload).toMatchObject({ interactionClosed: true, action: { buttons: [] } });

    for (const payload of [
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'interaction-card', action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'interaction-card', interactionId: 'i', interactionClosed: true, action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, interactionId: 'i', action: { kind: 'send', text: 'x' } },
      { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'interaction-card', interactionId: 'i', action: { kind: 'send', text: 'x', buttons: [[{ token: '', label: 'x' }]] } },
    ]) {
      expect(parseOp(payload).ok).toBe(false);
    }
  });

  it('turn.end.clientFinal 可选; 形状错误拒收', () => {
    const end = (clientFinal?: unknown) =>
      makeTurnEnd({
        requestId: 'r',
        externalKey: SCOPE.externalKey,
        sessionId: null,
        status: 'ok',
        finalText: 'x',
        errorMessage: null,
        usage: { durationMs: 1 },
        ...(clientFinal !== undefined ? { clientFinal: clientFinal as { complete: boolean } } : {}),
      });
    expect(roundTrip(end({ complete: true })).payload).toMatchObject({ clientFinal: { complete: true } });
    expect((roundTrip(end()).payload as { clientFinal?: unknown }).clientFinal).toBeUndefined();
    expect(parseHookMessage(serializeHookMessage(end({ complete: 'yes' }))).ok).toBe(false);
  });

  it('provider.commands.set: 默认菜单必须有且唯一, 命令名与描述遵守 Telegram 限制', () => {
    const ok = makeProviderCommandsSet({
      provider: 'telegram',
      menus: [
        { languageCode: null, commands: [{ command: 'new', description: 'Create a new task' }] },
        { languageCode: 'zh', commands: [{ command: 'new', description: '新建任务' }] },
      ],
    });
    expect(roundTrip(ok).payload).toEqual(ok.payload);
    for (const menus of [
      [{ languageCode: 'zh', commands: [] }],
      [{ languageCode: null, commands: [] }, { languageCode: null, commands: [] }],
      [{ languageCode: null, commands: [{ command: 'New', description: 'x' }] }],
      [{ languageCode: null, commands: [{ command: 'new', description: '' }] }],
      [{ languageCode: 'zh-CN', commands: [] }, { languageCode: null, commands: [] }],
    ]) {
      expect(parseHookMessage(withPayload(ok, { provider: 'telegram', menus })).ok).toBe(false);
    }
  });
});