zen-gitsync 2.17.15 → 2.17.17

package/src/ui/server/routes/workbench/taskRunner.js

@@ -15,13 +15,15 @@
 // 任务执行引擎：spawn 本地 agent CLI 跑子任务，流式收集输出，更新 job 状态。
 // 拆分自原 routes/workbench.js 1108-1564 行。
 //
-// 支持两种执行器（executor）：
+// 支持三种执行器（executor）：
 //   - claude   —— claude -p --output-format stream-json（默认，历史行为）
 //   - opencode —— opencode run --format json --auto（sst/opencode CLI，跟随其自身默认模型）
+//   - codex    —— codex exec --json（OpenAI Codex CLI，跟随其自身配置；2026-09-27 加入）
 //
 // 核心 API：
 //   - launchClaudeInNewWindow(cwd, prompt, resumeSessionId)  spawn claude，返回 {pid, child}
 //   - launchOpencodeRun(cwd, prompt, resumeSessionId)        spawn opencode，返回 {pid, child}
+//   - launchCodexExec(cwd, prompt, resumeSessionId)          spawn codex，返回 {pid, child}
 //   - normalizeTaskExecutor(value)                           非法值回落 'claude'
 //   - runSingleSubtask(task, sub, repoPath, branch, opts)    跑一次任务（sub 是运行载体，见下）
 //   - waitProcessExit(pid)                                   polling 等进程退出
@@ -185,10 +187,11 @@ function attachPromptStdin(child, promptText, resolve, reject) {
 }
 
 // ── 执行器（executor） ──────────────────────────────────────────────────
-// 工作台任务默认由 claude CLI 执行；opencode 作为可选执行器（2026-09-20）。
-// 两者都用「stdin 喂 prompt + stdout 结构化 JSON 事件流」的同构形态，
-// 差异只在协议：claude 是 stream-json，opencode 是 --format json 的事件 NDJSON。
-export const TASK_EXECUTORS = ['claude', 'opencode'];
+// 工作台任务默认由 claude CLI 执行；opencode（2026-09-20）、codex（2026-09-27）
+// 作为可选执行器。三者都用「stdin 喂 prompt + stdout 结构化 JSON 事件流」的同构形态，
+// 差异只在协议：claude 是 stream-json，opencode 是 --format json 的事件 NDJSON，
+// codex 是 exec --json 的 thread/item 事件 NDJSON。
+export const TASK_EXECUTORS = ['claude', 'opencode', 'codex'];
 
 /** 非法/缺省的 executor 一律回落 'claude'（历史行为的兼容兜底）。
  *  body.executor 来自网络，做一次 trim + 小写归一，与 config.js 同名函数同语义。 */
@@ -269,6 +272,95 @@ export function launchOpencodeRun(cwd, promptText, resumeSessionId) {
   });
 }
 
