# SuperPowers for DSH 功能报告

> 报告范围：当前仓库的 Base bundle、`superpowers-dsh` preset，以及可选的 UI/UX Pro Max Phase A。
>
> 代码基线：本文以已提交的 `4a4f4e6`（完整 SHA：`4a4f4e635baedc1a39e01ea4abf9e51a174b19c2`）为 UI/UX schema 修复的实现基线；文档内容随后独立补充，不改变该实现基线。
>
> 总体结论：仓库内可复现的自动化测试、结构校验和生成文件校验均通过；live DSH 结果另列为带环境和日期的手工验收记录。MCP 与 Visual Companion 尚未作为当前交付能力挂载。

## 1. 执行摘要

SuperPowers for DSH 是一个独立的 DeepSeek Harness（DSH）bundle，将 `obra/superpowers` 的工程工作流适配到 DSH 的 skill、preset、tool、sandbox 和 session 生命周期中。

当前交付由两个层次组成：

- Base bundle：提供 14 个可发现、可按需加载的 SuperPowers skills，以及一个可复制的 coding-agent preset；其中部分可选 provider 是否可用取决于 DSH profile 安装。
- Optional UI/UX bundle：提供固定版本的 UI/UX Pro Max 本地数据、Python core、DSH Host service、两个 scoped model-facing tools，以及 provenance 和安全持久化边界。

设计上，Host 层负责共享能力和生命周期；agent preset 负责只对选定会话暴露的工具与 prompt。这样，安装可选 UI/UX preset 不会把 UI/UX 工具或额外 prompt 注入普通 `superpowers-dsh` 会话。

## 2. 功能状态矩阵

| 能力 | 当前状态 | 交付入口 | 验证方式 |
| --- | --- | --- | --- |
| 14 个 SuperPowers skills | 已实现 | `skills/`、Host skill provider | `node scripts/verify.mjs`、`npm test` |
| 自动 `using-superpowers` bootstrap | 已实现 | `preset/superpowers-bootstrap.mjs` | bootstrap 生成检查、preset 测试 |
| DSH 原生计划、目标、子代理、工作流、Ralph、todo、job 工具 | 已接入 preset（provider 可用性取决于 DSH 安装） | `preset/agent.cordis.yml` | preset 结构与语法检查；不等同于每个工具的 live runtime 验证 |
| Windows sandbox 兼容层 | 已实现 | `preset/superpowers-pwsh-compat.mjs` | `scripts/verify-pwsh-compat.mjs`、集成测试 |
| UI/UX Pro Max 本地搜索 | Phase A 已实现 | `ui_ux_search` | 上游 parity、core 测试；另有手工 live DSH 验收 |
| UI/UX Pro Max 设计系统生成 | Phase A 已实现 | `ui_ux_generate` | 上游 parity、core 测试；另有手工 live DSH 验收 |
| UI/UX provenance 与 source IDs | 已实现 | `lib/ui-ux-pro-max/provenance.js` | contracts/core 测试；live 结果属于手工验收 |
| 受信任 workspace 持久化 | Phase A 已实现 | UI/UX core + DSH session cwd | 路径隔离、序列化、逃逸测试 |
| 独立 MCP server | 未挂载 | 规划中的 Phase B | 不属于当前交付 |
| DSH-only Visual Companion | 未挂载 | 规划中的 Phase C | 不属于当前交付 |

“已实现”表示代码路径已存在；验证方式会区分仓库内可复现的自动化检查与本次维护期间记录的手工 DSH 验收，不表示所有未来规划能力已经可用。

## 3. Base bundle 功能

### 3.1 Skill provider

`lib/index.js` 在 Host 层发现包内 `skills/*/SKILL.md`，解析 frontmatter，并通过 DSH skill registry 注册 provider。provider 支持：

- 列出 14 个 vendored skills；
- 按需读取具体 skill 正文；
- 返回目录型 resource base，便于 skill 使用相对资源；
- 透传取消信号，不把失效或不完整的文件暴露为候选项。

