@ghyper9023/pi-dev-workflow 0.4.1 → 0.4.2

package/.pi-dev-output/pi-review/md/review-20260521-214500.md

@@ -0,0 +1,270 @@
+# 代码审查报告：Grill/Input 文本换行与左方向键返回修复
+
+**审查日期**: 2026-05-21 21:45  
+**审查范围**: `extensions/grill-me-agent.ts` + `extensions/ui-helpers.ts` 的未提交改动  
+**审查目标**: 验证三个需求的实现质量：输入换行 / 选项换行 / ← 左方向键返回
+
+---
+
+## 文件差异总览
+
+| 文件 | 改动行数 | 风险等级 |
+|------|---------|---------|
+| `extensions/grill-me-agent.ts` | +30 / -8 | medium |
+| `extensions/ui-helpers.ts` | +26 / -1 | medium |
+
+---
+
+## 1. `extensions/grill-me-agent.ts` 审查
+
+### 1a) 左方向键拦截 (handleInput)
+
+```typescript
+if (backable && currentIndex > 1 && matchesKey(data, Key.left)) {
+    done("__BACK__");
+    return;
+}
+```
+
+**问题**: 左方向键的 `matchesKey` 检查先于 `selectList.handleInput(data)`。
+SelectList 只在 handleInput 内部更新 `selectedIndex` 的高亮状态。左方向键被拦截后，
+当前选中的 item 仍然正确（因为 SelectList 的 selectedIndex 没被改变），
+但容器的 `invalidate()` 没有被调用，不过 tui.requestRender() 未执行。
+
+**严重等级**: **low** — 当前不会引起可观察的 bug，但应调用 `container.invalidate()` 确保一致性。
+
+### 1b) 选项截断 + description (关键逻辑)
+
+```typescript
+const truncated = truncateToWidth(label, MAX_OPTION_LABEL, "...");
+return {
+    value: `opt-${i}`,
+    label: truncated,
+    description: truncated !== label ? opt : undefined,
+};
+```
+
+**分析**: `description` 字段会被 `normalizeToSingleLine` 处理（移除换行符），
+且 SelectList 渲染器对 description 也应用 `truncateToWidth`（剩余宽度可能很小）。
+对于超长选项文本，description 列宽度取决于终端剩余列数，如果终端很窄，
+description 仍然会被截断。但两列布局确实提供了更多可见内容。
+
+**严重等级**: **low** — 这是 pi-tui 库的设计限制，已经达到库能力范围内最好效果。
+
+### 1c) `__back__` 选项与左方向键返回路径的耦合
+
+grill-me-agent 中有两个返回上一题的路径：
+1. 通过选择 "← 返回上一题" SelectItem（value 为 `"__back__"`）
+2. 通过按 ← 方向键触发 `done("__BACK__")`
+
+调用方代码中：
+```typescript
+if (value === "__back__") return "__BACK__";
+```
+其中 `value` 来自 SelectList 的 `item.value`（即 `"__back__"`），大小写匹配正确。
+路径2直接传递 `"__BACK__"`（大写），由后续 `"__BACK__"` 检查处理。两路径殊途同归。
+
+**严重等级**: **low** — 当前功能正确，但若未来修改了 SelectItem 的 value 字符串，
+方向键路径不受影响（因为直接传常量字符串）。
+
+### 1d) hint 文案更新
+
+```typescript
+? "  ↑↓ 导航 • Enter 选择 • ← 返回上一题 • Esc 取消全部评审"
+```
+
+**问题**: 文案正确、清晰。无问题。
+
+---
+
+## 2. `extensions/ui-helpers.ts` 审查
+
+### 2a) 左方向键拦截破坏 Input 光标左移 (CRITICAL)
+
+```typescript
+if (backable && matchesKey(data, Key.left)) {
+    done(BACK_MARKER);
+    return;
+}
+// ... later:
+input.handleInput(data);
+```
+
+**严重问题**: **所有 `backable=true` 场景下，Input 组件的光标左移功能完全丢失**。
+
+**根因分析**:
+1. pi-tui 的 Input 组件中，左方向键绑定 `tui.editor.cursorLeft`（详细见 keybindings: `defaultKeys: ["left", "ctrl+b"]`）
+2. 本实现将 `matchesKey(data, Key.left)` 放在 `input.handleInput(data)` **之前**，且条件满足时直接 return
+3. Input.handleInput 永远不会收到左方向键事件，光标永远无法左移
+
+**影响范围**: 所有 `uiInput(ctx, ..., backable=true)` 调用的场景：
+- grill "自定义输入"环节（用户输入长文本后想修改前面的字符）
+- wizard 中可返回的上一步输入（如 dev-feat 的"核心功能描述"）
+
+**替代方案不充分**: 实施计划提到用户可用 `Ctrl+B` 替代左方向键光标左移。
+但 `Ctrl+B` 不是常见的终端快捷键（Emacs 用户熟悉，但 Vim 用户和普通终端用户不熟悉），
+且实施计划中没有在 UI hint 文本中提示 `Ctrl+B` 替代方案。
+
+**修复建议**:
+推荐 **方案 A**（最小改动，保留最佳用户体验）: 仅在输入框为空或光标在最左侧时拦截左方向键做"返回"，
+否则作为正常光标左移：
+
+```typescript
+// 左方向键 → 光标在最左侧或输入为空时触发返回
+if (backable && matchesKey(data, Key.left)) {
+    const cursor = getInputCursor?.(input); // 需要获取 Input 的 cursor 位置
+    if (this.cursorPosition === 0) {
+        done(BACK_MARKER);
+        return;
+    }
+}
+```
+
+但 Input 组件没有公开 cursor 属性（private）。替代方案：检查 input.getValue() 是否为空。
+
+**推荐方案 B**: 将"返回"功能从裸 `←` 改为 `Alt+←`（pi-tui 中已绑定 `tui.editor.cursorWordLeft`）或 `Ctrl+Shift+←`（已有实现）。
+
+**推荐方案 C（最小改动）**: 将 `backable` 左方向键拦截改为仅在 `input.getValue()` 为空时生效：
+
+```typescript
+if (backable && matchesKey(data, Key.left) && input.getValue().length === 0) {
+    done(BACK_MARKER);
+    return;
+}
+```
+
+这样用户在输入内容后按 ← 可以编辑，而在空输入时按 ← 返回。
+
+### 2b) 预览区域 Text 组件在空文本时仍输出一行
+
+```typescript
+const previewText = new Text("", 0, 0);
+```
+
+**中等问题 — medium**: **即使输入框为空，预览区域始终额外输出 1 行空白 + 1 Spacer 间距行**。
+
+经检查 pi-tui Text 组件的实现：
+```javascript
+// text.js render方法
+if (!this.text || this.text.trim() === "") {
+    const result = [];  // 早期返回空数组
+    ...
+    return result;
+}
+// ...
+return result.length > 0 ? result : [""];  // 如果 result 为空，返回 [""] 一行空行
+```
+
+早期返回处返回 `[]`（空数组），但最后一行 `return result.length > 0 ? result : [""]` **不会被执行**
+因为早期 return 已经走了。实际 `setText("")` 后 Text.render 返回 `[]`（输出 0 行）。
+
+所以 `new Text("", 0, 0)` 在空字符串时输出0行，但 paddingY=0, paddingX=0 使其没有边距。
+`render()` 实际执行路径：
+1. `!this.text` → `true`（因为 `this.text = ""`，空字符串是 falsy）
+2. 进入早期返回：`const result = []; return result;` → 返回 `[]`（空数组）
+
+**结论**: 空文本时 Text 输出 0 行。但后面的 `Spacer(1)` 固定输出 1 行空白间距。
+所以在无输入时 UI 有 **1 行额外空白**，不是 2 行。
+
+**严重等级**: 从 medium 降为 **low** — 仅 1 行空白的视觉影响，功能正常。
+
+### 2c) wrapTextWithAnsi 在 handleInput 中无条件调用
+
+```typescript
+const val = input.getValue();
+if (val.length > 0) {
+    const wrapped = wrapTextWithAnsi(val, width - 4);
+    ...
+}
+```
+
+**问题**: 每次按键都读取 value、换行、拼接 ANSI 字符串。对数百字符的输入性能可忽略，
+但 es module 反复调用 `wrapTextWithAnsi` 对大文本可能产生轻微延迟。
+
+**严重等级**: **low** — 性能微优化。
+
+---
+
+## 3. 整体架构审查
+
+### 3a) 左方向键在三个层级的冲突 (CRITICAL)
+
+**严重问题**: 
+
+左方向键在代码中有三种语义：
+1. **Input 原生**: 光标左移一个字符（`tui.editor.cursorLeft`）
+2. **uiInput 层**: 返回上一题（当 `backable=true`）
+3. **showQuestionTUI 层**: 返回上一题（当 `backable && currentIndex > 1`）
+
+路径 #3 → #2 → #1，是串联关系。当用户进入自定义输入后：
+- 按 ← → uiInput 拦截 → 返回 BACK_MARKER → showQuestionTUI → 返回上一题
+- 用户本意：在输入框中左移光标修改文字 → 无法实现
+
+两处左方向键拦截会同时影响不同的 UI 层级，用户流程交叉时无法区分
+"在 SelectList 中返回上一题"和"在 Input 中光标左移"。
+
+### 3b) backable=false 场景保留
+
+在 `uiInput` 中，当 `backable=false` 时，左方向键正常转发给 Input 组件（光标左移）。
+这是正确的行为，原有功能没有被破坏。
+
+### 3c) Ctrl+Shift+← 保留
+
+原有 `Ctrl+Shift+←` 返回功能被保留，与新增裸 ← 键并行。
+两者功能冗余但不冲突。
+
+---
+
+## 4. 测试覆盖分析
+
+| # | 测试场景 | 状态 | 问题 |
+|---|---------|------|------|
+| 1 | Grill 左方向键返回 | ✅ 已实现 | SelectList 层级正常 |
+| 2 | Grill 长选项显示 | ✅ 已实现 | description 在窄终端仍被截断（库限制） |
+| 3 | Grill 自定义输入 ← 返回 | ✅ 路径可达 | **但输入中无法左移光标** |
+| 4 | dev-* 长文本预览 | ✅ 已实现 | 空输入时有 1 行多余间距 |
+| 5 | 普通 Esc 取消 | ✅ 未改变 | — |
+| 6 | Ctrl+Shift+←/→ 导航 | ✅ 保留 | — |
+| 7 | 非 backable 左方向键 | ✅ 保留 | — |
+| 8 | 预览内容实时更新 | ✅ 按 Backspace 测试通过 | — |
+
+---
+
+## 汇总
+
+| 等级 | 数量 | 说明 |
+|------|------|------|
+| **critical** | 1 | backable=true 时 uiInput 中左方向键拦截导致 Input 光标左移完全失效 |
+| **medium** | 1 | 预览区域 Spacer 无条件占用行间距（视觉影响） |
+| **low** | 3 | container.invalidate() 缺失；wrapTextWithAnsi 性能微调；__BACK__ 路径耦合 |
+
+---
+
+## 关键问题详解
+
+### Critical 1: uiInput 左方向键拦截破坏光标左移
+
+**文件**: `extensions/ui-helpers.ts` 第 ~263 行
+**影响**: 所有 `backable=true` 的 uiInput 场景
+**根本原因**: `matchesKey(data, Key.left)` 在 `input.handleInput(data)` 之前拦截并 return
+
+**修复方案推荐**: 
+**方案 C（最小改动）**: 仅在输入框为空时拦截 ← 作为返回：
+```typescript
+if (backable && matchesKey(data, Key.left) && input.getValue().length === 0) {
+    done(BACK_MARKER);
+    return;
+}
+```
+这样做的好处：
+- 空输入时 ← 返回（用户无内容需要编辑）
+- 有输入内容时 ← 正常光标左移（用户可以修改文字）
+- 仍可使用 Ctrl+Shift+← 在任何状态下返回
+
+---
+
+## 总结
+
+实现的功能需求基本正确覆盖，但 `uiInput` 中的左方向键拦截过于激进，
+没有考虑 Input 组件本身对左方向键的依赖。其他改动在可接受范围内。
+主要建议修复 `uiInput` 中左方向键拦截的逻辑，增加光标位置或输入内容检查。

