superpowers-for-dsh

Readme

# SuperPowers for DSH

[English](README.en.md) · [功能报告](docs/feature-report.md) · [架构说明](docs/architecture.md) · [UI/UX Pro Max](docs/ui-ux-pro-max.md)

将 `obra/superpowers` 的工程工作流带入 DeepSeek Harness（DSH）：14 个可按需加载的 skills、自动 session bootstrap、DSH 原生计划与协作工具、Windows sandbox 兼容层，以及一个可选的 UI/UX Pro Max 本地设计能力包。

这是一个独立的 DSH bundle，不是 `obra/superpowers` 或 `LayneChai/superpowers-dsh` 的 fork。仓库保留 upstream skill 工作流正文，并自行维护 DSH provider、agent preset、bootstrap、sandbox adapter、UI/UX bridge 和验证体系。

## 当前交付状态

| 组件 | 当前能力 | 状态 |
| --- | --- | --- |
| `superpowers-for-dsh` bundle | Host skill provider、lazy UI/UX Host service | 代码与仓库检查通过 |
| `superpowers-dsh` preset | 14 个 SuperPowers skills、自动 bootstrap、DSH coding-agent 工具、Windows sandbox compatibility | 代码与仓库检查通过；工具运行时可用性取决于 DSH 安装 |
| `superpowers-dsh-uiux` preset | Base preset 能力 + `ui-ux-pro-max` skill + `ui_ux_search` + `ui_ux_generate` | Phase A 代码与 core 测试通过；另有手工 DSH 验收 |
| 独立 MCP server | stdio / Streamable HTTP adapter | 尚未作为当前能力挂载，规划于 Phase B |
| Visual Companion | DSH-only 可视化候选选择 | 尚未作为当前能力挂载，规划于 Phase C |

详细功能范围、架构、安全边界和验收证据见 [功能报告](docs/feature-report.md)。

## 能做什么

### 工程工作流

仓库打包了以下 14 个 skills：

- 需求与设计：`brainstorming`、`writing-plans`；
- 执行与协作：`executing-plans`、`subagent-driven-development`、`dispatching-parallel-agents`；
- 质量与调试：`systematic-debugging`、`test-driven-development`、`verification-before-completion`；
- 代码审查：`requesting-code-review`、`receiving-code-review`；
- Git 与交付：`using-git-worktrees`、`finishing-a-development-branch`；
- Skill 维护与入口规则：`writing-skills`、`using-superpowers`。

Host provider 在运行时发现 `skills/*/SKILL.md`，模型按任务需要加载 skill，而不是把所有正文一次性塞进上下文。

### DSH 原生协作

preset 声明并组合 DSH 的原生能力，包括 plan mode、goal、subagent、workflow、Ralph、todo、background jobs、filesystem、PowerShell 和 Web search。具体 provider 是否安装、是否可用，仍取决于 DSH profile；例如 `subagent_codex` 与 `subagent_claude_code` 在当前 preset 中明确 disabled。SuperPowers 流程负责决定什么时候使用可用工具，不替换 DSH 的执行、权限或取消机制。

### Windows sandbox compatibility

当 session 已处于 `danger-full-access` 时，普通 `pwsh`、`write`、`edit` 等调用不应继续携带 `sandbox_permissions` 或 `justification`。compatibility wrapper 会：

- 从该模式下的模型可见 schema 隐藏这两个字段；
- 在执行前清理旧模型发出的同模式或不完整字段；
- 在低权限模式下保留真实的升级请求，让 DSH approval/policy 正常处理。

### 可选 UI/UX Pro Max

可选 preset 使用固定版本的本地 UI/UX 数据和 Python standard-library runtime，提供：

- domain search：UX、颜色、图表、字体、landing、product、icons 等；
- stack search：React、Next.js、Vue、Svelte、Flutter、SwiftUI 等；
- 确定性 design-system generation；
- upstream repository、revision、skill version、warnings 和 source IDs；
- 受信任 workspace 下的可选持久化与路径隔离。

UI/UX Host core 本身不调用模型，也不联网搜索。它只读取仓库中固定 revision 的 upstream 数据。

## 前置条件

Base preset 需要：

- 一个可运行的 DSH Web profile；
- 能运行本仓库 Node.js scripts 的环境；
- Git（从源码安装时）。

UI/UX preset 另外需要：

- Python 3；
- 无需安装第三方 Python package；
- 项目不会自动安装或升级 Python。

可以先检查：

```powershell
node --version
python --version
```

Windows 下 UI/UX runtime 依次尝试 `python` 和 `py -3`；POSIX 下依次尝试 `python3` 和 `python`。如有需要，可以用 `UI_UX_PRO_MAX_PYTHON` 指定受信任的 Python executable。

## 安装

