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。

21.8 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import { parseMessageToolUse } from '../messageNormalize.js';
import {
  createdPathsFromDescriptor,
  describeToolUse,
  humanizeToolToken,
  parseToolName,
  sourcePathCandidatesFromDescriptor,
  piEditReplacements,
  truncateToolText,
} from '../toolUseDescriptor';

describe('parseToolName', () => {
  it('describes persisted Pi MCP wrappers with the same descriptor as direct calls', () => {
    const args = { query: 'card' };
    expect(describeToolUse('cindy_mcp_call_tool', { server: 'custom', tool: 'search', args }))
      .toEqual(describeToolUse('mcp:custom:search', args));
  });
  it.each(['start_team', 'part__tool'])('preserves Pi server boundaries for %s in raw and normalized messages', (tool) => {
    const server = 'cindy_orca__evil';
    const input = { value: 1 };
    const gateway = { server, tool, args: input };
    const normalized = parseMessageToolUse({ role: 'tool_use', toolUseId: 'pi-id', content: {
      toolName: 'cindy_mcp_call_tool', input: gateway,
    } });
    expect(normalized.toolUseId).toBe('pi-id');
    expect(parseToolName(normalized.toolName)).toEqual({ kind: 'mcp', server, tool });
    const expected = describeToolUse(`mcp:${server}:${tool}`, input);
    expect(describeToolUse('cindy_mcp_call_tool', gateway)).toEqual(expected);
    expect(describeToolUse(normalized.toolName, normalized.input)).toEqual(expected);
    expect(parseMessageToolUse({ role: 'tool_use', content: normalized })).toEqual(normalized);
  });

  it('parses Claude Code mcp__server__tool names', () => {
    expect(parseToolName('mcp__feishu__read_by_url')).toEqual({
      kind: 'mcp',
      server: 'feishu',
      tool: 'read_by_url',
    });
  });

  it('keeps single-underscore server names intact (double-underscore split)', () => {
    expect(parseToolName('mcp__orca_worker_bridge__send_to_lead')).toEqual({
      kind: 'mcp',
      server: 'orca_worker_bridge',
      tool: 'send_to_lead',
    });
  });

  it('rejoins extra double-underscore segments into the tool part', () => {
    expect(parseToolName('mcp__server__part_a__part_b')).toEqual({
      kind: 'mcp',
      server: 'server',
      tool: 'part_a__part_b',
    });
  });

  it('parses codex mcp:server:tool names', () => {
    expect(parseToolName('mcp:feishu:read_by_url')).toEqual({
      kind: 'mcp',
      server: 'feishu',
      tool: 'read_by_url',
    });
  });

  it('keeps colons inside the tool part for codex names', () => {
    expect(parseToolName('mcp:s:a:b')).toEqual({ kind: 'mcp', server: 's', tool: 'a:b' });
  });

  it('parses dynamic tool names with and without namespace', () => {
    expect(parseToolName('dynamic:ns:tool')).toEqual({ kind: 'dynamic', namespace: 'ns', tool: 'tool' });
    expect(parseToolName('dynamic:tool')).toEqual({ kind: 'dynamic', tool: 'tool' });
  });

  it('parses collab tool names', () => {
    expect(parseToolName('collab:wait')).toEqual({ kind: 'collab', tool: 'wait' });
  });

  it('falls back to plain for builtin and malformed names', () => {
    expect(parseToolName('Bash')).toEqual({ kind: 'plain', name: 'Bash' });
    expect(parseToolName('')).toEqual({ kind: 'plain', name: '' });
    expect(parseToolName('mcp__')).toEqual({ kind: 'plain', name: 'mcp__' });
    expect(parseToolName('mcp__server')).toEqual({ kind: 'plain', name: 'mcp__server' });
    expect(parseToolName('mcp:server')).toEqual({ kind: 'plain', name: 'mcp:server' });
    expect(parseToolName('dynamic:')).toEqual({ kind: 'plain', name: 'dynamic:' });
    expect(parseToolName('collab:')).toEqual({ kind: 'plain', name: 'collab:' });
  });
});