package/.pi-dev-output/pi-review/md/review-20260521-215158.md

@@ -0,0 +1,214 @@
+# 代码审查报告 — git diff 解析与循环计数 Bug
+
+**审查日期**：2026-05-21 21:51  
+**审查范围**：`extensions/workflow-engine.ts`, `extensions/ui-helpers.ts`  
+**审查者**：代码审查专家  
+
+---
+
+## 严重性问题
+
+### C1. [critical] 文本刮取过滤器不完整：`filePatterns` pattern 4 仍可能匹配包含 `{}` 或 `[]` 的脏数据
+
+**文件**：`extensions/workflow-engine.ts`  
+**位置**：`runAgentWithProgress` 函数，约第 1036~1044 行
+
+**问题描述**：
+`filePatterns` 中的最后一个 pattern：
+```typescript
+/(?:^|\n)\s*(?:edit|new|delete|read|modify|create|update|add|remove)\s*[:：]\s*([^\n]+\.[a-zA-Z0-9_]+)/gim
+```
+要求匹配的文件路径**必须包含 `.`**（`\.[a-zA-Z0-9_]+`），这排除了大部分纯符号文本。但当前已有的三个额外过滤器：
+```typescript
+if (filePath.includes("${") || filePath.includes("\\n") || filePath.includes("\\t")) continue;
+if (filePath.includes("[]") || filePath.includes("{}")) continue;
+if (filePath.match(/^[\s,;)\]}]+$/)) continue;
+```
+存在一个盲区：如果 agent 输出中包含类似 `modify: some.text.[]` 或 `update: file.name.{key}` 这样的文本（即包含 `.` 且包含 `{}` 或 `[]`），`filePath.includes("{}")` 和 `filePath.includes("[]")` 可以拦截。但如果文本是 `modify: arrays.0.name`（没有 `[]` 但语义上不是文件路径），过滤器无法拦截。
+
+**根因**：
+文本刮取始终是脆弱的 —— 正则无法完全区分自然语言中的"看起来像文件路径"的文本和真正的文件路径。当前代码虽然添加了多层过滤器，但 agent 输出千变万化，总会有漏网之鱼。
+
+**影响**：
+在 agent 输出包含包含 `.` 的代码片段或 JSON 路径（如 `config.data.0.name`、`output.path` 等）时，widget 中会显示这些虚假的 "M   config.data.0.name" 条目，造成 UI 混乱。
+
+**建议修复**：
+1. 最彻底的方式：完全依赖 `updateToolsFromGit`（git diff）来做文件变更检测，将文本刮取改为纯提示性（不影响 `_workflowFileChanges`）。
+2. 或者添加更严格的路径验证：验证文件是否真实存在于磁盘上（`fs.existsSync`），虽然会影响性能但准确率最高。
+3. 至少添加对数字索引路径（如 `data.0.name`、`list.1.title`）的过滤。
+
+**严重性**：critical — 直接导致 UI 显示脏数据，影响用户对工作流状态的判断。
+
+---
+
+### C2. [critical] 循环计数偏移：`loopCount` 在 while 循环开头递增导致 checkpoint 恢复时语义不一致
+
+**文件**：`extensions/workflow-engine.ts`  
+**位置**：`executeLoopGroup` 函数
+
+**问题描述**：
+当前（未提交的）修改将 `loopCount++` 从 reviewer 完成之后**移到了 while 循环最开头**。逻辑是：
+```
+while (loopCount < maxLoops) {
+    loopCount++;  // 现在 loopCount 从 0 → 1
+    // ... 执行 worker ...
+    // ... 执行 reviewer ...
+    // 如果 need_continue，continue → 再次 loopCount++ → 2
+}
+```
+
+这个修改解决了 UI 显示问题（不再显示两次 "第 1 次循环"），但引入了新的不一致性：
+
+1. **checkpoint 恢复时的语义偏移**：
+   - 旧语义（f98799d commit）：`loopCount` = "已完成次数"，`loopCounts[step.id]` 保存在 checkpoint 中
+   - 新语义：`loopCount` = "当前正在进行的轮次"（从 1 开始）
+   - 从 checkpoint 恢复时：`let loopCount = loopCounts[step.id] ?? 0;` — 如果之前完成了 1 次循环但被中断，`loopCounts[step.id] = 1`（旧语义的"已完成 1 次"），恢复后进入 while 时 `loopCount < maxLoops`，然后 `loopCount++` 变成 2。但恢复时应该**从第 2 次循环开始**（第 1 次已完成），所以行为是正确的。✅
+
+2. **初始 pending 状态显示问题**：
+   - `buildWidgetLines` 中 `isRunning` 的 fallback 检查 `if (s.loopCount == null || s.loopCount === 0)` 会 fallback 到"第 1 次循环"
+   - 但 `executeLoopGroup` 一开始就设置了 `state.loopCount = loopCount`（=1），所以 UI 永远不会走到这个 fallback
+   - 然而，如果 widget 的动画渲染在 `executeLoopGroup` 设置 loopCount 之前就触发，就可能看到短暂的"第 1 次循环"fallback
+
+3. **最大的问题**：`buildWidgetLines` 中 `isRunning` 时的 fallback 逻辑现在**永远不会被执行**，因为 `executeLoopGroup` 在 while 循环开头立即设置了 `loopCount = 1`。但这段代码仍然存在，是个死代码。
+
+**影响**：
+主要风险是 checkpoint 恢复场景下如果 loopCounts 的存储格式在旧版和新版之间切换，可能产生计数偏移。但当前分析显示实际行为可能是正确的。代码可读性降低，有死代码残留。
+
+**建议修复**：
+清理 `buildWidgetLines` 中 `isRunning` 分支下无用的 fallback 代码，改为直接依赖 `s.loopCount`。
+
+**严重性**：critical — 循环计数偏移是用户明确报告的 bug，虽然当前修改在"正常流程"下修复了它，但有死代码残留和 checkpoint 兼容性风险。
+
+---
+
+## 中等问题
+
+### M1. [medium] `buildWidgetLines` 中 `isRunning` 的 fallback 逻辑是死代码
+
+**文件**：`extensions/ui-helpers.ts`  
+**位置**：`buildWidgetLines` 函数
+```typescript
+if (isRunning) {
+    if (s.loopCount == null || s.loopCount === 0) {
+        // 安全 fallback（理论上不会走到这里）
+        loopStr = dim(theme, ` · 第 1 次循环`);
+    }
+}
+```
+
+**问题描述**：
+当前 `executeLoopGroup` 在 while 循环的第一行就设置了 `state.loopCount = loopCount`（=1），所以 widget 状态中的 `s.loopCount` 在 `isRunning` 状态下永远不会为 `null` 或 `0`。这段 fallback 代码永远无法被执行。
+
+实际上，这个 fallback 的存在表明原本的设计存在缺陷 —— 在 `f98799d` commit 中，`loopCount++` 被放在 reviewer 完成之后，所以 UI 在 worker 运行时 loopCount 还没更新，才需要这个 fallback 在 UI 层面补显示"第 1 次循环"。
+
+**建议修复**：
+移除 `isRunning` 分支下的 fallback 代码，因为这个场景现在不会发生，而且如果发生了（因某个竞态条件），显示错误的"第 1 次循环"比不显示更糟糕。
+
+**严重性**：medium — 死代码不影响功能，但降低可维护性，且未来如果代码重构可能造成误导。
+
+---
+
+### M2. [medium] `getGitDiffChanges` 的 `git status --porcelain` 解析中 `statusPrefix.startsWith("A")` 过于宽松
+
+**文件**：`extensions/workflow-engine.ts`  
+**位置**：`getGitDiffChanges` 函数
+```typescript
+if (filePath && !seen.has(filePath) && (statusPrefix === "??" || statusPrefix === "A " || statusPrefix.startsWith("A"))) {
+```
+
+**问题描述**：
+`statusPrefix.startsWith("A")` 会匹配所有以 `A` 开头的状态码，包括：
+- `"A "` — 已暂存的新增文件（正确）
+- `"AM"` — 已暂存新增但又有修改（正确但不常见）
+- `"AD"` — 已暂存新增但又有删除（罕见）
+- 但不应该匹配 `"??"`（未追踪，已有专用处理）
+
+更严重的是，`statusPrefix` 是 `trimmed.match(/^(..)\s+(.+)$/)` 的第一个捕获组，它捕获了**两个字符**。但 `trimmed` 是 `line.trim()` 后的结果，对于 `?? somefile`，`statusPrefix` 是 `"??"`，对于 `"?? somefile"` 的 `trimmed` = `"?? somefile"`，`match` 给出 `statusPrefix = "??"`，正确。对于 `"A  somefile"`（两个空格），`statusPrefix = "A "`（A + 空格），正确。
+
+但如果有一行是 `"A somefile"`（一个空格），这是不合法的 porcelain 格式，但 trim 后是 `"A somefile"`，match 给出 `statusPrefix = "A "`（因为 `(..)` 匹配第一个和第二个字符，第二个字符是空格）。
+
+实际上这个逻辑是正确的，只是看起来有点让人担心。风险很低。
+
+**建议修复**：
+明确只匹配已知的 porcelain 状态码：
+```typescript
+const ADD_CODES = new Set(["A ", "AM", "AD"]);
+if (filePath && !seen.has(filePath) && (statusPrefix === "??" || ADD_CODES.has(statusPrefix))) {
+```
+
+**严重性**：medium — 当前逻辑实际正确但不够严谨，可能在未来 git 版本输出变化时出现误匹配。
+
+---
+
+### M3. [medium] `addWidgetSubStepTool` 中 `gitMatch` 正则过于宽松
+
+**文件**：`extensions/workflow-engine.ts`  
+**位置**：`addWidgetSubStepTool` 函数
+```typescript
+const gitMatch = !oldMatch ? tool.match(/^([MAD])\s{2,}(.+)$/) : null;
+```
+
+**问题描述**：
+这个正则 `^([MAD])\s{2,}(.+)$` 匹配以 `M`、`A` 或 `D` 开头，后跟至少 2 个空格，然后任意内容。这意味着如果任何字符串以 `M ` 开头（比如 agent 输出中的 "More interesting..." 或 "Add new feature..."），它都可能被匹配。
+
+但实际上这个函数只被 `addWidgetSubStepTool` 调用，而该函数的调用者已经确保了 `tool` 参数要么来自 progress 回调（格式化的 `M   path`），要么来自 `updateToolsFromGit`（格式化的 `M   path`），要么来自文本刮取（格式化的 `M   path`）。所以误匹配的**源头**在于文本刮取，而不是这里。
+
+不过，多做一层防御总是好的。可以加强验证：确保捕获的 `filePath` 确实是一个真实存在的文件路径（或至少看起来像路径）。
+
+**严重性**：medium — 依赖上游调用的正确性，自身防御不足。
+
+---
+
+## 低优先级问题
+
+### L1. [low] `extractFileChanges` 函数中 `sendWorkflowResult` 使用 `sendMessage` 可能产生冗余消息
+
+**文件**：`extensions/ui-helpers.ts`  
+**位置**：`sendWorkflowResult` 函数
+
+**问题描述**：
+工作流完成时，`executeWorkflowBackground` 调用 `sendWorkflowResult` 发送完成消息。同时，在工作流取消时，cancel callback 中也调用了 `sendWorkflowResult`。如果工作流在自然完成后 cancel callback 也被触发（竞态条件），可能发送两条重复的完成消息。
+
+**严重性**：low — 仅在极罕见的竞态条件下可能发生。
+
+---
+
+### L2. [low] `populatePredefinedSubSteps` 在 checkpoint 恢复时可能跳过 sub-step 初始化
+
+**文件**：`extensions/workflow-engine.ts`  
+**位置**：`populatePredefinedSubSteps` 函数
+
+**问题描述**：
+函数开头的 `if (step.subSteps && step.subSteps.length > 0) return;` 意味着如果 widget step 已经包含 sub-steps（从 checkpoint 恢复时），就不会重新初始化。但 checkpoint 中的 sub-steps 可能没有 `detail` 字段（如 `超时时间60m`），导致恢复后的 sub-step 缺少超时时间显示。
+
+**严重性**：low — 仅影响 checkpoint 恢复后的展示细节。
+
+---
+
+### L3. [low] 重复的 `extractTaskSummary` 函数定义
+
+**文件**：`extensions/workflow-engine.ts` 和 `extensions/ui-helpers.ts`
+
+**问题描述**：
+两个文件各自定义了 `extractTaskSummary` 函数，功能完全一致。这是代码重复，如果未来需要修改需要同步修改两处。
+
+**严重性**：low — 不影响功能，单是代码风格问题。
+
+---
+
+## 总结
+
+当前代码已经针对 `git diff 解析` 和 `循环计数偏移` 两个 bug 做了本地修复（未提交）：
+
+1. **git diff 解析**：在本地已从 `split("\t")` 改回正则解析，并保留了 tab split 作为后备。✅
+2. **文本刮取脏数据**：已添加三层额外过滤器（`${}`, `[]`/`{}`, 纯符号）来拦截脏数据。✅
+3. **循环计数偏移**：已将 `loopCount++` 从 reviewer 完成后移到 while 循环开头。✅
+
+但存在以下**残留问题**：
+
+- **C1**: 文本刮取方案仍然脆弱，建议完全依赖 git diff 而非文本刮取
+- **C2 + M1**: 循环计数 fallback 是死代码，需要清理
+- **M2**: `statusPrefix.startsWith("A")` 过于宽松
+- **M3**: `addWidgetSubStepTool` 的 gitMatch 正则防御不足
+
+建议优先解决 C1 和 C2+M1，然后处理 M2-M3，最后清理 L1-L3 的代码风格问题。

