zen-gitsync 2.17.21 → 2.17.23

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

@@ -0,0 +1,295 @@
+// 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.
+//
+// 「这个 job 现在在干嘛」的纯函数单测。
+//
+// 这些函数过去挂在 progressReport.js 上（只喂给主 Agent 写汇报），2026-09-29 起看板
+// 「进行中」卡片直接把它们的结果显示给人看 —— 断言重心因此变成：**卡片上那句话是不是
+// 真话**。挑错 job（拿一条早就结束的）/ 把空串渲染成"暂无" / 静默没到阈值就报"卡住了"，
+// 在界面上都是"看起来很正常"的错，只有单测挡得住。
+//
+// 前四组（tailLine / describeLastTool / describeToolMix / silentMsOf）随实现一起从
+// progressReport.test.js 搬过来，断言原样保留。
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  tailLine,
+  tailExcerpt,
+  describeLastTool,
+  describeToolMix,
+  silentMsOf,
+  jobAgent,
+  buildLiveActivity,
+  pickLiveActivity,
+  TOOL_MIX_WINDOW,
+  SILENT_NOTABLE_MS,
+} from './jobActivity.js';
+
+// ── tailLine ────────────────────────────────────────────────────────────
+
+test('tailLine 取最后一行有效文本，跳过末尾空行', () => {
+  assert.equal(tailLine('第一行\n第二行\n\n   \n'), '第二行');
+});
+
+test('tailLine 把行内空白折成一个空格（多行输出里的缩进不该原样进 prompt / 卡片）', () => {
+  assert.equal(tailLine('a\n   正在   编辑\t文件   '), '正在 编辑 文件');
+});
+
+test('tailLine 截断超长行，且空 / 非字符串一律返回空串', () => {
+  assert.equal(tailLine('x'.repeat(500)).length, 160);
+  assert.equal(tailLine(''), '');
+  assert.equal(tailLine(null), '');
+  assert.equal(tailLine(undefined), '');
+});
+
+// ── tailExcerpt（跑完之后卡片上那段「最后说了什么」） ──────────────────────
+// 这段摘录要回答的是"这条已完成的任务，是不是其实在等我回话"，所以断言的重心是
+// **结尾那句必须还在**：模型收尾时那句「要 push 吗？」被截掉的话，这个功能就白做了。
+
+test('tailExcerpt 取尾部一段，压平成一行并去掉 markdown 标记', () => {
+  const out = '## 改动\n\n- **新增** `lastReply` 字段\n- 卡片上显示最后回复\n\n要 push 吗？';
+  // 标题 / 列表标记 / ** / 反引号都只是噪声；卡片上没有富文本，留着一堆符号没法读
+  assert.equal(tailExcerpt(out), '改动 新增 lastReply 字段 卡片上显示最后回复 要 push 吗？');
+});
+
+test('tailExcerpt 丢掉表格行与分隔线（压成一行后只剩一堆竖线）', () => {
+  const out = '## 验证\n\n| 项 | 结果 |\n|---|---|\n| vue-tsc | 0 错误 |\n\n已提交。要 push 吗？';
+  assert.equal(tailExcerpt(out), '验证 已提交。要 push 吗？');
+});
+
+test('tailExcerpt 真截断过才加 …（结尾那句永远保留）', () => {
+  const long = `${'前'.repeat(300)}收尾那句：要 push 吗？`;
+  const got = tailExcerpt(long);
+  assert.ok(got.startsWith('…'), '从中间开始就该有 … 标记');
+  assert.ok(got.endsWith('要 push 吗？'), '结尾那句不能被截掉 —— CSS 截的是尾巴，这是它被截的原因');
+  // 上限按"去掉 … 之后"算：… 不计入 100 字的预算
+  assert.equal(got.length, 101);
+});
+
+test('tailExcerpt 没截断就不加 …（… 是"这句话从中间开始"的标记，不能乱标）', () => {
+  assert.equal(tailExcerpt('你好！有什么可以帮你的？'), '你好！有什么可以帮你的？');
+  // 短输出连第一行一起保留：窗口没切，第一行是完整的一句，不是半截
+  assert.equal(tailExcerpt('你好！\n\n需要的话我可以读本机的看板文件。'), '你好！ 需要的话我可以读本机的看板文件。');
+});
+
+test('tailExcerpt 窗口起点落在半句中间时从下一个整行开始（摘录不以半句开头）', () => {
+  const out = `${'前'.repeat(5000)}\n完整的一行\n要 push 吗？`;
+  // 5000 字 > REPLY_WINDOW_CHARS：被切掉的首行本就是半句，丢掉而不是拼进来
+  assert.equal(tailExcerpt(out), '完整的一行 要 push 吗？');
+});
+
+test('tailExcerpt 单行超长输出也能给出尾部（窗口里没有换行可退）', () => {
+  const got = tailExcerpt(`${'字'.repeat(5000)}要 push 吗？`);
+  assert.ok(got.startsWith('…'));
+  assert.ok(got.endsWith('要 push 吗？'));
+});
+
+test('tailExcerpt 空输出 / 脏值 / 全是表格噪声时给空串（前端据此不渲染这一段）', () => {
+  assert.equal(tailExcerpt(''), '');
+  assert.equal(tailExcerpt(null), '');
+  assert.equal(tailExcerpt(undefined), '');
+  assert.equal(tailExcerpt('   \n\n   '), '');
+  assert.equal(tailExcerpt('|---|---|\n| a | b |'), '');
+});
+
+// ── describeLastTool ────────────────────────────────────────────────────
+
+test('describeLastTool 取最后一次带名字的调用，优先用 argsPreview', () => {
+  const calls = [
+    { name: 'Read', argsPreview: 'a.ts', arguments: '{"file_path":"a.ts"}' },
+    { name: 'Edit', argsPreview: 'b.ts', arguments: '{"file_path":"b.ts"}' },
+  ];
+  assert.equal(describeLastTool(calls), 'Edit b.ts');
+});
+
+test('describeLastTool 跳过没有名字的尾部记录（老数据 / 半截记录）', () => {
+  const calls = [{ name: 'Bash', argsPreview: 'npm test' }, { id: 'anon-1' }];
+  assert.equal(describeLastTool(calls), 'Bash npm test');
+});
+
+test('describeLastTool 没有 argsPreview 时退回 arguments；两者都没有就只给工具名', () => {
+  assert.equal(describeLastTool([{ name: 'Bash', arguments: 'ls -la' }]), 'Bash ls -la');
+  assert.equal(describeLastTool([{ name: 'Bash' }]), 'Bash');
+  assert.equal(describeLastTool([]), '');
+  assert.equal(describeLastTool(null), '');
+});
+
+// ── describeToolMix / silentMsOf ────────────────────────────────────────
+
+test('describeToolMix 给出最近几次调用的分布，多的在前', () => {
+  const calls = [
+    { name: 'Bash' }, { name: 'Read' }, { name: 'Bash' },
+    { name: 'Read' }, { name: 'Bash' }, { name: 'Edit' },
+  ];
+  assert.equal(describeToolMix(calls), 'Bash×3 · Read×2 · Edit');
+});
+
+test('describeToolMix 只看最近 TOOL_MIX_WINDOW 次 —— 早先的模式早被淹没了', () => {
+  // 先 30 次 Edit，再 20 次 Read：窗口内只有 Read，分布里不该冒出 Edit
+  const calls = [
+    ...Array.from({ length: 30 }, () => ({ name: 'Edit' })),
+    ...Array.from({ length: TOOL_MIX_WINDOW }, () => ({ name: 'Read' })),
+  ];
+  assert.equal(describeToolMix(calls), `Read×${TOOL_MIX_WINDOW}`);
+});
+
+test('describeToolMix 跳过没有名字的记录，但它们不占窗口名额', () => {
+  const calls = [
+    { name: 'Bash' },
+    ...Array.from({ length: TOOL_MIX_WINDOW }, () => ({ id: 'anon-1' })),
+  ];
+  assert.equal(describeToolMix(calls), 'Bash');
+});
+
+test('describeToolMix 没有调用时给空串（调用方据此不显示这一行）', () => {
+  assert.equal(describeToolMix([]), '');
+  assert.equal(describeToolMix(null), '');
+  assert.equal(describeToolMix(undefined), '');
+});
+
+test('silentMsOf 到阈值才算静默，不到 / 没这个字段一律 null', () => {
+  const at = '2026-09-28T10:00:00.000Z';
+  const base = Date.parse(at);
+  const job = { lastActivityAt: at };
+  assert.equal(silentMsOf(job, base + SILENT_NOTABLE_MS), SILENT_NOTABLE_MS);
+  assert.equal(silentMsOf(job, base + SILENT_NOTABLE_MS - 1), null);
+  // 老记录 / 别的实例上的旧版进程没有这个字段：给 null，而不是编一个 0
+  assert.equal(silentMsOf({}, base), null);
+  assert.equal(silentMsOf({ lastActivityAt: '不是时间' }, base), null);
+  assert.equal(silentMsOf(null, base), null);
+});
+
+// ── jobAgent（看板卡片上那个执行器图标该画谁） ────────────────────────────
+// 认不出时必须回空串，不能回落成某个品牌：卡片上画一个错的执行器标，
+// 用户会以为这条是 Claude 跑的，而它可能是 Codex —— 这比不画图标糟得多。
+
+test('jobAgent：认识的执行器原样返回', () => {
+  assert.equal(jobAgent({ agent: 'claude' }), 'claude');
+  assert.equal(jobAgent({ agent: 'opencode' }), 'opencode');
+  assert.equal(jobAgent({ agent: 'codex' }), 'codex');
+});
+
+test('jobAgent：大小写与首尾空白归一后再认（jobs.json 会被手工编辑）', () => {
+  assert.equal(jobAgent({ agent: ' Codex ' }), 'codex');
+  assert.equal(jobAgent({ agent: 'CLAUDE' }), 'claude');
+});
+
+test('jobAgent：认不出的一律空串，不猜', () => {
+  assert.equal(jobAgent({ agent: 'gemini' }), '');
+  assert.equal(jobAgent({ agent: '' }), '');
+  assert.equal(jobAgent({}), '');          // 老记录没有 agent 字段
+  assert.equal(jobAgent({ agent: 123 }), '');
+  assert.equal(jobAgent(null), '');
+  assert.equal(jobAgent(undefined), '');
+});
+
+// ── buildLiveActivity ───────────────────────────────────────────────────
+
+const START = '2026-09-28T10:00:00.000Z';
+const NOW = Date.parse('2026-09-28T10:03:20.000Z'); // 距 START 3 分 20 秒
+
+/** 一条"跑了 3 分 20 秒"的 job 模板 */
+function liveJob(over = {}) {
+  return {
+    id: 'j1',
+    taskId: 't1',
+    status: 'running',
+    agent: 'claude',
+    startedAt: START,
+    thinking: '先看现状\n这个文件的锁逻辑有问题，得先弄清楚谁在什么时候写',
+    output: '我先读一下 login.ts',
+    toolCalls: [{ name: 'Read', argsPreview: 'src/login.ts' }],
+    ...over,
+  };
+}
+
+test('buildLiveActivity：终态 / 空 job 返回 null（卡片据此不显示活动区）', () => {
+  assert.equal(buildLiveActivity(liveJob({ status: 'done' }), NOW), null);
+  assert.equal(buildLiveActivity(liveJob({ status: 'error' }), NOW), null);
+  assert.equal(buildLiveActivity(null, NOW), null);
+  // pending 也算在跑（进程刚起来还没吐字）：卡片上仍要给"已运行 0 秒"，不能空着
+  assert.equal(buildLiveActivity(liveJob({ status: 'pending' }), NOW).status, 'pending');
+});
+
+test('buildLiveActivity：把思考 / 工具 / 最新回复都抽成一句话，时长按传入的 now 算', () => {
+  const live = buildLiveActivity(liveJob(), NOW);
+  assert.equal(live.elapsedMs, 3 * 60 * 1000 + 20 * 1000);
+  assert.equal(live.agent, 'claude');
+  assert.equal(live.startedAt, START);
+  assert.equal(live.toolCallCount, 1);
+  assert.equal(live.lastTool, 'Read src/login.ts');
+  assert.equal(live.toolMix, 'Read');
+  assert.equal(live.lastThought, '这个文件的锁逻辑有问题，得先弄清楚谁在什么时候写');
+  assert.equal(live.lastLine, '我先读一下 login.ts');
+  // 没有 lastActivityAt → 静默这条不成立，给 null 而不是编个 0
+  assert.equal(live.silentMs, null);
+});
+
+test('buildLiveActivity：老记录没有 agent / toolCalls 时给出空值，不抛错', () => {
+  const live = buildLiveActivity({ id: 'j2', status: 'running', startedAt: START }, NOW);
+  assert.equal(live.agent, '');
+  assert.equal(live.toolCallCount, 0);
+  assert.equal(live.lastTool, '');
+  assert.equal(live.lastThought, '');
+  assert.equal(live.lastLine, '');
+});
+
+test('buildLiveActivity：startedAt 缺失或脏值时 elapsedMs 记 0（不显示负数 / NaN）', () => {
+  assert.equal(buildLiveActivity({ id: 'j', status: 'running' }, NOW).elapsedMs, 0);
+  assert.equal(buildLiveActivity({ id: 'j', status: 'running', startedAt: '不是时间' }, NOW).elapsedMs, 0);
+});
+
+// ── pickLiveActivity ────────────────────────────────────────────────────
+
+test('pickLiveActivity：一个任务有多条 job 时挑最近有动静的那条，不是跑得最久的', () => {
+  const live = pickLiveActivity([
+    { id: 'old', status: 'running', startedAt: '2026-09-28T09:00:00.000Z', output: '老的那条' },
+    {
+      id: 'fresh',
+      status: 'running',
+      startedAt: '2026-09-28T10:00:00.000Z',
+      lastActivityAt: '2026-09-28T10:03:00.000Z',
+      output: '刚吐过字的那条',
+    },
+  ], NOW);
+  assert.equal(live.jobId, 'fresh');
+  assert.equal(live.lastLine, '刚吐过字的那条');
+});
+
+test('pickLiveActivity：只看在跑的 —— 有终态 job 时不拿它顶替', () => {
+  const done = { id: 'done', status: 'done', startedAt: '2026-09-28T10:02:00.000Z', output: '已经结束了' };
+  assert.equal(pickLiveActivity([done], NOW), null);
+  const running = { id: 'run', status: 'running', startedAt: START, output: '还在跑' };
+  assert.equal(pickLiveActivity([done, running], NOW).jobId, 'run');
+});
+
+test('pickLiveActivity：时间戳打平时取末条（与 latestJob 同口径），空数组给 null', () => {
+  const same = [
+    { id: 'a', status: 'running', startedAt: START, output: 'a' },
+    { id: 'b', status: 'running', startedAt: START, output: 'b' },
+  ];
+  assert.equal(pickLiveActivity(same, NOW).jobId, 'b');
+  assert.equal(pickLiveActivity([], NOW), null);
+  assert.equal(pickLiveActivity(null, NOW), null);
+});
+
+test('pickLiveActivity：lastActivityAt 是脏值时退回 startedAt 比较', () => {
+  const live = pickLiveActivity([
+    { id: 'a', status: 'running', startedAt: '2026-09-28T09:00:00.000Z', lastActivityAt: '不是时间' },
+    { id: 'b', status: 'running', startedAt: '2026-09-28T08:00:00.000Z' },
+  ], NOW);
+  assert.equal(live.jobId, 'a');
+});

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