describe('describeToolUse — command tools', () => {
  it('extracts the Bash description when present', () => {
    expect(describeToolUse('Bash', { command: 'git status', description: '查看工作区状态' })).toEqual({
      kind: 'command',
      toolName: 'Bash',
      description: '查看工作区状态',
      command: 'git status',
    });
  });

  it('omits description when missing, non-string, or blank', () => {
    expect(describeToolUse('Bash', { command: 'ls' })).toEqual({
      kind: 'command',
      toolName: 'Bash',
      command: 'ls',
      intent: { action: 'list' },
    });
    expect(describeToolUse('Bash', { command: 'ls', description: 42 })).not.toHaveProperty('description');
    expect(describeToolUse('Bash', { command: 'ls', description: null })).not.toHaveProperty('description');
    expect(describeToolUse('Bash', { command: 'ls', description: '   ' })).not.toHaveProperty('description');
  });

  it('prefers displayCommand over command for codex exec, never has description', () => {
    expect(
      describeToolUse('exec', { command: 'pwsh -c "git status"', displayCommand: 'git status', cwd: '/repo' }),
    ).toEqual({
      kind: 'command',
      toolName: 'exec',
      command: 'git status',
      cwd: '/repo',
      intent: { action: 'gitStatus' },
    });
    expect(describeToolUse('exec', { command: 'ls -la' })).toEqual({
      kind: 'command',
      toolName: 'exec',
      command: 'ls -la',
      intent: { action: 'list' },
    });
    expect(describeToolUse('exec', { command: "/bin/zsh -lc 'git status'" })).toEqual({
      kind: 'command',
      toolName: 'exec',
      command: 'git status',
      intent: { action: 'gitStatus' },
    });
  });

  it('degrades to an empty command when input is unusable', () => {
    expect(describeToolUse('Bash', null)).toEqual({ kind: 'command', toolName: 'Bash', command: '' });
    expect(describeToolUse('exec', 'oops')).toEqual({ kind: 'command', toolName: 'exec', command: '' });
    expect(describeToolUse('Bash', [1, 2])).toEqual({ kind: 'command', toolName: 'Bash', command: '' });
  });

  it('derives intent from codex commandActions, preferring them over local parsing', () => {
    expect(
      describeToolUse('exec', {
        command: 'grep -n foo src/',
        commandActions: [{ type: 'search', command: 'grep -n foo src/', query: 'foo', path: 'src/' }],
      }),
    ).toMatchObject({ intent: { action: 'search', target: 'foo', path: 'src/' } });
    // commandActions 全是 unknown → 回退本地规则解析。
    expect(
      describeToolUse('exec', {
        command: 'pnpm test',
        commandActions: [{ type: 'unknown', command: 'pnpm test' }],
      }),
    ).toMatchObject({ intent: { action: 'test' } });
  });

  it('applies the safety gate to the unwrapped display command before trusting commandActions', () => {
    const descriptor = describeToolUse('exec', {
      command: "/bin/zsh -lc 'cat README.md | tee important.conf'",
      displayCommand: 'cat README.md | tee important.conf',
      commandActions: [
        { type: 'read', command: 'cat README.md', name: 'README.md', path: '/repo/README.md' },
      ],
    });
    expect(descriptor).toMatchObject({
      kind: 'command',
      command: 'cat README.md | tee important.conf',
    });
    expect(descriptor).not.toHaveProperty('intent');
  });

  it('skips intent computation when the model already wrote a description', () => {
    expect(
      describeToolUse('Bash', { command: 'ls src', description: '看看源码目录' }),
    ).not.toHaveProperty('intent');
  });

  it('omits intent for commands the local parser cannot classify', () => {
    expect(describeToolUse('Bash', { command: 'docker ps' })).not.toHaveProperty('intent');
    expect(describeToolUse('exec', { command: 'rm -rf build' })).not.toHaveProperty('intent');
  });
});