package/.pi-dev-output/pi-review/md/review-20260521-234500.md

@@ -0,0 +1,201 @@
+# 审查报告 — 超时时间/循环次数/git diff 解析修复
+
+**审查时间**: 2026-05-21 23:45  
+**审查范围**: `extensions/ui-helpers.ts`, `extensions/workflow-engine.ts`, `extensions/dev-prompts.ts`, `tests/test-loopcount-timeout-fix.mjs`  
+**审查提交**: 当前 HEAD (`01413c9`) + 未暂存修改  
+
+---
+
+## 严重（Critical）
+
+### C1. loopCount 显示逻辑在跨循环迭代期间显示错误的循环编号
+
+**位置**: `extensions/workflow-engine.ts` `executeLoopGroup()` (~L1190-1265) & `extensions/ui-helpers.ts` `buildWidgetLines()` (~L485-494)
+
+**根因**: `loopCount` 变量代表的是 **已完成的循环次数**，而非当前进行的循环次数。在 `executeLoopGroup` 中：
+
+1. `loopCount++` 在每次循环的 **末尾**（reviewer 完成后）执行
+2. 进入下一次循环时，`setWidgetSubStepStatus` 重置 sub-step 为 pending 并触发 `refreshWidget()`，此时 widget 中 step 的 `loopCount` 仍是上一次循环完成后的值
+3. 因此在 worker/reviewer 运行期间（可能需要几分钟），UI 显示的是上一次已完成循环的次数，而非当前循环的次数
+
+**具体场景**：
+- 第 1 次循环 worker/reviewer 运行 → `loopCount=0` → `isRunning` fallback 显示"第 1 次循环" ✅
+- 第 1 次循环完成 → `loopCount++` → `updateWidgetStep` → 显示"第 1 次循环" ✅
+- 第 2 次循环 worker 运行 → `loopCount=1`(仍为第 1 次完成值) → 显示仍是"第 1 次循环" ❌（应为"第 2 次循环"）
+- 第 2 次循环完成 → `loopCount=2` → 显示"第 2 次循环" ✅
+- 第 3 次循环 worker 运行 → `loopCount=2`(仍为第 2 次完成值) → 显示"第 2 次循环" ❌
+
+**修复建议**: 在 `buildWidgetLines` 中，当 `isRunning` 状态且 `s.maxLoops != null` 时，显示的循环次数应为 `s.loopCount + 1`（当前正在进行的循环）而非 `s.loopCount`。具体来说：
+
+```typescript
+// 当前逻辑（错误）：
+if (s.loopCount != null && s.loopCount > 0) {
+    loopStr = dim(theme, ` · 第 ${s.loopCount} 次循环`);
+} else if (s.maxLoops != null) {
+    if (isRunning) {
+        loopStr = dim(theme, ` · 第 1 次循环`);  // 硬编码 1
+    }
+}
+
+// 修复后：
+if (s.maxLoops != null) {
+    const displayCount = (s.loopCount ?? 0) + (isRunning && !isDone ? 1 : 0);
+    // 如果 loopCount=0（pending），显示第 0 次
+    // 如果 isRunning 且 loopCount=1，显示第 2 次
+    // 如果 isDone，显示 loopCount
+    if (displayCount > 0 || isPending) {
+        loopStr = dim(theme, ` · 第 ${displayCount} 次循环`);
+    }
+}
+```
+
+### C2. executeLoopGroup 重置 sub-step 状态时丢失 worker 的 tools/outputs 历史
+
+**位置**: `extensions/workflow-engine.ts` `executeLoopGroup()` L1194-1195
+
+```typescript
+// 每次循环开始时重置 sub-step 状态
+setWidgetSubStepStatus(stepIndex, step.loopAgentName!, "pending");
+setWidgetSubStepStatus(stepIndex, step.reviewAgentName!, "pending");
+```
+
+**根因**: `setWidgetSubStepStatus` 只将 sub-step 的 `status` 改为 `"pending"`，并没有重置 `tools`、`outputs`、`startedAt` 等字段。当进入新一轮循环时，旧的 tool 记录仍会显示在 UI 上，导致新 worker 的结果和旧 worker 的结果混合显示。
+
+然而，更严重的问题是 **`runAgentWithProgress` 在创建新的 sub-step 时检查 `existing = step.subSteps?.find(s => s.agent === agentName)`**，它找到旧 sub-step 后**不会清除旧数据**，而是直接复用：
+
+```typescript
+const existing = step.subSteps.find(s => s.agent === agentName);
+if (!existing) {
+    // 创建新的...
+} else {
+    // Update existing sub-step status, startedAt, and detail
+    existing.status = "running";
+    existing.startedAt = agentStartTime;
+    existing.detail = `超时时间${formatTimeout(timeoutMs)}`;
+    refreshWidget();
+}
+```
+
+注意：`tools` 和 `outputs` 没有被清空！所以在第 2 次循环的 worker 运行时，旧的 tools 和 outputs 仍然会显示在 UI 上。
+
+**修复建议**: 在 `executeLoopGroup` 重置 sub-step 时，同时清空 tools 和 outputs：
+
+```typescript
+// 每次循环开始时重置 sub-step 状态并清空历史
+const loopSub = _widgetSteps[stepIndex]?.subSteps?.find(s => s.agent === step.loopAgentName);
+const reviewSub = _widgetSteps[stepIndex]?.subSteps?.find(s => s.agent === step.reviewAgentName);
+if (loopSub) { loopSub.status = "pending"; loopSub.tools = []; loopSub.outputs = []; loopSub.startedAt = undefined; }
+if (reviewSub) { reviewSub.status = "pending"; reviewSub.tools = []; reviewSub.outputs = []; reviewSub.startedAt = undefined; }
+refreshWidget();
+```
+
+或者，在 `runAgentWithProgress` 中复用 sub-step 时清空 tools/outputs。
+
+---
+
+## 中等（Medium）
+
+### M1. 超时时间格式化不一致
+
+**位置**: `extensions/ui-helpers.ts` `formatTimeout()` (~L368-371)
+
+```typescript
+export function formatTimeout(ms: number): string {
+    const m = Math.floor(ms / 60000);
+    const s = Math.floor((ms % 60000) / 1000);
+    return s > 0 ? `${m}m${s}s` : `${m}m`;
+}
+```
+
+**问题**: 当超时时间恰好是整分钟（如 15min=900000ms）时，`formatTimeout` 返回 `15m`（不带秒）。这与 `formatDurationFull` 的行为不一致——`formatDurationFull` 在 `ms >= 60000` 时总是显示 `m` 和 `s` 两段（即使秒数为 0 也会显示 `0s`）。
+
+在 UI 上会看到 `(52.6s/超时时间15m)`，而预期应为 `(52.6s/超时时间15m0s)` 或至少格式一致。不过这个差异很细微，且现有的测试用例验证了 `15m` 格式是可接受的。
+
+**建议**: 如果希望一致性，可以改为 `return s > 0 ? `${m}m${s}s` : `${m}m0s`;`。
+
+### M2. 测试覆盖不完整
+
+**位置**: `tests/test-loopcount-timeout-fix.mjs`
+
+**问题**: 
+1. 测试用例仅通过静态代码分析（`string.includes()`）验证代码存在性，没有模拟执行验证运行时行为
+2. 没有测试验证跨多个循环迭代的 loopCount 正确性（如第 2 次循环显示"第 2 次循环"）
+3. 没有测试验证 `getGitDiffChanges` 的 git diff 解析正确处理制表符分隔的格式
+
+**建议**: 
+- 添加针对 `getGitDiffChanges` 的单元测试，模拟 `git diff --name-status` 输出并验证解析结果
+- 添加对 `buildWidgetLines` 中 loopCount 在 `isRunning` 状态下的测试
+
+### M3. 子代理行超时显示可能存在重复/格式问题
+
+**位置**: `extensions/ui-helpers.ts` `buildWidgetLines()` ~L560-565
+
+```typescript
+if (sub.detail && sub.detail.includes("超时时间")) {
+    subTimeoutStr = dim(theme, `/${sub.detail}`);
+}
+```
+
+**问题**: `sub.detail` 的值是 `"超时时间60m"`（来自 `runAgentWithProgress`），当拼接到 UI 行时，会变成 `(52.6s/超时时间60m)`。但 UI 示例中期望的格式是 `(52.6s/超时时间60m)`，这没问题。
+
+但如果 `sub.detail` 因某种原因包含多余字符（如空格或换行），或者被后续代码修改，可能导致格式异常。且 `sub.detail.includes("超时时间")` 检查是字符串包含匹配，过于宽松，应改为更精确匹配，如 `sub.detail.startsWith("超时时间")`。
+
+---
+
+## 低优先级（Low）
+
+### L1. setWidgetSubStepStatus 缩进不一致
+
+**位置**: `extensions/workflow-engine.ts` `setWidgetSubStepStatus()` ~L781-791
+
+```typescript
+function setWidgetSubStepStatus(stepIndex: number, agentName: string, status: WorkflowSubStepWidgetState["status"]): void {
+    const step = _widgetSteps[stepIndex];       // Tabs → spaces
+    if (!step) return;
+    const sub = step.subSteps?.find(s => s.agent === agentName);
+    if (sub) {
+		sub.status = status;                     // Spaces → tabs
+        refreshWidget();
+    }
+}
+```
+
+这个函数存在混用 tab 和 space 缩进的问题（`step` 行用空格，`sub` 行用 tab），这在 commit 01413c9 中引入。
+
+### L2. 注释中示例 UI 未更新
+
+**位置**: `extensions/ui-helpers.ts` ~L399-415
+
+`buildWidgetLines` 上方的 JSDoc 注释中的 UI 渲染示例仍然显示旧格式：
+```
+▶ ⠋ 🔧实施代码 → 审查 · 第 1 次循环  (1s/超时时间15m)
+    |__ worker ·
+```
+
+没有显示子代理行中应有的超时信息：
+```
+    |__ worker · (1s/超时时间15m)
+```
+
+### L3. git status --porcelain 解析边界情况
+
+**位置**: `extensions/workflow-engine.ts` `getGitDiffChanges()` ~L326-330
+
+```typescript
+const statusPrefix = trimmed.slice(0, 2);
+const filePath = trimmed.slice(3).trim();
+```
+
+当 `trimmed` 长度小于 3 时（如空行或长度异常的输入），`trimmed.slice(3)` 可能返回空字符串，然后 `trim()` 返回 `""`，导致 `if (filePath && ...)` 条件失败。这实际上是安全的（不会产生假阳性），但代码缺乏显式的长度检查，可读性略差。
+
+---
+
+## 总结
+
+本次审查发现 2 个严重问题、3 个中等问题和 3 个低优先级问题。
+
+**严重问题 C1** 是最关键的用户可见 bug：跨循环迭代期间，UI 显示的循环编号滞后。例如，当第 2 次循环的 worker 运行时，UI 仍显示"第 1 次循环"。需要修改 `buildWidgetLines` 中的 `loopCount` 显示逻辑，在运行时使用 `loopCount + 1` 作为当前循环编号。
+
+**严重问题 C2** 是另一个用户可见问题：跨循环迭代时，旧的 tools/outputs 数据未被清空，导致新 worker 的结果与旧数据混合显示。
+
+当前未暂存的 diff 已正确修复了超时时间显示位置（子代理行）和 git diff 解析（string 拆分替代正则），但循环次数计数问题（C1）和 sub-step 数据重置问题（C2）仍需要进一步修复。