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。

18.4 KB
Raw Blame
/**
 * generatedFiles — 从一轮回复的 tool_use 消息里派生「本轮 agent 新建的文件」。
 * ---------------------------------------------------------------------------
 * 纯派生、不新增持久化:tool_use 消息本身已落库并原样回放,所以历史会话重开后
 * 这张卡能稳定重建。跨 agent(claude-code / codex / pi)的工具名差异统一交给
 * `describeToolUse` 归一化,不自己维护工具名表:
 *   - kind==='file' 且 action==='create'  → Write / write(claude / pi 新建文件)
 *   - kind==='fileChange' 的 changes 里 action==='add' → codex file_change 新增文件
 *   - kind==='command' → 从命令文本里带明确写出语义的位置提取产物路径候选(source:'command')。
 *     Excel / Word / PDF 等二进制产物只能靠脚本(Bash/exec 跑 python、node)生成,
 *     没有文件工具记录;不补这个盲区,卡在「帮我生成个表格」主场景直接失灵。
 * 「修改已有文件」(edit / update)与读取不算产出(产品口径:只收新建,见
 * AskUserQuestion 决策)。结构化文件工具的 move / delete 同样排除;命令层把明确的
 * copy / move 目标作为候选,用于临时文件落到最终产物路径的场景。
 *
 * 误报防线(source:'command' 特有,由渲染方 GeneratedFilesCard 执行):
 *   命令文本里出现路径 ≠ 命令创建了它(可能只是读输入)。所以只认重定向、save / write
 *   API、输出参数等明确写出位置;候选除存在性外,还必须满足「文件 mtime 落在本轮时间窗内」才出 chip;窗口不可得
 *   (消息无 createdAt / 远程会话无法 stat)时宁可不出。tool 来源保持原判定。
 */

import {
  createdPathsFromDescriptor,
  describeToolUse,
  sourcePathCandidatesFromDescriptor,
} from '@cindy/maker-shared';

import { extractCommandOutputPathCandidates } from '../../shared/commandOutputPaths';
import { resolveToolFilePath } from './localPathResolver';
import { basename } from './utils';

// Keep the public extractor import compatible with existing consumers.
export { extractCommandOutputPathCandidates };

export interface GeneratedFileRef {
  /** 已按 workingDir 解析的绝对路径(用于存在性校验与 chip 打开)。 */
  path: string;
  /** 展示用文件名(basename)。 */
  name: string;
  /**
   * 'tool' = 文件工具结构化新建记录,存在即列;
   * 'command' = 命令文本启发式候选,渲染前还需 mtime 时间窗校验。
   */
  source: 'tool' | 'command';
  /**
   * false = 创建它的 tool_use 还在跑(有 toolUseId、结果未到),文件多半没落盘。
   * 缺省 / true = 可以做存在性检查。历史消息没有 toolUseId 时按已完成处理。
   */
  ready?: boolean;
  /** 文档工具返回的轻量交付信息;普通源码文件没有此字段。 */
  artifact?: DocumentArtifactMetadata;
  /** true 仅表示同一 tool_use 有结构化 ok:true 结果,可用本轮 mtime 证明成功覆盖。 */
  artifactConfirmed?: boolean;
}

export type DocumentArtifactFormat = 'pdf' | 'docx' | 'pptx' | 'xlsx';
export type DocumentArtifactSummary = {
  kind: 'pages' | 'slides' | 'sheets' | 'rows' | 'bytes';
  value: number;
};

export type DocumentArtifactPreview =
  | {
      kind: 'sheet';
      /** 只取工具输入中真实存在的前几行、前几列。 */
      rows: string[][];
      hasHeader: boolean;
    }
  | {
      kind: 'slide';
      /** 封面文字来自第一张幻灯片,不构造示例内容。 */
      title?: string;
      subtitle?: string;
    };

export interface DocumentArtifactMetadata {
  format: DocumentArtifactFormat;
  title?: string;
  subtitle?: string;
  theme?: 'light' | 'dark' | 'navy';
  cover?: boolean;
  summary?: DocumentArtifactSummary;
  preview?: DocumentArtifactPreview;
}