describe('describeToolUse — file tools', () => {
  it('maps Read/Edit/MultiEdit/Write to file actions with basename', () => {
    expect(describeToolUse('Read', { file_path: '/repo/src/app.ts' })).toEqual({
      kind: 'file',
      toolName: 'Read',
      action: 'read',
      filePath: '/repo/src/app.ts',
      fileName: 'app.ts',
    });
    expect(describeToolUse('Edit', { file_path: '/repo/a.ts' })).toMatchObject({ action: 'edit' });
    expect(describeToolUse('MultiEdit', { file_path: '/repo/a.ts' })).toMatchObject({ action: 'edit' });
    expect(describeToolUse('Write', { file_path: '/repo/a.ts' })).toMatchObject({ action: 'create' });
  });

  it('handles Windows separators in fileName', () => {
    expect(describeToolUse('Read', { file_path: 'C:\\repo\\src\\app.ts' })).toMatchObject({
      fileName: 'app.ts',
    });
  });

  it('falls back from file_path to path, then degrades to generic', () => {
    expect(describeToolUse('Read', { path: '/repo/b.ts' })).toMatchObject({ filePath: '/repo/b.ts' });
    expect(describeToolUse('Read', {})).toEqual({ kind: 'generic', toolName: 'Read' });
  });
});

describe('describeToolUse — pi builtin tools (lowercase, path field)', () => {
  it('maps pi bash to command with local intent (schema has no description field)', () => {
    expect(describeToolUse('bash', { command: 'git status' })).toEqual({
      kind: 'command',
      toolName: 'bash',
      command: 'git status',
      intent: { action: 'gitStatus' },
    });
    expect(describeToolUse('bash', { command: 'docker ps' })).toEqual({
      kind: 'command',
      toolName: 'bash',
      command: 'docker ps',
    });
  });

  it('maps pi read/edit/write/ls to file actions via the path field', () => {
    expect(describeToolUse('read', { path: '/repo/src/app.ts' })).toEqual({
      kind: 'file',
      toolName: 'read',
      action: 'read',
      filePath: '/repo/src/app.ts',
      fileName: 'app.ts',
    });
    expect(describeToolUse('edit', {
      path: '/repo/a.ts',
      edits: [{ oldText: 'a', newText: 'b' }],
    })).toMatchObject({ kind: 'file', action: 'edit', fileName: 'a.ts' });
    expect(describeToolUse('write', { path: '/repo/new.ts', content: 'x' })).toMatchObject({
      kind: 'file',
      action: 'create',
      fileName: 'new.ts',
    });
    expect(describeToolUse('ls', { path: '/repo/src' })).toMatchObject({
      kind: 'file',
      action: 'read',
      fileName: 'src',
    });
  });

  it('degrades pi ls without path (defaults to cwd) to generic', () => {
    expect(describeToolUse('ls', {})).toEqual({ kind: 'generic', toolName: 'ls' });
  });

  it('maps pi read/edit/write/ls to file actions regardless of edit input shape', () => {
    // legacy 顶层形态也必须仍然是 file/edit 描述符(路径来自 path)。
    expect(describeToolUse('edit', {
      path: '/repo/a.ts',
      oldText: 'x',
      newText: 'y',
    })).toMatchObject({ kind: 'file', action: 'edit', fileName: 'a.ts' });
  });

  it('maps pi grep to grep-mode and pi find (glob pattern) to glob-mode search', () => {
    expect(describeToolUse('grep', { pattern: 'TODO', path: 'src/', glob: '*.ts' })).toEqual({
      kind: 'search',
      toolName: 'grep',
      mode: 'grep',
      pattern: 'TODO',
      path: 'src/',
      glob: '*.ts',
    });
    expect(describeToolUse('find', { pattern: '**/*.spec.ts' })).toEqual({
      kind: 'search',
      toolName: 'find',
      mode: 'glob',
      pattern: '**/*.spec.ts',
    });
    expect(describeToolUse('grep', {})).toEqual({ kind: 'generic', toolName: 'grep' });
  });
});

