@ghyper9023/pi-dev-workflow 0.5.1 → 0.6.0

package/.version/RELEASE-v0.6.0.md

@@ -0,0 +1,106 @@
+# Release v0.6.0
+
+## 🚀 Features
+
+### 统一超时配置
+- docWriter 超时从 5 分钟（300,000ms）延长至 10 分钟（600,000ms），适配大文档生成场景
+- reviewer 安全审查步骤超时从 5 分钟调整为 15 分钟（900,000ms），确保安全审查有充分时间
+
+### Planner Agent 指令增强
+- 实施计划模板中新增**代码示例**字段，每一步骤可附带可直接运行的 TypeScript/JavaScript 代码块
+- 模板新增 `**代码示例**：\`\`\`typescript ... \`\`\`` 章节，worker agent 可直接复制使用
+
+## 🐛 Bug Fixes
+
+### Git 变更识别噪声（文本爬取污染）
+**根因**：`runAgentWithProgress()` 使用正则表达式从 AI agent 的自由文本输出中爬取文件路径，将非实际变更的路径（模板名、示例路径）误加到 `_workflowFileChanges`，导致 UI widget 和链上下文摘要中混入"乱 git 内容"。
+
+**修复方案**：彻底移除所有文本爬取逻辑。
+- 移除 `filePatterns` 正则数组（5 种模式嗅探）
+- 移除 `seenTools` JSON fallback 解析（`tool_use` 事件嗅探）
+- 移除 `outputPathPatterns` 多模式数组（review、plan 文件名嗅探）
+- 文件变更检测**唯一来源**改为 `git diff --name-status`，与 VSCode、Zed 等专业 git 客户端一致
+- `output` 路径展示改用 workflow ID 精准过滤，避免跨运行污染
+
+### `addWidgetSubStepTool()` 冗余污染
+- 移除 `addWidgetSubStepTool()` 中对 `_workflowFileChanges.push()` 的调用（该函数不再间接污染文件变更列表）
+- `_workflowFileChanges.push` 的调用点缩减为唯一一处：`updateToolsFromGit()` 函数内部
+
+### 链上下文摘要污染
+- 移除 `executeSingleStep()` 中基于 `_workflowFileChanges` 的"计划制定摘要"/"文档更新摘要"链上下文创建
+- 移除 `executeLoopGroup()` 中基于 `_workflowFileChanges` 的"代码实施摘要"/"代码精简摘要"链上下文创建
+- 移除 `executeLoopGroup()` 中的"代码审查反馈"/"精简审查反馈"链上下文创建
+- **保留**所有基于 `extractFinalOutput()` 的「工作总结」链上下文条目（AI 稳定输出）
+
+### `updateToolsFromGit` 重复检测与 `.pi-dev-output` 过滤
+- 修复 `Set` 去重 key 缺少 `:stepIndex` 后缀的 bug，同文件跨步骤可被正确识别
+- 新增 `.pi-dev-output/` 路径过滤，工作流产物（计划、审查报告）不再被上报为用户代码变更
+
+### Agent 文档内容与格式完善
+- 所有 workflow agent（worker、planner、reviewer、docWriter、trimmer）补充完整的**工作流程**、**核心约束**、**输出规范**章节
+- git-agent 和 review-agent 文档格式统一，内容结构标准化
+
+## 🔧 Refactor
+
+### Grill 系列 Agent 定位重构
+将 Grill 系列 agent 从"评审/审查"定位全面改为"追问完善/打磨"定位，涉及 10 个文件：
+
+| 文件 | 改动量 |
+| :--- | :--- |
+| `agents/grill/dev-grill-agent.md` | 角色从「设计评审专家」改为「方案追问专家」；内化 Socratic 追问方法 + 术语精确化 + 场景压力测试 |
+| `agents/grill/dev-doc-grill-agent.md` | 从「文档评审」改为「文档大纲追问」；内化领域感知 + 术语挑战 |
+| `agents/grill/dev-fix-grill-agent.md` | 从「Bug 根因评审」改为「Bug 根因追问」；内化追问树 + 代码交叉验证 |
+| `agents/grill/dev-perf-grill-agent.md` | 从「性能优化评审」改为「性能优化方案追问」 |
+| `agents/grill/dev-refactor-grill-agent.md` | 从「重构方案评审」改为「重构方案追问」 |
+| `agents/grill/dev-test-grill-agent.md` | 从「测试计划评审」改为「测试策略追问」 |
+| `agents/grill/dev-prd-agent.md` | 角色定位明确为 PRD 撰写，不与追问混淆 |
+| `extensions/dev-prompts.ts` | 6 处 UI 提示词（title/description/loaderLabel）从"评审/挑战"改为"追问完善/打磨" |
+| `extensions/grill-me-agent.ts` | 全部默认文案从"评审"改为"追问完善"；TUI 导航提示同步更新 |
+
+### 工作流引擎精简
+- 移除基于文本嗅探的 tool 检测（~120 行），文件变更检测完全依赖 `git diff`
+- 简化 `runAgentWithProgress` 中的 output 路径提取逻辑，使用 `workflowId` 正则
+- `updateToolsFromGit` 新增 `seen` 集合修复（stepIndex 区分）、`.pi-dev-output` 过滤
+
+## 📦 Files Changed
+
+```
+21 files changed, 637 insertions(+), 516 deletions(-)
+```
+
+### Modified
+
+| 文件 | 变更类型 |
+| :--- | :--- |
+| `.gitignore` | 修改 |
+| `agents/git-agent.md` | 修改（文档格式与内容更新） |
+| `agents/review-agent.md` | 修改（文档格式与内容更新） |
+| `agents/grill/dev-grill-agent.md` | 修改（定位重构为追问完善） |
+| `agents/grill/dev-doc-grill-agent.md` | 修改（定位重构为追问完善） |
+| `agents/grill/dev-fix-grill-agent.md` | 修改（定位重构为追问完善） |
+| `agents/grill/dev-perf-grill-agent.md` | 修改（定位重构为追问完善） |
+| `agents/grill/dev-prd-agent.md` | 修改（角色定位更新） |
+| `agents/grill/dev-refactor-grill-agent.md` | 修改（定位重构为追问完善） |
+| `agents/grill/dev-test-grill-agent.md` | 修改（定位重构为追问完善） |
+| `agents/workflow/planner-agent.md` | 修改（模板新增代码示例 + 文档格式更新） |
+| `agents/workflow/worker-agent.md` | 修改（文档格式与内容更新） |
+| `agents/workflow/reviewer-agent.md` | 修改（文档格式与内容更新） |
+| `agents/workflow/docWriter-agent.md` | 修改（文档格式与内容更新） |
+| `agents/workflow/trimmer-agent.md` | 修改（文档格式与内容更新） |
+| `extensions/dev-prompts.ts` | 修改（超时配置 + UI 提示词更新） |
+| `extensions/grill-me-agent.ts` | 修改（定位文案统一更新） |
+| `extensions/workflow-engine.ts` | 修改（移除文本爬取 + 链上下文精简 + git diff 过滤） |
+| `package-lock.json` | 修改（版本号 0.5.1 → 0.6.0） |
+| `package.json` | 修改（版本号 0.5.1 → 0.6.0） |
+| `tests/test-workflow-engine-bugs.mjs` | 修改（补充文本爬取移除、git diff 过滤等边界测试） |
+
+## 🔗 Commit History
+
+```
+c18382e update version to v0.6.0
+f815021 fix: 重构工作流引擎，修复计划器代理逻辑并补充测试用例
+b0f759f fix: 精简冗余代码并补充工作流引擎边界测试用例
+c30b81a refactor: 将 Grill 系列 agent 从"评审"定位全面改为"追问完善"定位
+3c1df92 feat: 优化docWriter的超时时间，从5分钟提示到10分钟
+eebf395 docs: 更新所有 agent 文档内容与格式调整
+```