interface ToolUseLike {
  role: string;
  toolName?: string;
  toolInput?: unknown;
  toolUseId?: string;
  content?: string;
}

function documentToolName(toolName: string): string | null {
  const normalized = toolName.replace(/^mcp__/, 'mcp:').replace(/__/g, ':');
  const name = normalized.split(':').at(-1) ?? normalized;
  return /^(make_docx|make_pptx|make_xlsx|render_pdf)$/.test(name) ? name : null;
}

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

/**
 * 只认结构化失败:ok/success=false、status=error/failed,或 `<tool_use_error>`。
 * 普通 Write 失败文案不在这里猜,避免把成功输出误杀。
 */
export function isExplicitFailedToolResult(content: string | undefined): boolean {
  if (!content) return false;
  if (content.includes('<tool_use_error>')) return true;
  const parsed = parseToolResult(content);
  if (!parsed) return false;
  if (parsed.ok === false || parsed.success === false) return true;
  const status = typeof parsed.status === 'string' ? parsed.status.toLowerCase() : '';
  return status === 'error' || status === 'failed' || status === 'failure';
}

function parseToolResult(content: string | undefined): Record<string, unknown> | null {
  if (!content) return null;
  try {
    const parsed = JSON.parse(content) as unknown;
    return asRecord(parsed);
  } catch {
    return null;
  }
}

function stringField(record: Record<string, unknown> | null, key: string): string | undefined {
  const value = record?.[key];
  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
}

function previewCellText(value: unknown): string {
  if (value === null || value === undefined) return '';
  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
    return String(value).slice(0, 48);
  }
  const record = asRecord(value);
  if (record && 'result' in record) return previewCellText(record.result);
  if (record && 'text' in record) return previewCellText(record.text);
  return '';
}

function sheetPreview(input: Record<string, unknown> | null): DocumentArtifactPreview | undefined {
  const firstSheet = asRecord(Array.isArray(input?.sheets) ? input.sheets[0] : null);
  if (!firstSheet) return undefined;
  const header = Array.isArray(firstSheet.header)
    ? firstSheet.header.slice(0, 3).map(previewCellText)
    : [];
  const bodyRows = Array.isArray(firstSheet.rows)
    ? firstSheet.rows
        .slice(0, header.length > 0 ? 3 : 4)
        .filter(Array.isArray)
        .map((row) => row.slice(0, 3).map(previewCellText))
    : [];
  const rows = header.length > 0 ? [header, ...bodyRows] : bodyRows;
  return rows.length > 0 ? { kind: 'sheet', rows, hasHeader: header.length > 0 } : undefined;
}

