@ghyper9023/pi-dev-workflow 0.6.3 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @ghyper9023/pi-dev-workflow
 
-> Developer workflow toolkit for [pi coding agent](https://pi.dev/): git agents, code review, Karpathy guidelines, themes, automation workflows
+> Developer workflow toolkit for [pi coding agent](https://pi.dev/): git commands, code review, Karpathy guidelines, themes, prompt wizards
 
 ## 快速安装
 
@@ -13,9 +13,9 @@ pi install git:github.com/cherish-ltt/pi-dev-workflow
 ```
 
 然后 `/reload` 热加载即可使用所有功能。
-> [!NOTE]  
-> - 本pi-package存在sub-agent功能，会与其他使用sub-agent功能的pi-package冲突，但冲突可以修复，请提交issue或自行处理。
-> - 本pi-package添加了`APPEND_SYSTEM.md`，存在默认使用中文等特色设定，需要自行修改`prompts/APPEND_SYSTEM.md`。
+> [!NOTE]
+> - 本 pi-package 已移除子代理，不会与其他 pi-package 的子代理功能冲突。
+> - 本 pi-package 添加了 `APPEND_SYSTEM.md`，存在默认使用中文等特色设定，可自行修改 `prompts/APPEND_SYSTEM.md`。
 
 ## 目录结构
 
@@ -24,23 +24,6 @@ pi-package/
 ├── package.json                     # 包元数据 & pi 配置
 ├── README.md                        # 本文件
 ├── .gitignore
-├── agents/
-│   ├── git-agent.md                 # git-sub-agent 定义（专注 git 操作）
-│   ├── review-agent.md              # review-sub-agent 定义（专注代码审查）
-│   ├── grill/                       # 方案追问完善 (Grill) agent 定义
-│   │   ├── dev-grill-agent.md       #   通用 /dev-feat Grill agent
-│   │   ├── dev-fix-grill-agent.md   #   /dev-fix Bug 根因追问
-│   │   ├── dev-doc-grill-agent.md   #   /dev-doc 文档大纲追问完善
-│   │   ├── dev-refactor-grill-agent.md   #   /dev-refactor 重构追问完善
-│   │   ├── dev-test-grill-agent.md   #   /dev-test 测试追问完善
-│   │   ├── dev-perf-grill-agent.md   #   /dev-perf 优化追问完善
-│   │   └── dev-prd-agent.md         #   PRD 生成 agent
-│   └── workflow/                    # 自动化工作流 agent 定义
-│       ├── planner-agent.md         #   计划制定 agent
-│       ├── worker-agent.md          #   代码实施 agent
-│       ├── reviewer-agent.md        #   代码审查 agent
-│       ├── trimmer-agent.md         #   代码精简 agent
-│       └── docWriter-agent.md       #   文档撰写 agent
 ├── prompts/
 │   ├── APPEND_SYSTEM.md             # 全局追加提示：强制使用简体中文+英文专业名词
 │   ├── review-commit.md             # 审查 commit 的提示模板
@@ -55,70 +38,51 @@ pi-package/
 │   └── to-prd/
 │       └── SKILL.md                 # 从对话上下文生成 PRD 文档
 ├── extensions/
-│   ├── append-system.ts             # 追加APPEND_SYSTEM.md提示词
+│   ├── append-system.ts             # 追加 APPEND_SYSTEM.md 提示词
 │   ├── dev-prompts.ts               # 提示词优化向导（/dev-* 命令）
-│   ├── git-commands.ts              # git-sub-agent 命令
-│   ├── grill-me-agent.ts            # Grill + PRD 运行时：方案追问完善、PRD 生成
-│   ├── sub-agents.ts                # 子代理系统：git-sub-agent + review-sub-agent
-│   ├── workflow-engine.ts           # 工作流编排引擎（由 dev-prompts.ts 引入）
-│   └── ui-helpers.ts                # TUI 组件构建器（Select/Confirm/Input/Widget）
+│   ├── git-commands.ts              # git 命令（直接执行）
+│   ├── grill-me-agent.ts            # Grill + PRD 运行时（运行在当前代理中）
+│   └── ui-helpers.ts                # TUI 组件构建器（Select/Confirm/Input）
 └── themes/
     └── claude-code-theme.json       # Claude Code CLI 风格主题
 ```
 
-## Sub-Agents（子代理）
+## Themes
+
+| Theme | 说明 |
+|---|---|
+| **claude-code-theme** | 仿 Claude Code CLI 配色：深色底 + 琥珀金主色 + 紫罗兰辅色 |
+| **oh-my-pi-titanium** | 钛金属风格主题 |
+
+## 推荐扩展（第三方）
 
-子代理运行在独立的 `pi` 进程中，拥有隔离的上下文窗口，专注处理特定领域任务。
+以下为社区推荐的第三方 Pi 扩展，可按需安装：
 
-| 子代理 | 触发方式 | 职责 |
+| 扩展 | 作用 | 安装 |
 |---|---|---|
-| **git-sub-agent** | `/git-commit [msg]` / `/git-push` / `/git-commit-push [msg]` | Git 全流程操作 |
-| **review-sub-agent** | 自动检测用户提示中的审查意图 | 代码审查、diff 分析 |
+| **pi-web-access** | 网页搜索、URL 抓取、GitHub 仓库克隆、PDF 提取、YouTube 视频理解与本地视频分析，支持多家搜索/内容服务提供商 | `pi install npm:pi-web-access` |
+| **pi-mcp-adapter** | MCP（Model Context Protocol）适配器扩展，让 Pi 接入 MCP 工具生态 | `pi install npm:pi-mcp-adapter` |
+| **rpiv-ask-user-question** | 结构化问卷扩展：模型不确定时以带类型的选项向你提问，替代自由文本回复 | `pi install npm:@juicesharp/rpiv-ask-user-question` |
+| **rpiv-todo** | 模型待办清单：实时悬浮面板展示，`/reload` 与会话压缩后依然保留 | `pi install npm:@juicesharp/rpiv-todo` |
+| **@plannotator/pi-extension** | 交互式方案评审扩展：带注释的方案审查，可标注 Agent 消息，审查代码/PR | `pi install npm:@plannotator/pi-extension` |
 
-### git-sub-agent
+## Git 命令
 
-在隔离进程中执行 git 操作，支持三种子命令：
+三个命令直接通过 pi 的内置执行器运行 git，结果写入当前会话上下文，不需要隔离的子代理进程。
 
 | 命令 | 说明 |
 |---|---|
-| `/git-commit [message]` | 暂存所有变更并提交（空信息让 AI 根据 diff 自动生成 Conventional Commits message） |
+| `/git-commit [message]` | 暂存所有变更并提交（空信息会让 AI 根据 diff 自动生成 Conventional Commits message） |
 | `/git-push` | 推送到远程 |
 | `/git-commit-push [message]` | 暂存 + 提交 + 推送一键完成 |
 
-### review-sub-agent
-
-当用户输入包含 review/审查/审阅 + code/代码/diff/commit/html 等关键词时，自动弹出三种模式选择：
-
-| # | 模式 | 行为 |
-|---|------|------|
-| **1** | 后台审查（非阻塞，异步通知） | 后台运行审查，不阻塞对话，完成后通过消息通知 |
-| **2** | 仅审查（阻塞，等待结果） | 等待审查完成才恢复交互 |
-| **3** / Esc | 不是审查（放行给主代理） | 不启动子代理，原消息交给主 AI 处理 |
-
-也支持 `/skill:review-html` 直接触发阻塞审查。
-审查结果以交互式 HTML 报告形式写入 `.pi-dev-output/pi-review/html/` 目录。
-
-### subagent 工具
-
-LLM 也可以直接调用 `subagent` 工具委派任务给任意子代理：
-
-```
-可用子代理：git-agent, review-agent
-```
-
-## Themes
-
-| Theme | 说明 |
-|---|---|
-| **claude-code-theme** | 仿 Claude Code CLI 配色：深色底 + 琥珀金主色 + 紫罗兰辅色 |
-
 ## Dev Prompts（提示词优化向导）
 
-基于 [ai提示词优化.md](./ai%E6%8F%90%E7%A4%BA%E8%AF%8D%E4%BC%98%E5%8C%96.md) 中的优质模板，通过交互式问答引导你填写 `[xxx]` 占位符，组装完整的高质量提示词后直接投递给主代理执行。
+基于 [ai提示词优化.md](./ai%E6%8F%90%E7%A4%BA%E8%AF%8D%E4%BC%98%E5%8C%96.md) 中的优质模板，通过交互式问答引导你填写 `[xxx]` 占位符，组装完整的高质量提示词后**直接投递给当前代理执行**。
 
 ### 命令一览
 
-| 命令 | 用途 | 对应模板类型 | 含工作流 |
+| 命令 | 用途 | 对应模板类型 | 支持 Grill |
 |------|------|-------------|---------|
 | `/dev-feat` | 新功能/创意生成 | `feat` | ✅ |
 | `/dev-fix` | 问题排查/错误修正 | `fix` | ✅ |
@@ -128,9 +92,9 @@ LLM 也可以直接调用 `subagent` 工具委派任务给任意子代理：
 | `/dev-perf` | 性能优化 | `perf` | ✅ |
 | `/dev-style` | 风格/格式调整 | `style` | ✅ |
 | `/dev-security` | 安全审查 | `security` | ✅ |
-| `/dev-chore` | 日常维护/自动化 | `chore` | ❌（传统模式） |
-| `/dev-explain` | 概念解释 | `explain` | ❌（传统模式） |
-| `/dev-compare` | 对比评估 | `compare` | ❌（传统模式） |
+| `/dev-chore` | 日常维护/自动化 | `chore` | ❌ |
+| `/dev-explain` | 概念解释 | `explain` | ❌ |
+| `/dev-compare` | 对比评估 | `compare` | ❌ |
 
 ### 使用方法
 
@@ -145,14 +109,15 @@ LLM 也可以直接调用 `subagent` 工具委派任务给任意子代理：
 目标模块/文件名？ src/auth/login.ts
 核心功能描述？ 用户可以通过邮箱+密码注册并登录
 ...
-✅ 提示词已组装完成，正在发送给主代理...
+✅ 提示词已组装完成，正在发送给当前代理...
 ```
 
 **交互规则**：
 - **留空（直接回车）** — 该字段标记为「无」，对应的模板段落整段跳过
 - **输入「无」** — 与留空效果相同，明确表示不需要该段内容
 - **按 Esc** — 随时退出向导，不产生任何输出
-- **填写后** — 自动用 `pi.sendUserMessage()` 投递给主代理，立即开始执行
+- **填写后** — 自动用 `pi.sendUserMessage()` 投递给当前代理，立即开始执行
+- 向导会自动将组装好的提示词保存到 `.pi-dev-output/pi-grill/answers/`，中断后可恢复
 
 ### 示例 1：用 `/dev-fix` 修 Bug
 
@@ -181,7 +146,7 @@ Bug 描述？ 创建用户成功后返回 201，但实际上返回了 500
 
 组装后的提示词包含：角色（技术文档工程师）→ 大纲先行 → Markdown 层级文档 → 2 个可运行示例。
 
-### 示例 3：用 `/dev-feat` 走完整流程（含 Grill + 自动化工作流 + PRD）
+### 示例 3：用 `/dev-feat` 走完整流程（含 Grill + PRD）
 
 ```text
 /dev-feat
@@ -194,148 +159,27 @@ Bug 描述？ 创建用户成功后返回 201，但实际上返回了 500
 🔍 设计方案追问完善 — 是否进入方案追问完善 (Grill) 模式？
 → 逐题回答完毕（约 15-25 题），追问记录附加到提示词末尾。
 
-→ 弹出工作流确认框：
-🚀 进入自动化工作流？
-工作流将自动执行以下步骤：
-1. 📋 Planner — 分析代码库并生成实施计划
-2. 🔧 Worker → Reviewer — 实施代码并审查
-3. ✂️ Trimmer → Reviewer — 精简代码并审查
-4. 📝 DocWriter — 更新文档
-
-→ 选择"是"后，工作流开始执行...
-
-📋 工作流进度
- ▶ ⏳ 📋 生成实施计划
-   ⬜ 🔧 实施代码 → 审查
-   ⬜ ✂️ 精简代码 → 审查
-   ⬜ 📝 更新文档
-
-→ Planner 完成 ✅，计划写入 .pi-dev-output/pi-plans/
-→ Worker + Reviewer 循环开始... 审查发现 critical 问题，自动进入第 2 轮循环...
-→ 所有步骤完成后：🎉 工作流全部完成！
-
 → 弹出 PRD 确认框：
 📋 创建 PRD — 是否为此功能创建 PRD 文档？
 → 选择"是"，PRD 保存到 .pi-dev-output/pi-prd/payments-20260519.md
+→ 最终提示词（含追问记录）发送给当前代理开始执行
 ```
 
----
-
-## Automation Workflow（自动化工作流引擎）
-
-> 自 v0.4.0 起支持
-
-`/dev-*` 向导组装完提示词后，除了直接发送给主代理（传统模式），还可以选择进入 **自动化工作流** — 由一组专业的 sub-agent 按预设步骤链自动执行，无需人工逐条指令干预。
-
-工作流由 `extensions/workflow-engine.ts` 编排，在 `extensions/dev-prompts.ts` 中定义各命令的步骤链。每个步骤启动一个独立的 sub-agent 进程，拥有隔离的上下文窗口。
-
-**文件变更检测**：工作流引擎完全依赖 `git diff --name-status` 检测文件变更，与 VSCode、Zed 等专业 git 客户端的检测方式一致，无 AI 文本解析带来的假阳性噪声。
-
-### Workflow Agent 一览
-
-5 个专用 sub-agent 各司其职，定义在 `agents/workflow/` 目录下：
-
-| Agent | 职责 | 定义文件 |
-|-------|------|---------|
-| **planner** | 分析代码库，生成详细的实施计划（含可直接运行的代码示例模板）并写入 `.pi-dev-output/pi-plans/` | `agents/workflow/planner-agent.md` |
-| **worker** | 按计划逐步实现代码改动（严格遵循计划，不做计划外修改） | `agents/workflow/worker-agent.md` |
-| **reviewer** | 审查代码质量，输出带严重等级的结构化报告（critical/medium/low） | `agents/workflow/reviewer-agent.md` |
-| **trimmer** | 精简冗余代码、缩短冗长行、消除重复逻辑，优化可读性 | `agents/workflow/trimmer-agent.md` |
-| **docWriter** | 根据代码最新状态更新 README 和代码注释 | `agents/workflow/docWriter-agent.md` |
-
-### 工作流模式
-
-步骤执行前，弹出模式选择对话框：
-
-| 模式 | 说明 |
-|------|------|
-| **值守**（默认 / attended） | 自动步骤自动执行，`[confirm]` 步骤需用户确认，loop-group 循环需用户许可 |
-| **完全信任**（full-auto） | 全自动运行，无任何确认步骤。超时自动重试一次，循环自动进入下一轮 |
-| **完全值守**（full-attended） | 每一步（包括 auto 类型步骤）都需用户确认后才执行 |
-
-### 命令工作流一览
-
-每个 `/dev-*` 命令对应不同的步骤链。以下配置定义在 `extensions/dev-prompts.ts` 的 `WORKFLOW_STEPS` 常量中：
-
-图例：
-- `{}` — Loop-Group（执行 → 审查 → 循环，直到无严重问题或达最大次数）
-- `[]` — Confirm 步骤（需用户确认是否执行）
-- `→` — 顺序执行
-
-| 命令 | 工作流步骤 | 说明 |
-|------|-----------|------|
-| `/dev-feat` | planner → {worker→reviewer} → {trimmer→reviewer} → [docWriter] | 完整流程：计划 → 实施+审查 → 精简+审查 → 文档（可跳过） |
-| `/dev-fix` | planner → {worker→reviewer} → [docWriter] | 无 trimmer 阶段 |
-| `/dev-refactor` | planner → {worker→reviewer} → {trimmer→reviewer} | 无 docWriter 阶段 |
-| `/dev-perf` | planner → {worker→reviewer} | 无 trimmer 和 docWriter |
-| `/dev-test` | planner → {worker→reviewer} | 同上 |
-| `/dev-doc` | planner → docWriter | 简化流程，直接计划→撰写 |
-| `/dev-style` | {trimmer→reviewer} | 无计划阶段，仅精简+审查（最多 2 轮循环） |
-| `/dev-security` | reviewer | 仅安全审查 |
-| `/dev-chore` | 无工作流 | 传统模式，直接发送 prompt |
-| `/dev-explain` | 无工作流 | 传统模式 |
-| `/dev-compare` | 无工作流 | 传统模式 |
-
-### 断点续传 (Checkpoint)
-
-工作流在执行过程中会定期保存 checkpoint 到 `.pi-dev-output/pi-workflow/checkpoint.json`。如果工作流因终端关闭、网络断开或 AI 超时而中断，后续恢复方式如下：
-
-- **自动恢复**：再次执行对应的 `/dev-*` 命令时，引擎自动检测 checkpoint 文件，弹出确认对话框询问是否恢复
-- **手动恢复**：注册了专门的 `/dev-workflow-continue` 命令，用于手动恢复上次中断的工作流
-- **Checkpoint 内容**：包含原始 prompt、运行模式、各步骤状态、loop 次数、plan 文件引用路径
-
-如果在恢复对话框中选择"否"，则丢弃 checkpoint 重新开始。
-
-### Loop-Group 循环审查
-
-`{}` 标记的步骤组称为 Loop-Group。机制如下：
-
-1. 先执行实施 agent（worker 或 trimmer），再执行 reviewer agent
-2. Reviewer 输出 `[REVIEW_SUMMARY]` JSON 摘要：
-
-```
-[REVIEW_SUMMARY]
-{"maxSeverity":"critical","critical":2,"medium":1,"low":3}
-[/REVIEW_SUMMARY]
-```
-
-3. 若 `maxSeverity === "critical"` 且未达到最大循环次数（默认 3 次），进入下一轮循环
-4. 在 `full-auto` 模式下自动循环；在 `attended` 模式下询问用户是否继续
-5. 达到最大循环次数后，无论审查结果如何，进入下一步
-6. Reviewer 输出支持 fallback 裸 JSON 解析（兜底识别）
-
-### 超时处理
-
-每个步骤有独立的超时时间（`timeoutMs` 字段）。默认超时：worker/trimmer/planner 为 5 分钟，docWriter 为 10 分钟（600,000ms），security 审查步骤为 15 分钟（900,000ms）。超时后的行为因模式而异：
-
-| 模式 | 超时行为 |
-|------|---------|
-| `full-auto` | 自动重试一次（带 `[RETRY]` 前缀），重试仍超时则步骤标记为 failed |
-| `attended` / `full-attended` | 弹出选择：重新执行 / 跳过此步骤 / 取消工作流 |
-| loop-group 内 | 超时后不阻塞循环，可自动进入审查阶段（带 `[TIMEOUT_WARNING]` 标记） |
-
-## Skills
-
-| Skill | 来源 | 说明 |
-|---|---|---|
-| **karpathy-guidelines** | [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) | 基于 Andrej Karpathy 对 LLM 编码陷阱的观察，强调简洁、精准、可验证 |
-| **review-html** | 自制 | git diff / commit 审查，输出自包含的交互式 HTML 报告 |
-| **grill-with-docs** | [mattpocock/skills](https://github.com/mattpocock/skills) | 方案追问完善 — 挑战方案、统一术语、实时更新 CONTEXT.md 和 ADR |
-| **to-prd** | [mattpocock/skills](https://github.com/mattpocock/skills) | 从对话上下文和代码库理解生成 PRD，保存到 `.pi-dev-output/pi-prd/` |
-
 ## 方案追问完善（Grill）机制
 
-Grill（"追问式打磨"）是提交方案前由 AI sub-agent 从多个维度追问完善你的设计的交互流程。Grill 阶段在 `/dev-*` 向导完成后自动触发，以确认对话框询问是否进入追问完善。
+Grill（"追问式打磨"）是提交方案前由 AI 从多个维度追问完善你的设计的交互流程。Grill 阶段在 `/dev-*` 向导完成后自动触发，以确认对话框询问是否进入追问完善。
+
+由于当前主流模型普遍具备 >=1M 上下文窗口，Grill 不再创建隔离的子代理进程，而是由**当前代理**执行追问任务，所有追问记录直接追加到当前会话上下文中。
 
 追问完善流程：
 1. **确认** — 弹出对话框，选择"是"进入追问完善
-2. **生成问题** — sub-agent 根据方案上下文，一次生成全部追问问题（JSON 数组）
+2. **生成问题** — 当前代理根据方案上下文，一次生成全部追问问题（JSON 数组）
 3. **逐题回答** — TUI 逐题展示，每道题带选项列表 + 自定义输入入口
 4. **增强提示词** — 所有 Q&A 追加到原提示词末尾，形成 `enhancedPrompt`
 
-### 按领域定制的 Grill Agent
+### 按领域定制的 Grill 场景
 
-不同的 `/dev-*` 命令使用专门定制的 grill agent，问题方向与任务类型对齐：
+不同的 `/dev-*` 命令使用不同的追问方向，问题维度与任务类型对齐：
 
 | 命令 | Grill 场景 | 追问维度 |
 |---|---|---|
@@ -369,18 +213,40 @@ Grill（"追问式打磨"）是提交方案前由 AI sub-agent 从多个维度
 
 仅 `/dev-feat` 命令在执行完成后自动触发 PRD 生成。其余 `/dev-*` 命令不包含此阶段。
 
-流程：
-1. **等待** — 等待主代理完成任务（`ctx.waitForIdle()`）
-2. **确认** — 弹出对话框询问是否创建 PRD
-3. **生成** — sub-agent 读取对话上下文 + 代码库理解，按模板生成 Markdown PRD
-4. **保存** — 写入 `.pi-dev-output/pi-prd/<module>-<date>.md`
-5. **后续操作** — 询问是否立即开始开发：
-   - "是" — 将 PRD 作为开发指令发送给主代理
+PRD 由当前代理生成，不再使用隔离的子代理进程：
+
+1. **确认** — 弹出对话框询问是否创建 PRD
+2. **生成** — 当前代理读取对话上下文 + 代码库理解，按模板生成 Markdown PRD
+3. **保存** — 写入 `.pi-dev-output/pi-prd/<module>-<date>.md`
+4. **后续操作** — 询问是否立即开始开发：
+   - "是" — 将 PRD 作为开发指令发送给当前代理
    - "否" — 仅保存文件，稍后手动引用
    - "✏️ 自定义开发指令" — 输入自定义指令，与 PRD 一起发送
 
 PRD 模板包含：Problem Statement、Solution、User Stories、Implementation Decisions、Testing Decisions、Out of Scope、Further Notes。
 
+如果需要为其他场景生成 PRD，可以手动使用 `to-prd` skill（直接引用 `/skill:to-prd`）。
+
+## Skills
+
+| Skill | 来源 | 说明 |
+|---|---|---|
+| **karpathy-guidelines** | [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) | 基于 Andrej Karpathy 对 LLM 编码陷阱的观察，强调简洁、精准、可验证 |
+| **review-html** | 自制 | git diff / commit 审查，输出自包含的交互式 HTML 报告 |
+| **grill-with-docs** | [mattpocock/skills](https://github.com/mattpocock/skills) | 方案追问完善 — 挑战方案、统一术语、实时更新 CONTEXT.md 和 ADR |
+| **to-prd** | [mattpocock/skills](https://github.com/mattpocock/skills) | 从对话上下文和代码库理解生成 PRD，保存到 `.pi-dev-output/pi-prd/` |
+
+## 自动审查
+
+当用户输入包含 `review`/`审查`/`审阅` 且同时包含 `code`/`代码`/`diff`/`commit`/`html` 等关键词时，会自动弹出模式选择：
+
+| # | 模式 | 行为 |
+|---|------|------|
+| **1** | 开始审查（阻塞，等待结果） | 在当前代理中运行审查，等待交互式 HTML 报告生成 |
+| **2** / Esc | 不是审查（放行给主代理） | 不启动审查，原消息交给当前 AI 处理 |
+
+也支持直接输入 `/skill:review-html` 触发审查。审查结果以交互式 HTML 报告形式写入 `.pi-dev-output/pi-review/html/` 目录。
+
 ## 使用方式
 
 ### 安装
@@ -396,8 +262,6 @@ pi install git:github.com/cherish-ltt/pi-dev-workflow
 pi install /path/to/pi-dev-workflow
 ```
 
-### 加载
-
 pi 会自动加载包内的 `skills/`、`prompts/`、`extensions/`、`themes/` 内容。
 安装后执行 `/reload` 热加载所有变更。
 
@@ -411,7 +275,7 @@ pi install git:github.com/cherish-ltt/pi-dev-workflow
 ## 常见问题
 
 **Q: Grill 阶段可以跳过吗？**
-A: 可以。在 Grill 确认对话框中选择"否"即可跳过，原提示词不变直接投递给主代理。追问过程中按 Esc 也可随时取消，已回答的问题仍会附加到提示词中。
+A: 可以。在 Grill 确认对话框中选择"否"即可跳过，原提示词不变直接投递给当前代理。追问过程中按 Esc 也可随时取消，已回答的问题仍会附加到提示词中。
 
 **Q: 所有 `/dev-*` 命令都支持 Grill 吗？**
 A: 不是。以下命令支持 Grill：`/dev-feat`、`/dev-fix`、`/dev-doc`、`/dev-refactor`、`/dev-test`、`/dev-perf`。`/dev-chore`、`/dev-style`、`/dev-security`、`/dev-explain`、`/dev-compare` 不包含 Grill 阶段。
@@ -420,10 +284,10 @@ A: 不是。以下命令支持 Grill：`/dev-feat`、`/dev-fix`、`/dev-doc`、`
 A: 只有 `/dev-feat` 会在执行完成后触发 PRD 生成。其他命令不包含此阶段。如果需要为其他场景生成 PRD，可以手动使用 `to-prd` skill（直接引用 `/skill:to-prd`）。
 
 **Q: 如何自定义 Grill 的问题数量和方向？**
-A: 在 `extensions/grill-me-agent.ts` 中修改对应 AgentDef 的 `systemPrompt` 即可控制问题方向和数量。目前各领域 grill agent 的问题数量由 LLM 自主决定（典型 15-40 题）。
+A: 在 `extensions/grill-me-agent.ts` 中修改对应 Grill 场景的提示词即可控制问题方向和数量。目前各领域 Grill 的问题数量由 LLM 自主决定（典型 15-40 题）。
 
 **Q: 追问问答是否影响原提示词？**
-A: 追问问答以「方案追问记录」区块追加到原提示词末尾，原提示词内容不变。主代理执行时会同时参考原需求 + 追问中确认的决策。
+A: 追问问答以「方案追问记录」区块追加到原提示词末尾，原提示词内容不变。当前代理执行时会同时参考原需求 + 追问中确认的决策。
 
 **Q: Grill 中如何返回上一题？**
 A: 使用 `Ctrl+Shift+←` 返回上一题（在选项列表和自定义输入框中均适用）。裸 `←` 键在选项列表中无效果，在输入框中用于光标左移编辑文本。
@@ -434,26 +298,14 @@ A: `Enter` 确认提交，`Esc` 取消返回选项列表，`Ctrl+Shift+←` 返
 **Q: `grill-with-docs` skill 和 `/dev-*` 内置的 Grill 有什么区别？**
 A: `grill-with-docs` 是可独立调用的 skill（`/skill:grill-with-docs`），侧重领域术语统一和文档同步（更新 CONTEXT.md、创建 ADR）。`/dev-*` 内置的 Grill 是任务向导的一部分，侧重方案追问完善，不涉及文档持久化。
 
-**Q: 工作流执行到一半中断了怎么办？**
-A: 工作流引擎会在每次步骤完成后保存 checkpoint 到 `.pi-dev-output/pi-workflow/checkpoint.json`。重新执行对应的 `/dev-*` 命令时会自动检测并询问是否恢复。也可手动使用 `/dev-workflow-continue` 命令恢复上次中断的工作流。
-
-**Q: 如何跳过工作流，直接发送 prompt 给主代理？**
-A: 在工作流确认对话框中选择"否"即可直接发送 prompt 给主代理，行为与传统模式完全一致。
-
-**Q: `{}` loop-group 最多循环多少次？会无限循环吗？**
-A: 不会无限循环。每个 loop-group 默认最大循环次数为 3（由 `maxLoops` 字段控制），达到上限后无论审查结果如何都会进入下一步。`/dev-style` 的 loop-group 最大次数为 2。如果使用 `full-auto` 模式且问题重复出现，达到上限后自动结束循环。
-
-**Q: reviewer 的审查等级如何决定 workflow 走向？**
-A: reviewer 输出 `[REVIEW_SUMMARY]` JSON 块，`maxSeverity: "critical"` 时触发下一轮循环（如果未达上限），`"medium"` 或 `"low"` 时结束循环进入下一步。
-
-**Q: docWriter 步骤为什么要标记为 `[confirm]`？**
-A: 文档更新是可选的。有时代码变更只是内部重构或 Bug 修复，不需要更新 README。`[confirm]` 允许用户跳过此步骤。
+**Q: 自动审查可以关闭吗？**
+A: 检测到审查意图时选择"3. 不是审查"即可放行原消息给当前代理。如果需要完全关闭，可以在 `extensions/dev-prompts.ts` 中移除 `pi.on("input")` 的审查拦截逻辑。
 
-**Q: 超时后会发生什么？**
-A: 在 `full-auto` 模式下超时会自动重试一次；在 `attended` 模式下会弹出对话框让用户选择：重新执行、跳过此步骤、取消工作流。重试后仍然超时则该步骤标记为 failed。
+**Q: Git 命令需要子代理吗？**
+A: 不需要。`/git-commit`、`/git-push`、`git-commit-push` 直接通过 pi 的内置执行器运行 git，结果会出现在当前会话中。
 
-**Q: 所有命令都支持自动化工作流吗？**
-A: 不是。`/dev-chore`、`/dev-explain`、`/dev-compare` 三个命令无工作流配置，使用传统模式直接发送 prompt。其余 8 个命令均包含工作流支持。具体各命令的步骤链见「命令工作流一览」表格。
+**Q: 提示词保存到哪个目录？**
+A: 向导组装的提示词保存到 `.pi-dev-output/pi-grill/answers/`，Grill 生成的问题文件保存到 `.pi-dev-output/pi-grill/questions/`。中断后重新执行对应命令可从备份恢复。
 
 ## License