xipian1216/dsh-aa-bridge

Agents Anywhere ↔ DeepSeek Harness Bridge

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

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

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

关于 Agents Anywhere

本插件由 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 进程。

本地构建

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

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

本地安装

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

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

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

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

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

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

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

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

GitHub 安装

发布版本后，用户执行：

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 进程后，按包名移除：

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。

验证

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 仍可处理原生问题。