zen-gitsync 2.17.8 → 2.17.10

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

@@ -40,7 +40,7 @@ import {
 } from './shared.js';
 
 // 进程表：记录每个子任务的运行状态
-// jobId -> { id, taskId, subId, status, pid, startedAt, endedAt, exitCode, error, prompt, child, output, thinking, claudeSessionId }
+// jobId -> { id, taskId, subId, status, pid, startedAt, endedAt, exitCode, error, prompt, child, output, thinking, claudeSessionId, toolCalls }
 export const jobs = new Map();
 
 // 事件总线：SSE /api/workbench/events 监听 'event'，路由层用 publish() 推送
@@ -164,9 +164,17 @@ export function serializeJob(j, taskMap) {
   const { child, ...rest } = j;
   const t = taskMap ? taskMap.get(rest.taskId) : null;
   const sub = t && Array.isArray(t.subtasks) ? t.subtasks.find(s => s.id === rest.subId) : null;
+  // size 是保留策略（maxSizeMB）的计价口径，工具调用也会占体积，必须算进去，
+  // 否则一份全是工具流水的 job 会被当成"很小"而留下来。
+  const toolCallsSize = Array.isArray(rest.toolCalls)
+    ? rest.toolCalls.reduce((sum, c) => sum + (typeof c?.arguments === 'string' ? c.arguments.length : 0)
+      + (typeof c?.result === 'string' ? c.result.length : 0)
+      + (typeof c?.argsPreview === 'string' ? c.argsPreview.length : 0), 0)
+    : 0;
   const size = ((rest.prompt || '').length
     + (rest.output || '').length
-    + (rest.thinking || '').length);
+    + (rest.thinking || '').length
+    + toolCallsSize);
   return {
     ...rest,
     taskTitle: t ? t.title : '',
@@ -252,7 +260,10 @@ export async function hydrateJobs() {
     }
     // 旧版本可能没 size 字段；补齐以兼容历史文件
     if (typeof j.size !== 'number') {
-      j.size = ((j.prompt || '').length + (j.output || '').length + (j.thinking || '').length);
+      const toolSize = Array.isArray(j.toolCalls)
+        ? j.toolCalls.reduce((sum, c) => sum + (c?.arguments || '').length + (c?.result || '').length, 0)
+        : 0;
+      j.size = ((j.prompt || '').length + (j.output || '').length + (j.thinking || '').length + toolSize);
     }
     jobs.set(j.id, j);
   }
@@ -318,6 +329,9 @@ export function snapshotJobs() {
     // 本轮用的执行器（claude | opencode）。前端对话区助手名 / 日志详情按它显示;
     // 加字段时记得同步这里 —— 白名单投影会把没列出的字段静默剥掉。
     agent: j.agent || null,
+    // 工具调用流水（{id,name,argsPreview,arguments,result,status,error}[]）。
+    // 前端靠它画工具块;刷新页面 / 换实例后仍然可见,所以必须过白名单。
+    toolCalls: Array.isArray(j.toolCalls) ? j.toolCalls : [],
     // 续接对话用:claude --output-format stream-json 的 system.init 事件捕获到的 session_id
     claudeSessionId: j.claudeSessionId || null
   }));

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