describe('describeToolUse — Codex file_change', () => {
  it('normalizes add/update/delete and rename changes', () => {
    expect(describeToolUse('file_change', {
      changes: [
        { path: '/repo/src/new.ts', kind: { type: 'add' }, diff: '+++ b/src/new.ts\n+hello' },
        { path: '/repo/src/app.ts', kind: { type: 'update' }, diff: '-old\n+new' },
        { path: '/repo/src/old.ts', kind: { type: 'delete' }, diff: '-gone' },
        {
          path: '/repo/src/before.ts',
          kind: { type: 'update', move_path: '/repo/src/after.ts' },
          diff: '',
        },
      ],
    })).toEqual({
      kind: 'fileChange',
      toolName: 'file_change',
      changes: [
        {
          action: 'add',
          path: '/repo/src/new.ts',
          fileName: 'new.ts',
          diff: '+++ b/src/new.ts\n+hello',
        },
        {
          action: 'update',
          path: '/repo/src/app.ts',
          fileName: 'app.ts',
          diff: '-old\n+new',
        },
        {
          action: 'delete',
          path: '/repo/src/old.ts',
          fileName: 'old.ts',
          diff: '-gone',
        },
        {
          action: 'move',
          path: '/repo/src/before.ts',
          fileName: 'before.ts',
          movePath: '/repo/src/after.ts',
          moveFileName: 'after.ts',
          diff: '',
        },
      ],
    });
  });

  it('accepts camelCase/top-level move fields and preserves unknown actions', () => {
    expect(describeToolUse('file_change', {
      changes: [
        { path: 'C:\\repo\\a.ts', kind: { type: 'update', movePath: 'C:\\repo\\b.ts' }, diff: '' },
        { path: '/repo/custom.bin', kind: { type: 'chmod' }, diff: '' },
      ],
    })).toMatchObject({
      kind: 'fileChange',
      changes: [
        { action: 'move', fileName: 'a.ts', moveFileName: 'b.ts' },
        { action: 'unknown', fileName: 'custom.bin' },
      ],
    });
  });

  it('degrades the whole call to generic when changes are empty or malformed', () => {
    expect(describeToolUse('file_change', { changes: [] })).toEqual({
      kind: 'generic',
      toolName: 'file_change',
    });
    expect(describeToolUse('file_change', {
      changes: [{ path: '/repo/a.ts', kind: { type: 'update' } }],
    })).toEqual({ kind: 'generic', toolName: 'file_change' });
  });
});

describe('describeToolUse — search / web / todo / task tools', () => {
  it('maps Grep and Glob to search descriptors', () => {
    expect(describeToolUse('Grep', { pattern: 'foo', path: 'src', glob: '*.ts' })).toEqual({
      kind: 'search',
      toolName: 'Grep',
      mode: 'grep',
      pattern: 'foo',
      path: 'src',
      glob: '*.ts',
    });
    expect(describeToolUse('Glob', { pattern: '**/*.md' })).toEqual({
      kind: 'search',
      toolName: 'Glob',
      mode: 'glob',
      pattern: '**/*.md',
    });
    expect(describeToolUse('Grep', {})).toEqual({ kind: 'generic', toolName: 'Grep' });
  });

  it('maps WebFetch / WebSearch / web_search to web descriptors', () => {
    expect(describeToolUse('WebFetch', { url: 'https://x.dev' })).toEqual({
      kind: 'web',
      toolName: 'WebFetch',
      mode: 'fetch',
      target: 'https://x.dev',
    });
    expect(describeToolUse('WebSearch', { query: 'electron ipc' })).toMatchObject({
      mode: 'search',
      target: 'electron ipc',
    });
    expect(describeToolUse('web_search', { query: 'codex' })).toMatchObject({ mode: 'search' });
    expect(describeToolUse('WebFetch', {})).toEqual({
      kind: 'generic',
      toolName: 'WebFetch',
    });
  });

  it('maps TodoWrite / update_plan to todo', () => {
    expect(describeToolUse('TodoWrite', { todos: [] })).toEqual({ kind: 'todo', toolName: 'TodoWrite' });
    expect(describeToolUse('update_plan', null)).toEqual({ kind: 'todo', toolName: 'update_plan' });
  });

  it('extracts Task description and subagent type', () => {
    expect(
      describeToolUse('Task', { description: '搜索代码', subagent_type: 'Explore', prompt: '...' }),
    ).toEqual({ kind: 'task', toolName: 'Task', description: '搜索代码', subagentType: 'Explore' });
    expect(describeToolUse('Task', {})).toEqual({ kind: 'task', toolName: 'Task' });
  });
});

