@ghyper9023/pi-dev-workflow 0.4.2 → 0.5.0

package/.pi-dev-output/pi-plans/20260520-153000-fix-workflow-engine-bugs.md

@@ -1,150 +0,0 @@
-# 修复 workflow-engine 中两个 Bug — 实施计划
-
-## 概述
-
-修复 `extensions/workflow-engine.ts` 中的两个 Bug：
-
-1. **Bug A — executeLoopGroup 缺少 exitCode 检查**（第 1179 行）：`executeLoopGroup` 函数在调用 `runAgentWithProgress` 后，只处理了超时（`isTimeoutResult`），但没有检查 sub-agent 非正常退出（exitCode !== 0 且 exitCode !== -1）的情况。对比 `executeSingleStep` 在第 1146 行有显式的 exitCode 检查。这会导致 agent 崩溃或报错时，工作流继续运行 reviewer，产生错误的结果。
-
-2. **Bug B — setTimeout cleanupWidget 竞态条件**（第 1436 行和第 1648 行）：工作流完成或取消后，使用 `setTimeout(() => cleanupWidget(), 5000)` 延迟 5 秒清理 widget。如果用户在这 5 秒内启动新工作流，定时器触发时会调用 `cleanupWidget`，将 `_workflowRunning` 设为 `false` 并清空 `_lastWorkflowCtx`，破坏正在运行的新工作流。
-
-## 根因分析
-
-**Bug A 根因**：`executeLoopGroup` 在 2025 年 3 月的迭代中从 `executeSingleStep` 分支出来，当时只实现了超时处理逻辑（`isTimeoutResult`），但遗漏了通用的 exitCode 非零检查。`executeSingleStep` 在第 1146 行有 `if (result.exitCode !== 0 && result.stderr) { throw new Error(...); }`，但 `executeLoopGroup` 中没有对应逻辑。
-
-**Bug B 根因**：使用延迟 `setTimeout` 进行异步清理是一种脆弱的模式。它假设在定时器超时前不会有新的工作流启动，但用户可能在完成消息查看后立即开始新的工作流。`cleanupWidget` 会无条件重置 `_workflowRunning` 和 `_lastWorkflowCtx` 等全局状态，没有任何保护机制。
-
-## 文件清单
-
-### 修改文件
-| 文件路径 | 改动描述 | 风险等级 |
-|---------|---------|---------|
-| `extensions/workflow-engine.ts` | 修复 Bug A（添加 exitCode 检查）和 Bug B（定时器竞态保护） | 低 |
-
-### 新增文件
-| 文件路径 | 用途说明 |
-|---------|---------|
-| `tests/test-workflow-engine-bugs.mjs` | 复现并验证 Bug A 和 Bug B 的修复 |
-
-## 实施步骤
-
-### 步骤 1：修复 executeLoopGroup 缺少 exitCode 检查（Bug A）
-
-- **前置条件**：无
-- **改动文件**：`extensions/workflow-engine.ts`
-- **改动位置**：第 1179 行 `let agentResult = await runAgentWithProgress(...)` 之后
-- **改动内容**：在 `isTimeoutResult(agentResult)` 判断之前，插入 exitCode 检查。如果 `agentResult.exitCode !== 0` 且 `agentResult.exitCode !== -1`（-1 是超时标记），则根据 mode 分支处理：
-  - **full-auto 模式**：直接 `throw new Error(...)`，由上层 `executeWorkflowBackground` 的 catch 块捕获，将步骤标记为 failed。
-  - **非 full-auto 模式**：弹出 UI 选择，让用户选择"重新执行"、"跳过此步骤"或"取消工作流"（与超时处理的分支逻辑一致）。
-  
-  具体代码片段（在 `isTimeoutResult` 检查之前插入）：
-
-  ```typescript
-  // 检查 agent 是否异常退出（非超时非零退出码）
-  if (result.exitCode !== 0 && !isTimeoutResult(result)) {
-    if (mode === "full-auto") {
-      throw new Error(`Agent ${step.loopAgentName} 异常退出 (exit ${result.exitCode}): ${result.stderr.slice(0, 200)}`);
-    } else {
-      const choice = await uiSelect(ctx, `❌ ${step.loopAgentName} 异常退出 (exit ${result.exitCode})`, [
-        "1. 重新执行", "2. 跳过此步骤", "3. 取消工作流",
-      ]);
-      if (!choice || choice.startsWith("3")) { cancelWorkflow(); return; }
-      if (choice.startsWith("2")) { state.status = "skipped"; return; }
-      // 重新执行
-      result = await runAgentWithProgress(loopAgent, `[RETRY]\n\n${loopTask}`, stepIndex, step.loopAgentName!, step.timeoutMs);
-    }
-  }
-  ```
-
-- **验证方式**：运行 `node tests/test-workflow-engine-bugs.mjs` 确认测试通过
-
-### 步骤 2：修复 setTimeout cleanupWidget 竞态条件（Bug B）
-
-- **前置条件**：步骤 1 完成
-- **改动文件**：`extensions/workflow-engine.ts`
-- **改动位置**：
-  1. 第 1436 行：`executeWorkflowBackground` 函数末尾的 `setTimeout(() => cleanupWidget(), 5000);`
-  2. 第 1648 行：`cancelWorkflow` 回调中的 `setTimeout(() => cleanupWidget(), 5000);`
-- **改动内容**：引入一个模块级别的定时器 ID 变量 `_cleanupTimer: ReturnType<typeof setTimeout> | null`，并在以下两个位置修改：
-  
-  1. 声明新变量（在全局变量区域，约第 606 行附近）：
-     ```typescript
-     let _cleanupTimer: ReturnType<typeof setTimeout> | null = null;
-     ```
-  
-  2. 修改第 1436 行的 `setTimeout`：
-     ```typescript
-     // 清除之前的定时器
-     if (_cleanupTimer) clearTimeout(_cleanupTimer);
-     _cleanupTimer = setTimeout(() => {
-       _cleanupTimer = null;
-       cleanupWidget();
-     }, 5000);
-     ```
-  
-  3. 修改第 1648 行的 `setTimeout`：
-     ```typescript
-     if (_cleanupTimer) clearTimeout(_cleanupTimer);
-     _cleanupTimer = setTimeout(() => {
-       _cleanupTimer = null;
-       cleanupWidget();
-     }, 5000);
-     ```
-  
-  4. 在 `initWidget` 函数中（约第 639 行）添加清除逻辑，确保新工作流启动时取消旧定时器：
-     ```typescript
-     if (_cleanupTimer) {
-       clearTimeout(_cleanupTimer);
-       _cleanupTimer = null;
-     }
-     ```
-
-  5. 在 `cleanupWidget` 函数中（约第 790 行）添加清除逻辑：
-     ```typescript
-     if (_cleanupTimer) {
-       clearTimeout(_cleanupTimer);
-       _cleanupTimer = null;
-     }
-     ```
-
-- **验证方式**：运行 `node tests/test-workflow-engine-bugs.mjs` 确认测试通过
-
-### 步骤 3：编写测试用例
-
-- **前置条件**：步骤 1 和步骤 2 完成
-- **新增文件**：`tests/test-workflow-engine-bugs.mjs`
-- **测试内容**：
-
-  **Bug A 测试**：
-  - **测试 1**：模拟 `SubagentResult` 对象，验证 `executeLoopGroup` 在收到 `exitCode: 1` 且 `stderr: "some error"` 时的行为
-    - 构造 `{ exitCode: 1, stderr: "Agent crashed: OOM", output: "" }`
-    - 验证 `isTimeoutResult` 返回 `false`
-    - 验证自定义的 simulate 函数能正确识别非零退出码
-  - **测试 2**：验证 `executeSingleStep` 已有 exitCode 检查（确认现有行为不被破坏）
-  - **测试 3**：验证 `isTimeoutResult` 对 `{ exitCode: -1, stderr: "timed out" }` 返回 `true`（确认超时仍被正确识别）
-
-  **Bug B 测试**：
-  - **测试 4**：模拟定时器竞态场景
-    - 验证 `initWidget` 被调用时能清除旧的 `_cleanupTimer`
-    - 验证 `cleanupWidget` 被调用时能清除 `_cleanupTimer`
-    - 验证新工作流启动后，旧定时器不会触发
-
-- **验证方式**：运行 `node tests/test-workflow-engine-bugs.mjs`
-
-## 依赖关系
-
-- 步骤 1 和步骤 2 相互独立，可并行实施
-- 步骤 3 依赖步骤 1 和步骤 2 完成
-
-## 测试策略
-
-- **Bug A 单元测试**：通过模拟 `SubagentResult` 对象和 `isTimeoutResult` 函数，验证非零退出码被正确识别和处理
-- **Bug B 单元测试**：通过模拟定时器 ID 管理和 `initWidget` 的清理行为，验证竞态条件被消除
-- **回归测试**：运行现有测试 `node tests/test-workflow-engine.mjs` 确认无破坏
-
-## 注意事项
-
-1. **最小化改动**：只插入必要的新逻辑，不重构现有代码结构
-2. **与 executeSingleStep 保持一致**：Bug A 的修复逻辑应与 `executeSingleStep` 第 1146 行的 exitCode 检查保持一致
-3. **定时器清除顺序**：在 `initWidget` 中清除旧定时器必须在设置 `_workflowRunning = true` **之前**完成，确保不会在旧定时器触发和新定时器设置之间出现窗口期
-4. **手动确认**：部署后需手动测试快速连续启动两个工作流的场景

