superpowers-zh 1.1.0 → 1.1.2

package/docs/assets/RECORDING-GUIDE.md

@@ -0,0 +1,47 @@
+# GIF 录制指南
+
+## 方式一：macOS 录屏（推荐，最真实）
+
+### 准备
+1. 终端字体调到 18pt+，背景用深色
+2. 准备一个测试项目目录 `~/demo-project`
+3. 确保 superpowers-zh 已安装
+
+### 录制步骤
+1. **Cmd+Shift+5** 打开录屏，选择录制区域（只录终端窗口）
+2. 执行以下操作：
+
+```bash
+# 第一步：安装（3秒）
+cd ~/demo-project
+npx superpowers-zh
+
+# 第二步：给 AI 提需求（等 AI 回复）
+claude "给用户模块加一个批量导出功能"
+```
+
+3. 等 AI 输出中文的头脑风暴内容（澄清问题 + 方案），录到这里就可以停了
+4. 停止录屏
+
+### 转 GIF
+```bash
+# mov 转 gif（用 ffmpeg）
+ffmpeg -i recording.mov -vf "fps=10,scale=700:-1:flags=lanczos" -c:v gif docs/assets/demo.gif
+
+# 如果太大（>2MB），降低 fps 或尺寸
+ffmpeg -i recording.mov -vf "fps=8,scale=600:-1:flags=lanczos" -c:v gif docs/assets/demo.gif
+```
+
+## 方式二：VHS 脚本（模拟输入，输出需要手动编排）
+
+```bash
+cd /Users/yx/work/wenzhang/superpowers-zh
+vhs docs/assets/demo.tape
+```
+
+注意：VHS 只模拟键盘输入，AI 输出需要在 tape 文件中用 Type 模拟。
+
+## 最终效果要求
+- 时长：15-20 秒
+- 文件大小：< 2MB
+- 关键帧：能看到 AI 用中文输出设计方案/澄清问题

package/docs/assets/demo.tape

@@ -0,0 +1,99 @@
+Output docs/assets/demo.gif
+Set FontSize 16
+Set Width 900
+Set Height 520
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 40ms
+Set Padding 20
+
+# Scene 1: Install superpowers-zh
+Type "cd ~/my-project && npx superpowers-zh"
+Enter
+Sleep 1s
+
+# Simulate install output
+Set TypingSpeed 0ms
+Type@0ms ""
+Sleep 300ms
+
+Ctrl+L
+
+Set TypingSpeed 0ms
+
+# Simulated install output line by line
+Type "  superpowers-zh v1.2.0"
+Enter
+Sleep 200ms
+Type "  Detected: Claude Code"
+Enter
+Sleep 200ms
+Type "  Installing 20 skills to .claude/skills/ ..."
+Enter
+Sleep 500ms
+Type "  ✓ 14 translated skills installed"
+Enter
+Sleep 200ms
+Type "  ✓ 6 Chinese-specific skills installed"
+Enter
+Sleep 300ms
+Type "  Done! Your AI assistant now has superpowers."
+Enter
+Enter
+Sleep 1.5s
+
+# Scene 2: User gives a task
+Set TypingSpeed 40ms
+Type `claude "给用户模块加一个批量导出功能"`
+Enter
+Sleep 1.5s
+
+# Simulate AI brainstorming response
+Set TypingSpeed 15ms
+Type "  Using brainstorming to design this feature"
+Enter
+Enter
+Sleep 300ms
+Type "  在开始实现之前，我需要了解几个关键问题："
+Enter
+Enter
+Sleep 200ms
+Type "  1. 导出格式是 CSV 还是 Excel？是否需要支持多种格式？"
+Enter
+Sleep 200ms
+Type "  2. 预计数据量多大？超过 1 万条需要考虑异步处理"
+Enter
+Sleep 200ms
+Type "  3. 有权限要求吗？比如只允许管理员导出"
+Enter
+Sleep 200ms
+Type "  4. 需要支持筛选条件导出吗？"
+Enter
+Enter
+Sleep 500ms
+Type "  基于常见场景，我初步提出 2 个方案："
+Enter
+Enter
+Sleep 300ms
+Type "  方案 A：同步导出（适合 < 5000 条）"
+Enter
+Type "    - 直接流式写入 Response，用户点击即下载"
+Enter
+Type "    - 优点：实现简单，无需额外基础设施"
+Enter
+Type "    - 缺点：大数据量会超时"
+Enter
+Enter
+Sleep 300ms
+Type "  方案 B：异步任务 + 下载链接（适合大数据量）"
+Enter
+Type "    - 后台 Worker 生成文件，完成后通知用户下载"
+Enter
+Type "    - 优点：不阻塞请求，支持任意数据量"
+Enter
+Type "    - 缺点：需要消息队列 + 对象存储"
+Enter
+Enter
+Sleep 500ms
+Type "  请确认需求细节，我再给出详细设计。"
+Enter
+Sleep 3s

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
-  "name": "superpowers",
-  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.0.0",
+  "name": "superpowers-zh",
+  "description": "AI 编程超能力中文版 — TDD、调试、代码审查等经过实战验证的工作方法论",
+  "version": "1.1.1",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-zh",
-  "version": "1.1.0",
-  "description": "AI 编程超能力中文版 — 14 个翻译 + 5 个中国特色原创 skills",
+  "version": "1.1.2",
+  "description": "AI 编程超能力中文增强版 — superpowers（99k+ ⭐）完整汉化 + 6 个中国原创 skills，支持 OpenClaw / Claude Code / Cursor / Windsurf / Kiro / Gemini CLI 等 14 款工具",
   "type": "module",
   "main": ".opencode/plugins/superpowers.js",
   "bin": {
@@ -19,6 +19,7 @@
     ".opencode/",
     "GEMINI.md",
     "gemini-extension.json",
+    "docs/",
     "README.md",
     "LICENSE"
   ],