@@ -88,6 +88,9 @@ export function projectJob(j) {
     thinking: j.thinking || '',
     pid: j.pid || null,
     startedAt: j.startedAt || null,
+    // 最后一次产出的时刻。别的实例跑的任务，进度报告只能从这份文件上读它 ——
+    // 不过白名单就会变成"本实例的报告说得出静默多久，跨实例的报告永远说不出来"。
+    lastActivityAt: j.lastActivityAt || null,
     endedAt: j.endedAt || null,
     exitCode: typeof j.exitCode === 'number' ? j.exitCode : null,
     error: j.error || null,

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

@@ -344,25 +344,76 @@ function normalizeReport(raw) {
         toolCallCount: Number.isFinite(Number(t.toolCallCount)) ? Math.max(0, Math.floor(Number(t.toolCallCount))) : 0,
         lastTool: typeof t.lastTool === 'string' ? t.lastTool : '',
         lastLine: typeof t.lastLine === 'string' ? t.lastLine : '',
+        // 2026-09-29 补的三样：老记录里没有它们 —— 一律给"没有"（'' / null），
+        // 不要硬塞一个默认值冒充"当时它就是在思考 / 当时静默了 0 秒"
+        toolMix: typeof t.toolMix === 'string' ? t.toolMix : '',
+        lastThought: typeof t.lastThought === 'string' ? t.lastThought : '',
+        silentMs: Number.isFinite(Number(t.silentMs)) ? Math.max(0, Math.floor(Number(t.silentMs))) : null,
       })),
   };
 }
 
