@ghyper9023/pi-dev-workflow 0.4.1 → 0.4.3

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

@@ -0,0 +1,241 @@
+# 代码审查报告
+
+**审查时间**: 2026-05-21 20:45  
+**审查范围**: commit `01413c9` 对 `extensions/ui-helpers.ts` 和 `extensions/workflow-engine.ts` 的修改  
+**功能需求**: 修复超时时间显示位置、循环次数计数、git diff 解析
+
+---
+
+## Critical 问题
+
+### C1. `executeLoopGroup` 中 `loopCount` 更新后调用 `updateWidgetStep` 但 UI 在 sub-step 运行期间仍不显示循环次数
+
+**严重等级**: critical  
+**文件**: `extensions/workflow-engine.ts`（executeLoopGroup） & `extensions/ui-helpers.ts`（buildWidgetLines）  
+**根因分析**:
+
+在 commit `01413c9` 中，`buildWidgetLines` 的 `isRunning` 分支（原本显示"第 1 次循环"）被删除，并改为"由 `executeLoopGroup` 通过 `updateWidgetStep` 管理 loopCount"。
+
+然而 `executeLoopGroup` 的流程是：
+1. `while (loopCount < maxLoops)` — 进入循环，`loopCount=0`
+2. 重置 sub-step 为 pending
+3. 运行 worker agent（耗时较长）
+4. 运行 reviewer agent（耗时较长）
+5. `loopCount++`（变为 1）
+6. `updateWidgetStep(...)` 设置 `loopCount=1`
+
+**问题核心**：在第 3-4 步（worker/reviewer 运行期间），`runAgentWithProgress` 内部会多次调用 `refreshWidget()`（通过 `setWidgetSubStepStatus`、`addWidgetSubStepTool` 等）。但这些 `refreshWidget()` 调用时，widget step 的 `loopCount` 仍为 `undefined`，因为 `updateWidgetStep(loopCount=1)` 还没执行到。
+
+因此在整个 sub-step 运行期间（这是 UI 可见时间最长的阶段），**用户完全看不到任何循环次数提示**。只有等 sub-step 全部完成后才更新 loopCount，但此时 UI 已经准备进入下一轮了。
+
+**影响**: 用户在整个 worker/reviewer 执行过程中完全看不到"第 N 次循环"提示，这是严重的用户体验 bug。
+
+**修复方案**: 在 `executeLoopGroup` 中，**在运行 worker agent 之前**（而不是之后）就更新 loopCount 到 widget。
+
+```typescript
+// 在 while 循环开始处，运行 agent 之前
+loopCount++;
+state.loopCount = loopCount;
+updateWidgetStep(stepIndex, step.label, "running", {
+    loopCount,
+    maxLoops: step.maxLoops,
+    startedAt: _widgetSteps[stepIndex]?.startedAt || Date.now(),
+});
+
+// 然后运行 worker agent
+const loopTask = buildTaskForStep(step.loopAgentName!, contextPrompt, planFileRelPath, _workflowCwd);
+let agentResult = await runAgentWithProgress(loopAgent, loopTask, stepIndex, step.loopAgentName!, step.timeoutMs);
+```
+
+这样在 sub-step 开始运行前，widget 上已经显示正确的 `loopCount`，后续所有 `refreshWidget()` 都能读取到正确的值。
+
+同时应保留 `buildWidgetLines` 中 `isRunning` 状态的 fallback 逻辑（`第 1 次循环`）作为兜底。
+
+### C2. `buildWidgetLines` 中超时时间在步骤行和子代理行显示逻辑冲突
+
+**严重等级**: critical  
+**文件**: `extensions/ui-helpers.ts`（buildWidgetLines）  
+**根因分析**:
+
+当前代码中：
+- **步骤行（step line）**: 对于 loop-group 步骤已移除了 `timeoutMs`（`step.type === "loop-group" ? undefined : step.timeoutMs`），所以步骤行不会显示超时。
+- **子代理行（sub-step line）**: 通过 `sub.detail`（内容如 `超时时间60m`）在 agent 行末尾显示。
+
+但当前子代理行的渲染代码（`buildWidgetLines` 中的 sub-step 渲染部分）**已经实现了** 功能需求要求的显示格式：
+
+```
+|__ ✓ worker · (52.6s/超时时间60m)
+```
+
+代码中已有的逻辑（查看 ~Line 539-545）：
+```typescript
+if (sub.detail && sub.detail.includes("超时时间")) {
+    subTimeoutStr = dim(theme, `/${sub.detail}`);
+}
+```
+
+**问题在于**：当前 `sub.detail` 已在 `runAgentWithProgress` 中设置为 `超时时间${formatTimeout(timeoutMs)}`，所以这部分功能本身是**已实现**的。功能需求中描述的超时显示位置问题可能存在于旧的代码版本，commit `01413c9` 已经修复了这部分。
+
+但在审查过程中确认：**当前代码中 sub-step 的超时时间显示逻辑是正确的**，不应再改动。需要重点关注的是**确保 detail 中的"超时时间"文本不被作为独立的子项重复显示**。
+
+当前代码（~Line 554-556）：
+```typescript
+if (childItems.length === 0 && sub.detail && !sub.detail.includes("超时时间")) {
+    childItems.push(sub.detail);
+}
+```
+
+这个逻辑是正确的：`sub.detail` 包含"超时时间"时不会被作为子项重复显示。
+
+---
+
+## Medium 问题
+
+### M1. `getGitDiffChanges` 中 `git status --porcelain` 解析存在潜在 bug
+
+**严重等级**: medium  
+**文件**: `extensions/workflow-engine.ts`（getGitDiffChanges）  
+**根因分析**:
+
+当前代码已按实施计划中的方案改用了字符串拆分而非正则：
+```typescript
+const parts = trimmed.split("\t");
+if (parts.length === 2) {
+    const status = parts[0]!.trim();
+    const filePath = parts[1]!.trim();
+    ...
+}
+```
+
+但 `git status --porcelain` 的解析仍有问题：
+```typescript
+const statusPrefix = trimmed.slice(0, 2);
+const filePath = trimmed.slice(3).trim();
+```
+
+`git status --porcelain` 的实际输出格式为：
+- `?? newfile.ts` — untracked (2 字符状态 + 空格 + 路径)
+- ` M modified.ts` — working tree 修改 (空格 + M + 空格 + 路径)
+- `A  staged.ts` — staged 添加 (A + 空格 + 空格 + 路径)
+- `M  staged-mod.ts` — staged 修改 (M + 空格 + 空格 + 路径)
+
+前两个字符是 `XY`（index 状态 + working tree 状态），后面跟**一个空格**再跟路径。所以 `trimmed.slice(0, 2)` 取到的是完整的 2 字符状态码，`trimmed.slice(3)` 取到的是路径（跳过了第 3 个字符即空格）。
+
+**但问题在于**：`trimmed` 是通过 `line.trim()` 得到的，**这已经去掉了首尾空格**。对于 ` M modified.ts`（首字符为空格），`trim()` 后变成了 `M modified.ts`，此时 `statusPrefix = "M "`（"M" + 空格），**但原始的 git porcelain 输出中 "M" 前面有一个空格表示 working tree 状态**，trim 后丢失了这个信息。
+
+修复方案：**不要对 line 做 `trim()`**，或者使用 `line` 而非 `trimmed` 来解析状态码。
+
+```typescript
+// 正确的解析方式
+for (const line of statusOutput.split("\n")) {
+    if (!line.trim()) continue;
+    // 前两个字符是状态
+    const statusPrefix = line.slice(0, 2); // 直接使用原始 line，不 trim
+    const filePath = line.slice(3).trim();
+    // "??" 表示 untracked/new
+    // "A " 或 "AM" 或 "M " 表示 tracked 文件被修改
+    if (statusPrefix === "??") {
+        // untracked = new
+        ...
+    } else if (statusPrefix === "A " || statusPrefix.startsWith("A")) {
+        // staged new
+        ...
+    }
+    ...
+}
+```
+
+### M2. `executeLoopGroup` 中异常退出重试逻辑可能导致无限循环
+
+**严重等级**: medium  
+**文件**: `extensions/workflow-engine.ts`（executeLoopGroup）  
+**根因分析**:
+
+在 `executeLoopGroup` 中，当 agent 异常退出（非零退出码且非超时）时：
+
+```typescript
+while (agentResult.exitCode !== 0 && !isTimeoutResult(agentResult)) {
+    if (mode === "full-auto") {
+        throw new Error(...);
+    } else {
+        const choice = await uiSelect(ctx, ..., [
+            "1. 重新执行", "2. 跳过此步骤", "3. 取消工作流",
+        ]);
+        ...
+        agentResult = await runAgentWithProgress(loopAgent, `[RETRY]\n\n${loopTask}`, ...);
+    }
+}
+```
+
+这里使用了 `while` 循环而非 `if`，但每次重试都会创建新的 `agentResult`。如果 agent **持续**异常退出，理论上用户每次都选"重新执行"就会无限循环。不过用户有选择跳过或取消的权力，所以实际风险较低。
+
+建议改为 `do-while` 或加一个最大重试次数限制，但功能需求要求最小改动，可标记为观察项。
+
+---
+
+## Low 问题
+
+### L1. `updateWidgetStep` 中 `startedAt` 回退逻辑可能导致时间错误
+
+**严重等级**: low  
+**文件**: `extensions/workflow-engine.ts`（executeLoopGroup）  
+**根因分析**:
+
+在 `executeLoopGroup` 中的 `updateWidgetStep` 调用：
+```typescript
+updateWidgetStep(stepIndex, step.label, "running", {
+    loopCount,
+    maxLoops: step.maxLoops,
+    startedAt: _widgetSteps[stepIndex]?.startedAt || Date.now(),
+});
+```
+
+如果 `_widgetSteps[stepIndex]?.startedAt` 为 `0`（理论上不可能，但类型上 permit），`||` 会回退到 `Date.now()`，这没问题。但如果 `startedAt` 已经有一个较早的值，每次循环都复用同一个 `startedAt` 会导致累计时间异常——步骤行显示的时间是**工作流开始到当前的总时间**，而不是本轮循环的开始时间。
+
+然而 `loop-group` 步骤的步骤行显示的是从 `stepStartTime` 开始到现在的总运行时长（因为 step 级别只有一个 `startedAt`），而 sub-step 有自己的 `startedAt`。所以这个行为是预期的，不构成 bug。标记为低优先级观察项。
+
+### L2. `buildWidgetLines` 中 `isRunning` 状态检测逻辑冗余
+
+**严重等级**: low  
+**文件**: `extensions/ui-helpers.ts`（buildWidgetLines）  
+**根因分析**:
+
+当前代码：
+```typescript
+const isRunning = s.status === "running" || isCurrent;
+```
+
+`isCurrent` 定义为 `i === state.currentStepIndex && state.status === "running"`。所以 `isRunning` 的检测等价于 `s.status === "running" || (i === currentStepIndex && state.status === "running")`。
+
+实际上，如果 `i === currentStepIndex` 且 `state.status === "running"`，那么 `s.status` 应该已经是 `"running"`（由 `updateWidgetStep` 设置）。所以 `isCurrent` 部分通常是冗余的。
+
+但在初始状态或过渡状态中可能存在短暂的不一致。保留作为容错是可以的，但可考虑简化。
+
+### L3. 测试文件中 `extractLoopGroups` 函数解析逻辑脆弱
+
+**严重等级**: low  
+**文件**: `tests/test-loopcount-timeout-fix.mjs`  
+**根因分析**:
+
+`extractLoopGroups` 函数通过逐行扫描和花括号深度来解析 loop-group 配置块，这种方法很脆弱：
+1. 它假定 `type: "loop-group"` 所在行是配置块的开始
+2. 它通过 `}` 后跟 `,` 或 `;` 来检测结束
+3. 如果配置格式稍有变化（如多行注释、属性换行等），解析就会失败
+
+实际测试运行发现当前能正确解析所有 7 个 loop-group 配置（断言 `>=6`），但未来修改配置格式时需要同步更新测试解析器。
+
+---
+
+## 总结
+
+| 等级 | 数量 | 说明 |
+|------|------|------|
+| Critical | 2 | loopCount 在 sub-step 运行期间不显示（时序问题）；超时显示逻辑需验证 |
+| Medium | 2 | `git status --porcelain` 解析 bug；重试可能无限循环 |
+| Low | 3 | startedAt 回退、运行状态检测冗余、测试解析脆弱 |
+
+## 推荐修复优先级
+
+1. **修复 C1**: 在 `executeLoopGroup` 中，将 `loopCount++` 和 `updateWidgetStep` 移到运行 worker agent 之前
+2. **修复 M1**: 修正 `git status --porcelain` 解析中 `line.trim()` 导致的状态码丢失问题
+3. 其他问题可在后续迭代中优化

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` 中左方向键拦截的逻辑，增加光标位置或输入内容检查。