@@ -29,8 +30,14 @@
     "codex",
     "gemini",
     "kiro",
+    "deerflow",
     "trae",
     "antigravity",
+    "openclaw",
+    "windsurf",
+    "aider",
+    "opencode",
+    "qwen",
     "vscode",
     "copilot",
     "ai-coding",

package/skills/brainstorming/SKILL.md

@@ -27,7 +27,7 @@ description: "在任何创造性工作之前必须使用此技能——创建功
 4. **提出 2-3 种方案** — 附带权衡分析和你的推荐
 5. **展示设计** — 按复杂度分节展示，每节展示后获得用户批准
 6. **编写设计文档** — 保存到 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` 并 commit
-7. **规格审查循环** — 调度 spec-document-reviewer 子代理，提供精心组织的审查上下文（绝不是你的会话历史）；修复问题后重新调度直到通过（最多 3 次迭代，之后交给人工处理）
+7. **规格自检** — 快速内联检查占位符、矛盾、模糊性、范围（详见下方）
 8. **用户审查书面规格** — 在继续之前请用户审查规格文件
 9. **过渡到实现** — 调用 writing-plans 技能创建实现计划
 
@@ -43,8 +43,7 @@ digraph brainstorming {
     "分节展示设计" [shape=box];
     "用户批准设计?" [shape=diamond];
     "编写设计文档" [shape=box];
-    "规格审查循环" [shape=box];
-    "规格审查通过?" [shape=diamond];
+    "规格自检\n（内联修复）" [shape=box];
     "用户审查规格?" [shape=diamond];
     "调用 writing-plans 技能" [shape=doublecircle];
 
@@ -57,10 +56,8 @@ digraph brainstorming {
     "分节展示设计" -> "用户批准设计?";
     "用户批准设计?" -> "分节展示设计" [label="否，修改"];
     "用户批准设计?" -> "编写设计文档" [label="是"];
-    "编写设计文档" -> "规格审查循环";
-    "规格审查循环" -> "规格审查通过?";
-    "规格审查通过?" -> "规格审查循环" [label="发现问题，\n修复后重新调度"];
-    "规格审查通过?" -> "用户审查规格?" [label="通过"];
+    "编写设计文档" -> "规格自检\n（内联修复）";
+    "规格自检\n（内联修复）" -> "用户审查规格?";
     "用户审查规格?" -> "编写设计文档" [label="要求修改"];
     "用户审查规格?" -> "调用 writing-plans 技能" [label="批准"];
 }
@@ -116,19 +113,22 @@ digraph brainstorming {
 - 如果可用，使用 elements-of-style:writing-clearly-and-concisely 技能
 - 将设计文档 commit 到 git
 
-**规格审查循环：**
-编写规格文档后：
+**规格自检：**
+编写规格文档后，以全新的视角审视它：
 
-1. 调度 spec-document-reviewer 子代理（参见 spec-document-reviewer-prompt.md）
-2. 如果发现问题：修复，重新调度，重复直到通过
-3. 如果循环超过 3 次迭代，交给人工指导
+1. **占位符扫描：** 有没有"待定"、"TODO"、未完成的章节或模糊的需求？修复它们。
+2. **内部一致性：** 各章节之间有矛盾吗？架构和功能描述匹配吗？
+3. **范围检查：** 这是否聚焦到可以用一个实现计划覆盖，还是需要进一步拆分？
+4. **模糊性检查：** 有没有需求可以被两种方式理解？如果有，选择一种并明确写出来。
+
+发现问题就直接内联修复。无需重新审查——修好继续推进。
 
 **用户审查关卡：**
-规格审查循环通过后，请用户在继续之前审查书面规格：
+规格自检完成后，请用户在继续之前审查书面规格：
 
 > "规格已编写并 commit 到 `<path>`。请审查一下，如果在我们开始编写实现计划之前你想做任何修改，请告诉我。"
 
-等待用户回复。如果他们要求修改，做出修改并重新运行规格审查循环。只有在用户批准后才继续。
+等待用户回复。如果他们要求修改，做出修改并重新运行规格自检。只有在用户批准后才继续。
 
 **实现：**
 

package/skills/workflow-runner/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: workflow-runner
+description: "在 Claude Code / OpenClaw / Cursor 中直接运行 agency-orchestrator YAML 工作流——无需 API key，使用当前会话的 LLM 作为执行引擎。当用户提供 .yaml 工作流文件或要求多角色协作完成任务时触发。"
+---
+
+# 工作流执行器：在 AI 工具内运行多角色编排
+
+直接在当前会话中执行 agency-orchestrator 的 YAML 工作流，无需配置 API key。当前 LLM 就是执行引擎——依次扮演每个角色完成任务。
+
+## 适用场景
+
+- 用户提供了一个 `.yaml` 工作流文件（如 `运行 workflows/story-creation.yaml`）
+- 用户要求多个角色协作完成任务（如"用产品经理和架构师一起评审这个 PRD"）
+- 用户安装了 `agency-agents-zh` 并希望直接在 AI 工具内编排多角色
+
+## 执行流程（5 步）
+
+按以下顺序执行，不要跳步：
+
+### 第 1 步：解析工作流
+
+用 Read 工具读取用户指定的 YAML 文件，提取以下字段：
+
+```yaml
+name: "工作流名称"
+agents_dir: "agency-agents-zh"    # 角色定义目录
+inputs:                            # 输入变量
+  - name: xxx
+    required: true/false
+    default: "默认值"
+steps:                             # 执行步骤
+  - id: step_id
+    role: "category/agent-name"    # 角色路径
+    task: "任务描述 {{变量}}"       # 支持模板变量
+    output: variable_name          # 输出变量名
+    depends_on: [other_step_id]    # 依赖关系
+```
+
+**忽略 `llm`、`concurrency`、`timeout`、`retry` 配置**——Skill 模式使用当前会话的 LLM，这些字段仅用于 CLI 模式。
+
+**定位角色目录**：用 Bash `test -d` 按以下顺序检查，用第一个存在的：
+1. 当前工作目录下的 `{agents_dir}/`（如 `./agency-agents-zh/`）
+2. `../{agents_dir}/`（上级目录）
+3. 相对于 YAML 文件所在目录的 `{agents_dir}/`
+4. `node_modules/agency-agents-zh/`
+
+如果全部找不到，**停止执行**并提示用户：
+```
+找不到角色目录。请先安装：
+  git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
+  或：npm install agency-agents-zh
+```
+
+### 第 2 步：收集输入
+
+- 对每个 `required: true` 的输入，检查用户消息中是否已提供值
+- 未提供的必填输入：**立即向用户询问**，不要猜测或用空值
+- 有 `default` 的可选输入：使用默认值
+- 无默认值的可选输入：设为空字符串
+
+### 第 3 步：构建执行顺序
+
+根据 `depends_on` 进行拓扑排序，将步骤分成多个层级：
+
+- **无 depends_on 的步骤** → 第 1 层
+- **depends_on 全部在第 N 层或之前的步骤** → 第 N+1 层
+- **同一层内的步骤**互不依赖，可并行
+
+在回复中展示执行计划：
+```
+执行计划（共 N 步）：
+  第 1 层: [step_id] — 角色名
+  第 2 层: [step_a, step_b] — 并行
+  第 3 层: [step_id] — 角色名
+```
+
+### 第 4 步：逐层执行
+
+对每一层：
+
+#### 4a. 预读角色文件
+
+用 Read 工具读取该层所有步骤的角色 `.md` 文件：`{角色目录}/{role}.md`
+
+从文件中提取：
+- **角色名**：frontmatter 中的 `name` 字段
+- **角色 system prompt**：第二个 `---` 之后的全部 markdown 内容
+
+#### 4b. 渲染 task 模板
+
+将 task 中的 `{{变量名}}` 替换为：
+- 来自 inputs 的用户输入值
+- 来自前序步骤 output 的结果文本
+
+#### 4c. 执行
+
+**单步骤层**：直接在主会话中扮演该角色执行。格式：
+
+```
+### Step N/Total: step_id（角色名）
+
+[以该角色身份完成 task，使用角色的专业知识和沟通风格]
+```
+
+**多步骤层（并行）**：使用 Agent 工具为每个步骤启动子代理。每个子代理的 prompt 必须包含：
+- 角色文件的**完整文本内容**（不是路径——子代理可能无法读文件）
+- 渲染后的 task 文本
+- 指令："以上是你的角色定义，请以该角色身份完成以下任务，直接输出结果"
+
+#### 4d. 保存输出到上下文
+
+如果 step 有 `output` 字段，将该步骤的输出文本存入变量上下文，供后续步骤的 `{{变量}}` 使用。
+
+### 第 5 步：保存结果并展示
+
+用 Write 工具将结果保存到文件：
+
+```
+.ao-output/{工作流名称}-{YYYY-MM-DD}/
+├── steps/
+│   ├── 1-{step_id}.md       # 每步的输出
+│   ├── 2-{step_id}.md
+│   └── ...
+├── summary.md                # 最后一步的完整输出（最终成果）
+└── metadata.json             # 基本元数据
+```
+
+metadata.json 格式：
+```json
+{
+  "name": "工作流名称",
+  "date": "2026-03-22",
+  "success": true,
+  "steps": [
+    {"id": "step_id", "role": "category/agent", "status": "completed"},
+    ...
+  ]
+}
+```
+
+执行完毕后，向用户展示：
+1. 最终成果（summary.md 的内容）
+2. 文件保存位置
+3. 执行了几个步骤
+
+## 重要规则
+
+<HARD-GATE>
+- 每个步骤都必须真正扮演对应角色，使用该角色的专业知识和沟通风格，不能泛泛回答
+- 角色切换必须明确——每步开始时标注角色名
+- 不要跳过步骤或合并步骤，严格按 DAG 层级顺序执行
+- 如果角色文件找不到，告知用户并建议安装 agency-agents-zh
+- 不要在没有读取角色 .md 文件的情况下执行步骤——必须先 Read 再执行
+</HARD-GATE>
+
+## 没有 YAML 文件时的快捷模式
+
+如果用户没有指定 YAML 文件，但描述了需要多角色协作的任务：
+
+1. 根据用户描述，**自动生成** YAML 工作流定义
+2. 展示给用户确认
+3. 确认后按上述流程执行
+
+示例：
+- 用户说"帮我用叙事学家和心理学家写个故事" → 生成 story-creation 类似的工作流
+- 用户说"让产品经理和架构师评审这个 PRD" → 生成 product-review 类似的工作流
+
+## 故障处理
+
+- **角色文件不存在**：提示用户运行 `ao init` 或 `npm install agency-agents-zh`
+- **模板变量未定义**：检查上下文，如果是必填输入则向用户询问
+- **步骤执行失败**：标记该步骤为失败，跳过所有依赖它的下游步骤，继续执行其他独立步骤

package/skills/writing-plans/SKILL.md

@@ -103,26 +103,33 @@ git commit -m "feat: add specific feature"
 ```
 ````
 
