dsh-open-in-x

Readme

# dsh-open-in-x

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

在 DeepSeek Harness Web 界面中，把当前会话的工作目录直接交给本机外部应用打开。

支持：

- macOS Finder、Windows 文件资源管理器、Linux 默认文件管理器
- macOS 终端、Windows Terminal、常见 Linux 终端模拟器
- Visual Studio Code
- Cursor
- Windsurf
- Zed
- IntelliJ IDEA
- WebStorm
- PyCharm
- Android Studio

插件会向当前会话顶部工具栏添加“在外部应用中打开”按钮，只展示 DSH Host 所在机器上已安装的应用。这里的“本机”指运行 `dsh web` 的机器；如果浏览器连接的是远程 DSH，应用不会在浏览器所在电脑启动。

## 要求

- Node.js 22.19+ 或 24+
- DeepSeek Harness `0.1.0-rc.6` 或更高的兼容版本
- DSH Web 默认绑定到 `127.0.0.1`

Harness 仍处于 developer preview，Web Client 插件协议可能发生不兼容变化。本插件的公开 Slot 实现针对官方 `0.1.1-rc.2` / 上游提交 `b150a551` 开发，并在本机 DSH `0.1.0-rc.7` 上完成了真实安装和启动冒烟测试。旧版本没有 session header action slot 时，插件会把相同操作加入真实 Workspace 的 `⋯` 菜单；新版本检测到公开 slot 后会自动撤下兼容层。

## 安装

安装 npm 发布版：

```bash
npx @deepseek-ai/dsh plugin --profile web add dsh-open-in-x
npx @deepseek-ai/dsh web
```

从源码构建并安装到 Web profile：

```bash
pnpm install
pnpm run check
npm pack
npx @deepseek-ai/dsh plugin --profile web add ./dsh-open-in-x-0.1.1.tgz
npx @deepseek-ai/dsh web
```

开发时也可以直接安装本地目录：

```bash
npx @deepseek-ai/dsh plugin --profile web add /absolute/path/to/dsh-open-in-x
```

安装后重启 `dsh web`。选择一个已有工作目录的会话，在会话顶部工具栏点击“在外部应用中打开”，再选择 Finder、VS Code 等应用。

卸载：

```bash
npx @deepseek-ai/dsh plugin --profile web remove dsh-open-in-x
```

## 配置

默认启用全部内置 launcher，未安装的应用不会显示。Host 插件支持以下 Cordis 配置：

```yaml
apps:
  - finder
  - terminal
  - vscode
  - cursor
  - windsurf
  - zed
  - idea
  - webstorm
  - pycharm
  - android-studio
allowRemote: false
allowLegacyPaths: false
defaultApp: vscode
quickOpen: true
```

`allowRemote` 默认必须保持 `false`。只有在 DSH 位于带身份认证和 CSRF 防护的可信反向代理之后，并且你明确理解“网页触发 Host GUI 进程”的风险时才应开启。

`quickOpen: true` 且 `defaultApp` 可用时，主按钮会直接在默认应用中打开；旁边的下拉按钮仍可选择其他应用。

应用列表只在 DSH Web 页面加载（包括刷新页面）时检测一次，不会定时检测，也不会在页面重新回到前台时检测。安装或卸载应用后刷新 DSH Web 页面即可更新列表；未安装或当前平台不支持的应用始终不展示。

新式会话操作只向 Host 发送 Session ID，工作目录完全由 Host 的 Session 状态解析。旧版 DSH 的 Workspace 菜单只能提供路径，因此默认由 `allowLegacyPaths: false` 禁止；仅在本机可信环境需要旧版兼容菜单时才应显式开启。

## 工作原理

插件是一个 DSH bundle，同时包含两部分：

- Browser half 优先注册到公开的 `conversation.session.header.actions` list slot，只向 Host 发送当前会话的 `id`；不具备该 slot 的旧版本使用仅面向 Workspace 菜单的兼容适配。
- Host half 在 `ctx.webServer` 注册唯一的 `POST /__dsh/open-in-x` exact route，在宿主机启动选定应用。

当前官方仓外插件没有稳定的运行时 Typert Remote contribution 注册入口，因此这里使用独立 WebServer route；研究依据和版本限制见 [调研文档](docs/research/deepseek-harness-plugin-development.md)。

## 安全边界

- 只接受 JSON POST；请求体上限 8 KiB，schema 严格拒绝额外字段。
- 默认只接受 loopback、same-origin 请求。
- Browser 只能提交固定 app id 和 Session ID，不能提交 executable、argv、shell 文本或 Session 工作目录。
- Host 从 Session header 解析权威 cwd；旧版路径动作独立配置且默认关闭。
- 启动进程使用 argv 数组和 `shell: false`，不会拼接 shell 命令。
- 相同 app/cwd 在短时间内限流，避免重复点击启动大量进程。

## 开发

```bash
pnpm run typecheck
pnpm run test
pnpm run build
pnpm run check
```

`pnpm run check` 执行类型检查、单元/HTTP/客户端交互测试和 Host/Browser 双端构建。GitHub Actions 会在 Ubuntu、macOS、Windows 的 Node.js 22/24 上重复验证，并检查 npm 打包内容。安装包需要提交构建后的 `lib/`，因为 DSH profile 安装不会替插件运行构建。

## 安装故障排查

如果 `dsh plugin add` 报 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`，被拦截的通常是目标 profile 锁文件里已有的近期依赖，并不一定是本插件。添加任何插件都会让 pnpm 重新验证完整 `pnpm-lock.yaml`。

推荐等待错误中最新的 `published at` 时间满 24 小时后，直接重试原安装命令。不要在没有审查依赖变化的情况下运行 `pnpm clean --lockfile` 或批量加入 `minimumReleaseAgeExclude`：前者可能解析到更新、年龄更短的版本，后者会绕过原本的供应链缓冲策略。

`npm warn Unknown user config "electron_mirror"` 是独立的非致命警告。新版 npm 不再接受 `.npmrc` 中的 `electron_mirror`；确认不再依赖该设置后可删除这一行，需要 Electron 镜像的工具应改用其支持的 `ELECTRON_MIRROR` 环境变量。

## License

MIT