当前包含的 skill 名称为：

`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`、`finishing-a-development-branch`、`using-git-worktrees`、`writing-skills`、`using-superpowers`。

skill 正文来自固定的 `obra/superpowers` v6.3.0（commit `b36e082`）。本仓库保留 upstream 工作流正文，只在 `using-superpowers` 增加 DSH 平台 reference 连接。

### 3.2 Agent preset 与 bootstrap

`preset/agent.cordis.yml` 是可复制的 agent-plane composition，不依赖开发机绝对路径。安装后，用户可以在新会话中选择 `superpowers-dsh`。

`preset/superpowers-bootstrap.mjs` 只注册 system-prompt section，向新会话说明：

- 必须先判断并加载适用 skill；
- Claude Code 概念如何映射到 DSH 原生工具；
- 当前会话的工具和权限边界。

它不拦截 `agent/pre-step`，也不修改 DSH 的 plan mode 或 tool dispatch 生命周期。preset 中的 `subagent_codex` 与 `subagent_claude_code` 行当前明确标记为 `disabled`；这些 provider 需要 DSH profile 额外安装和配置，不能仅凭 preset 文件宣称可运行。

### 3.3 Windows sandbox compatibility

`preset/superpowers-pwsh-compat.mjs` 根据当前 session 的 effective sandbox mode 处理带有 `sandbox_permissions` 与 `justification` 的旧式调用：

- 在 `danger-full-access` 已经生效时，从模型可见 schema 隐藏不必要的升级字段；
- 执行前清理同模式或不完整的 legacy 字段；
- 真正需要更宽权限的请求在低权限 mode 下继续交给 DSH 的 approval/policy 流程；
- 保留原始工具执行器，不绕过 DSH 的权限和取消机制。

## 4. UI/UX Pro Max Phase A

### 4.1 上游固定信息

UI/UX Pro Max 数据和 Python runtime 固定来自：

- Repository：`https://github.com/nextlevelbuilder/ui-ux-pro-max-skill`
- Revision：`e4f45473691e4b389519ee4bc359a3d6df666c26`
- Skill version：`2.13.0`
- Upstream CLI version：`2.5.0`
- Imported source root：`src/ui-ux-pro-max`

仓库将 allowlisted 的 data、Python runtime 和 LICENSE 保存在 `third_party/ui-ux-pro-max/`，并用 manifest 记录版本、来源路径和 SHA-256。vendored upstream 文件不做源代码改写。

Python runtime 只使用标准库；Node 侧通过项目自有的一次一请求 JSON bridge 调用它，不进行 shell interpolation，也不自动安装 Python 或 Python packages。

### 4.2 可选 preset 的组成

`superpowers-dsh-uiux` 在独立 preset 中增加：

- `ui-ux-pro-max` skill：规定 brainstorming、搜索、生成和 provenance 的使用顺序；
- `ui_ux_search`：搜索固定数据目录；
- `ui_ux_generate`：生成确定性的 UI/UX design system；
- `ui-ux-pro-max-host`：lazy Host service，只在首次调用 UI/UX 能力时构造 Python core；
- `ui-ux-pro-max:bootstrap`：提醒模型保留 upstream revision 与 source IDs，并明确当前没有 Visual Companion。

普通 `superpowers-dsh` preset 不注册上述两个 UI/UX tools，也不加载 UI/UX prompt section。

### 4.3 搜索契约

`ui_ux_search` 的返回值统一包裹为：

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

参数的模型可见 schema 使用 DSH 支持的 `oneOf` 表达三种互斥形态：

1. `query`，不带 selector；
2. `query` + `domain`；
3. `query` + `stack`。

每个分支使用 `additionalProperties: false`，所以 `domain` 与 `stack` 不能在同一次调用中混用。其他参数为：