export function extractDocumentArtifactMetadata(
  toolName: string,
  input: unknown,
  resultContent?: string,
): DocumentArtifactMetadata | undefined {
  const name = documentToolName(toolName);
  if (!name) return undefined;
  const inputRecord = asRecord(input);
  const result = parseToolResult(resultContent);
  // 旧消息可能没有保存 tool_result,仍允许只按输入重建轻量卡片;但只要当前
  // 消息明确带了结果,就必须由 ok:true 证明生成成功。解析失败和 ok:false 都
  // 不能把同轮预先存在的同名文件冒充成这次成功交付的作品。
  if (resultContent !== undefined && result?.ok !== true) return undefined;
  const resultArtifact = asRecord(result?.artifact);
  const format =
    name === 'make_docx'
      ? 'docx'
      : name === 'make_pptx'
        ? 'pptx'
        : name === 'make_xlsx'
          ? 'xlsx'
          : 'pdf';
  const theme =
    stringField(resultArtifact, 'theme') ??
    stringField(result, 'theme') ??
    stringField(inputRecord, 'theme');
  const validTheme = theme === 'light' || theme === 'dark' || theme === 'navy' ? theme : undefined;
  const title =
    stringField(resultArtifact, 'title') ??
    stringField(result, 'title') ??
    stringField(inputRecord, 'title') ??
    (name === 'make_pptx'
      ? stringField(
          asRecord(Array.isArray(inputRecord?.slides) ? inputRecord.slides[0] : null),
          'title',
        )
      : name === 'make_xlsx'
        ? stringField(
            asRecord(Array.isArray(inputRecord?.sheets) ? inputRecord.sheets[0] : null),
            'name',
          )
        : undefined);
  const subtitle =
    stringField(resultArtifact, 'subtitle') ??
    stringField(result, 'subtitle') ??
    stringField(inputRecord, 'subtitle');
  const rawSummary = asRecord(resultArtifact?.summary) ?? asRecord(result?.summary);
  const summaryKind = rawSummary?.kind;
  const summaryValue = rawSummary?.value;
  const summary =
    (summaryKind === 'pages' ||
      summaryKind === 'slides' ||
      summaryKind === 'sheets' ||
      summaryKind === 'rows' ||
      summaryKind === 'bytes') &&
    typeof summaryValue === 'number' &&
    Number.isFinite(summaryValue)
      ? { kind: summaryKind, value: summaryValue }
      : name === 'make_pptx' && Array.isArray(inputRecord?.slides)
        ? { kind: 'slides' as const, value: inputRecord.slides.length }
        : name === 'make_xlsx' && Array.isArray(inputRecord?.sheets)
          ? { kind: 'sheets' as const, value: inputRecord.sheets.length }
          : (name === 'make_docx' || name === 'render_pdf') &&
              typeof result?.bytes === 'number' &&
              Number.isFinite(result.bytes)
            ? { kind: 'bytes' as const, value: result.bytes }
            : undefined;
  const firstSlide =
    name === 'make_pptx'
      ? asRecord(Array.isArray(inputRecord?.slides) ? inputRecord.slides[0] : null)
      : null;
  const preview =
    name === 'make_xlsx'
      ? sheetPreview(inputRecord)
      : name === 'make_pptx'
        ? {
            kind: 'slide' as const,
            ...(stringField(firstSlide, 'title')
              ? { title: stringField(firstSlide, 'title') }
              : {}),
            ...(stringField(firstSlide, 'subtitle')
              ? { subtitle: stringField(firstSlide, 'subtitle') }
              : {}),
          }
        : undefined;
  return {
    format,
    ...(title ? { title } : {}),
    ...(subtitle ? { subtitle } : {}),
    ...(validTheme ? { theme: validTheme } : {}),
    ...(typeof resultArtifact?.cover === 'boolean'
      ? { cover: resultArtifact.cover }
      : typeof inputRecord?.cover === 'boolean'
        ? { cover: inputRecord.cover }
        : {}),
    ...(summary ? { summary: summary as DocumentArtifactSummary } : {}),
    ...(preview ? { preview } : {}),
  };
}

/**
 * 去重 key。**只对 Windows 路径形态**(盘符前缀或含反斜杠)做大小写不敏感折叠——
 * NTFS 上 `A.txt` 与 `a.txt` 是同一文件;POSIX 路径(Linux 本地会话 / 远程 Linux
 * workdir)必须保留原大小写,否则会把两个真实不同的文件错误合并、丢掉一个
 * (PR #1835 review)。macOS 虽默认大小写不敏感,但无法从纯 POSIX 路径形态区分
 * macOS 与 Linux;两害相权取轻:宁可 macOS 偶尔多出一个重复 chip,也不能在 Linux
 * 上丢文件。
 */
