dsh2server

配置

唯一必填项

endpoint: 'https://example.com/dsh-api'

endpoint 是服务器 API 的基地址。插件由它推导出 …/ws、…/events、…/inbox（规则见 docs/API.md §2.1）。

它接受单个 URL、URL 列表或逗号分隔字符串，并且每个 URL 的协议（http / https）可以任意混用：

### 常用可选配置

完整列表（含默认值）见 [`cordis.patch.yml`](https://github.com/23J1633/dsh2server/blob/7cfaedba5d7a55d552be650091e19fc16f1b6e77/cordis.patch.yml)。最常改的几个：

| 配置 | 默认 | 说明 |
|---|---|---|
| `key` | `''` | 留空 = 自动生成并保存在本机；填写 = 使用该 key 且不落盘 |
| `keyFile` | `''` | 身份文件路径，默认 `/dsh2server/identity.json` |
| `a2sConfigFile` | `''` | 可选的 A2S 共享配置文件；留空使用系统默认位置 |
| `deviceId` | `''` | 设备聚合 ID；A2S 模式通常自动继承，不需要手填 |
| `authMode` | `hello` | key 的传递方式：`hello` / `header` / `query` |
| `transport` | `auto` | `auto`（先 WebSocket 再回退 HTTP）/ `ws` / `http` |
| `locale` | `system` | 插件设置页与插件状态语言：`system` / `zh-CN` / `en-US` |
| `autoSubscribeSessions` | `running` | 自动推送哪些会话的逐条事件：`none` / `running` / `all` |
| `forwardApprovals` | `false` | 是否把**工具调用审批**转发到服务器等待远程批准 |
| `forwardQuestions` | `true` | 是否把**结构化提问**转发到服务器；关闭后远程会话遇到提问只能回本机处理 |
| `allowRemotePrompt` | `true` | 是否允许远程下发新命令 |
| `allowRemoteControl` | `true` | 是否允许远程中断/暂停/切策略/轮换 key（同时管着权限预设的切换与插件配置的写入） |
| `allowRemoteCommand` | `true` | 是否允许远程执行斜杠命令（如 `/compact`） |
| `allowedCwdPrefixes` | `[]` | 非空时，只有工作目录匹配这些前缀的会话才可见/可控 |
| `logLevel` | `info` | `silent` / `error` / `warn` / `info` / `debug` |

> 配置错误会在**加载阶段**直接失败，并给出精确到字段的错误信息（例如 `transport: must be one of auto | ws | http`）。

---

## 图形化配置（dsh Web GUI）

装好之后，dsh 的网页界面里会**自动多出一个标签页**：

设置 → 插件 → dsh2server

它提供：

| 区域 | 能做什么 |
|---|---|
| 服务器 API 端点 | 独立端点列表，每个 URL 可单独添加、编辑或移除（`http` / `https` 可混用）。**保存后立即生效，无需重启 dsh** |
| 传输方式 | `auto` / `ws` / `http` 下拉（PHP 后端选 `http`） |
| 插件语言 | 自动跟随系统 / 简体中文 / English；保存后立即生效，也可由 A2Switch 统一配置 |
| 本机实例 Key | 指纹展示、`显示` 完整 key、**`复制 Key`** 一键复制、`复制登记命令`（生成可直接执行的 curl）、`轮换 Key` |
| 连接状态 | 每条链路的实时状态（已连接 / 未连接 / 被拒绝）与拒绝原因 |
| 远程权限 | `allowRemotePrompt` / `allowRemoteControl` / `forwardApprovals` 开关 |

语言设置只影响 dsh2server 自己的配置页、提示和上报元数据，不会翻译 DSH 会话正文。显式选择会写入网页设置层；选择“自动跟随系统”时使用浏览器/运行电脑语言。网页层没有显式覆盖时，profile 中的 `zh-CN` / `en-US` 可固定语言；profile 为默认 `system` 时则继续采用 A2Switch 写入的 `agents.dsh.locale`。

### 它是怎么出现的（对使用者完全透明）

标签页是**这个包自带的前端半边**，不是对 dsh 的改动：

- 包在自己的 `package.json` 里声明了 `dsh.client`（`exports["./client"]` → `lib/client.js`），dsh 的**客户端模块系统**会自动扫描已启用的 Loader 条目，把每个声明了 `dsh.client` 的包的浏览器产物送到页面；
- 浏览器半边只往 dsh **公开的插槽** `settings.plugins.tab` 里注册一行（和内置的「插件配置」标签用的是同一个扩展点），并自带样式与数据获取；
- 数据通过本包自己注册在 Connection 共享通道上的 `/api/dsh2server/*` 路由取得——因此天然带有 dsh 的 Host/Origin 校验与浏览器会话认证。

结论：**任何人 `dsh plugin add dsh2server` 之后，打开网页就能看到这个标签页**，不需要改 dsh、不需要额外步骤，也不需要作者本机有什么特殊配置。前端产物零外部依赖（只用 shell 平台表里的 `react`，所以连 `dsh.client.external` 都不用声明，不会因为别人组合里缺某个插件而失败）。

### 配置的优先级

网页里改过的项写入 **`/dsh2server/config.json`**，它**逐键覆盖** `cordis.yml` 里的同名项：

schema 默认值 key、allowedCwdPrefixes 这类部署级/安全级配置不在网页可编辑范围内，仍然只由 cordis.yml 决定。

---

它是怎么出现的（对使用者完全透明）

标签页是这个包自带的前端半边，不是对 dsh 的改动：

• 包在自己的 package.json 里声明了 dsh.client（exports["./client"] → lib/client.js），dsh 的客户端模块系统会自动扫描已启用的 Loader 条目，把每个声明了 dsh.client 的包的浏览器产物送到页面；
• 浏览器半边只往 dsh 公开的插槽 settings.plugins.tab 里注册一行（和内置的「插件配置」标签用的是同一个扩展点），并自带样式与数据获取；
• 数据通过本包自己注册在 Connection 共享通道上的 /api/dsh2server/* 路由取得——因此天然带有 dsh 的 Host/Origin 校验与浏览器会话认证。

结论：任何人 dsh plugin add dsh2server 之后，打开网页就能看到这个标签页，不需要改 dsh、不需要额外步骤，也不需要作者本机有什么特殊配置。前端产物零外部依赖（只用 shell 平台表里的 react，所以连 dsh.client.external 都不用声明，不会因为别人组合里缺某个插件而失败）。

配置的优先级

网页里改过的项写入 /dsh2server/config.json，它逐键覆盖 cordis.yml 里的同名项：

schema 默认值   `key`、`allowedCwdPrefixes` 这类部署级/安全级配置**不在**网页可编辑范围内，仍然只由 `cordis.yml` 决定。

---

### Configuration and UI

The bundle contributes its own Harness settings page for endpoint(s), key, transport, language, reconnect/heartbeat behavior, approval forwarding, file limits, and optional capabilities. Simplified Chinese and English are available; `system` follows the browser/host locale. Saving settings redraws the page and reconnects when required.

Sensitive keys are masked in UI/log output. A2Switch shared settings only fill absent profile fields. Environment variables and explicit profile values win, followed by shared configuration and built-in defaults.