+// ── codex 执行器（2026-09-27 加入） ──────────────────────────────────────
+// codex exec 是非交互模式，形态与另两个执行器同构（stdin 喂 prompt + stdout NDJSON）：
+//
+//   codex exec [resume <thread_id>] --json --skip-git-repo-check
+//     --dangerously-bypass-approvals-and-sandbox -      （`-` = prompt 从 stdin 读）
+//
+//   - --json      输出 JSONL 事件流（thread.started / item.* / turn.*）
+//   - --dangerously-bypass-approvals-and-sandbox
+//                 免批准 + 免沙箱，对应 claude 的 bypassPermissions、opencode 的 --auto。
+//                 工作台任务全程无人应答批准提示，不跳过的话一遇审批就卡死
+//   - --skip-git-repo-check
+//                 工作台允许在非 git 目录建任务，不跳过的话 codex 直接拒绝启动
+//   - 不传 -m / -s：模型与沙箱跟随 codex 自身配置（同 opencode 的口径）
+//   - 续聊：codex exec resume <thread_id>，thread_id 来自 thread.started 事件
+
+/**
+ * Windows 下把 codex 解析成可直接 spawn 的 exe。
+ *
+ * npm 全局安装的 codex 是 .cmd shim（Node 23+ 拒绝 spawn .cmd，EINVAL），shim 指向
+ * `node bin/codex.js`；而 bin/codex.js 自己也只是一层壳，真正干活的原生二进制在平台
+ * 子包里：node_modules/@openai/codex/node_modules/@openai/codex-win32-<arch>/vendor/
+ * <triple>/bin/codex.exe（与 bin/codex.js 的查找口径一致，另留一份无平台子包的兜底路径）。
+ *
+ * 为什么不直接 spawn(process.execPath, [bin/codex.js, ...])：那层壳会再 spawn 一次原生
+ * 二进制，取消任务时 kill 到的只是壳进程，原生 codex 会变孤儿继续改文件。
+ */
+function resolveCodexExe() {
+  try {
+    const lines = execFileSync('where', ['codex'], { encoding: 'utf8', windowsHide: true })
+      .split(/\r?\n/).map(s => s.trim()).filter(Boolean);
+    // 独立安装（scoop / 手动下载 / 包管理器直装）优先：PATH 上直接就是原生 exe
+    const directExe = lines.find(s => /\.exe$/i.test(s));
+    if (directExe && fs.existsSync(directExe)) return directExe;
+    const cmdShim = lines.find(s => /\.cmd$/i.test(s));
+    if (cmdShim) {
+      const prefix = path.dirname(cmdShim);
+      const triple = process.arch === 'arm64' ? 'aarch64-pc-windows-msvc' : 'x86_64-pc-windows-msvc';
+      const archTag = process.arch === 'arm64' ? 'arm64' : 'x64';
+      const candidates = [
+        path.join(prefix, 'node_modules', '@openai', 'codex', 'node_modules', '@openai',
+          `codex-win32-${archTag}`, 'vendor', triple, 'bin', 'codex.exe'),
+        path.join(prefix, 'node_modules', '@openai', 'codex', 'vendor', triple, 'bin', 'codex.exe'),
+      ];
+      for (const exe of candidates) {
+        if (fs.existsSync(exe)) return exe;
+      }
+    }
+  } catch { /* fallback */ }
+  // 兜底交给 PATH：装在非 npm 全局目录时通常有 codex.exe
+  return 'codex.exe';
+}
+
+/**
+ * codex 子进程环境。
+ * RUST_LOG=error：codex 默认把 tracing 的 INFO 日志写 stderr，而 stderr 里非 JSON 行
+ * 会被当正文贴进输出面板（实测一次执行能刷出上百行）；压到 error 档即可清干净，
+ * 真正的报错走 stdout 的 JSON 事件流（error / turn.failed），信息不丢。
+ */
+function buildCodexEnv() {
+  return { ...process.env, LANG: 'zh_CN.UTF-8', RUST_LOG: 'error' };
+}
+
+/** spawn codex exec 跑一个 prompt，返回 { pid, child }（参数口径见上方注释）。 */
+export function launchCodexExec(cwd, promptText, resumeSessionId) {
+  return new Promise((resolve, reject) => {
+    const flags = ['--json', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox'];
+    const args = resumeSessionId
+      ? ['exec', 'resume', ...flags, String(resumeSessionId), '-']
+      : ['exec', ...flags, '-'];
+    let child;
+    if (process.platform === 'win32') {
+      child = spawn(resolveCodexExe(), args, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: false,
+        env: buildCodexEnv()
+      });
+    } else {
+      child = spawn('codex', args, {
+        cwd,
+        detached: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: buildCodexEnv()
+      });
+    }
+    attachPromptStdin(child, promptText, resolve, reject);
+  });
+}
+
 // ── 工具调用（tool_use）收集 ──────────────────────────────────────────────
 // 为什么要有这一层：job.output 只承载「模型说的话」。工具调用（读了哪个文件、跑了什么命令、
 // 拿到了什么结果）原本在两个事件处理器里被整段丢掉，于是前端只剩「思考 + 正文」两块，
@@ -585,6 +677,156 @@ export function createOpencodeEventHandler(job, appendOutput, appendThinking, to
   };
 }
 