bundle 与 agent preset 是两个不同层次：bundle 安装到 DSH profile，preset 模板复制到用户的 `.agent-presets` 目录。两步都需要完成。

### 1. 安装 bundle

从 GitHub 安装：

```powershell
npx @deepseek-ai/dsh plugin --profile web add github:Meteor-system/superpowers-for-dsh
```

或从本地 clone 安装：

```powershell
git clone https://github.com/Meteor-system/superpowers-for-dsh.git
npx @deepseek-ai/dsh plugin --profile web add C:\path\to\superpowers-for-dsh
```

确认 bundle 已进入 profile composition：

```powershell
dsh --profile web --dump-config
```

输出中应包含 `superpowers-for-dsh` 和 `ui-ux-pro-max-host`。后者只是 lazy Host service，不会自动把 UI/UX tools 暴露给普通会话。

### 2. 安装 Base preset

在仓库根目录运行：

```powershell
node scripts/install-preset.mjs
```

默认安装到：

```text
%USERPROFILE%\.dsh\.agent-presets\superpowers-dsh
```

已有目录时，安装器默认拒绝覆盖。升级 preset 时使用：

```powershell
node scripts/install-preset.mjs --force
```

`--force` 会先把旧目录重命名为带时间戳的 backup；新安装失败时，安装器会恢复旧目录。

### 3. 可选：安装 UI/UX preset

```powershell
node scripts/install-preset.mjs --variant uiux
```

默认安装到：

```text
%USERPROFILE%\.dsh\.agent-presets\superpowers-dsh-uiux
```

覆盖升级同样使用：

```powershell
node scripts/install-preset.mjs --variant uiux --force
```

### 4. 重启 profile 并创建新会话

preset composition 会被运行中的 DSH 挂载和缓存。安装或更新后：

1. 停止并重新启动原来的 DSH profile；
2. 刷新 DSH Web 页面；
3. 创建新会话；
4. 选择 `SuperPowers for DSH` 或 `SuperPowers for DSH + UI/UX Pro Max`。

旧会话保留创建时的 preset generation，不能用来验证新的 bootstrap、tool catalog 或 model-facing schema。

## 快速验证

在仓库根目录运行：

```powershell
node scripts/verify.mjs
npm test
```

如果安装了 Python 3，还可以运行完整 UI/UX smoke：

```powershell
npm run verify:uiux
```

单独检查生成的 optional preset 是否与 authored contracts 一致：

```powershell
node scripts/build-uiux-preset.mjs --check
```

`4a4f4e6` 实现基线的完整测试包含 97 个测试，覆盖 skill provider、preset installer、sandbox compatibility、UI/UX contracts、Python bridge、上游 parity、取消、超时、路径隔离、provenance 和 generated-preset parity。`npm test` 不会启动 DSH Web；因此它验证仓库实现和 preset 结构，不等同于每个 DSH profile/provider 的端到端验收。UI/UX schema 的手工 DSH 验收记录见 [功能报告](docs/feature-report.md)。

## 使用 Base preset

新会话启动后，bootstrap 会要求模型在行动前检查适用 skill。常见工作流示例：

```text
新功能：brainstorming -> writing-plans -> executing-plans / subagents
Bug：systematic-debugging -> test-driven-development -> verification-before-completion
交付：requesting-code-review -> finishing-a-development-branch
```

DSH 工具映射和平台注意事项位于 [`skills/using-superpowers/references/dsh-tools.md`](skills/using-superpowers/references/dsh-tools.md)。

普通 `pwsh` 调用不需要手工添加 legacy escalation 字段：

```json
{
  "command": "Get-Location",
  "description": "确认当前项目目录",
  "timeoutMs": 30000,
  "workdir": "D:\\Code\\project",
  "run_in_background": false
}
```

## 使用 UI/UX Pro Max

UI/UX skill 要求先通过 `brainstorming` 明确产品、用户、平台、目标和约束，并取得明确确认。之后再搜索证据和生成 design system。

### 1. Domain search

```json
{
  "query": "keyboard focus modal",
  "domain": "ux",
  "max_results": 3,
  "diagnostics": true
}
```

### 2. Stack search

stack search 必须是单独调用，不能和 `domain` 放在同一个参数对象中：

```json
{
  "query": "accessible responsive analytics dashboard",
  "stack": "react",
  "max_results": 3,
  "diagnostics": true
}
```

### 3. Generate

需求稳定后生成确定性的 design system：

```json
{
  "query": "SaaS analytics dashboard for business operators",
  "project_name": "Metrics",
  "format": "markdown",
  "variance": 5,
  "motion": 4,
  "density": 5,
  "persist": false
}
```

`persist` 省略或为 `false` 时，不能传 `page` 或 `force`。需要持久化时，使用受信任的 agent session cwd：

