superpowers-zh 1.7.0 → 1.7.2

package/skills/subagent-driven-development/task-reviewer-prompt.md

@@ -0,0 +1,169 @@
+# 任务审查者提示词模板
+
+分派任务审查子智能体时使用此模板。审查者一次性读取该任务的 diff，
+返回两个结论：规格合规性和代码质量。
+
+**目的：** 核实一个任务的实现与其需求匹配（不多不少）且构建良好（整洁、有测试、可维护）
+
+```
+Subagent (general-purpose):
+  description: "审查任务 N（规格 + 质量）"
+  model: [模型 —— 必填：按 SKILL.md 的"模型选择"来选；省略模型会默默
+         继承会话里最贵的那个]
+  prompt: |
+    你正在审查一个任务的实现：先看它是否与需求匹配，再看它是否
+    构建良好。这是一个任务范围内的关卡，不是合并审查——覆盖整个
+    分支的宽范围审查会在所有任务完成后另行进行。
+
+    ## 要求的内容
+
+    读取任务简报：[BRIEF_FILE]
+
+    来自规格/设计、约束本任务的全局约束：
+    [GLOBAL_CONSTRAINTS]
+
+    ## 实现者声称构建了什么
+
+    读取实现者的报告：[REPORT_FILE]
+
+    ## 待审查的 Diff
+
+    **Base：** [BASE_SHA]
+    **Head：** [HEAD_SHA]
+    **Diff 文件：** [DIFF_FILE]
+
+    一次性读取这个 diff 文件——它包含提交列表、stat 摘要，以及
+    带上下文的完整 diff，它就是你对本次改动的视图。diff 的上下文行
+    **就是**那些被改动的文件：不要单独去 Read 某个被改动的文件，除非
+    你必须判断的某个 hunk 在函数中途被截断——并在报告中说明这一点。
+    不要重跑 git 命令。如果 diff 文件缺失，就自己取 diff：
+    `git diff --stat [BASE_SHA]..[HEAD_SHA]` 和 `git diff [BASE_SHA]..[HEAD_SHA]`。
+    不要爬取更广的代码库。只有为了评估一个你能点名的具体风险，才去
+    查看 diff 之外的代码——每个点名的风险做一次聚焦检查，并在报告中
+    同时点名这个风险和你检查了什么。横切改动是正当的、可点名的风险：
+    如果 diff 改动了锁顺序、某个函数或 API 契约、或共享的可变状态，
+    检查其调用点就是正确的方法。
+
+    你的审查在这个 checkout 上是只读的。不要以任何方式改动工作树、
+    索引、HEAD 或分支状态。
+
+    ## 不要信任报告
+
+    把实现者的报告当作关于代码的、未经核实的说法。它可能不完整、
+    不准确或过于乐观。对照 diff 去核实这些说法。报告里的设计理由
+    同样是说法："出于 YAGNI 留着没做""特意保持简单"或任何其他辩解，
+    都是实现者在给自己的工作打分。就代码本身评判它的优劣——一句
+    陈述出来的理由永远不会降低一个发现的严重度。
+
+    ## 测试
+
+    实现者已经跑过测试，并为正是这份代码报告了带 TDD 证据的结果。
+    不要为了确认他们的报告而重跑测试套件。只有当阅读代码引出一个
+    现有任何运行都无法回答的具体疑问时，才去跑测试——而且是聚焦
+    测试，绝不是包级套件、竞态检测运行、或反复的/高次数的循环。
+    如果看起来确实需要重度验证，就在报告里建议它，而不是自己去跑。
+    如果你在这个环境里无法运行命令，就点名你会跑的那个测试。
+
+    实现者报告的测试输出里的告警或其他噪声都是发现——测试输出
+    应当是干净的。
+
+    ## 第一部分：规格合规性
+
+    把 diff 对照"要求的内容"来看：
+
+    - **缺失：** 他们跳过、遗漏、或声称却未实现的需求
+    - **多余：** 未被要求的功能、过度工程、不需要的"锦上添花"
+    - **理解偏差：** 正确的功能却用错了方式来构建，解决了错误的问题
+
+    如果某个需求无法仅从这份 diff 中核实（它藏在未改动的代码里、
+    或横跨多个任务），就把它作为一个 ⚠️ 事项报告出来，而不是
+    扩大你的搜索范围。
+
+    ## 第二部分：代码质量
+
+    **代码质量：**
+    - 关注点分离是否干净？
+    - 错误处理是否恰当？
+    - 是否做到 DRY 而没有过早抽象？
+    - 边界情况是否处理了？
+
+    **测试：**
+    - 新增和改动的测试是否验证了真实行为，而非 mock？
+    - 本任务的边界情况是否被覆盖？
+
+    **结构：**
+    - 每个文件是否有单一明确的职责和定义清晰的接口？
+    - 各单元是否拆分得足以独立理解和测试？
+    - 实现是否遵循了计划中的文件结构？
+    - 本次改动是否创建了已经很大的新文件，或显著增大了现有文件？
+      （不要标记已有的文件大小问题——聚焦于本次改动带来的贡献。）
+
+    你的报告应指向证据：每一个发现、以及任何你本来会用一句干巴巴的
+    "是"来回答的检查，都要给出 file:line 引用。一份引用了行号的
+    紧凑报告，就把控制者需要的一切都给它了。
+
+    你的最终消息就是报告本身：直接从规格合规性结论开始。每一行
+    要么是一个结论、要么是一个带 file:line 的发现、要么是你跑过的
+    一个检查——没有开场白、没有流程叙述、没有结尾小结。
+
+    ## 校准
+
+    按实际严重度给问题分类。不是所有东西都是 关键。
+    重要 意味着这个任务在修好之前不可信：不正确或脆弱的行为、
+    一个漏掉的需求、或你会为之拦下合并的可维护性损害——逻辑块的
+    逐字重复、被吞掉的错误、什么都不断言的测试。"覆盖面可以更广"
+    和打磨类建议是 次要。
+    如果计划或简报明确强制了某个本评分标准称之为缺陷的东西（一个
+    什么都不断言的测试、逻辑块的逐字重复），那**就是**一个发现——
+    把它报告为 重要，并标注为"计划强制"。计划的作者身份不能给它
+    自己的工作打分；由人类来决定。
+    在列出问题之前，先承认做得好的地方——准确的赞扬能帮实现者
+    信任其余的反馈。
+
+    ## 输出格式
+
+    ### 规格合规性
+
+    - ✅ 符合规格 | ❌ 发现问题：[缺失/多余/理解偏差的内容，
+      附带 file:line 引用]
+    - ⚠️ 无法从 diff 中核实：[你无法仅凭 diff 核实的需求，以及
+      控制者应当检查什么——与你能核实的一切的 ✅/❌ 结论一起报告]
+
+    ### 优点
+    [哪些做得好？要具体。]
+
+    ### 问题
+
+    #### 关键（必须修复）
+    #### 重要（应当修复）
+    #### 次要（锦上添花）
+
+    每个问题：file:line、哪里错了、为什么重要、如何修复（如果不明显）。
+
+    ### 评估
+
+    **任务质量：** [通过 | 需要修复]
+
+    **理由：** [1-2 句技术性评估]
+```
+
+**占位符：**
+- `[模型]` —— 必填：按 SKILL.md 的"模型选择"选审查者模型
+- `[BRIEF_FILE]` —— 必填：任务简报文件（`scripts/task-brief PLAN N`
+  会打印路径；与实现者所用的是同一个文件）
+- `[GLOBAL_CONSTRAINTS]` —— 从计划的"全局约束"一节或规格里逐字抄下的、
+  有约束力的需求：精确的取值、格式、以及组件之间被明确规定的关系
+  （不是流程规则——那些已经在本模板里了）
+- `[REPORT_FILE]` —— 必填：实现者写入其详细报告的那个文件
+- `[BASE_SHA]` —— 本任务之前的提交
+- `[HEAD_SHA]` —— 当前提交
+- `[DIFF_FILE]` —— 必填：控制者写入审查包的那个路径
+  （`scripts/review-package BASE HEAD` 会打印它写入的唯一路径；
+  审查包永远不会进入控制者的上下文）
+
+**审查者返回：** 规格合规性结论（✅/❌/⚠️）、优点、问题
+（关键/重要/次要）、任务质量结论
+
+一次修复分派可以同时处理规格差距和质量发现；修复后的重新审查
+覆盖两个结论。
+</content>