+## 禁止占位符
+
+每个步骤都必须包含工程师需要的实际内容。以下是**计划缺陷**——绝不要写出来：
+- "待定"、"TODO"、"后续实现"、"补充细节"
+- "添加适当的错误处理" / "添加验证" / "处理边界情况"
+- "为上述代码编写测试"（没有实际测试代码）
+- "类似任务 N"（重复代码——工程师可能不按顺序阅读任务）
+- 只描述做什么而不展示怎么做的步骤（代码步骤必须有代码块）
+- 引用了未在任何任务中定义的类型、函数或方法
+
 ## 注意事项
 - 始终使用精确的文件路径
-- 计划中包含完整代码（而非"添加验证"）
+- 每个步骤都包含完整代码——如果步骤涉及代码变更，就展示代码
 - 精确的命令和预期输出
-- 使用 @ 语法引用相关技能
 - DRY、YAGNI、TDD、频繁 commit
 
-## 计划审查循环
+## 自检
+
+编写完整计划后，以全新视角审视规格并对照检查计划。这是你自己执行的检查清单——不是子代理调度。
+
+**1. 规格覆盖度：** 浏览规格中的每个章节/需求。你能指出实现它的任务吗？列出所有遗漏。
 
-编写完整计划后：
+**2. 占位符扫描：** 搜索计划中的红旗——上方"禁止占位符"章节中的任何模式。修复它们。
 
