zen-gitsync 2.17.17 → 2.17.18

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

@@ -252,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, openFilePath, attachments = [], 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 存在
@@ -279,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++) {
@@ -286,8 +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 });
+    // 请求级上下文：工作区状态快照 + 当前打开的文档 + 本轮附件路径
+    // （只改副本，不落 session.messages，下一轮不重复累积）
+    injectRequestContext(messages, { cwd, openFilePath, attachments, locale, workspaceBlock });
 
     let result;
     try {
@@ -417,18 +433,30 @@ function summarizeArgs(name, args) {
   }
 }
 
-// ── 请求级上下文注入（文件空间对话 / 本轮附件） ──────────────
-// 把"用户当前打开的文件"与"本轮附件的落盘路径"追加到**请求副本**的 system 消息末尾：
-// 只影响这一次请求，session.messages 与磁盘历史保持原样，下一轮也不会重复累积。
+// ── 请求级上下文注入（工作区状态 / 文件空间对话 / 本轮附件） ──────────────
+// 把"工作区各板块的状态摘要""用户当前打开的文件"与"本轮附件的落盘路径"追加到
+// **请求副本**的 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 }) {
+// 快照块同理,只给摘要与目录路径,板块正文由模型按需读。
+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();

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

@@ -4,7 +4,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import path from 'node:path'
-import { injectRequestContext } from './agentChat.js'
+import { injectRequestContext, buildWebSystemPrompt } from './agentChat.js'
 
 const ROOT = path.resolve('C:/proj')
 
@@ -104,3 +104,68 @@ test('injectRequestContext: 附件条数超过 20 时截断(防御性上限)', (
   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/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');
+});

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

@@ -25,10 +25,13 @@ import path from 'node:path';
 import { asyncRoute, HttpError } from '../../utils/asyncRoute.js';
 import { agentSessionStore } from './agentSessionStore.js';
 import { runAgentTurn } from './agentChat.js';
+import { runExternalTurn } from './runExternalTurn.js';
+import { normalizeAgentEngine, isExternalEngine, engineLabel } from './agentEngines.js';
 import { saveAgentAttachments, MAX_ATTACHMENTS } from '../../utils/agentAttachments.js';
 import { registerAgentMarketplaceRoutes } from './agentMarketplace.js';
 import { createProjectListProvider } from './projectTool.js';
-import { nowIso } from './shared.js';
+import { createWorkspaceSnapshotter } from '../aiContext/wiring.js';
+import { nowIso, logger } from './shared.js';
 
 const { genSessionId, autoTitle, read: readSession, write: writeSession, delete: deleteSession, listMeta: listSessionsMeta, enforceRetention, rename: renameSession } = agentSessionStore;
 
