zen-gitsync 2.18.20 → 2.18.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-gitsync",
-  "version": "2.18.20",
+  "version": "2.18.22",
   "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",
@@ -48,6 +48,9 @@
     "verify:agent-prompt-settings:reverse": "node scripts/verify-agent-prompt-settings.cjs --reverse",
     "verify:agent-input-facts": "node scripts/verify-agent-input-facts.cjs",
     "verify:agent-input-facts:reverse": "node scripts/verify-agent-input-facts.cjs --reverse",
+    "verify:agent-presets": "node scripts/verify-agent-presets.cjs",
+    "verify:agent-presets:reverse": "node scripts/verify-agent-presets.cjs --reverse",
+    "verify:preset-scopes": "node scripts/verify-preset-scopes.cjs",
     "verify:wb-dialogs": "node scripts/verify-workbench-dialogs.cjs",
     "verify:wb-dispatch": "node scripts/verify-workbench-dispatch-attach.cjs",
     "verify:wb-env-context": "node scripts/verify-workbench-env-context.mjs",

package/src/cli/ai/agent.js

@@ -19,8 +19,9 @@
 // 能力:
 //   - 默认使用 g ui 里配置的模型(~/.zen-gitsync/config.json 顶层 models,
 //     isDefault 优先,否则取第一个);--model=<序号|名称> 或会话内 /model 切换
-//   - OpenAI 兼容流式 function calling:模型可以调用 run_command /
-//     read_file / write_file / edit_file / list_files / search_text / ask_user
+//   - OpenAI 兼容流式 function calling:模型可以调用内置工具(文件读写、
+//     命令执行、搜索、后台任务、计划、问用户…完整清单见 tools.js 的 TOOL_DEFINITIONS)
+//   - 同一轮的只读工具并发执行(连续的 read/search 合成一批),写类与命令串行
 //   - 图片:Alt+V 粘贴剪贴板图片、/image <路径> 附加本地图片,
 //     以多模态(image_url)消息发给模型(需模型支持视觉)
 //   - 权限:启动目录内全开放,其他目录可读写;唯一红线由 safety.js 拦截