describe('describeToolUse — mcp / dynamic / collab', () => {
  it('builds mcp descriptors with humanized tool label and detail', () => {
    expect(describeToolUse('mcp__feishu__read_by_url', { url: 'https://f.cn/doc' })).toEqual({
      kind: 'mcp',
      toolName: 'mcp__feishu__read_by_url',
      server: 'feishu',
      tool: 'read_by_url',
      serverLabel: 'feishu',
      toolLabel: 'read by url',
      detail: 'https://f.cn/doc',
    });
  });

  it('picks detail by key priority (description first)', () => {
    expect(
      describeToolUse('mcp:jira:query_issues', { query: 'bug', description: '查询未关闭缺陷' }),
    ).toMatchObject({ detail: '查询未关闭缺陷' });
  });

  it('truncates long detail to 80 chars and omits detail for non-record input', () => {
    const long = 'x'.repeat(200);
    const withLong = describeToolUse('mcp__s__t', { description: long });
    expect(withLong).toMatchObject({ detail: `${'x'.repeat(77)}...` });
    expect(describeToolUse('mcp__s__t', null)).not.toHaveProperty('detail');
  });

  it('builds dynamic and collab descriptors', () => {
    expect(describeToolUse('dynamic:ns:do_thing', { query: 'q' })).toEqual({
      kind: 'dynamic',
      toolName: 'dynamic:ns:do_thing',
      namespace: 'ns',
      tool: 'do_thing',
      toolLabel: 'do thing',
      detail: 'q',
    });
    expect(describeToolUse('collab:wait', null)).toEqual({
      kind: 'collab',
      toolName: 'collab:wait',
      tool: 'wait',
      toolLabel: 'wait',
    });
  });
});

describe('describeToolUse — generic fallback', () => {
  it('maps unknown tools to generic with detail extraction', () => {
    expect(describeToolUse('SomethingNew', { description: '做点什么' })).toEqual({
      kind: 'generic',
      toolName: 'SomethingNew',
      detail: '做点什么',
    });
  });

  it('never throws on hostile input shapes', () => {
    for (const input of [null, undefined, 'str', 42, [], { nested: { deep: true } }]) {
      expect(() => describeToolUse('SomethingNew', input)).not.toThrow();
      expect(describeToolUse('SomethingNew', input)).toMatchObject({ kind: 'generic' });
    }
  });
});

describe('helpers', () => {
  it('humanizes underscore tokens', () => {
    expect(humanizeToolToken('read_by_url')).toBe('read by url');
    expect(humanizeToolToken('part_a__part_b')).toBe('part a part b');
  });

  it('truncates display text with ellipsis', () => {
    expect(truncateToolText('short', 10)).toBe('short');
    expect(truncateToolText('a'.repeat(12), 10)).toBe(`${'a'.repeat(7)}...`);
  });
});

describe('piEditReplacements', () => {
  it('reads the declared edits[] shape in order', () => {
    expect(piEditReplacements({
      path: '/repo/a.ts',
      edits: [{ oldText: 'a', newText: 'b' }, { oldText: 'c', newText: 'd' }],
    })).toEqual([
      { oldText: 'a', newText: 'b' },
      { oldText: 'c', newText: 'd' },
    ]);
  });

  it('reads the legacy top-level { oldText, newText } single replacement', () => {
    expect(piEditReplacements({ path: '/repo/a.ts', oldText: 'x', newText: 'y' })).toEqual([
      { oldText: 'x', newText: 'y' },
    ]);
  });

  it('appends the top-level pair after edits[], mirroring pi normalizeEditInput', () => {
    expect(piEditReplacements({
      path: '/repo/a.ts',
      edits: [{ oldText: 'a', newText: 'b' }],
      oldText: 'x',
      newText: 'y',
    })).toEqual([
      { oldText: 'a', newText: 'b' },
      { oldText: 'x', newText: 'y' },
    ]);
  });

  it('keeps pure insert/delete segments and fills the missing side with an empty string', () => {
    expect(piEditReplacements({ edits: [{ newText: 'added' }, { oldText: 'removed' }] })).toEqual([
      { oldText: '', newText: 'added' },
      { oldText: 'removed', newText: '' },
    ]);
  });

  it('ignores unusable input instead of throwing', () => {
    expect(piEditReplacements(null)).toEqual([]);
    expect(piEditReplacements('oops')).toEqual([]);
    expect(piEditReplacements({ path: '/repo/a.ts' })).toEqual([]);
    expect(piEditReplacements({ edits: 'nope' })).toEqual([]);
    expect(piEditReplacements({ edits: [null, 42, {}] })).toEqual([]);
    // 顶层只给一半不成段(pi 自己也要求两侧都是字符串才归一化)。
    expect(piEditReplacements({ oldText: 'x' })).toEqual([]);
    expect(piEditReplacements({ newText: 'y' })).toEqual([]);
  });
});

