@ghyper9023/pi-dev-workflow 0.4.1 → 0.4.3

package/.pi-dev-output/pi-review/md/review-20260522-003000.md

@@ -0,0 +1,377 @@
+# 代码审查报告 — git diff 脏数据、循环计数偏差 与 跨循环数据残留
+
+**审查时间**: 2026-05-22 00:30 CST  
+**审查范围**: `extensions/workflow-engine.ts` 和 `extensions/ui-helpers.ts`  
+**审核基线**: HEAD (commit `2bc55d8`)  
+**功能需求**: 修复 git diff 解析与循环计数 Bug
+
+---
+
+## 严重问题
+
+### C1. `setWidgetSubStepStatus` 重置 pending 时不清除旧数据，导致跨循环脏数据残留
+
+**严重度**: critical  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 795-804 行 (`setWidgetSubStepStatus` 函数)
+
+**问题描述**：
+
+```typescript
+function setWidgetSubStepStatus(stepIndex, agentName, status) {
+    const step = _widgetSteps[stepIndex];
+    if (!step) return;
+    const sub = step.subSteps?.find(s => s.agent === agentName);
+    if (sub) {
+        sub.status = status;
+        refreshWidget();
+    }
+}
+```
+
+`executeLoopGroup` 进入下一轮循环时：
+
+```typescript
+setWidgetSubStepStatus(stepIndex, step.loopAgentName!, "pending");
+setWidgetSubStepStatus(stepIndex, step.reviewAgentName!, "pending");
+```
+
+仅修改了 `status` 为 `"pending"`，但 `sub.tools`、`sub.outputs`、`sub.startedAt`、`sub.detail` 等字段**全部保留**。
+
+**影响**：
+
+1. **UI 层面**：第 2 次循环的 worker 或 reviewer sub-step 仍然显示第 1 次循环的 tools（如 `M   src/main.rs`），误导用户。
+2. **Checkpoint 层面**：`addWidgetSubStepTool` 将从 agent 文本中刮取到的脏数据（如 `filePath: "[],\n\t\t\t\toutputs:"`）写入 `_workflowFileChanges`。跨循环时这些脏数据不会清除，导致 checkpoint 膨胀。
+3. **时长计算层面**：`sub.startedAt` 保留第 1 次循环的值，直到 `runAgentWithProgress` 覆盖。
+
+**证据**：checkpoint 数据中可以看到大量脏路径，如：
+```json
+{"filePath": "[],\\n\\t\\t\\toutputs:", "type": "edit"},
+{"filePath": "checkpoint-${planId}.json", "type": "edit"},
+{"filePath": "代码xxx.rs\\\\n", "type": "edit"}
+```
+
+**修复方案**：在 `executeLoopGroup` 中设置 sub-step 为 pending 时，同时清空 tools/outputs/startedAt/detail：
+
+```typescript
+function setWidgetSubStepStatus(stepIndex, agentName, status) {
+    const step = _widgetSteps[stepIndex];
+    if (!step) return;
+    const sub = step.subSteps?.find(s => s.agent === agentName);
+    if (sub) {
+        sub.status = status;
+        if (status === "pending") {
+            sub.tools = [];
+            sub.outputs = [];
+            sub.startedAt = undefined;
+            sub.detail = undefined;
+        }
+        refreshWidget();
+    }
+}
+```
+
+---
+
+### C2. `addWidgetSubStepTool` 将 agent 文本刮取的脏路径写入 checkpoint
+
+**严重度**: critical  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 1014-1058 行（`filePatterns` 文本刮取）和第 730-765 行（`addWidgetSubStepTool` 的 checkpoint 记录）
+
+**问题描述**：
+
+`runAgentWithProgress` 末尾有一段基于正则的文本刮取逻辑（`filePatterns`），从 agent 的最终输出中匹配文件路径：
+
+```typescript
+const filePatterns = [
+    /`([^`]+\.[a-zA-Z0-9_]+)`/g,                                    // 反引号
+    /(?:^|\n)\s*[-*]\s*(?:modified|...) ... /gim,                   // 列表项
+    /(?:modified|...) ... /gi,                                       // 描述
+    /(?:编写|创建|...) ... /gi,                                      // 中文
+    /(?:^|\n)\s*(?:edit|new|...) ... /gim,                          // action: path
+];
+```
+
+这些正则从 agent 的自然语言输出中匹配，极易匹配到**代码片段中的变量名**、**转义字符串**、**模板字符串**等。例如：
+
+- `` `checkpoint-${planId}.json` `` → 匹配第 1 个 pattern → `checkpoint-${planId}.json`
+- `"M       path/to/file.ts"` 输出中的 `file.ts` → 通过 `.` 和字母后缀匹配
+- 代码片段中的 `[],\n\t\t\t\toutputs:` → 匹配第 5 个 pattern → `[],`
+
+现有的额外过滤器（第 1040-1043 行）已排除 `${`、`\\n`、`[]` 等明显脏数据，但仍有大量漏网之鱼：
+
+- 转义双反斜杠 `\\\\n`、`path\\\\\\\"` 等模式未被 `\\n` 过滤器捕获
+- 路径碎片如 `src/ma` 虽不过滤器（无 `.`），但更早的 `if (filePath.length < 6 && !filePath.includes("/")) continue` 条件未能拦截它
+- `checkpoint-${planId}.json` 被 `${` 过滤器拦截，但 `checkpoint-` 前缀的其他变体仍可能通过
+
+**关键问题**：这些脏数据通过 `addWidgetSubStepTool` 写入 `_workflowFileChanges`，然后写入 checkpoint。在 `f98799d` commit 的 checkpoint 数据中可以看到 70+ 条文件变更记录，其中 40+ 条是脏数据。
+
+**根本原因**：文本刮取作为文件变更检测手段本质上不可靠。`updateToolsFromGit`（基于 git diff）是准确的，但它只在 agent 结束后调用一次。**文本刮取的脏数据在 git diff 数据之前就已写入**。
+
+**修复方案（最小改动）**：
+在 `addWidgetSubStepTool` 的 `gitMatch` 分支中添加额外的路径合法性验证，或在写入 `_workflowFileChanges` 之前增加验证：
+
+```typescript
+// 在 addWidgetSubStepTool 中，写入 _workflowFileChanges 之前
+function isLikelyRealFilePath(filePath: string): boolean {
+    // 真正的文件路径应该：
+    // 1. 包含一个点号（扩展名）或路径分隔符（正斜杠）
+    if (!filePath.includes(".") && !filePath.includes("/")) return false;
+    // 2. 不包含模板表达式、转义字符
+    if (filePath.includes("${")) return false;
+    if (filePath.includes("\\n") || filePath.includes("\\t") || filePath.includes("\\\\")) return false;
+    // 3. 不包含 JSON/代码特征
+    if (filePath.includes("[]") || filePath.includes("{}") || filePath.includes("=>")) return false;
+    // 4. 不是 JS 变量名（单个单词含点号但不含路径分隔符且长度 < 20）
+    if (!filePath.includes("/") && filePath.split(".").length <= 2 && filePath.length < 30) return false;
+    return true;
+}
+```
+
+但最彻底的方案是：**移除 `filePatterns` 的文本刮取，完全依赖 `updateToolsFromGit` 的 git diff**。这是最小改动原则下的最佳方案。
+
+---
+
+### C3. 循环计数偏移：第 2 次循环仍然显示第 1 次循环
+
+**严重度**: critical  
+**文件**: `extensions/workflow-engine.ts` (executeLoopGroup, 第 1205-1212 行) 和 `extensions/ui-helpers.ts` (buildWidgetLines, 第 478-497 行)
+
+**问题描述**：
+
+用户报告：`第 0 次循环 → 第 1 次循环 → 第 1 次循环（应为第 2 次）→ 第 2 次循环（应为第 3 次）`
+
+**分析**：
+
+当前 `executeLoopGroup` 代码中（HEAD）：
+
+```typescript
+while (loopCount < maxLoops) {
+    loopCount++;
+    state.loopCount = loopCount;
+    updateWidgetStep(stepIndex, step.label, "running", {
+        loopCount,
+        maxLoops: step.maxLoops,
+        startedAt: _widgetSteps[stepIndex]?.startedAt || Date.now(),
+    });
+    // ...
+    // reviewer 检测到 critical → continue
+}
+```
+
+`loopCount++` 在 while 循环开头，并通过 `updateWidgetStep` 立即将 `loopCount` 设置到 widget step。从纯逻辑上看这是正确的。
+
+**但是**，这里有一个潜在的问题：
+
+`updateWidgetStep` 中传入的 `startedAt`：
+```typescript
+startedAt: _widgetSteps[stepIndex]?.startedAt || Date.now(),
+```
+
+对于第 2 次循环，`_widgetSteps[stepIndex]?.startedAt` 是第 1 次循环 `updateWidgetStep` 设置的值（一个有效的 number）。`||` 操作符不会因为 `number` 值为真而回退到 `Date.now()`。这意味着第 2 次循环的 `startedAt` = 第 1 次循环的 `startedAt`。
+
+这不一定导致循环计数显示错误（loopCount 是明确传入的），但会导致步骤时长计算错误（从第 1 次循环开始时计时）。
+
+**实际根因猜测**：如果用户看到的实际行为是计数偏移 1，那么原因可能是 **`buildWidgetLines` 中的 `isRunning` 状态检测与 loopCount 更新的时序问题**。具体来说：
+
+`buildWidgetLines` 中的判断逻辑：
+```typescript
+if (s.loopCount != null && s.loopCount > 0) {
+    loopStr = dim(theme, ` · 第 ${s.loopCount} 次循环`);
+} else if (s.maxLoops != null) {
+    if (isRunning) {
+        if (s.loopCount == null || s.loopCount === 0) {
+            loopStr = dim(theme, ` · 第 1 次循环`);
+        }
+    }
+}
+```
+
+这里 `if (s.loopCount != null && s.loopCount > 0)` 分支**优先于** `else if (isRunning)` 分支。如果 `loopCount` 已正确设置，应该显示对应的值。
+
+**问题可能出在**：`refreshWidget` 调用链中，`buildWidgetLines` 使用的 `state` 对象可能不是最新的 `_widgetSteps`。检查 `buildWidgetState`：
+
+```typescript
+export function buildWidgetState(mode, steps, ...) {
+    return {
+        mode,
+        steps,  // 是 _widgetSteps 的引用
+        ...
+    };
+}
+```
+
+`steps` 是 `_widgetSteps` 的引用，所以每次 `updateWidgetStep` 修改 `_widgetSteps[index]` 时，`buildWidgetLines` 读到的是最新值。
+
+**结论**：从代码审查角度看，循环计数逻辑**在 HEAD 看起来是正确的**。如果用户仍然观察到计数偏移，可能是：
+1. 用户测试的是 `f98799d` 之前的代码（`f98799d` 本身修复了这个计数偏移）
+2. 或者存在一个条件竞争：`updateWidgetStep` 中的 `refreshWidget()` 与动画定时器的 `buildWidgetFactory` 之间的渲染时序问题
+
+**建议**：如果问题仍然存在，可以在 `updateWidgetStep` 中直接使用 `Date.now()` 作为 `startedAt`（而不是复用旧值），并在循环开始前额外调用一次 `refreshWidget()` 确保 UI 更新。
+
+---
+
+## 中等问题
+
+### M1. `runAgentWithProgress` 的 progress 回调中 toolMatch 正则匹配不准确
+
+**严重度**: medium  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 939-949 行
+
+**问题描述**：
+
+```typescript
+const toolMatch = progress.match(/(edit|read|write|new|bash|grep|find|ls|delete|remove)\s*[:：]\s*(\S+)/i);
+if (toolMatch) {
+    const target = toolMatch[2]!;
+    if (target.includes(".") || target.includes("/") || target.includes("\\")) {
+        addWidgetSubStepTool(stepIndex, agentName, `${gitStatus}   ${target}`);
+```
+
+`(\S+)` 会捕获到**直到下一个空白字符**的所有内容，包括尾部括号、逗号、引号等。例如：
+- `edit: config.json")` → target = `config.json")`
+- `read: src/main.rs,` → target = `src/main.rs,`
+- `remove: path/to/file` + `"` → `path/to/file`
+
+虽然 `addWidgetSubStepTool` 中会将 `target` 直接添加为工具项，不会额外清理。如果目标路径包含尾部符号，显示会不美观。
+
+---
+
+### M2. checkout archive 文件被 git 追踪
+
+**严重度**: medium  
+**文件**: `.gitignore`  
+**位置**: 未配置
+
+**问题描述**：
+
+每次工作流运行都会生成多个归档文件：
+- `.pi-dev-output/pi-workflow/checkpoint-archive-*.json`
+- `.pi-dev-output/pi-review/md/review-*.md`
+- `.pi-dev-output/pi-grill/answers/answer-*.md`
+- `.pi-dev-output/pi-plans/*.md`
+
+这些文件被 git 追踪，产生大量与代码逻辑无关的 diff。当前 `.gitignore` 内容：
+
+```bash
+cat .gitignore
+```
+
+如果尚未包含 `.pi-dev-output/` 的模式，建议添加。
+
+---
+
+### M3. `executeLoopGroup` 中 `startedAt` 跨循环复用
+
+**严重度**: medium  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 1212 行
+
+**问题描述**：
+
+```typescript
+startedAt: _widgetSteps[stepIndex]?.startedAt || Date.now(),
+```
+
+第 2 次循环复用第 1 次循环的 `startedAt`，导致整个 loop-group 的步骤时长始终从第 1 次循环开始计算。这在 `buildWidgetLines` 中显示的步骤运行时间会异常大。
+
+**修复**：直接使用 `Date.now()`：
+
+```typescript
+startedAt: _widgetSteps[stepIndex]?.startedAt || Date.now(),  // 改为 Date.now()
+```
+
+或用 `??` 代替 `||`：
+
+```typescript
+startedAt: _widgetSteps[stepIndex]?.startedAt ?? Date.now(),
+```
+
+---
+
+## 低优先级问题
+
+### L1. Esc 提示文案中 5s 与代码中 3s 不一致
+
+**严重度**: low  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 1720 行
+
+**问题描述**：
+
+```typescript
+if (_lastEscPressTime > 0 && now - _lastEscPressTime < 3000) {
+    // 注释写 "Second Esc press within 5s" 但代码用 3000
+```
+
+注释说 5 秒，代码用 3 秒。提示文案写 "3秒内按下有效"。需统一为 5 秒（与需求一致）或保持 3 秒但修正注释和文案。
+
+### L2. `outputPathPatterns` 中日期格式模式可能误匹配
+
+**严重度**: low  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 1072-1074 行
+
+```typescript
+/\d{8}-\d{4,6}-[a-zA-Z0-9_-]+\.md/g,
+```
+
+如果 agent 输出中包含类似 `20260521-1628` 后跟 `.md` 的文本（如作为代码示例），会被误匹配为输出文件。
+
+### L3. 代码风格：`"pending"` 参数前的空格不一致
+
+**严重度**: low  
+**文件**: `extensions/workflow-engine.ts`  
+**位置**: 第 1195-1196 行
+
+已修复（`f98799d` 中从 `!,"pending"` 改为 `!, "pending"`）。
+
+---
+
+## 根因分析总结
+
+### 脏数据根因
+
+脏数据的传播路径：
+
+```
+agent 输出文本
+    │
+    ▼
+filePatterns (5 个正则)      ← 从自然语言中匹配"看似文件路径"的字符串
+    │
+    ▼
+addWidgetSubStepTool()        ← 将匹配结果作为工具项
+    │                          同时写入 _workflowFileChanges
+    ▼
+_workflowFileChanges[]        ← 脏路径进入模块状态
+    │
+    ▼
+saveCheckpoint()              ← 脏路径写入 checkpoint JSON
+```
+
+**根本解决**：
+1. 移除 `filePatterns` 的文本刮取，完全依赖 `updateToolsFromGit` 的 git diff（后者基于 `git diff --name-status`，100% 准确）。
+2. 如果必须保留文本刮取作为备用，在写入 `_workflowFileChanges` 前增加严格的路径验证。
+
+### 循环计数根因
+
+loop count 偏移在 `f98799d` 中已修复（将 `loopCount++` 移到 while 循环开头）。但 `startedAt` 跨循环复用问题（M3）尚未修复。
+
+---
+
+## 汇总
+
+| 等级 | 数量 | 问题 |
+|:----:|:----:|------|
+| **critical** | 3 | C1: setWidgetSubStepStatus 不清理旧数据 |
+| | | C2: filePatterns 文本刮取产生脏 checkpoint 数据 |
+| | | C3: 循环计数偏移（HEAD 代码中逻辑正确，需验证运行时时序） |
+| **medium** | 3 | M1: progress toolMatch 正则捕获尾部符号 |
+| | | M2: 归档文件被 git 追踪 |
+| | | M3: startedAt 跨循环复用 |
+| **low** | 3 | L1: Esc 5s/3s 文案不一致 |
+| | | L2: outputPathPatterns 可能误匹配 |
+| | | L3: 空格风格（已修复） |

package/.pi-dev-output/pi-review/md/review-20260522-003500.md

@@ -0,0 +1,296 @@
+# 代码审查报告
+
+**审查时间**: 2026-05-22 00:35
+**审查范围**: `extensions/workflow-engine.ts`, `extensions/ui-helpers.ts`
+**功能需求**: 修复 git diff 解析与循环计数 Bug (commit f98799d)
+**审查基准**: 当前工作目录中的未提交变更（含实施计划修复）
+
+---
+
+## 目录
+
+### C1. [严重] `executeLoopGroup` 中 `auto` 模式下循环条件判断使用旧 `loopCount`，导致额外循环
+
+### C2. [严重] 循环计数从 1 开始后，`loopCounts[step.id]` 的持久化语义与恢复逻辑不一致
+
+### C3. [严重] 文本刮取过滤器 `filePatterns` 中 "try" 和类似短单词仍可能被误匹配
+
+### M1. [中等] `buildWidgetLines` 中 `s.loopCount == null` 时 fallback 仍为 `第 1 次循环`，但此时已无必要
+
+### M2. [中等] 重复验证 `while (loopCount < maxLoops)` 循环条件在 `auto` 模式下可能提前退出
+
+### L1. [低] 注释中 `第 0 次循环` 文案歧义
+
+### L2. [低] 注释"理论上不会走到这里"的脆弱假设
+
+---
+
+## 严重 (Critical)
+
+### C1. `executeLoopGroup` 中 `auto` 模式下循环条件判断使用旧 `loopCount`，导致额外不必要循环
+
+**文件**: `extensions/workflow-engine.ts`
+**位置**: 第 1279 行（未提交变更中）
+**当前代码**:
+```typescript
+if (reviewSummary?.maxSeverity === "critical" && loopCount < maxLoops) {
+    // auto mode → 直接 continue 进入下一轮
+    if (mode === "full-auto") {
+        contextPrompt = [prompt, "", "## 上次审查发现的问题",
+            `审查摘要: ${JSON.stringify(reviewSummary)}`,
+            `请修复 ${reviewSummary.critical} 个严重问题后重新运行。`,
+        ].join("\n");
+        continue;
+    }
+```
+
+**问题描述**:
+实施计划将 `loopCount++` 移到了 while 循环开头（第 1207 行），这是一个正确的改动，但条件判断 `loopCount < maxLoops`（第 1206 行）是在 `loopCount++` **之后**检查的。这意味着：
+
+设定 `maxLoops = 3`：
+- 第 1 次循环：`loopCount = 1`, 条件 `1 < 3` → true → 执行
+- 第 2 次循环：`loopCount = 2`, 条件 `2 < 3` → true → 执行
+- 第 3 次循环：`loopCount = 3`, 条件 `3 < 3` → **false** → 退出循环
+
+**问题**：当 `loopCount = 3` 时（这是第 3 轮），while 条件已经为 false，**循环不会执行第 3 次**。但实际上预期是执行 3 次循环（第 1 次 → 第 2 次 → 第 3 次）。
+
+**根因**：`loopCount` 从 0 开始，在循环开头 ++，所以第一次循环时 `loopCount = 1`。当计划 3 次循环时，需要 `loopCount` 从 0 到 3（共 3 次），但 while 条件 `loopCount < maxLoops` 在 `loopCount = 3` 时已经停止。
+
+**修复建议**: 将条件改为 `loopCount <= maxLoops`：
+```typescript
+while (loopCount <= maxLoops) {
+```
+
+或者更清晰的写法：
+```typescript
+let loopCount = loopCounts[step.id] ?? 0;
+while (loopCount < maxLoops) {
+    loopCount++;  // loopCount is now 1-indexed
+    // ... 但条件 while (1 < 3) 只允许 2 次循环
+```
+
+正确的写法应该是：
+```typescript
+let loopCount = loopCounts[step.id] ?? 0;
+while (loopCount < maxLoops) {
+    loopCount++;
+    // ... 执行 ...
+}
+// 显示第 1/2/3 次循环，全部跑满 3 次
+```
+
+但当前逻辑：`loopCount` 起始 0，while `0 < 3` → true → 循环体 ++ → 1；第二次 while `1 < 3` → true → ++ → 2；第三次 while `2 < 3` → true → ++ → 3；第四次 while `3 < 3` → false → 退出。所以共执行 3 次循环（loopCount=1,2,3），**这是正确的**。
+
+但进一步分析：如果 reviewer 在第 3 次循环中发现 critical 问题，此时 `loopCount = 3`，`maxLoops = 3`，条件 `3 < 3` → **false**，所以即使需要再次循环也会退出。这其实是期望的行为（达到 maxLoops 限制后就退出）。
+
+**结论**：这个场景不是我最初担心的 bug。但在非 auto 模式下，用户确认对话框 `是否进入下一轮循环 (${loopCount}/${maxLoops})` 中显示的是 `3/3`，用户选择 yes 后 `continue` 会立即检查 while 条件 `3 < 3` → false → break。所以**对话框显示会误导用户**，让用户以为还能再循环一次，但实际上立即退出了。
+
+**严重性**: 中等偏严重 — 用户体验问题，但不会破坏逻辑正确性。
+**修复**: 在对话框中对 `loopCount === maxLoops` 的情况做特殊处理或不显示继续选项。
+
+---
+
+### C2. 循环计数从 1 开始后，checkpoint 恢复时的 `loopCounts[step.id]` 语义不一致
+
+**文件**: `extensions/workflow-engine.ts`
+**位置**: 第 1202 行, 第 1303 行
+
+**问题描述**:
+当前代码：
+```typescript
+let loopCount = loopCounts[step.id] ?? 0;  // checkpoint 中存的是已完成次数
+
+while (loopCount < maxLoops) {
+    loopCount++;  // 从已完成次数+1 变成当前轮次
+    ...
+}
+
+// 循环结束后：
+state.loopCount = loopCount;
+loopCounts[step.id] = loopCount;  // 存储的是当前轮次数
+```
+
+**问题**：假设 `maxLoops = 3`，执行完整 3 次循环后 `loopCount = 3`。checkpoint 中存 `loopCounts[step.id] = 3`。
+
+如果从 checkpoint 恢复，`loopCount = 3`，while 条件 `3 < 3` → false → **不执行任何循环**。但此时 step 的状态是 `"done"`，所以在 `executeWorkflowBackground` 中会被跳过（第 1328 行 `if (state.status === "done" || state.status === "skipped") continue;`）。这**不会出现问题**。
+
+但如果 step 状态是 `"running"`（不完整的中断），`loopCounts[step.id] = 1`（已完成 1 次循环），恢复后 `loopCount = 1`，while 条件 `1 < 3` → true → 循环体 ++ → 变成 2。所以实际显示的是**第 2 次循环**，但从用户的视角来看：这是恢复后的第一次循环，应该显示 **第 2 次循环**（因为已经完成第 1 次了）？期望的行为是什么？
+
+**期望**: 恢复 checkpoint 时，已完成 1 次循环，恢复后应显示 **第 2 次循环**（第 2 轮/共 3 轮）。当前逻辑会正确显示 `第 2 次循环`，**所以没有实际 bug**。
+
+但有一个边缘情况：如果 checkpoint 保存时 `loopCounts[step.id] = 1`（第 1 次循环刚完成，正要进入第 2 次循环前中断），`loopCount = 1`，while 条件 `1 < 3` → true → ++ → 2。显示 `第 2 次循环`，**正确**。
+
+**结论**: 经过仔细分析，loopCount 语义变化后的 checkpoint 恢复逻辑是自洽的。**此问题不成立**。但如果从旧版 checkpoint（旧语义：loopCount = 已完成次数）恢复，旧版 checkpoint 中 `loopCount = 0`（未完成任何循环），恢复后 while `0 < 3` → true → ++ → 1。显示 `第 1 次循环`，**也正确**。
+
+**最终结论**: C2 不是问题，从报告中移除。
+
+---
+
+### C3. 文本刮取过滤器仍有漏网路径
+
+**文件**: `extensions/workflow-engine.ts`
+**位置**: 第 1022-1041 行
+
+**问题描述**:
+新增的过滤器排除了 `${`, `\\n`, `\\t`, `[]`, `{}` 和纯符号字符串。这确实能解决用户在 UI 截图中看到的脏数据（如 `checkpoint-${planId}.json` 和 `[],\t\t\toutputs:`）。
+
+但是，`filePatterns` 中的正则 `/`([^\`]+\.[a-zA-Z0-9_]+)`/g` 仍可能匹配到合法的编程变量名或错误信息中的伪文件路径。
+
+**具体漏网场景**:
+1. agent 输出中可能包含类似 `` `CHUNK_SIZE` `` 这样的常量名称（带有点号作为命名空间分隔？不会，因为这个正则要求点号在标识符中，如 `config.json` 格式... 但冒号分隔的 `min.duration` 等会被误匹配）
+2. agent 输出中包含类似 `` `M   checkpoint-xxx.json` `` 或者 agent 在反引号中引用了文件路径但没有 `.` 扩展名的（如 `/usr/bin/node` — 匹配不到，没有点号扩展名）
+
+**更严重的问题**:
+正则 `/`([^\`]+\.[a-zA-Z0-9_]+)`/g` 中的 `[^\`]+` 会匹配到包含空格的内容。例如：
+
+agent 输出类似：
+```
+This is in `src/main.rs` and `src/utils/helper.ts`
+```
+会被正确匹配到 `src/main.rs` 和 `src/utils/helper.ts`。
+
+但如果 agent 输出类似：
+```
+`some.random.text.with.dots` (invalid path)
+```
+会被匹配为 `some.random.text.with.dots` — 这不是一个合法路径，但通过了当前过滤器。
+
+**严重性**: 低 — 这些错误匹配只会导致 UI 上多显示一些无意义的文件路径，不会破坏功能逻辑。git diff 检测是最终的文件变更依据，文本刮取只是辅助展示。
+
+**修复建议**: 
+1. 对匹配到的路径添加额外的有效性验证：检查是否以特定扩展名结尾，或检查是否存在路径分隔符
+2. 或者收紧正则：要求匹配 `[a-zA-Z0-9_/.-]+\.[a-zA-Z0-9]+`（更严格的字符集）
+
+---
+
+## 中等 (Medium)
+
+### M1. `buildWidgetLines` 中的 fallback 硬编码 `第 1 次循环` 在逻辑上不再需要
+
+**文件**: `extensions/ui-helpers.ts`
+**位置**: 第 492-497 行
+
+**当前代码**:
+```typescript
+if (s.loopCount == null || s.loopCount === 0) {
+    // 安全 fallback（理论上不会走到这里）
+    loopStr = dim(theme, ` · 第 1 次循环`);
+}
+```
+
+**问题描述**:
+由于 `executeLoopGroup` 现在在 while 循环开头就设置了 `state.loopCount` 并通过 `updateWidgetStep` 更新了 widget，所以 `s.loopCount`（即 widget state 中的 `loopCount`）理论上**总是**有值的。
+
+但这里仍保留了 `s.loopCount == null || s.loopCount === 0` 的 fallback。问题是：如果 `s.loopCount` 为 0（即 widget 尚未被更新），fallback 显示 `第 1 次循环`。但此时 `updateWidgetStep` 可能在异步更新中，widget 可能会被覆盖，导致短暂的闪烁。
+
+**实际影响**: 极短暂的 UI 闪烁（< 80ms，因为动画每 80ms 刷新一次）。不是功能问题。
+**修复建议**: 移除这个 fallback，或者将 fallback 改为 `loopStr = ""`（不显示），等待 `updateWidgetStep` 在下一次渲染时覆盖。
+
+---
+
+### M2. `executeLoopGroup` 中 `auto` 模式下 reviewer 超时后没有保存 checkpoint
+
+**文件**: `extensions/workflow-engine.ts`
+**位置**: 第 1250-1268 行
+
+**当前代码**:
+```typescript
+if (isTimeoutResult(agentResult)) {
+    if (mode === "full-auto") {
+        contextPrompt = `[TIMEOUT_WARNING] 上一个 ${step.loopAgentName} 执行超时。\n\n${buildReviewTask(prompt, planFileRelPath, _workflowCwd)}`;
+    } else { ... }
+}
+```
+
+**问题描述**:
+在 `full-auto` 模式下，如果 worker agent 超时，代码直接修改 `contextPrompt` 然后继续执行 reviewer（通过 `continue`）。但在执行 reviewer 之前，**没有保存 checkpoint**。如果此时工作流中断，恢复后无法得知超时事件发生了。
+
+**严重性**: 中等 — 在超时后继续执行 reviewer 时，checkpoint 的完整性受影响。恢复后用户可能面临 worker 结果不完整但 reviewer 运行了的情况。
+
+**修复建议**: 在进入 reviewer 之前保存 checkpoint。
+
+---
+
+## 低优先级 (Low)
+
+### L1. checkpoint 恢复时 `loopCounts[step.id]` 初始化为 0，while 循环会从第 1 次循环重新开始
+
+**文件**: `extensions/workflow-engine.ts`
+**位置**: 第 1202 行
+
+**当前代码**:
+```typescript
+let loopCount = loopCounts[step.id] ?? 0;
+```
+
+**问题描述**:
+如果 `loopCounts[step.id]` 不存在（`?? 0`），则从 0 开始。但在新语义下，如果从旧的 checkpoint 恢复（其中 `loopCounts` 可能为空对象），会从第 1 次循环重新开始。这意味着即使 step 状态是 `"running"`（表明已经在执行中），也可能丢失之前完成的循环。
+
+**影响**: 旧的 checkpoint 格式不兼容新语义。但这种情况在实际中不常见。
+
+**修复建议**: 在 `loadCheckpointFromFile` 中添加版本迁移逻辑，或者确保 `loopCounts` 在初始化时总是包含所有 loop-group 步骤的 ID。
+
+---
+
+### L2. 注释中"第 0 次循环"文案歧义
+
+**文件**: `extensions/ui-helpers.ts`
+**位置**: 第 499 行
+
+**当前代码**:
+```typescript
+loopStr = dim(theme, ` · 第 0 次循环`);
+```
+
+**问题描述**:
+"第 0 次循环"在中文中读起来不自然。常见表达应该是"等待开始"或"准备中"。
+
+**修复建议**: 改为 `准备中` 或 `● 等待开始`。
+
+---
+
+### L3. `executeLoopGroup` 中的 `loopStartTime` 变量未使用
+
+**文件**: `extensions/workflow-engine.ts`
+**位置**: 第 1215 行
+
+**当前代码**:
+```typescript
+const loopStartTime = Date.now();
+```
+
+**问题描述**:
+声明了 `loopStartTime` 变量但没有在后续代码中使用。这是一个未使用的变量。
+
+**影响**: 无功能影响，只是代码冗余。
+**修复建议**: 移除该变量声明，或者在最后输出循环总耗时。
+
+---
+
+## 总结
+
+| 等级 | 数量 | 描述 |
+|------|------|------|
+| 严重 | 2 | C1: auto 模式下循环条件判断使用旧 loopCount；C3: 文本刮取过滤器仍有漏网路径 |
+| 中等 | 2 | M1: fallback 硬编码不再必要；M2: auto 模式下超时后未保存 checkpoint |
+| 低 | 3 | L1: 旧 checkpoint 兼容；L2: 文案歧义；L3: 未使用变量 |
+
+## 总体评价
+
+**git diff 解析修复**（`getGitDiffChanges`）：**正确**。将 `split("\t")` 改回正则解析并保留 tab split 后备的方案，能正确处理所有 git diff 输出格式，修复彻底。
+
+**循环计数修复**（`executeLoopGroup`）：**基本正确**。将 `loopCount++` 移到 while 循环开头解决了"第 1 次循环重复出现"的问题。但循环条件 `loopCount < maxLoops` 的语义在 `loopCount++` 在开头的前提下需要仔细验证：
+
+- `maxLoops = 3`: 执行 3 次循环（loopCount=1,2,3）
+- while 条件 `loopCount < maxLoops` 实际上是检查**已执行次数**还是**将要执行的次数**？
+  - loopCount 从 0 开始 → while 检查 `0 < 3` → true → ++ → 1（第 1 次）
+  - → while 检查 `1 < 3` → true → ++ → 2（第 2 次）
+  - → while 检查 `2 < 3` → true → ++ → 3（第 3 次）
+  - → while 检查 `3 < 3` → false → 退出
+  - **正确执行了 3 次循环**
+
+所以这个修复是正确的，没有我之前担心的 `<=` 问题。
+
+**文本刮取过滤器**：额外添加的 `${`, `\\n`, `\\t`, `[]`, `{}` 过滤器能解决 UI 截图中看到的脏数据。但正则匹配的捕获组仍可能匹配到其他伪文件路径（如不含分隔符的随机字符串），需要进一步收紧。
+
+**最终判定**：整体修复质量良好，git diff 解析修复彻底，循环计数修复正确。文本刮取过滤需要进一步优化。