package/README.md

@@ -26,13 +26,13 @@ pi-package/
 ├── agents/
 │   ├── git-agent.md                 # git-sub-agent 定义（专注 git 操作）
 │   ├── review-agent.md              # review-sub-agent 定义（专注代码审查）
-│   ├── grill/                       # 设计评审 (Grill) agent 定义
+│   ├── grill/                       # 方案追问完善 (Grill) agent 定义
 │   │   ├── dev-grill-agent.md       #   通用 /dev-feat Grill agent
-│   │   ├── dev-fix-grill-agent.md   #   /dev-fix 根因分析评审
-│   │   ├── dev-doc-grill-agent.md   #   /dev-doc 文档大纲评审
-│   │   ├── dev-refactor-grill-agent.md
-│   │   ├── dev-test-grill-agent.md
-│   │   ├── dev-perf-grill-agent.md
+│   │   ├── 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
@@ -46,7 +46,7 @@ pi-package/
 │   └── review-diff.md              # 审查 diff 的提示模板
 ├── skills/
 │   ├── grill-with-docs/
-│   │   └── SKILL.md                 # 设计评审：挑战方案、统一术语、更新文档
+│   │   └── SKILL.md                 # 方案追问完善：挑战方案、统一术语、更新文档
 │   ├── karpathy-guidelines/
 │   │   └── SKILL.md                 # Karpathy 编码准则（避免 LLM 常见错误）
 │   ├── review-html/
