@steerable/agent-shell 0.6.61 → 0.6.63

package/dist/local-backend/turn-file-selection.js

@@ -0,0 +1,186 @@
+/**
+ * 本轮哪些文件升成交付卡片。
+ *
+ * 证据优先级：生成流程结构化结果 > 最终回复引用 > present_files > 文件扫描。
+ * 启发式只纠正没有明确 purpose 的 present_files 和扫描结果；明确标为 output
+ * 的同名 PDF 与幻灯片会同时保留。
+ */
+import path from 'node:path';
+const SOURCE_EXTENSIONS = new Set([
+    '.pptx', '.ppt', '.key', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+    '.docx', '.doc', '.pages',
+    '.xlsx', '.xls', '.xlsm', '.numbers',
+]);
+const PRESENTATION_EXTENSIONS = new Set([
+    '.pptx', '.ppt', '.key', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+]);
+const IMAGE_OR_PDF_EXTENSIONS = new Set([
+    '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg',
+]);
+const RENDER_EXTENSIONS = new Set([
+    '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg',
+    '.html', '.htm', '.csv', '.tsv',
+    '.zip', '.tar', '.gz', '.7z',
+    '.mp4', '.mov', '.mp3', '.epub', '.rtf',
+]);
+const HELPER_EXTENSIONS = new Set([
+    '.mjs', '.js', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.sh', '.rb', '.go', '.rs',
+    '.java', '.css', '.json', '.yml', '.yaml', '.toml',
+]);
+const PREVIEW_NAME = /预览|截图|图像版|preview|screenshot|thumbnail/i;
+/** 没有办公文件时，自动升成卡片的渲染文件上限。再多就交给 present_files 点名。 */
+const AUTO_RENDER_MAX = 4;
+/**
+ * 选出本轮交付卡片的路径。结构化证据不会被文件名启发式覆盖。
+ */
+export function selectDeliverablePaths(files, evidence) {
+    const unique = [];
+    const seen = new Set();
+    for (const file of files) {
+        if (seen.has(file.path))
+            continue;
+        seen.add(file.path);
+        unique.push(file);
+    }
+    const strongest = strongestEvidence(evidence, seen);
+    const explicitOutputs = new Set([...strongest.values()]
+        .filter((item) => item.purpose === 'output')
+        .map((item) => item.path));
+    const excluded = new Set([...strongest.values()]
+        .filter((item) => item.purpose === 'preview' || item.purpose === 'intermediate')
+        .map((item) => item.path));
+    const ambiguousReferences = new Set([...strongest.values()]
+        .filter((item) => item.purpose === undefined)
+        .map((item) => item.path));
+    const sources = unique.filter((file) => isSource(file.path)).map((file) => file.path);
+    const availableSources = sources.filter((item) => !excluded.has(item));
+    const outsideSources = availableSources.filter((item) => !inAgentScratch(item));
+    const sourcePool = outsideSources.length > 0 ? outsideSources : availableSources;
+    let inferred;
+    if (ambiguousReferences.size > 0) {
+        inferred = [...ambiguousReferences].filter((item) => !excluded.has(item) && !isShadow(item, availableSources));
+        const parents = availableSources.filter((source) => [...ambiguousReferences].some((item) => isShadowOf(item, source)));
+        const outsideParents = parents.filter((item) => !inAgentScratch(item));
+        for (const source of outsideParents.length > 0 ? outsideParents : parents) {
+            if (!inferred.includes(source))
+                inferred.push(source);
+        }
+        // 点名的全是脚本或预览、本轮又只有一份办公文件：卡片给那一份，不给脚本。
+        const onlySource = sourcePool.length === 1 ? sourcePool[0] : undefined;
+        if (onlySource &&
+            !inferred.some((item) => isSource(item)) &&
+            [...ambiguousReferences].every((item) => isHelper(item) || isShadow(item, availableSources))) {
+            inferred = [onlySource];
+        }
+        if (inferred.some((item) => isSource(item))) {
+            inferred = inferred.filter((item) => !isHelper(item));
+        }
+        if (inferred.length === 0) {
+            inferred = [...ambiguousReferences].filter((item) => !excluded.has(item));
+        }
+    }
+    else if (explicitOutputs.size > 0) {
+        inferred = [];
+    }
+    else if (sourcePool.length > 0) {
+        inferred = [...sourcePool];
+    }
+    else {
+        inferred = autoRenders(unique.filter((file) => !excluded.has(file.path)));
+    }
+    return new Set([...explicitOutputs, ...inferred]);
+}
+function strongestEvidence(evidence, knownPaths) {
+    const strongest = new Map();
+    for (const item of evidence) {
+        if (!knownPaths.has(item.path))
+            continue;
+        const previous = strongest.get(item.path);
+        if (!previous ||
+            evidenceRank(item.source) > evidenceRank(previous.source) ||
+            (item.source === previous.source &&
+                item.purpose !== undefined &&
+                previous.purpose === undefined)) {
+            strongest.set(item.path, item);
+        }
+    }
+    return strongest;
+}
+function evidenceRank(source) {
+    switch (source) {
+        case 'generation':
+            return 3;
+        case 'final-reference':
+            return 2;
+        case 'present-files':
+            return 1;
+    }
+}
+function autoRenders(files) {
+    const renders = files.filter((file) => isRender(file.path) && !inAgentScratch(file.path));
+    const plain = renders.filter((file) => !previewName(file.path));
+    const pool = plain.length > 0 ? plain : renders;
+    if (pool.length === 0 || pool.length > AUTO_RENDER_MAX)
+        return [];
+    return pool.map((file) => file.path);
+}
+function isShadow(filePath, sources) {
+    return sources.some((source) => isShadowOf(filePath, source));
+}
+/** 预览 PDF / 截图：和幻灯片同干名，或文件名像预览且跟办公文件在同一目录。 */
+function isShadowOf(filePath, sourcePath) {
+    if (filePath === sourcePath || !isSource(sourcePath) || !isRender(filePath))
+        return false;
+    if (stemsMatch(filePath, sourcePath) &&
+        isPresentation(sourcePath) &&
+        isImageOrPdf(filePath)) {
+        return true;
+    }
+    return previewName(filePath) && sameDir(filePath, sourcePath);
+}
+function isSource(filePath) {
+    return SOURCE_EXTENSIONS.has(extensionOf(filePath));
+}
+function isPresentation(filePath) {
+    return PRESENTATION_EXTENSIONS.has(extensionOf(filePath));
+}
+function isImageOrPdf(filePath) {
+    return IMAGE_OR_PDF_EXTENSIONS.has(extensionOf(filePath));
+}
+function isRender(filePath) {
+    return RENDER_EXTENSIONS.has(extensionOf(filePath));
+}
+function isHelper(filePath) {
+    return HELPER_EXTENSIONS.has(extensionOf(filePath));
+}
+function previewName(filePath) {
+    return PREVIEW_NAME.test(path.basename(filePath));
+}
+function extensionOf(filePath) {
+    return path.extname(filePath).toLowerCase();
+}
+function stemsMatch(left, right) {
+    const a = stemKey(left);
+    const b = stemKey(right);
+    return a.length > 0 && a === b;
+}
+function stemKey(filePath) {
+    const base = path.basename(filePath);
+    const ext = path.extname(base);
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    return stem
+        .replace(/预览|截图|图像版/g, '')
+        .replace(/preview|screenshot|thumbnail/gi, '')
+        .replace(/[\s._\-—–()（）【】[\]]+/g, '')
+        .toLowerCase()
+        .normalize('NFC');
+}
+function sameDir(left, right) {
+    return directoryOf(left) === directoryOf(right);
+}
+function directoryOf(filePath) {
+    return path.dirname(filePath).replace(/\\/g, '/').replace(/\/+$/, '').normalize('NFC');
+}
+function inAgentScratch(filePath) {
+    return /(?:^|[/\\])(?:review_work|scripts)(?:[/\\]|$)/i.test(filePath);
+}