@@ -299,6 +299,8 @@ export function buildRunningAgents({ jobs = [], tasks = [] } = {}) {
  * 一条 job 产出两条记录（派发 / 收尾），这是它的真实生命周期：
  *   dispatch   ← startedAt 存在
  *   done / error / cancelled ← endedAt 存在，按 status 分
+ * 唯一例外：job 是由一条指令直接带起来的，那次起跑并进指令行（见
+ * absorbInstructionDispatches）—— 否则派发行和指令行会同秒同文地出现两遍。
  * 只回结构化字段，句子交给前端 i18n。
  *
  * @param {{ jobs?: object[], tasks?: object[], instructions?: object[] }} input
@@ -367,6 +369,44 @@ export function buildActivityFeed({ jobs = [], tasks = [], instructions = [] } =
   }
 
   // 时间缺失的排最后（排序键用空串，天然沉底）
-  rows.sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')));
-  return rows.slice(0, MAX_ACTIVITY_ENTRIES);
+  return absorbInstructionDispatches(rows)
+    .sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')))
+    .slice(0, MAX_ACTIVITY_ENTRIES);
+}
+
+/**
+ * 把「由指令直接带起来的那一次起跑」并进指令行，不再单独出「派发」。
+ *
+ * 派发行的正文是「{taskTitle}」派发至 {project}，而任务标题就是指令首行
+ * （建任务时 `text.split('\n')[0]` 取的）—— 于是同一秒里会出现两行几乎一字不差：
+ * 一行标「用户派发」、一行标「派发」，看着像日志重复打印了一遍。
+ * 落点信息本来也没丢：指令行自己就带 projectName，前端还会补上落点与依据。
+ *
+ * 只吸收**每条指令之后的第一次**起跑，不是吸收这个任务的所有起跑：
+ * 同一个任务被手动重跑时，后面那些派发行没有指令与之对应，抹掉就会出现
+ * 「连着两条完成，却找不到第二次是从哪儿开始的」。
+ *
+ * 手动点执行产生的 job（没有对应指令）一概不动 —— 那种情况下派发行是**唯一**
+ * 能说明"它是什么时候跑起来的"的记录。
+ */
+function absorbInstructionDispatches(rows) {
+  const startsByTask = new Map();
+  for (const r of rows) {
+    if (r.kind !== 'dispatch' || !r.taskId) continue;
+    if (!startsByTask.has(r.taskId)) startsByTask.set(r.taskId, []);
+    startsByTask.get(r.taskId).push(r);
+  }
+  for (const list of startsByTask.values()) {
+    list.sort((a, b) => String(a.at || '').localeCompare(String(b.at || '')));
+  }
+
+  const absorbed = new Set();
+  for (const r of rows) {
+    if (r.kind !== 'user' || !r.taskId || !r.at) continue;
+    const start = (startsByTask.get(r.taskId) || []).find(
+      x => !absorbed.has(x.id) && String(x.at || '') >= String(r.at)
+    );
+    if (start) absorbed.add(start.id);
+  }
+  return absorbed.size ? rows.filter(r => !absorbed.has(r.id)) : rows;
 }

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

@@ -332,6 +332,12 @@ export function decorateTaskForBoard(task, jobsForTask = []) {
     attachmentCount: Array.isArray(task.attachments) ? task.attachments.length : 0,
     runningJobs: jobs.filter(j => j && (j.status === 'running' || j.status === 'pending')).length,
     lastJobStatus: last ? last.status : null,
+    // 最近一条 job 的结束时间 = 这张卡片"跑完"的时刻。
+    // 看板的「已完成」列要按完成时间倒序排（最新完成的在最上边），而 updatedAt 撑不起这个排序：
+    // 简单任务的执行完成只写 jobs.json，tasks.json 里的 updatedAt 一直停在创建时间
+    //（见 taskRunner.persistTaskAfterRun —— 它只有复杂任务才走），
+    // 于是十几张卡片的时间会全是创建时刻，"最新完成的"根本排不出来。
+    lastJobEndedAt: last ? (last.endedAt || last.startedAt || null) : null,
     createdAt: task.createdAt || null,
     updatedAt: task.updatedAt || null,
   };

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

@@ -215,6 +215,29 @@ test('decorateTaskForBoard: 只回卡片需要的字段', () => {
   assert.equal(card.subtaskErrorCount, 1);
   assert.equal(card.attachmentCount, 1);
   assert.equal(card.runningJobs, 0);
+  // 没跑过就没有完成时间——看板「已完成」列的排序靠它，空值必须显式是 null
+  // 而不是 undefined（前端 doneAt 的回退链要能一路退到 updatedAt）
+  assert.equal(card.lastJobEndedAt, null);
+});
+
+test('decorateTaskForBoard: lastJobEndedAt 取最近一条 job 的结束时间（已完成列排序用）', () => {
+  const jobs = [
+    job('j1', 't1', 'done', '2026-01-01T00:00:00Z', '2026-01-01T00:10:00Z'),
+    job('j2', 't1', 'done', '2026-01-03T00:00:00Z', '2026-01-03T00:20:00Z'),
+    job('j3', 't1', 'error', '2026-01-02T00:00:00Z', '2026-01-02T00:05:00Z'),
+  ];
+  const base = { id: 't1', title: '', desc: '', subtasks: [], createdAt: '2025-12-31T00:00:00Z' };
+
+  // 只有 j2 是"最近"的，即使它的结束时间排在 startedAt 序里也是最后
+  assert.equal(decorateTaskForBoard(base, jobs).lastJobEndedAt, '2026-01-03T00:20:00Z');
+
+  // 简单任务执行完成不写 tasks.json 的 updatedAt，所以完成时间只能由 job 给——
+  // 这条断言守的就是"卡片时间不能退化成创建时间"这个坑
+  assert.equal(decorateTaskForBoard(base, jobs).updatedAt, null);
+
+  // 还在跑（没有 endedAt）时退到 startedAt，卡片至少有个时间可显示
+  const running = [job('j9', 't1', 'running', '2026-02-01T00:00:00Z')];
+  assert.equal(decorateTaskForBoard(base, running).lastJobEndedAt, '2026-02-01T00:00:00Z');
 });
 
 // ── 编排状态与活动流 ────────────────────────────────────────────────