package/.pi-dev-output/pi-plans/20260521-113000-fix-loopcount-timeout.md

@@ -1,215 +0,0 @@
-# 修复 Workflow loopCount UI 不同步 & 超时时间分离 — 实施计划
-
-## 概述
-
-修复 workflow-engine.ts 中三个相互关联的 Bug：
-
-1. **loopCount UI 不同步**：`executeLoopGroup()` 在 while 循环中每次迭代后 `loopCount++`，但未调用 `updateWidgetStep()` 更新 widget 状态，导致 widget 中的 `loopStr` 在第 2、3、4 次循环时仍显示"第 1 次循环"。
-2. **reviewer 与 loopAgent 共用超时**：`executeLoopGroup()` 中 reviewer 调用 `runAgentWithProgress()` 时传的是 `step.timeoutMs`，未使用独立超时时间。
-3. **默认超时值不准确**：worker 应为 30min、trimmer 应为 20min、reviewer 应为 15min。
-
-## 根因分析
-
-### Bug 1: loopCount UI 不同步
-- `executeLoopGroup()` (workflow-engine.ts L1197-1270) 中，`loopCount++` (L1243) 之后没有任何 `updateWidgetStep()` 调用。
-- 外层的 `executeWorkflowBackground()` 只在步骤完成时（done/failed）调用 `updateWidgetStep()` 更新 `loopCount`，因此中间迭代的 loopCount 从未通知 widget。
-- Widget 端 `buildWidgetLines()` (ui-helpers.ts L460-470) 中，`loopStr` 显示逻辑依赖于 `s.loopCount`，且当 `isRunning && s.loopCount == null` 时硬编码显示"第 1 次循环"——这进一步掩盖了问题。
-
-### Bug 2: reviewer 超时未分离
-- `WorkflowStepDef` 接口没有 `reviewTimeoutMs` 字段。
-- `executeLoopGroup()` L1224 行：`runAgentWithProgress(reviewAgent, reviewTask, stepIndex, step.reviewAgentName!, step.timeoutMs)` — reviewer 和 loopAgent 使用同一个 `step.timeoutMs`。
-
-### Bug 3: 默认超时值不正确
-- `dev-prompts.ts` 中所有 `worker` 相关的 loop-group 的 `timeoutMs` 都是 `900_000` (15min)，应为 `1_800_000` (30min)。
-- `trimmer` 相关的 loop-group 的 `timeoutMs` 是 `300_000` (5min)，应为 `1_200_000` (20min)。
-- reviewer 的独立超时（通过 `reviewTimeoutMs`）应为 `900_000` (15min)。
-
-## 文件清单
-
-### 修改文件
-| 文件路径 | 改动描述 | 风险等级 |
-|---------|---------|---------|
-| `extensions/workflow-engine.ts` | 1) 给 `WorkflowStepDef` 增加 `reviewTimeoutMs` 字段；2) `executeLoopGroup()` 中 loopCount++ 后调用 `updateWidgetStep()`；3) reviewer 调用 `runAgentWithProgress()` 使用 `reviewTimeoutMs`；4) loop-group 行不显示 timeout | 中 |
-| `extensions/dev-prompts.ts` | 1) 修改所有 loop-group 的 `timeoutMs` 默认值；2) 为所有 loop-group 添加 `reviewTimeoutMs` 字段 | 低 |
-| `extensions/ui-helpers.ts` | 1) `buildWidgetLines()` 中 loop-group 行不显示超时时间；2) sub-step 级别显示各自的超时时间 | 低 |
-
-### 新增文件
-| 文件路径 | 用途说明 |
-|---------|---------|
-| `tests/test-loopcount-timeout-fix.mjs` | 测试 loopCount 同步、reviewer 独立超时、默认值修改 |
-
-## 实施步骤
-
-### 步骤 1：修改 `WorkflowStepDef` 接口，增加 `reviewTimeoutMs` 字段
-- **前置条件**：无
-- **改动文件**：`extensions/workflow-engine.ts`
-- **改动内容**：在 `WorkflowStepDef` 接口中增加可选字段 `reviewTimeoutMs?: number;`（第 49-58 行）
-- **验证方式**：TypeScript 编译不报错
-
-### 步骤 2：修改 `dev-prompts.ts` 中所有 loop-group 的默认超时值
-- **前置条件**：步骤 1 完成
-- **改动文件**：`extensions/dev-prompts.ts`
-- **改动内容**：
-
-  1. **FEAT_WORKFLOW_STEPS** (第 369-401 行)
-     - `worker-reviewer` 的 `timeoutMs`: `900_000` → `1_800_000`，新增 `reviewTimeoutMs: 900_000`
-     - `trimmer-reviewer` 的 `timeoutMs`: `300_000` → `1_200_000`，新增 `reviewTimeoutMs: 900_000`
-
-  2. **FIX_WORKFLOW_STEPS** (第 404-428 行)
-     - `worker-reviewer` 的 `timeoutMs`: `900_000` → `1_800_000`，新增 `reviewTimeoutMs: 900_000`
-
-  3. **REFACTOR_WORKFLOW_STEPS** (第 430-456 行)
-     - `worker-reviewer` 的 `timeoutMs`: `900_000` → `1_800_000`，新增 `reviewTimeoutMs: 900_000`
-     - `trimmer-reviewer` 的 `timeoutMs`: `300_000` → `1_200_000`，新增 `reviewTimeoutMs: 900_000`
-
-  4. **PERF_WORKFLOW_STEPS** (第 458-475 行)
-     - `worker-reviewer` 的 `timeoutMs`: `900_000` → `1_800_000`，新增 `reviewTimeoutMs: 900_000`
-
-  5. **TEST_WORKFLOW_STEPS** (第 477-494 行)
-     - `worker-reviewer` 的 `timeoutMs`: `900_000` → `1_800_000`，新增 `reviewTimeoutMs: 900_000`
-
-  6. **STYLE_WORKFLOW_STEPS** (第 513-523 行)
-     - `trimmer-reviewer` 的 `timeoutMs`: `300_000` → `1_200_000`，新增 `reviewTimeoutMs: 900_000`
-
-- **验证方式**：检查所有 loop-group 配置都有对应的 `reviewTimeoutMs`，超时值符合需求
-
-### 步骤 3：修改 `executeLoopGroup()` 中 reviewer 使用独立超时 + 每次循环后更新 UI
-- **前置条件**：步骤 1、2 完成
-- **改动文件**：`extensions/workflow-engine.ts`
-- **改动内容**（在 `executeLoopGroup` 函数内，约第 1197-1270 行）：
-
-  1. **取出 reviewTimeoutMs**：在 while 循环之前，定义 `const reviewTimeoutMs = step.reviewTimeoutMs ?? step.timeoutMs;`
-
-  2. **修改 reviewer 的超时传递**：将 `runAgentWithProgress(reviewAgent, reviewTask, stepIndex, step.reviewAgentName!, step.timeoutMs)` 改为 `runAgentWithProgress(reviewAgent, reviewTask, stepIndex, step.reviewAgentName!, reviewTimeoutMs)`
-
-  3. **loopCount++ 后立即更新 UI**：在 `loopCount++;`（第 1243 行）之后，添加：
-     ```typescript
-     // 立即更新 UI 显示当前循环次数
-     state.loopCount = loopCount;
-     updateWidgetStep(stepIndex, step.label, "running", {
-         loopCount,
-         maxLoops: step.maxLoops,
-         timeoutMs: step.timeoutMs,
-         startedAt: step.startTime || Date.now(),
-     });
-     ```
-     注意：`step.startTime` 需要从外部传入或在函数内维护。`executeLoopGroup` 当前没有 `startTime` 参数。需要在 `executeWorkflowBackground` 中（第 1405 行）调用 `updateWidgetStep` 时已传入了 `startedAt`。方案是在 `executeLoopGroup` 中也接收 `startedAt` 或让 loop-group 步骤的 `startedAt` 能通过 `_widgetSteps[stepIndex]` 访问。
-
-     更优的方案：在 `executeLoopGroup` 中直接通过 `_widgetSteps[stepIndex]` 读取 `startedAt`。但模块变量 `_widgetSteps` 是 `workflow-engine.ts` 的私有变量，直接在 `executeLoopGroup` 中引用是合理的（已在同一模块中）。
-
-  4. **还原子步骤的 pending 状态**：在每次循环重新开始前，将 worker/reviewer 的 sub-step 状态重置为 "pending"，以便 UI 显示新的迭代。
-     ```typescript
-     // 每次循环开始时重置 sub-step 状态
-     setWidgetSubStepStatus(stepIndex, step.loopAgentName!, "pending");
-     setWidgetSubStepStatus(stepIndex, step.reviewAgentName!, "pending");
-     ```
-
-- **验证方式**：运行测试，检查 widget 状态在每次循环后是否正确更新
-
-### 步骤 4：修改 `ui-helpers.ts` 中 loop-group 行的超时显示
-- **前置条件**：无
-- **改动文件**：`extensions/ui-helpers.ts`
-- **改动内容**（在 `buildWidgetLines` 函数中，约第 455-456 行）：
-
-  1. **loop-group 行不显示超时时间**：修改超时显示逻辑，当步骤是 loop-group 类型时跳过 timeout 显示。但由于 `buildWidgetLines` 不直接知道步骤类型，且 `WorkflowStepWidgetState` 中没有 `type` 字段，有两种方案：
-     - **方案 A（推荐）**：在 `updateWidgetStep` 调用 loop-group 的 running/done 状态时，不传入 `timeoutMs`（设为 `undefined`），这样 `buildWidgetLines` 中 `s.timeoutMs` 为 `undefined`，`timeout` 字符串为空。
-     - **方案 B**：在 `WorkflowStepWidgetState` 中增加 `type` 字段，但需要修改多个地方。
-
-     采用方案 A：`executeLoopGroup` 的 `updateWidgetStep` 调用中不传 `timeoutMs`，而在 worker/reviewer 的 sub-step 级别显示各自的超时。
-
-  2. **sub-step 级别显示超时**：在 sub-step 的 label 行（如 "worker ·" / "reviewer ·"）后面附加超时时间。sub-step 的 `detail` 字段可用于此目的。在 `runAgentWithProgress` 中设置 sub-step 的 `detail` 或通过 `setWidgetSubStepStatus` 扩展接口。
-
-     具体做法：在 `runAgentWithProgress` 初始化 sub-step 时，将超时信息写入 `detail` 字段，例如 `worker · 超时时间30m`。
-
-- **验证方式**：视觉检查 widget 输出，确认 loop-group 行不再显示超时，sub-step 行显示正确
-
-### 步骤 5：修改 `executeWorkflowBackground` 中 loop-group 步骤的 `updateWidgetStep` 调用
-- **前置条件**：步骤 4 完成
-- **改动文件**：`extensions/workflow-engine.ts`
-- **改动内容**：
-
-  在第 1405 行，当步骤类型为 `loop-group` 时，不传入 `timeoutMs`：
-  ```typescript
-  updateWidgetStep(currentStepIndex, step.label, "running", {
-      maxLoops: step.maxLoops,
-      startedAt: stepStartTime,
-      // loop-group 行不显示 timeoutMs，由子代理 sub-step 显示
-  });
-  ```
-
-  在 done 状态更新时（第 1418 行），也不传 `timeoutMs`。
-
-- **验证方式**：在 widget 中确认 loop-group 行没有超时显示
-
-### 步骤 6：更新 `runAgentWithProgress` 在 sub-step 中显示超时
-- **前置条件**：步骤 4 完成
-- **改动文件**：`extensions/workflow-engine.ts`
-- **改动内容**：
-
-  修改 `runAgentWithProgress` 函数中初始化 sub-step 的代码（约第 739-758 行），在 sub-step 的 `detail` 字段中写入超时时间。
-
-  由于 `runAgentWithProgress` 没有直接接收超时参数用于 UI 显示，可以在 sub-step 初始化时添加：
-  ```typescript
-  if (!existing) {
-      step.subSteps.push({
-          agent: agentName,
-          status: "running",
-          tools: [],
-          outputs: [],
-          startedAt: agentStartTime,
-          detail: `超时时间${formatTimeout(timeoutMs)}`,
-      });
-      refreshWidget();
-  }
-  ```
-
-  注意需要 import `formatTimeout` 到 workflow-engine.ts，或将其从 ui-helpers.ts 导出。
-
-- **验证方式**：widget 中 sub-step 行应显示各自的超时时间
-
-### 步骤 7：导出 `formatTimeout` 供 workflow-engine.ts 使用
-- **前置条件**：步骤 6 中的设计决策
-- **改动文件**：`extensions/ui-helpers.ts`
-- **改动内容**：
-
-  将 `formatTimeout` 函数前面加上 `export`（约第 427 行），使其可被其他模块导入使用。
-
-- **验证方式**：TypeScript 编译通过
-
-### 步骤 8：编写测试文件 `test-loopcount-timeout-fix.mjs`
-- **前置条件**：所有代码修改完成
-- **改动文件**：`tests/test-loopcount-timeout-fix.mjs`（新增）
-- **改动内容**：编写测试覆盖以下场景：
-  1. **loopCount 更新测试**：模拟 `executeLoopGroup` 的 while 循环，验证每次 `loopCount++` 后 `updateWidgetStep` 被调用，且传入正确的 `loopCount` 值
-  2. **reviewer 独立超时测试**：验证 reviewer 调用 `runAgentWithProgress` 时使用 `reviewTimeoutMs` 而非 `step.timeoutMs`
-  3. **默认超时值测试**：静态分析 `dev-prompts.ts` 中所有 loop-group 配置，验证超时值是否符合需求（worker=30min, trimmer=20min, reviewer=15min）
-  4. **loop-group 行不显示 timeout 测试**：验证 `updateWidgetStep` 对 loop-group 步骤不传 `timeoutMs`
-  5. **sub-step 显示 timeout 测试**：验证 `runAgentWithProgress` 在新 sub-step 的 `detail` 中写入超时信息
-  6. **回归测试**：确保原有功能（非 loop-group 步骤的超时显示、完成状态等）不受影响
-- **验证方式**：运行 `node tests/test-loopcount-timeout-fix.mjs`
-
-## 依赖关系
-
-- 步骤 1 是步骤 2、3 的前置条件（接口先定义才能使用）
-- 步骤 2 是步骤 3 的前置条件（配置中的 `reviewTimeoutMs` 值在步骤 3 中使用）
-- 步骤 4、5、6、7 可并行进行设计，但应顺序实施（步骤 4 → 步骤 7 → 步骤 6 → 步骤 5）
-- 步骤 8 在所有代码修改完成后进行
-
-## 测试策略
-
-- **单元测试**：通过静态分析源代码模拟函数行为，验证 loopCount 更新逻辑、超时分离逻辑
-- **集成测试**：模拟完整的 `executeLoopGroup` 执行流程，检查 widget state 的每个字段
-- **回归测试**：运行已有的 `test-workflow-engine.mjs` 和 `test-workflow-engine-bugs.mjs`，确保无破坏
-- **手动测试**：在 TUI 中运行 `/dev-fix` 命令，观察 widget 中 loop-count 和超时显示是否正确
-
-## 注意事项
-
-1. **loopCount 初始值**：`executeLoopGroup` 中 `loopCount` 从 `loopCounts[step.id] ?? 0` 开始（第 1199 行）。这意味着第一次循环时 `loopCount` 为 0，在 `loopCount++` 后变为 1。UI 中第一次显示应该是"第 1 次循环"，与现有 `buildWidgetLines` 中的硬编码一致。
-
-2. **`_widgetSteps` 的访问**：`executeLoopGroup` 中需要读取 `_widgetSteps[stepIndex]` 来获取 `startedAt`。由于 `_widgetSteps` 是模块级变量，直接在函数中引用即可。
-
-3. **sub-step 的重置**：每次循环开始时，需要将 worker 和 reviewer 的 sub-step 状态重置为 "pending"，否则 UI 会显示上次循环的已完成状态。这通过 `setWidgetSubStepStatus` 实现。
-
-4. **超时 UI 显示**：根据设计评审第 8 问的决策，loop-group 行不显示超时时间，超时只显示在 sub-step 级别。worker sub-step 显示"超时时间30m"，reviewer sub-step 显示"超时时间15m"。
-
-5. **`WORKFLOW_SUB_STEP_WIDGET_STATE.detail`**：利用现有的 `detail` 字段来显示 sub-step 的超时信息，无需添加新字段。

