SuperPowers for DSH

English · 功能报告 · 架构说明 · UI/UX Pro Max

将 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 和验证体系。

当前交付状态

详细功能范围、架构、安全边界和验收证据见 功能报告。

能做什么

工程工作流

仓库打包了以下 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。

可以先检查：

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 安装：

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

或从本地 clone 安装：

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：

dsh --profile web --dump-config

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

2. 安装 Base preset

在仓库根目录运行：

node scripts/install-preset.mjs

默认安装到：

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

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

node scripts/install-preset.mjs --force

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

3. 可选：安装 UI/UX preset

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

默认安装到：

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

覆盖升级同样使用：

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。

快速验证

在仓库根目录运行：

node scripts/verify.mjs
npm test

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

npm run verify:uiux

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

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 验收记录见 功能报告。

使用 Base preset

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

新功能：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。

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

{
  "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

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

2. Stack search

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

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

3. Generate

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

{
  "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：

{
  "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：

{
  "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。

架构概览

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

关键文件：

更完整的数据流和边界说明见 架构文档 与 功能报告。

已知限制

• 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 隔离。

开发与验证

常用命令：

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，v6.3.0，commit b36e082，MIT；
• UI/UX Pro Max：nextlevelbuilder/ui-ux-pro-max-skill，revision e4f45473691e4b389519ee4bc359a3d6df666c26，skill version 2.13.0，MIT；
• provider packaging 结构曾参考 LayneChai/superpowers-dsh，本仓库为独立实现；
• 本仓库维护的 DSH adapter、preset、bridge、文档和验证脚本遵循仓库 MIT license。

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