-/** 读报告历史（新的在前）。文件缺失 / 损坏一律当"还没有报告"，不抛错 */
+/**
+ * 读报告历史（新的在前）。文件缺失 / 损坏一律当"还没有报告"，不抛错。
+ *
+ * **没有事实的报告不算报告**：那是一条"当时什么都没在跑"的空记录，对回头翻历史的人
+ * 零信息量，却要占掉上限 20 条里的一格，把真正有用的挤出去（用户 2026-09-29 的原话：
+ * "这种没有在执行的就不用展示了"）。
+ *
+ * 写入侧已经不再产生它们（见 routes/workbench/index.js 的 runProgressReport），
+ * 这里再挡一次是因为：老版本进程 / 另一个实例写进同一份文件的空报告，
+ * 在读取方看来同样得当成不存在 —— 面板只认这个函数给的清单。
+ * 另外 appendReport 是拿本函数的返回值重写整个文件的，所以历史遗留的空报告
+ * 会在下一次落盘时被真正从磁盘上清掉。
+ */
 export async function readReports() {
   const data = await readJson(ORCHESTRATOR_REPORTS_FILE, null);
   const list = data && Array.isArray(data.reports) ? data.reports : [];
   return list
     .map(normalizeReport)
+    .filter(r => r.tasks.length > 0)
     .sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')))
     .slice(0, MAX_PROGRESS_REPORTS);
 }
 
