# open-design

> Open Design 注入 dsh 的 profile，走 JSONL stdio 驱动 dsh 转发文本、思考、工具、用量，支持续接。

## 元数据

- 作者: [@nexu-io](https://github.com/nexu-io)
- 仓库: <https://github.com/nexu-io/open-design.git>
- GitHub: [nexu-io/open-design](https://github.com/nexu-io/open-design)
- Star: 88,204
- 主语言: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- 主页: <https://open-design.ai>
- Topics: `agent-skills`, `ai-design`, `byok`, `claude-code-for-design`, `claude-design`, `codex-design`, `coding-agents`, `cursor-design`, `deepseek`, `deepseek-harness`, `design-systems`, `desktop-app`, `dsh`, `dsh-plugin`, `figma-alternative`, `hermes-agent`, `local-first`, `prototyping`, `ui-generator`, `vibe-coding`
- Fork: 10,189
- Open Issues: 815
- 最后推送: 2026-08-17T16:42:41.000Z
- 加入目录: 2026-08-17T00:00:00.000Z

## 安装

```bash
dsh plugin --profile web add github:nexu-io/open-design/packages/dsh-runtime
```

## 百科

## 一句话定位
open-design-runtime 是 Open Design 注入到用户本机 DeepSeek Harness 内的 JSONL stdio 协议适配层，让 Open Design 不存凭据、不下载 dsh，就能直接驱动用户自己安装的官方 `dsh` CLI 完成设计生成任务。

## 核心能力
- 以 `open-design` profile 身份注入到 DeepSeek Harness 中，用 commander 接管启动模式（--probe / --models / --stdio 三选一）
- 通过 stdin/stdout 上的 JSONL 帧把"execute / cancel / session / text / thinking / tool_call / tool_result / usage / result / protocol_error"等消息拼成结构化协议
- 把 Harness 的文本、思考、工具调用、工具结果、token 用量实时转发给宿主，文本折叠忽略空 delta
- 启动期只读探测协议兼容性与模型目录（带 provider、模型名、推理强度选项与默认项），密钥永不写入帧
- 跨进程 cold resume：会话 ID 由 Harness 自身存储，宿主要续接只需在下次 run 提供 `resume_session_id`
- 支持中途取消：在 execute 激活前收到的 cancel 会被记录并在 AbortController 初始化时立刻重放

## 技术实现
- **语言**: TypeScript (ESM)
- **关键依赖**: 
  - `@deepseek-ai/dsh-cordis` 4.0.1（插件容器）
  - `@deepseek-ai/dsh-cmdline` 0.1.0-rc.6（命令行解析）
  - `commander` 15.0.0（CLI 框架）
- **架构模式**: 通过 `cordis.patch.yml` 把 dsh 的 `system-prompt` 改写为 Open Design 化身，并禁用 `hmr`；同时向宿主注册 `open-design-startup` 与 `open-design-runtime` 两个 Cordis 服务，前者定模式、后者驱动会话
- **入口文件**: `packages/dsh-runtime/src/index.ts`（apply）、`packages/dsh-runtime/src/startup.ts`（启动模式解析）、`packages/dsh-runtime/src/protocol.ts`（帧定义）

## 适用场景
已经安装并配置好 DeepSeek Harness 的用户，希望把 dsh 里的模型能力接入 Open Design，让 Open Design 统一管理 prompt、模型切换、会话续接和中途取消，同时仍然把 API Key 留在 dsh 的 Web UI 中。Open Design 不再额外存秘钥，文件由 Harness 直接写到 OD 的当前工程目录，可被 OD 既有的实时预览管道直接消费。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6+ | 由用户本地安装的官方 `dsh` CLI 提供；本插件不附带 |
| Node.js | >=24 | 插件自身运行时（`dsh` 进程内部） |
| 平台 | 跨平台 | 依赖用户本机已装 dsh，README 同时给出 macOS/Linux 与 Windows 的 bootstrap 安装脚本 |
| 原生模块 | 无 | 纯 Node stdio 协议，无 better-sqlite3 / node-pty 等原生依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:nexu-io/open-design
```

## 配置项
本插件对终端用户没有独立配置项；运行期所需的 cwd、prompt、模型、推理强度等参数均由宿主（Open Design 主程序）通过 JSONL 协议逐次下发，插件自身只接受运行模式开关：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 启动模式 | 枚举 | 三个开关互斥：`--probe` 输出协议兼容信息后退出；`--models` 导出模型目录后退出；`--stdio` 进入正式对话循环 | launch 时由宿主决定 |
| 取消请求 | 协议命令 | 收到 `cancel { request_id }` 时立即终止对应请求，已在 pipeline 中的请求会延迟到 execute 激活时重放 | 无 |

## 常见问题
**Q: 必须先安装 DeepSeek Harness 吗？**

A: 是。插件不会下载或安装 dsh 本身，需要用户先用 Open Design 提供的 bootstrap 安装脚本（macOS/Linux：curl … install-dsh.sh；Windows：irm install-dsh.ps1）把官方 dsh 装好并在 Harness 的 Web UI 里配置好模型 API Key。

**Q: 我的 API Key 会保存在 Open Design 里吗？**

A: 不会。Open Design 仅在 dsh 的 Web UI 中以只写方式存放凭据，Open Design 既不读取也不回写 Key 明文；运行时按需让 dsh 自己读取自己配置的秘钥。

**Q: 每个设计任务都会新启一个 dsh 进程吗？**

A: 是。Open Design 每次发起 run 都会启动一个短命的 `dsh --profile open-design --stdio` 进程；Harness 会话存储负责跨进程 cold resume，无需在 CLI 参数里带会话 ID。

**Q: 跑一半想停下来怎么办？**

A: 协议层支持中途取消。宿主发 cancel 命令后会立即 abort；插件在 AbortController 未初始化的窗口期也会保留请求级意图并在 execute 激活时重放。

**Q: 一次进程能同时跑多个任务吗？**

A: 不能。每个 profile 进程恰好接受一个 execute 命令，第二个会被 `DSH_PROFILE_BUSY` 拒绝；要用并发请由宿主侧开多个进程。

**Q: 怎么卸载这个连接组件？**

A: 通过 `od agent setup deepseek-harness` 或 DSH 自带的 `dsh plugin --profile open-design remove` 卸载即可，DSH 自己的安装、凭据、模型配置都不会被改动。

**Q: 生成的文件会留在 Open Design 工程里吗？**

A: 会。Harness 把文件落到 OD 当前的工程工作目录，文件监听和实时预览交给 Open Design 既有的工件管道处理。

**Q: 协议握手失败会怎样？**

A: 探测阶段仅打印一个 JSON 对象失败信息；Open Design 仍把 DeepSeek Harness 留在"已安装 CLI"列表里并显示"需要安装连接组件"，需要用户再次确认才会通过本插件的 dsh 重装。

## 上手难度
进阶 — 用户需要先独立安装与配置好 DeepSeek Harness（含 API Key），并理解 Open Design 不会复制秘钥这件事；理解后只需要让 Open Design 自动发现 dsh 即可使用。

## 已知问题与限制
- 每个 `dsh --profile open-design --stdio` 进程只接受一次 execute 命令，重复发送 command 会被 `DSH_PROFILE_BUSY` 拒绝（src/index.ts:422-431）
- 进程退出有 1 秒保底回退：rc.6 在宿主 stdin 仍打开时可能让 root 释放先于 launcher 的文件 watcher 附着完成，插件会踢一个 `process.exit` 兜底（src/index.ts:124-135）
- Harness 报 blocked / 无 turn_end / 已被 abort 等异常都会被规整为 `DSH_PROFILE_TURN_FAILED` / `DSH_PROFILE_TURN_BLOCKED` / `DSH_PROFILE_MISSING_TURN_END` 错误码，宿主需要在 UI 层提示用户重试
- 插件自身不携带 dsh 可执行文件、Node.js、凭据或 provider 配置，缺少其中任意一项都需要用户在另一侧补齐

---

本文档由 [deepseek-plugin.org](https://deepseek-plugin.org) 自动生成，对应 HTML 页面: [open-design](https://deepseek-plugin.org/plugins/nexu-io/open-design/packages/dsh-runtime)
百度百科由 AI 生成 (模型: `MiniMax-M3`)