package/dist/local-backend/turn-files.d.ts

@@ -1,7 +1,7 @@
 /**
  * 回合产物文件收集（「本轮写了哪些文件」列表）。
  *
- * 四个来源取并集：
+ * 六个来源取并集：
  *
  *  1. 工作区扫描（递归）：回合的可写根（项目根 + 场景包工作区，与 exec
  *     沙箱同源）里 mtime/birthtime ≥ 回合开始时间的文件。覆盖脚本/命令
@@ -16,6 +16,10 @@
  *  4. 命令/代码文本里的绝对路径字面量：exec 命令、snippet 代码中出现的
  *     绝对路径（含 ~/ 前缀与引号包裹形式），stat + 时间水位线验证后并入。
  *     覆盖脚本写到与 cwd 无关的任意位置（如 doc.save('/tmp/x/a.pdf')）。
+ *  5. 生成工具结果的结构化 artifacts：每项明确给出 path 与
+ *     output / preview / intermediate purpose，是交付选择的最高优先级。
+ *  6. 最终回复里的文件引用：Codex file citation、Markdown 本地链接和
+ *     行内代码路径，作为模型最终确认的交付文件。
  *
  * 来源 3/4 都是「猜候选、靠 stat + mtime/birthtime 水位线证伪」：命令里
  * 提到的既有文件（ls /etc/hosts）时间戳旧、不会被误收；不存在的路径
@@ -29,6 +33,7 @@
  * 扫描是有界 best-effort：忽略依赖/构建缓存目录，深度与遍历条目数有硬顶，
  * 超限直接截断返回已收集部分——产物列表是展示面，永远不该拖垮回合收尾。
  */