- `max_results`：运行时限制为 1–20；
- `diagnostics`：boolean；
- `domain`：`style`、`color`、`chart`、`landing`、`product`、`ux`、`typography`、`icons`、`gsap`、`react`、`web`、`google-fonts`；
- `stack`：固定 manifest 中声明的 React、Vue、Svelte、SwiftUI、Flutter 等 stack 名称。

Node core 会再次执行输入规范化，因此 schema 校验不是唯一防线。domain search 与 stack search 分别映射到 upstream 的 `search` 和 `search_stack` 操作。

### 4.4 生成契约

`ui_ux_generate` 支持：

- `query`；
- `project_name`；
- `format`：`ascii` 或 `markdown`；
- `variance`、`motion`、`density`：运行时限制为 1–10；
- `persist`；
- 受约束的 `page` 与 `force`。

模型可见 schema 使用两个 `oneOf` 分支：

- non-persist 分支：`persist` 可省略或为 `false`，不暴露 `page`/`force`；
- persist 分支：要求 `persist: true`，才暴露 `page`/`force`。

持久化不接受模型提供的任意 `output_dir` 或绝对路径。DSH adapter 使用受信任的 agent session cwd，core 会 realpath、检查 containment，并将公开结果中的路径改写为 workspace-relative、forward-slash 形式。持久化生成按序列化队列执行，避免并发写入冲突。

### 4.5 Provenance 与 source IDs

每个 search/generate 响应都保留 upstream repository、revision、skill version，并返回 warnings 数组。source ID 由 upstream revision、源文件标识和结果身份经过 canonical JSON + SHA-256 计算，格式为：

```text
uiux:<64 位小写十六进制字符串>
```

source IDs 是证据身份，不是模型推断。搜索结果如果没有可定位的 `file` 字段，合法地可能返回空 `sourceIds`；这不应被填充为猜测值。设计系统生成则根据 `source_identities` 和 motion identity 映射到固定源文件。

### 4.6 根因与修复

此前暴露出的两个错误是：

- search 请求被序列化为同时包含 `domain` 和 `stack`，upstream 以 `domain and stack are mutually exclusive` 拒绝；
- generate 请求在 `persist:false` 时仍带有 `page`/`force`，upstream 以 `page and force require persist` 拒绝。

根因不是 upstream 数据，而是 model-facing tool schema 只列出可选字段，没有把互斥和条件依赖表达给模型及其 provider serializer；runtime normalizer 只能在请求已经生成后做第二次拦截。

修复内容：

- `searchParameters` 改为三个带 `additionalProperties:false` 的 `oneOf` 分支，分别表达无 selector、domain selector、stack selector；
- `generateParameters` 改为 non-persist 与 `persist:true` 两个分支，用 `const` 约束持久化条件；
- `preset-uiux/ui-ux-pro-max-contracts.mjs` 由 canonical contracts 重新生成，避免 authored/generated drift；
- contracts、preset parity 和生成脚本测试增加合法/非法边界用例；
- 保留 Node core normalizer 作为第二道防线，继续拒绝缺少 query、越界数字和不安全持久化输入。

`oneOf` 改善了 provider 和模型看到的工具契约，但不能保证模型永远不生成 malformed arguments；因此 runtime normalizer 和错误码仍然是必要的安全边界。

## 5. 架构与数据流

```text
DSH host composition
├─ superpowers-for-dsh provider
│  └─ lib/index.js -> 14 个 skills
└─ ui-ux-pro-max-host
   └─ lazy uiUxProMax service

agent preset
├─ superpowers bootstrap / sandbox compatibility
└─ optional uiux preset
   ├─ ui-ux-pro-max skill provider
   ├─ ui_ux_search
   └─ ui_ux_generate

ui_ux_search / ui_ux_generate
        │
        ▼
Node contracts + normalizer
        │
        ▼
shared UI/UX core
        │
        ▼
one-request JSON bridge
        │
        ▼
pinned Python runtime + local data
        │
        ▼
provenance envelope -> DSH tool result
```