-1. 调度一个 plan-document-reviewer 子代理（参见 plan-document-reviewer-prompt.md），提供精心组织的审查上下文——绝不是你的会话历史。这样可以让审查员专注于计划本身，而非你的思考过程。
-   - 提供：计划文档路径、规格文档路径
-2. 如果发现问题：修复问题，重新调度审查员审查整个计划
-3. 如果通过：进入执行交接
+**3. 类型一致性：** 后续任务中使用的类型、方法签名和属性名是否与前面任务中定义的一致？任务 3 中叫 `clearLayers()` 但任务 7 中叫 `clearFullLayers()` 就是 bug。
 
-**审查循环指南：**
-- 编写计划的同一个代理负责修复（保留上下文）
-- 如果循环超过 3 次迭代，交给人工指导
-- 审查员是顾问性质的——如果你认为反馈不正确，可以解释你的理由
+如果发现问题，直接内联修复。无需重新审查——修好继续推进。如果发现规格中的需求没有对应任务，就添加任务。
 
 ## 执行交接
 

package/skills/writing-skills/SKILL.md

@@ -92,7 +92,7 @@ skills/
 ## SKILL.md 结构
 
 **Frontmatter（YAML）：**
-- 仅支持两个字段：`name` 和 `description`
+- 两个必需字段：`name` 和 `description`（完整支持字段参见 [agentskills.io/specification](https://agentskills.io/specification)）
 - 总计最多 1024 字符
 - `name`：只使用字母、数字和连字符（不要用括号、特殊字符）
 - `description`：第三人称，仅描述何时使用（不是做什么）
@@ -603,7 +603,7 @@ helper1、helper2、step3、pattern4
 
 **绿色阶段 - 编写最小技能：**
 - [ ] 名称只使用字母、数字、连字符（无括号/特殊字符）
-- [ ] YAML frontmatter 仅包含 name 和 description（最多 1024 字符）
+- [ ] YAML frontmatter 包含必需的 `name` 和 `description` 字段（最多 1024 字符；参见 [spec](https://agentskills.io/specification)）
 - [ ] 描述以"Use when..."开头并包含具体的触发条件/症状
 - [ ] 描述用第三人称
 - [ ] 全文包含搜索关键词（错误、症状、工具）