zen-gitsync 2.17.16 → 2.17.18

package/src/ui/server/routes/workbench/runExternalTurn.test.js

@@ -0,0 +1,275 @@
+// 外部引擎一轮对话的适配器单测。
+//
+// 这里**故意不 mock 事件处理器** —— 用的是 taskRunner 里真的那三个
+// （createClaudeEventHandler / createOpencodeEventHandler / createCodexEventHandler），
+// 只把 spawn 换成假的子进程喂固定的 NDJSON。这样测的是"三家协议 → SSE 事件"这条真链路：
+// mock 掉处理器就只能测到我自己写的胶水，而那恰恰是最不容易错的部分。
+//
+// 每个引擎的样例 NDJSON 都取自实测（见 taskRunner 各 handler 的头部注释与
+// taskRunner.opencode.test.js / taskRunner.codex.test.js 的 fixture 口径）。
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+
+import { runExternalTurn } from './runExternalTurn.js';
+
+/** 假子进程：按顺序把 lines 推给 stdout，然后 close。 */
+function fakeChild(lines, { exitCode = 0 } = {}) {
+  const child = new EventEmitter();
+  child.pid = 4242;
+  child.exitCode = null;
+  child.stdout = new Readable({ read() {} });
+  child.stderr = new Readable({ read() {} });
+  child.kill = () => { child.exitCode = 0; child.emit('close', 0); };
+  setImmediate(() => {
+    for (const l of lines) child.stdout.push(`${l}\n`);
+    child.stdout.push(null);
+    child.exitCode = exitCode;
+    child.emit('close', exitCode);
+  });
+  return child;
+}
+
+/** 收事件的小工具 */
+function collector() {
+  const events = [];
+  return {
+    events,
+    send: (evt) => events.push(evt),
+    of: (type) => events.filter(e => e.type === type),
+    types: () => events.map(e => e.type),
+  };
+}
+
+const baseSession = () => ({ messages: [], engineSessionId: '' });
+
+test('claude:stream-json → content / thinking / tool_call_start / tool_result / done', async () => {
+  const lines = [
+    JSON.stringify({ type: 'system', subtype: 'init', session_id: 'claude-sess-1' }),
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: '你好' }] } }),
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'thinking', thinking: '先看看' }] } }),
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 't1', name: 'Bash', input: { command: 'ls' } }] } }),
+    JSON.stringify({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 't1', content: 'a.txt\nb.txt' }] } }),
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: '结束' }] } }),
+  ];
+  const session = baseSession();
+  const c = collector();
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: '列个目录', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { claude: async () => ({ pid: 4242, child: fakeChild(lines) }) },
+  });
+
+  assert.equal(c.of('content').map(e => e.delta).join(''), '你好结束');
+  assert.equal(c.of('thinking').map(e => e.delta).join(''), '先看看');
+  const starts = c.of('tool_call_start');
+  assert.equal(starts.length, 1);
+  assert.equal(starts[0].toolCallId, 't1');
+  assert.equal(starts[0].name, 'Bash');
+  assert.match(starts[0].argsPreview, /ls/);
+  const results = c.of('tool_result');
+  assert.equal(results.length, 1);
+  assert.match(String(results[0].result), /a\.txt/);
+  assert.equal(c.of('done').length, 1);
+  assert.equal(c.of('error').length, 0);
+  assert.equal(c.of('done')[0].content, '你好结束');
+
+  // 续聊标识搬运：claude 的 session_id → session.engineSessionId
+  assert.equal(session.engineSessionId, 'claude-sess-1');
+});
+
+test('opencode:--format json → 同一组事件（含 completed 态工具）', async () => {
+  const lines = [
+    JSON.stringify({ type: 'step_start', sessionID: 'oc-1', part: { type: 'step-start' } }),
+    JSON.stringify({ type: 'text', sessionID: 'oc-1', part: { id: 'p1', type: 'text', text: '看看' } }),
+    JSON.stringify({ type: 'reasoning', sessionID: 'oc-1', part: { id: 'p2', type: 'reasoning', text: '思考中' } }),
+    JSON.stringify({ type: 'tool_use', sessionID: 'oc-1', part: { id: 'p3', callID: 'c1', type: 'tool', tool: 'bash', state: { status: 'completed', input: { cmd: 'ls' }, output: 'ok' } } }),
+    JSON.stringify({ type: 'step_finish', sessionID: 'oc-1', part: { type: 'step-finish' } }),
+  ];
+  const session = baseSession();
+  const c = collector();
+  await runExternalTurn({
+    session, engine: 'opencode', userMessage: 'hi', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { opencode: async () => ({ pid: 4242, child: fakeChild(lines) }) },
+  });
+
+  assert.equal(c.of('content').map(e => e.delta).join(''), '看看');
+  assert.equal(c.of('thinking').map(e => e.delta).join(''), '思考中');
+  assert.equal(c.of('tool_call_start')[0].name, 'bash');
+  assert.match(String(c.of('tool_result')[0].result), /ok/);
+  assert.equal(c.of('done').length, 1);
+  assert.equal(session.engineSessionId, 'oc-1');
+});
+
+test('codex:exec --json → 同一组事件（item.* 分派）', async () => {
+  const lines = [
+    JSON.stringify({ type: 'thread.started', thread_id: 'th-1' }),
+    JSON.stringify({ type: 'item.completed', item: { id: 'i1', type: 'agent_message', text: '好了' } }),
+    JSON.stringify({ type: 'item.completed', item: { id: 'i2', type: 'reasoning', text: '想想' } }),
+    JSON.stringify({ type: 'item.completed', item: { id: 'i3', type: 'command_execution', command: 'ls', status: 'completed', aggregated_output: 'files', exit_code: 0 } }),
+    JSON.stringify({ type: 'turn.completed', usage: { input_tokens: 1, output_tokens: 1 } }),
+  ];
+  const session = baseSession();
+  const c = collector();
+  await runExternalTurn({
+    session, engine: 'codex', userMessage: 'hi', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { codex: async () => ({ pid: 4242, child: fakeChild(lines) }) },
+  });
+
+  assert.equal(c.of('content').map(e => e.delta).join(''), '好了');
+  assert.equal(c.of('thinking').map(e => e.delta).join(''), '想想');
+  assert.equal(c.of('tool_call_start')[0].name, 'command_execution');
+  assert.match(String(c.of('tool_result')[0].result), /files/);
+  assert.equal(c.of('done').length, 1);
+  assert.equal(session.engineSessionId, 'th-1');
+});
+
+test('非 JSON 行（CLI 的告警）原样贴出来，不当成事件丢掉', async () => {
+  const session = baseSession();
+  const c = collector();
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: 'hi', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { claude: async () => ({ pid: 4242, child: fakeChild(['Warning: something odd', '{"type":"result","subtype":"success"}']) }) },
+  });
+  assert.match(c.of('content').map(e => e.delta).join(''), /Warning: something odd/);
+  assert.equal(c.of('error').length, 0, '告警不该被判成失败');
+});
+
+test('跨数据块被切断的 NDJSON 行要能拼回来', async () => {
+  const session = baseSession();
+  const c = collector();
+  const child = new EventEmitter();
+  child.pid = 1; child.exitCode = null;
+  child.stdout = new Readable({ read() {} });
+  child.stderr = new Readable({ read() {} });
+  child.kill = () => {};
+  setImmediate(() => {
+    // 一条 JSON 被从中间切开推送
+    child.stdout.push('{"type":"assistant","message":{"content":[{"type":"te');
+    child.stdout.push('xt","text":"拼回来了"}]}}\n');
+    child.stdout.push(null);
+    child.emit('close', 0);
+  });
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: 'hi', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { claude: async () => ({ pid: 1, child }) },
+  });
+  assert.equal(c.of('content').map(e => e.delta).join(''), '拼回来了');
+});
+
+test('工作区状态块拼在用户消息前面（不写进用户的仓库文件）', async () => {
+  const session = baseSession();
+  const c = collector();
+  let seenPrompt = '';
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: '我的仓库有哪些', cwd: 'D:/ws',
+    promptPrefix: '【工作区状态】快照目录: C:/u/.zen-gitsync/ai-context',
+    send: c.send,
+    launchers: { claude: async (_cwd, prompt) => { seenPrompt = prompt; return { pid: 1, child: fakeChild([]) }; } },
+  });
+  assert.match(seenPrompt, /【工作区状态】/);
+  assert.match(seenPrompt, /我的仓库有哪些/);
+  assert.ok(seenPrompt.indexOf('【工作区状态】') < seenPrompt.indexOf('我的仓库有哪些'), '状态块必须在用户消息之前');
+});
+
+test('附件只传绝对路径，内容不进 prompt', async () => {
+  const session = baseSession();
+  const c = collector();
+  let seenPrompt = '';
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: '看看附件', cwd: 'D:/ws',
+    filePaths: ['C:/u/.zen-gitsync/agent-attachments/2026-09-28/a.pdf'],
+    send: c.send,
+    launchers: { claude: async (_cwd, prompt) => { seenPrompt = prompt; return { pid: 1, child: fakeChild([]) }; } },
+  });
+  assert.match(seenPrompt, /a\.pdf/);
+  assert.match(seenPrompt, /绝对路径/);
+});
+
+test('续聊：把上次的 engineSessionId 交给 launcher（--resume / --session）', async () => {
+  const session = { messages: [], engineSessionId: 'prev-id' };
+  const c = collector();
+  let resumeArg = null;
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: '继续', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { claude: async (_cwd, _prompt, resumeId) => { resumeArg = resumeId; return { pid: 1, child: fakeChild([]) }; } },
+  });
+  assert.equal(resumeArg, 'prev-id');
+});
+
+test('launcher 抛错（CLI 没装）→ 发 error，不让整轮静默失败', async () => {
+  const session = baseSession();
+  const c = collector();
+  await runExternalTurn({
+    session, engine: 'codex', userMessage: 'hi', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { codex: async () => { throw new Error('spawn codex ENOENT'); } },
+  });
+  assert.equal(c.of('error').length, 1);
+  assert.match(c.of('error')[0].error, /Codex 启动失败/);
+  assert.match(c.of('error')[0].error, /ENOENT/);
+  assert.equal(c.of('done').length, 0, '启动失败不该再发 done');
+});
+
+test('未知引擎 → 明确报错（不静默当内置处理）', async () => {
+  const c = collector();
+  await runExternalTurn({ session: baseSession(), engine: 'gemini', userMessage: 'hi', cwd: 'D:/ws', send: c.send });
+  assert.equal(c.of('error').length, 1);
+  assert.match(c.of('error')[0].error, /未知的外部引擎/);
+});
+
+test('落盘：user + assistant(带 tool_calls) + tool 结果，形状与 g ai 一致', async () => {
+  const lines = [
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: '看完了' }] } }),
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 't9', name: 'Read', input: { path: 'a.md' } }] } }),
+    JSON.stringify({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 't9', content: '内容' }] } }),
+  ];
+  const session = baseSession();
+  const c = collector();
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: '看看', cwd: 'D:/ws',
+    send: c.send,
+    launchers: { claude: async () => ({ pid: 1, child: fakeChild(lines) }) },
+  });
+
+  assert.equal(session.messages[0].role, 'user');
+  const assistant = session.messages.find(m => m.role === 'assistant');
+  assert.equal(assistant.content, '看完了');
+  assert.equal(assistant.tool_calls[0].id, 't9');
+  assert.equal(assistant.tool_calls[0].type, 'function');
+  assert.equal(assistant.tool_calls[0].function.name, 'Read');
+  const tool = session.messages.find(m => m.role === 'tool');
+  assert.equal(tool.tool_call_id, 't9');
+  assert.equal(tool.content, '内容');
+});
+
+test('中止：用户点停止 → 杀掉子进程树并标 [已停止]', async () => {
+  const session = baseSession();
+  const c = collector();
+  const ac = new AbortController();
+  let killed = false;
+  const child = new EventEmitter();
+  child.pid = 999; child.exitCode = null;
+  child.stdout = new Readable({ read() {} });
+  child.stderr = new Readable({ read() {} });
+  child.kill = () => { child.exitCode = 143; child.emit('close', 143); };
+  setImmediate(() => { child.stdout.push(JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: '写了一半' }] } }) + '\n'); ac.abort(); });
+
+  await runExternalTurn({
+    session, engine: 'claude', userMessage: 'hi', cwd: 'D:/ws',
+    signal: ac.signal,
+    send: c.send,
+    launchers: { claude: async () => ({ pid: 999, child }) },
+    // 注入杀掉实现：真实现走 taskkill，假子进程上观察不到，只能注入
+    killTree: () => { killed = true; child.kill(); },
+  });
+
+  assert.equal(killed, true, '中止必须杀掉子进程（否则界面停了、机器上还在跑）');
+  assert.match(c.of('done')[0].content, /已停止/);
+});

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

