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.2 KB
Raw Blame
import { basenameRemotePath } from './filePreview.js';
import { parseMessageToolUse } from './messageNormalize.js';
import { normalizeDisplayCommand } from './commandDisplay.js';
import {
  commandIntentFromActions,
  commandIntentFromCommand,
  type CommandIntent,
} from './commandIntent.js';

/**
 * 工具调用「人话摘要」共享层(issue #450)。
 *
 * 把 tool_use 的 (toolName, input) 解析成结构化描述符,供桌面端 / 手机端
 * 各自格式化最终文案 —— 桌面端有 4 语言 i18n、手机端是中文硬编码,所以本层
 * 只输出结构化数据,绝不拼接面向用户的句子。
 *
 * 数据来源约定(由 maker-core translator 决定,本层只读):
 * - Claude Code:toolName 为 SDK 原名(Bash/Read/...,MCP 为 `mcp__server__tool`),
 *   input 全量透传;Bash 的 `description` 是模型每次调用填写的一句话描述。
 * - Codex:shell 工具 toolName='exec'(input 无 description,`displayCommand`
 *   是解包 POSIX / PowerShell wrapper 后的展示命令);MCP 为 `mcp:server:tool`,另有
 *   `dynamic:ns:tool` / `collab:tool` / `web_search`。
 * - pi:内置工具名全小写(bash/read/edit/write/grep/find/ls),文件参数字段为
 *   `path`(fileDescriptor 已双认 file_path/path);bash 无 description 字段,
 *   桥接 MCP 复用 Codex 的 `mcp:server:tool` 形态,保留 server 中的双下划线。
 */

// ── 工具名拆解 ───────────────────────────────────────────────────────────────

export type ParsedToolName =
  | { kind: 'plain'; name: string }
  | { kind: 'mcp'; server: string; tool: string }
  | { kind: 'dynamic'; namespace?: string; tool: string }
  | { kind: 'collab'; tool: string };

/**
 * 拆解 MCP / dynamic / collab 工具名。
 *
 * - `mcp__server__tool`(Claude Code):去前缀后按双下划线切,首段是 server,
 *   其余段用 `__` 重接为 tool —— server 自身含单下划线(如 orca_worker_bridge)
 *   不受影响。
 * - `mcp:server:tool`(Codex):按冒号切,tool 段可再含冒号。
 * - 段数不足(拆不出 server + tool)时降级 plain,按原名展示。
 */
export function parseToolName(toolName: string): ParsedToolName {
  if (toolName.startsWith('mcp__')) {
    const segments = toolName.slice('mcp__'.length).split('__');
    if (segments.length >= 2 && segments[0]) {
      const tool = segments.slice(1).join('__');
      if (tool) return { kind: 'mcp', server: segments[0], tool };
    }
    return { kind: 'plain', name: toolName };
  }
  if (toolName.startsWith('mcp:')) {
    const segments = toolName.split(':');
    if (segments.length >= 3 && segments[1]) {
      const tool = segments.slice(2).join(':');
      if (tool) return { kind: 'mcp', server: segments[1], tool };
    }
    return { kind: 'plain', name: toolName };
  }
  if (toolName.startsWith('dynamic:')) {
    const segments = toolName.split(':');
    if (segments.length >= 3 && segments[1] && segments.slice(2).join(':')) {
      return { kind: 'dynamic', namespace: segments[1], tool: segments.slice(2).join(':') };
    }
    if (segments.length === 2 && segments[1]) {
      return { kind: 'dynamic', tool: segments[1] };
    }
    return { kind: 'plain', name: toolName };
  }
  if (toolName.startsWith('collab:')) {
    const tool = toolName.slice('collab:'.length);
    if (tool) return { kind: 'collab', tool };
    return { kind: 'plain', name: toolName };
  }
  return { kind: 'plain', name: toolName };
}

// ── 工具调用描述符 ───────────────────────────────────────────────────────────