+/**
+ * codex `exec --json` 事件处理器。
+ *
+ * 事件形态（codex-cli 0.157.x；schema 源：openai/codex codex-rs/exec/src/exec_events.rs）：
+ *   { type:'thread.started', thread_id }            会话续接标识（exec resume <id>）
+ *   { type:'turn.started' } / { type:'turn.completed', usage }
+ *   { type:'turn.failed', error:{ message } }       本轮终态失败（进程退出码可能仍是 0）
+ *   { type:'item.started'|'item.updated'|'item.completed', item:{ id, type, ... } }
+ *   { type:'error', message }                       重试等非终止信息（真失败走 turn.failed）
+ *
+ * item.type（snake_case）分派：
+ *   agent_message      正文 → output（按 item.id 做累积/增量去重，两种推送语义都兼容）
+ *   reasoning          思考 → thinking
+ *   command_execution  命令 → 工具调用（command 作参数摘要，aggregated_output 作结果）
+ *   file_change        改动文件清单 → 工具调用
+ *   mcp_tool_call      MCP 工具 → 工具调用（server.tool 作名字）
+ *   web_search         搜索 → 工具调用
+ *   error              非致命告警（配置项被忽略 / 模型元信息缺失等）→ 贴进 output，不判失败
+ *   其余（todo_list / collab_tool_call / 未来新增）忽略 —— 事件枚举是 non_exhaustive，
+ *   未知类型不能影响正文收集与终态判定。
+ * （导出仅为回归测试可见：taskRunner.codex.test.js）
+ */
+export function createCodexEventHandler(job, appendOutput, appendThinking, toolCalls) {
+  const tracker = toolCalls || createToolCallTracker(job);
+  const seenTextItems = new Map(); // item.id -> 已落地的累计文本
+
+  const appendItemText = (item, isThinking) => {
+    const text = typeof item?.text === 'string' ? item.text : '';
+    if (!text) return;
+    const id = typeof item?.id === 'string' ? item.id : '';
+    const prev = id ? seenTextItems.get(id) : undefined;
+    let delta = text;
+    if (prev !== undefined) {
+      delta = text.startsWith(prev) ? text.slice(prev.length) : text;
+    }
+    if (!delta) return;
+    if (id) seenTextItems.set(id, prev !== undefined ? prev + delta : text);
+    if (isThinking) appendThinking(delta);
+    else appendOutput(delta);
+  };
+
+  // codex 的 status: in_progress | completed | failed | declined（snake_case）
+  const mapItemStatus = (raw) => {
+    const s = typeof raw === 'string' ? raw.toLowerCase() : '';
+    if (s === 'completed') return 'done';
+    if (s === 'failed' || s === 'declined') return 'error';
+    return 'running';
+  };
+
+  const changesText = (changes) => (Array.isArray(changes) ? changes : [])
+    .map(c => (c && c.path ? `${c.kind || 'update'} ${c.path}` : ''))
+    .filter(Boolean)
+    .join('\n');
+
+  const handleItem = (item) => {
+    if (!item || typeof item !== 'object') return;
+    switch (item.type) {
+      case 'agent_message':
+        appendItemText(item, false);
+        return;
+      case 'reasoning':
+        appendItemText(item, true);
+        return;
+      case 'error':
+        // 非致命告警：原样贴出来让用户看得见，但不置 agentError —— 那会把告警变成任务失败
+        if (item.message) appendOutput(`\n> [codex] ${item.message}\n`);
+        return;
+      case 'command_execution': {
+        const status = mapItemStatus(item.status);
+        tracker.record({
+          id: item.id,
+          name: 'command_execution',
+          input: { command: item.command },
+          status,
+          output: status === 'running' ? undefined : item.aggregated_output,
+          error: status === 'error' ? `命令未成功完成（exit_code=${item.exit_code ?? 'null'}）` : ''
+        });
+        return;
+      }
+      case 'file_change': {
+        const status = mapItemStatus(item.status);
+        tracker.record({
+          id: item.id,
+          name: 'file_change',
+          input: { changes: item.changes },
+          status,
+          output: status === 'running' ? undefined : changesText(item.changes),
+          error: status === 'error' ? '文件改动未应用' : ''
+        });
+        return;
+      }
+      case 'mcp_tool_call': {
+        const status = mapItemStatus(item.status);
+        tracker.record({
+          id: item.id,
+          name: item.server && item.tool ? `${item.server}.${item.tool}` : (item.tool || 'mcp_tool_call'),
+          input: item.arguments,
+          // result.content 是 MCP 的内容块数组（与 claude 的 tool_result 同形态），
+          // 直接喂给 extractToolText 能压成文本；没有 content 时整包 JSON 兜底
+          status,
+          output: status === 'running' ? undefined : (item.result?.content ?? item.result),
+          error: item.error?.message || (status === 'error' ? 'MCP 工具调用失败' : '')
+        });
+        return;
+      }
+      case 'web_search': {
+        const status = mapItemStatus(item.status);
+        tracker.record({
+          id: item.id,
+          name: 'web_search',
+          input: { query: item.query },
+          status,
+          output: status === 'running' ? undefined : item.results
+        });
+        return;
+      }
+      default:
+        return;
+    }
+  };
+
+  return (evt) => {
+    if (!evt || typeof evt !== 'object') return;
+    // thread_id 是 codex 的会话续接标识（exec resume <id>）。复用 claudeSessionId 字段：
+    // 前端与续接路由都认它，换执行器只是取值来源不同。
+    if (evt.type === 'thread.started') {
+      if (typeof evt.thread_id === 'string' && evt.thread_id && job.claudeSessionId !== evt.thread_id) {
+        job.claudeSessionId = evt.thread_id;
+        publish('job:update', job);
+      }
+      return;
+    }
+    if (evt.type === 'item.started' || evt.type === 'item.updated' || evt.type === 'item.completed') {
+      handleItem(evt.item);
+      return;
+    }
+    if (evt.type === 'turn.failed') {
+      const msg = evt.error?.message
+        || (evt.error?.additional_details ? String(evt.error.additional_details) : '')
+        || 'codex 执行出错';
+      if (!job.agentError) job.agentError = msg;
+      return;
+    }
+    if (evt.type === 'error') {
+      // 非终止信息（如 "Reconnecting... 1/5" 重试提示）：贴进 output，终态仍由 turn.* 决定
+      if (evt.message) appendOutput(`\n> [codex] ${evt.message}\n`);
+    }
+  };
+}
+
 /**
  * 执行一次任务。任务一次只跑一个进程，本函数是唯一的执行入口
  * （首次执行、手动重跑、续聊都走它）。
@@ -595,10 +837,11 @@ export function createOpencodeEventHandler(job, appendOutput, appendThinking, to
  * @param {string} branch       分支名（可空）
  * @param {object} [options]
  * @param {string|null} [options.resumeSessionId]
- *        续接历史会话:claude 走 --resume <id>，opencode 走 --session <id>。
- *        id 来自上一轮 stream 事件捕获的会话标识(两者都记在 job.claudeSessionId)。
+ *        续接历史会话:claude 走 --resume <id>，opencode 走 --session <id>，
+ *        codex 走 exec resume <thread_id>。
+ *        id 来自上一轮 stream 事件捕获的会话标识(三者都记在 job.claudeSessionId)。
  * @param {string} [options.executor]
- *        执行器 'claude' | 'opencode'。缺省回落 'claude'；路由层负责把
+ *        执行器 'claude' | 'opencode' | 'codex'。缺省回落 'claude'；路由层负责把
  *        "body 指定 > 配置默认"先解析好再传进来。
  * @returns {Promise<'done'|'cancelled'|'error'>} 本次运行的终态
  */