@@ -49,6 +49,23 @@ export const DEFAULT_JOBS_CONFIG = { maxCount: 500, maxSizeMB: 256 };
 export const ORCHESTRATOR_FILE = path.join(DATA_DIR, 'orchestrator.json');
 export const MAX_ORCHESTRATOR_INSTRUCTIONS = 200;
 
+/**
+ * 「真相源文件」清单 —— 注入给模型、让它需要细节时自己去读全文的那几个文件。
+ *
+ * 为什么集中在这一处：有**两条**链路都要把这份清单报给模型 ——
+ *   · aiContext（智能体页对话，七个板块的注入块）
+ *   · envContext（多项目编排台派发任务时的运行环境块）
+ * 以前是各写各的（一个写三个文件名、另一个写四个），加一个可读文件就得改两处，
+ * 而漏改的那一处**不会报错**：模型只是永远不知道那个文件存在，于是回答"我看不到"。
+ * 现在路径只有这一份，标签/取舍仍由各视图自己决定（那是视图的职责，不是口径）。
+ */
+export const TRUTH_FILES = {
+  tasksFile: TASKS_FILE,
+  jobsFile: JOBS_FILE,
+  orchestratorFile: ORCHESTRATOR_FILE,
+  configFile: CONFIG_FILE,
+};
+
 // 派发默认提示词（全局 / 各项目级）**单条**长度上限。
 // 它不是"指令"，而是一条每次派发都会被拼进 prompt 的约束 —— 4000 字足够写下一整套
 // 规范，再长只会让每一次执行都白烧一遍 token。

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 })
+})