```json
{
  "query": "SaaS analytics dashboard for business operators",
  "project_name": "Metrics",
  "format": "markdown",
  "persist": true,
  "page": "overview",
  "force": false
}
```

不要提供 `output_dir` 或绝对输出路径。DSH adapter 会把受信任的 workspace 传给 core，公开结果只保留 workspace-relative 路径。

### Model-facing schema 约束

`ui_ux_search` 使用三个 `oneOf` 分支：

- 只带 `query`；
- `query` + `domain`；
- `query` + `stack`。

`ui_ux_generate` 使用两个 `oneOf` 分支：

- non-persist：`persist` 省略或为 `false`，没有 `page`/`force`；
- persist：必须为 `persist: true`，此时才能出现 `page`/`force`。

每个分支都使用 `additionalProperties: false`。core 仍会执行第二次输入规范化和范围检查，避免仅依赖模型或 schema。

### 返回结果与 provenance

两个工具都返回相同的 envelope：

```json
{
  "upstream": {
    "repository": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill",
    "revision": "e4f45473691e4b389519ee4bc359a3d6df666c26",
    "skillVersion": "2.13.0"
  },
  "sourceIds": [
    "uiux:..."
  ],
  "warnings": [],
  "result": {}
}
```

必须原样保留 `upstream`、`sourceIds` 和 `warnings`。数据库没有返回 match 时，不要用模型知识伪造 source ID。某些无法映射到具体文件身份的 search 结果可能合法地返回空 `sourceIds`。

## 架构概览

```text
DSH Host
├─ superpowers-for-dsh -> 14-skill provider
└─ ui-ux-pro-max-host -> lazy shared core

Agent scope
├─ superpowers-dsh
│  ├─ bootstrap
│  ├─ sandbox compatibility
│  └─ DSH-native coding tools
└─ superpowers-dsh-uiux
   ├─ Base preset 能力
   ├─ ui-ux-pro-max skill
   ├─ ui_ux_search
   └─ ui_ux_generate
```

关键文件：

| 文件/目录 | 责任 |
| --- | --- |
| `cordis.patch.yml` | 把 skill provider 和 lazy UI/UX Host service 插入 Host composition |
| `lib/index.js` | 发现并加载 14 个 packaged skills |
| `preset/` | Base agent preset、bootstrap、sandbox compatibility |
| `preset-uiux/` | Optional UI/UX skill、tools、contracts 和 prompt |
| `lib/ui-ux-pro-max/` | Contracts、core、Python runtime、Host lifecycle、provenance |
| `third_party/ui-ux-pro-max/` | 固定 upstream 数据、Python runtime、manifest 和 LICENSE |
| `scripts/` | 安装、生成、smoke、upstream sync 和 verification |
| `test/uiux/` | Phase A contracts、runtime、parity、installer 和 preset tests |

更完整的数据流和边界说明见 [架构文档](docs/architecture.md) 与 [功能报告](docs/feature-report.md)。

## 已知限制

- UI/UX core 需要 Python 3，但项目不会自动安装 Python；
- UI/UX tools 只属于 `superpowers-dsh-uiux`，普通 preset 不应出现它们；
- preset 更新后必须重启 profile 并创建新会话；
- 当前 UI/UX 交付是 Phase A：没有独立 MCP server，也没有 Visual Companion；
- raw schema 只使用 DSH 支持的 JSON Schema 子集；数值范围等约束由 runtime normalizer 再次执行；
- Base provider 在 Host 层共享，但 model-facing tools 和 prompt 按 preset 隔离。

## 开发与验证

常用命令：

```powershell
npm test
npm run test:uiux
node scripts/verify.mjs
node scripts/build-uiux-preset.mjs --check
node scripts/smoke-uiux-core.mjs
git diff --check
```

提交前应检查完整 diff，尤其不要无意改写 `skills/` 与 `third_party/ui-ux-pro-max/` 中固定的 upstream 内容。更新 upstream 必须使用显式 revision、重新生成 manifest/hash，并重新执行 parity；部署到 DSH 后还应按安装章节重新做一次 fresh-session 的手工 live 验收。

## 上游、归属与许可证

- SuperPowers skills：[`obra/superpowers`](https://github.com/obra/superpowers)，v6.3.0，commit `b36e082`，MIT；
- UI/UX Pro Max：[`nextlevelbuilder/ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)，revision `e4f45473691e4b389519ee4bc359a3d6df666c26`，skill version `2.13.0`，MIT；
- provider packaging 结构曾参考 [`LayneChai/superpowers-dsh`](https://github.com/LayneChai/superpowers-dsh)，本仓库为独立实现；
- 本仓库维护的 DSH adapter、preset、bridge、文档和验证脚本遵循仓库 MIT license。

完整归属和 redistribution boundary 见 [NOTICE.md](NOTICE.md) 与 [docs/upstream.md](docs/upstream.md)。