package/skills/using-superpowers/references/copilot-tools.md

@@ -7,7 +7,7 @@
 | `Read`（读取文件） | `view` |
 | `Write`（创建文件） | `create` |
 | `Edit`（编辑文件） | `edit` |
-| `Bash`（运行命令） | `bash` |
+| `Bash`（运行命令） | `bash`（Windows 上常为 `powershell`，见[异步 Shell 会话](#异步-shell-会话)） |
 | `Grep`（搜索文件内容） | `grep` |
 | `Glob`（按名称搜索文件） | `glob` |
 | `Skill` 工具（调用技能） | `skill` |
@@ -31,7 +31,11 @@ Copilot CLI 的 `task` 工具接受 `agent_type` 参数：
 
 ## 异步 Shell 会话
 
-Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有直接等价物：
+Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有直接等价物。
+
+> ⚠️ **shell 工具面随平台和版本而异，下面两套工具名不会同时出现。** 动手之前先确认你这个 build 实际注册的是哪一套 —— 照着不存在的工具名调用，agent 会找不到工具然后即兴发挥。Windows 上常见的是 powershell 那一套（实测 Copilot CLI 1.0.69-1 / Windows 只有 powershell，没有任何 `bash` / `async` 家族工具）。
+
+**Unix / macOS —— bash 一套：**
 
 | 工具 | 用途 |
 |------|---------|
@@ -41,6 +45,32 @@ Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有
 | `stop_bash` | 终止异步会话 |
 | `list_bash` | 列出所有活跃的 shell 会话 |
 
+**Windows —— powershell 一套：**
+
+| 工具 | 用途 |
+|------|---------|
+| `powershell` 配合 `detach: true` | 在后台启动长时间运行的命令（参数名是 `detach`，**不是** `async`） |
+| `read_powershell` | 读取会话的输出 |
+| `stop_powershell` | 终止会话 |
+| `list_powershell` | 列出所有活跃的 shell 会话 |
+| （无 `write_powershell`） | 这一套**没有**向运行中会话发送输入的工具 |
+
+### Windows 上的两个坑
+
+**1. `.sh` 脚本不能裸跑。** powershell 下直接执行 `scripts/start-server.sh` 会报 `The term 'scripts/start-server.sh' is not recognized...`，必须显式走 Git Bash：
+
+```powershell
+& "C:\Program Files\Git\bin\bash.exe" scripts/start-server.sh
+```
+
+**2. `stop_powershell` 停不掉 `detach: true` 启动的进程。** detached 进程要按 PID 停：
+
+```powershell
+Stop-Process -Id <PID>
+```
+
+所以**不要把 `stop_*` 当作 detached 常驻进程的唯一清理路径** —— 必须先拿到真实的 Windows PID（不是 MSYS PID），再 `Stop-Process`。涉及长驻 server 的 skill（如 brainstorming 的视觉伴侣）在 Windows 上尤其要注意这一点。
+
 ## 额外的 Copilot CLI 工具
 
 | 工具 | 用途 |

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -1,26 +0,0 @@
-# 代码质量审查者提示词模板
-
-分派代码质量审查子智能体时使用此模板。
-
-**目的：** 验证实现是否构建良好（整洁、有测试、可维护）
-
-**仅在规格合规性审查通过后才分派。**
-
-```
-Task tool (superpowers:code-reviewer):
-  使用模板 requesting-code-review/code-reviewer.md
-
-  WHAT_WAS_IMPLEMENTED: [来自实现者的报告]
-  PLAN_OR_REQUIREMENTS: [plan-file] 中的任务 N
-  BASE_SHA: [任务开始前的提交]
-  HEAD_SHA: [当前提交]
-  DESCRIPTION: [任务摘要]
-```
-
-**除标准代码质量关注点外，审查者还应检查：**
-- 每个文件是否有单一明确的职责和定义清晰的接口？
-- 各单元是否拆分得足以独立理解和测试？
-- 实现是否遵循了计划中的文件结构？
-- 本次实现是否创建了已经很大的新文件，或显著增大了现有文件？（不要标记已有的文件大小问题——聚焦于本次变更带来的影响。）
-
-**代码审查者返回：** 优点、问题（关键/重要/次要）、评估结论

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -1,61 +0,0 @@
-# 规格合规审查者提示词模板
-
-分派规格合规审查子智能体时使用此模板。
-
-**目的：** 验证实现者是否构建了所要求的内容（不多不少）
-
-```
-Task tool (general-purpose):
-  description: "审查任务 N 的规格合规性"
-  prompt: |
-    你正在审查一个实现是否与其规格匹配。
-
-    ## 要求的内容
-
-    [任务需求的完整文本]
-
-    ## 实现者声称构建了什么
-
-    [来自实现者的报告]
-
-    ## 关键：不要信任报告
-
-    实现者完成得疑似过快。他们的报告可能不完整、
-    不准确或过于乐观。你必须独立验证所有内容。
-
-    **不要：**
-    - 相信他们关于实现内容的说法
-    - 信任他们关于完整性的声明
-    - 接受他们对需求的解读
-
-    **要做的：**
-    - 阅读他们写的实际代码
-    - 逐行对比实际实现和需求
-    - 检查他们声称已实现但实际遗漏的部分
-    - 寻找他们未提及的多余功能
-
-    ## 你的工作
-
-    阅读实现代码并验证：
-
-    **缺失的需求：**
-    - 他们是否实现了所有被要求的内容？
-    - 是否有他们跳过或遗漏的需求？
-    - 是否有他们声称可用但实际未实现的功能？
-
-    **多余/不需要的工作：**
-    - 他们是否构建了未被要求的内容？
-    - 他们是否过度工程化或添加了不必要的功能？
-    - 他们是否添加了规格中没有的"锦上添花"功能？
-
-    **理解偏差：**
-    - 他们是否以不同于预期的方式解读了需求？
-    - 他们是否解决了错误的问题？
-    - 他们是否实现了正确的功能但方式不对？
-
-    **通过阅读代码来验证，而非信任报告。**
-
-    报告：
-    - ✅ 符合规格（如果经过代码检查后一切匹配）
-    - ❌ 发现问题：[具体列出缺失或多余的内容，附带 file:line 引用]
-```