zen-gitsync 2.17.16 → 2.17.18

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

@@ -25,9 +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;
 
@@ -51,6 +55,9 @@ function sessionBelongsTo(sessionCwd, projectCwd) {
 // matching response. The entry is removed on every completion or disconnect.
 const pendingAgentQuestions = new Map();
 
+/** 正在进行中的会话 id 集合：同一会话同一时刻只允许一个生成中的轮次 */
+const activeSessionTurns = new Set();
+
 function interactionKey(sessionId, interactionId) {
   return `${String(sessionId)}:${String(interactionId)}`;
 }
@@ -110,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 });
 
@@ -119,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();
@@ -187,10 +245,19 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
       .filter(u => typeof u === 'string' && /^data:image\/[\w.+-]+;base64,/.test(u))
       .slice(0, 10);
 
-    if (!userMessage && images.length === 0) {
+    // 非图片附件：前端只传文件名 + 字节，服务端落盘到数据目录，只把**绝对路径**交给模型。
+    // 内容不进消息体（省 token，模型自己用 read/grep 按需取），校验见 utils/agentAttachments.js。
+    const rawAttachments = (Array.isArray(req.body?.attachments) ? req.body.attachments : [])
+      .slice(0, MAX_ATTACHMENTS)
+      .map(a => ({ name: a?.name, dataUrl: a?.dataUrl }));
+
+    if (!userMessage && images.length === 0 && rawAttachments.length === 0) {
       return res.status(400).json({ success: false, error: '消息内容不能为空' });
     }
 
+    // 文件空间对话：客户端把"当前打开的文档"带上来，服务端只在请求副本里注入上下文（不落库）
+    const openFilePath = String(req.body?.openFilePath || '').trim().slice(0, 512);
+
     // SSE 头
     res.set({
       'Content-Type': 'text/event-stream',
@@ -207,6 +274,15 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
     let finished = false;
     let activeChild = null;
 
+    // 同一会话同一时刻只允许一个进行中的生成：跨视图（对话 Tab / 文件空间面板）
+    // 或前端连点都靠这道闸挡住，否则两个流各自的会话快照会互相覆盖。
+    if (sessionIdInput && activeSessionTurns.has(sessionIdInput)) {
+      send({ type: 'error', error: '该会话正在生成中，请等它结束后再发送' });
+      finished = true;
+      return res.end();
+    }
+    let activeSessionKey = null;
+
     // 客户端断开
     if (req.socket) {
       req.socket.once('close', () => {
@@ -249,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,
@@ -257,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: []
@@ -264,26 +364,47 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
         isNew = true;
       }
 
-      // 获取模型配置
-      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();
-      }
+      // 本轮占用该会话（finally 里释放）
+      activeSessionKey = session.sessionId;
+      activeSessionTurns.add(activeSessionKey);
+
+      // 附件落盘（拿到绝对路径后再把路径交给模型）。落盘失败不该拖垮整轮对话：
+      // 拿不到路径最多是模型看不到附件，用户仍能正常对话。
+      const attachments = await saveAgentAttachments(rawAttachments, {
+        onSkip: (info) => console.warn('[agent] 附件被忽略:', info.name, info.reason)
+      }).catch((err) => {
+        console.warn('[agent] 附件落盘失败:', err?.message || err);
+        return [];
+      });
 
-      // 更新 session 的 model 信息
-      session.model = `${model.model || ''} (${model.name || ''})`;
+      // 获取模型配置。**只有内置 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 = '';
+      }
 
       // 工作目录
       const cwd = session.cwd || (typeof getCurrentProjectPath === 'function' ? getCurrentProjectPath() : process.cwd());
@@ -296,33 +417,64 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
         title: isNew ? autoTitle([{ role: 'user', content: userMessage }]) : session.title
       });
 
-      // 运行 agent 循环
-      const { aborted } = await runAgentTurn({
-        session,
-        model,
-        userMessage,
-        images,
-        cwd,
-        locale,
-        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
-      });
-
-      if (aborted) {
-        finished = true;
-        return res.end();
+          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 消息自动生成)
@@ -330,7 +482,8 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
         session.title = autoTitle(session.messages);
       }
 
-      // 持久化
+      // 持久化。中止(用户点"停止")的轮次同样要落盘 —— 磁盘上没有这条会话时，
+      // 前端停止后立刻刷新列表会把左栏这一条整个吞掉（表现为"一停止任务就没了"）。
       session.updatedAt = nowIso();
       await writeSession(session.sessionId, session);
       enforceRetention().catch(() => {});