package/.pi-dev-output/pi-plans/20260521-1730-grill-input-wrap-back-fix.md

@@ -1,240 +0,0 @@
-# Grill/Input 文本换行与左方向键返回修复 — 实施计划
-
-## 概述
-
-修复 extensions/ 目录中 grill 和 dev-* 命令的三个 UI 问题：
-1. dev-* 命令输入栏和 grill 自定义输入框不会自动换行（单行水平滚动），超长文本被截断
-2. grill 提问回答环节的选项（a/b/c...）文字过长时不换行，内容被截断
-3. grill 提问回答环节的 ← 左方向键返回上一题功能未实现
-
-## 根因分析
-
-### 问题 1：输入不换行
-`ui-helpers.ts` 中的 `uiInput` 函数使用 pi-tui 的 `Input` 组件。该组件是**单行文本输入**，支持水平滚动但不支持换行：`render()` 只输出一行文本，`handlePaste()` 会移除所有换行符。无法通过配置启用多行模式。
-
-### 问题 2：选项不换行
-`grill-me-agent.ts` 中的 `showQuestionTUI` 使用 pi-tui 的 `SelectList` 组件显示选项（a/b/c...）。`SelectList.renderItem()` 使用 `truncateToWidth()` 将过长的 label **截断**而非**换行**。SelectList 不支持多行 item 渲染。
-
-### 问题 3：左方向键不生效
-`showQuestionTUI` 的 `handleInput` 将键盘事件直接转发给 `selectList.handleInput(data)`。
-SelectList 只处理 `tui.select.up/down/confirm/cancel`（分别绑定了 ↑↓ Enter Esc），**不处理 `left` 键**（left 绑定的是 `tui.editor.cursorLeft`）。因此左方向键事件被静默丢弃。
-
-## 文件清单
-
-### 修改文件
-| 文件路径 | 改动描述 | 风险等级 |
-|---------|---------|---------|
-| `extensions/grill-me-agent.ts` | 1. 在 `showQuestionTUI.handleInput` 中拦截左方向键实现返回 2. 对过长选项使用 `description` 字段显示完整文本 3. 新增 import | 低 |
-| `extensions/ui-helpers.ts` | 1. `uiInput` 中添加实时换行预览区域 2. `uiInput.handleInput` 中拦截左方向键返回 | 低 |
-
-**不修改**：`@earendil-works/pi-tui` 库（SelectList、Input 组件保持不变）。
-
-## 实施步骤
-
-### 步骤 1：修复 `grill-me-agent.ts` — 左方向键返回 + 选项过长处理
-
-- **改动文件**：`extensions/grill-me-agent.ts`
-- **改动内容**：
-
-  **a) 新增 import（文件头部，约第 13~15 行）**
-  添加：
-  ```typescript
-  import { matchesKey, Key, truncateToWidth } from "@earendil-works/pi-tui";
-  ```
-  
-  **b) `showQuestionTUI` 中拦截左方向键（约第 670 行的 `handleInput`）**
-  当前代码仅做 `selectList.handleInput(data)`。左方向键传入 SelectList 后无效果。
-  
-  修改为：先检查左方向键，若匹配则直接 `done("__BACK__")`，**不转发给 SelectList**：
-  ```typescript
-  return {
-      render: (w) => container.render(w),
-      invalidate: () => container.invalidate(),
-      handleInput: (data) => {
-          // 左方向键 → 返回上一题（SelectList 不处理 left 键，需自行拦截）
-          if (backable && currentIndex > 1 && matchesKey(data, Key.left)) {
-              done("__BACK__");
-              return;
-          }
-          selectList.handleInput(data);
-          tui.requestRender();
-      },
-  };
-  ```
-
-  **c) 选项文字过长处理（约第 640 行构建 `selectItems` 处）**
-  SelectList 的 `renderItem` 对主列使用 `truncateToWidth` 截断。当选项文本超过主列宽度时，内容不可见。
-  
-  修改方案：将完整 label **截断到合理长度**，将完整文本放入 `description` 字段。SelectList 在有 description 时会使用两列布局（主列 + description 列），让用户尽可能看到更多内容：
-  ```typescript
-  const MAX_OPTION_LABEL = 50;
-  const selectItems: SelectItem[] = q.options.map((opt, i) => {
-      const prefix = `(${String.fromCharCode(97 + i)}) `;
-      const label = opt === previousAnswer
-          ? `${prefix}${opt} - 上次选择`
-          : `${prefix}${opt}`;
-      const truncated = truncateToWidth(label, MAX_OPTION_LABEL, "...");
-      return {
-          value: `opt-${i}`,
-          label: truncated,
-          // 只有被截断时才提供 description，展示完整文本
-          description: truncated !== label ? opt : undefined,
-      };
-  });
-  ```
-
-  **注意**：`truncateToWidth` 已经是 `@earendil-works/pi-tui` 的导出，可直接 import。
-
-- **验证方式**：
-  - 运行 `/dev-fix` → 进入 grill → 在第一个问题上按 ← 键（此时 backable=false，currentIndex=1），不应触发返回
-  - 进入第二个问题，按 ← 键，确认返回第一个问题
-  - 确认选择了第一个问题的答案后，返回第一个问题，应看到" - 上次选择"标记
-  - 对包含长选项文字的问题，确认 label 被截断但 description 列显示完整文本
-
-### 步骤 2：修复 `ui-helpers.ts` — 输入框实时换行预览
-
-- **改动文件**：`extensions/ui-helpers.ts`
-- **改动内容**：
-
-  在 `uiInput` 函数的返回对象中（约第 230~245 行），当前的 `handleInput` 仅转发给 `input.handleInput(data)`。修改为：在转发后读取 `input.getValue()`，用 `wrapTextWithAnsi` 换行后更新一个预览 Text 组件。
-
-  完整修改如下（仅修改 `uiInput` 函数的返回部分）：
-
-  ```typescript
-  // 在 Input 上方添加预览 Text（约第 215 行，在 input 创建前）
-  const previewText = new Text("", 0, 0);
-  container.addChild(previewText);
-  container.addChild(new Spacer(1));
-  // ... 创建 input ...
-
-  // 修改 return 对象中的 handleInput（约第 230 行）
-  return {
-      render: (w) => container.render(w),
-      invalidate: () => container.invalidate(),
-      handleInput: (data) => {
-          // 先让 Input 处理输入（更新内部 value）
-          input.handleInput(data);
-          
-          // 读取更新后的 value，更新预览
-          const val = input.getValue();
-          if (val.length > 0) {
-              const wrapped = wrapTextWithAnsi(val, width - 4);
-              const previewContent = wrapped
-                  .map(l => theme.fg("dim", `  ${l}`))
-                  .join("\n");
-              previewText.setText(previewContent);
-          } else {
-              previewText.setText("");
-          }
-          
-          tui.requestRender();
-      },
-  };
-  ```
-
-  **注意**：
-  - `previewText` 的初始状态应为空文本（`""`）
-  - 每次按键后，`input.handleInput(data)` 会修改 Input 的内部 value，然后我们立即读取并更新预览
-  - 使用 `theme.fg("dim", ...)` 使预览文本颜色较淡，与输入框区分
-  - `wrapTextWithAnsi` 已经 import
-
-- **验证方式**：
-  - 运行 `/dev-feat` → 在"核心功能描述"输入框输入超过终端宽度的长文本 → 确认上方出现换行预览
-  - 按 Backspace 删除字符 → 确认预览实时更新
-  - 按 Esc 取消 → 确认预览消失、输入被取消
-  - 按 Enter 提交 → 确认正常提交
-
-### 步骤 3：修复 `ui-helpers.ts` — 左方向键返回（自定义输入环节）
-
-- **改动文件**：`extensions/ui-helpers.ts`
-- **改动内容**：
-
-  在 `uiInput` 的 `handleInput` 中，**在调用 `input.handleInput(data)` 之前**拦截左方向键。当 `backable=true` 且按下左方向键时，返回 `BACK_MARKER`。
-
-  现有代码中已经支持 `Ctrl+Shift+←` 作为返回键（约第 240~244 行）。现在增加裸的 ← 键支持：
-
-  ```typescript
-  handleInput: (data) => {
-      // [新增] 左方向键 → 返回（优先于 Input 的光标左移）
-      if (backable && matchesKey(data, Key.left)) {
-          done(BACK_MARKER);
-          return;
-      }
-      
-      // [原有] Ctrl+Shift+← → 返回
-      if (backable && matchesKey(data, Key.ctrlShift("left"))) {
-          done(BACK_MARKER);
-          return;
-      }
-      // [原有] Ctrl+Shift+→ → 提交并继续
-      if (backable && matchesKey(data, Key.ctrlShift("right"))) {
-          done(input.getValue() || "");
-          return;
-      }
-      
-      // [原有] 转发给 Input 处理
-      input.handleInput(data);
-      
-      // [新增] 更新预览（步骤 2）
-      const val = input.getValue();
-      if (val.length > 0) {
-          const wrapped = wrapTextWithAnsi(val, width - 4);
-          previewText.setText(
-              wrapped.map(l => theme.fg("dim", `  ${l}`)).join("\n")
-          );
-      } else {
-          previewText.setText("");
-      }
-      
-      tui.requestRender();
-  },
-  ```
-
-  **关于光标左移的替代方案**：拦截左方向键后，Input 组件中失去光标左移能力。但 pi-tui 的 keybinding 中 `tui.editor.cursorLeft` 同时绑定了 `left` 和 `ctrl+b`（见 keybindings.d.ts），用户可以使用 `Ctrl+B` 替代左方向键进行光标左移。这是合理的权衡。
-
-- **验证方式**：
-  - 进入 grill → 选择"自定义输入" → 按 ← 键 → 确认返回到选项列表
-  - 在非 grill 场景的普通输入（如 `/dev-feat` 的第一题）中按 ← 键 → 确认整个 wizard 被取消（因为 backable=true 但当前是第一题，返回即取消）
-  - 确认 Ctrl+B 在输入框中仍可左移光标
-
-### 步骤 4：更新 hints 文案（可选）
-
-- **改动文件**：`extensions/grill-me-agent.ts`（约第 663~667 行）
-- **改动内容**：
-
-  更新 hint 文本，说明左方向键也可用于返回：
-
-  ```typescript
-  const hint = backable && currentIndex > 1
-      ? "  ↑↓ 导航 • Enter 选择 • ← 返回上一题 • Esc 取消全部评审"
-      : "  ↑↓ 导航 • Enter 选择 • Esc 取消全部评审";
-  ```
-
-- **验证方式**：检查 grill 问题界面底部提示文字是否正确显示
-
-## 依赖关系
-
-- 步骤 1 与步骤 2、3 无依赖，可并行
-- 步骤 3 依赖步骤 2 的代码修改位置（handleInput 中需同时处理左方向键和预览更新）
-- 步骤 4 可选，在步骤 1 之后
-
-## 测试策略
-
-手动测试清单：
-
-| 测试场景 | 操作 | 预期结果 |
-|---------|------|---------|
-| Grill 左方向键返回 | 在 grill 第二个问题按 ← | 返回第一个问题，保留之前的选择 |
-| Grill 选项显示 | 包含长选项文字的问题 | label 截断有 ...，description 列显示完整文本 |
-| Grill 自定义输入返回 | 选自定义输入后按 ← | 返回到选项列表 |
-| dev-* 长文本预览 | 输入超长文本 | Input 上方显示换行后的完整文本预览 |
-| 普通 Esc 取消 | 按 Esc | 取消当前操作（不破坏原有功能） |
-| 上一步/下一步导航 | 使用 Ctrl+Shift+←/→ | 原有功能不受影响 |
-| 非 backable 左方向键 | 普通输入中按 ← | 光标在输入框中左移 |
-
-## 注意事项
-
-- **不修改 pi-tui 库代码**，所有改动在 `extensions/` 目录内完成
-- **左方向键拦截**：在 SelectList 环境中，left 键对 SelectList 无意义（SelectList 只用 ↑↓ 导航），拦截 100% 安全。在 Input 环境中，左方向键的"光标左移"功能可用 Ctrl+B 替代
-- **预览性能**：每次按键触发 `wrapTextWithAnsi`，对数百字符的输入性能可忽略
-- **description 列**：SelectList 的 description 列本身也被 `truncateToWidth` 截断，但两列布局比单列能显示更多内容