zen-gitsync 2.16.1 → 2.16.3

package/README.md

@@ -1,4 +1,4 @@
-# zen-gitsync
+# zen-gitsync
 
 [English](#zen-gitsync) | [中文](#zh)
 
@@ -410,7 +410,9 @@ rm -f package-lock.json # when running on pnpm
 
 ### AI coding agent (terminal):
 Launch an interactive AI agent that writes code, runs commands, and commits for you.
-It uses the default model configured in `g ui` (Settings → AI models).
+It uses the default model configured in `g ui` (Settings → AI models). If no model is
+configured yet, `g ai` launches an interactive setup wizard — pick a provider, choose a
+model, enter your API key, test the connection, and you're ready to go.
 
 ```bash
 $ g ai                          # interactive REPL
@@ -418,7 +420,7 @@ $ g ai "fix the failing test"   # one-shot task, then exit
 $ g ai --model=2                # pick the 2nd configured model (index or name)
 ```
 
-In-session commands: `/help`, `/model`, `/cd <path>`, `/image [path]`, `/think`, `/clear`, `/exit`.
+In-session commands: `/help`, `/model`, `/addmodel`, `/cd <path>`, `/image [path]`, `/think`, `/clear`, `/exit`.
 
 Images: press `Alt+V` in the REPL to paste a clipboard image (screenshot), or attach a
 local file with `/image <path>`; images are sent as multimodal `image_url` parts with your
@@ -919,6 +921,29 @@ git add --renormalize .
 
 ## 命令行
 
+### AI 编码智能体（终端）：
+启动交互式 AI 智能体，自动写代码、跑命令、提交代码。
+默认使用 `g ui` 中配置的模型（设置 → AI 模型）。如果尚未配置任何模型，`g ai` 会启动
+交互式配置向导 —— 选择服务商、选择模型、输入 API Key、测试连接，完成后即可直接使用。
+
+```bash
+$ g ai                          # 交互式 REPL
+$ g ai "修复失败的测试"           # 单发模式：执行一轮后退出
+$ g ai --model=2                # 使用第 2 个已配置的模型（序号或名称）
+```
+
+会话内命令：`/help`、`/model`、`/addmodel`、`/cd <路径>`、`/image [路径]`、`/think`、`/clear`、`/exit`。
+
+图片：在 REPL 中按 `Alt+V` 粘贴剪贴板图片（截图），或用 `/image <路径>` 附加本地图片；
+图片以多模态 `image_url` 部件随下一条消息发送（需视觉模型）。单独 `/image` 查看待发送图片，
+`/image clear` 清除。
+
+终端 UI 对标 Codex / Claude Code 风格：盒式输入框、等待 spinner、灰斜体流式思考、
+`⏺` 工具块 + 智能参数摘要、轻量 Markdown 渲染（加粗、行内代码、标题、代码块）。
+
+权限模型：启动目录内所有操作直接执行；其他目录同样可读写；仅系统级破坏命令
+（格式化磁盘、`rm -rf /`、关机等）由内置安全守卫硬拦截。
+
 #### 交互式提交：
 ```bash
 $ g

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-gitsync",
-  "version": "2.16.1",
+  "version": "2.16.3",
   "description": "Auto commit, scheduled sync, and visual GUI for Git. Run `g` in any repo for one-key commit & push, AI commit messages, scheduled background sync, and a drag-and-drop workflow builder.",
   "main": "index.js",
   "type": "module",

package/src/cli/ai/agent.js

@@ -27,8 +27,8 @@
 //     (格式化磁盘、删根目录、关机等系统级破坏操作)
 //
 // 视觉风格(termui.js):对标 Codex CLI / Claude Code / OpenCode —
-//   盒式输入框、ora 等待 spinner、✻ 思考灰斜体、⏺ 工具块 + ⎿ 结果槽、
-//   正文逐行轻量 markdown(**bold** / `code` / # 标题 / ``` 围栏 / - 列表)
+//   盒式输入框、ora 等待 spinner、✻ 思考(橙黄斜体)、⚙ 工具头(青) + │ 结果槽、
+//   正文 ➤ 子弹头(绿)+ 逐行轻量 markdown(**bold** / `code` / # 标题 / ``` 围栏 / - 列表)
 //
 // 使用方式:
 //   g ai                  交互模式(REPL)