@@ -114,7 +117,7 @@ export function submitAgentAnswer({ sessionId, interactionId, answer }) {
  * @param {() => string} deps.getCurrentProjectPath
  * @param {Object} deps.configManager
  */
-export function registerAgentRoutes({ app, getCurrentProjectPath, configManager }) {
+export function registerAgentRoutes({ app, getCurrentProjectPath, configManager, snapshotter }) {
 
   registerAgentMarketplaceRoutes({ app, getCurrentProjectPath });
 
@@ -123,10 +126,61 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
   // 不给它加缓存:agent 一轮里最多问一两次,而"项目状态"本来就要现读才准。
   const listProjects = createProjectListProvider({ configManager, getCurrentProjectPath });
 
+  // 工作区状态快照（七个板块的摘要 + 落盘文件路径）。同样在这里建一次、复用 ——
+  // 它要读配置、tasks.json、执行记录、git 状态、监控与思维导图,这些依赖本层一并拿得最全。
+  //
+  // `snapshotter` 是个**只为测试留的注入口**(与 remoteRepos 的 *Impl 同一套做法):
+  // 生产不传,走真实实现;单测传一个空壳,免得跑一次对话就在测试机上 spawn `gh`
+  // 和 PowerShell、还去连一次网。默认值写成参数默认值,不传时才构造。
+  const workspaceSnapshotter = snapshotter || createWorkspaceSnapshotter({ configManager, getCurrentProjectPath });
+  const getContextBlock = ({ locale } = {}) => workspaceSnapshotter.getBlock({ locale });
+
   // ════════════════════════════════════════════════════════════════════════
   // §1. 会话列表
   // ════════════════════════════════════════════════════════════════════════
+  /**
+   * 预热工作区状态快照 —— 这是"初始加载"该做的事,但**不是**把七个界面板块都挂起来。
+   *
+   * 用户打开智能体页时前端会拉这个会话列表,此刻就顺手在后台把快照生成好;
+   * 等他打完字发出去,快照早已就绪,那一轮就能带上完整上下文。
+   * 刻意不 await:它要跑 gh/gitee/git/PowerShell,等它会让会话列表白屏几秒。
+   * 也刻意不放在 registerAgentRoutes 里:启动时预热会让"打开服务"这条路径凭空多几次
+   * 子进程与网络调用,而用户可能压根不会打开智能体页。
+   */
+  function warmSnapshotInBackground() {
+    try {
+      if (typeof workspaceSnapshotter?.warm === 'function') workspaceSnapshotter.warm().catch(() => {});
+    } catch (err) {
+      logger.warn(`[agentRoutes] 预热工作区快照失败: ${err?.message || err}`);
+    }
+  }
+
+  /**
+   * POST /api/ai-context/refresh   body: { sections?: string[], force?: boolean }
+   *
+   * 给前端"切到某个面板就更新对应板块"用的定向刷新口。**按板块**而不是全量:
+   * 七个板块的取数成本差两个数量级,切个 Git 面板没必要顺带联网拉一遍仓库列表。
+   *
+   * 前端一律 fire-and-forget 调它(不等响应) —— 一次全量要 6~7 秒,没有哪个 UI 该等它。
+   * 真正拖慢也不怕:force 仍受各板块自己的 forceTtlMs 地板限制,联网板块最多 60s 一次。
+   *
+   * 顺带把各板块状态回给调用方(采集时间/是否新鲜),排查"为什么模型看到的是旧的"时很好用。
+   */
+  app.post('/api/ai-context/refresh', asyncRoute(async (req, res) => {
+    const body = req.body || {};
+    const ids = Array.isArray(body.sections) ? body.sections.map(String) : undefined;
+    const force = body.force === true;
+    const state = await workspaceSnapshotter.refreshSections(ids, { force });
+    res.json({ success: true, ...state });
+  }));
+
+  /** GET 版本:只读回各板块状态,不触发任何取数(给未来做面板用) */
+  app.get('/api/ai-context/state', asyncRoute(async (_req, res) => {
+    res.json({ success: true, ...workspaceSnapshotter.getState() });
+  }));
+
   app.get('/api/agent/sessions', asyncRoute(async (req, res) => {
+    warmSnapshotInBackground();
     let sessions = await listSessionsMeta();
     // 按项目隔离:前端传当前项目路径时只返回该项目的会话
     const cwdFilter = String(req.query?.cwd || '').trim();
@@ -271,6 +325,25 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
           finished = true;
           return res.end();
         }
+        // 引擎在会话**建立时就锁死**，中途不许换。
+        // 为什么：三家 CLI 的续聊标识互不通用（claude --resume / opencode --session /
+        // codex exec resume），而且历史消息格式不同（我们存的是 OpenAI chat completions
+        // 形状，喂给 claude 没有意义）。允许中途切换的表现是"看起来切了，上下文却串了"——
+        // 与工作台 taskExecutor.ts 注释里那条"续哪个执行器由上一轮 job.agent 决定"同源。
+        const requestedEngine = req.body?.engine === undefined
+          ? null
+          : normalizeAgentEngine(req.body?.engine);
+        const sessionEngine = normalizeAgentEngine(session.engine);
+        if (requestedEngine && requestedEngine !== sessionEngine && Array.isArray(session.messages) && session.messages.length > 0) {
+          send({
+            type: 'error',
+            error: `该会话由 ${engineLabel(sessionEngine)} 运行，无法中途切换引擎。请新建会话再选 ${engineLabel(requestedEngine)}。`,
+            code: 'ENGINE_LOCKED'
+          });
+          finished = true;
+          return res.end();
+        }
+        session.engine = sessionEngine;
       } else {
         session = {
           version: 1,
@@ -279,6 +352,11 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
           source: 'web',
           cwd: currentProjectCwd,
           model: '',
+          // 引擎：gai（内置，默认）| claude | opencode | codex
+          engine: normalizeAgentEngine(req.body?.engine),
+          // 外部 CLI 自己的续聊标识（claude session_id / opencode sessionID /
+          // codex thread_id）。g ai 用不到，留着空串。
+          engineSessionId: '',
           createdAt: nowIso(),
           updatedAt: nowIso(),
           messages: []
@@ -299,27 +377,35 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
         return [];
       });
 
-      // 获取模型配置
-      let model;
-      try {
-        if (!configManager) throw new Error('configManager 不可用');
-        const rawConfig = await configManager.readRawConfigFile();
-        const models = Array.isArray(rawConfig.models) ? rawConfig.models : [];
-        model = models.find(m => m.isDefault) || models[0];
-      } catch (err) {
-        send({ type: 'error', error: '读取 AI 配置失败: ' + err.message });
-        finished = true;
-        return res.end();
-      }
-      if (!model) {
-        send({ type: 'error', error: '未配置 AI 模型，请先在通用设置中添加模型' });
-        finished = true;
-        return res.end();
+      // 获取模型配置。**只有内置 g ai 需要** —— 外部 CLI 用自己的模型与配置
+      // （claude/opencode/codex 各自的 CLI 配置；本机上 Codex 甚至是走本地代理跑
+      //  deepseek-v4.1-flash）。为外部引擎要求"先在设置里配模型"是错的：
+      // 明明能跑，却先被一道无关的校验拦住。
+      const useExternal = isExternalEngine(session.engine);
+      let model = null;
+      if (!useExternal) {
+        try {
+          if (!configManager) throw new Error('configManager 不可用');
+          const rawConfig = await configManager.readRawConfigFile();
+          const models = Array.isArray(rawConfig.models) ? rawConfig.models : [];
+          model = models.find(m => m.isDefault) || models[0];
+        } catch (err) {
+          send({ type: 'error', error: '读取 AI 配置失败: ' + err.message });
+          finished = true;
+          return res.end();
+        }
+        if (!model) {
+          send({ type: 'error', error: '未配置 AI 模型，请先在通用设置中添加模型' });
+          finished = true;
+          return res.end();
+        }
+        // 更新 session 的 model 信息
+        session.model = `${model.model || ''} (${model.name || ''})`;
+      } else {
+        // 外部引擎：不落具体模型名（它随 CLI 自己的配置变），只记引擎，便于列表里辨认
+        session.model = '';
       }
 
-      // 更新 session 的 model 信息
-      session.model = `${model.model || ''} (${model.name || ''})`;
-
       // 工作目录
       const cwd = session.cwd || (typeof getCurrentProjectPath === 'function' ? getCurrentProjectPath() : process.cwd());
 
@@ -331,31 +417,65 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
         title: isNew ? autoTitle([{ role: 'user', content: userMessage }]) : session.title
       });
 
-      // 运行 agent 循环
-      await runAgentTurn({
-        session,
-        model,
-        userMessage,
-        images,
-        cwd,
-        locale,
-        openFilePath,
-        attachments,
-        signal: abortController.signal,
-        send,
-        onChild: (child) => { activeChild = child; },
-        askUser: (args, meta = {}) => waitForAgentAnswer({
-          sessionId: session.sessionId,
-          interactionId: meta.interactionId,
-          question: args.question,
-          options: Array.isArray(args.options) ? args.options : [],
-          allowFreeText: args.allowFreeText !== false,
-          multiple: args.multiple === true,
+      if (useExternal) {
+        // 外部 CLI 引擎：CLI 自己跑循环，服务端只做 spawn + 事件翻译。
+        // 工作区状态块走 prompt 前缀（见 runExternalTurn 文件头：往项目里写
+        // AGENTS.md/CLAUDE.md 会弄脏用户工作区，且三家读取口径实测不一致）。
+        let promptPrefix = '';
+        if (typeof getContextBlock === 'function') {
+          try { promptPrefix = await getContextBlock({ locale }); } catch (err) { logger.warn(`[agent] 外部引擎状态块获取失败: ${err?.message || err}`); }
+        }
+        // 图片附件转成文件路径交给 CLI（它们收路径不收 base64）。走同一套落盘校验。
+        const imageAttachments = images.map((u, i) => ({ name: `pasted-${i + 1}.png`, dataUrl: u }));
+        const imageFiles = imageAttachments.length > 0
+          ? await saveAgentAttachments(imageAttachments, {
+            onSkip: (info) => console.warn('[agent] 图片附件被忽略:', info.name, info.reason)
+          }).catch((err) => {
+            console.warn('[agent] 图片附件落盘失败:', err?.message || err);
+            return [];
+          })
+          : [];
+        const filePaths = [...attachments.map(a => a.path), ...imageFiles.map(f => f.path)];
+
+        await runExternalTurn({
+          session,
+          engine: session.engine,
+          userMessage,
+          cwd,
+          promptPrefix,
+          filePaths,
+          signal: abortController.signal,
           send,
+          onChild: (child) => { activeChild = child; },
+        });
+      } else {
+        // 运行 agent 循环（内置 g ai：服务端跑 LLM + 工具）
+        await runAgentTurn({
+          session,
+          model,
+          userMessage,
+          images,
+          cwd,
+          locale,
+          openFilePath,
+          attachments,
           signal: abortController.signal,
-        }),
-        listProjects
-      });
+          send,
+          onChild: (child) => { activeChild = child; },
+          askUser: (args, meta = {}) => waitForAgentAnswer({
+            sessionId: session.sessionId,
+            interactionId: meta.interactionId,
+            question: args.question,
+            options: Array.isArray(args.options) ? args.options : [],
+            allowFreeText: args.allowFreeText !== false,
+            multiple: args.multiple === true,
+            send,
+            signal: abortController.signal,
+          }),
+          listProjects,
+          getContextBlock
+        });
+      }
 
       // 更新标题(新会话从第一条 user 消息自动生成)
       if (isNew) {
@@ -378,4 +498,9 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
       if (activeSessionKey) activeSessionTurns.delete(activeSessionKey);
     }
   });
+
+  // 把生成器交出去:调用方(server/index.js)要在服务启动后预热一次快照,
+  // 覆盖"g ui 刚启动"这个时机。预热调用刻意留在**生产入口**而不是这里 ——
+  // 单测会调 registerAgentRoutes 四次,预热写在这里等于测试机上 spawn 四轮 gh。
+  return { snapshotter: workspaceSnapshotter };
 }