function dedupeKeyForPath(abs: string): string {
  const isWindowsShape = /^[a-zA-Z]:[\\/]/.test(abs) || abs.includes('\\');
  if (!isWindowsShape) return abs;
  // 斜杠也归一:`C:/x/a.md`(命令文本常见形态)与 `C:\x\a.md`(Write 记录)是
  // 同一文件,不折叠会重复出 chip。连续分隔符同理折叠:命令文本常是二次转义的
  // 包装串(如 powershell 包一层 node -e),提取出的 `C:\\x\\a.md` 与 `C:\x\a.md`
  // 在 fs 层等价(Windows 归并重复分隔符),不折叠会对同一文件出两个 chip。
  // UNC 头部的 `\\` 是路径语义的一部分,保留。
  return abs
    .replace(/\//g, '\\')
    .replace(/(?<!^)\\{2,}/g, '\\')
    .toLowerCase();
}

/**
 * Windows 形态的绝对路径统一成反斜杠本机形态再往下传:Explorer `/select`
 * (定位)对正斜杠路径静默无反应,`shell.openPath` 在仅用户层文件关联的机器上
 * 对正斜杠也会解析失败(实测「本轮产出」卡 docx chip 打不开的根因)。POSIX
 * 路径原样保留。
 */
function canonicalizeWindowsShape(abs: string): string {
  // 连续分隔符折叠进画布路径本身(不只 dedupe key):stat 虽能容忍 `C:\\x`,但
  // Explorer `/select` 与 chip 展示不该带转义残留。盘符形态不存在 UNC 头,可整段折叠。
  return /^[a-zA-Z]:[\\/]/.test(abs) ? abs.replace(/\//g, '\\').replace(/\\{2,}/g, '\\') : abs;
}


/**
 * 一组消息(通常是一个 turn 的切片,但对任意切片都成立)→ 新建文件的有序去重
 * 列表。路径经 `resolveToolFilePath` 解析成绝对路径;`workingDir` 为空时按原样
 * 保留(与其它 chip 解析同策)。存在性(及 command 候选的 mtime 时间窗)校验由
 * 调用方在渲染前做(异步 IPC)。同一路径同时有 tool 与 command 来源时按 tool 计
 * (tool 是结构化实锤,不该被降级成启发式候选)。
 */
export function collectGeneratedFiles(
  messages: readonly ToolUseLike[],
  workingDir: string,
): GeneratedFileRef[] {
  // The edit/create/command/source passes inspect the same tools. Parse each
  // descriptor once even on a cold history mount (command parsing is expensive).
  const descriptors = new Map<ToolUseLike, ReturnType<typeof describeToolUse>>();
  const descriptorFor = (message: ToolUseLike) => {
    let descriptor = descriptors.get(message);
    if (!descriptor) {
      descriptor = describeToolUse(message.toolName ?? '', message.toolInput);
      descriptors.set(message, descriptor);
    }
    return descriptor;
  };
  const resultByToolUseId = new Map<string, string>();
  for (const message of messages) {
    if (
      message.role === 'tool_result' &&
      message.toolUseId &&
      typeof message.content === 'string'
    ) {
      resultByToolUseId.set(message.toolUseId, message.content);
    }
  }
  // 第一遍:收「本轮被文件工具**修改**过」的路径。它们是编辑不是新建,命令文本
  // 里再出现也不算产物候选——否则跑测试 / 构建命令引用刚编辑过的源码文件
  // (`vitest run src/x.test.ts`)会被 mtime 窗口放行,把编码会话的改动文件全
  // 误收进卡。read 不排除:agent 生成后回读验证是常见动作,不该反杀真产物。
  const editedKeys = new Set<string>();
  for (const msg of messages) {
    if (msg.role !== 'tool_use' || !msg.toolName) continue;
    const resultContent = msg.toolUseId ? resultByToolUseId.get(msg.toolUseId) : undefined;
    if (msg.toolUseId && resultContent === undefined) continue;
    if (isExplicitFailedToolResult(resultContent)) continue;
    const d = descriptorFor(msg);
    if (d.kind === 'file' && d.action === 'edit' && d.filePath) {
      editedKeys.add(dedupeKeyForPath(resolveToolFilePath(d.filePath, workingDir)));
    } else if (d.kind === 'fileChange') {
      for (const c of d.changes) {
        if (c.action !== 'add' && c.path) {
          editedKeys.add(dedupeKeyForPath(resolveToolFilePath(c.path, workingDir)));
        }
      }
    }
  }

  const byKey = new Map<string, GeneratedFileRef>();
  for (const msg of messages) {
    if (msg.role !== 'tool_use') continue;
    const toolName = msg.toolName ?? '';
    if (!toolName) continue;

    const resultContent = msg.toolUseId ? resultByToolUseId.get(msg.toolUseId) : undefined;
    const toolFailed = isExplicitFailedToolResult(resultContent);
    const toolReady = !msg.toolUseId || resultByToolUseId.has(msg.toolUseId);
    const addPath = (rawPath: string, source: GeneratedFileRef['source']): void => {
      if (toolFailed) return;
      const abs = canonicalizeWindowsShape(resolveToolFilePath(rawPath, workingDir));
      const key = dedupeKeyForPath(abs);
      if (source === 'command' && editedKeys.has(key)) return;
      const prev = byKey.get(key);
      if (prev) {
        if (prev.source === 'command' && source === 'tool') prev.source = 'tool';
        if (toolReady) delete prev.ready;
        return;
      }
      byKey.set(key, {
        path: abs,
        name: basename(abs),
        source,
        ...(toolReady ? {} : { ready: false }),
      });
    };

    for (const rawPath of createdPathsFromDescriptor(descriptorFor(msg))) {
      addPath(rawPath, 'tool');
    }
    const artifact = extractDocumentArtifactMetadata(toolName, msg.toolInput, resultContent);
    if (artifact) {
      const outputPath =
        typeof asRecord(msg.toolInput)?.outPath === 'string'
          ? (asRecord(msg.toolInput)!.outPath as string)
          : undefined;
      if (outputPath) {
        const abs = canonicalizeWindowsShape(resolveToolFilePath(outputPath, workingDir));
        const key = dedupeKeyForPath(abs);
        const existing = byKey.get(key);
        const artifactConfirmed = parseToolResult(resultContent)?.ok === true;
        if (existing) {
          // 同路径第二次文档工具还在跑时,保留第一次已确认的交付,不要用未落地预览覆盖。
          if (!toolReady || toolFailed) {
            /* keep existing */
          } else {
            existing.artifact = artifact;
            if (artifactConfirmed) existing.artifactConfirmed = true;
            delete existing.ready;
          }
        } else {
          byKey.set(key, {
            path: abs,
            name: basename(abs),
            source: 'tool',
            artifact,
            ...(artifactConfirmed ? { artifactConfirmed: true } : {}),
            ...(toolReady ? {} : { ready: false }),
          });
        }
      }
    }
    const descriptor = descriptorFor(msg);
    if (descriptor.kind === 'command' && descriptor.command) {
      for (const rawPath of extractCommandOutputPathCandidates(descriptor.command)) {
        addPath(rawPath, 'command');
      }
    }
    if (descriptor.kind === 'fileChange' && toolReady && !toolFailed) {
      for (const change of descriptor.changes) {
        if ((change.action === 'delete' || change.action === 'move') && change.path) {
          byKey.delete(dedupeKeyForPath(resolveToolFilePath(change.path, workingDir)));
        }
      }
    }
  }

  // 最后一遍:摘掉中间件 —— 本轮产出、但又被本轮另一次产出当素材读走的文件。
  // 典型是自己写的 HTML 设计稿:它先被 Write 出来,再被 render_pdf 渲成 PDF,
  // 两个都进列表的话用户会同时看到设计稿和成品(2026-08-21 实测)。
  // 求交集而不是猜字段名,所以只有真产出过的文件才可能被摘。
  for (const msg of messages) {
    if (msg.role !== 'tool_use' || !msg.toolName) continue;
    const d = descriptorFor(msg);
    for (const raw of sourcePathCandidatesFromDescriptor(d)) {
      byKey.delete(dedupeKeyForPath(canonicalizeWindowsShape(resolveToolFilePath(raw, workingDir))));
    }
  }
  return [...byKey.values()];
}