-/** 追加一份报告（新的在前），超出上限的旧报告直接丢掉 */
+/** 两份报告"说的是同一件事"吗：同一批任务 + 同一段正文 + 同一种失败 */
+function sameReport(a, b) {
+  if (!a || !b) return false;
+  if (a.trigger !== b.trigger || a.text !== b.text) return false;
+  if (a.errorCode !== b.errorCode || a.errorDetail !== b.errorDetail) return false;
+  if (a.tasks.length !== b.tasks.length) return false;
+  return a.tasks.every((t, i) => (t.taskId || '') === (b.tasks[i].taskId || '')
+    && (t.taskTitle || '') === (b.tasks[i].taskTitle || ''));
+}
+
+/**
+ * 追加一份报告（新的在前），超出上限的旧报告直接丢掉。
+ *
+ * 窗口期内**内容一样的**只留第一份。为什么需要它：没有正文的报告（没配模型 = NO_MODEL）
+ * 是逐字节相同的 —— 「立即报告」连点两下、或两个实例各点一下，历史里就会出现两条
+ * 一模一样的记录（真实数据：2026-09-28T15:44:08.161 与 .226 两条 manual / tasks=0）。
+ * 前端那个"生成中"的防抖挡不住这种点击：空报告不叫模型，本机往返几十毫秒就返回了，
+ * 第二次点击落在防抖释放之后。
+ *
+ * 判据刻意**不含**时长 / 工具次数 / 最近输出这些每份报告都会变的字段 ——
+ * 带上它们就永远"不算重复"，等于没做这个检查。
+ */
+const REPORT_DEDUPE_WINDOW_MS = 10 * 1000;
+
+/** @returns {Promise<object>} 落盘的那一份；被判为重复时返回已在历史里的头部那条 */
 export async function appendReport(entry) {
   return serialize(async () => {
     const report = normalizeReport({ id: genId(), at: nowIso(), ...entry });
     const existing = await readReports();
+    const head = existing[0];
+    const headAt = Date.parse((head && head.at) || '');
+    if (head && Number.isFinite(headAt)
+      && Date.now() - headAt < REPORT_DEDUPE_WINDOW_MS
+      && sameReport(head, report)) {
+      // 不落盘。返回头部那条而不是 null：调用方（runProgressReport）要拿它广播，
+      // 前端本来就在展示它，等于"你看到的就是刚生成的"
+      return head;
+    }
     const reports = [report, ...existing].slice(0, MAX_PROGRESS_REPORTS);
     await writeJson(ORCHESTRATOR_REPORTS_FILE, { version: 1, reports });
     return report;

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

@@ -0,0 +1,177 @@
+// 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.
+//
+
+// 进度报告**历史文件**的两条规则（读写都在 orchestratorStore 里）：
+//
+//   1. 没有事实的报告不算报告 —— 读的时候当不存在，写的时候也活不过下一次落盘。
+//      用户 2026-09-29 的原话："这种没有在执行的就不用展示了"：那 4 条
+//      "当时没有任务在执行"既零信息量，又占着 20 条上限的格子。
+//   2. 窗口期内**内容一样**的只留第一份 —— 没有正文的报告（NO_MODEL）逐字节相同，
+//      「立即报告」连点两下就会在历史里留下两条一模一样的记录
+//      （真实数据：2026-09-28T15:44:08.161 与 .226，两条都是 manual / tasks=0）。
+//
+// 隔离：必须在 import 之前把 USERPROFILE/HOME 指向 mkdtemp 沙箱，否则就是往用户真实的
+// ~/.zen-gitsync 里写报告（同 dispatchInstruction.test.js / jobStore.test.js 的做法）。
+
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '../../../../..');
+
+// ---- 环境隔离:必须在 import 之前完成 ----
+const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'zgs-report-store-test-'));
+const savedEnv = {
+  USERPROFILE: process.env.USERPROFILE,
+  HOME: process.env.HOME,
+  HOMEDRIVE: process.env.HOMEDRIVE,
+  HOMEPATH: process.env.HOMEPATH,
+};
+process.env.USERPROFILE = fakeHome;
+process.env.HOME = fakeHome;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+const load = p => import(pathToFileURL(path.join(projectRoot, p)).href);
+const { readReports, appendReport } = await load('src/ui/server/routes/workbench/orchestratorStore.js');
+const { ORCHESTRATOR_REPORTS_FILE, readJson } = await load('src/ui/server/routes/workbench/shared.js');
+
+after(async () => {
+  for (const k of Object.keys(savedEnv)) {
+    if (savedEnv[k] === undefined) delete process.env[k];
+    else process.env[k] = savedEnv[k];
+  }
+  await fs.rm(fakeHome, { recursive: true, force: true }).catch(() => {});
+});
+
+/** 一份任务事实的最小形状（normalizeReport 认得的那几个字段） */
+const fact = (taskId, taskTitle) => ({
+  taskId,
+  taskTitle,
+  projectName: 'zen-gitsync',
+  startedAt: null,
+  elapsedMs: 1000,
+  agent: 'claude',
+  toolCallCount: 3,
+  lastTool: 'Edit src/a.ts',
+  lastLine: '正在改登录模块',
+});
+
+/** 手写历史文件：直接落盘才能构造"30 秒前"这种 appendReport 自己写不出来的时间 */
+async function seed(reports) {
+  await fs.mkdir(path.dirname(ORCHESTRATOR_REPORTS_FILE), { recursive: true });
+  await fs.writeFile(ORCHESTRATOR_REPORTS_FILE, JSON.stringify({ version: 1, reports }, null, 2), 'utf8');
+}
+
+/** 磁盘上的原始内容（不走 readReports 的过滤），用来验证"真的清掉了" */
+async function onDisk() {
+  const data = await readJson(ORCHESTRATOR_REPORTS_FILE, null);
+  return (data && Array.isArray(data.reports)) ? data.reports : [];
+}
+
+const iso = (msAgo) => new Date(Date.now() - msAgo).toISOString();
+
+const rawReport = (over = {}) => ({
+  id: 'r-' + Math.random().toString(36).slice(2, 8),
+  at: iso(0),
+  trigger: 'manual',
+  text: '',
+  errorCode: '',
+  errorDetail: '',
+  tasks: [],
+  ...over,
+});
+
+before(async () => { await seed([]); });
+
+test('空报告读不出来（"这种没有在执行的就不用展示了"）', async () => {
+  await seed([
+    rawReport({ id: 'with-facts', at: iso(60_000), tasks: [fact('t1', '有事实的任务')] }),
+    rawReport({ id: 'empty-1', at: iso(30_000) }),
+    rawReport({ id: 'empty-2', at: iso(20_000) }),
+  ]);
+  const list = await readReports();
+  assert.deepEqual(list.map(r => r.id), ['with-facts']);
+});
+
+test('空报告不再占用 20 条上限：读出来的是最近 20 条**真**报告', async () => {
+  const reports = [];
+  // 交错写：每两条真报告中间夹一条空报告，真报告共 21 条（超上限 1 条）
+  for (let i = 0; i < 21; i++) {
+    reports.push(rawReport({ id: `real-${i}`, at: iso((21 - i) * 1000), tasks: [fact(`t${i}`, `任务 ${i}`)] }));
+    reports.push(rawReport({ id: `empty-${i}`, at: iso((21 - i) * 1000 + 500) }));
+  }
+  await seed(reports);
+  const list = await readReports();
+  assert.equal(list.length, 20);
+  assert.ok(list.every(r => r.tasks.length > 0), '读出来的每一条都得有事实');
+  // 新的在前：real-20 最新，real-0 被上限挤掉
+  assert.equal(list[0].id, 'real-20');
+  assert.ok(!list.some(r => r.id === 'real-0'));
+});
+
+test('历史遗留的空报告在下一次落盘时从磁盘上清掉', async () => {
+  await seed([rawReport({ id: 'legacy-empty', at: iso(60_000) })]);
+  await appendReport(rawReport({ id: 'ignored', trigger: 'auto', tasks: [fact('t1', '任务')] }));
+  const disk = await onDisk();
+  assert.equal(disk.length, 1);
+  assert.ok(!disk.some(r => r.id === 'legacy-empty'), '空报告应该已经从文件里消失');
+});
+
+test('窗口期内内容一样的第二份不落盘（连点两下的去重）', async () => {
+  await seed([]);
+  const first = await appendReport(rawReport({ errorCode: 'NO_MODEL', tasks: [fact('t1', '任务 A')] }));
+  const second = await appendReport(rawReport({ errorCode: 'NO_MODEL', tasks: [fact('t1', '任务 A')] }));
+  assert.equal(second.id, first.id, '第二份应该被判为重复，返回已有的那份');
+  assert.equal((await onDisk()).length, 1);
+});
+
+test('同一批任务但正文不同 → 两份都留（不是"同一批任务就合并"）', async () => {
+  await seed([]);
+  const base = { tasks: [fact('t1', '任务 A')] };
+  await appendReport(rawReport({ ...base, text: '第一次汇报：正在改登录模块。' }));
+  await appendReport(rawReport({ ...base, text: '第二次汇报：已经在跑测试了。' }));
+  assert.equal((await onDisk()).length, 2);
+});
+
+test('过了去重窗口那份就不再算重复（同一分钟连点两下之外是正常的两份）', async () => {
+  // 手写一条 30 秒前的报告，再用相同内容 append —— 窗口（10s）已经过去
+  const stale = rawReport({ id: 'stale', at: iso(30_000), errorCode: 'NO_MODEL', tasks: [fact('t1', '任务 A')] });
+  await seed([stale]);
+  const saved = await appendReport(rawReport({ errorCode: 'NO_MODEL', tasks: [fact('t1', '任务 A')] }));
+  assert.notEqual(saved.id, 'stale');
+  assert.equal((await onDisk()).length, 2);
+});
+
+test('触发的来源不同（手动 vs 自动）不算重复', async () => {
+  await seed([]);
+  const tasks = [fact('t1', '任务 A')];
+  await appendReport(rawReport({ trigger: 'manual', tasks }));
+  await appendReport(rawReport({ trigger: 'auto', tasks }));
+  assert.equal((await onDisk()).length, 2);
+});
+
+test('上限仍然生效：多余的报告按时间从旧到新丢掉', async () => {
+  await seed([]);
+  for (let i = 0; i < 23; i++) {
+    // 每份正文都不同，绕开去重窗口
+    await appendReport(rawReport({ text: `第 ${i} 次汇报`, tasks: [fact('t1', '任务 A')] }));
+  }
+  assert.equal((await onDisk()).length, 20);
+});