export type ToolUseDescriptor =
  | {
      kind: 'command';
      toolName: string;
      /** 模型填写的一句话人话描述(仅 Claude Code Bash 有;trim 后非空才认)。 */
      description?: string;
      /** 原始命令;缺失时为空串,消费端回退 toolName 展示。 */
      command: string;
      cwd?: string;
      /**
       * 代码解析出的结构化意图(issue #450 codex 支持):codex `commandActions`
       * 优先,其次本地规则表解析命令原文。仅在无模型 description 时计算 ——
       * description 存在时渲染端也不会用到 intent。
       */
      intent?: CommandIntent;
    }
  | {
      kind: 'file';
      toolName: string;
      action: 'read' | 'edit' | 'create';
      filePath: string;
      fileName: string;
    }
  | {
      kind: 'fileChange';
      toolName: string;
      changes: Array<{
        action: 'add' | 'delete' | 'update' | 'move' | 'unknown';
        path: string;
        fileName: string;
        movePath?: string;
        moveFileName?: string;
        diff: string;
      }>;
    }
  | {
      kind: 'search';
      toolName: string;
      mode: 'grep' | 'glob';
      pattern: string;
      path?: string;
      glob?: string;
    }
  | {
      kind: 'web';
      toolName: string;
      mode: 'fetch' | 'search';
      /** fetch = url,search = query。 */
      target: string;
    }
  | { kind: 'todo'; toolName: string }
  | {
      kind: 'task';
      toolName: string;
      description?: string;
      subagentType?: string;
    }
  | {
      kind: 'mcp';
      toolName: string;
      server: string;
      tool: string;
      /** server 原名(不做转换,server 名本身就是标识)。 */
      serverLabel: string;
      /** tool 下划线转空格后的可读形态(read_by_url → read by url)。 */
      toolLabel: string;
      /** 从 input 常见字段里抽出的一段人话细节(截断到 80 字)。 */
      detail?: string;
      /**
       * 这次调用产出的文件路径(按 `outPath` 约定判定,见 mcpOutputPath)。
       *
       * 存在的理由:产物卡此前只认 Write / file_change 两种来源,用 MCP 工具做出来的
       * 文件在结构上根本不算「本轮产物」——`cindy_docs` 做完一份 PPT,对话里只能得到
       * 模型自己写的一行路径,没有卡(2026-08-21 实测)。
       *
       * 判定走约定而不是工具名单:任何 MCP 工具,只要带一个非空字符串 `outPath`,
       * 就按「它在那儿产了个文件」处理。这样新增工具与第三方插件遵循同一约定即可
       * 自动生效,不需要逐个登记。误报由消费端既有的存在性 + 时间窗校验挡掉
       * (文件不存在就不出 chip)。
       */
      createdPath?: string;
      /**
       * 这次调用**读进来当素材**的路径候选(只有它自己也产出文件时才有值)。
       *
       * 「产出 B 的过程中读了 C」⇒ C 是中间件,不是交付物。`render_pdf` 拿一份自己
       * 写的 HTML 渲染成 PDF 就是这个形态:那份 HTML 是设计稿,不该跟成品并排摆给
       * 用户看(2026-08-21 实测,对话里冒出了一张 `q3-summary.html` 卡)。
       *
       * 不猜字段名:input 里的字符串值全部作为候选,由消费端与「本轮真的产出过的
       * 文件」求交集来定。没产出过的字符串自然命不中,误伤不了正文里的普通参数。
       */
      sourceCandidates?: string[];
    }
  | {
      kind: 'dynamic';
      toolName: string;
      namespace?: string;
      tool: string;
      toolLabel: string;
      detail?: string;
    }
  | {
      kind: 'collab';
      toolName: string;
      tool: string;
      toolLabel: string;
      detail?: string;
    }
  | { kind: 'generic'; toolName: string; detail?: string };

/** pi `edit` 的一段定向替换。 */
export interface PiEditReplacement {
  oldText: string;
  newText: string;
}

/**
 * 归一化 pi `edit` 工具的替换段。
 *
 * pi v0.83.0 的 `edit` 有**两种**入参形态,展示层必须都认(`edit.ts` 的
 * `editSchema` 与 `LegacyEditToolInput` / `normalizeEditInput`):
 *  - 声明 schema(模型被要求产出的形态):`{ path, edits: [{ oldText, newText }] }`;
 *  - legacy 顶层单段:`{ path, oldText, newText }` —— pi 自己仍接受并归一化。
 *
 * 顺序与 pi 的 `normalizeEditInput` 对齐:先取 `edits[]`,再把顶层
 * `oldText`/`newText`(两者都是字符串才认)作为**最后一段**追加。只认其中之一
 * 会让另一种形态退化成空 diff 与 `+0 -0`。
 */
