@agents-anywhere/dsh-bridge

Readme

# Agents Anywhere ↔ DeepSeek Harness Bridge

`@agents-anywhere/dsh-bridge` 是一个独立的 DSH Web bundle，同时提供 host SDK 服务和 Web 状态入口。Agents Anywhere Connector 连接已经运行的 `dsh web`，两端使用同一个 DSH 进程和同一个实时 Agent。

```text
Agents Anywhere Connector → DshBridgeClient → DSH Web 插件 → DSH Services
DSH Browser                                      ↗
```

插件不启动第二个 DSH 进程，不需要 `aa` profile，也不依赖 `@deepseek-ai/dsh-session-control`。

## 关于 Agents Anywhere

本插件由 [Agents Anywhere](https://github.com/anywhere-labs/Agents-Anywhere) 项目提供并维护，是 Agents Anywhere Connector 对接 DeepSeek Harness 的配套 Runtime Bridge。Agents Anywhere 让用户通过 Web 或移动端查看和管理运行在自己设备上的编程 Agent Session；本插件负责把 DSH 的 Session、Timeline、审批和运行时控制能力提供给 Agents Anywhere，代码和 DSH 运行环境仍保留在用户自己的设备上。

## 版本兼容性

| Bridge 版本 | DSH 版本 | 状态 |
| --- | --- | --- |
| `v0.2.x` | `0.1.0-rc.7` | 当前维护基线 |
| `v0.1.0` | `0.1.0-rc.6` | 保留给 rc.6 用户 |

两个版本不承诺交叉兼容。安装前可用 `dsh --version` 确认 DSH 版本；rc.7 用户应固定安装 `v0.2.0`。

## 功能

- 通过有版本的 JSON-RPC API 暴露 Session、Turn、Timeline、模型、权限、命令、取消和交互能力。
- Connector 与浏览器共享 DSH Web 进程中的 Session 日志、Agent registry 和操作队列。
- 插件创建或恢复的 Agent 支持切换模型与推理强度；借用 Desktop 已有 Agent 时只接受相同模型的幂等选择，实际变更会明确返回 `UNSUPPORTED_OPERATION`。
- 权限选择通过 DSH `permissionPresets` 写入真实 Session，owned 与 borrowed Agent 使用同一条持久化路径。
- AA 创建 Session 时会按 canonical cwd 创建或复用 DSH Workspace，并将 Session 幂等登记到该 Workspace；历史未分组的 `aa-*` Session 会在 Bridge 启动时安全回填。
- Session 名册携带 DSH Desktop 可见性：本地归档、尚未开始 turn 的空白会话和 subagent 会话在 AA 中进入 Archived，普通会话进入 Active。
- 写操作按 Session 串行执行，并使用稳定的 client message ID 处理重试。
- Connector 断开后 DSH Web 与实时 Session 继续运行，Connector 可以重新连接。
- Bridge 通知失败只记录为同步告警，不会撤销已经接受的 DSH 操作或终止 DSH Web。
- SDK 端点只绑定 `127.0.0.1`；随机认证令牌保存在权限为 `0600` 的端点文件中。

DSH Session 日志仍是对话历史的唯一持久真源。插件不支持跨主机连接，也不允许多个 Connector 同时连接同一个 DSH Web 进程。

## 本地构建

```bash
cd /absolute/path/to/aa-plugin
corepack enable
pnpm install
pnpm verify
```

构建后的 `lib/` 是 Git 分发产物，需要和源码一起提交。安装 Git 依赖时不会在用户机器上执行构建脚本。

## 本地安装

普通 `dsh web` 只需安装到承载 Web 的 profile，例如 `web`：

```bash
dsh plugin --profile web add /absolute/path/to/aa-plugin
dsh web
```

DSH Desktop 使用相同的插件包，不需要 Desktop 专用构建，也不需要插件访问 Desktop/Electron 私有接口。先在 Desktop 中切换到一个可运行 Web 的当前 profile，然后在该 profile 的专用终端安装；当前 profile 为 `web` 时执行：

```bash
dsh plugin --profile web add /absolute/path/to/aa-plugin
```

不要同时在两个使用相同 `DSH_HOME` 的 DSH Web/Desktop 进程中启动 Bridge。一个 `DSH_HOME` 只允许一个存活的 endpoint owner；第二个进程会明确报错，已确认失效的旧 descriptor 会在启动时自动回收。

插件启动后会在以下位置写入 Connector 发现文件：

```text
$DSH_HOME/agents-anywhere/bridge/endpoint.json
```

未设置 `DSH_HOME` 时使用 `~/.dsh`。端点端口和认证令牌由插件生成，不需要手工填写。

## GitHub 安装

发布版本后，用户执行：

```bash
dsh plugin --profile web add github:xipian1216/dsh-aa-bridge#v0.2.0
dsh web
```

固定 tag 或 commit 可以避免上游更新导致未审查代码在下次安装时变化。

如果 Desktop 当前使用的不是 `web`，把命令中的 profile 名替换为 Desktop 当前 profile。插件只需要安装到实际承载 Web 的那个 profile，不需要再安装到 `aa` profile。

停止对应的 DSH Web/Desktop 进程后，按包名移除：

```bash
dsh plugin --profile web remove @agents-anywhere/dsh-bridge
```

## Agents Anywhere 配置

先启动 `dsh web`，再在 Agents Anywhere 中配置 DeepSeek Harness：

| 配置项 | 建议值 |
| --- | --- |
| DSH home | 留空；只有 Web 使用自定义 `DSH_HOME` 时才填写相同的绝对路径 |
| `startupTimeoutMs` | `30000` |
| `requestTimeoutMs` | `60000` |
| `maxRestartAttempts` | `3` |
| `restartBackoffMs` | `1000` |

不再填写 DSH executable、profile、环境变量、shutdown timeout 或 kill grace。Connector 不拥有 `dsh web` 进程，因此停止 Connector 不会关闭 Web。

## 验证

```bash
pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run
```

真实会话验证由维护者启动 DSH Web 和 Agents Anywhere Connector 后执行。

## 限制

- 仅支持同一机器、同一操作系统用户。
- 一次只接受一个 Connector 连接。
- 同一个 `DSH_HOME` 同时只允许一个 Bridge endpoint owner；需要并行启动多个 DSH Web 时必须使用不同的 `DSH_HOME`。
- 不支持跨主机共识、网络分区接管或多个 DSH 进程合并同一 Session 日志。
- 当前协议不支持图片和普通文件附件。
- DSH rc.7 没有公开 Desktop live Agent 的 canonical model-selection handle，因此 borrowed Session 无法从插件切换 provider、model 或 reasoning effort；插件会拒绝变化值，不会回显虚假成功。Desktop 完成下一次请求后，AA 会从真实 `request/header` 读取其有效选择。
- DSH Web 的当前选中 Session 是浏览器本地状态，Host bridge 不会暴露空白占位会话；空白会话开始第一个 turn 后才进入 AA Active。
- AA 当前不会根据后续的 `hidden=false` 自动取消已有归档；已在 AA 中归档的普通会话需要手动取消归档一次。
- 多客户端 user-question 镜像只在目标 DSH 提供 observer 扩展时启用；普通 Web 仍可处理原生问题。