# Superpowers 模式 · 模式说明与如何使用

本文件对应 DSH 内置预设卡片上的「模式说明」与「如何使用」两个面板。
`Superpowers` 是第三方预设，DSH 只为内置的四个预设（标准 / PTC / 极简 /
创造）提供卡片内的帮助按钮，所以这两块内容放在这里。原因与替代方案见
[为什么卡片上没有那两个按钮](#为什么卡片上没有那两个按钮)。

---

## 一、模式说明

新建任务时选择「Superpowers」，然后说明你要做什么、相关文件在哪里、怎样
算完成。这个模式只在这个任务里生效。

### 工作方式

它把 [obra/superpowers](https://github.com/obra/superpowers) 的完整开发
方法论装进一个 DSH 预设：

- **流程约定写在系统提示词里。** `using-superpowers` 的正文作为本模式的
  persona 注入，每次请求都会重新发送。它不会因为上下文压缩、历史裁剪而
  丢失——这是它和一些"会话开始时注入一次"的做法最关键的区别。
- **15 个技能只在本模式可见。** 技能目录由包内的 provider 注册进本预设的
  技能层，其他模式的任务看不到它们，system prompt 里也不会为此多花 token。
- **工具链与标准模式对齐。** 计划模式、子 Agent、工作流、目标、上下文压缩、
  终端、文件读写检索都在，所以这个模式可以独立完成从想法到提交的全过程。

### 五个阶段

| 阶段 | 技能 | 产出 |
| --- | --- | --- |
| 想清楚 | `brainstorming` | 一份你点头过的设计或规格 |
| 写计划 | `writing-plans` | 拆成可独立验证的小任务，每步带测试与命令 |
| 执行 | `subagent-driven-development` / `executing-plans` | 每个任务实现 + 独立评审，或在一个上下文里按台账推进 |
| 排障 | `systematic-debugging` / `test-driven-development` | 先找根因、先写失败测试，再改代码 |
| 收尾 | `verification-before-completion` / `requesting-code-review` / `finishing-a-development-branch` | 有证据的完成声明、合并前评审、干净的分支收尾 |

技能不是必须全用。规则是：**只要有技能明显适用，就先加载它再动手**——
包括在提问、翻代码之前。

### 什么时候选

- 功能开发、缺陷修复、重构这类"要交付代码"的任务。
- 你想让 Agent 先停下来把需求和设计谈清楚，而不是直接开写。
- 任务足够长，需要计划和台账，中途还可能被压缩上下文。
- 你想复盘一次跑歪的会话：`diagnosing-superpowers` 会读磁盘上的会话记录，
  给出 `文件:行号` 级别的证据。

### 什么时候别选

- 和编码无关的问答、资料整理、纯文本处理——用标准模式，省下流程 token。
- 你只想快速改一行、不想走完整流程——用标准模式更直接。
- 实验对照基线——极简模式更合适。

---

## 二、如何使用

新建任务时选择「Superpowers」，然后描述任务。不需要记技能名字：Agent 会
自己按规则加载。你也可以用 `/技能名` 直接点名（例如 `/brainstorming`），
或者直接说"用 TDD 做"。

### 从想法到设计

> 我想给这个 CLI 加一个「导出为 CSV」的功能，但还没想清楚参数怎么设计。先跟我把需求和边界聊清楚，给我两三个方案对比，我确认之后再写代码。

预期产出：一份你确认过的设计（含取舍与边界情况），此阶段**不应**出现生产
代码改动。

### 按计划执行一个功能

> 按刚才确认的设计写一份实施计划，拆成可以单独验证的小任务，每个任务写清
> 要跑哪条测试命令。计划先给我看。

预期产出：一份落盘的计划文件，每个任务都有明确的验证命令与通过标准。确认
后可以说「按计划执行」。

### 修一个 bug（先根因）

> 提交订单后偶尔会出现重复扣款。先定位根因，别急着改；找到之后先写一个能
> 复现的失败测试，再修，最后跑相关测试并说明原因。

预期产出：根因说明、一个先失败后通过的测试、最小修复、测试输出。

### 审查一次改动

> 审查我这次分支的改动，重点看潜在 bug 和测试缺口，指出文件与行号。先不要
> 改文件。

预期产出：带 `文件:行号` 的评审意见，按严重程度排序。

### 并行处理互不相关的任务

> 这三个模块各自升级依赖，互不影响。并行派人处理，最后汇总每个模块改了什么、测试结果如何。

预期产出：每个模块一份独立的改动与测试结果，最后合并成一份汇总。

### 复盘一次跑歪的会话

> 上个会话跑得很慢而且最后没做完。读一下它的会话记录，告诉我到底卡在哪，给出证据。

预期产出：一份带 `文件:行号` 证据的复盘，指出重复劳动、被忽略的计划或没
触发的技能。

---

## 三、为什么卡片上没有那两个按钮

这不是配置问题，是 DSH 当前的设计：内置预设的帮助按钮只对**内置**预设
开放。证据（DSH `0.2.1-alpha.2` 源码）：

- `packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx:115`
  调用 `presetGuide(row.id, builtIn ? 'system' : 'user')`，`:142-147` 只在
  查到帮助内容时才渲染这两个按钮。
- `PresetGuideDialog.tsx:19-24` 是一张写死四个 id 的表；
  `:32-34` 对 `trust !== 'system'` 一律返回 `undefined`。
- `agent-preset-registry/src/display.ts:53-55` 里，`isBuiltInPreset` 要求
  该行**没有**发布 `name`，且 id 在同样的四个键里。

所以第三方预设的卡片只会显示「查看配置」，任何插件都无法把按钮加进去
（`ui-agent-preset` 注册 `settings.section` 时没有声明子插槽，profile 的
patch 也只能覆盖 `config` / `disabled` / `inject` / `intercept` / `isolate`，
无法把某一行指向另一个模块）。

**因此本仓库把这部分内容做成了你现在读的这份文档，并让它随包分发。**
如果你希望官方支持第三方预设自带帮助，可以到 DSH 仓库提 feature request；
在那之前，这份 `docs/guide.zh.md` 就是「模式说明 / 如何使用」的等价物。

---

## 四、相关文档

- [架构说明](architecture.md) —— 这个预设为什么这样组装，隔离是怎么做到的。
- [与插件模式的对比](plugin-vs-preset.md) —— 两种集成方式的取舍。
- [README](../README.md) —— 安装、升级、卸载、自定义，以及与标准预设的固有差异。