@@ -258,6 +281,53 @@ test('buildActivityFeed: job 起止合成两条记录，与人类指令一起按
   assert.equal(feed[0].instructionStatus, 'accepted');
 });
 
+test('buildActivityFeed: 指令带起来的起跑并进指令行，不再重复出一遍「派发」', () => {
+  const jobs = [{
+    id: 'j1', taskId: 't1', status: 'done',
+    startedAt: '2026-01-01T00:00:01Z', endedAt: '2026-01-01T00:05:00Z',
+  }];
+  // 任务标题就是指令首行，所以派发行和指令行本来长得一模一样
+  const tasks = [{ id: 't1', title: '把这些重构一下', projectPath: 'D:\\ws\\proj-a', subtasks: [] }];
+  const instructions = [{
+    id: 'i1', text: '把这些重构一下', taskId: 't1', projectPath: 'D:\\ws\\proj-a',
+    at: '2026-01-01T00:00:00Z', status: 'accepted',
+  }];
+
+  const feed = buildActivityFeed({ jobs, tasks, instructions });
+  assert.deepEqual(feed.map(r => r.kind), ['done', 'user']);
+  // 落点没丢：指令行自己带着项目名，前端据此渲染「落点「proj-a」」
+  assert.equal(feed[1].projectName, 'proj-a');
+});
+
+test('buildActivityFeed: 只吸收指令后的首次起跑，手动重跑仍保留派发行', () => {
+  const jobs = [
+    { id: 'j1', taskId: 't1', status: 'done', startedAt: '2026-01-01T00:00:01Z', endedAt: '2026-01-01T00:05:00Z' },
+    { id: 'j2', taskId: 't1', status: 'done', startedAt: '2026-01-01T00:10:00Z', endedAt: '2026-01-01T00:15:00Z' },
+  ];
+  const tasks = [{ id: 't1', title: '跑一下', projectPath: 'D:\\ws\\proj-a', subtasks: [] }];
+  const instructions = [{
+    id: 'i1', text: '跑一下', taskId: 't1', projectPath: 'D:\\ws\\proj-a',
+    at: '2026-01-01T00:00:00Z', status: 'accepted',
+  }];
+
+  const feed = buildActivityFeed({ jobs, tasks, instructions });
+  assert.deepEqual(feed.map(r => r.kind), ['done', 'dispatch', 'done', 'user']);
+  assert.equal(feed[1].jobId, 'j2'); // 留下的是第二次（重跑）那次
+});
+
+test('buildActivityFeed: 指令还没跑起来时，起跑行照旧保留给别的 job', () => {
+  // 指令建了任务但没执行（调度暂停）——此时该任务的任何起跑都不是它带起来的
+  const jobs = [{ id: 'j1', taskId: 't1', status: 'done', startedAt: '2026-01-01T00:00:00Z', endedAt: '2026-01-01T00:05:00Z' }];
+  const tasks = [{ id: 't1', title: '手跑的', projectPath: 'D:\\a', subtasks: [] }];
+  const instructions = [{
+    id: 'i1', text: '手跑的', taskId: 't1', projectPath: 'D:\\a',
+    at: '2026-01-01T00:20:00Z', status: 'created',
+  }];
+
+  const feed = buildActivityFeed({ jobs, tasks, instructions });
+  assert.deepEqual(feed.map(r => r.kind), ['user', 'done', 'dispatch']);
+});
+
 test('buildActivityFeed: 失败与取消分别落成 error / cancelled', () => {
   const jobs = [
     { id: 'j1', taskId: 't1', subId: 's1', status: 'error', startedAt: '2026-01-01T00:00:00Z', endedAt: '2026-01-01T00:01:00Z', error: 'boom' },

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

@@ -0,0 +1,198 @@
+// 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.
+//
+// g ai 的 list_projects 工具：数据源与格式化。
+//
+// 解决什么问题：GUI 里最近项目面板早就把"哪些项目落后了几个提交"算好了，但那份数据
+// 只走 HTTP 给前端，g ai 的上下文里一个字段都没有。于是用户问"我哪些项目需要 pull"，
+// 它只能去 list_files 扫盘 —— 本仓库实测扫出 37 个 git 仓库（node_modules 里的嵌套
+// 仓库也算），跟界面上那 9 个最近项目完全不是一套口径。
+//
+// 为什么单独一个模块，不写进 src/cli/ai/tools.js：
+//   那个文件被 CLI 与 Web 两端共用，是"有哪些工具"的清单；最近目录、tasks.json、
+//   看板统计都只存在于 GUI 侧，塞进去等于让 CLI 反向依赖 UI。这里把数据源与格式化
+//   收在一起，由 workbench/agentRoutes.js 注入进工具上下文，tools.js 只留一句转发。
+//   （同一手法见 taskRunner.setEnvContextProvider：只有 GUI 侧拿得到这些依赖。）
+//
+// 口径必须与界面对齐，所以这里**只**调用 projectRegistry 的 listProjects：
+//   最近目录 ∪ 任务里的 projectPath → buildProjectEntries，
+//   Git 状态 → probeDirectoryGitStates，任务分列 → summarizeProjectTasks。
+//   一条都不重新实现 —— 面板显示"落后 4"，g ai 也必须说"落后 4"。
+//
+// refresh 为什么存在：领先/落后读的是本地 remote-tracking 引用，也就是"上次 fetch
+// 时的快照"（见 directoryGitState.js 文件头）。不 fetch 就回答"你不需要 pull"是错的
+// ——用户最初问的恰好就是这句。所以给一个 opt-in 的 refresh，复用「刷新全部」按钮
+// 背后那个 fetchDirectoryRemotes（同一个进程内 in-flight 保护也一并继承）。
+
+import { listProjects } from './projectRegistry.js';
+import { readJson, TASKS_FILE } from './shared.js';
+import { snapshotJobs } from './jobStore.js';
+import { fetchDirectoryRemotes } from '../../utils/directoryFetch.js';
+
+/**
+ * refresh=true 时逐个项目联网 fetch 的并发数。
+ * 与「最近项目」面板的「刷新全部」取同一档（RecentDirectoriesList.vue 的
+ * REFRESH_CONCURRENCY）—— 界面同一个动作是什么节奏，g ai 触发时就是什么节奏。
+ */
+const REFRESH_CONCURRENCY = 6;
+
+/** 单个仓库的 fetch 失败原因最多回几条：全塞进去会把这轮工具输出淹掉 */
+const MAX_REPORTED_FAILURES = 5;
+
+function gitLineOf(p) {
+  if (p.exists === false) return '目录不存在（可能已被删除或移动）';
+  const g = p.git;
+  if (!g) return 'Git 状态未探到（上次探测超时，重跑一次可能就有了）';
+  if (g.isGitRepo !== true) return '不是 Git 仓库';
+
+  const parts = [];
+  parts.push(g.detached ? 'HEAD 处于 detached 状态' : `分支 ${g.branch || '(未知)'}`);
+  if (g.hasUpstream && g.upstream) {
+    const track = [];
+    if (g.behind > 0) track.push(`落后 ${g.behind}`);
+    if (g.ahead > 0) track.push(`领先 ${g.ahead}`);
+    parts.push(`${g.upstream}${track.length ? `（${track.join(' · ')}）` : '（已同步）'}`);
+  } else {
+    parts.push('未配置上游分支');
+  }
+  if (g.changed > 0) {
+    parts.push(`工作区 ${g.changed} 项未提交（已暂存 ${g.staged} · 未暂存 ${g.unstaged} · 未跟踪 ${g.untracked}）`);
+  } else {
+    parts.push('工作区干净');
+  }
+  return parts.join(' · ');
+}
+
+function taskLineOf(p) {
+  const s = p.stats || {};
+  if (!s.total) return '任务: 无';
+  const parts = [`待处理 ${s.todo || 0}`, `进行中 ${s.doing || 0}`, `已完成 ${s.done || 0}`];
+  if (s.runningJobs > 0) parts.push(`正在执行 ${s.runningJobs}`);
+  if (s.errorSubtasks > 0) parts.push(`子任务报错 ${s.errorSubtasks}`);
+  return `任务: ${parts.join(' / ')}`;
+}
+
+/**
+ * 把 listProjects 的结果拼成给模型看的文本。纯函数，单测覆盖。
+ *
+ * @param {object[]} projects listProjects() 的输出
+ * @param {object}   [opts]
+ * @param {boolean}  [opts.refreshed] 本轮是否已联网 fetch 过
+ * @param {object}   [opts.fetchStats] refreshProjects() 的统计（未刷新时为 null）
+ * @param {string}   [opts.tasksFile]  tasks.json 路径（给模型一条"要细节自己读"的路）
+ * @returns {string}
+ */
+export function formatProjectList(projects, { refreshed = false, fetchStats = null, tasksFile = '' } = {}) {
+  const list = Array.isArray(projects) ? projects : [];
+  const lines = [];
+  // 抬头必须写清"这是什么口径"，否则模型会以为自己看到的是一份普通目录扫描结果
+  lines.push(`[用户本机的「最近项目」清单 · 与 g ui 最近项目面板同一口径 · 共 ${list.length} 个]`);
+  lines.push(refreshed
+    ? '本轮已对每个项目执行 git fetch（领先/落后是 fetch 之后的真实值）。'
+    : '⚠️ 领先/落后读的是本地 remote-tracking 引用，即"上次 fetch 时的快照"，不是实时值；'
+      + '用户问的是否需要 pull / 推送时，应带 refresh=true 重跑一次再下结论。');
+  lines.push('');
+
+  list.forEach((p, i) => {
+    lines.push(`${i + 1}. ${p.name || p.path}${p.isCurrent ? '  ← 当前所在项目' : ''}`);
+    lines.push(`   路径: ${p.path}`);
+    lines.push(`   Git: ${gitLineOf(p)}`);
+    lines.push(`   ${taskLineOf(p)}`);
+  });
+
+  if (refreshed && fetchStats) {
+    lines.push('');
+    lines.push(`本轮 fetch 结果: 成功 ${fetchStats.ok} · 跳过 ${fetchStats.skipped}（非仓库/无 remote/已有刷新在跑）· 失败 ${fetchStats.failed}`);
+    for (const f of fetchStats.failures.slice(0, MAX_REPORTED_FAILURES)) {
+      lines.push(`  失败: ${f}`);
+    }
+    if (fetchStats.failures.length > MAX_REPORTED_FAILURES) {
+      lines.push(`  …还有 ${fetchStats.failures.length - MAX_REPORTED_FAILURES} 条失败未列出`);
+    }
+  }
+
+  if (tasksFile) {
+    lines.push('');
+    lines.push(`要任务细节（标题/描述/子任务/报错）直接读: ${tasksFile}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 逐个项目 git fetch，带回三态计数。
+ * 并发上限与面板一致；单个失败只记账，不中断整轮（fetchDirectoryRemotes 本身不抛）。
+ */
+async function refreshProjects(projects) {
+  // 不存在的目录没有 fetch 的意义（后端也会跳过），先剔除省一轮请求
+  const targets = projects.filter(p => p.exists !== false).map(p => p.path);
+  const stats = { ok: 0, skipped: 0, failed: 0, failures: [] };
+  let cursor = 0;
+
+  const worker = async () => {
+    while (cursor < targets.length) {
+      const target = targets[cursor++];
+      const r = await fetchDirectoryRemotes(target);
+      if (r.status === 'ok') stats.ok += 1;
+      else if (r.status === 'failed') {
+        stats.failed += 1;
+        stats.failures.push(`${target}: ${r.timeout ? `fetch 超时（超过 ${r.timeoutSeconds ?? 30} 秒）` : (r.error || 'fetch 失败')}`);
+      } else {
+        stats.skipped += 1;
+      }
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: Math.max(1, Math.min(REFRESH_CONCURRENCY, targets.length)) }, worker),
+  );
+  return stats;
+}
+
+/**
+ * 生成注入给工具上下文的 listProjects 实现。
+ *
+ * @param {object}   deps
+ * @param {object}   deps.configManager         读最近目录（与看板同一份配置）
+ * @param {Function} [deps.getCurrentProjectPath] 当前项目路径，用于打"← 当前"
+ * @returns {(args?: { refresh?: boolean }) => Promise<string>}
+ */
+export function createProjectListProvider({ configManager, getCurrentProjectPath } = {}) {
+  return async function listProjectsForAgent({ refresh = false } = {}) {
+    let recentDirs = [];
+    try {
+      recentDirs = (await configManager.getRecentDirectories()) || [];
+    } catch {
+      // 与看板同一退路：读不到最近目录就只按"任务里出现过的项目"列
+    }
+    const { tasks } = await readJson(TASKS_FILE, { tasks: [] });
+    const jobs = snapshotJobs();
+    const taskList = Array.isArray(tasks) ? tasks : [];
+    const currentProjectPath = typeof getCurrentProjectPath === 'function' ? getCurrentProjectPath() : '';
+
+    const probeOptions = refresh ? { useCache: false } : undefined;
+    let projects = await listProjects({ recentDirs, tasks: taskList, jobs, currentProjectPath, probeOptions });
+
+    let fetchStats = null;
+    if (refresh && projects.length > 0) {
+      fetchStats = await refreshProjects(projects);
+      // fetch 动了 remote-tracking 引用 → 重探一次。必须 useCache:false：
+      // 否则拿到的是 15s TTL 里 fetch 之前那份快照，等于白刷（与 fs.js 的 fetch 路由同因）。
+      projects = await listProjects({
+        recentDirs, tasks: taskList, jobs, currentProjectPath, probeOptions: { useCache: false },
+      });
+    }
+
+    return formatProjectList(projects, { refreshed: refresh, fetchStats, tasksFile: TASKS_FILE });
+  };
+}

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

@@ -0,0 +1,152 @@
+// 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.
+//
+// list_projects 工具输出（projectTool.js formatProjectList）纯函数单测。
+//
+// 这里守的是三件事：
+//   1. 模型**真的**能读到项目名/路径/Git 状态/任务进度 —— 用户最初的问题
+//      ("我哪些项目需要 pull")就靠这几个字段回答，少一个都答不了；
+//   2. 领先/落后在没刷新时必须被明确标注为"本地快照"，并且要提示 refresh=true
+//      —— 否则模型会把"上次 fetch 时的状态"当成实时值，给出相反的结论；
+//   3. 各种边界（非仓库 / 目录不存在 / 探测超时 / 无 upstream / detached / 无任务）
+//      都有可读的说法，而不是抛出 undefined。
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { formatProjectList } from './projectTool.js';
+
+/** 造一条 listProjects() 口径的项目 */
+function project(overrides = {}) {
+  const baseGit = {
+    isGitRepo: true,
+    branch: 'main',
+    upstream: 'origin/main',
+    hasUpstream: true,
+    detached: false,
+    ahead: 0,
+    behind: 0,
+    changed: 0,
+    staged: 0,
+    unstaged: 0,
+    untracked: 0,
+  };
+  const baseStats = { total: 0, todo: 0, doing: 0, done: 0, progress: 0, runningJobs: 0, errorSubtasks: 0 };
+  const merged = {
+    path: 'D:\\ws\\proj',
+    key: 'd:\\ws\\proj',
+    name: 'proj',
+    source: 'recent',
+    isCurrent: false,
+    exists: true,
+    git: baseGit,
+    stats: baseStats,
+    ...overrides,
+  };
+  // git / stats 是"部分覆盖"语义,但 git: null 表示"探测超时、没探到",不能被默认值吃掉
+  if ('git' in overrides) merged.git = overrides.git === null ? null : { ...baseGit, ...overrides.git };
+  if ('stats' in overrides) merged.stats = { ...baseStats, ...overrides.stats };
+  return merged;
+}
+
+test('未刷新时明确标注"本地快照"并提示 refresh=true', () => {
+  const text = formatProjectList([project()]);
+  assert.match(text, /共 1 个/);
+  assert.match(text, /上次 fetch 时的快照/);
+  assert.match(text, /refresh=true/);
+});
+
+test('刷新过之后不再出现快照警告，改为报出三态计数', () => {
+  const text = formatProjectList([project()], {
+    refreshed: true,
+    fetchStats: { ok: 2, skipped: 1, failed: 1, failures: ['D:\\ws\\bad: fetch 失败'] },
+  });
+  assert.doesNotMatch(text, /上次 fetch 时的快照/);
+  assert.match(text, /成功 2 · 跳过 1.*失败 1/);
+  assert.match(text, /D:\\ws\\bad: fetch 失败/);
+});
+
+test('落后/领先/未提交都出现在 Git 行里，且当前项目被标出', () => {
+  const text = formatProjectList([
+    project({ isCurrent: true, git: { branch: 'main', behind: 4, ahead: 2, changed: 3, staged: 1, unstaged: 1, untracked: 1 } }),
+  ]);
+  assert.match(text, /← 当前所在项目/);
+  assert.match(text, /分支 main/);
+  assert.match(text, /origin\/main（落后 4 · 领先 2）/);
+  assert.match(text, /工作区 3 项未提交（已暂存 1 · 未暂存 1 · 未跟踪 1）/);
+});
+
+test('已同步 / 无 upstream / detached 各有说法，不出现 undefined', () => {
+  const synced = formatProjectList([project({ git: { ahead: 0, behind: 0 } })]);
+  assert.match(synced, /origin\/main（已同步）/);
+
+  const noUpstream = formatProjectList([project({ git: { upstream: null, hasUpstream: false } })]);
+  assert.match(noUpstream, /未配置上游分支/);
+
+  const detached = formatProjectList([project({ git: { detached: true, branch: null } })]);
+  assert.match(detached, /detached/);
+  assert.doesNotMatch(detached, /undefined/);
+});
+
+test('非仓库 / 目录不存在 / 探测超时都能区分，不谎报成"干净"', () => {
+  const notRepo = formatProjectList([project({ git: { isGitRepo: false } })]);
+  assert.match(notRepo, /不是 Git 仓库/);
+  assert.doesNotMatch(notRepo, /工作区干净/);
+
+  const missing = formatProjectList([project({ exists: false })]);
+  assert.match(missing, /目录不存在/);
+
+  const unknown = formatProjectList([project({ git: null })]);
+  assert.match(unknown, /Git 状态未探到/);
+});
+
+test('任务进度按看板三列报出，无任务时说"无"', () => {
+  const withTasks = formatProjectList([project({ stats: { total: 9, todo: 1, doing: 2, done: 6, runningJobs: 1, errorSubtasks: 1 } })]);
+  assert.match(withTasks, /待处理 1 \/ 进行中 2 \/ 已完成 6/);
+  assert.match(withTasks, /正在执行 1/);
+  assert.match(withTasks, /子任务报错 1/);
+
+  assert.match(formatProjectList([project()]), /任务: 无/);
+});
+
+test('多个项目按顺序编号，条目之间不串行', () => {
+  const text = formatProjectList([
+    project({ path: 'D:\\ws\\a', name: 'a' }),
+    project({ path: 'D:\\ws\\b', name: 'b' }),
+  ]);
+  assert.match(text, /1\. a/);
+  assert.match(text, /2\. b/);
+  assert.equal(text.match(/路径: /g).length, 2);
+});
+
+test('失败条目过多时截断，但保留总数', () => {
+  const failures = Array.from({ length: 8 }, (_, i) => `D:\\ws\\p${i}: fetch 失败`);
+  const text = formatProjectList([project()], {
+    refreshed: true,
+    fetchStats: { ok: 0, skipped: 0, failed: 8, failures },
+  });
+  assert.match(text, /还有 3 条失败未列出/);
+  assert.doesNotMatch(text, /D:\\ws\\p7/);
+});
+
+test('给了 tasks.json 路径时把它带给模型（要细节自己读）', () => {
+  const text = formatProjectList([project()], { tasksFile: 'C:\\Users\\u\\.zen-gitsync\\tasks.json' });
+  assert.match(text, /C:\\Users\\u\\\.zen-gitsync\\tasks\.json/);
+});
+
+test('空清单也是一个合法回答（不抛异常、不说"共 undefined 个"）', () => {
+  const text = formatProjectList([]);
+  assert.match(text, /共 0 个/);
+  assert.doesNotMatch(text, /undefined/);
+});