@@ -76,6 +77,7 @@ const STRINGS = {
     llmRetrying: (attempt, max, reason) => `LLM 请求中断,正在重试(第 ${attempt}/${max} 次): ${reason}`,
     toolIterLimit: (n) => `已达单轮最大工具调用次数(${n}),本轮结束。如需继续请再发一条消息。`,
     toolRunning: (name) => `执行 ${name}…`,
+    toolRunningBatch: (n) => `并行执行 ${n} 个工具…`,
     busy: '任务执行中，请稍候，或按 Ctrl+C 停止当前任务。',
     bye: '已退出 g ai',
     cleared: '对话历史已清空',
@@ -136,6 +138,7 @@ const STRINGS = {
     llmRetrying: (attempt, max, reason) => `LLM request interrupted, retrying (${attempt}/${max}): ${reason}`,
     toolIterLimit: (n) => `Hit max tool iterations (${n}) for this turn. Send another message to continue.`,
     toolRunning: (name) => `Running ${name}…`,
+    toolRunningBatch: (n) => `Running ${n} tools in parallel…`,
     busy: 'Agent is working. Wait or press Ctrl+C to stop the task.',
     bye: 'Bye',
     cleared: 'Conversation cleared',
@@ -293,6 +296,8 @@ ${isWin ? `- 当前是 Windows cmd.exe,以下 Unix 命令**不存在**,用了必
 - 大文件用 offset/limit 分段读取,不要一次读爆上下文
 - git 操作用 run_command 执行;提交代码可以用 git 命令,也可以用本 CLI 的 g -y(默认信息提交并推送)或 g --ai(AI 生成提交信息)
 - run_command 默认就在工作目录执行,不要再加 cd / cd /d 前缀;默认超时 120 秒,长任务加大 timeout_seconds(最大 600)
+- 起 dev server / watch / 监听端口这类不会自己结束的命令,用 run_in_background=true(立刻拿到 bg_N),再用 background_task 看日志或 kill;直接前台跑只会一直占着,到超时被杀
+- 一轮里要读多个文件 / 搜多处时,把它们放进同一次响应里一起发 —— 只读工具会并发执行,比一个个来回快得多
 - 命令在 ${shellDesc} 下执行,注意语法兼容
 - 先读取当前项目的规范、依赖与测试配置，再选择对应的验证命令，不要假定所有项目都使用 npm
 - 用户要求概述或简短回答时，只读取必要的结构与入口文件，控制探索范围
@@ -400,6 +405,8 @@ ${isWin ? `- This is Windows cmd.exe. The following Unix commands do NOT exist h
 - Read large files in segments (offset/limit)
 - Git operations go through run_command; to commit, use git commands or this CLI's g -y / g --ai
 - run_command already executes in the working directory — do NOT prefix with cd; default timeout 120s, raise timeout_seconds (max 600) for long tasks
+- For processes that never exit on their own (dev server, watch, port listeners) pass run_in_background=true (you get a bg_N id immediately), then use background_task to read logs or kill it; running them in the foreground just blocks until the timeout kills them
+- When a turn needs several files or several searches, issue them in the same response — read-only tools run concurrently, which is far faster than one round-trip each
 - Commands run under ${shellDesc}; keep syntax compatible
 - Read this project's instructions, dependencies and test configuration before choosing verification commands; do not assume npm
 - For a brief overview, inspect only the necessary structure and entry points; keep exploration proportional to the request

package/src/cli/ai/extensions.js

@@ -18,7 +18,7 @@
 //   - 失败一律降级,绝不让扩展问题变成 "g ai 起不来"
 //   - /cwd 切换工作目录时要能重新解析项目级扩展,同时关掉旧目录起的子进程
 //
-// 与 tools.js 的关系:内置 7 个工具是**底座**,永远存在。
+// 与 tools.js 的关系:内置工具(见 TOOL_DEFINITIONS)是**底座**,永远存在。
 // 这里的 MCP 工具是**叠加**,名字以 mcp__ 开头,由 agent 循环按名字分流;
 // 名字不认识时返回 null,让调用方回落内置工具 —— 所以扩展全挂也不影响原有能力。
 

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

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict'
 import { streamChatOnce } from './transport.js'
 import { normalizeUsage, addUsage } from './telemetry.js'
 import { runAgentTurn } from './turn.js'
+import { splitToolBatches } from './tools.js'
 import { buildRequestMessages, repairToolHistory, resolveRequestBudget } from './context.js'
 import { createAssistantWriter, stripAnsi } from './termui.js'
 
@@ -188,6 +189,8 @@ test('用户点了停止就不再重试', async () => {
 })
 
 const call = n => ({ id: `call${n}`, type: 'function', function: { name: 'read_file', arguments: '{}' } })
+const readCall = (n, file) => ({ id: `call${n}`, type: 'function', function: { name: 'read_file', arguments: JSON.stringify({ path: file }) } })
+const writeCall = n => ({ id: `call${n}`, type: 'function', function: { name: 'write_file', arguments: '{}' } })
 const askCall = (id = 'ask1') => ({ id, type: 'function', function: {
   name: 'ask_user',
   arguments: JSON.stringify({ question: 'Which option?', options: ['A', 'B'], allow_free_text: false }),
@@ -277,8 +280,10 @@ test('ask_user pauses a turn until the answer arrives, then continues the model
 
 test('cancellation during a tool skips the remaining batch and keeps valid tool history', async () => {
   const s = state(), executed = []
+  // 用写类工具验取消语义:只读工具现在会并发,取消时它们早已一起发出去了;
+  // 真正需要"取消后别再动"的是写文件这种有副作用的操作。
   const stats = await runAgentTurn(s, 'task', strings, [], { ui: quiet,
-    chat: async () => ({ content: '', toolCalls: [call(1), call(2)] }),
+    chat: async () => ({ content: '', toolCalls: [writeCall(1), writeCall(2)] }),
     execute: async name => { executed.push(name); s.abortController.abort(); return 'first result' },
   })
   assert.equal(stats.status, 'cancelled')
@@ -324,3 +329,54 @@ test('resume marks missing tool results without replaying actions', () => {
   assert.equal(repaired[3].tool_call_id, 'call2')
   assert.match(repaired[3].content, /status is unknown/)
 })
+
+test('consecutive read-only calls in one round run concurrently and keep call order', async () => {
+  const s = state()
+  let active = 0, maxActive = 0, round = 0
+  const stats = await runAgentTurn(s, 'task', strings, [], { ui: quiet,
+    chat: async () => (++round === 1
+      ? { content: '', toolCalls: [readCall(1, 'a.js'), readCall(2, 'b.js'), readCall(3, 'c.js')] }
+      : { content: 'done', toolCalls: [] }),
+    execute: async (name, args) => {
+      active++
+      maxActive = Math.max(maxActive, active)
+      await new Promise(resolve => setTimeout(resolve, 15))
+      active--
+      return `contents of ${args.path}`
+    },
+  })
+
+  assert.equal(stats.status, 'completed')
+  // 真并发:三个工具的执行区间必须重叠(串行时 maxActive 恒为 1)
+  assert.equal(maxActive, 3, '只读工具应该同时执行')
+  assert.equal(stats.toolCalls, 3)
+  const tools = s.messages.filter(m => m.role === 'tool')
+  assert.deepEqual(tools.map(m => m.tool_call_id), ['call1', 'call2', 'call3'], 'tool 消息必须按模型给的顺序入栈')
+  assert.deepEqual(tools.map(m => m.content), ['contents of a.js', 'contents of b.js', 'contents of c.js'])
+})
+
+test('write tools break the parallel batch instead of joining it', () => {
+  const batches = splitToolBatches([call(1), call(2), writeCall(3), call(4), call(5)])
+  assert.deepEqual(batches.map(b => [b.parallel, b.calls.length]), [[true, 2], [false, 1], [true, 2]])
+  // 单个只读工具没必要走并发路径(多一层 Promise 包装和聚合 spinner)
+  assert.deepEqual(splitToolBatches([call(1)]).map(b => b.parallel), [false])
+})
+
+test('one throwing tool in a parallel batch does not drop its siblings', async () => {
+  const s = state()
+  let round = 0
+  const stats = await runAgentTurn(s, 'task', strings, [], { ui: quiet,
+    chat: async () => (++round === 1
+      ? { content: '', toolCalls: [readCall(1, 'a.js'), readCall(2, 'boom.js')] }
+      : { content: 'done', toolCalls: [] }),
+    execute: async (_name, args) => {
+      if (args.path === 'boom.js') throw new Error('disk on fire')
+      return 'ok'
+    },
+  })
+  assert.equal(stats.status, 'completed')
+  const tools = s.messages.filter(m => m.role === 'tool')
+  assert.equal(tools.length, 2)
+  assert.equal(tools[0].content, 'ok')
+  assert.match(tools[1].content, /disk on fire/)
+})

package/src/cli/ai/termui.js

@@ -721,7 +721,16 @@ export function summarizeToolArgs(name, args, { chars = '字符' } = {}) {
   }
   switch (name) {
     case 'run_command':
-      return '$ ' + clamp(args?.command)
+      // 后台命令必须一眼看出来:否则卡片显示的命令和普通命令一样,用户不知道它还在跑
+      return (args?.run_in_background ? '[后台] $ ' : '$ ') + clamp(args?.command)
+    case 'background_task': {
+      const action = String(args?.action || 'read')
+      if (action === 'list') return '列出后台任务'
+      const id = String(args?.id || '')
+      if (action === 'kill') return clamp(`停止 ${id}`)
+      const wait = Number(args?.wait_seconds) || 0
+      return clamp(`${id || '?'}${wait ? ` · 等 ${wait}s` : ''}`)
+    }
     case 'read_file': {
       const range = (args?.offset || args?.limit)
         ? ` L${args?.offset || 1}-${(args?.offset || 1) + (args?.limit || 2000) - 1}`
@@ -752,7 +761,7 @@ export function summarizeToolArgs(name, args, { chars = '字符' } = {}) {
 export function printToolHeader(name, summary, write = (s) => process.stdout.write(s), { locale = 'zh-CN' } = {}) {
   // ▶ 保留青色作为工具执行的标识色;name 用白色加粗与下方结果区分;
   // summary 用浅灰(#a0aec0)— dim 在黑底下太暗看不清,浅灰可读且仍比 name 低调
-  const labels = { run_command: '执行命令', read_file: '读取文件', write_file: '写入文件', edit_file: '修改文件', list_files: '浏览目录', search_text: '搜索内容', update_plan: '更新计划' }
+  const labels = { run_command: '执行命令', background_task: '后台任务', read_file: '读取文件', write_file: '写入文件', edit_file: '修改文件', list_files: '浏览目录', search_text: '搜索内容', update_plan: '更新计划' }
   const rows = wrapTerminalText(summary || '', Math.max(16, Math.min(100, termWidth() - 6)))
   const label = String(locale).startsWith('en') ? name : labels[name] || name
   write('\n' + chalk.cyan('▸ ') + chalk.bold.white(label) + (label !== name ? chalk.gray(`  ${name}`) : '') + '\n')

package/src/cli/ai/tools.js

@@ -60,6 +60,12 @@ const MAX_IMAGE_BYTES = 4 * 1024 * 1024   // read_image 单张上限(原始字
 // 超了让模型自己先压缩(它手上有 run_command),比我们默默截断成半张图好。
 const CMD_TIMEOUT_DEFAULT = 120    // run_command 默认超时(秒)
 const CMD_TIMEOUT_MAX = 600        // run_command 超时上限(秒)
+// 后台命令的输出缓冲上限(字符,stdout/stderr 各一份)。dev server 一晚上能吐几十兆,
+// 全留着会把 agent 进程撑爆;超了丢最老的,记住丢了多少在结果里说明。
+const MAX_BG_CHARS = 100000
+// 同时保留的后台任务数。g ai 是长会话工具,模型忘了 kill 的命令会堆积,
+// 超过就淘汰最老的**已结束**任务(还在跑的绝不淘汰,那是用户的服务)。
+const MAX_BG_TASKS = 20
 
 // 已知的长耗时命令(装依赖 / 构建 / 测试 / clone …)。模型不给 timeout_seconds 时
 // 默认只有 120s,这类命令经常跑不完就被终止,模型再换个写法重试 —— 白等好几轮。
@@ -90,6 +96,36 @@ const BINARY_EXTS = new Set([
   '.map', '.jar', '.class', '.pyc',
 ])
 
+// ──────────────────────────────────────────────
+// 并发执行分组(CLI 的 turn.js 与 Web 智能体的 agentChat.js 共用一份口径)
+// ──────────────────────────────────────────────
+//
+// 可以并发的工具:只读、无终端交互、彼此没有先后依赖。
+// 写类(edit_file / write_file)和 run_command 绝不能进这个名单 —— 模型经常在同一轮里
+// 发「write_file + run_command」表示"写完就跑",并发会把顺序打乱,命令可能在文件落盘前执行。
+// 用白名单而不是黑名单:漏加一个只读工具只是慢,错加一个写工具会改错文件。
+export const PARALLEL_SAFE_TOOLS = new Set([
+  'read_file', 'read_image', 'list_files', 'search_text', 'list_projects',
+])
+
+/**
+ * 把同一轮的 tool_calls 切成执行批次:连续的只读工具合成一个并发批,其余各自成批。
+ * 长度为 1 的批强制走串行路径 —— 单元素并发只会多一层 Promise 包装。
+ *
+ * @param {Array<object>} toolCalls - assistant 消息里的 tool_calls
+ * @returns {Array<{ parallel: boolean, calls: Array<object> }>}
+ */
+export function splitToolBatches(toolCalls) {
+  const batches = []
+  for (const call of toolCalls || []) {
+    const safe = PARALLEL_SAFE_TOOLS.has(call?.function?.name)
+    const last = batches[batches.length - 1]
+    if (safe && last?.parallel) last.calls.push(call)
+    else batches.push({ parallel: safe, calls: [call] })
+  }
+  return batches.map(b => (b.calls.length > 1 ? b : { parallel: false, calls: b.calls }))
+}
+
 // ──────────────────────────────────────────────
 // 工具 schema(OpenAI function calling 格式)
 // ──────────────────────────────────────────────
@@ -98,18 +134,39 @@ export const TOOL_DEFINITIONS = [
     type: 'function',
     function: {
       name: 'run_command',
-      description: '在系统默认 shell 执行一条命令(Windows 为 cmd.exe,POSIX 为 /bin/sh)。可用于构建、测试、安装依赖、git 操作(add/commit/push)、查看系统信息等。命令以当前用户权限运行;会把系统搞崩的命令(格式化、删根目录、关机等)会被安全守卫拒绝。',
+      description: '在系统默认 shell 执行一条命令(Windows 为 cmd.exe,POSIX 为 /bin/sh)。可用于构建、测试、安装依赖、git 操作(add/commit/push)、查看系统信息等。命令以当前用户权限运行;会把系统搞崩的命令(格式化、删根目录、关机等)会被安全守卫拒绝。'
+        + '要起**长时间运行**的东西(dev server、watch、监听端口、持续日志)请传 run_in_background=true —— 它会立刻返回一个后台任务 id,你用 background_task 去看输出或停掉它;直接在前台跑这类命令会一直占着直到超时被终止。',
       parameters: {
         type: 'object',
         properties: {
           command: { type: 'string', description: '要执行的完整命令行' },
           cwd: { type: 'string', description: '执行目录,默认是智能体启动目录;可传任意绝对/相对路径' },
-          timeout_seconds: { type: 'number', description: `超时秒数,默认 ${CMD_TIMEOUT_DEFAULT},最大 ${CMD_TIMEOUT_MAX}` },
+          timeout_seconds: { type: 'number', description: `超时秒数,默认 ${CMD_TIMEOUT_DEFAULT},最大 ${CMD_TIMEOUT_MAX};后台执行时忽略` },
+          run_in_background: { type: 'boolean', description: 'true = 后台执行,立刻拿到 bg_N 形式的任务 id,不阻塞本轮对话' },
         },
         required: ['command'],
       },
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'background_task',
+      description: '查看或停止 run_command 起的后台命令。'
+        + 'action=read(默认):拿到**自上次读取以来**的新增输出 + 当前状态(还在跑 / 已退出 + 退出码);'
+        + 'action=kill:终止该后台进程;action=list:列出全部后台任务。'
+        + '刚起服务时输出往往还没出来,直接 read 会拿到空内容 —— 用 wait_seconds 等几秒再返回,别连续空转轮询。',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['read', 'kill', 'list'], description: '要做的动作,默认 read' },
+          id: { type: 'string', description: 'run_command 返回的后台任务 id(形如 bg_1)。read / kill 必填' },
+          wait_seconds: { type: 'number', description: 'read 时最多等待多少秒(有新输出或进程退出就提前返回),默认 0,上限 60' },
+        },
+        required: [],
+      },
+    },
+  },
   {
     type: 'function',
     function: {
@@ -193,7 +250,9 @@ export const TOOL_DEFINITIONS = [
     type: 'function',
     function: {
       name: 'search_text',
-      description: '搜索正则匹配的行,返回 文件:行号: 内容。path 可以是目录(递归搜全部文本文件)或单个文件。用于定位符号、关键字、调用点。',
+      description: '搜索正则匹配的行,返回 文件:行号: 内容。path 可以是目录(递归搜全部文本文件)或单个文件。用于定位符号、关键字、调用点。'
+        + '只看"这个符号出现在哪些文件"用 files_only=true(比读完内容省很多 token);'
+        + '要看匹配处的上下午文(判断是不是真的那个调用点)用 context_lines。',
       parameters: {
         type: 'object',
         properties: {
@@ -201,6 +260,8 @@ export const TOOL_DEFINITIONS = [
           path: { type: 'string', description: '搜索目录或单个文件路径,默认智能体启动目录' },
           ext: { type: 'string', description: '限定扩展名过滤,如 "js" 或 "js,ts,vue";不传则搜全部文本文件' },
           ignore_case: { type: 'boolean', description: '忽略大小写,默认 false' },
+          files_only: { type: 'boolean', description: 'true = 只返回命中的文件路径(每个文件一次),不返回行内容' },
+          context_lines: { type: 'number', description: '每条命中前后各显示几行上下文,默认 0,上限 5。上下文行用 "文件-行号- 内容" 标记' },
         },
         required: ['pattern'],
       },
@@ -512,6 +573,178 @@ function execCommand(command, options) {
   })
 }
 
+// ──────────────────────────────────────────────
+// 后台命令(run_in_background)
+// ──────────────────────────────────────────────
+//
+// 为什么需要:起 dev server / watch / 监听端口这类命令在前台跑只会占着到超时被
+// terminateCommand 杀掉 —— 模型看不到启动成功的日志,用户还得自己再起一遍。
+// 后台执行让它立刻拿到输出句柄,继续干活。
+//
+// 与 execCommand 的区别:那边是"跑完给我结果"的 Promise,这边是"活着,随时能读"。
+// 输出按 stdout/stderr 分别缓冲,读走的部分记游标 —— 每次 read 只回**新增**内容,
+// 否则一个 dev server 的启动日志会被反复回喂进上下文。
+//
+// 生命周期:登记进 cleanup(trackChild),g ai 退出时统一终止。**不**接 ctx.onChild,
+// 所以 Ctrl+C 停当前任务不会顺手杀掉用户刚起的服务。
+const backgroundTasks = new Map()
+let bgSeq = 0
+
+function trimBackgroundTasks() {
+  if (backgroundTasks.size <= MAX_BG_TASKS) return
+  // Map 保持插入序:从最老的开始淘汰,但只淘汰已经结束的(还在跑的是用户的服务)
+  for (const [id, task] of backgroundTasks) {
+    if (backgroundTasks.size <= MAX_BG_TASKS) break
+    if (!task.running) backgroundTasks.delete(id)
+  }
+}
+
+function wakeBackgroundWaiters(task) {
+  const waiters = task.waiters
+  task.waiters = []
+  for (const resolve of waiters) resolve()
+}
+
+function spawnBackground(command, { cwd, env, onOutput }) {
+  const id = `bg_${++bgSeq}`
+  const child = spawn(command, {
+    cwd,
+    env,
+    shell: true,
+    detached: process.platform !== 'win32',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const task = {
+    id, command, cwd, child,
+    stdout: '', stderr: '',
+    stdoutRead: 0, stderrRead: 0,      // 已经回给模型的位置
+    dropped: 0,                         // 被缓冲上限挤掉的字符数
+    code: null, signal: null,
+    running: true,
+    startedAt: Date.now(), endedAt: null,
+    waiters: [],
+  }
+  // 增量解码:一次 data 事件可能切在多字节字符中间,留着尾巴等下一块
+  const decoders = { stdout: new TextDecoder('utf-8'), stderr: new TextDecoder('utf-8') }
+  const append = (stream, text) => {
+    if (!text) return
+    task[stream] += text
+    if (task[stream].length > MAX_BG_CHARS) {
+      const drop = task[stream].length - MAX_BG_CHARS
+      task[stream] = task[stream].slice(drop)
+      // 游标跟着一起往前挪,否则下次 read 会从被截掉的区域开始、吐出重复内容
+      task[`${stream}Read`] = Math.max(0, task[`${stream}Read`] - drop)
+      task.dropped += drop
+    }
+    // 实时推给界面(Web 端把它塞进那张卡的 result;CLI 不传,等于没有副作用)
+    if (typeof onOutput === 'function') {
+      try { onOutput(text) } catch { /* 推流失败不能影响进程本身 */ }
+    }
+    wakeBackgroundWaiters(task)
+  }
+  child.stdout?.on('data', buf => append('stdout', decoders.stdout.decode(buf, { stream: true })))
+  child.stderr?.on('data', buf => append('stderr', decoders.stderr.decode(buf, { stream: true })))
+  child.on('error', () => {})
+  child.on('close', (code, signal) => {
+    task.running = false
+    task.code = typeof code === 'number' ? code : 1
+    task.signal = signal || null
+    task.endedAt = Date.now()
+    // decoder 里可能还压着半个字符,进程都退了就不用等下一块了
+    append('stdout', decoders.stdout.decode())
+    append('stderr', decoders.stderr.decode())
+    wakeBackgroundWaiters(task)
+  })
+  trackChild(child)
+  backgroundTasks.set(id, task)
+  trimBackgroundTasks()
+  return task
+}
+
+/** 取出自上次读取以来的新增输出,并推进游标 */
+function takeBackgroundOutput(task) {
+  const out = { stdout: task.stdout.slice(task.stdoutRead), stderr: task.stderr.slice(task.stderrRead) }
+  task.stdoutRead = task.stdout.length
+  task.stderrRead = task.stderr.length
+  return out
+}
+
+/** 等新输出或进程退出,最多 seconds 秒(到点返回,不报错) */
+function waitForBackground(task, seconds) {
+  if (!(seconds > 0) || !task.running) return Promise.resolve()
+  return new Promise(resolve => {
+    const timer = setTimeout(done, seconds * 1000)
+    timer.unref?.()
+    function done() {
+      clearTimeout(timer)
+      task.waiters = task.waiters.filter(fn => fn !== done)
+      resolve()
+    }
+    task.waiters.push(done)
+  })
+}
+
+function describeBackground(task) {
+  const secs = Math.max(0, Math.round(((task.endedAt || Date.now()) - task.startedAt) / 1000))
+  return task.running
+    ? `[${task.id}] 运行中 · ${secs}s · ${task.command}`
+    : `[${task.id}] 已退出(exit ${task.code}${task.signal ? ` · ${task.signal}` : ''}) · ${secs}s · ${task.command}`
+}
+
+/**
+ * 后台任务是否还在跑。
+ * 给界面用:agentChat 在 background_task 返回后靠它判断"那个 bg 是不是已经结束了",
+ * 结束了就把原来那张"后台运行中"的卡改成完成。
+ * @returns {boolean|null} null = 没有这个 id 的任务
+ */
+export function backgroundTaskRunning(id) {
+  const task = backgroundTasks.get(String(id || ''))
+  return task ? task.running : null
+}
+
+async function toolBackgroundTask(args) {
+  const action = String(args.action || 'read').toLowerCase()
+
+  if (action === 'list') {
+    if (!backgroundTasks.size) return '当前没有后台任务。用 run_command({ run_in_background: true, ... }) 起一个。'
+    return [...backgroundTasks.values()].map(describeBackground).join('\n')
+  }
+
+  const id = String(args.id || '').trim()
+  if (!id) return `错误: ${action} 需要 id(就是 run_command 返回的那个 bg_N)`
+  const task = backgroundTasks.get(id)
+  if (!task) return `错误: 没有找到后台任务 ${id}。用 background_task({ action: "list" }) 看现有任务。`
+
+  if (action === 'kill') {
+    if (!task.running) return `${describeBackground(task)}\n它已经退出了,不需要停止。`
+    await terminateCommand(task.child)
+    // taskkill 是异步的:close 事件可能在上面 await 期间就已经落定了,
+    // 这时候再等 waiter 会白等满 5s(实测)
+    if (task.running) {
+      await new Promise(resolve => {
+        const timer = setTimeout(resolve, 5000)
+        timer.unref?.()
+        task.waiters.push(() => { clearTimeout(timer); resolve() })
+      })
+    }
+    return `已终止 ${describeBackground(task)}`
+  }
+
+  if (action !== 'read') return `错误: 未知 action "${action}"(支持 read / kill / list)`
+
+  const waitSec = Math.max(0, Math.min(60, Number(args.wait_seconds) || 0))
+  await waitForBackground(task, waitSec)
+  const { stdout, stderr } = takeBackgroundOutput(task)
+
+  const parts = [describeBackground(task)]
+  if (task.dropped) parts.push(`[缓冲区已丢弃最老的 ${task.dropped} 字符]`)
+  parts.push(stdout.trim() ? `--- 新增输出 ---\n${truncateMiddle(stdout.trimEnd(), MAX_CMD_OUTPUT)}` : '(stdout 无新增输出)')
+  if (stderr.trim()) parts.push(`--- 新增 stderr ---\n${truncateMiddle(stderr.trimEnd(), MAX_CMD_OUTPUT)}`)
+  if (!task.running) parts.push(`进程已结束,退出码 ${task.code}。`)
+  return parts.join('\n')
+}
+
 // ──────────────────────────────────────────────
 // 「建了仓库」的识别：run_command 之后把新项目顺手登记进常用目录
 // ──────────────────────────────────────────────
@@ -636,6 +869,19 @@ async function toolRunCommand(args, ctx) {
     return `错误: 执行目录不存在: ${cwd}`
   }
 
+  if (args.run_in_background) {
+    // PATH 补丁与前台一致:后台命令照样要能找到刚装的 CLI
+    const env = await augmentEnvPath({ ...process.env, FORCE_COLOR: '0' })
+    const task = spawnBackground(command, { cwd, env, onOutput: ctx.onOutput })
+    return [
+      `$ ${command}`,
+      `(后台运行 · id ${task.id} · pid ${task.child.pid || '?'})`,
+      `查看输出: background_task({ action: "read", id: "${task.id}", wait_seconds: 3 })`
+        + `(刚启动时日志还没出来,带上 wait_seconds 等一会儿)\n`
+        + `停止: background_task({ action: "kill", id: "${task.id}" })`,
+    ].join('\n')
+  }
+
   // 子进程的 PATH 每次补一次注册表最新值。
   // 为什么不能直接 {...process.env}：服务端/GUI 进程的环境块是**启动快照**，
   // 用户在这个进程活着期间装的 CLI（gh 就是这么被坑的）不在里面 —— 探测侧能找到，
@@ -857,6 +1103,8 @@ async function toolSearchText(args, ctx) {
   const extFilter = args.ext
     ? new Set(String(args.ext).split(',').map(e => e.trim().replace(/^\./, '').toLowerCase()).filter(Boolean))
     : null
+  const filesOnly = args.files_only === true
+  const contextLines = Math.max(0, Math.min(5, Number(args.context_lines) || 0))
 
   const hits = []
   let scanned = 0
@@ -868,11 +1116,23 @@ async function toolSearchText(args, ctx) {
     let text
     try { text = await fs.readFile(full, 'utf-8') } catch { return }
     scanned++
+    const rel = path.relative(ctx.cwd, full) || full
     const lines = text.split('\n')
     for (let i = 0; i < lines.length && hits.length < MAX_SEARCH_HITS; i++) {
       regex.lastIndex = 0
-      if (regex.test(lines[i])) {
-        hits.push(`${path.relative(ctx.cwd, full) || full}:${i + 1}: ${lines[i].trim().slice(0, 300)}`)
+      if (!regex.test(lines[i])) continue
+      // 只要文件名:同一文件命中多次也只记一条,否则 100 条上限全被一个文件吃掉
+      if (filesOnly) { hits.push(rel); break }
+      if (contextLines === 0) {
+        hits.push(`${rel}:${i + 1}: ${lines[i].trim().slice(0, 300)}`)
+        continue
+      }
+      const from = Math.max(0, i - contextLines)
+      const to = Math.min(lines.length - 1, i + contextLines)
+      for (let j = from; j <= to && hits.length < MAX_SEARCH_HITS; j++) {
+        // 命中行用 `:N:`、上下文行用 `-N-`,与本仓库其他探针脚本的 grep 习惯一致
+        const sep = j === i ? ':' : '-'
+        hits.push(`${rel}:${j + 1}${sep} ${lines[j].trim().slice(0, 300)}`)
       }
     }
   }
@@ -1142,6 +1402,7 @@ async function toolScheduleTask(args, ctx) {
 // ──────────────────────────────────────────────
 const TOOL_HANDLERS = {
   run_command: toolRunCommand,
+  background_task: toolBackgroundTask,
   read_file: toolReadFile,
   read_image: toolReadImage,
   write_file: toolWriteFile,

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

@@ -193,6 +193,30 @@ test('search_text 非法正则不抛异常', async () => {
   assert.match(r, /正则无效/)
 })
 
+test('search_text 的 files_only 只回文件名，context_lines 带上下文并区分命中行', async () => {
+  await fs.mkdir(path.join(tmpDir, 'ctxcase'), { recursive: true })
+  await fs.writeFile(path.join(tmpDir, 'ctxcase/one.js'), 'alpha\nbeta\nTARGET\ndelta\nepsilon')
+  await fs.writeFile(path.join(tmpDir, 'ctxcase/two.js'), 'TARGET\ngamma\nTARGET')
+
+  // files_only:一个文件只记一条(否则同文件多次命中会把 100 条上限吃光),不吐行内容
+  const files = await executeTool('search_text', { pattern: 'TARGET', path: 'ctxcase', files_only: true }, ctx)
+  assert.equal(files.trim().split('\n').length, 2)
+  assert.match(files, /one\.js/)
+  assert.match(files, /two\.js/)
+  assert.doesNotMatch(files, /beta/)
+
+  // 命中行 `:N:`、上下文行 `:N-`(行号前固定冒号,与 ripgrep 一致);窗口外的行不该混进来
+  const withCtx = await executeTool('search_text', { pattern: 'TARGET', path: 'ctxcase/one.js', context_lines: 1 }, ctx)
+  assert.match(withCtx, /one\.js:2- beta/)
+  assert.match(withCtx, /one\.js:3: TARGET/)
+  assert.match(withCtx, /one\.js:4- delta/)
+  assert.doesNotMatch(withCtx, /epsilon/)
+
+  // 不传 context_lines 时输出格式不变(默认 0 不能退化成带上下文)
+  const plain = await executeTool('search_text', { pattern: 'TARGET', path: 'ctxcase/one.js' }, ctx)
+  assert.match(plain.trim(), /^ctxcase[\\/]one\.js:3: TARGET$/)
+})
+
 // ========== run_command ==========
 
 test('run_command 执行成功并返回输出与退出码', async () => {
@@ -574,3 +598,60 @@ test('register_project：目录不存在 / 未注入实现 / 空路径都给可
   // CLI 下没有「常用目录」这个概念 —— 要回一句说明，而不是崩掉
   assert.match(await executeTool('register_project', { path: tmpDir }, ctx), /只在 g ui/)
 })
+
+// ──────────────────────────────────────────────
+// 后台命令：起服务不该占着前台等到超时
+// ──────────────────────────────────────────────
+test('run_command(run_in_background) 立刻返回 id，background_task 能读到输出且只回新增部分', async () => {
+  // 注意引号层次:外层双引号是给 cmd 的,JS 代码里只能用单引号,
+  // 否则 cmd 会在内层双引号处截断(实测 exit 1 + 无输出)
+  const script = "console.log('boot ok'); setTimeout(() => console.log('second line'), 120)"
+  const started = await executeTool('run_command',
+    { command: `"${process.execPath}" -e "${script}"`, run_in_background: true }, ctx)
+  const id = (started.match(/\bbg_\d+\b/) || [])[0]
+  assert.ok(id, `后台结果里应该带任务 id，实际: ${started}`)
+  assert.match(started, /background_task/)
+
+  const first = await executeTool('background_task', { action: 'read', id, wait_seconds: 10 }, ctx)
+  assert.match(first, /boot ok/)
+
+  // 增量语义：读走的内容不再重复回吐，否则 dev server 日志会被反复喂进上下文。
+  // 判据只能看「新增输出」段落 —— 整个返回值里还带着命令行原文(含 boot ok 字样)，直接对全文断言会自命中。
+  await new Promise(r => setTimeout(r, 200))
+  const second = await executeTool('background_task', { action: 'read', id, wait_seconds: 10 }, ctx)
+  const secondBody = second.split('--- 新增输出 ---')[1] || ''
+  assert.doesNotMatch(secondBody, /boot ok/)
+  assert.match(secondBody, /second line/)
+
+  // 进程跑完了要如实报退出码，模型才知道"服务挂了"还是"还活着"
+  assert.match(second, /exit 0/)
+
+  // 读干净之后再读：如实说没有新输出，而不是把旧内容再吐一遍
+  const third = await executeTool('background_task', { action: 'read', id }, ctx)
+  assert.match(third, /stdout 无新增输出/)
+
+  const list = await executeTool('background_task', { action: 'list' }, ctx)
+  assert.match(list, new RegExp(id))
+})
+
+test('background_task 的 kill 会真的结束进程，未知 id / 空 id 给可照做的提示', async () => {
+  // 起一个不会自己退出的进程
+  const started = await executeTool('run_command',
+    { command: `"${process.execPath}" -e "setInterval(() => {}, 1000)"`, run_in_background: true }, ctx)
+  const id = (started.match(/\bbg_\d+\b/) || [])[0]
+  assert.ok(id)
+
+  // 起来之后立刻读，应该是 running
+  const running = await executeTool('background_task', { action: 'read', id }, ctx)
+  assert.match(running, /运行中/)
+
+  const killed = await executeTool('background_task', { action: 'kill', id }, ctx)
+  assert.match(killed, /已终止/)
+
+  const after = await executeTool('background_task', { action: 'read', id }, ctx)
+  assert.match(after, /已退出/)
+
+  assert.match(await executeTool('background_task', { action: 'read' }, ctx), /需要 id/)
+  assert.match(await executeTool('background_task', { action: 'read', id: 'bg_99999' }, ctx), /没有找到/)
+  assert.match(await executeTool('background_task', { action: 'nope', id }, ctx), /未知 action/)
+})

package/src/cli/ai/transport.js

@@ -116,7 +116,7 @@ export async function streamChatOnce({ model, messages, signal, onToken = () =>
   maxRetries = MAX_LLM_RETRIES, sleepFn = defaultSleep }) {
   const { url, headers } = buildAiChatRequest({ ...model, sessionId })
   const providerKey = `${url}\n${model.model}`
-  // 内置 7 个工具是底座;extraTools 是 MCP 等外部能力的叠加(见 extensions.js)。
+  // 内置工具(TOOL_DEFINITIONS)是底座;extraTools 是 MCP 等外部能力的叠加(见 extensions.js)。
   // 扩展工具为空时**必须回落到原始数组**,避免把 tools: [] 发给模型。
   const tools = Array.isArray(extraTools) && extraTools.length ? [...TOOL_DEFINITIONS, ...extraTools] : TOOL_DEFINITIONS
   const body = { model: model.model, messages, tools, temperature: 0.3, stream: true }