@@ -341,6 +494,13 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager
       send({ type: 'error', error: '智能体对话失败: ' + (err?.message || String(err)) });
       finished = true;
       res.end();
+    } finally {
+      if (activeSessionKey) activeSessionTurns.delete(activeSessionKey);
     }
   });
+
+  // 把生成器交出去:调用方(server/index.js)要在服务启动后预热一次快照,
+  // 覆盖"g ui 刚启动"这个时机。预热调用刻意留在**生产入口**而不是这里 ——
+  // 单测会调 registerAgentRoutes 四次,预热写在这里等于测试机上 spawn 四轮 gh。
+  return { snapshotter: workspaceSnapshotter };
 }

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

@@ -1,7 +1,87 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtempSync, readdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { registerAgentRoutes, waitForAgentAnswer } from './agentRoutes.js';
+
+// agentSessionStore 的落盘目录在模块加载时由 os.homedir() 求值，必须在 import 之前
+// 把 HOME 指到沙箱，否则这个文件会往真实 ~/.zen-gitsync/agent-sessions 里写会话。
+const SANDBOX = mkdtempSync(path.join(os.tmpdir(), 'zen-agent-routes-'));
+process.env.USERPROFILE = SANDBOX;
+process.env.HOME = SANDBOX;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+const { registerAgentRoutes, waitForAgentAnswer } = await import('./agentRoutes.js');
+
+// 工作区状态快照的替身。真实实现会 spawn `gh` / `gitee` / PowerShell 并联网,
+// 单测里一律用空壳 —— 否则跑一次对话就在测试机上拉起一串子进程、还连一次网。
+// getBlock 回空串 = "这一轮不注入快照",与冷启动时的真实行为一致(见 aiContext/index.js
+// 的 getSnapshot:冷启动先回 null,后台再生成)。
+const STUB_SNAPSHOTTER = {
+  getBlock: async () => '',
+  warm: async () => null,
+  refreshAll: async () => null,
+  refreshSections: async () => ({ dir: '', persistedAt: null, sections: [] }),
+  getState: () => ({ dir: '', persistedAt: null, sections: [] }),
+  invalidate() {}
+};
+
+const event = data => `data: ${JSON.stringify(data)}\n\n`;
+
+// 轮询等待条件成立（SSE 是边跑边写出来的，没有可 await 的句柄）
+async function waitUntil(check, timeoutMs = 2000) {
+  const start = Date.now();
+  while (!check()) {
+    if (Date.now() - start > timeoutMs) throw new Error('等待超时');
+    await new Promise(resolve => setTimeout(resolve, 5));
+  }
+}
+
+// 面板切换 → 定向刷新快照的端点。守两件事：
+//   ① sections 原样透传给生成器（前端按"我在看哪一块"决定刷哪几块）
+//   ② 不带 body / 不带 sections 时等于"全部"，不是"什么都不刷"
+test('ai-context 刷新端点:按板块定向刷新，并把各板块状态回给前端', async () => {
+  const calls = [];
+  let refreshHandler;
+  let stateHandler;
+  const FAKE_STATE = { dir: 'D:/snap', persistedAt: '2026-09-28 10:00:00', sections: [{ id: 'git', fresh: true }] };
+  const app = {
+    get(route, handler) { if (route === '/api/ai-context/state') stateHandler = handler; },
+    delete() {},
+    put() {},
+    post(route, handler) { if (route === '/api/ai-context/refresh') refreshHandler = handler; }
+  };
+  registerAgentRoutes({
+    app,
+    getCurrentProjectPath: () => path.resolve('active-project'),
+    configManager: null,
+    snapshotter: {
+      ...STUB_SNAPSHOTTER,
+      refreshSections: async (ids, opts) => { calls.push({ ids, opts }); return FAKE_STATE; },
+      getState: () => FAKE_STATE
+    }
+  });
+
+  let payload;
+  const res = { json(v) { payload = v; } };
+
+  await refreshHandler({ body: { sections: ['github'], force: true } }, res);
+  assert.deepEqual(calls[0].ids, ['github']);
+  assert.equal(calls[0].opts.force, true);
+  assert.equal(payload.success, true);
+  assert.equal(payload.dir, 'D:/snap');
+
+  // 不带 body：sections 为 undefined = 全部，force 默认 false（尊重各板块 TTL）
+  await refreshHandler({}, res);
+  assert.equal(calls[1].ids, undefined);
+  assert.equal(calls[1].opts.force, false);
+
+  // 只读状态的口：不触发任何取数
+  await stateHandler({}, res);
+  assert.equal(payload.dir, 'D:/snap');
+  assert.equal(calls.length, 2, 'GET /state 不该触发刷新');
+});
 
 test('agent respond resolves a pending ask_user question and validates answers', async () => {
   let respondHandler;
@@ -16,7 +96,8 @@ test('agent respond resolves a pending ask_user question and validates answers',
   registerAgentRoutes({
     app,
     getCurrentProjectPath: () => path.resolve('active-project'),
-    configManager: null
+    configManager: null,
+    snapshotter: STUB_SNAPSHOTTER
   });
 
   const sent = [];
@@ -65,7 +146,8 @@ test('agent respond: 多选提交逐项校验,回给模型的是 JSON 数组字
   registerAgentRoutes({
     app,
     getCurrentProjectPath: () => path.resolve('active-project'),
-    configManager: null
+    configManager: null,
+    snapshotter: STUB_SNAPSHOTTER
   });
 
   const sent = [];
@@ -113,7 +195,8 @@ test('agent chat rejects a cwd that differs from the active server project', asy
   registerAgentRoutes({
     app,
     getCurrentProjectPath: () => activeCwd,
-    configManager: null
+    configManager: null,
+    snapshotter: STUB_SNAPSHOTTER
   });
 
   let output = '';
@@ -133,3 +216,76 @@ test('agent chat rejects a cwd that differs from the active server project', asy
   assert.match(output, /PROJECT_MISMATCH/);
   assert.match(output, /项目不一致/);
 });
+
+// 回归：用户点"停止"（客户端断开连接 → 服务端 abort）后，这条会话仍要落盘。
+// 之前中止分支直接 res.end()，磁盘上没有会话文件，前端停止后立刻刷新列表
+// 就把左栏这一条整个吞掉了 —— 用户看到的是"一停止任务就没了"。
+test('停止(客户端断开)后会话仍要落盘，并带上自动标题与已流出的正文', async () => {
+  const activeCwd = path.resolve('active-project');
+  let chatHandler;
+  const app = {
+    get() {},
+    delete() {},
+    put() {},
+    post(route, handler) {
+      if (route === '/api/agent/chat') chatHandler = handler;
+    }
+  };
+  registerAgentRoutes({
+    app,
+    getCurrentProjectPath: () => activeCwd,
+    configManager: {
+      readRawConfigFile: async () => ({
+        models: [{ model: 'test', name: 'T', baseURL: 'https://example.invalid/v1', apiKey: 'k', isDefault: true }]
+      })
+    },
+    snapshotter: STUB_SNAPSHOTTER
+  });
+
+  // 模型流：吐一段正文后挂住（模拟"停在生成中"）。真 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 originalFetch = globalThis.fetch;
+  globalThis.fetch = async (_url, init) => hanging(init);
+
+  let onSocketClose;
+  let output = '';
+  let ended = false;
+  const req = {
+    body: { userMessage: '请列出当前项目的目录结构', cwd: activeCwd },
+    headers: {},
+    socket: { once(_evt, cb) { onSocketClose = cb; } }
+  };
+  const res = {
+    set() {},
+    flushHeaders() {},
+    write(chunk) { output += chunk; },
+    end() { ended = true; }
+  };
+
+  try {
+    const route = chatHandler(req, res);
+    await waitUntil(() => output.includes('"type":"content"'));
+    onSocketClose();
+    await route;
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+
+  assert.equal(ended, true, '中止后也要正常收尾');
+  const dir = path.join(SANDBOX, '.zen-gitsync', 'agent-sessions');
+  const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+  assert.equal(files.length, 1, '被停止的会话必须落盘，否则左栏这一条会消失');
+  const saved = JSON.parse(readFileSync(path.join(dir, files[0]), 'utf-8'));
+  assert.equal(saved.title, '请列出当前项目的目录结构');
+  const last = saved.messages[saved.messages.length - 1];
+  assert.equal(last.role, 'assistant');
+  assert.equal(last.content, '已经写了一半');
+});

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

@@ -120,6 +120,9 @@ async function listAgentSessionsMeta() {
         source: data.source || 'web',  // 'web' | 'cli'
         cwd: data.cwd || '',
         model: data.model || '',
+        // 引擎：老会话没有这个字段，一律视为内置 g ai（历史行为），
+        // 与 agentEngines.normalizeAgentEngine 的回落口径一致。
+        engine: data.engine || 'gai',
         createdAt: data.createdAt || '',
         updatedAt: data.updatedAt || '',
         messageCount: Array.isArray(data.messages) ? data.messages.length : 0,