@@ -677,7 +920,11 @@ export async function runSingleSubtask(task, sub, repoPath, branch, options) {
   let toolTracker = null;
 
   try {
-    const launcher = executor === 'opencode' ? launchOpencodeRun : launchClaudeInNewWindow;
+    const launcher = executor === 'opencode'
+      ? launchOpencodeRun
+      : executor === 'codex'
+        ? launchCodexExec
+        : launchClaudeInNewWindow;
     const { pid, child } = await launcher(repoPath || process.cwd(), prompt, resumeSessionId);
     job.pid = pid;
     // 保存 child 引用，供 cancel 接口调用 kill
@@ -729,7 +976,9 @@ export async function runSingleSubtask(task, sub, repoPath, branch, options) {
 
     const handleEvent = executor === 'opencode'
       ? createOpencodeEventHandler(job, appendOutput, appendThinking, toolTracker)
-      : createClaudeEventHandler(job, appendOutput, appendThinking, toolTracker);
+      : executor === 'codex'
+        ? createCodexEventHandler(job, appendOutput, appendThinking, toolTracker)
+        : createClaudeEventHandler(job, appendOutput, appendThinking, toolTracker);
 
     const handleLine = (line, channel) => {
       const trimmed = line.trim();

package/src/ui/server/routes/workbench/taskRunner.opencode.test.js

@@ -54,12 +54,14 @@ function makeSink() {
 }
 
 test('normalizeTaskExecutor：白名单 + 大小写 + 非法回落', () => {
-  assert.deepEqual(TASK_EXECUTORS, ['claude', 'opencode']);
+  assert.deepEqual(TASK_EXECUTORS, ['claude', 'opencode', 'codex']);
   assert.equal(normalizeTaskExecutor('opencode'), 'opencode');
+  assert.equal(normalizeTaskExecutor('codex'), 'codex');
   // 大小写不敏感（存储前统一小写）
   assert.equal(normalizeTaskExecutor('OpenCode'), 'opencode');
   assert.equal(normalizeTaskExecutor('opencode '), 'opencode');
-  assert.equal(normalizeTaskExecutor('codex'), 'claude');
+  assert.equal(normalizeTaskExecutor('Codex '), 'codex');
+  assert.equal(normalizeTaskExecutor('gpt'), 'claude');
   assert.equal(normalizeTaskExecutor(undefined), 'claude');
   assert.equal(normalizeTaskExecutor(null), 'claude');
 });

package/src/ui/server/utils/agentAttachments.js

@@ -0,0 +1,169 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+/**
+ * 智能体对话的**非图片附件**落盘。
+ *
+ * 设计口径(2026-09-27 与用户确认的方案"附件当路径提示"):
+ *   - 图片继续走多模态:前端转 dataURL → 请求体的 images[] → image_url part,模型直接"看"。
+ *   - 非图片不进消息体,只落盘 + 把**绝对路径**写进 system 提示,模型需要时用 read / grep
+ *     工具自己去读。理由:
+ *       a) .log / .csv / 代码文件动辄几百 KB,内联进消息既费 token 又容易把上下文撑爆;
+ *       b) 模型本来就有文件工具,给路径让它按需取,比一次全塞进去划算得多;
+ *       c) 这也是唯一可行路径 —— 浏览器 <input type=file> 出于安全**不提供磁盘路径**,
+ *          只有 File 对象,所以想"只给路径"就必须由服务端落盘一次。
+ *
+ * 落盘位置:~/.zen-gitsync/agent-attachments/<轮次目录>/<文件名>(见 src/paths.js)。
+ * 按轮次分子目录,是为了同名文件在第二轮不被覆盖、第一次给过的路径一直有效。
+ *
+ * 安全口径:客户端传来的 name 一律当作**不可信输入** —— 只取 basename、剥掉控制字符与
+ * 路径分隔符、限长;大小与数量在服务端再卡一遍(不能只信前端)。
+ */
+import fs from 'fs/promises'
+import path from 'path'
+import { AGENT_ATTACHMENTS_DIR } from '../../../paths.js'
+
+/** 单轮最多几个附件 */
+export const MAX_ATTACHMENTS = 10
+/** 单个附件解密后最大字节数 */
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024
+/** 单轮附件合计最大字节数(前端 base64 后约 ×1.37,须留在 /api/agent/chat 的 50mb 之内) */
+export const MAX_ATTACHMENT_TOTAL_BYTES = 20 * 1024 * 1024
+/** 保留最近多少轮的上传目录,多余的顺手清掉 */
+export const KEEP_UPLOAD_TURNS = 30
+/** 文件名最长字符数(保留扩展名) */
+const MAX_NAME_LEN = 80
+
+/**
+ * 把客户端给的文件名洗成安全的单段文件名。
+ * 只做"文件名"该做的事:app 后面所有路径都是自己拼的,这里防的是 `../../x` 这类穿越与
+ * Windows 保留字符。
+ */
+export function sanitizeFileName(raw, fallback = 'file') {
+  let name = String(raw || '')
+  // 归一化分隔符后只取最后一段 —— Windows 的 \\ 与 POSIX 的 / 都要挡
+  name = name.split(/[\\/]/).pop() || ''
+  // 控制字符(含 \0)与 Windows 非法字符
+  name = name.replace(/[\x00-\x1f\x7f<>:"|?*]/g, '_')
+  // 纯点名".."/"." 不算文件名
+  name = name.replace(/^\.+$/, '')
+  name = name.trim()
+  if (!name) return fallback
+  if (name.length <= MAX_NAME_LEN) return name
+  // 超长时保留扩展名,截前半段
+  const ext = path.extname(name).slice(0, 16)
+  const base = name.slice(0, MAX_NAME_LEN - ext.length)
+  return base + ext
+}
+
+/** `data:<mime>;base64,<payload>` → Buffer;不是 base64 dataURL 就返回 null */
+export function decodeDataUrl(dataUrl) {
+  if (typeof dataUrl !== 'string') return null
+  const m = /^data:[^,]*;base64,(.+)$/s.exec(dataUrl)
+  if (!m) return null
+  try {
+    return Buffer.from(m[1], 'base64')
+  } catch {
+    return null
+  }
+}
+
+/** 一轮一个子目录名:时间戳 + 随机尾巴(同一毫秒内两次调用也不会撞) */
+function turnDirName(now = new Date()) {
+  const p = (n) => String(n).padStart(2, '0')
+  const stamp = `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`
+  const rand = Math.random().toString(36).slice(2, 6)
+  return `${stamp}-${rand}`
+}
+
+/**
+ * 落盘一批附件。
+ *
+ * @param {Array<{name?: string, dataUrl?: string}>} list 客户端传来的原始数组(不可信)
+ * @param {{ dir?: string, now?: Date, onSkip?: (info: {name: string, reason: string}) => void }} [opts]
+ * @returns {Promise<Array<{ name: string, path: string, bytes: number }>>} 落盘成功的附件(路径为绝对路径)
+ */
+export async function saveAgentAttachments(list, opts = {}) {
+  const dir = opts.dir || AGENT_ATTACHMENTS_DIR
+  const onSkip = typeof opts.onSkip === 'function' ? opts.onSkip : () => {}
+  const items = (Array.isArray(list) ? list : []).slice(0, MAX_ATTACHMENTS)
+  if (items.length === 0) return []
+
+  const saved = []
+  const used = new Set()
+  let total = 0
+  // 目录按需创建:一次都没上传过附件的用户不会平白多一个目录
+  let ensured = false
+  let turnDir = ''
+
+  for (const raw of items) {
+    const name = sanitizeFileName(raw?.name)
+    if (total >= MAX_ATTACHMENT_TOTAL_BYTES) {
+      onSkip({ name, reason: 'total-too-large' })
+      continue
+    }
+    const buf = decodeDataUrl(raw?.dataUrl)
+    if (!buf || buf.length === 0) {
+      onSkip({ name, reason: 'bad-payload' })
+      continue
+    }
+    if (buf.length > MAX_ATTACHMENT_BYTES) {
+      onSkip({ name, reason: 'too-large' })
+      continue
+    }
+    if (total + buf.length > MAX_ATTACHMENT_TOTAL_BYTES) {
+      onSkip({ name, reason: 'total-too-large' })
+      continue
+    }
+    if (!ensured) {
+      await fs.mkdir(dir, { recursive: true })
+      turnDir = path.join(dir, turnDirName(opts.now))
+      await fs.mkdir(turnDir, { recursive: true })
+      ensured = true
+    }
+    // 同一轮里两个文件同名:加 -1 / -2 后缀,不要互相覆盖
+    let finalName = name
+    let n = 1
+    while (used.has(finalName.toLowerCase())) {
+      const ext = path.extname(name)
+      finalName = `${name.slice(0, name.length - ext.length)}-${n++}${ext}`
+    }
+    used.add(finalName.toLowerCase())
+    const target = path.join(turnDir, finalName)
+    try {
+      await fs.writeFile(target, buf)
+    } catch (err) {
+      onSkip({ name, reason: `write-failed:${err?.code || err?.message || 'unknown'}` })
+      continue
+    }
+    total += buf.length
+    saved.push({ name: finalName, path: target, bytes: buf.length })
+  }
+
+  if (saved.length > 0) {
+    await pruneUploadDirs(dir, opts.now).catch(() => {})
+  }
+  return saved
+}
+
+/** 只保留最近 keep 轮目录(尽力而为:失败不抛,不影响本轮对话) */
+export async function pruneUploadDirs(dir = AGENT_ATTACHMENTS_DIR, now = new Date(), keep = KEEP_UPLOAD_TURNS) {
+  const dirs = (await fs.readdir(dir, { withFileTypes: true }).catch(() => []))
+    .filter(e => e.isDirectory()).map(e => e.name).sort()
+  const extra = dirs.slice(0, Math.max(0, dirs.length - keep))
+  for (const name of extra) {
+    await fs.rm(path.join(dir, name), { recursive: true, force: true }).catch(() => {})
+  }
+  return extra.length
+}

package/src/ui/server/utils/agentAttachments.test.js

@@ -0,0 +1,140 @@
+// 智能体非图片附件落盘:文件名消毒 / 体积与数量上限 / 同名不覆盖 / 轮次目录清理。
+// 关键口径:客户端传的 name 是不可信输入,任何情况下都不能拼进目录外。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import {
+  saveAgentAttachments,
+  sanitizeFileName,
+  decodeDataUrl,
+  pruneUploadDirs,
+  MAX_ATTACHMENT_BYTES,
+  MAX_ATTACHMENTS
+} from './agentAttachments.js'
+
+async function tmpDir(prefix = 'zen-att-') {
+  return await fs.mkdtemp(path.join(os.tmpdir(), prefix))
+}
+
+function dataUrl(text, mime = 'text/plain') {
+  return `data:${mime};base64,${Buffer.from(text, 'utf8').toString('base64')}`
+}
+
+test('sanitizeFileName: 剥路径穿越、控制字符与 Windows 非法字符', () => {
+  assert.equal(sanitizeFileName('../../etc/passwd'), 'passwd')
+  assert.equal(sanitizeFileName('C:\\Windows\\evil.txt'), 'evil.txt')
+  assert.equal(sanitizeFileName('a\u0000b.txt'), 'a_b.txt')
+  assert.equal(sanitizeFileName('bad:name?.log'), 'bad_name_.log')
+  assert.equal(sanitizeFileName('..'), 'file', '纯点名要回落默认名')
+  assert.equal(sanitizeFileName(''), 'file')
+  assert.equal(sanitizeFileName(null), 'file')
+})
+
+test('sanitizeFileName: 超长名截断但保留扩展名', () => {
+  const long = 'x'.repeat(200) + '.log'
+  const out = sanitizeFileName(long)
+  assert.ok(out.length <= 80, `长度应被截断,实际 ${out.length}`)
+  assert.ok(out.endsWith('.log'), '扩展名要保留')
+})
+
+test('decodeDataUrl: 只认 base64 dataURL', () => {
+  assert.equal(decodeDataUrl(dataUrl('hi')).toString('utf8'), 'hi')
+  assert.equal(decodeDataUrl('data:text/plain,hi'), null, '非 base64 不认')
+  assert.equal(decodeDataUrl('not-a-data-url'), null)
+  assert.equal(decodeDataUrl(undefined), null)
+})
+
+test('saveAgentAttachments: 落盘到指定目录并返回绝对路径,内容一致', async () => {
+  const dir = await tmpDir()
+  const saved = await saveAgentAttachments(
+    [{ name: '错误日志.log', dataUrl: dataUrl('boom\n', 'text/plain') }],
+    { dir }
+  )
+  assert.equal(saved.length, 1)
+  assert.equal(saved[0].name, '错误日志.log')
+  assert.ok(path.isAbsolute(saved[0].path), '返回的必须是绝对路径(模型按绝对路径读)')
+  assert.equal(await fs.readFile(saved[0].path, 'utf8'), 'boom\n')
+  // 落在 dir 的子目录里(一轮一个目录)
+  assert.equal(path.dirname(path.dirname(saved[0].path)), dir)
+  await fs.rm(dir, { recursive: true, force: true })
+})
+
+test('saveAgentAttachments: 目录穿越的 name 写不到目录外', async () => {
+  const dir = await tmpDir()
+  const saved = await saveAgentAttachments(
+    [{ name: '../../escaped.txt', dataUrl: dataUrl('x') }],
+    { dir }
+  )
+  assert.equal(saved.length, 1)
+  assert.equal(saved[0].name, 'escaped.txt')
+  assert.ok(saved[0].path.startsWith(dir), '必须仍在传入目录内')
+  await fs.rm(dir, { recursive: true, force: true })
+})
+
+test('saveAgentAttachments: 超大 / 空 payload / 数量超限都会被跳过并回调', async () => {
+  const dir = await tmpDir()
+  const skipped = []
+  const big = Buffer.alloc(MAX_ATTACHMENT_BYTES + 1, 0x61).toString('base64')
+  const list = [
+    { name: 'ok.txt', dataUrl: dataUrl('fine') },
+    { name: 'big.bin', dataUrl: `data:application/octet-stream;base64,${big}` },
+    { name: 'broken.txt', dataUrl: 'not-a-data-url' },
+    { name: 'empty.txt', dataUrl: 'data:text/plain;base64,' }
+  ]
+  const saved = await saveAgentAttachments(list, { dir, onSkip: i => skipped.push(i.reason) })
+  assert.deepEqual(saved.map(s => s.name), ['ok.txt'])
+  assert.ok(skipped.includes('too-large'))
+  assert.ok(skipped.includes('bad-payload'))
+  await fs.rm(dir, { recursive: true, force: true })
+})
+
+test('saveAgentAttachments: 超过 MAX_ATTACHMENTS 的余量直接截掉', async () => {
+  const dir = await tmpDir()
+  const list = Array.from({ length: MAX_ATTACHMENTS + 3 }, (_, i) => ({
+    name: `f${i}.txt`,
+    dataUrl: dataUrl(String(i))
+  }))
+  const saved = await saveAgentAttachments(list, { dir })
+  assert.equal(saved.length, MAX_ATTACHMENTS)
+  await fs.rm(dir, { recursive: true, force: true })
+})
+
+test('saveAgentAttachments: 同一轮内同名文件加序号,不互相覆盖', async () => {
+  const dir = await tmpDir()
+  const saved = await saveAgentAttachments(
+    [
+      { name: 'a.txt', dataUrl: dataUrl('first') },
+      { name: 'a.txt', dataUrl: dataUrl('second') }
+    ],
+    { dir }
+  )
+  assert.equal(saved.length, 2)
+  assert.notEqual(saved[0].path, saved[1].path)
+  assert.equal(await fs.readFile(saved[0].path, 'utf8'), 'first')
+  assert.equal(await fs.readFile(saved[1].path, 'utf8'), 'second')
+  await fs.rm(dir, { recursive: true, force: true })
+})
+
+test('saveAgentAttachments: 空数组不建目录(没人上传就别留垃圾)', async () => {
+  const dir = path.join(await tmpDir(), 'never')
+  const saved = await saveAgentAttachments([], { dir })
+  assert.deepEqual(saved, [])
+  await assert.rejects(fs.stat(dir), '目录不该被创建')
+})
+
+test('pruneUploadDirs: 只保留最近 KEEP_UPLOAD_TURNS 轮', async () => {
+  const dir = await tmpDir()
+  // 目录名按时间戳字典序排序,这里直接造有序名字
+  for (const n of ['20260101-000000-aaaa', '20260102-000000-bbbb', '20260103-000000-cccc']) {
+    const d = path.join(dir, n)
+    await fs.mkdir(d, { recursive: true })
+    await fs.writeFile(path.join(d, 'x.txt'), 'x')
+  }
+  const removed = await pruneUploadDirs(dir, new Date(), 2)
+  assert.equal(removed, 1)
+  const left = (await fs.readdir(dir)).sort()
+  assert.deepEqual(left, ['20260102-000000-bbbb', '20260103-000000-cccc'])
+  await fs.rm(dir, { recursive: true, force: true })
+})