@@ -49,11 +49,13 @@ import { TOOL_DEFINITIONS, executeTool } from './tools.js'
 import { createThinkFilter } from './streamFilter.js'
 import {
   printBanner, printHelpPanel,
+  filterSlashCommands, renderSlashHintBody,
   startSpinner, createAssistantWriter,
   summarizeToolArgs, printToolHeader, printToolResult,
   printOk, printWarn, printError, printDim,
 } from './termui.js'
 import { readClipboardImage, checkImageFile, imageToDataUrl, formatBytes } from './images.js'
+import { runModelSetup, collectModelInput, buildModelConfig } from './modelSetup.js'
 
 // truncateDisplay 已迁移到 termui.js;这里 re-export 保持既有测试/外部引用不断
 export { truncateDisplay } from './termui.js'
@@ -94,7 +96,7 @@ const STRINGS = {
     prompt: '❯ ',
     bannerModel: '模型',
     bannerCwd: '目录',
-    thinkingLabel: '✻  思考',
+    thinkingLabel: '思考',
     chars: '字符',
     imagePasting: '正在读取剪贴板图片…',
     imageAttached: (n, size) => `📎 图片 #${n} 已附加(${size}),将随下一条消息发送`,
@@ -104,6 +106,10 @@ const STRINGS = {
     imageListEmpty: '当前没有待发送的图片(Alt+V 粘贴或 /image <路径> 附加)',
     imageCleared: '已清除待发送的图片',
     imageSending: (n) => `📎 附带 ${n} 张图片`,
+    addModelTitle: '添加模型配置',
+    addModelSaved: (name) => `✓ 模型 "${name}" 已添加并切换为当前模型`,
+    addModelCancelled: '已取消添加模型',
+    addModelSaveError: (msg) => `保存配置失败: ${msg}`,
   },
   en: {
     noModel: 'No AI model configured. Add one in GUI settings first (run `g ui`).',
@@ -130,7 +136,7 @@ const STRINGS = {
     prompt: '❯ ',
     bannerModel: 'Model',
     bannerCwd: 'CWD',
-    thinkingLabel: '✻  Thinking',
+    thinkingLabel: 'Thinking',
     chars: 'chars',
     imagePasting: 'Reading clipboard image…',
     imageAttached: (n, size) => `📎 Image #${n} attached (${size}); sent with your next message`,
@@ -140,6 +146,10 @@ const STRINGS = {
     imageListEmpty: 'No pending images (Alt+V to paste, or /image <path>)',
     imageCleared: 'Pending images cleared',
     imageSending: (n) => `📎 ${n} image(s) attached`,
+    addModelTitle: 'Add Model Configuration',
+    addModelSaved: (name) => `✓ Model "${name}" added and switched to`,
+    addModelCancelled: 'Add model cancelled',
+    addModelSaveError: (msg) => `Failed to save: ${msg}`,
   },
 }
 
@@ -164,13 +174,24 @@ function buildSystemPrompt({ cwd, locale, shellDesc }) {
 
 # 运行环境
 - 操作系统: ${process.platform}
-- Shell: ${shellDesc}${isWin ? `
-- 注意:Windows cmd 没有 head/grep/ls/sed/cat/tail 等 Unix 命令,直接跑会报"不是内部或外部命令"。
-  列目录用 list_files、搜内容用 search_text、看文件用 read_file,优先用工具而不是 shell;
-  必须跑 shell 时优先跨平台写法(如 node -e "..."),别用 Unix 专属命令` : ''}
+- Shell: ${shellDesc}
 - 当前工作目录: ${cwd}(用户在此启动 g ai,也是所有相对路径的基准)
 - 当前时间: ${now}
 
+# 平台兼容性(重要!)
+- 必须使用与当前 Shell 兼容的命令,禁止盲套 Unix 写法
+${isWin ? `- 当前是 Windows cmd.exe,以下 Unix 命令**不存在**,用了必定报"不是内部或外部命令":
+  tail / head / cat / grep / ls / sed / awk / wc / cut / uniq / xargs / which / touch
+  平台守卫会在执行前拦截这些命令,但请主动避免,不要浪费一轮调用
+- 跨平台替代方案:
+  · 列目录 → list_files 工具 或 cmd 的 dir
+  · 搜内容 → search_text 工具 或 cmd 的 findstr
+  · 看文件 → read_file 工具 或 cmd 的 type
+  · 看输出末尾 → PowerShell "命令 | Select-Object -Last N"
+  · 文本处理 → node -e "..." 或 PowerShell
+  · 查命令路径 → cmd 的 where(不是 which)
+- 必须跑 shell 时优先跨平台写法(如 node -e "..."),别用 Unix 专属命令` : `- 当前是 POSIX 环境,Unix 命令可用`}
+
 # 权限(用户已明确授权,无需反复征求同意)
 - 工作目录内:读写文件、执行命令等所有操作直接执行
 - 其他目录:同样可以读取和修改
@@ -203,13 +224,24 @@ function buildSystemPrompt({ cwd, locale, shellDesc }) {
 
 # Environment
 - OS: ${process.platform}
-- Shell: ${shellDesc}${isWin ? `
-- Note: Windows cmd has NO Unix commands (head/grep/ls/sed/cat/tail); running them fails with "not recognized".
-  Use the tools instead: list_files for directories, search_text for content, read_file for files.
-  For shell one-offs, prefer cross-platform forms like node -e "..."` : ''}
+- Shell: ${shellDesc}
 - Working directory: ${cwd} (where the user launched g ai; base for all relative paths)
 - Current time: ${now}
 
+# Platform compatibility (important!)
+- You MUST use commands compatible with the current shell. Do NOT blindly copy Unix patterns.
+${isWin ? `- This is Windows cmd.exe. The following Unix commands do NOT exist here and will fail with "not recognized":
+  tail / head / cat / grep / ls / sed / awk / wc / cut / uniq / xargs / which / touch
+  A platform guard will block these before execution, but avoid them proactively — don't waste a turn.
+- Cross-platform alternatives:
+  · List dirs → list_files tool, or cmd's dir
+  · Search content → search_text tool, or cmd's findstr
+  · Read files → read_file tool, or cmd's type
+  · Tail output → PowerShell "command | Select-Object -Last N"
+  · Text processing → node -e "..." or PowerShell
+  · Find executable → cmd's where (not which)
+- For shell one-offs, prefer cross-platform forms like node -e "..."` : `- POSIX environment: Unix commands are available`}
+
 # Permissions (explicitly granted by the user — do not keep asking)
 - Inside the working directory: read/write files and run commands directly
 - Other directories: may also be read and modified
@@ -334,6 +366,33 @@ function trimHistory(messages) {
   messages.splice(1, cut - 1)
 }
 
+// ──────────────────────────────────────────────
+// 消息消毒:确保发给 LLM 的消息数组里没有空内容。
+//
+// 背景:部分 LLM provider(如 Moonshot/Kimi、智谱、火山引擎等)对 assistant
+// 消息的 content 字段校验严格 —— 当模型只返回 tool_calls 而没有文本时,
+// content 为空字符串 "" 会被拒绝并报 "chat content is empty (2013)"。
+// OpenAI 官方规范允许 assistant 消息在带 tool_calls 时 content 为 null,
+// 本函数将空字符串统一转为 null,并对 tool/user 消息做兜底防止空内容。
+// ──────────────────────────────────────────────
+export function sanitizeMessages(messages) {
+  for (const m of messages) {
+    if (typeof m.content !== 'string') continue
+    if (m.content === '') {
+      if (m.role === 'assistant') {
+        // assistant 带 tool_calls 时 content 用 null(OpenAI 规范);
+        // 不带 tool_calls 的空内容也用 null,provider 通常可接受
+        m.content = null
+      } else if (m.role === 'tool') {
+        m.content = '(no output)'
+      } else if (m.role === 'user') {
+        m.content = ' '
+      }
+    }
+  }
+  return messages
+}
+
 // ──────────────────────────────────────────────
 // 多模态历史:base64 图片很占上下文,只保留"最近一条带图消息"里的图片,
 // 更早消息里的 image_url 部件降级为文字占位(模型仍知道这里曾有图)
@@ -387,7 +446,7 @@ async function runAgentTurn(state, userText, t, images = []) {
     const stopSpinner = () => {
       if (!spinnerStopped) { spinner.stop(); spinnerStopped = true }
     }
-    // 每次 LLM 调用一个 writer:思考灰斜体、正文 ⏺ + 逐行 markdown
+    // 每次 LLM 调用一个 writer:思考(橙黄斜体)+ 正文 ➤ 子弹头 + 逐行 markdown
     const writer = createAssistantWriter({
       showThinking: state.showThinking,
       thinkingHeader: t.thinkingLabel,
@@ -404,6 +463,9 @@ async function runAgentTurn(state, userText, t, images = []) {
       else writer.writeContent(text)
     }
 
+    // 发送前消毒:确保历史里没有空 content 的消息(部分 provider 报 2013)
+    sanitizeMessages(state.messages)
+
     let result
     try {
       result = await streamChatOnce({
@@ -440,12 +502,13 @@ async function runAgentTurn(state, userText, t, images = []) {
 
     // 无工具调用:本轮结束,assistant 文本入历史
     if (toolCalls.length === 0) {
-      state.messages.push({ role: 'assistant', content: content || '' })
+      state.messages.push({ role: 'assistant', content: content || null })
       return
     }
 
     // 有工具调用:assistant(带 tool_calls)入历史,然后逐个执行
-    state.messages.push({ role: 'assistant', content: content || '', tool_calls: toolCalls })
+    // content 为 null 而非空字符串:部分 provider 拒绝空字符串内容(2013 错误)
+    state.messages.push({ role: 'assistant', content: content || null, tool_calls: toolCalls })
 
     for (const tc of toolCalls) {
       const name = tc.function?.name || ''
@@ -491,6 +554,7 @@ function printSlashHelp(t, locale) {
   const lines = zh ? [
     '  /help             显示本帮助',
     '  /model            列出可用模型;/model <序号> 切换模型',
+    '  /addmodel         添加新的模型配置(交互式向导)',
     '  /cd <路径>        切换智能体工作目录',
     '  /image [路径]     查看待发送图片;/image <路径> 附加本地图片;/image clear 清除',
     '  /think            开关思考过程显示',
@@ -504,6 +568,7 @@ function printSlashHelp(t, locale) {
   ] : [
     '  /help             Show this help',
     '  /model            List models; /model <n> to switch',
+    '  /addmodel         Add a new model (interactive wizard)',
     '  /cd <path>        Change agent working directory',
     '  /image [path]     List pending images; attach a file; /image clear to reset',
     '  /think            Toggle thinking display',
@@ -582,6 +647,47 @@ async function handleSlashCommand(state, input, t) {
     printOk(t.modelSwitched(modelLabel(state.model)))
     return 'ok'
   }
+  if (cmd === '/addmodel') {
+    // 智能体执行中不允许启动向导:向导的 rl.question 会与流式输出交错,体验混乱
+    if (state.busy) {
+      printDim(t.busy)
+      return 'ok'
+    }
+    state.inWizard = true
+    try {
+      console.log(chalk.cyan.bold('\n' + t.addModelTitle))
+      // 复用 modelSetup 的交互式收集逻辑(服务商 → 接口 → 模型名 → Key → 显示名 → 测试)
+      const collected = await collectModelInput({
+        locale: state.locale,
+        rl: state.rl,
+        cancelMessage: t.addModelCancelled,
+      })
+      if (!collected) return 'ok'
+      const { baseURL, model, apiKey, displayName } = collected
+      // 构建模型配置(isDefault=false:/addmodel 只是追加,不改默认模型)
+      const newModel = buildModelConfig({ baseURL, model, apiKey, name: displayName, isDefault: false })
+      // 持久化到 ~/.git-commit-tool.json 顶层 models 数组
+      const cfg = await config.loadConfig()
+      const models = Array.isArray(cfg.models) ? cfg.models : []
+      models.push(newModel)
+      cfg.models = models
+      try {
+        await config.saveConfig(cfg)
+      } catch (err) {
+        printError(t.addModelSaveError(err.message))
+        return 'ok'
+      }
+      // 同步 REPL 状态:更新模型列表 + 自动切换到新模型(用户刚添加,大概率想立刻用)
+      state.models = models
+      state.model = newModel
+      printOk(t.addModelSaved(displayName || model))
+    } catch (err) {
+      printError(err.message)
+    } finally {
+      state.inWizard = false
+    }
+    return 'ok'
+  }
   if (cmd === '/cd') {
     if (!arg) { console.log(state.ctx.cwd); return 'ok' }
     const { resolve } = await import('node:path')
@@ -617,11 +723,15 @@ export async function runAiAgent(argv = []) {
     return
   }
 
-  const models = Array.isArray(cfg.models) ? cfg.models : []
+  let models = Array.isArray(cfg.models) ? cfg.models : []
   if (models.length === 0) {
-    console.error(chalk.red(t.noModel))
-    process.exitCode = 1
-    return
+    // 未配置模型:启动交互式配置向导,参照 g ui 设置里的"添加模型"
+    const setupResult = await runModelSetup({ locale })
+    if (!setupResult) {
+      process.exitCode = 1
+      return
+    }
+    models = setupResult.models
   }
 
   // --model=<序号|名称> 选择模型;默认 isDefault,否则第一个
@@ -664,6 +774,8 @@ export async function runAiAgent(argv = []) {
     showThinking: true,     // /think 切换:是否回显模型的思考过程
     pendingImages: [],      // Alt+V / /image 附加的待发送图片 [{path, bytes}]
     pasting: false,         // 剪贴板读取进行中(防 Alt+V 连打并发)
+    inWizard: false,        // /addmodel 交互式向导进行中:忽略 REPL 的 line 事件
+    rl: null,               // REPL readline 引用(供 /addmodel 复用做 rl.question)
   }
 
   // SIGINT 时中止进行中的 LLM 请求 + 正在跑的子命令
@@ -684,7 +796,7 @@ export async function runAiAgent(argv = []) {
 
   // ── 交互模式(REPL)──
   printBanner({
-    title: 'g ai — AI Agent',
+    title: 'Zen GitSync — AI Agent',
     modelLabel: modelLabel(model),
     baseURL: model.baseURL || '',
     cwd,
@@ -696,9 +808,12 @@ export async function runAiAgent(argv = []) {
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: chalk.cyan.bold(t.prompt),
+    // prompt: ❯ 用青色加粗;末尾追加 ANSI 亮白+加粗码,
+    // 让用户输入的文本继承亮白色高亮(黑底上最清晰)
+    prompt: chalk.cyan.bold(t.prompt) + '\x1b[1;97m',
     historySize: 200,
   })
+  state.rl = rl  // 供 /addmodel 等需要 rl.question 的斜杠命令复用
 
   // 输入提示符管理。
   //
@@ -756,6 +871,35 @@ export async function runAiAgent(argv = []) {
     if (!state.busy) safeShowPrompt()
   }
 
+  // ── 斜杠命令即时提示 ──
+  // 在提示符下方浮现匹配到的命令,随输入过滤;不移动光标(用 DECSC/DECRC 保存-恢复)。
+  // slashHintRows 记录当前提示占了几行,下次刷新/提交时据此擦除,避免残影。
+  let slashHintRows = 0
+  const eraseSlashHint = () => {
+    if (!process.stdout.isTTY || slashHintRows === 0) return
+    // 保存光标 → 下移到提示区逐行清空 → 恢复光标
+    let seq = '\x1b7'
+    for (let i = 0; i < slashHintRows; i++) seq += '\x1b[1B\x1b[2K'
+    seq += '\x1b8'
+    process.stdout.write(seq)
+    slashHintRows = 0
+  }
+  const renderSlashHint = () => {
+    if (!process.stdout.isTTY || state.busy || state.inWizard) { return }
+    const matches = filterSlashCommands(rl.line, state.locale)
+    const body = renderSlashHintBody(matches)
+    // 先擦掉旧提示(行数可能变化),再画新的
+    eraseSlashHint()
+    if (!body) return
+    const rows = body.split('\n')
+    // 保存光标,逐行下移打印(每行先清行防止与旧内容叠字),最后恢复光标回输入行
+    let seq = '\x1b7'
+    for (const r of rows) seq += '\x1b[1B\x1b[2K\r' + r
+    seq += '\x1b8'
+    process.stdout.write(seq)
+    slashHintRows = rows.length
+  }
+
   // Alt+V 粘贴剪贴板图片(node 把 ESC+v 解析为 meta+v;部分终端不发 Alt,可用 /image 兜底)
   const pasteFromClipboard = async () => {
     if (state.pasting) return
@@ -777,6 +921,13 @@ export async function runAiAgent(argv = []) {
     }
   }
   rl.input.on('keypress', (ch, key) => {
+    // Enter 提交由 line 处理器负责擦除提示,这里不重画(此刻 readline 已换行,
+    // 光标不在输入行,重画会错位)
+    if (!(key && (key.name === 'return' || key.name === 'enter'))) {
+      // 每次按键后即时刷新斜杠命令提示(readline 已先处理完本次按键,rl.line 为最新值)。
+      // 非 slash / 无匹配时 renderSlashHint 会把上一次的提示擦掉。
+      renderSlashHint()
+    }
     if (!key) return
     const isAltV = (key.meta && key.name === 'v')
       || (typeof key.sequence === 'string' && key.sequence.length === 2
@@ -789,6 +940,15 @@ export async function runAiAgent(argv = []) {
   rl.prompt()
 
   rl.on('line', async (line) => {
+    // 提交时光标已落到提示符下一行(即提示区起点),直接清到屏幕末尾擦掉整块提示,
+    // 比 DECSC/DECRC 相对定位更稳(此时光标不在输入行)
+    if (process.stdout.isTTY && slashHintRows > 0) {
+      process.stdout.write('\x1b[0J')
+      slashHintRows = 0
+    }
+    // /addmodel 等交互式向导进行中时,用户的回答由向导自身的 rl.question 处理,
+    // 不应进入 REPL 的正常输入流程(否则会把向导的答案当成命令/消息发给模型)
+    if (state.inWizard) return
     const input = line.trim()
 
     if (input.startsWith('/')) {

package/src/cli/ai/agent.test.js

@@ -17,7 +17,7 @@
 // 且切口把 "src/cli/ai/agent.js" 从中间切断显示成 "rc/cli/ai/agent.js"。
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { truncateDisplay, stripStaleImages } from './agent.js'
+import { truncateDisplay, stripStaleImages, sanitizeMessages } from './agent.js'
 
 const LIMIT = 600
 
@@ -112,3 +112,79 @@ test('stripStaleImages: en locale 用英文占位符', () => {
   assert.equal(messages[0].content[0].text, '[image omitted from history]')
   assert.equal(messages[1].content[0].type, 'image_url')
 })
+
+// ── sanitizeMessages:空 content 消毒(防止 provider 报 2013) ──
+test('sanitizeMessages: assistant 空 content 转 null(带 tool_calls 场景)', () => {
+  const messages = [
+    { role: 'system', content: 'sys' },
+    { role: 'user', content: 'hi' },
+    { role: 'assistant', content: '', tool_calls: [{ id: 'tc1', type: 'function', function: { name: 'read_file', arguments: '{}' } }] },
+    { role: 'tool', tool_call_id: 'tc1', name: 'read_file', content: 'file contents...' },
+  ]
+  sanitizeMessages(messages)
+  assert.equal(messages[2].content, null, 'assistant 空 content 应转为 null')
+  assert.ok(messages[2].tool_calls, 'tool_calls 应保留不动')
+})
+
+test('sanitizeMessages: assistant 空 content 转 null(无 tool_calls)', () => {
+  const messages = [
+    { role: 'assistant', content: '' },
+  ]
+  sanitizeMessages(messages)
+  assert.equal(messages[0].content, null)
+})
+
+test('sanitizeMessages: tool 空 content 兜底为 (no output)', () => {
+  const messages = [
+    { role: 'tool', tool_call_id: 'tc1', name: 'run_command', content: '' },
+  ]
+  sanitizeMessages(messages)
+  assert.equal(messages[0].content, '(no output)')
+})
+
+test('sanitizeMessages: user 空 content 兜底为空格', () => {
+  const messages = [
+    { role: 'user', content: '' },
+  ]
+  sanitizeMessages(messages)
+  assert.equal(messages[0].content, ' ')
+})
+
+test('sanitizeMessages: 非空 content 不受影响', () => {
+  const messages = [
+    { role: 'system', content: 'sys' },
+    { role: 'user', content: 'hello' },
+    { role: 'assistant', content: 'world' },
+    { role: 'tool', tool_call_id: 'tc1', name: 'read_file', content: 'output' },
+  ]
+  const snapshot = JSON.parse(JSON.stringify(messages))
+  sanitizeMessages(messages)
+  assert.deepEqual(messages, snapshot)
+})
+
+test('sanitizeMessages: 数组 content(多模态)不受影响', () => {
+  const messages = [
+    { role: 'user', content: [{ type: 'text', text: 'hi' }, { type: 'image_url', image_url: { url: 'data:...' } }] },
+  ]
+  const snapshot = JSON.parse(JSON.stringify(messages))
+  sanitizeMessages(messages)
+  assert.deepEqual(messages, snapshot)
+})
+
+test('sanitizeMessages: 模拟真实工具调用流程后消息数组无空 content', () => {
+  // 模拟:模型只返回 tool_calls 没有文本 → 工具执行 → 下次请求
+  const messages = [
+    { role: 'system', content: 'sys prompt' },
+    { role: 'user', content: '帮我读一下文件' },
+    { role: 'assistant', content: '', tool_calls: [{ id: 'tc1', type: 'function', function: { name: 'read_file', arguments: '{"path":"a.js"}' } }] },
+    { role: 'tool', tool_call_id: 'tc1', name: 'read_file', content: '1→hello' },
+  ]
+  sanitizeMessages(messages)
+  // 消毒后所有消息的 content 都不应是空字符串
+  for (const m of messages) {
+    if (typeof m.content === 'string') {
+      assert.ok(m.content.length > 0, `role=${m.role} 的 content 不应为空字符串`)
+    }
+  }
+  assert.equal(messages[2].content, null, 'assistant 空 content 应为 null')
+})