@turingflow/agent-kit 0.0.0-stage → 0.1.1

package/dist/server/artifacts.js

@@ -0,0 +1,1061 @@
+/**
+ * agent-kit · 产物（Artifact）管理
+ *
+ * 问题背景：模型用 Write 工具生成的 HTML / Markdown / 图片等「供用户查看的文件」，
+ * 原来会落到任意磁盘位置（如 apps/web/），且模型常在回复里复述真实路径，
+ * 既泄露服务器目录结构，前端也无法直接渲染。
+ *
+ * 本模块提供：
+ *   - 会话隔离目录：<产物根>/.agent/<sessionId>/（选了项目 → 项目根/.agent/；无项目 → ~/.agent/），
+ *     每个会话只能看到自己的产出；
+ *   - 模型只接触虚拟路径 /agent-output/<sessionId>/...，真实目录永不进入模型上下文；
+ *   - 产物登记表（registry）：模型按用户指示写到「任意位置」（如用户指定目录）的文件，
+ *     在执行层登记真实路径后即成为本会话产物——原位置即产物，不复制、不搬移进 .agent；
+ *     用户未指定位置时仍默认落 .agent/<sessionId>（见 buildArtifactPrompt）；
+ *   - 基线/增量扫描：一轮对话后找出新文件，作为产物推给前端；
+ *   - 安全读取：readArtifact 严格限制在 session 目录内与已登记的产物路径上，任何穿越尝试返回 null；
+ *   - 脱敏：redactOutputPaths 抹掉模型可能复述的 /agent-output 标记。
+ */
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createHash, randomUUID } from "node:crypto";
+/** 真实磁盘产物目录名（隐藏目录：选了项目在项目根、无项目在 ~ 下），靠 .gitignore 排除 */
+export const ARTIFACT_DIR_NAME = ".agent";
+/** 模型上下文里的虚拟输出根：模型写文件用 /agent-output/<sessionId>/<name>（保持稳定，不改） */
+export const ARTIFACT_VIRTUAL_ROOT = "/agent-output";
+/** 产物根目录（真实磁盘位置，宿主侧）：无工作区时统一放用户目录 ~/.agent */
+export function artifactRoot() {
+    return path.join(os.homedir(), ARTIFACT_DIR_NAME);
+}
+/**
+ * CodeBuddy CLI 沙箱项目根：<homedir>/.codebuddy/projects/<cwd转写>/。
+ * 模型用 Bash/Python 等工具写文件时，默认落在沙箱会话目录 <project>/<sessionId>/（而非宿主 .agent），
+ * 因此产物收集与读取必须同时覆盖两个位置。转写规则：X:\a\b → x-a-b。
+ * cwdOverride：工作区模式下传工作目录（CLI cwd 已是工作目录，沙箱根随 cwd 变化）；
+ * 目录不存在时返回 null（非 CodeBuddy CLI 环境不启用）。
+ */
+export function sandboxProjectRoot(cwdOverride) {
+    try {
+        const cwd = cwdOverride && cwdOverride.trim() ? cwdOverride.trim() : process.cwd();
+        const m = cwd.match(/^([A-Za-z]):\\(.*)$/);
+        if (!m)
+            return null;
+        const proj = m[1].toLowerCase() + "-" + m[2].split("\\").join("-");
+        const root = path.join(os.homedir(), ".codebuddy", "projects", proj);
+        return existsSync(root) ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 工作区模式下某会话的产物根（<工作区>/.agent）；无工作区返回宿主根 ~/.agent */
+function artifactRootFor(workspaceDir) {
+    return workspaceDir && workspaceDir.trim() ? path.join(workspaceDir.trim(), ARTIFACT_DIR_NAME) : artifactRoot();
+}
+/** 某会话的候选产物目录：产物根/.agent/<sid> + 沙箱 <project>/<sid>（存在时），产物根优先 */
+export function sessionDirCandidates(sessionId, workspaceDir) {
+    const s = sanitizeSessionId(sessionId);
+    const root = artifactRootFor(workspaceDir);
+    const list = [path.join(root, s)];
+    const sb = sandboxProjectRoot(workspaceDir);
+    if (sb)
+        list.push(path.join(sb, s));
+    return list;
+}
+/**
+ * 取会话「基 id」：编辑重发/重新生成时，前端会把发给服务端的 SDK transcript id
+ * 换成 `${sid}_${uuid}`（让 CLI 不加载旧 transcript，见 ChatWindow 的 rt.sdkSid），
+ * 产物目录因此跟着换成一个「分叉目录」。但产物**归属仍是原会话**——前端卡片与
+ * 预览请求一律带基 sid（activeSid）。会话 id 是 UUID 本身不含 '_'，故 '_' 前段即基 id。
+ */
+export function baseSessionId(sessionId) {
+    const s = String(sessionId || "");
+    const i = s.indexOf("_");
+    return i > 0 ? s.slice(0, i) : s;
+}
+/**
+ * 同源分叉目录列表：某基会话下所有 `<base>_<uuid>` 目录（宿主根 + 沙箱根）。
+ *
+ * 为什么需要：模型写文件时用的是当轮真实的 SDK transcript id（编辑重发 = 新 transcript），
+ * 于是文件落在分叉目录里；而读取/列举一律按基会话走。不把分叉目录并进来就会出现
+ * 「卡片在、点开 404」的错觉（文件明明在磁盘上）。按基 id 前缀扫一层目录即可覆盖，
+ * 根目录条目数量级为会话数，可接受。
+ */
+export async function forkSessionDirs(sessionId, workspaceDir) {
+    const base = sanitizeSessionId(baseSessionId(sessionId));
+    const prefix = `${base}_`;
+    const roots = [artifactRootFor(workspaceDir)];
+    const sb = sandboxProjectRoot(workspaceDir);
+    if (sb)
+        roots.push(sb);
+    const out = [];
+    for (const r of roots) {
+        let entries;
+        try {
+            entries = await fs.readdir(r, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && e.name.startsWith(prefix))
+                out.push(path.join(r, e.name));
+        }
+    }
+    return out;
+}
+/** 读取用：基目录候选 + 全部分叉目录（去重，保持「宿主根优先」的既有次序）。 */
+export async function readDirCandidates(sessionId, workspaceDir) {
+    const out = [];
+    for (const d of [...sessionDirCandidates(sessionId, workspaceDir), ...(await forkSessionDirs(sessionId, workspaceDir))]) {
+        if (!out.includes(d))
+            out.push(d);
+    }
+    return out;
+}
+/** 只允许会话 ID 使用安全字符，杜绝路径穿越 */
+export function sanitizeSessionId(s) {
+    const cleaned = String(s || "").replace(/[^a-zA-Z0-9_-]/g, "");
+    return cleaned || "unknown";
+}
+/** 清洗文件名：去除前导分隔符、去除 . 与 .. 段，防穿越；过长截断 */
+export function sanitizeArtifactName(name) {
+    const parts = String(name)
+        .split(/[\\/]+/)
+        .filter((p) => p && p !== "." && p !== "..");
+    return parts.join("/").slice(0, 200) || "file";
+}
+/**
+ * 中间产物目录名（相对会话目录的**第一段**命中即视为中间产物，不向用户展示）：
+ *  - _drafts / _intermediate / _tmp：模型写草稿 / 临时 / 半成品文件的约定目录（见 buildArtifactPrompt）；
+ *  - tool-results：CodeBuddy CLI 沙箱会话目录里的内部工具执行记录（chatcmpl-tool-*-render.txt、
+ *    mcp-web-fetch-*.txt 等），不是用户可见产物；
+ *  - subagents：CLI 子代理（subagent）的 transcript / 结果目录（位于会话目录内 subagents/<id>/），
+ *    同样属于 SDK 内部文件，不是用户交互产物；
+ *  - attachments：**用户上传附件的 staging 目录**（服务端把用户文件复制到 CLI cwd 的
+ *    attachments/<rel>，见 handlers.ts stageVirtualCopy）。用户的文件永远不是模型生成的产物，
+ *    收集/列表必须整体跳过——否则用户截图会出现在「产物」面板里。
+ * 只有会话目录根下（及非保留子目录）的文件才是「最终产物」。
+ * 点开头（隐藏文件/目录）同样视为中间产物，避免 .DS_Store/.gitkeep 之类进入产物列表。
+ */
+export const INTERMEDIATE_DIR_NAMES = new Set(["_drafts", "_intermediate", "_tmp", "tool-results", "subagents", "attachments"]);
+/** 判断一个相对路径是否属于中间产物：第一段命中保留目录名 / 以点开头；
+ *  或**任意路径段**命中 CodeBuddy CLI 内部目录（tool-results / subagents / .codebuddy）——
+ *  subagents/<id>/tool-results/xxx 这类 SDK 内部文件即使不在第一段也必须过滤。 */
+export function isIntermediateRel(rel) {
+    const parts = String(rel).split(/[\\/]+/).filter(Boolean);
+    const first = parts[0] || "";
+    if (first.startsWith(".") || INTERMEDIATE_DIR_NAMES.has(first))
+        return true;
+    return parts.some((p) => p === "tool-results" || p === "subagents" || p === ".codebuddy");
+}
+/** CLI 内部绝对路径判定（registry 登记条目用）：路径任意段命中 tool-results/subagents/.codebuddy
+ *  → CodeBuddy SDK 内部文件，不是用户交互产物，不展示。 */
+export function isCliInternalAbsPath(abs) {
+    return String(abs)
+        .split(/[\\/]+/)
+        .some((p) => p === "tool-results" || p === "subagents" || p === ".codebuddy");
+}
+/* ======================= 产物登记表（registry） =======================
+ * 策略：只要模型创建了文件，无论落在哪个目录都是本会话的输出物，原位置直接展示，
+ * 不复制、不搬移进 .agent。执行层（sdk.ts withArtifactRegistration）在写文件工具
+ * （Write/Edit/MultiEdit/NotebookEdit）获准执行时登记目标真实路径；Bash/Python 等
+ * shell 写入无法可靠解析路径，由工作目录根扫描兜底登记（见 collectWorkFiles）。
+ * 登记条目持久化在 <产物根>/.registry/<sid>.json（点开头隐藏目录，永远不会被
+ * isIntermediateRel / collectArtifacts 当作产物收集）。 */
+/** 登记表目录名（在产物根下，点开头 = 中间产物，不进入产物清单） */
+const REGISTRY_DIR_NAME = ".registry";
+function registryFileFor(sessionId, workspaceDir) {
+    return path.join(artifactRootFor(workspaceDir), REGISTRY_DIR_NAME, sanitizeSessionId(sessionId) + ".json");
+}
+/** 读取会话登记表（损坏/不存在 → 空数组）。
+ *  含编辑重发/重新生成产生的分叉登记表（`<base>_<uuid>`）：模型那一轮写的是分叉
+ *  transcript id，登记项落在分叉登记表里，而读取一律按基会话走 → 必须合并，
+ *  否则「模型写到用户指定目录」的文件会出现同样的卡片 404。 */
+export async function loadRegistry(sessionId, workspaceDir) {
+    const names = [sanitizeSessionId(sessionId)];
+    const base = sanitizeSessionId(baseSessionId(sessionId));
+    if (base !== names[0]) {
+        // 分叉登记表：<base>_<uuid>.json（uuid 段含 '-'，sanitize 后仍保持唯一）
+        const regDir = path.join(artifactRootFor(workspaceDir), REGISTRY_DIR_NAME);
+        let entries;
+        try {
+            entries = await fs.readdir(regDir, { withFileTypes: true });
+        }
+        catch {
+            entries = [];
+        }
+        for (const e of entries) {
+            if (e.isFile() && e.name.startsWith(`${base}_`) && e.name.endsWith(".json"))
+                names.push(e.name.slice(0, -5));
+        }
+    }
+    const merged = [];
+    const seenAbs = new Set();
+    const seenId = new Set();
+    for (const n of names) {
+        let arr;
+        try {
+            arr = JSON.parse(await fs.readFile(registryFileFor(n, workspaceDir), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(arr))
+            continue;
+        for (const e of arr) {
+            if (!e || typeof e !== "object" ||
+                typeof e.id !== "string" ||
+                typeof e.name !== "string" ||
+                typeof e.absPath !== "string")
+                continue;
+            // 同一路径/同一 id 只保留首个（基会话登记表优先，保持原有语义）
+            if (seenAbs.has(e.absPath) || seenId.has(e.id))
+                continue;
+            seenAbs.add(e.absPath);
+            seenId.add(e.id);
+            merged.push(e);
+        }
+    }
+    return merged;
+}
+/** 只读本会话自己的登记表文件（不合并分叉）：读-改-写与落盘必须用本，避免把
+ *  「基 + 全部分叉」的合并结果写回某一个分叉文件，造成登记项跨文件漂移。 */
+async function loadOwnRegistry(sessionId, workspaceDir) {
+    try {
+        const raw = await fs.readFile(registryFileFor(sessionId, workspaceDir), "utf8");
+        const arr = JSON.parse(raw);
+        if (!Array.isArray(arr))
+            return [];
+        return arr.filter((e) => !!e && typeof e === "object" &&
+            typeof e.id === "string" &&
+            typeof e.name === "string" &&
+            typeof e.absPath === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/** 同一会话的读-改-写串行化，避免并行工具登记时覆盖其他文件。 */
+const registryMutations = new Map();
+async function mutateRegistry(sessionId, workspaceDir, update) {
+    const key = registryFileFor(sessionId, workspaceDir);
+    const previous = registryMutations.get(key) ?? Promise.resolve();
+    const operation = previous.catch(() => { }).then(async () => {
+        const entries = await loadOwnRegistry(sessionId, workspaceDir);
+        await update(entries);
+        await saveRegistry(sessionId, entries, workspaceDir);
+    });
+    registryMutations.set(key, operation);
+    try {
+        await operation;
+    }
+    finally {
+        if (registryMutations.get(key) === operation)
+            registryMutations.delete(key);
+    }
+}
+/** 原子替换登记表，读取列表不会看到半截 JSON。 */
+export async function saveRegistry(sessionId, entries, workspaceDir) {
+    let temporary;
+    try {
+        const f = registryFileFor(sessionId, workspaceDir);
+        await fs.mkdir(path.dirname(f), { recursive: true });
+        temporary = `${f}.${randomUUID()}.tmp`;
+        await fs.writeFile(temporary, JSON.stringify(entries), "utf8");
+        await fs.rename(temporary, f);
+    }
+    catch {
+        /* 登记失败不阻塞主流程（产物仅少一次展示机会） */
+    }
+    finally {
+        if (temporary)
+            await fs.unlink(temporary).catch(() => { });
+    }
+}
+/** 把模型工具入参里的路径归一化为真实绝对路径：
+ *  - /agent-output/<sid>/x → <产物根>/<sid>/x（与 pathAliases 同一映射，登记层拿原始入参时自行解析）
+ *  - bash 风格 /d/a/b → D:\a\b（Windows）
+ *  - 相对路径 → 相对执行 cwd 解析
+ *  无法解析返回 null。 */
+export function normalizeArtifactAbsPath(rawPath, workspaceDir, cwd) {
+    let p = String(rawPath ?? "").trim();
+    if (!p)
+        return null;
+    if (p.startsWith(ARTIFACT_VIRTUAL_ROOT + "/")) {
+        const root = workspaceDir && workspaceDir.trim() ? path.join(workspaceDir.trim(), ARTIFACT_DIR_NAME) : artifactRoot();
+        p = path.join(root, p.slice(ARTIFACT_VIRTUAL_ROOT.length + 1).replace(/^[/\\]+/, ""));
+    }
+    else {
+        const m = p.match(/^\/([a-z])\/(.*)$/s);
+        if (m)
+            p = `${m[1].toUpperCase()}:\\${m[2].replace(/\//g, "\\")}`;
+        if (!path.isAbsolute(p))
+            p = path.resolve(cwd && cwd.trim() ? cwd.trim() : process.cwd(), p);
+    }
+    return path.normalize(p);
+}
+/** 极简稳定 hash（djb2 → 8 位 hex），用于任意路径产物的 id 后缀（防同名不同目录冲突） */
+function hash8(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(16).padStart(8, "0").slice(0, 8);
+}
+/**
+ * 登记一个产物路径（幂等：absPath 已登记则跳过）。id 规则：
+ *  - 在会话目录候选内 → 相对会话目录路径（与扫描产物 id 一致，天然去重）；
+ *  - 工作目录根散落文件 → 文件名（与历史 collectWorkFiles id 一致，旧卡片可继续预览）；
+ *  - 其他任意路径（用户指定目录）→ ext-<hash8>-<basename>。
+ */
+export async function registerArtifactPath(sessionId, rawPath, workspaceDir, cwd, origin = "model", before) {
+    try {
+        const abs = normalizeArtifactAbsPath(rawPath, workspaceDir, cwd);
+        if (!abs)
+            return;
+        // CLI 内部文件（tool-results / subagents / .codebuddy 沙箱）不登记为产物：
+        // 只有用户交互产生的文件（模型按用户指示 Write 的目标）才算产出物
+        if (isCliInternalAbsPath(abs))
+            return;
+        // 会话目录内的 attachments/ 子目录是用户上传附件的 staging 区（见 handlers.ts
+        // stageVirtualCopy）：用户的文件永远不是模型生成的产物，模型意外写入此处也不登记。
+        // 覆盖分叉目录：本轮 sid 可能就是 `<base>_<uuid>`（编辑重发），而登记/收集另一侧
+        // 按基会话走，两边候选集不一致会让同一文件在登记与读取时算出不同 id。
+        for (const dir of await readDirCandidates(sessionId, workspaceDir)) {
+            const rel = path.relative(dir, abs);
+            if (rel && !rel.startsWith("..") && !path.isAbsolute(rel) && isIntermediateRel(rel)) {
+                return;
+            }
+        }
+        const base = path.basename(abs);
+        let id = "";
+        for (const dir of await readDirCandidates(sessionId, workspaceDir)) {
+            const rel = path.relative(dir, abs);
+            if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+                id = sanitizeArtifactName(rel.split("\\").join("/"));
+                break;
+            }
+        }
+        // Dedicated session output directories contain generated files, including legacy
+        // outputs created before the registry recorded their creation identity.
+        const inSessionOutput = Boolean(id);
+        if (!id) {
+            const workRoot = workDirRoot(workspaceDir);
+            const relW = path.relative(workRoot, abs);
+            if (relW && !relW.startsWith("..") && !path.isAbsolute(relW) && !relW.includes(path.sep)) {
+                id = sanitizeArtifactName(relW.split("\\").join("/"));
+            }
+            else {
+                id = `ext-${hash8(abs)}-${sanitizeArtifactName(base)}`;
+            }
+        }
+        const initial = before ?? await snapshotFile(abs);
+        await mutateRegistry(sessionId, workspaceDir, (entries) => {
+            const existing = entries.find((e) => e.absPath === abs);
+            if (existing) {
+                if (origin === "model" && existing.origin === "scan") {
+                    existing.origin = "model";
+                    existing.createdBySession = inSessionOutput || initial.exists === false;
+                }
+                return;
+            }
+            entries.push({
+                id, name: base, absPath: abs, type: artifactType(base), lastSeen: false,
+                origin, registeredAt: Date.now(), createdBySession: origin === "model" && (inSessionOutput || initial.exists === false),
+            });
+        });
+    }
+    catch {
+        /* 忽略登记失败 */
+    }
+}
+const MIME = {
+    html: "text/html; charset=utf-8",
+    htm: "text/html; charset=utf-8",
+    md: "text/markdown; charset=utf-8",
+    markdown: "text/markdown; charset=utf-8",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    pdf: "application/pdf",
+    txt: "text/plain; charset=utf-8",
+    json: "application/json; charset=utf-8",
+    csv: "text/csv; charset=utf-8",
+};
+/** 文本/代码类扩展名（可内嵌预览，前端 <pre> 等宽渲染）；html/md/图片/pdf 已在 artifactType 前序分支处理 */
+const TEXT_EXTS = new Set([
+    "txt", "json", "css", "js", "mjs", "cjs", "ts", "tsx", "jsx", "py", "csv",
+    "xml", "yaml", "yml", "toml", "ini", "sh", "bash", "bat", "ps1", "sql",
+    "java", "go", "rs", "c", "cpp", "h", "rb", "php", "vue", "svelte",
+]);
+export function artifactType(name) {
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    if (ext === "html" || ext === "htm")
+        return "html";
+    if (ext === "md" || ext === "markdown")
+        return "markdown";
+    if (["png", "jpg", "jpeg", "gif", "webp", "svg"].includes(ext))
+        return "image";
+    if (ext === "pdf")
+        return "pdf";
+    if (ext === "docx")
+        return "word";
+    if (TEXT_EXTS.has(ext))
+        return "text";
+    return "other";
+}
+export function mimeFor(name) {
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    return MIME[ext] || "application/octet-stream";
+}
+/** 确保会话目录存在并返回其路径（工作区模式下为 <工作区>/.agent/<sid>，无工作区 ~/.agent/<sid>） */
+export async function ensureSessionDir(sessionId, workspaceDir) {
+    const root = artifactRootFor(workspaceDir);
+    const dir = path.join(root, sanitizeSessionId(sessionId));
+    await fs.mkdir(dir, { recursive: true });
+    // 根目录也确保存在（首次）
+    await fs.mkdir(root, { recursive: true });
+    return dir;
+}
+/** 文本 diff 白名单：这些扩展名的文件参与左右内容对比（基线读内容快照、收集带新旧内容）；
+ *  其余（图片/pdf 等二进制）只标记变更类型，不携带内容（前端显示"无法对比"提示）。 */
+const TEXT_DIFF_EXTS = new Set([
+    ...TEXT_EXTS,
+    "txt", "md", "markdown", "json", "css", "js", "mjs", "cjs", "ts", "tsx", "jsx", "py",
+    "html", "htm", "xml", "yaml", "yml", "toml", "sql", "sh", "bat", "svg", "ini", "conf", "log", "csv", "ipynb", "tex",
+]);
+/** 文件是否参与文本 diff（扩展名在白名单内） */
+export function isTextDiffable(name) {
+    const ext = String(name).split(".").pop()?.toLowerCase() ?? "";
+    return TEXT_DIFF_EXTS.has(ext);
+}
+/** 基线内容快照上限：超过此大小的文件视为不可 diff（超大文本/二进制），content 置 null */
+const BASELINE_CONTENT_LIMIT = 512 * 1024;
+/** 工作目录（模型写文件的 cwd）根散落文件纳入产物时的排除表：常见工程配置文件不作为产物展示 */
+const WORK_DIR_EXCLUDE = [
+    /^package\.json$/i, /^package-lock\.json$/i, /^pnpm-(lock\.yaml|workspace\.yaml)$/i,
+    /^yarn\.lock$/i, /^tsconfig.*\.json$/i, /^next\.config\..*$/i, /^vite\.config\..*$/i,
+    /^eslint(\.config)?\..*$/i, /^prettier(\.config)?\..*$/i, /^\.env.*$/i, /^\.gitignore$/i,
+    /^\.npmrc$/i, /^\.gitattributes$/i, /^\.gitmodules$/i, /^LICENSE$/i,
+    // 运行时/工程说明文件：dev server 重写的 *.log、README/CHANGELOG/CONTRIBUTING 均非对话产物
+    /^.*\.log$/i, /^README.*$/i, /^CHANGELOG.*$/i, /^CONTRIBUTING.*$/i,
+    // jsconfig.json：Next.js 可读性配置（tsconfig 的 JS 版），绝不是模型写的产物
+    /^jsconfig\.json$/i,
+];
+/** 模型写文件的工作目录：选了工作区用工作区，否则进程 cwd（模型默认在 cwd 写文件） */
+function workDirRoot(workspaceDir) {
+    return workspaceDir && workspaceDir.trim() ? workspaceDir.trim() : process.cwd();
+}
+/** 工作目录根散落文件候选（仅根目录文件；子目录不扫——避免工程源码/依赖混入产物） */
+async function workFileCandidates(workDir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await fs.readdir(workDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (!e.isFile())
+            continue;
+        if (isIntermediateRel(e.name))
+            continue;
+        if (WORK_DIR_EXCLUDE.some((re) => re.test(e.name)))
+            continue;
+        out.push({ name: e.name, abs: path.join(workDir, e.name) });
+    }
+    return out;
+}
+/**
+ * 把工作目录根**散落文件**登记为产物（幂等），保证列表/预览读原路径即可；不再复制副本进 .agent。
+ *
+ * 关键点：这里登记的文件只作「候选」，origin 一律记 scan —— 它们是工作目录里本来就在的
+ * 工程文件（jsconfig.json、README 之类）。已登记过的路径**不覆盖**原条目，
+ * 免得把 collectArtifacts 判定过的真产物降级成 scan。
+ */
+async function ensureWorkRegistered(workDir, sessionId, workspaceDir) {
+    const registry = await loadRegistry(sessionId, workspaceDir);
+    const byAbs = new Map(registry.map((e) => [e.absPath, e]));
+    for (const f of await workFileCandidates(workDir)) {
+        const abs = path.join(workDir, f.name);
+        if (byAbs.has(abs))
+            continue; // 已登记（模型写的或上一次扫描登记的）→ 沿用原条目
+        await registerArtifactPath(sessionId, abs, workspaceDir, workDir, "scan");
+    }
+}
+/**
+ * 产物表里的登记条目该不该展示：
+ *  - 非工作目录的登记条目（模型按用户指示写到任意位置，origin=model）→ 展示；
+ *  - 工作目录根内 origin=model（模型 Write/Edit 工具显式登记）→ 展示；
+ *  - 工作目录根内 origin=scan（列表兜底扫描登记的工程/外部进程文件）→ 一律不展示。
+ * 不做 mtime 启发式：外部进程（dev server 重写 .log、编辑器改 README）同样会让 mtime
+ * 变新，无法与「模型 shell 写入」可靠区分 → 保守不展示（纯聊天轮次不再凭空冒产物）。
+ */
+async function shouldShowWorkFile(e, workDir) {
+    if (e.createdBySession === false || e.origin === "scan")
+        return false;
+    if (e.createdBySession === true)
+        return true;
+    const resolved = path.resolve(e.absPath);
+    const wd = path.resolve(workDir);
+    if (resolved !== wd && !resolved.startsWith(wd + path.sep))
+        return true; // 非工作目录产物：原逻辑
+    if ((e.origin ?? "scan") !== "scan") {
+        // 历史迁移：早期 collectWorkFiles 未传 origin 时，README/*.log/LICENSE 等工作目录根
+        // 工程文件被误标成 model。命中排除表的一律不展示（模型未来改 README 等也按此处理）。
+        if (WORK_DIR_EXCLUDE.some((re) => re.test(path.basename(resolved))))
+            return false;
+        return true; // 模型工具写的文件：就是产物
+    }
+    return false; // scan 条目（工程脚手架 / 运行时文件）一律不展示
+}
+/** collectArtifacts 用：工作目录根散落文件 → 登记原路径 + 变更（按 w: 基线判断 added/modified）。
+ *  产物即原文件本身（不复制、不搬移）；源文件 mtime/size 与基线一致（未变）则跳过；
+ *  重写（源变）记为 modified，首次为 added。 */
+async function collectWorkFiles(workDir, sessionId, workspaceDir, baseline) {
+    const out = [];
+    for (const f of await workFileCandidates(workDir)) {
+        const key = "w:" + f.name;
+        const stamp = baseline.get(key);
+        try {
+            const ss = await fs.stat(f.abs, { bigint: true });
+            if (stamp && stamp.mtimeNs === ss.mtimeNs && stamp.size === Number(ss.size))
+                continue;
+            // origin 必须显式传 scan：工作目录根散落文件是「工程/外部进程文件」，不是模型工具写的真产物。
+            // 不传会落默认 model → shouldShowWorkFile 放行 → README/dev-restart-out.log 被误当对话产物。
+            await registerArtifactPath(sessionId, f.abs, workspaceDir, workDir, "scan");
+            const change = {
+                id: sanitizeArtifactName(f.name),
+                name: f.name,
+                type: artifactType(f.name),
+                size: Number(ss.size),
+                change: stamp ? "modified" : "added",
+            };
+            if (isTextDiffable(f.name) && Number(ss.size) <= BASELINE_CONTENT_LIMIT) {
+                change.oldContent = stamp?.content ?? null;
+                change.newContent = await fs.readFile(f.abs, "utf8").catch(() => null);
+            }
+            out.push(change);
+        }
+        catch {
+            /* 忽略并发/权限 */
+        }
+    }
+    return out;
+}
+/** 对常见文档保留摘要，即使重写改变 mtime 也能识别内容没有变化。 */
+async function snapshotFile(absPath) {
+    try {
+        const stat = await fs.stat(absPath, { bigint: true });
+        if (!stat.isFile())
+            return { exists: false, mtimeNs: 0n, size: 0, content: null };
+        const size = Number(stat.size);
+        const data = size <= 16 * 1024 * 1024 ? await fs.readFile(absPath).catch(() => null) : null;
+        return {
+            exists: true,
+            mtimeNs: stat.mtimeNs,
+            size,
+            content: data && size <= BASELINE_CONTENT_LIMIT && isTextDiffable(absPath) && !data.includes(0)
+                ? data.toString("utf8") : null,
+            digest: data ? createHash("sha256").update(data).digest("hex") : undefined,
+        };
+    }
+    catch (error) {
+        if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) {
+            return { exists: false, mtimeNs: 0n, size: 0, content: null };
+        }
+        throw error;
+    }
+}
+function sameFile(before, after) {
+    if (!before || before.exists === false || after.exists === false)
+        return false;
+    if (before.digest && after.digest)
+        return before.digest === after.digest;
+    if (before.content != null && after.content != null)
+        return before.content === after.content;
+    return before.mtimeNs === after.mtimeNs && before.size === after.size;
+}
+/**
+ * 基线：记录某会话「开始前」已存在的产物（宿主 + 沙箱两个位置的会话目录，以及产物根下散落文件），
+ * 返回 key（"s:"/"t:" + 文件名）→ 文件戳，用于增量与更新识别。
+ */
+export async function baselineArtifacts(sessionId, workspaceDir) {
+    const map = new Map();
+    const stamp = async (dir, prefix, rel = "") => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const childRel = rel ? `${rel}/${e.name}` : e.name;
+            if (isIntermediateRel(childRel))
+                continue;
+            if (e.isDirectory() && prefix === "s:") {
+                await stamp(path.join(dir, e.name), prefix, childRel);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            try {
+                // 相同虚拟路径的宿主文件优先，与 readArtifact 的读取次序一致。
+                if (!map.has(prefix + childRel))
+                    map.set(prefix + childRel, await snapshotFile(path.join(dir, e.name)));
+            }
+            catch {
+                /* 文件被并发删除等情况忽略 */
+            }
+        }
+    };
+    // 工作目录根散落文件（模型按用户指示写到 cwd，如「放到根目录」）也入基线（w: 前缀），
+    // 用于增量识别（首次 added / 重写 modified）；工程配置/隐藏文件排除
+    const stampWorkDir = async (dir) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (!e.isFile())
+                continue;
+            if (isIntermediateRel(e.name))
+                continue;
+            if (WORK_DIR_EXCLUDE.some((re) => re.test(e.name)))
+                continue;
+            try {
+                map.set("w:" + e.name, await snapshotFile(path.join(dir, e.name)));
+            }
+            catch {
+                /* 忽略 */
+            }
+        }
+    };
+    // 基线覆盖基目录 + 全部分叉目录（编辑重发轮次写的文件也算本会话既有产物，
+    // 否则下一轮会把上一轮的文件全判成 added）
+    for (const dir of await readDirCandidates(sessionId, workspaceDir)) {
+        await stamp(dir, "s:");
+    }
+    await stamp(artifactRootFor(workspaceDir), "t:");
+    await stampWorkDir(workDirRoot(workspaceDir));
+    // 登记在任意目录的既有文件也必须有本轮基线，尤其用于 shell 修改和删除的旧内容。
+    for (const entry of await loadRegistry(sessionId, workspaceDir)) {
+        if (entry.origin === "scan" || isCliInternalAbsPath(entry.absPath))
+            continue;
+        try {
+            map.set("r:" + entry.absPath, await snapshotFile(entry.absPath));
+        }
+        catch { /* 无权读取的文件不影响本轮 */ }
+    }
+    return map;
+}
+/**
+ * 写工具执行前采集：目标文件在本轮编辑前是否已存在 + 文本内容快照（供 diff 旧内容）。
+ * 写入 into（键 = 归一化绝对路径）。同一文件本轮多次编辑只保留首次快照（= 本轮开始前状态）。
+ *
+ * 用途：模型用 Edit/Write 改「已有文件」（如工作区里的工程源码）时，登记表（registry）新建
+ * 条目的 lastSeen 恒为 false，光靠 collectArtifacts 无法区分「新建文件」与「编辑已有文件」，
+ * 会把编辑误判为 added（→ 只进「产物」不进「变更」，且缺旧内容无法 diff）。执行前若文件已存在，
+ * 不存在也保留快照：本轮先 Write 新建再 Edit 时，仍按新建文件归类。
+ */
+export async function capturePreWriteSnapshot(absPath, into) {
+    if (into.has(absPath))
+        return;
+    try {
+        const snapshot = await snapshotFile(absPath);
+        if (!into.has(absPath))
+            into.set(absPath, snapshot);
+    }
+    catch {
+        /* 权限错误不应误判为文件不存在 */
+    }
+}
+/**
+ * 一轮对话结束后收集本轮「变更」（新增、内容更新、删除）：
+ *  - 会话子目录（宿主 .agent 与 CodeBuddy 沙箱两处）里的新文件/更新文件记为变更（added/modified），
+ *    递归扫描子目录（模型常把产物写进 brand-icons/ 等子目录，此前只扫顶层导致卡片缺失）；
+ *  - 中间产物目录（_drafts/、_intermediate/、_tmp/ 及点开头隐藏项）一律不收集，
+ *    只有会话目录根下（及非保留子目录）的文件才作为「最终产物」呈现给用户；
+ *  - 宿主根目录下「散落」的新**文件**（模型忘记带 sessionId 子目录）移入会话子目录，保证隔离；
+ *    **根目录下的目录不做任何搬移/扫描**——它可能是其他会话自己的目录，搬入会造成跨会话产物混入；
+ *  - 同名文件被重新写入（覆盖/更新，mtime 或大小变化）记为 modified；
+ *  - 删除检测：会话子目录内基线存在、本轮结束后磁盘已无 → deleted（根目录散落文件不判，
+ *    它们可能被搬移进会话目录或属其他会话，误判风险高）；
+ *  - 文本文件（isTextDiffable 且 ≤ 上限）携带 oldContent/newContent 供前端左右 diff；
+ *    二进制/超大文件只标记变更类型。
+ * 返回变更清单（新增/修改在前、删除在后，按 id 去重）。id 为相对会话目录的 posix 路径。
+ */
+export async function collectArtifacts(sessionId, baseline, workspaceDir, 
+/** 写工具执行前的目标文件快照（键 = 归一化绝对路径）：区分「编辑已有文件」与「新建文件」并提供 diff 旧内容 */
+preWrite) {
+    const sessionDir = await ensureSessionDir(sessionId, workspaceDir);
+    const root = artifactRootFor(workspaceDir);
+    const found = [];
+    const diskKeys = new Set(); // 本轮结束后磁盘上仍存在的 key（deleted 检测用）
+    /** 递归扫描一个目录；rel 为相对该扫描根的 posix 路径（顶层文件为 ""，子目录为 "sub/"） */
+    const consider = async (dir, prefix, moveTo, rel) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const childRel = rel ? `${rel}/${e.name}` : e.name;
+            const key = prefix + childRel;
+            if (e.isDirectory()) {
+                // 根目录（t:）下的目录一律不搬移、不扫描：它可能是**其他会话自己的目录**
+                //（如另一场对话的 .agent/<sid>/），整体搬进来会造成跨会话产物混入。
+                // 只处理「模型忘记带 sessionId」的散落**文件**；散落子目录属罕见且无法安全归因，留原地即可。
+                if (prefix === "t:")
+                    continue;
+                // 中间产物目录（_drafts/ 等）不进入产物清单
+                if (isIntermediateRel(childRel))
+                    continue;
+                await consider(path.join(dir, e.name), prefix, moveTo, childRel);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            // 中间产物不收集（_drafts/ 下的草稿、点开头隐藏文件）
+            if (isIntermediateRel(childRel))
+                continue;
+            // 文件戳：新增（基线无记录）或内容更新（mtime/大小变化）都算本轮产物
+            const absolutePath = path.join(dir, e.name);
+            const current = await snapshotFile(absolutePath).catch(() => null);
+            if (!current || current.exists === false)
+                continue;
+            if (diskKeys.has(key))
+                continue; // 宿主目录优先，重复虚拟路径只处理一次
+            diskKeys.add(key);
+            const stamp = baseline.get(key);
+            if (sameFile(stamp, current))
+                continue;
+            if (prefix === "t:" && moveTo) {
+                // 散落根目录的文件 → 移入会话子目录，确保跨会话不串
+                const src = path.join(dir, e.name);
+                const dst = path.join(moveTo, sanitizeArtifactName(childRel));
+                try {
+                    await fs.rename(src, dst);
+                }
+                catch {
+                    try {
+                        const buf = await fs.readFile(src);
+                        await fs.writeFile(dst, buf);
+                        await fs.unlink(src);
+                    }
+                    catch {
+                        /* 忽略无法移动的文件 */
+                    }
+                }
+            }
+            const id = sanitizeArtifactName(childRel);
+            const change = {
+                id,
+                name: childRel,
+                type: artifactType(e.name),
+                size: current.size,
+                change: stamp && stamp.exists !== false ? "modified" : "added",
+            };
+            change.oldContent = stamp?.content ?? (change.change === "added" ? "" : null);
+            change.newContent = current.content ?? null;
+            found.push(change);
+            // shell 等工具直接写会话目录时也持久化产出身份，后续 Edit 不会把它误当成用户既有文件。
+            if (change.change === "added") {
+                const trackedPath = prefix === "t:" && moveTo ? path.join(moveTo, id) : absolutePath;
+                await registerArtifactPath(sessionId, trackedPath, workspaceDir, undefined, "model", {
+                    exists: false, mtimeNs: 0n, size: 0, content: null,
+                });
+            }
+        }
+    };
+    // 收集覆盖基目录 + 全部分叉目录：编辑重发/重新生成那一轮，模型写的是分叉
+    // transcript id 的目录，只扫基目录会漏推这一轮的产物卡片。
+    // 本轮 sid 自身对应的目录排在最前（宿主根优先的既有次序不变）。
+    for (const dir of await readDirCandidates(sessionId, workspaceDir)) {
+        await consider(dir, "s:", null, "");
+    }
+    await consider(root, "t:", sessionDir, "");
+    // 工作目录根散落文件（README/.log 等工程或外部进程文件）：只登记（origin=scan），
+    // 不产生本轮变更推送——它们不是对话产物；模型按指示用 Write 写 cwd 根的文件会以
+    // origin=model 走 registry 段正常推送（见下），此处只兜底登记，不做展示。
+    await collectWorkFiles(workDirRoot(workspaceDir), sessionId, workspaceDir, baseline);
+    // 删除检测：会话子目录（s:）内基线存在、磁盘已无 → deleted（t: 散落 / w: 工作目录不判，
+    // 副本保留在会话目录，误判风险高）
+    for (const [key, stamp] of baseline) {
+        if (!key.startsWith("s:") || stamp.exists === false)
+            continue;
+        if (diskKeys.has(key))
+            continue;
+        const id = sanitizeArtifactName(key.slice(2));
+        found.push({
+            id,
+            name: id,
+            type: artifactType(id),
+            size: stamp.size,
+            change: "deleted",
+            oldContent: stamp?.content ?? null,
+        });
+    }
+    // —— 登记产物（模型写到任意位置的文件，见 registerArtifactPath）——
+    // 逐个对比磁盘状态与上次收集戳：编辑已有文件 → modified（带旧内容）；新登记且此前不存在 →
+    // added；戳变化 → modified；上次存在、本次消失 → deleted；登记过但从未写成功 → 忽略（不误报 deleted）。
+    // 「此前是否存在」由执行前快照 preWrite 判定（登记条目 lastSeen 恒 false，单凭它会把编辑误判为 added）。
+    // 登记条目随收集更新 lastSeen/戳并持久化。
+    await mutateRegistry(sessionId, workspaceDir, async (registry) => {
+        for (const e of registry) {
+            // scan 条目（工作目录根工程/外部进程文件）不产生变更推送：只做登记兜底，永不推卡片
+            if (e.origin === "scan")
+                continue;
+            // 有本轮工具追踪时，只将实际观察到的写入归因给 Agent。
+            // 历史登记的工作区文件被编辑器/外部进程改动，不应在纯聊天轮次中冒出变更。
+            if (preWrite && !preWrite.has(e.absPath))
+                continue;
+            // CLI 内部文件（tool-results / subagents / .codebuddy 沙箱）不收集为产物
+            if (isCliInternalAbsPath(e.absPath))
+                continue;
+            if ((await readDirCandidates(sessionId, workspaceDir)).some((dir) => {
+                const rel = path.relative(dir, e.absPath);
+                return rel && !rel.startsWith("..") && !path.isAbsolute(rel) && isIntermediateRel(rel);
+            }))
+                continue;
+            const current = await snapshotFile(e.absPath).catch(() => null);
+            if (!current)
+                continue;
+            const wasSeen = e.lastSeen;
+            const pre = baseline.get("r:" + e.absPath) ?? preWrite?.get(e.absPath);
+            const before = pre ?? (wasSeen && e.mtimeNs != null
+                ? { exists: true, mtimeNs: BigInt(e.mtimeNs), size: e.size ?? 0, content: null } : undefined);
+            if (current.exists === false) {
+                if (before?.exists !== false && (before || wasSeen)) {
+                    found.push({
+                        id: e.id,
+                        name: e.name,
+                        type: e.type,
+                        size: before?.size ?? e.size ?? 0,
+                        change: "deleted",
+                        oldContent: before?.content ?? null,
+                        newContent: "",
+                    });
+                }
+                e.lastSeen = false;
+                e.mtimeNs = undefined;
+                e.size = undefined;
+                continue;
+            }
+            const size = current.size;
+            const mtimeNs = String(current.mtimeNs);
+            const unchanged = sameFile(before, current);
+            e.lastSeen = true;
+            e.mtimeNs = mtimeNs;
+            e.size = size;
+            if (unchanged)
+                continue;
+            const change = {
+                id: e.id,
+                name: e.name,
+                type: e.type,
+                size,
+                change: before && before.exists !== false ? "modified" : "added",
+            };
+            change.oldContent = before?.content ?? (change.change === "added" ? "" : null);
+            change.newContent = current.content ?? null;
+            found.push(change);
+        }
+    });
+    const seen = new Set();
+    return found.filter((a) => (seen.has(a.id) ? false : (seen.add(a.id), true)));
+}
+/**
+ * 列出某会话的全部产物（递归，含非保留子目录），用于「查看所有产物 (N)」按钮与右侧列表面板。
+ * 与 collectArtifacts 不同：不做基线增量，直接返回磁盘上当前存在的全部文件；
+ * 中间产物目录（_drafts/ 等）与隐藏文件不进入列表，只呈现最终产物。
+ * 会话目录不存在时返回空数组。
+ */
+export async function listSessionArtifacts(sessionId, workspaceDir) {
+    const safeSession = sanitizeSessionId(sessionId);
+    const seen = new Set();
+    const out = [];
+    await ensureWorkRegistered(workDirRoot(workspaceDir), sessionId, workspaceDir);
+    const registry = await loadRegistry(sessionId, workspaceDir);
+    const editedOnly = new Set(registry.filter((e) => e.createdBySession === false && e.origin !== "scan").map((e) => e.absPath));
+    const walk = async (dir, rel) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const childRel = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                // 中间产物目录不进入列表（_drafts/ 等草稿目录）
+                if (isIntermediateRel(childRel))
+                    continue;
+                await walk(path.join(dir, e.name), childRel);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            // 中间产物文件（保留目录名 / 点开头隐藏文件）不向用户展示
+            if (isIntermediateRel(childRel))
+                continue;
+            if (editedOnly.has(path.join(dir, e.name)))
+                continue;
+            const stat = await fs
+                .stat(path.join(dir, e.name), { bigint: true })
+                .catch(() => null);
+            if (!stat)
+                continue;
+            const id = sanitizeArtifactName(childRel);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            out.push({
+                id,
+                name: childRel,
+                type: artifactType(e.name),
+                size: Number(stat.size),
+                mtimeMs: Number(stat.mtimeMs),
+                dir,
+            });
+        }
+    };
+    for (const dir of await readDirCandidates(safeSession, workspaceDir)) {
+        await walk(dir, "");
+    }
+    // 登记产物（任意位置创建的文件）：当前仍存在于磁盘的条目并入列表
+    const workDir = workDirRoot(workspaceDir);
+    for (const e of registry) {
+        // CLI 内部文件（tool-results / subagents / .codebuddy 沙箱）不展示
+        if (isCliInternalAbsPath(e.absPath))
+            continue;
+        if ((await readDirCandidates(sessionId, workspaceDir)).some((dir) => {
+            const rel = path.relative(dir, e.absPath);
+            return rel && !rel.startsWith("..") && !path.isAbsolute(rel) && isIntermediateRel(rel);
+        }))
+            continue;
+        // 工作目录根散落文件：登记时刻之前就存在 → 工程脚手架文件，不是本轮产物（不展示）
+        if (!(await shouldShowWorkFile(e, workDir)))
+            continue;
+        if (seen.has(e.id))
+            continue;
+        const stat = await fs
+            .stat(e.absPath, { bigint: true })
+            .catch(() => null);
+        if (!stat)
+            continue;
+        seen.add(e.id);
+        out.push({
+            id: e.id,
+            name: e.name,
+            type: e.type,
+            size: Number(stat.size),
+            mtimeMs: Number(stat.mtimeMs),
+            dir: path.dirname(e.absPath),
+        });
+    }
+    // 最新产物在前：右侧列表首项与自动预览（list[0]）都指向最新生成的文件
+    out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return out.map(({ mtimeMs, ...meta }) => meta);
+}
+/** 安全读取产物：在产物根与沙箱候选会话目录内查找（产物根优先），任何穿越尝试返回 null；
+ *  会话目录未命中时，回查登记表（registry）：模型写到任意位置的文件按登记 id/name 读原路径，
+ *  仅限已登记的真实路径（任意 id 无法读取未登记文件）。 */
+export async function readArtifact(sessionId, id, workspaceDir) {
+    const safeSession = sanitizeSessionId(sessionId);
+    const safeId = sanitizeArtifactName(id);
+    for (const dir of await readDirCandidates(safeSession, workspaceDir)) {
+        const expected = path.resolve(dir);
+        const resolved = path.resolve(dir, safeId);
+        if (resolved !== expected && !resolved.startsWith(expected + path.sep))
+            continue;
+        try {
+            const buf = await fs.readFile(resolved);
+            // docx 原文件直接返回：前端 WordArtifact 用 mammoth(浏览器版) 转换渲染，输入/产物统一走原文件
+            return { buf, mime: mimeFor(safeId) };
+        }
+        catch {
+            /* 尝试下一个候选目录 */
+        }
+    }
+    // 登记产物（原位置即产物）：按 id（ext-xxx-... 或工作目录根文件名）精确匹配登记条目
+    for (const e of await loadRegistry(sessionId, workspaceDir)) {
+        if (e.id !== safeId && e.name !== safeId)
+            continue;
+        // 双重校验：只读登记过的真实路径本身（路径穿越 / 篡改一律拒绝）
+        if (path.resolve(e.absPath) !== e.absPath)
+            continue;
+        try {
+            const buf = await fs.readFile(e.absPath);
+            return { buf, mime: mimeFor(e.name) };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** 构造前端拉取产物的隔离 URL（session 与 file 均经编码，服务端二次校验） */
+export function artifactUrl(basePath, sessionId, id) {
+    const bp = (basePath || "/").replace(/\/+$/, "");
+    return `${bp}/api/artifact?session=${encodeURIComponent(sessionId)}&file=${encodeURIComponent(id)}`;
+}
+/**
+ * 脱敏（第一道）：把「真实产物根目录」替换成虚拟标记 /agent-output。
+ * 同时处理 Windows 盘符路径（D:\...\agent-output）与 CLI 使用的 bash 风格路径（/d/.../agent-output），
+ * 避免任一真实路径残留在模型输出中。
+ */
+export function redactArtifactPaths(text) {
+    const root = artifactRoot();
+    const posix = root.replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, d) => `/${d.toLowerCase()}`);
+    return String(text ?? "").split(root).join(ARTIFACT_VIRTUAL_ROOT).split(posix).join(ARTIFACT_VIRTUAL_ROOT);
+}
+/**
+ * 脱敏：抹掉模型可能复述的虚拟输出路径标记（/agent-output...），
+ * 避免内部约定外泄。配合系统提示（不要提路径）作为安全网。
+ */
+export function redactOutputPaths(text) {
+    return String(text ?? "").replace(/\/agent-output(?:\/[^\s)<>"']*)?/g, "");
+}
+/**
+ * 清洗助手文本里的限流噪音（服务端源头，防止 429 错误进入回复正文/存库）：
+ *  - CLI transcript 会给消息加 trace 前缀（(32hex/uuid)），剥离前缀、保留正文；
+ *  - 429 频率限制错误整段（可能带 trace 前缀/后缀）直接丢弃；
+ *  - 内容若清洗后为空（纯错误轮次），返回空串，前端不展示空气泡。
+ */
+export function sanitizeAssistantText(text) {
+    if (!text)
+        return text;
+    const out = [];
+    for (const rawLine of String(text).split("\n")) {
+        // 保留行首缩进（代码块排版依赖），清洗只作用于行内容本身：
+        // 此前对每行 trim() 会系统性剥掉代码块缩进（44/44 代码块行首空格丢失的根因）。
+        const leading = /^[ \t]*/.exec(rawLine)?.[0] ?? "";
+        const trimmed = rawLine.trim();
+        if (!trimmed) {
+            out.push("");
+            continue;
+        }
+        let rest = trimmed.replace(/^\(\s*[0-9a-fA-F]{8,}\s*\/\s*[0-9a-fA-F-]{8,}[^)\n]*\)\s*/, "");
+        if (/429/.test(rest) && /频率限制|rate\s*[- ]?limit/i.test(rest))
+            continue;
+        if (!rest.trim())
+            continue;
+        rest = rest.replace(/429[^\n]*?频率限制[^\n]*$/i, "");
+        out.push(leading + rest);
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}