export function piEditReplacements(input: unknown): PiEditReplacement[] {
  const inp = readRecord(input);
  if (!inp) return [];
  const out: PiEditReplacement[] = [];
  if (Array.isArray(inp.edits)) {
    for (const raw of inp.edits) {
      const rec = readRecord(raw);
      // 单段内只要有一侧是字符串就成段(另一侧按空串),纯增/纯删才不会被丢掉。
      const oldText = typeof rec?.oldText === 'string' ? rec.oldText : undefined;
      const newText = typeof rec?.newText === 'string' ? rec.newText : undefined;
      if (oldText === undefined && newText === undefined) continue;
      out.push({ oldText: oldText ?? '', newText: newText ?? '' });
    }
  }
  if (typeof inp.oldText === 'string' && typeof inp.newText === 'string') {
    out.push({ oldText: inp.oldText, newText: inp.newText });
  }
  return out;
}

/** 下划线(含双下划线)转空格并收敛连续空白,得到可读的 token。 */
export function humanizeToolToken(token: string): string {
  return token.replace(/_+/g, ' ').replace(/\s+/g, ' ').trim();
}

/** 展示用截断:超出 max 时截到 max-3 并补 `...`(与 payloadSummary 风格一致)。 */
export function truncateToolText(text: string, max: number): string {
  const normalized = text.trim();
  if (normalized.length <= max) return normalized;
  return `${normalized.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
}

/** MCP / dynamic / collab / generic 的 detail 抽取字段优先级。 */
const DETAIL_KEYS = ['description', 'url', 'query', 'path', 'file_path', 'title', 'name', 'prompt'] as const;

const DETAIL_MAX_CHARS = 80;

/**
 * 解析一次工具调用为结构化描述符。
 *
 * 防御约定:input 可能是 null / string / array / 任意残缺对象(老消息、
 * 第三方 MCP、模型漏填),任何分支都不许抛异常 —— 拿不到关键参数时降级
 * generic(文件/搜索/Web 类)或空串回退(command 类)。
 */
export function describeToolUse(toolName: string, input: unknown): ToolUseDescriptor {
  ({ toolName, input } = parseMessageToolUse({ role: 'tool_use', content: { toolName, input } }));
  const inp = readRecord(input);

  const parsed = parseToolName(toolName);
  if (parsed.kind === 'mcp') {
    const createdPath = mcpOutputPath(inp);
    const sourceCandidates = createdPath ? mcpSourceCandidates(inp, createdPath) : [];
    return {
      kind: 'mcp',
      toolName,
      server: parsed.server,
      tool: parsed.tool,
      serverLabel: parsed.server,
      toolLabel: humanizeToolToken(parsed.tool),
      ...withDetail(inp),
      ...(createdPath ? { createdPath } : {}),
      ...(sourceCandidates.length > 0 ? { sourceCandidates } : {}),
    };
  }
  if (parsed.kind === 'dynamic') {
    return {
      kind: 'dynamic',
      toolName,
      ...(parsed.namespace ? { namespace: parsed.namespace } : {}),
      tool: parsed.tool,
      toolLabel: humanizeToolToken(parsed.tool),
      ...withDetail(inp),
    };
  }
  if (parsed.kind === 'collab') {
    return {
      kind: 'collab',
      toolName,
      tool: parsed.tool,
      toolLabel: humanizeToolToken(parsed.tool),
      ...withDetail(inp),
    };
  }

  switch (toolName) {
    // pi 内置 bash 与 Claude Code Bash 同构:input.command 必有,description
    // 仅 CC 会填(pi schema 无此字段,自然走 intent 兜底),共用一条路径。
    case 'Bash':
    case 'bash': {
      const description = readNonEmptyString(inp?.description);
      const command = readNonEmptyString(inp?.command) ?? '';
      // description 缺失(模型漏填 / pi bash 无此字段)才兜底算 intent。
      const intent = description ? undefined : commandIntentFromCommand(command);
      return {
        kind: 'command',
        toolName,
        ...(description ? { description } : {}),
        command,
        ...withCwd(inp),
        ...(intent ? { intent } : {}),
      };
    }
    case 'exec': {
      // codex shell:displayCommand 是解包 wrapper 后的展示命令,优先。
      const rawCommand = readNonEmptyString(inp?.command) ?? '';
      const command = readNonEmptyString(inp?.displayCommand)
        ?? normalizeDisplayCommand(rawCommand)
        ?? rawCommand;
      // codex 官方 commandActions(translator 透传)优先,本地规则解析兜底。
      // 完整命令一并传入:commandActions 采纳前先过同一道形态安全闸
      // (防止 `cat a | tee b` 这类后段副作用绕过,见 commandIntent 注释)。
      const intent =
        commandIntentFromActions(inp?.commandActions, command) ?? commandIntentFromCommand(command);
      return { kind: 'command', toolName, command, ...withCwd(inp), ...(intent ? { intent } : {}) };
    }
    case 'file_change':
      return fileChangeDescriptor(toolName, inp);
    case 'Read':
    case 'read':
    // pi ls 目标是目录,读取语义与 read 同档;path 可缺省(默认当前目录),
    // 缺省时 fileDescriptor 自然降级 generic。
    case 'ls':
      return fileDescriptor(toolName, 'read', inp);
    case 'Edit':
    case 'MultiEdit':
    case 'edit':
      return fileDescriptor(toolName, 'edit', inp);
    case 'Write':
    case 'write':
      return fileDescriptor(toolName, 'create', inp);
    // pi grep/find 与 CC Grep/Glob 同构:pattern 必有,path/glob 可选;
    // find 的 pattern 是 glob 表达式,归 glob 模式。
    case 'Grep':
    case 'Glob':
    case 'grep':
    case 'find': {
      const pattern = readNonEmptyString(inp?.pattern);
      if (!pattern) return genericDescriptor(toolName, inp);
      const path = readNonEmptyString(inp?.path);
      const glob = readNonEmptyString(inp?.glob);
      return {
        kind: 'search',
        toolName,
        mode: toolName === 'Grep' || toolName === 'grep' ? 'grep' : 'glob',
        pattern,
        ...(path ? { path } : {}),
        ...(glob ? { glob } : {}),
      };
    }
    case 'WebFetch': {
      const url = readNonEmptyString(inp?.url);
      if (!url) return genericDescriptor(toolName, inp);
      return { kind: 'web', toolName, mode: 'fetch', target: url };
    }
    case 'WebSearch':
    case 'web_search': {
      const query = readNonEmptyString(inp?.query);
      if (!query) return genericDescriptor(toolName, inp);
      return { kind: 'web', toolName, mode: 'search', target: query };
    }
    case 'TodoWrite':
    case 'update_plan':
      return { kind: 'todo', toolName };
    case 'Task':
    case 'Agent': {
      const description = readNonEmptyString(inp?.description);
      const subagentType = readNonEmptyString(inp?.subagent_type);
      return {
        kind: 'task',
        toolName,
        ...(description ? { description } : {}),
        ...(subagentType ? { subagentType } : {}),
      };
    }
    default:
      return genericDescriptor(toolName, inp);
  }
}

// ── 内部辅助 ────────────────────────────────────────────────────────────────

function fileDescriptor(
  toolName: string,
  action: 'read' | 'edit' | 'create',
  inp: Record<string, unknown> | null,
): ToolUseDescriptor {
  const filePath = readNonEmptyString(inp?.file_path) ?? readNonEmptyString(inp?.path);
  if (!filePath) return genericDescriptor(toolName, inp);
  return {
    kind: 'file',
    toolName,
    action,
    filePath,
    fileName: basenameRemotePath(filePath) || filePath,
  };
}

/**
 * Codex file_change 一次可以携带多个文件;这里只把协议形态收敛成稳定的
 * 展示模型。任一 change 缺关键字段时整次降级 generic,避免 UI 只展示半套
 * 变更而让用户误以为剩余文件没有被修改。
 */
function fileChangeDescriptor(
  toolName: string,
  inp: Record<string, unknown> | null,
): ToolUseDescriptor {
  if (!Array.isArray(inp?.changes) || inp.changes.length === 0) {
    return genericDescriptor(toolName, inp);
  }

  const changes: Extract<ToolUseDescriptor, { kind: 'fileChange' }>['changes'] = [];
  for (const rawChange of inp.changes) {
    const change = readRecord(rawChange);
    const kind = readRecord(change?.kind);
    const path = readNonEmptyString(change?.path);
    const kindType = readNonEmptyString(kind?.type);
    if (!change || !kind || !path || !kindType || typeof change.diff !== 'string') {
      return genericDescriptor(toolName, inp);
    }

    const movePath = readNonEmptyString(kind.move_path)
      ?? readNonEmptyString(kind.movePath)
      ?? readNonEmptyString(change.move_path)
      ?? readNonEmptyString(change.movePath);
    const action = movePath
      ? 'move'
      : kindType === 'add' || kindType === 'delete' || kindType === 'update'
        ? kindType
        : 'unknown';

    changes.push({
      action,
      path,
      fileName: basenameRemotePath(path) || path,
      ...(movePath
        ? {
            movePath,
            moveFileName: basenameRemotePath(movePath) || movePath,
          }
        : {}),
      diff: change.diff,
    });
  }

  return { kind: 'fileChange', toolName, changes };
}

function genericDescriptor(toolName: string, inp: Record<string, unknown> | null): ToolUseDescriptor {
  return { kind: 'generic', toolName, ...withDetail(inp) };
}

function withDetail(inp: Record<string, unknown> | null): { detail?: string } {
  const detail = extractDetail(inp);
  return detail ? { detail } : {};
}

function withCwd(inp: Record<string, unknown> | null): { cwd?: string } {
  const cwd = readNonEmptyString(inp?.cwd);
  return cwd ? { cwd } : {};
}

/**
 * MCP 工具产出文件的约定字段。三种写法都收(camel / snake / 全小写),因为
 * 这条约定要覆盖的不只是内置 server,还有第三方插件自带的工具。
 *
 * 只认参数名,不认工具名:见 `createdPath` 的说明。
 */
const MCP_OUTPUT_PATH_KEYS = ['outPath', 'out_path', 'outputPath', 'output_path'] as const;

function mcpOutputPath(inp: Record<string, unknown> | null): string | undefined {
  if (!inp) return undefined;
  for (const key of MCP_OUTPUT_PATH_KEYS) {
    const value = readNonEmptyString(inp[key]);
    if (value) return value;
  }
  return undefined;
}

/**
 * 产出型调用里可能是「素材路径」的字符串。见 `sourceCandidates` 的说明:
 * 这里只负责把候选捞出来,是不是真素材由消费端与本轮产物集求交集决定。
 *
 * 只看顶层字段,且跳过超长字符串——内联正文(`html`、`markdown`)动辄上千字,
 * 不可能是路径,也不该被拖进比对。
 */
const MCP_SOURCE_CANDIDATE_MAX_CHARS = 512;

function mcpSourceCandidates(
  inp: Record<string, unknown> | null,
  createdPath: string,
): string[] {
  if (!inp) return [];
  const out: string[] = [];
  for (const value of Object.values(inp)) {
    const text = readNonEmptyString(value);
    if (!text || text === createdPath) continue;
    if (text.length > MCP_SOURCE_CANDIDATE_MAX_CHARS) continue;
    out.push(text);
  }
  return out;
}

function extractDetail(inp: Record<string, unknown> | null): string | undefined {
  if (!inp) return undefined;
  for (const key of DETAIL_KEYS) {
    const value = readNonEmptyString(inp[key]);
    if (value) return truncateToolText(value, DETAIL_MAX_CHARS);
  }
  return undefined;
}

/**
 * 一条 tool_use → 它**新建**的文件原始路径(可能为空)。
 *
 * 对话里的产物卡与伙伴作品集是两条独立链路,此前各自抄了一份同样的判定,注释还
 * 互相写着「同口径」——加一种产物来源就得记得改两处,漏一处就是一边有卡一边没有。
 * 判定收在这里一份,两条链路都调它。
 *
 * 只收新建,不收编辑:改过的文件不是本轮产物。存在性、时间窗这些校验各自在消费端做。
 */
/**
 * 一条 tool_use 引用的素材路径候选(只有产出型调用才有)。与
 * `createdPathsFromDescriptor` 配套:两条链路都要把「产出成品时读走的中间件」
 * 从成品列表里摘掉,判定收在这里一份。
 */
export function sourcePathCandidatesFromDescriptor(descriptor: ToolUseDescriptor): string[] {
  return descriptor.kind === 'mcp' ? (descriptor.sourceCandidates ?? []) : [];
}

export function createdPathsFromDescriptor(descriptor: ToolUseDescriptor): string[] {
  if (descriptor.kind === 'file') {
    return descriptor.action === 'create' && descriptor.filePath ? [descriptor.filePath] : [];
  }
  if (descriptor.kind === 'fileChange') {
    return descriptor.changes
      .filter((change) => change.action === 'add' && change.path)
      .map((change) => change.path);
  }
  if (descriptor.kind === 'mcp') {
    return descriptor.createdPath ? [descriptor.createdPath] : [];
  }
  return [];
}

function readRecord(value: unknown): Record<string, unknown> | null {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : null;
}

function readNonEmptyString(value: unknown): string | undefined {
  if (typeof value !== 'string') return undefined;
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : undefined;
}