边界职责如下：

| 层 | 主要文件 | 责任 |
| --- | --- | --- |
| Bundle provider | `lib/index.js`、`cordis.patch.yml` | 让 skills 进入 Host registry |
| Base preset | `preset/agent.cordis.yml` | 组合基础 agent 工具和 prompt |
| Sandbox adapter | `preset/superpowers-pwsh-compat.mjs` | 按 effective mode 过滤 legacy escalation 字段 |
| UI/UX Host | `lib/ui-ux-pro-max/host.js` | lazy 构造并关闭共享 core |
| UI/UX core | `lib/ui-ux-pro-max/core.js` | 规范化、调用 runtime、串行化持久化、包装结果 |
| Python runtime | `lib/ui-ux-pro-max/python-runtime.js` | interpreter discovery、超时、取消、输出限制、子进程回收 |
| Contracts | `lib/ui-ux-pro-max/contracts.js` | model-facing schema 与第二层输入校验 |
| Provenance | `lib/ui-ux-pro-max/provenance.js` | canonical JSON、source IDs、envelope |
| Optional preset | `preset-uiux/` | scoped UI/UX skill、tools、contracts 和 prompt |
| Pinned upstream | `third_party/ui-ux-pro-max/` | 固定数据、runtime、许可证和 manifest |

## 6. 安全性与可靠性边界

当前实现明确限制以下风险：

- 不执行模型提供的任意 shell command；
- 不让模型指定任意持久化目录或绝对输出路径；
- 不把 Cordis context、session、process handle 或 live runtime object 穿过 core 边界；
- 限制 bridge 输入、stdout、stderr、超时和子进程生命周期；
- 取消请求会终止并回收 Python child process；
- core close 是幂等的，并等待持久化队列与运行中的 child process 收敛；
- upstream 错误、协议错误、超时、取消、输出超限、关闭后调用和路径逃逸使用稳定的 UIUX error code；
- HTTP/MCP 尚未作为当前交付能力暴露，因此本报告不宣称其认证或远程部署能力。

## 7. 安装与运行要求

### Base bundle

1. 在 DSH profile 中安装 bundle。
2. 从仓库根目录安装 `superpowers-dsh` preset。
3. 重启 profile，刷新 DSH Web，并在新会话中选择 preset。

安装脚本默认写入 `%USERPROFILE%\\.dsh\\.agent-presets\\superpowers-dsh`。已有目录时默认拒绝覆盖；`--force` 会先创建带时间戳的 backup。

### Optional UI/UX

在仓库根目录额外运行：

```powershell
node scripts/install-preset.mjs --variant uiux
python --version
node scripts/smoke-uiux-core.mjs
```

然后重启 profile，并在新会话中选择 `superpowers-dsh-uiux`。修改或重新安装 preset 后，旧会话仍保留原来的 preset generation，不能用旧会话判断新 schema 是否生效。

## 8. 验证与验收证据

### 8.1 仓库内可复现的自动化检查

以下检查以 `4a4f4e6` 为实现基线，在本文工作树中执行；它们不启动 DSH Web，也不声称覆盖每个 profile 的工具 provider 可用性：

| 命令/检查 | 结果 |
| --- | --- |
| `npm test` | 97 个测试通过，0 失败 |
| `node scripts/verify.mjs` | `14` skills、optional UI/UX tools、`presetPortable: true`、`syntax: true` |
| `node scripts/build-uiux-preset.mjs --check` | 生成文件无 drift |
| `node scripts/smoke-uiux-core.mjs` | exit 0；revision 为 `e4f45473691e4b389519ee4bc359a3d6df666c26`，UX/React 各返回 2 条 |
| `git diff --check` | 无 whitespace error |

`test/uiux/contracts.test.mjs` 和 `test/uiux/preset-tools.test.mjs` 会在本地检查 model-facing `oneOf`/`const` 合同、generated preset parity，以及以下非法组合：

