zen-gitsync 2.17.16 → 2.17.18

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

@@ -31,7 +31,6 @@
 import path from 'path';
 import os from 'os';
 import { logger } from './shared.js';
-import { agentSessionStore } from './agentSessionStore.js';
 
 // 从 CLI 侧导入工具定义、执行器与 LLM 传输层（同一 monorepo，路径可达）
 import { TOOL_DEFINITIONS, executeTool } from '../../../../cli/ai/tools.js';
@@ -242,6 +241,9 @@ ${isWin ? `- This is Windows. The following Unix commands do NOT exist here:
 //   - model: { baseURL, model, apiKey }
 //   - userMessage: 用户输入文本
 //   - images: base64 dataURL 数组(可选,多模态图片,随最新一条 user 消息发给模型)
+//   - openFilePath: 文件空间里当前打开的文档(可选,注入请求副本,不落库)
+//   - attachments: 非图片附件(可选) = [{ name, path }],path 是**服务端落盘后的绝对路径**,
+//     只把路径写进请求副本的 system 提示,内容由模型自己用工具读(见 utils/agentAttachments.js)
 //   - cwd: 工作目录
 //   - locale: 'zh' | 'en'
 //   - signal: AbortSignal (客户端断开时触发)
@@ -250,9 +252,11 @@ ${isWin ? `- This is Windows. The following Unix commands do NOT exist here:
 //   - askUser: (args, meta) => Promise<string>  等待用户回答
 //   - listProjects: (args) => Promise<string>  list_projects 工具的数据源
 //     (由 agentRoutes 注入:最近目录/tasks.json/看板统计只有 GUI 侧拿得到)
+//   - getContextBlock: ({locale}) => Promise<string>  工作区状态快照的摘要块
+//     (由 agentRoutes 注入,实现在 routes/aiContext/:七个板块的摘要 + 落盘文件路径)
 //
 // 返回: { aborted: boolean }
-export async function runAgentTurn({ session, model, userMessage, images = [], cwd, locale, signal, send, onChild, askUser, listProjects }) {
+export async function runAgentTurn({ session, model, userMessage, images = [], cwd, locale, openFilePath, attachments = [], signal, send, onChild, askUser, listProjects, getContextBlock }) {
   const ctx = { cwd, locale, onChild, askUser, listProjects };
 
   // 确保 session.messages 存在
@@ -277,6 +281,19 @@ export async function runAgentTurn({ session, model, userMessage, images = [], c
       : userMessage
   });
 
+  // 工作区状态快照:整轮只取一次(TTL 在生成器内部,见 aiContext/index.js),
+  // 不放进循环 —— 否则每执行一次工具调用都要重拼一遍,而这轮对话里它不会变。
+  // 取不到就空着跳过:快照是**锦上添花**,不能因为它挂了就让用户这条消息发不出去。
+  let workspaceBlock = '';
+  if (typeof getContextBlock === 'function') {
+    try {
+      workspaceBlock = (await getContextBlock({ locale })) || '';
+    } catch (err) {
+      logger.warn(`[agentChat] 取工作区状态快照失败,本轮跳过注入: ${err?.message || err}`);
+      workspaceBlock = '';
+    }
+  }
+
   const maxIterations = await resolveMaxToolIterations();
 
   for (let iter = 0; iter < maxIterations; iter++) {
@@ -284,6 +301,9 @@ export async function runAgentTurn({ session, model, userMessage, images = [], c
     // 摘录成一条梗概 → 旧图片降级 → provider 兼容消毒。
     // 只作用于副本,session.messages 保持完整(与 CLI 的磁盘口径一致)。
     const messages = prepareRequestMessages(session.messages, { locale });
+    // 请求级上下文：工作区状态快照 + 当前打开的文档 + 本轮附件路径
+    // （只改副本，不落 session.messages，下一轮不重复累积）
+    injectRequestContext(messages, { cwd, openFilePath, attachments, locale, workspaceBlock });
 
     let result;
     try {
@@ -306,14 +326,6 @@ export async function runAgentTurn({ session, model, userMessage, images = [], c
       return { aborted: false };
     }
 
-    if (result.aborted) {
-      // 保存当前会话状态
-      session.updatedAt = new Date().toISOString();
-      await agentSessionStore.write(session.sessionId, session).catch(() => {});
-      send({ type: 'error', error: '已取消' });
-      return { aborted: true };
-    }
-
     const { content, toolCalls } = result;
 
     // 推理内容必须原样带回历史。DeepSeek 系 thinking 模式下带 tool_calls 的 assistant
@@ -322,6 +334,18 @@ export async function runAgentTurn({ session, model, userMessage, images = [], c
     // 口径与 CLI 侧 src/cli/ai/turn.js 的 assistant.reasoning_content 保持一致。
     const withReasoning = msg => (result.reasoning ? { ...msg, reasoning_content: result.reasoning } : msg);
 
+    if (result.aborted) {
+      // 用户点了"停止"：把已经流出来的部分正文补进历史，否则磁盘上这一轮只剩一条
+      // user 消息，重新打开会话时刚才生成的内容会整段丢失。
+      // 半截的 tool_calls 已被 transport 在中止时丢弃，这里只补正文，不会有悬空引用。
+      // 落盘由路由层统一负责（中止的轮次同样要写，见 agentRoutes.js）。
+      if (content) {
+        session.messages.push(withReasoning({ role: 'assistant', content }));
+      }
+      send({ type: 'error', error: '已取消' });
+      return { aborted: true };
+    }
+
     // 无工具调用：本轮结束
     if (toolCalls.length === 0) {
       session.messages.push(withReasoning({ role: 'assistant', content: content || null }));
@@ -409,4 +433,64 @@ function summarizeArgs(name, args) {
   }
 }
 
+// ── 请求级上下文注入（工作区状态 / 文件空间对话 / 本轮附件） ──────────────
+// 把"工作区各板块的状态摘要""用户当前打开的文件"与"本轮附件的落盘路径"追加到
+// **请求副本**的 system 消息末尾：只影响这一次请求，session.messages 与磁盘历史保持原样，
+// 下一轮也不会重复累积。
+//
+// ⚠️ 工作区快照**必须走这条副本路径，不能塞进 session.messages 里那条 system 消息**。
+// 那条只在首轮 push 一次（见上面 `session.messages.length === 0` 的判断）并会落盘，
+// 快照进去就等于永久停在"会话创建那天"——git 分支、任务进度全会是过期的，
+// 而且这种错不会报错、只会让模型理直气壮地给出错答案。有单测钉住这一点。
+//
+// 附件为什么只给路径、不给内容：见 utils/agentAttachments.js 的头注释 —— 非图片附件
+// 由服务端落盘，模型自己用 read / grep 按需取，比把几百 KB 文本内联进消息省得多。
+// 快照块同理,只给摘要与目录路径,板块正文由模型按需读。
+export function injectRequestContext(messages, { cwd, openFilePath, attachments = [], locale, workspaceBlock = '' }) {
+  if (!Array.isArray(messages)) return;
+  const en = String(locale || '').startsWith('en');
+
+  const parts = [];
+
+  // ⓪ 工作区状态快照（七个板块的摘要 + 落盘目录）。由 aiContext 生成，只在这个副本里。
+  if (typeof workspaceBlock === 'string' && workspaceBlock.trim()) {
+    parts.push(workspaceBlock.trim());
+  }
+
+  // ① 当前打开的文档（文件空间对话才有；项目外或等于根目录直接忽略）
+  if (openFilePath) {
+    const root = cwd || process.cwd();
+    let rel = '';
+    try {
+      rel = path.relative(root, path.resolve(root, openFilePath));
+    } catch {
+      rel = '';
+    }
+    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+      const file = rel.split(path.sep).join('/');
+      parts.push(en
+        ? `The file the user currently has open in the editor is \`${file}\` (relative to the project root). When the user says "this file" / "the current file" / "here", that is what they mean; read it with your tools before assuming its content.`
+        : `用户此刻在文件空间打开的文件是 \`${file}\`（相对项目根目录）。用户说"这个文件/当前文件"时默认指它；请先用工具读取内容，不要臆测。`);
+    }
+  }
+
+  // ② 本轮附件：只给绝对路径，内容让模型自己去读
+  const files = (Array.isArray(attachments) ? attachments : [])
+    .filter(a => a && typeof a.path === 'string' && a.path)
+    .slice(0, 20);
+  if (files.length > 0) {
+    const lines = files.map(a => `- \`${a.path}\`${a.name && a.name !== path.basename(a.path) ? ` (${a.name})` : ''}`);
+    parts.push(en
+      ? `The user attached ${files.length} file(s) this turn; they were saved to these absolute paths:\n${lines.join('\n')}\nRead them with your tools when relevant (they are NOT inlined here). Do not guess their contents.`
+      : `用户本轮附带了 ${files.length} 个文件，已保存到以下绝对路径：\n${lines.join('\n')}\n需要时用工具读取（内容没有内联在这里），不要臆测。`);
+  }
+
+  if (parts.length === 0) return;
+
+  const note = `\n\n# ${en ? 'Current context' : '当前上下文'}\n${parts.join('\n\n')}`;
+  const sys = messages.find(m => m && m.role === 'system' && typeof m.content === 'string');
+  if (sys) sys.content += note;
+  else messages.unshift({ role: 'system', content: note.trim() });
+}
+
 export { buildWebSystemPrompt };

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

@@ -0,0 +1,171 @@
+// injectRequestContext：把"当前打开的文档"与"本轮附件路径"注进**请求副本**。
+// 关键口径：只改请求副本、不碰 session.messages；越界路径忽略；下一轮不会重复累积；
+// 附件只给绝对路径、不给内容（内容由模型自己用 read / grep 取）。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import { injectRequestContext, buildWebSystemPrompt } from './agentChat.js'
+
+const ROOT = path.resolve('C:/proj')
+
+test('injectRequestContext: 相对项目根的斜杠路径追加进 system 消息', () => {
+  const messages = [
+    { role: 'system', content: 'rules' },
+    { role: 'user', content: 'hi' }
+  ]
+  injectRequestContext(messages, { cwd: ROOT, openFilePath: path.join(ROOT, 'src', 'a.md'), locale: 'zh' })
+  assert.match(messages[0].content, /^rules\n\n# 当前上下文/)
+  assert.match(messages[0].content, /src\/a\.md/)
+  assert.equal(messages[1].content, 'hi', '其它消息不受影响')
+})
+
+test('injectRequestContext: 项目外路径 / 空值一律忽略', () => {
+  const outside = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(outside, { cwd: ROOT, openFilePath: 'D:/other/x.md', locale: 'zh' })
+  assert.equal(outside[0].content, 'rules', '项目外路径不注入')
+
+  const none = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(none, { cwd: ROOT, openFilePath: '', locale: 'zh' })
+  assert.equal(none[0].content, 'rules', '没传 openFilePath 时不动消息')
+})
+
+test('injectRequestContext: 没有 system 消息时补一条，英文 locale 用英文说明', () => {
+  const messages = [{ role: 'user', content: 'hi' }]
+  injectRequestContext(messages, { cwd: ROOT, openFilePath: 'README.md', locale: 'en' })
+  assert.equal(messages.length, 2)
+  assert.equal(messages[0].role, 'system')
+  assert.match(messages[0].content, /README\.md/)
+  assert.match(messages[0].content, /Current context/)
+})
+
+test('injectRequestContext: 每轮都基于副本重新注入，不会重复累积', () => {
+  const session = [{ role: 'system', content: 'rules' }]
+  const first = session.map(m => ({ ...m }))
+  const second = session.map(m => ({ ...m }))
+  injectRequestContext(first, { cwd: ROOT, openFilePath: 'a.md', locale: 'zh' })
+  injectRequestContext(second, { cwd: ROOT, openFilePath: 'a.md', locale: 'zh' })
+  assert.equal(session[0].content, 'rules', '原始会话记录保持干净')
+  assert.equal((first[0].content.match(/# 当前上下文/g) || []).length, 1)
+  assert.equal((second[0].content.match(/# 当前上下文/g) || []).length, 1)
+})
+
+test('injectRequestContext: 附件只注入绝对路径,内容不进消息体', () => {
+  const messages = [{ role: 'system', content: 'rules' }, { role: 'user', content: '看下这个日志' }]
+  injectRequestContext(messages, {
+    cwd: ROOT,
+    locale: 'zh',
+    attachments: [
+      { name: '错误日志.log', path: 'C:\\Users\\x\\.zen-gitsync\\agent-attachments\\20260927-193000-ab12\\错误日志.log' }
+    ]
+  })
+  assert.match(messages[0].content, /^rules\n\n# 当前上下文/)
+  assert.match(messages[0].content, /用户本轮附带了 1 个文件/)
+  assert.match(messages[0].content, /agent-attachments.+错误日志\.log/)
+  assert.match(messages[0].content, /不要臆测/)
+  // 消息体本身没有任何文件内容
+  assert.equal(messages[1].content, '看下这个日志')
+})
+
+test('injectRequestContext: 文档 + 附件可以同时注入,各成一段', () => {
+  const messages = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(messages, {
+    cwd: ROOT,
+    openFilePath: 'src/a.md',
+    locale: 'en',
+    attachments: [
+      { name: 'a.log', path: '/tmp/att/a.log' },
+      { name: 'b.csv', path: '/tmp/att/b.csv' }
+    ]
+  })
+  const sys = messages[0].content
+  assert.match(sys, /# Current context/)
+  assert.match(sys, /src\/a\.md/)
+  assert.match(sys, /attached 2 file/)
+  assert.match(sys, /\/tmp\/att\/a\.log/)
+  assert.match(sys, /\/tmp\/att\/b\.csv/)
+  // 只加一个标题段
+  assert.equal((sys.match(/# Current context/g) || []).length, 1)
+})
+
+test('injectRequestContext: 脏附件数据(缺 path / 空数组)不会破坏消息,也不留空段', () => {
+  const dirty = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(dirty, { cwd: ROOT, locale: 'zh', attachments: [{ name: 'x.txt' }, null, 'oops'] })
+  assert.equal(dirty[0].content, 'rules', '没有可用 path 时不注入')
+
+  const empty = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(empty, { cwd: ROOT, locale: 'zh', attachments: [] })
+  assert.equal(empty[0].content, 'rules')
+})
+
+test('injectRequestContext: 附件条数超过 20 时截断(防御性上限)', () => {
+  const messages = [{ role: 'system', content: 'rules' }]
+  const many = Array.from({ length: 25 }, (_, i) => ({ name: `f${i}.txt`, path: `/tmp/att/f${i}.txt` }))
+  injectRequestContext(messages, { cwd: ROOT, locale: 'zh', attachments: many })
+  assert.match(messages[0].content, /用户本轮附带了 20 个文件/)
+  assert.ok(!messages[0].content.includes('f24.txt'), '第 21 个之后不该出现')
+})
+
+// ── 工作区状态快照（七个板块） ────────────────────────────────
+// 这一段守的是两条容易静默出错的规则：
+//   1) 快照只进**请求副本**，绝不进那条会落盘的 system 消息 —— 否则它会永久停在
+//      会话创建那天（首轮之后不再重建），而且不报错、只是答案悄悄过期。
+//   2) 快照空 / 取不到时不留下空段、不影响其它上下文。
+
+const SNAPSHOT = '[工作区状态 · 由 zen-gitsync 服务端自动生成，不是用户输入的内容]\n\n- 当前项目 Git 状态 | git-current.md | 分支 main，工作区干净'
+
+test('injectRequestContext: 工作区快照注入请求副本，且排在其它上下文之前', () => {
+  const messages = [{ role: 'system', content: 'rules' }, { role: 'user', content: 'hi' }]
+  injectRequestContext(messages, { cwd: ROOT, openFilePath: 'src/a.md', locale: 'zh', workspaceBlock: SNAPSHOT })
+  const sys = messages[0].content
+  assert.match(sys, /^rules\n\n# 当前上下文/)
+  assert.ok(sys.includes('工作区状态'), '快照必须在')
+  assert.ok(sys.indexOf('工作区状态') < sys.indexOf('src/a.md'), '快照应排在"当前打开的文件"之前')
+  assert.equal(messages[1].content, 'hi', '其它消息不受影响')
+})
+
+test('注入路径不会污染会话记录：快照不进那条会落盘的 system 消息', () => {
+  // 首轮 push 进 session.messages 的 system 提示词（会落盘、之后不再重建）
+  const persistent = buildWebSystemPrompt({ cwd: ROOT, locale: 'zh' })
+  assert.ok(!persistent.includes('工作区状态'), '落库的 system 里不许有快照');
+  assert.ok(!persistent.includes('快照目录'), '落库的 system 里不许有快照路径');
+
+  // 每轮从完整会话记录重建副本 → 快照出现且只出现一次，不会跨轮累积
+  const session = [{ role: 'system', content: 'rules' }]
+  for (let i = 0; i < 3; i++) {
+    const copy = session.map(m => ({ ...m }))
+    injectRequestContext(copy, { cwd: ROOT, locale: 'zh', workspaceBlock: SNAPSHOT })
+    assert.equal((copy[0].content.match(/工作区状态/g) || []).length, 1)
+  }
+  assert.equal(session[0].content, 'rules', '原始会话记录保持干净')
+})
+
+test('injectRequestContext: 快照为空 / 只有空白时不注入、不留空段', () => {
+  const empty = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(empty, { cwd: ROOT, locale: 'zh', workspaceBlock: '' })
+  assert.equal(empty[0].content, 'rules')
+
+  const blank = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(blank, { cwd: ROOT, locale: 'zh', workspaceBlock: '   \n  ' })
+  assert.equal(blank[0].content, 'rules')
+
+  // 没传这个参数时（老调用点）行为与从前完全一致
+  const legacy = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(legacy, { cwd: ROOT, locale: 'zh' })
+  assert.equal(legacy[0].content, 'rules')
+})
+
+test('injectRequestContext: 快照 + 文档 + 附件三者可以共存，共用一个标题段', () => {
+  const messages = [{ role: 'system', content: 'rules' }]
+  injectRequestContext(messages, {
+    cwd: ROOT,
+    locale: 'zh',
+    workspaceBlock: SNAPSHOT,
+    openFilePath: 'src/a.md',
+    attachments: [{ name: 'a.log', path: '/tmp/att/a.log' }]
+  })
+  const sys = messages[0].content
+  assert.equal((sys.match(/# 当前上下文/g) || []).length, 1, '只加一个标题段')
+  assert.ok(sys.includes('工作区状态'))
+  assert.ok(sys.includes('src/a.md'))
+  assert.ok(sys.includes('用户本轮附带了 1 个文件'))
+})

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

@@ -45,16 +45,18 @@ const longSession = () => {
 }
 
 // 跑一轮真实的 runAgentTurn,桩掉 globalThis.fetch —— 抓住发出去的请求体与产生的事件
-async function runWeb({ session, userMessage, respond, locale = 'zh-CN' }) {
+// (respond 收到 fetch 的 init,方便测试按 signal 模拟"读到一半被中止")
+async function runWeb({ session, userMessage, respond, locale = 'zh-CN', signal, onEvent }) {
   const { runAgentTurn } = await import('./agentChat.js')
   const events = []
   let sent
   const original = globalThis.fetch
-  globalThis.fetch = async (_url, init) => { sent = JSON.parse(init.body); return respond() }
+  globalThis.fetch = async (_url, init) => { sent = JSON.parse(init.body); return respond(init) }
   try {
     const result = await runAgentTurn({
       session, model, userMessage, locale, cwd: process.cwd(),
-      signal: new AbortController().signal, send: e => events.push(e),
+      signal: signal ?? new AbortController().signal,
+      send: e => { events.push(e); onEvent?.(e) },
     })
     return { sent, events, result }
   } finally {
@@ -134,6 +136,34 @@ test('流被截断（没有 finish_reason 也没有 [DONE]）时不执行半截
   assert.equal(session.messages.some(m => m.role === 'tool'), false, '被截断的调用不得留下工具结果')
 })
 
+// 回归：用户点"停止"（中止正在跑的这一轮）时，已经流出来的正文必须留在会话记录里。
+// 之前中止分支只把当时的状态写盘、不回填正文，重新打开这条会话时刚才生成的内容整段消失。
+test('中止时已流出的正文要留在会话记录里', async () => {
+  const session = newSession('ag-sandbox-aborted', withSystem())
+  const controller = new AbortController()
+
+  // 吐一段正文后挂住（模拟"停在生成中"）；真 fetch 在 signal abort 时会打断 body 读取，
+  // 桩里照做才能真的走到中止分支
+  const hanging = init => new Response(new ReadableStream({
+    start(stream) {
+      const bytes = new TextEncoder()
+      stream.enqueue(bytes.encode(event({ choices: [{ delta: { content: '已经写了一半' } }] })))
+      init?.signal?.addEventListener('abort', () => stream.error(new DOMException('Aborted', 'AbortError')))
+    },
+  }), { status: 200, headers: { 'content-type': 'text/event-stream' } })
+
+  const { result } = await runWeb({
+    session, userMessage: '写一半就停', respond: hanging, signal: controller.signal,
+    // 正文事件到达 = 这段已经被读进来，此刻中止最贴近用户点"停止"的时机
+    onEvent: e => { if (e.type === 'content') controller.abort() },
+  })
+
+  assert.equal(result.aborted, true)
+  const last = session.messages[session.messages.length - 1]
+  assert.equal(last.role, 'assistant')
+  assert.equal(last.content, '已经写了一半')
+})
+
 test('400 且正文提到 tool/function 时提示换模型,而不是甩网关 JSON', async () => {
   const session = newSession('ag-sandbox-nofc', withSystem())
   const noFunctionCalling = () => new Response(

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

@@ -0,0 +1,77 @@
+// 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.
+//
+// 智能体面板的「引擎」注册表。
+//
+// 引擎 = 谁来跑这一轮对话的智能体循环。两种性质完全不同：
+//
+//   gai ── 内置。**服务端**跑循环：LLM 流式 + 服务端执行工具（src/cli/ai/tools.js），
+//          前端只渲染事件。默认引擎，历史行为。
+//
+//   claude / opencode / codex ── 外部 CLI。**CLI 自己**跑循环：它有自己的工具集、
+//          自己的系统提示词、自己的权限模型。服务端退化成一根管子 —— spawn 出来、
+//          把它的 NDJSON 翻译成同一组 SSE 事件。见 runExternalTurn.js。
+//
+// ⚠️ 这儿**不新写一份 id 清单**：外部三家直接复用 config.js 的 TASK_EXECUTORS。
+//   本仓库为"同一份口径在多个地方各写一遍"吃过亏（见 agentParity.test.js 的注释：
+//   提示词四处、路径归一三处，分叉的失效方式是「不报错，两个入口表现不一样」）。
+//   工作台那份是任务执行器，这里是对话引擎，但**底层是同一批 CLI**，加第四家时
+//   应当只改 config.js 一处。有单测钉住这条。
+
+import { TASK_EXECUTORS } from '../../../../config.js';
+
+/** 内置引擎 id。用 'gai' 而不是 'g-ai'/'zen'：前端路由与 i18n key 都用它。 */
+export const BUILTIN_ENGINE = 'gai';
+
+/** 外部 CLI 引擎（顺序继承 config.js，与工作台执行器列表一致） */
+export const EXTERNAL_ENGINES = TASK_EXECUTORS;
+
+/** 全部可选引擎，内置排第一（前端下拉默认选中第一项） */
+export const AGENT_ENGINES = [BUILTIN_ENGINE, ...EXTERNAL_ENGINES];
+
+/**
+ * 展示名。产品名中英文一致、不走 i18n —— 与前端 utils/taskExecutor.ts 的
+ * TASK_EXECUTOR_OPTIONS 同一条判断（"Claude Code" 在中文界面里也不译）。
+ */
+export const ENGINE_LABELS = {
+  [BUILTIN_ENGINE]: 'g ai',
+  claude: 'Claude Code',
+  opencode: 'OpenCode',
+  codex: 'Codex',
+};
+
+export function isAgentEngine(value) {
+  return typeof value === 'string' && AGENT_ENGINES.includes(value);
+}
+
+export function isExternalEngine(value) {
+  return typeof value === 'string' && EXTERNAL_ENGINES.includes(value);
+}
+
+/**
+ * 归一化：非法/缺省一律回落内置引擎。
+ *
+ * 为什么回落而不是报错：body.engine 来自网络，老前端不会带这个字段。
+ * 报错会让所有老客户端在升级服务端后立刻不能聊天 —— 回落才是安全的兼容方向
+ * （与 taskRunner.normalizeTaskExecutor 的取舍一致）。
+ */
+export function normalizeAgentEngine(value) {
+  if (typeof value !== 'string') return BUILTIN_ENGINE;
+  const v = value.trim().toLowerCase();
+  return isAgentEngine(v) ? v : BUILTIN_ENGINE;
+}
+
+export function engineLabel(id) {
+  return ENGINE_LABELS[normalizeAgentEngine(id)];
+}

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

@@ -0,0 +1,65 @@
+// 引擎注册表单测。
+//
+// 最要紧的一条是**不新写清单**：外部三家必须与 config.js 的 TASK_EXECUTORS 同源。
+// 本仓库为"同一份口径各写一遍"吃过亏（提示词四处、路径归一三处），分叉的失效方式是
+// 「不报错，两个入口表现不一样」—— 加第四家 CLI 时若只改了工作台，这里就会静默漏掉。
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  AGENT_ENGINES,
+  BUILTIN_ENGINE,
+  ENGINE_LABELS,
+  EXTERNAL_ENGINES,
+  engineLabel,
+  isAgentEngine,
+  isExternalEngine,
+  normalizeAgentEngine,
+} from './agentEngines.js';
+import { TASK_EXECUTORS } from '../../../../config.js';
+
+test('外部引擎清单与 config.js 同源（加第四家只该改一处）', () => {
+  assert.deepEqual(EXTERNAL_ENGINES, TASK_EXECUTORS, '外部引擎必须直接复用 TASK_EXECUTORS');
+  assert.equal(EXTERNAL_ENGINES, TASK_EXECUTORS, '应当是同一个数组引用，不是复制一份');
+});
+
+test('内置引擎排第一（前端下拉默认选首项）', () => {
+  assert.equal(AGENT_ENGINES[0], BUILTIN_ENGINE);
+  assert.equal(BUILTIN_ENGINE, 'gai');
+  assert.equal(new Set(AGENT_ENGINES).size, AGENT_ENGINES.length, 'id 不能重复');
+});
+
+test('每个引擎都有展示名', () => {
+  for (const id of AGENT_ENGINES) {
+    assert.ok(ENGINE_LABELS[id], `${id} 缺展示名`);
+  }
+});
+
+test('normalizeAgentEngine:非法值一律回落内置引擎（老前端不带这个字段）', () => {
+  assert.equal(normalizeAgentEngine(undefined), 'gai');
+  assert.equal(normalizeAgentEngine(null), 'gai');
+  assert.equal(normalizeAgentEngine(''), 'gai');
+  assert.equal(normalizeAgentEngine('  '), 'gai');
+  assert.equal(normalizeAgentEngine('CLAUDE'), 'claude', '要容错大小写与首尾空格');
+  assert.equal(normalizeAgentEngine(' claude '), 'claude');
+  assert.equal(normalizeAgentEngine('gemini'), 'gai', '未知引擎回落，而不是报错');
+  assert.equal(normalizeAgentEngine(42), 'gai');
+});
+
+test('isAgentEngine / isExternalEngine 的边界', () => {
+  assert.equal(isAgentEngine('gai'), true);
+  assert.equal(isAgentEngine('claude'), true);
+  assert.equal(isAgentEngine('nope'), false);
+  assert.equal(isAgentEngine(undefined), false);
+  // gai 是内置的，不是外部引擎 —— 两条链路的分派全靠这个判据
+  assert.equal(isExternalEngine('gai'), false);
+  assert.equal(isExternalEngine('claude'), true);
+  assert.equal(isExternalEngine('opencode'), true);
+  assert.equal(isExternalEngine('codex'), true);
+});
+
+test('engineLabel:未知值回落内置引擎名（不显示 undefined）', () => {
+  assert.equal(engineLabel('claude'), 'Claude Code');
+  assert.equal(engineLabel('gai'), 'g ai');
+  assert.equal(engineLabel('whatever'), 'g ai');
+});