@nevermindzzt/dsh-manager-plugin

Readme

# @nevermindzzt/dsh-manager-plugin

![Version](https://img.shields.io/badge/version-v0.2.3-blue)
![Protocol](https://img.shields.io/badge/dsh--manager%20Protocol-v1-6f42c1)
![License](https://img.shields.io/badge/license-MIT-green)

本版本使用 DSH `0.1.2-rc.1` 提供的 `ctx.settings.installSection()` API，不再导入已移除的 `settingsNamespace` 或 `installSettingsSection` 顶层导出。
## 0.2.3 transport and relay optimization

- 移除私有证书、TLS fingerprint 和证书 pinning；
- manager 使用单一 HTTP upstream 端口；
- 可信内网可直接使用 `http://manager:port`；
- 公网 HTTPS/WSS 由 Cloudflare Tunnel 或其他反向代理终止，manager upstream 仍使用 HTTP；
- DSH 0.1.2-rc.1 startup URL 只在内存中保存，绝不写入 plugin state 或日志；
- 首个 manager 标记的根请求使用 startup token，随后通过 Cookie 使用干净 URL；
- WebSocket tunnel 会转发浏览器 Cookie；
- 对浏览器支持 gzip 的请求保留 DSH gzip 响应，避免在 Agent WebSocket 上传输未压缩静态资源；
- 与支持 `proxy.binary-response-v1` 的 manager 使用二进制响应帧，避免 HTTP 响应 body 再次 Base64 编码。

## 架构

```text
浏览器
  ↓ HTTP / WebSocket（或外部代理终止后的 HTTPS / WSS）
dsh-manager 单一 HTTP 端口
  ↓ HTTP / WS Agent Protocol v1
dsh-manager-plugin
  ↓ 本地 dsh HTTP / WebSocket
当前 dsh 实例
```

插件只能代理当前 dsh 实例，不提供任意 shell 或 launcher 生命周期命令。

## 能力

- 使用首次配对码完成一次性注册；后续连接只使用 Agent Token；
- HTTP/HTTPS enrollment（HTTPS 由外部代理提供）；
- WS/WSS Agent 长连接（WSS 由外部代理提供）；
- HTTP 请求反向代理；
- WebSocket 双向代理；
- settings.host、plugin.config、`dsh.web.bootstrap-v1` 和 `proxy.binary-response-v1` 能力声明；
- Agent Token 本地持久化；
- pairing code 刷新不会使已有 Agent Token 失效；
- 不支持任意 shell 和远程生命周期命令。

## 安装

```powershell
dsh plugin --profile web add @nevermindzzt/dsh-manager-plugin@0.2.3
```

安装后重启 dsh：

```powershell
dsh web
```

## dsh 设置

进入：

```text
设置 → 插件 → 插件配置 → dsh-manager
```

配置项：启用 dsh-manager 直连、Manager URL、首次配对码、Agent 名称和实例 ID。没有 TLS fingerprint 配置项。保存后插件会重新建立连接。

## Manager URL

可信内网：

```text
http://manager.example.com:10090
```

通过 HTTPS 反向代理：

```text
https://manager.example.com
```

HTTPS 由 Node.js 系统 CA 校验；插件不接受私有证书 fingerprint，也不会关闭证书校验。

## 环境变量

```text
DSH_MANAGER_URL=http://manager.example.com:10090
DSH_MANAGER_PAIRING_CODE=one-time-code
DSH_MANAGER_NAME=linux-dsh
DSH_MANAGER_INSTANCE_ID=default
```

未配置 `DSH_MANAGER_URL` 时插件保持禁用。

## 本地凭证

默认状态文件：

```text
~/.dsh/manager-agent.json
```

保存内容包括 Agent ID、Agent Token、manager URL、Agent 名称和实例 ID。startup URL/token 不会保存。

## DSH 0.1.2-rc.1 bootstrap

DSH Web UI 只接受启动时打印的 `GET /?token=...`，成功后颁发 Cookie 并重定向到 `/`。插件通过 `ctx.connection.authenticatedUrl()` 得到启动 URL，但只把它保存在当前进程内存中：

1. manager 对新的 `/dsh/<session>/` 根请求发送 `bootstrap:true`；
2. 插件才访问内存中的 startup URL；
3. DSH 的 303 和 Set-Cookie 返回 manager；
4. 后续请求使用浏览器 Cookie；
5. manager WebSocket open 请求携带浏览器 Cookie，插件转发到本地 DSH WebSocket。

## 安全边界

- Agent Token 不提交到 Git；
- manager 只保存 Token Hash；
- plain HTTP 不提供传输加密，只用于可信网络；
- 公网必须使用外部 HTTPS/WSS 反向代理；
- 插件只代理当前 dsh Web 服务；
- startup token 不持久化、不写入日志；
- 不接受 manager 下发任意 shell。

## 开发与验证

```powershell
npm install
npm test
```

测试覆盖 HTTP manager transport、enrollment 生命周期、DSH startup bootstrap、Set-Cookie、gzip 响应保留、二进制 HTTP 响应帧、HTTP proxy 和 authenticated WebSocket Cookie forwarding。

## 相关项目

- [dsh-manager](https://github.com/NevermindZZT/dsh-manager)
- [dsh-launcher](https://github.com/NevermindZZT/dsh-launcher)
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)

[MIT](LICENSE)