+import { type DeliveryEvidenceSource } from './turn-file-selection.js';
 export interface TurnFile {
     /** 绝对路径（点击打开直接用）。 */
     path: string;
@@ -40,8 +45,12 @@ export interface TurnFile {
     additions?: number;
     /** 删除行数（展示用，如 -0）。 */
     deletions?: number;
-    /** 类别：deliverable = present_files 声明的最终交付文件；intermediate = 其余本轮写过的文件。 */
+    /** 类别：deliverable = 本轮交付卡片；intermediate = 其余本轮写过的文件。 */
     category?: 'deliverable' | 'intermediate';
+    /** 新回合由后端完成分层证据选择；前端不再二次猜测。 */
+    selection?: 'resolved';
+    /** 成为交付卡片所依据的最高优先级证据。 */
+    deliverySource?: DeliveryEvidenceSource | 'inference';
     /** present_files 给出的一行说明（交付卡片副标题）。 */
     description?: string;
 }
@@ -56,7 +65,10 @@ export interface TurnFileAction {
 export declare const DELIVERABLE_EXTENSIONS: Set<string>;
 /** 是否为临时文件 / 办公软件锁定文件（如 ~$ 开头的文件名），产物列表中一律排除。 */
 export declare function isIgnoredFileName(name: string): boolean;
-/** 判定文件是最终交付文件还是中间修改文件。 */
+/**
+ * 按扩展名做的单文件猜测。回合级取舍在 `selectDeliverablePaths`：
+ * 同名预览不会因为扩展名就和正文一起升成卡片。
+ */
 export declare function classifyFileCategory(filePath: string): 'deliverable' | 'intermediate';
 /** 从统一 diff 文本中统计增删行数。 */
 export declare function parseDiffStats(diffText: string): {
@@ -74,4 +86,6 @@ export declare function collectTurnFiles(options: {
     actions?: readonly TurnFileAction[];
     projectRoot?: string | null;
     homeDir?: string;
+    /** 完整助手回复；其中明确的本地文件链接或行内代码路径属于最终引用。 */
+    finalText?: string;
 }): Promise<TurnFile[]>;

package/dist/local-backend/turn-files.js

@@ -1,7 +1,7 @@
 /**
  * 回合产物文件收集（「本轮写了哪些文件」列表）。
  *
- * 四个来源取并集：
+ * 六个来源取并集：
  *
  *  1. 工作区扫描（递归）：回合的可写根（项目根 + 场景包工作区，与 exec
  *     沙箱同源）里 mtime/birthtime ≥ 回合开始时间的文件。覆盖脚本/命令
@@ -16,6 +16,10 @@
  *  4. 命令/代码文本里的绝对路径字面量：exec 命令、snippet 代码中出现的
  *     绝对路径（含 ~/ 前缀与引号包裹形式），stat + 时间水位线验证后并入。
  *     覆盖脚本写到与 cwd 无关的任意位置（如 doc.save('/tmp/x/a.pdf')）。
+ *  5. 生成工具结果的结构化 artifacts：每项明确给出 path 与
+ *     output / preview / intermediate purpose，是交付选择的最高优先级。
+ *  6. 最终回复里的文件引用：Codex file citation、Markdown 本地链接和
+ *     行内代码路径，作为模型最终确认的交付文件。
  *
  * 来源 3/4 都是「猜候选、靠 stat + mtime/birthtime 水位线证伪」：命令里
  * 提到的既有文件（ls /etc/hosts）时间戳旧、不会被误收；不存在的路径
@@ -32,7 +36,9 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { PRESENT_FILES_TOOL_NAME, readPresentedArgs, } from '../present-files.js';
+import { fileURLToPath } from 'node:url';
+import { PRESENT_FILES_TOOL_NAME, readPresentedArgs, resolvePresentedPath, } from '../present-files.js';
+import { selectDeliverablePaths, } from './turn-file-selection.js';
 /** 这些目录要么体量巨大（node_modules/target），要么是框架内部状态（.steerable），扫了只有噪音。 */
 const IGNORED_DIR_NAMES = new Set([
     'node_modules',
@@ -81,7 +87,10 @@ export function isIgnoredFileName(name) {
         return true;
     return false;
 }
-/** 判定文件是最终交付文件还是中间修改文件。 */
+/**
+ * 按扩展名做的单文件猜测。回合级取舍在 `selectDeliverablePaths`：
+ * 同名预览不会因为扩展名就和正文一起升成卡片。
+ */
 export function classifyFileCategory(filePath) {
     const normalized = filePath.replace(/\\/g, '/');
     const ext = path.extname(normalized).toLowerCase();
@@ -161,21 +170,55 @@ export async function collectTurnFiles(options) {
         await scanShallow(dir, sinceMs, byPath);
     }
     // present_files 声明的文件：本轮可能没动过（交付已有文件），不受时间水位线
-    // 约束，只要求仍是普通文件。
-    const presented = new Map();
+    // 约束，只要求仍是普通文件。路径按 realpath + NFC 并到扫描结果上，避免
+    // macOS 文件名归一化或 /var 与 /private/var 把同一文件收成两条。
+    const presentedByKey = new Map();
     for (const action of options.actions ?? []) {
         if (action.tool !== PRESENT_FILES_TOOL_NAME || action.success === false)
             continue;
         for (const file of readPresentedArgs(action.arguments, projectRoot, homeDir)) {
-            presented.set(file.path, file);
+            const key = await canonicalFileKey(file.path);
+            const prev = presentedByKey.get(key);
+            if (!prev || (!prev.description && file.description))
+                presentedByKey.set(key, file);
         }
     }
-    for (const file of presented.values()) {
-        if (byPath.has(file.path))
+    for (const [key, file] of presentedByKey) {
+        if (byPath.has(key))
             continue;
         const stat = await statPresentedFile(file.path);
         if (stat)
-            byPath.set(file.path, stat);
+            byPath.set(key, stat);
+    }
+    // 生成工具可在成功结果的 artifacts 数组里直接声明 path + purpose。
+    // 这是最高优先级来源，不用文件名猜主文件与预览文件。
+    const generatedByKey = new Map();
+    for (const action of options.actions ?? []) {
+        if (action.success === false)
+            continue;
+        for (const artifact of readStructuredArtifacts(action.result, projectRoot, homeDir)) {
+            const key = await canonicalFileKey(artifact.path);
+            generatedByKey.set(key, artifact);
+            if (byPath.has(key))
+                continue;
+            const stat = await statPresentedFile(artifact.path);
+            if (stat)
+                byPath.set(key, stat);
+        }
+    }
+    // 最终回复中的 Codex file citation、Markdown 本地链接和行内代码路径是次高
+    // 优先级。它们也可以引用本轮没改过但交付给用户的已有文件。
+    const finalReferencesByKey = new Map();
+    for (const reference of readFinalFileReferences(options.finalText ?? '', projectRoot, homeDir)) {
+        const key = await canonicalFileKey(reference.path);
+        const previous = finalReferencesByKey.get(key);
+        if (!previous || reference.explicitOutput)
+            finalReferencesByKey.set(key, reference);
+        if (byPath.has(key))
+            continue;
+        const stat = await statPresentedFile(reference.path);
+        if (stat)
+            byPath.set(key, stat);
     }
     // 从 actions 中提取增删行数统计（local_edit_file 的 diff 或 local_write_file 的 content）
     const statsByPath = new Map();
@@ -211,23 +254,58 @@ export async function collectTurnFiles(options) {
             }
         }
     }
-    const enriched = [];
-    for (const file of byPath.values()) {
-        const base = path.basename(file.path);
-        if (isIgnoredFileName(base))
+    const visible = [];
+    for (const [key, file] of byPath) {
+        if (isIgnoredFileName(path.basename(file.path)))
             continue;
+        visible.push({ key, file });
+    }
+    const evidence = [];
+    for (const { key, file } of visible) {
+        const generated = generatedByKey.get(key);
+        if (generated) {
+            evidence.push({
+                path: file.path,
+                source: 'generation',
+                purpose: generated.purpose,
+            });
+        }
+        const finalReference = finalReferencesByKey.get(key);
+        if (finalReference) {
+            evidence.push({
+                path: file.path,
+                source: 'final-reference',
+                ...(finalReference.explicitOutput ? { purpose: 'output' } : {}),
+            });
+        }
+        const presented = presentedByKey.get(key);
+        if (presented) {
+            evidence.push({
+                path: file.path,
+                source: 'present-files',
+                ...(presented.purpose ? { purpose: presented.purpose } : {}),
+            });
+        }
+    }
+    const deliverablePaths = selectDeliverablePaths(visible.map(({ file }) => file), evidence);
+    const enriched = [];
+    for (const { key, file } of visible) {
         const stats = statsByPath.get(file.path);
-        const declared = presented.get(file.path);
-        // 本轮有声明时以声明为准；没有声明（旧模型、未调用）才退回扩展名规则。
-        const category = presented.size > 0
-            ? declared
-                ? 'deliverable'
-                : 'intermediate'
-            : classifyFileCategory(file.path);
+        const declared = presentedByKey.get(key);
+        const generated = generatedByKey.get(key);
+        const category = deliverablePaths.has(file.path) ? 'deliverable' : 'intermediate';
+        const deliverySource = category === 'deliverable'
+            ? selectedDeliverySource(key, generatedByKey, finalReferencesByKey, presentedByKey)
+            : undefined;
         enriched.push({
             ...file,
             category,
-            ...(declared?.description ? { description: declared.description } : {}),
+            selection: 'resolved',
+            ...(deliverySource ? { deliverySource } : {}),
+            // 预览被拿掉之后，不把它的说明贴到推断出的可编辑文件上。
+            ...(category === 'deliverable' && (generated?.description || declared?.description)
+                ? { description: generated?.description ?? declared?.description }
+                : {}),
             ...(stats ? { additions: stats.additions, deletions: stats.deletions } : {}),
         });
     }
@@ -268,9 +346,23 @@ async function walk(dir, sinceMs, depth, state, out) {
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
-            out.set(full, file);
+            await putTurnFile(out, file);
+    }
+}
+/** 同一文件的扫描路径和模型声明路径收成一个键。 */
+async function canonicalFileKey(filePath) {
+    try {
+        return (await fs.realpath(filePath)).normalize('NFC');
+    }
+    catch {
+        return path.normalize(filePath).normalize('NFC');
     }
 }
+async function putTurnFile(out, file) {
+    const key = await canonicalFileKey(file.path);
+    if (!out.has(key))
+        out.set(key, file);
+}
 /** stat 一个文件，命中「本轮触碰过」则返回 TurnFile，否则 null。 */
 async function statTurnFile(full, sinceMs) {
     let stat;
@@ -304,6 +396,125 @@ async function statPresentedFile(full) {
         return null;
     return { path: full, kind: 'modified', size: stat.size };
 }
+/**
+ * 生成工具结果的标准产物字段：
+ * `{ artifacts: [{ path, purpose, description? }] }`，sidecar 包装结果也可放在
+ * `data.artifacts`。purpose 必填，避免把没有语义的路径数组冒充可靠证据。
+ */
+function readStructuredArtifacts(result, projectRoot, homeDir) {
+    if (!result || typeof result !== 'object')
+        return [];
+    const record = result;
+    const data = record.data && typeof record.data === 'object'
+        ? record.data
+        : null;
+    const raw = Array.isArray(record.artifacts)
+        ? record.artifacts
+        : Array.isArray(data?.artifacts)
+            ? data.artifacts
+            : [];
+    const artifacts = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const artifact = item;
+        if (typeof artifact.path !== 'string' || !isArtifactPurpose(artifact.purpose))
+            continue;
+        const resolved = resolvePresentedPath(artifact.path, projectRoot, homeDir);
+        if (!resolved)
+            continue;
+        const description = typeof artifact.description === 'string' ? artifact.description.trim() : '';
+        artifacts.push({
+            path: resolved,
+            purpose: artifact.purpose,
+            ...(description ? { description } : {}),
+        });
+    }
+    return artifacts;
+}
+function isArtifactPurpose(value) {
+    return value === 'output' || value === 'preview' || value === 'intermediate';
+}
+function readFinalFileReferences(text, projectRoot, homeDir) {
+    if (!text)
+        return [];
+    const rawPaths = new Map();
+    for (const match of text.matchAll(/:codex-file-citation\{([^}]*)\}/g)) {
+        const attributes = match[1] ?? '';
+        const purpose = directiveAttribute(attributes, 'purpose');
+        const filePath = directiveAttribute(attributes, 'path');
+        if (purpose === 'output' && filePath)
+            rawPaths.set(filePath, true);
+    }
+    for (const match of text.matchAll(/!?\[[^\]]*]\((?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"']*["'])?\)/g)) {
+        const target = match[1] ?? match[2];
+        if (target && !rawPaths.has(target))
+            rawPaths.set(target, false);
+    }
+    for (const match of text.matchAll(/`([^`\n]+)`/g)) {
+        const candidate = match[1]?.trim();
+        if (candidate && looksLikeLocalFileReference(candidate) && !rawPaths.has(candidate)) {
+            rawPaths.set(candidate, false);
+        }
+    }
+    const resolved = new Map();
+    for (const [raw, explicitOutput] of rawPaths) {
+        const decoded = decodeFileReference(raw);
+        if (!decoded || /^(?:https?|data):/i.test(decoded))
+            continue;
+        const filePath = resolvePresentedPath(decoded, projectRoot, homeDir);
+        if (!filePath)
+            continue;
+        const previous = resolved.get(filePath);
+        if (!previous || explicitOutput) {
+            resolved.set(filePath, { path: filePath, explicitOutput });
+        }
+    }
+    return [...resolved.values()];
+}
+function directiveAttribute(attributes, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = new RegExp(`(?:^|\\s)${escaped}=(?:"([^"]*)"|'([^']*)'|([^\\s}]+))`).exec(attributes);
+    return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+function decodeFileReference(raw) {
+    let value = raw.trim();
+    try {
+        value = decodeURIComponent(value);
+    }
+    catch {
+        // 非法百分号不是可靠的文件引用。
+        return null;
+    }
+    if (value.startsWith('file://')) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return value;
+}
+function looksLikeLocalFileReference(value) {
+    if (/^(?:~\/|\/|[A-Za-z]:[\\/])/.test(value))
+        return path.extname(value).length > 1;
+    return (!/^[a-z][a-z0-9+.-]*:/i.test(value) &&
+        /(?:^|[/\\])[^/\\]+\.[A-Za-z0-9]{1,10}$/.test(value));
+}
+function selectedDeliverySource(key, generatedByKey, finalReferencesByKey, presentedByKey) {
+    const generated = generatedByKey.get(key);
+    if (generated?.purpose === 'output')
+        return 'generation';
+    if (generated?.purpose === 'preview' || generated?.purpose === 'intermediate') {
+        return 'inference';
+    }
+    if (finalReferencesByKey.has(key))
+        return 'final-reference';
+    if (presentedByKey.has(key))
+        return 'present-files';
+    return 'inference';
+}
 /** local_edit_file 的 diff：直连结果在顶层，经 sidecar 回流的结果折进 `data`。 */
 function editDiffOf(result) {
     if (!result || typeof result !== 'object')
@@ -340,11 +551,11 @@ async function collectWriteToolPath(action, sinceMs, projectRoot, out) {
         : projectRoot
             ? path.resolve(projectRoot, raw)
             : null;
-    if (!full || out.has(full))
+    if (!full || out.has(await canonicalFileKey(full)))
         return;
     const file = await statTurnFile(full, sinceMs);
     if (file)
-        out.set(full, file);
+        await putTurnFile(out, file);
 }
 /**
  * exec 行动的实际工作目录（与 tool-router / local-executor 的解析规则对齐）：
@@ -394,11 +605,11 @@ async function scanShallow(dir, sinceMs, out) {
         if (entry.isSymbolicLink() || !entry.isFile())
             continue;
         const full = path.join(dir, entry.name);
-        if (out.has(full))
+        if (out.has(await canonicalFileKey(full)))
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
-            out.set(full, file);
+            await putTurnFile(out, file);
     }
 }
 /**
@@ -433,10 +644,10 @@ async function collectPathLiterals(action, sinceMs, homeDir, out) {
         }
     }
     for (const full of candidates) {
-        if (out.has(full))
+        if (out.has(await canonicalFileKey(full)))
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
-            out.set(full, file);
+            await putTurnFile(out, file);
     }
 }

package/dist/present-files.d.ts

@@ -6,6 +6,7 @@
  * 导出副本，所以由模型显式声明。工具只 stat 元数据、不读内容，也不复制
  * 文件——用户打开的是源文件当前版本。
  */
+import type { ArtifactPurpose } from './local-backend/turn-file-selection.js';
 export declare const PRESENT_FILES_TOOL_NAME = "present_files";
 export declare const PRESENT_FILES_SCHEMA: {
     name: string;
@@ -30,6 +31,11 @@ export declare const PRESENT_FILES_SCHEMA: {
                             type: string;
                             description: string;
                         };
+                        purpose: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                        };
                     };
                     required: string[];
                     additionalProperties: boolean;
@@ -43,6 +49,7 @@ export declare const PRESENT_FILES_SCHEMA: {
 export interface PresentedFile {
     path: string;
     description?: string;
+    purpose?: ArtifactPurpose;
 }
 /**
  * 把参数里的路径解析成绝对路径：展开 `~/`，相对路径按项目根解析；

package/dist/present-files.js

@@ -18,8 +18,9 @@ export const PRESENT_FILES_SCHEMA = {
         'When a file you created or updated is an output the user asked to receive ' +
         '(spreadsheet, slide deck, document, report, image, exported archive), call this after writing it ' +
         'and before your final reply, including files produced by scripts or commands. ' +
-        'Do not present helper scripts, scratch files, render previews made only to check your work, ' +
-        'or intermediate exports. Files you write but do not present are still listed to the user as edited files.',
+        'Set purpose="output" for every independent deliverable. If you include a preview or intermediate ' +
+        'file for context, label it purpose="preview" or purpose="intermediate"; those files stay in the ' +
+        'edited-files list. Do not label helper scripts or layout-check screenshots as outputs.',
     mode: 'read',
     inputSchema: {
         type: 'object',
@@ -40,6 +41,11 @@ export const PRESENT_FILES_SCHEMA = {
                             type: 'string',
                             description: 'Optional one-line summary shown on the file card.',
                         },
+                        purpose: {
+                            type: 'string',
+                            enum: ['output', 'preview', 'intermediate'],
+                            description: 'Use output for an independent final deliverable; preview/intermediate never creates a deliverable card.',
+                        },
                     },
                     required: ['path'],
                     additionalProperties: false,
@@ -83,7 +89,16 @@ export function readPresentedArgs(args, projectRoot, homeDir) {
         if (!resolved)
             continue;
         const description = typeof record.description === 'string' ? record.description.trim() : '';
-        out.push({ path: resolved, ...(description ? { description } : {}) });
+        const purpose = record.purpose === 'output' ||
+            record.purpose === 'preview' ||
+            record.purpose === 'intermediate'
+            ? record.purpose
+            : undefined;
+        out.push({
+            path: resolved,
+            ...(description ? { description } : {}),
+            ...(purpose ? { purpose } : {}),
+        });
     }
     return out;
 }