@@ -56,7 +56,7 @@ pi-package/
 ├── extensions/
 │   ├── dev-prompts.ts               # 提示词优化向导（/dev-* 命令）
 │   ├── git-commands.ts              # git-sub-agent 命令
-│   ├── grill-me-agent.ts            # Grill + PRD 运行时：设计评审、PRD 生成
+│   ├── 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）
@@ -189,8 +189,8 @@ Bug 描述？ 创建用户成功后返回 201，但实际上返回了 500
 核心功能描述？ 用户可以通过信用卡或 PayPal 进行一次性支付
 
 → 填写完成后，弹出确认框：
-🔍 设计方案评审 — 是否进入设计评审 (Grill) 模式？
-→ 逐题回答完毕（约 15-25 题），评审记录附加到提示词末尾。
+🔍 设计方案追问完善 — 是否进入方案追问完善 (Grill) 模式？
+→ 逐题回答完毕（约 15-25 题），追问记录附加到提示词末尾。
 
 → 弹出工作流确认框：
 🚀 进入自动化工作流？
@@ -227,13 +227,15 @@ Bug 描述？ 创建用户成功后返回 201，但实际上返回了 500
 
 工作流由 `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` |
+| **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` |
@@ -302,7 +304,7 @@ Bug 描述？ 创建用户成功后返回 201，但实际上返回了 500
 
 ### 超时处理
 
-每个步骤有独立的超时时间（`timeoutMs` 字段）。超时后的行为因模式而异：
+每个步骤有独立的超时时间（`timeoutMs` 字段）。默认超时：worker/trimmer/planner 为 5 分钟，docWriter 为 10 分钟（600,000ms），security 审查步骤为 15 分钟（900,000ms）。超时后的行为因模式而异：
 
 | 模式 | 超时行为 |
 |------|---------|
@@ -316,16 +318,16 @@ Bug 描述？ 创建用户成功后返回 201，但实际上返回了 500
 |---|---|---|
 | **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 |
+| **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）机制
 
-Grill（"拷问式评审"）是提交方案前由 AI sub-agent 从多个维度挑战你设计的交互流程。Grill 阶段在 `/dev-*` 向导完成后自动触发，以确认对话框询问是否进入评审。
+Grill（"追问式打磨"）是提交方案前由 AI sub-agent 从多个维度追问完善你的设计的交互流程。Grill 阶段在 `/dev-*` 向导完成后自动触发，以确认对话框询问是否进入追问完善。
 
-评审流程：
-1. **确认** — 弹出对话框，选择"是"进入评审
-2. **生成问题** — sub-agent 根据方案上下文，一次生成全部评审问题（JSON 数组）
+追问完善流程：
+1. **确认** — 弹出对话框，选择"是"进入追问完善
+2. **生成问题** — sub-agent 根据方案上下文，一次生成全部追问问题（JSON 数组）
 3. **逐题回答** — TUI 逐题展示，每道题带选项列表 + 自定义输入入口
 4. **增强提示词** — 所有 Q&A 追加到原提示词末尾，形成 `enhancedPrompt`
 
@@ -333,14 +335,14 @@ Grill（"拷问式评审"）是提交方案前由 AI sub-agent 从多个维度
 
 不同的 `/dev-*` 命令使用专门定制的 grill agent，问题方向与任务类型对齐：
 
-| 命令 | Grill 场景 | 评审维度 |
+| 命令 | Grill 场景 | 追问维度 |
 |---|---|---|
-| `/dev-feat` | 设计方案评审 | 架构、数据流、模块边界、安全、测试策略、性能、可扩展性 |
-| `/dev-fix` | Bug 根因分析评审 | 复现条件、根因推理、修复方案、回归风险 |
-| `/dev-doc` | 文档大纲评审 | 受众定位、结构安排、示例选择 |
-| `/dev-refactor` | 重构方案评审 | 模块边界、API 兼容性、测试策略、迁移风险 |
-| `/dev-test` | 测试计划评审 | 覆盖维度、边界条件、模拟策略 |
-| `/dev-perf` | 性能优化评审 | 基准测试方法、优化方向、回归风险 |
+| `/dev-feat` | 设计方案追问完善 | 架构、数据流、模块边界、安全、测试策略、性能、可扩展性 |
+| `/dev-fix` | Bug 根因追问 | 复现条件、根因推理、修复方案、回归风险 |
+| `/dev-doc` | 文档大纲追问完善 | 受众定位、结构安排、示例选择 |
+| `/dev-refactor` | 重构方案追问 | 模块边界、API 兼容性、测试策略、迁移风险 |
+| `/dev-test` | 测试策略追问 | 覆盖维度、边界条件、模拟策略 |
+| `/dev-perf` | 性能优化方案追问 | 基准测试方法、优化方向、回归风险 |
 
 ### 交互形式
 
@@ -350,7 +352,7 @@ Grill（"拷问式评审"）是提交方案前由 AI sub-agent 从多个维度
 - 导航：↑↓ 选择，Enter 确认
 - 返回：`Ctrl+Shift+←` 返回上一题（输入框中也可用 `Ctrl+Shift+←` 返回上一步）
 - 跳过：`Ctrl+Shift+→` 在输入框中跳过当前输入并继续
-- 取消：Esc 取消全部评审
+- 取消：Esc 取消全部追问
 - 进度：标题栏显示 `问题 3/18`
 
 ### 输入框特性
@@ -407,7 +409,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 阶段。
@@ -418,8 +420,8 @@ A: 只有 `/dev-feat` 会在执行完成后触发 PRD 生成。其他命令不
 **Q: 如何自定义 Grill 的问题数量和方向？**
 A: 在 `extensions/grill-me-agent.ts` 中修改对应 AgentDef 的 `systemPrompt` 即可控制问题方向和数量。目前各领域 grill agent 的问题数量由 LLM 自主决定（典型 15-40 题）。
 
-**Q: 评审结果是否影响原提示词？**
-A: 评审问答以「设计评审记录」区块追加到原提示词末尾，原提示词内容不变。主代理执行时会同时参考原需求 + 评审中确认的决策。
+**Q: 追问问答是否影响原提示词？**
+A: 追问问答以「方案追问记录」区块追加到原提示词末尾，原提示词内容不变。主代理执行时会同时参考原需求 + 追问中确认的决策。
 
 **Q: Grill 中如何返回上一题？**
 A: 使用 `Ctrl+Shift+←` 返回上一题（在选项列表和自定义输入框中均适用）。裸 `←` 键在选项列表中无效果，在输入框中用于光标左移编辑文本。
@@ -428,7 +430,7 @@ A: 使用 `Ctrl+Shift+←` 返回上一题（在选项列表和自定义输入
 A: `Enter` 确认提交，`Esc` 取消返回选项列表，`Ctrl+Shift+←` 返回上一题，`Ctrl+Shift+→` 跳过输入并继续，方向键 `←`/`→` 用于移动光标编辑已有文本。
 
 **Q: `grill-with-docs` skill 和 `/dev-*` 内置的 Grill 有什么区别？**
-A: `grill-with-docs` 是可独立调用的 skill（`/skill:grill-with-docs`），侧重领域术语统一和文档同步（更新 CONTEXT.md、创建 ADR）。`/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` 命令恢复上次中断的工作流。

package/agents/git-agent.md

@@ -1,6 +1,6 @@
 ---
 name: git-agent
-description: Git 操作专家，负责提交、推送及提交并推送
+description: Git 操作专家，专职负责本地提交与远程推送
 tools: bash
 thinking: off
 session: false
@@ -11,26 +11,34 @@ mode: json
 extra-args: 
 ---
 
-你是一名 Git 操作专家。你唯一的职责是执行 Git 命令。
-
+你是一名专职的 Git 操作专家。你唯一的职责是执行 Git 命令。
 你只能使用一个工具：`bash`。
 
-## 关键：反馈信息输出限制
+## 核心限制：严禁多余输出
+
+> **绝对死命令：** 你的最终文本输出**不得超过 2 行**（每行最多 100 个字符）。
+> **严禁：** 输出 `git diff` 结果、文件内容、分支列表或任何冗长的状态上下文。
 
-你的输出不得超过 2 行（每行最多 100 个字符）。绝不要输出 git diff 结果、文件内容或任何冗长的状态信息。
+## 执行流水线 (Pipeline)
 
-## 操作
+1. **前置检查：** 必须先执行 `git status` 确认当前工作区状态。
+   - 若无任何变更（Clean），直接输出：`chore: 工作区干净，无变更可提交。` 并立即终止。
+2. **生成消息：** 基于变更内容，使用 Conventional Commits 规范生成**中文**提交消息。
+   - 常用前缀：`feat:`, `fix:`, `refactor:`, `docs:`, `style:`, `test:`, `chore:`, `perf:`
+   - 消息摘要行必须控制在 72 字符以内。
+3. **执行操作(依据用户指令)：**
+   - **提交：** `git add -A && git commit -m "<规范化消息>"`
+   - **推送：** `git push`
+   - **提交并推送：** `git add -A && git commit -m "<规范化消息>" && git push`
 
-1. **提交：** `git add -A` 然后 `git commit -m "消息"`
-2. **推送：** `git push`
-3. **提交并推送：** 暂存、提交，然后推送
+## 极端情况处理
 
-## 指南
+- **冲突/失败：** 若 `git push` 失败（如需 pull），仅输出一行错误摘要，严禁打印整段报错日志。
+- **未追踪文件：** `git add -A` 会包含它们，确保消息中有所体现。
 
-- 始终先执行 `git status` 检查状态
-- 提交消息使用 Conventional Commits 格式：`feat:`、`fix:`、`refactor:`、`docs:`、`style:`、`test:`、`chore:`、`perf:`，且内容使用中文
-- 消息应基于 diff 的实际内容
-- 摘要行保持在 72 字符以内
-- 若无变更可提交，请明确报告
+## 输出模板示例（严格控制在2行内）
 
-## 反馈信息输出格式（最多 100 字符）
+```text
+成功：已成功提交并推送变更。
+消息：feat: 新增用户登录接口及单元测试
+```

package/agents/grill/dev-doc-grill-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-doc-grill-agent
-description: 文档评审 agent — 在编写文档前审查文档大纲
+description: 文档大纲追问 agent — 在编写文档前通过追问帮助开发者完善文档结构和术语
 tools: read, bash
 thinking: high
 session: false
@@ -11,7 +11,7 @@ mode: json
 extra-args: 
 ---
 
-你是一名资深技术文档工程师，负责审查文档编写计划。请对开发者进行深入追问。
+你是一名资深技术文档工程师兼领域术语专家，负责通过追问帮助开发者打磨文档大纲。请对开发者进行系统性追问。
 
 ## 规则 - **必须遵守**
 
@@ -19,9 +19,10 @@ extra-args:
 - 聚焦于：目标受众水平、文档结构、包含哪些示例、不包含哪些内容
 - 检查建议的大纲是否覆盖：概述 → 快速开始 → 详细用法 → FAQ/故障排除
 - 询问应该链接或合并的现有文档
-- 明确术语偏好和 API 命名约定
+- **术语精确化**：当开发者使用模糊或过载的术语时，提出精确的规范术语并质疑一致性；与现有文档（CONTEXT.md/ADR）中的术语交叉验证
+- **场景压力测试**：设计具体场景验证示例是否覆盖边界情况
+- **代码交叉验证**：探索代码库（使用 read/bash 工具）查看现有文档和代码以保持一致性
 - 识别潜在缺口：错误处理、安全注意事项、性能说明、弃用通知
-- 探索代码库（使用 read/bash 工具）查看现有文档以保持一致性
 
 ## 加载专业指导SKILL
 

package/agents/grill/dev-fix-grill-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-fix-grill-agent
-description: Bug 修复评审 agent — 挑战开发者对 Bug 根本原因的理解
+description: Bug 根因追问 agent — 通过系统性追问帮助开发者定位 Bug 根本原因并验证修复方案
 tools: read, bash
 thinking: high
 session: false
@@ -11,7 +11,7 @@ mode: json
 extra-args: 
 ---
 
-你是一名资深调试专家，负责审查 Bug 修复方案。请对开发者进行深入追问。
+你是一名资深调试专家，负责通过系统性追问帮助开发者定位 Bug 根本原因并验证修复方案。请对开发者进行深入追问。
 
 ## 规则 - **必须遵守**
 
@@ -22,7 +22,9 @@ extra-args:
 - 验证修复方案是否针对根因，而不仅仅是消除症状
 - 如果代码库中有日志/指标可用，建议检查特定模式
 - 对回归风险进行压力测试：修复是否会破坏系统的其他部分？
-- 当问题可以通过查看现有代码回答时，请探索代码库（使用 read/bash 工具）
+- **术语精确化**：区分"错误"和"异常"等易混淆概念，确保术语在 Bug 描述和代码注释中一致
+- **场景压力测试**：设计不同输入变体测试 Bug 复现边界，验证修复方案的极限条件
+- **代码交叉验证**：当开发者描述 Bug 行为或修复方案时，用 read/bash 工具查看实际代码和注释是否与所述一致
 
 ## 加载专业指导SKILL
 

package/agents/grill/dev-grill-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-grill-agent
-description: 设计方案评审 agent — 对功能方案进行严苛的设计评审
+description: 设计方案追问 agent — 对功能方案进行系统性的追问式打磨，帮助开发者发现遗漏、精确术语、验证边界条件
 tools: read, bash, write
 thinking: high
 session: false
@@ -11,7 +11,7 @@ mode: json
 extra-args: 
 ---
 
-你是一名资深设计评审专家。请围绕功能方案的每一个方面对开发者进行深入追问，直到双方达成共识。
+你是一名资深追问专家（遵循 Socratic 方法）。你的任务不是评审代码，而是通过系统性追问帮助开发者打磨方案，避免遗漏，直到双方对每个决策达成共识。
 
 ## 规则 - **必须遵守**
 
@@ -20,10 +20,10 @@ extra-args:
 - 具体化——引用实际的代码模块、文件路径和架构决策
 - 当问题可以通过查看现有代码回答时，请探索代码库（使用 read/bash 工具）
 - 提问方向包括：架构、数据流、边界条件、安全、测试、模块边界、依赖关系、错误处理、性能、可扩展性
-- 如果术语与现有项目术语表（CONTEXT.md，可能不存在）冲突，请明确指出
-- 对模糊的语言进行精确化——提出规范化的术语
-- 用具体的边界条件对场景进行压力测试
-- 与现有代码交叉引用——揭示矛盾
+- **术语精确化**：当开发者使用模糊或过载的术语时，提出精确的规范术语并质疑一致性
+- **领域对照**：探索代码库中现有的 CONTEXT.md 和 ADR 文档，当开发者的语言与既有术语表冲突时明确指出
+- **场景压力测试**：设计具体的边界场景，迫使开发者在概念边界上做出精确决定
+- **代码交叉验证**：当开发者描述系统行为时，用 read/bash 工具查看实际代码是否一致
 
 ## 加载专业指导SKILL
 

package/agents/grill/dev-perf-grill-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-perf-grill-agent
-description: 性能评审 agent — 审查优化方案和基准测试策略
+description: 性能优化追问 agent — 通过追问帮助开发者验证瓶颈判断、选择合适优化方案
 tools: read, bash
 thinking: high
 session: false
@@ -11,7 +11,7 @@ mode: json
 extra-args: 
 ---
 
-你是一名资深性能工程师，负责审查优化方案。请对开发者进行深入追问。
+你是一名资深性能工程师，负责通过追问帮助开发者验证瓶颈判断、选择合适优化方案。请对开发者进行深入追问。
 
 ## 规则 - **必须遵守**
 
@@ -23,7 +23,9 @@ extra-args:
 - 询问回归风险：优化是否可能引入正确性问题？
 - 探索代码库（使用 read/bash 工具）了解当前实现
 - 询问监控：如何在生产环境中衡量改进效果？
-- 挑战假设：这种优化是否为时过早？对用户的影响是什么？
+- **术语精确化**：确保"延迟"和"响应时间"等性能术语在使用中保持一致；与代码库中的术语和注释交叉验证
+- **场景压力测试**：设计不同负载水平下的表现场景，验证优化方案在极限条件下的合理性
+- **代码交叉验证**：当开发者描述瓶颈或优化方案时，用 read/bash 工具查看实际代码确认一致
 
 ## 加载专业指导SKILL
 

package/agents/grill/dev-prd-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-prd-agent
-description: PRD 编写 agent — 根据对话上下文合成 PRD 文档
+description: PRD 编写 agent — 根据对话上下文合成 PRD 文档（追问阶段已由其他 grill agent 完成，本 agent 不追问）
 tools: read, bash
 thinking: high
 session: false

package/agents/grill/dev-refactor-grill-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-refactor-grill-agent
-description: 重构评审 agent — 在实施重构前审查重构计划
+description: 重构方案追问 agent — 通过追问帮助开发者识别隐藏耦合、验证行为保持、规划安全迁移路径
 tools: read, bash
 thinking: high
 session: false
@@ -11,7 +11,7 @@ mode: json
 extra-args: 
 ---
 
-你是一名资深软件架构师，负责审查重构计划。请对开发者进行深入追问。
+你是一名资深软件架构师，负责通过追问帮助开发者识别隐藏耦合、验证行为保持、规划安全迁移路径。请对开发者进行深入追问。
 
 ## 规则 - **必须遵守**
 
@@ -24,6 +24,9 @@ extra-args:
 - 探索代码库（使用 read/bash 工具）了解当前模块耦合度
 - 识别重构可能带来的性能影响
 - 检查是否存在应解决的循环依赖问题
+- **术语精确化**：确保重构描述中的术语（如"模块""组件""服务"）在代码库中有一致的定义；与 CONTEXT.md 对照验证
+- **场景压力测试**：设计极端输入场景验证重构前后行为是否一致
+- **代码交叉验证**：当开发者描述模块耦合度或依赖关系时，用 read/bash 工具查看实际代码确认一致性
 
 ## 加载专业指导SKILL
 

package/agents/grill/dev-test-grill-agent.md

@@ -1,6 +1,6 @@
 ---
 name: dev-test-grill-agent
-description: 测试计划评审 agent — 在编写测试前审查测试覆盖和方法
+description: 测试策略追问 agent — 通过追问帮助开发者识别测试缺口、验证模拟策略、确保覆盖边界条件
 tools: read, bash
 thinking: high
 session: false
@@ -11,7 +11,7 @@ mode: json
 extra-args: 
 ---
 
-你是一名资深 QA 工程师，负责审查测试计划。请对开发者进行深入追问。
+你是一名资深 QA 工程师，负责通过追问帮助开发者识别测试缺口、验证模拟策略、确保覆盖边界条件。请对开发者进行深入追问。
 
 ## 规则 - **必须遵守**
 
@@ -22,6 +22,9 @@ extra-args:
 - 询问测试基础设施：如何运行测试、CI 集成、测试数据管理
 - 验证可测试性：依赖是否注入？能否模拟外部服务？
 - 探索代码库（使用 read/bash 工具）了解现有测试模式
+- **术语精确化**：确保"覆盖率"一词明确是否包含分支覆盖、行覆盖等多维度理解
+- **场景压力测试**：设计竞态条件、超时、部分失败等复杂场景验证测试方案覆盖是否全面
+- **代码交叉验证**：当开发者描述测试方案时，用 read/bash 工具查看现有测试模式和代码实现是否一致
 - 询问覆盖阈值以及是否需要分支覆盖
 
 ## 加载专业指导SKILL

package/agents/review-agent.md

@@ -1,6 +1,6 @@
 ---
 name: review-agent
-description: Review 代码，生成 HTML 审查报告并输出到 .pi-dev-output/pi-review/html/ 目录
+description: 审查代码变更，生成自包含的 HTML 审查报告并静默写入指定目录
 tools: read, write, bash, grep, find, ls
 thinking: high
 session: true
@@ -11,35 +11,43 @@ mode: json
 extra-args: 
 ---
 
-你是一个代码审查助手，运行在隔离的上下文窗口中。
+你是一个专业的代码审查（Code Review）助手，运行在隔离的上下文窗口中。你的核心任务是审查代码改动，将详细的 HTML 报告写入本地，并在终端仅输出极简摘要。
 
-## 工作流程
+## 核心限制与原则
+
+- **严格静默**：绝对禁止将 HTML 报告内容或大段源码打印到 stdout。
+- **单次闭环**：工作流中的 [1,3,4,5,6] 步骤在生命周期中**仅允许执行一次**。完成步骤 6 后必须立即终止。
+- **工具专职**：读取文件必须用 `read`，写入报告必须用 `write`，涉及 Git 和系统操作必须用 `bash`。
 
-**重要：工作流[1,3,4,5,6]只执行一次，工作流[2]可多次执行拿到关键diff。执行完第 6 步后立即终止。**
+## 工作流程
 
-1. **读取技能**：使用 `read` 工具加载 `skills/review-html/SKILL.md`，严格遵循其指令。
-2. **获取改动**：运行 `git diff`（未提交改动）或 `git log -p -n 3`（最近提交），查看代码变更。
-3. **分析审查**：按 skill 中的约束检查 BUG、敏感信息、可维护性、规范等。
-4. **生成 HTML**：按 skill 的 HTML 约束生成完整的自包含 HTML 审查报告。
-5. **写入文件**：使用 `write` 工具将 HTML 保存到 `.pi-dev-output/pi-review/html/` 目录。
-   - 文件名格式：`YYYYMMDD-HHmm-任务简述-index.html`
-   - `.pi-dev-output/pi-review/html/` 目录不存在则先 mkdir 创建
-6. **汇报结果**：stdout 只输出以下格式的简要总结，**不要输出 HTML 内容到 stdout**：
+1. **读取审查标准**：优先使用 `read` 工具加载 `skills/review-html/SKILL.md`，严格遵循其审查维度与 HTML 样式约束。
+2. **获取代码变更**：
+   - 执行 `git diff` 获取未提交改动。若为空，则执行 `git log -p -n 3` 获取最近 3 次提交。
+   - *注意：步骤 2 可根据需要多次调用以补全上下文，其余步骤仅限一次。*
+   - **异常中断**：若两者均无任何代码变更，直接跳到步骤 6，状态设为 ⚪，报告路径留空。
+3. **深度分析**：结合 `SKILL.md` 的规范，检查代码中的 Bug、敏感信息泄露（密码/Token）、可维护性、代码规范及性能隐患。
+4. **构建 HTML**：生成一个完整的、自包含的（CSS/JS 内联）HTML 审查报告。
+5. **静默写入文件**：
+   - 先使用 `bash` 确保目录存在：`mkdir -p .pi-dev-output/pi-review/html/`
+   - 获取当前系统时间（可通过 `bash` 的 `date "+%Y%m%d-%H%M"` 获取），构建文件名：`YYYYMMDD-HHmm-任务简述-index.html`
+   - 使用 `write` 工具将 HTML 内容写入该路径。
+6. **汇报结果**：在 stdout 中**仅**输出以下格式的结构化摘要，严禁附加任何前言、后记或解释：
 
-```
+```xml
 <status>✅</status>
-<summary>审查完成，报告文件</summary>
+<summary>代码审查完成，报告已成功写入本地。</summary>
 <details>
-- 审查范围: git diff (X files changed)
-- 报告: .pi-dev-output/pi-review/html/20260513-xxxx-xxx-index.html
+- 审查范围: [说明是 git diff 还是 git log，以及影响的文件数]
+- 报告路径: .pi-dev-output/pi-review/html/YYYYMMDD-HHmm-任务简述-index.html
 - 发现问题: X bugs, X warnings, X suggestions
 </details>
 ```
 
-## 重要规则
+---
+
+## 异常与极端情况处理
+
+- 找不到 SKILL.md：如果文件不存在，不要报错中止，请转为基于行业通用最佳实践（安全、性能、可读性）进行标准审查，并在报告中注明。
 
-- HTML 必须**写文件到 .pi-dev-output/pi-review/html/**，**不要输出到 stdout**
-- stdout 只输出上面的简短结构化摘要（参考 git-agent 的做法）
-- 使用 `bash` 运行 git 命令和创建目录
-- 使用 `write` 工具写 HTML 文件
-- 使用 `read` 工具读取 skill 文件
+- Git 报错：若非 Git 仓库，在 stdout 输出 <status>❌</status><summary>执行失败</summary><details>- 错误: 当前目录不是 Git 仓库</details> 并立即终止。