/**
 * 这组断言的由来是一次真机事故:伙伴用 cindy_docs 做出了一份 8 页 PPT、文件确实
 * 落盘了,但对话里只有模型自己写的一行路径 —— 没有卡,作品集里也没有。原因是
 * 产物判定只认 Write / file_change,MCP 工具做出来的文件在结构上根本不算产物。
 */
describe('MCP 工具的产出文件(outPath 约定)', () => {
  it('带 outPath 的 MCP 调用被算作新建了那个文件', () => {
    const d = describeToolUse('mcp__cindy_docs__make_pptx', {
      slides: [{ layout: 'cover', title: 'Q3' }],
      outPath: 'documents/Q3.pptx',
    });
    expect(d.kind).toBe('mcp');
    expect(createdPathsFromDescriptor(d)).toEqual(['documents/Q3.pptx']);
  });

  it('snake_case / camelCase 的写法都认(第三方插件不必跟我们同一套命名)', () => {
    for (const key of ['out_path', 'outputPath', 'output_path']) {
      const d = describeToolUse('mcp:someserver:export', { [key]: 'out/a.pdf' });
      expect(createdPathsFromDescriptor(d)).toEqual(['out/a.pdf']);
    }
  });

  it('没有 outPath 的 MCP 调用不产出任何路径(读类工具不该冒出卡)', () => {
    const d = describeToolUse('mcp__cindy_docs__read_sheet', { path: 'data.xlsx' });
    expect(createdPathsFromDescriptor(d)).toEqual([]);
  });

  it('Write 与 file_change 的既有判定不变', () => {
    expect(
      createdPathsFromDescriptor(describeToolUse('Write', { file_path: '/tmp/a.txt' })),
    ).toEqual(['/tmp/a.txt']);
    expect(createdPathsFromDescriptor(describeToolUse('Edit', { file_path: '/tmp/a.txt' }))).toEqual(
      [],
    );
  });
});

describe('中间件不算成品(素材候选)', () => {
  it('产出型调用引用的其它路径会被列为素材候选', () => {
    const d = describeToolUse('mcp__cindy_docs__render_pdf', {
      htmlPath: 'tmp/design.html',
      outPath: 'documents/report.pdf',
    });
    expect(sourcePathCandidatesFromDescriptor(d)).toContain('tmp/design.html');
    // 产物本身不会把自己列成素材。
    expect(sourcePathCandidatesFromDescriptor(d)).not.toContain('documents/report.pdf');
  });

  it('内联正文不会被当成路径候选(html/markdown 动辄上千字)', () => {
    const d = describeToolUse('mcp__cindy_docs__render_pdf', {
      html: `<html>${'x'.repeat(2000)}</html>`,
      outPath: 'documents/report.pdf',
    });
    expect(sourcePathCandidatesFromDescriptor(d)).toEqual([]);
  });

  it('不产出文件的调用没有素材候选(读类工具不该反杀任何东西)', () => {
    const d = describeToolUse('mcp__cindy_docs__read_sheet', { path: 'data.xlsx' });
    expect(sourcePathCandidatesFromDescriptor(d)).toEqual([]);
  });
});