- `ui_ux_search({query, domain, stack})`；
- `ui_ux_generate({query, page})`；
- `ui_ux_generate({query, persist:false, force:true})`。

这些是仓库内的 schema matcher/contract 测试，不是 DSH Web 的端到端运行时测试。

### 8.2 手工 DSH 验收记录（非自动化 artifact）

以下记录来自 2026-08-29 的维护会话，不由 `npm test` 或仓库脚本自动重放，也没有把 DSH session transcript 作为仓库 artifact 提交：

- 环境：Windows，现有 DSH Web `http://127.0.0.1:3080`，`web` profile；重启进程后创建 fresh UI/UX session；
- request header：实际出现 `ui_ux_search` 的 3 分支 `oneOf` 和 `ui_ux_generate` 的 2 分支 `oneOf`；
- search：显式发送 `{"query":"keyboard focus modal","domain":"ux"}`，工具成功返回 pinned revision；
- generate：显式发送 `project_name:"Metrics"`、`format:"markdown"`、`variance:5`、`motion:4`、`density:5`、`persist:false`，未带 `page`/`force`，工具成功返回 design system 和 6 个 source IDs。

这项手工记录证明当时重启后的 DSH profile 能消费新 preset schema；它不替代可复现的仓库测试，也不代表当前运行中的旧 session 会自动刷新。需要重新验证 live 行为时，应按安装章节重启 profile 并创建新会话。

## 9. 当前限制与后续方向

### 当前限制

- UI/UX core 需要本机可发现的 Python 3；项目不会自动安装 Python 或 Python packages；
- UI/UX 能力只在 `superpowers-dsh-uiux` preset 中可见；
- preset 变化需要重启 profile 并创建新会话才能观察到新的 model-facing schema；
- `variance`、`motion`、`density` 的数值范围由 runtime normalizer 保证，raw schema 只表达 integer 类型；
- 当前没有 MCP server 或 Visual Companion，因此不应在使用说明中把它们当作已挂载能力。

### 后续方向

- Phase B：在共享 core 之上增加独立 MCP adapter 和传输层，并保持与 DSH adapter 相同的 provenance 与安全边界；
- Phase C：增加 DSH-only Visual Companion 和 selection event contract；
- upstream 升级必须重新审计 commit、license、数据文件、parity fixtures、schema、安装和 live DSH 验收。

## 10. 许可证与归属

- `obra/superpowers` skill 内容：MIT，v6.3.0，commit `b36e082`；
- UI/UX Pro Max vendored runtime：固定 revision `e4f45473691e4b389519ee4bc359a3d6df666c26`，遵循其 upstream MIT 条款；
- 本仓库维护的 adapter、preset、bridge、文档和验证脚本：遵循本仓库 MIT license；
- Google Fonts 与 Phosphor Icons 在 upstream 中以 catalog metadata 形式存在，本集成不重新分发字体二进制或 icon package。

详细归属见 [NOTICE.md](../NOTICE.md) 和 [docs/upstream.md](upstream.md)。架构细节见 [docs/architecture.md](architecture.md)，UI/UX 操作说明见 [docs/ui-ux-pro-max.md](ui-ux-pro-max.md)。

## 11. 最终结论

当前交付已经覆盖“工程 skill 适配 + DSH preset + Windows sandbox 兼容 + 可选 UI/UX Phase A”这一范围。核心实现具备：

- 可安装、可复制、可隔离的 preset 结构；
- upstream 固定版本和可追溯 provenance；
- model-facing schema 与 runtime normalizer 的双层约束；
- workspace containment、取消、超时和资源回收；
- 可复现的仓库自动化测试，以及一份单独标注环境和日期的手工 DSH 验收记录。

仓库测试结果不等于所有 DSH provider 的端到端可用性证明；profile 中未安装的 provider 仍保持 disabled 或不可用状态。

在使用或发布时，应把 Base 能力、UI/UX Phase A 能力和未挂载的 Phase B/C 计划明确区分。