dsh-superpowers

Readme

# dsh-superpowers

[![Gitee 仓库](https://img.shields.io/badge/Gitee-tang--yongtao%2Fdsh--superpowers-c71d23?logo=gitee)](https://gitee.com/tang-yongtao/dsh-superpowers)
[![GitHub 仓库](https://img.shields.io/badge/GitHub-TangYT%2Fdsh--superpowers-181717?logo=github)](https://github.com/TangYT/dsh-superpowers)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![上游版本](https://img.shields.io/badge/upstream-superpowers%20v6.3.0-8A2BE2)](https://github.com/obra/superpowers)

**DeepSeek Harness（DSH）移植版 [obra/superpowers](https://github.com/obra/superpowers)**——一套 agentic 技能框架与软件开发方法论，让 AI 编码代理在动手之前先想清楚：头脑风暴 → 写计划 → 子代理执行 → TDD → 系统化调试 → 代码评审 → 收尾合并，全程有技能约束质量。

移植严格遵循上游自带的[移植指南](https://github.com/obra/superpowers/blob/main/docs/porting-to-a-new-harness.md)：**整个集成 = 技能文件（原样搬运）+ 工具映射 + 会话启动引导注入**。

## ✨ 功能特性

- **14 个开箱即用的技能**，会话启动即自动注入技能目录，模型按需调用
- **会话启动引导（bootstrap）**：每个会话的系统提示自动注入 `<EXTREMELY_IMPORTANT>` 包裹的技能使用规则——模型在任何回复前先检查是否有匹配技能，这是上游定义的"唯一必需"的集成点
- **DSH 原生工具映射**：技能的动作语言（派发子代理、建 todo、跑 shell、进 plan mode……）翻译为 DSH 工具（`subagent`/`subagent_fork`、`todo_write`、`pwsh`/`bash`、`skill`、`exit_plan_mode`、`remlab_*` 等）
- **零依赖、热更新**：纯 Node 内置模块实现；改技能正文下次加载即生效，无需重启
- **一键同步上游**：`npm run sync` 从 pin 定的上游版本重新拉取技能

### 技能清单

| 技能 | 触发场景 |
|---|---|
| `brainstorming` | 任何创造性工作前：澄清意图、需求与设计 |
| `writing-plans` | 有需求/规格时，动手写代码前制定实施计划 |
| `executing-plans` | 在独立会话中执行书面实施计划，带评审检查点 |
| `subagent-driven-development` | 每个任务派发全新实施子代理 + 任务评审 + 全分支评审 |
| `test-driven-development` | 实现任何功能/修 bug 前：红-绿-重构 |
| `systematic-debugging` | 遇任何 bug/测试失败时先根因分析再提修复 |
| `requesting-code-review` | 完成任务/合并前请评审验证 |
| `receiving-code-review` | 收到评审意见后如何核实与回应 |
| `using-git-worktrees` | 需要隔离工作区时用 git worktree |
| `dispatching-parallel-agents` | 2+ 个无共享状态的独立任务并行派发 |
| `verification-before-completion` | 声称完成前必须跑验证命令拿证据 |
| `finishing-a-development-branch` | 实现完成后如何集成（合入/PR/cleanup） |
| `writing-skills` | 编写/修改/验证新技能（元技能） |
| `using-superpowers` | 会话开始时如何发现与调用技能（随 bootstrap 注入） |

## 📦 安装

```sh
# 从 Gitee 安装（推荐；需 pnpm 与 git 可用）
dsh plugin --profile <profile> add git+https://gitee.com/tang-yongtao/dsh-superpowers.git

# 从 GitHub 安装（镜像仓库）
dsh plugin --profile <profile> add git+https://github.com/TangYT/dsh-superpowers.git

# 本地开发：链接安装（改 index.js / skills/ 后无需重新安装）
dsh plugin --profile <profile> add link:<本仓库路径>

# 卸载
dsh plugin --profile <profile> remove dsh-superpowers
```

安装后**重启 `dsh web`**（宿主重启才生效）。生效标志：启动日志出现两行 `dsh-superpowers: ...`，新会话的技能目录包含上述 14 个技能，系统提示出现 `You have superpowers.` 引导段。

## 🚀 使用

技能面向模型自动触发，无需记命令：

1. **自然语言触发（推荐）**：直接说"帮我头脑风暴一个新功能"→ 模型自动调用 `brainstorming`；"这个 bug 查下根因"→ `systematic-debugging`；"写个实施计划"→ `writing-plans`。模型会宣布 `Using [技能名] to [目的]`，界面出现 `Skill` 工具调用卡片（可点开查看加载的正文）。
2. **斜杠命令（显式调用）**：输入框输入 `/`，命令菜单列出全部技能（如 `/brainstorming`），选中或手打发送即注入该技能全文；名字用裸 kebab-case（`/brainstorming`，不是 `/superpowers:brainstorming`）。
3. **列出技能**：问"你现在有哪些技能？"。
4. **跳过技能**：用户指令优先——"不用头脑风暴，直接改"即可绕过。

## ⚙️ 配置

编辑 profile 中该插件的行配置（bundle patch 的 `config`）：

```yaml
config:
  bootstrap: false   # 关闭会话启动注入（保留技能 provider）
```

系统提示每请求约多 5–6KB 前缀，介意 token 开销时可关闭 bootstrap。

## 📁 目录结构

```
├── index.js             # 插件主体：技能 provider + bootstrap 系统提示章节
├── cordis.patch.yml     # bundle patch（经 dsh plugin add 由 loader 应用）
├── package.json         # dsh.bundle / dsh.engines 声明
├── skills/              # 14 个技能 bundle（正文与上游逐字一致）
│   └── using-superpowers/references/dsh-tools.md   # DSH 工具映射（本移植新增）
├── scripts/sync.mjs     # 从上游 pin 版本同步技能（tarball，单请求，无 API 限流）
├── test/smoke.mjs       # 冒烟测试（含真实 Cordis 上下文注入校验）
├── NOTICE               # 上游归因与 pin 版本说明
└── LICENSE              # MIT
```

## 🛠 开发与测试

```sh
npm test        # 冒烟测试：provider 契约 + bootstrap 契约 + patch 形状 + 真实 Cordis 上下文
npm run sync    # 重新拉取上游技能（默认 v6.3.0，改 scripts/sync.mjs 的 UPSTREAM_REF 升级）
```

冒烟测试会把插件放进**真实 `@deepseek-ai/cordis` Context** 里运行，注入校验与生产一致。同步脚本镜像上游 `skills/` 树并自动恢复本移植自有的两处改动（`dsh-tools.md` 与 Platform Adaptation 行）。

## 🔄 与上游同步

上游 [obra/superpowers](https://github.com/obra/superpowers) 会持续更新。升级步骤：

1. 修改 `scripts/sync.mjs` 中的 `UPSTREAM_REF` 为新版本 tag；
2. `npm run sync`；
3. `npm test` 全绿后提交发布。

## ❓ 常见问题

- **重启后新会话看不到技能？** 技能是模型面向的（注入模型上下文），GUI 无技能面板。新会话里问"你现在有哪些技能？"即可验证；若确认缺失，检查插件是否装进了当前 profile（微信/lark 等渠道会话属于其他 profile，需分别安装）。
- **brainstorming 的视觉伴侣？** `skills/brainstorming/scripts/` 下的本地 Web UI 原样保留但属可选；其 bash 脚本在 Windows 上需 WSL 或远端 Linux（如 remote-lab 绑定的服务器），纯文本头脑风暴流程不依赖它。
- **项目/用户技能重名？** DSH 按 rank 解析：项目(100/200)、用户(400/500) 技能优先于 bundled(600)，本地覆盖为预期行为。

## 🤝 贡献

欢迎 Issue 与 PR。提交前请运行 `npm test` 确保全部通过；对技能内容的修改请优先提交上游 [obra/superpowers](https://github.com/obra/superpowers)，本仓库只做移植层（bootstrap/provider/工具映射）与同步。

## 📄 License 与归因

[MIT](LICENSE)。技能内容版权归 [Jesse Vincent (obra)](https://github.com/obra/superpowers)（MIT），本仓库按上游移植指南原样搬运并以 `NOTICE` 记录 pin 版本（v6.3.0）与移植层改动范围。