# @chenacc/dsh-agentbridge 中文文档

规范地址：https://npmcn.com/package/%40chenacc/dsh-agentbridge/

版本：0\.4\.3
npm 元数据更新时间：2026-11-08T17:47:51.825Z
中文译文更新时间：2026-11-09T12:58:32.843Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chenacc/dsh-agentbridge
原文对照：https://npmcn.com/package/%40chenacc/dsh-agentbridge/?lang=original
项目主页：https://github.com/chenacc1/agentbridge/tree/main/integrations/dsh-phone#readme
源码仓库：https://github.com/chenacc1/agentbridge

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：288 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-commands ^0\.1\.0-rc\.7
- 首次发布：2026-11-05T16:25:05.135Z
- 最新版本发布：2026-11-08T17:47:51.532Z
- 近 30 天下载量：2679（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

Agent Bridge for DSH Desktop:在一次谈话中运行/手机,将电话控制台与那个精确的活的Agent对齐.

## 安装

```sh
npm install @chenacc/dsh-agentbridge
```

也可以使用：`pnpm add @chenacc/dsh-agentbridge`、`yarn add @chenacc/dsh-agentbridge`、`bun add @chenacc/dsh-agentbridge`

## README

# @chenacc/dsh-agentbridge

[![npm version](https://img.shields.io/npm/v/@chenacc/dsh-agentbridge?color=2f6f7e)](https://www.npmjs.com/package/@chenacc/dsh-agentbridge) [![license](https://img.shields.io/badge/license-MIT-blue)](https://npmcn.com/package/%40chenacc/dsh-agentbridge/LICENSE) [![stars](https://img.shields.io/github/stars/chenacc1/agentbridge?style=social)](https://github.com/chenacc1/agentbridge/stargazers)

AgentBridge 的 DSH Desktop 集成插件。在某个项目会话里执行 `/phone`，把**屏幕上那一条** live Agent 会话接到手机控制台：手机扫码后可以发消息、审批、切换模型、停止任务，桌面与手机看到同一份事件流。

![手机端控制台：扫码后接管的是屏幕上那一条会话](https://npmcn.com/package/%40chenacc/dsh-agentbridge/assets/hero-phone.jpg)

一条命令装进当前 profile：

```powershell
cd "$env:USERPROFILE\.dsh\profiles\desktop"; pnpm add @chenacc/dsh-agentbridge@latest
```

重启 DSH Desktop，在项目会话里输入 `/phone`——二维码默认就是公网地址，手机用流量也能打开。

-   精确绑定当前会话：会话 ID、项目目录、provider / 模型都取自真实会话，不是新建一个"类似的"会话。
-   电脑始终是唯一执行端：凭据和文件访问留在本机，手机只下发命令。

> 觉得有用就给主仓库点个 star：[chenacc1/agentbridge](https://github.com/chenacc1/agentbridge) —— 不影响任何功能。

## 前置条件（重要）

这个插件**只是一个桥接层**，真正的服务端是本机运行的 AgentBridge 桥（默认 `http://127.0.0.1:8787`）。

从 0.2.0 起，桥作为依赖随插件一起安装，**DSH Desktop 启动时插件会自己在后台把桥拉起来**，所以正常情况下你什么都不用敲，重启桌面后直接 `/phone` 就行。

从 0.3.0 起，插件默认还会**自动开一条 Cloudflare 隧道**，把桥映射成一个公网 https 地址——手机用流量、在外地都能扫码打开，不必和电脑连同一个 Wi-Fi。

这一步需要一个叫 `cloudflared` 的小工具（Cloudflare 官方客户端）。**你不用管它**：插件会先在本机找，找不到就自己从 Cloudflare 官方的 GitHub Releases 下载一份到 `~\.agentbridge\bin\cloudflared.exe`（约 55 MB，只下一次，不用管理员权限，删掉那个文件夹就等于卸载）。下载完还会跑一次 `cloudflared --version` 验证，验不过的文件不会留在磁盘上。

想自己装也行，插件优先用系统里已有的那份：

```powershell
winget install --id Cloudflare.cloudflared
```

下载不到（断网、公司代理拦着）也能用，只是退回到"手机和电脑同一个 Wi-Fi"，日志里会说明原因。

只有自动启动失败时（沙箱限制、端口被占、装在非常规位置）才需要手动起桥：

```powershell
npx @chenacc/agentbridge
```

想长期用、或要改配置（项目白名单、远程通道、通知推送）：

```powershell
npm install -g @chenacc/agentbridge
agentbridge phone --agent claude
```

也可以从仓库跑：`git clone` → `npm install` → `npm start`。

桥起不来时 `/phone` 会把上面这些命令直接印在会话里，不会让你对着一个报错发呆。

要求：DSH Desktop 已安装（存在 `%USERPROFILE%\.dsh\profiles\desktop\package.json`），Node.js 22+。

## 安装

通过 DSH Desktop 的插件市场安装，或手动装进当前 profile：

```powershell
cd "$env:USERPROFILE\.dsh\profiles\desktop"
pnpm add @chenacc/dsh-agentbridge@latest
```

然后确认 profile 的 `package.json` 里有：

```json
{
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@chenacc/dsh-agentbridge"] } }
}
```

改完重启 DSH Desktop 才会加载命令。

## 使用

1.  重启 DSH Desktop。几秒后插件会把桥拉起来，再开一条 Cloudflare 隧道，二维码里就是公网地址——手机用 Wi-Fi 或流量都能打开。
2.  在 DSH Desktop 里打开目标项目会话，输入 `/phone`。
3.  会话里出现一次性二维码（5 分钟有效、只能用一次）。用微信扫一扫，进入手机控制台。
4.  配对成功后，下次直接从手机页进入，不必再扫。

关于公网地址，有两件事值得知道：

-   **地址会变。** `trycloudflare.com` 的免费域名每次隧道重建都会换一个，所以别把旧地址当书签。要保持固定地址，去 Cloudflare 建一条命名隧道，然后把 `AGENTBRIDGE_PUBLIC_ORIGIN` 设成自己的域名（这时插件就不再自己起隧道）。
-   **它是对公网开放的。** 所以插件在开隧道时**强制打开访问密钥**，二维码里带着 `?key=…`；拿到二维码的人就能控制这台电脑，别截图外传。

## 配置

| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `AGENTBRIDGE_ORIGIN` | `http://127.0.0.1:8787` | 插件连接的 AgentBridge 地址；桥换了端口时设置它 |
| `AGENTBRIDGE_DATA_DIR` | `~/.agentbridge`（自动启动时） | 桥的会话、配对、密钥与日志目录，不会写进 `~/.dsh` |
| `AGENTBRIDGE_NO_AUTOSTART` | 未设置 | 设为 `1` 关掉"插件加载时自动起桥"，只保留 `/phone` 里的手动提示 |
| `AGENTBRIDGE_REMOTE` | `auto` | 走哪条路径：`auto` / `cloudflare` / `named` / `funnel` / `tailscale` / `zerotier` / `lan` |
| `AGENTBRIDGE_NO_TUNNEL` | 未设置 | 设为 `1` 只用局域网（等价于 `AGENTBRIDGE_REMOTE=lan`） |
| `AGENTBRIDGE_PUBLIC_ORIGIN` | 未设置 | 自己指定对外的地址；设了它插件不再挑路径 |
| `AGENTBRIDGE_TUNNEL_URL` | 未设置 | 直接指定一个隧道域名；主要给测试和"隧道自己管"的人用 |
| `AGENTBRIDGE_CLOUDFLARE_TUNNEL` / `AGENTBRIDGE_CLOUDFLARE_HOSTNAME` | 未设置 | 用已经建好的 Cloudflare 命名隧道 + 自己的域名 |
| `AGENTBRIDGE_CLOUDFLARED` | 自动查找 | 用你自己那份 `cloudflared`；设了它插件既不搜索也不下载 |
| `AGENTBRIDGE_NO_DOWNLOAD` | 未设置 | 设为 `1` 禁止插件自动下载 `cloudflared`（会退回局域网） |
| `AGENTBRIDGE_CLOUDFLARED_URL` | 官方 GitHub Releases | 换一个下载源（内网镜像之类）；下载后照样要过 `--version` 校验 |
| `AGENTBRIDGE_TAILSCALE` / `AGENTBRIDGE_ZEROTIER` | 自动检测 | 手动指定 Tailscale 可执行文件 / ZeroTier 的 IPv4 |
| `AGENTBRIDGE_NOTIFY_IMPORT` | 未设置 | 通知设置（`notify.json`）留在旧数据目录时，指向它一次即可自动迁到 `~/.agentbridge` |

> 通知配置跟着桥的数据目录走。插件把数据目录定在 `~/.agentbridge`，如果你早先用仓库里的 `npm start` 配过通知，那份 `notify.json` 还留在仓库的 `.agentbridge` 下——设一次 `AGENTBRIDGE_NOTIFY_IMPORT=<仓库路径>` 重启即可自动迁过来。桥启动日志会打印 `Notifications: pushplus/clawbot` 或 `Notifications: off — no webhook configured in …`。

路径选择由桥包的 `@chenacc/agentbridge/remote` 负责，CLI 与插件共用同一份实现：同一个顺序、同一把访问密钥。当前实际走的是哪条，看 `/api/health` 的 `remoteProvider` 字段。

变量要设在**真正启动 DSH Desktop 的环境里**（插件读 `process.env`），不是设在跑 bridge 的终端里。

## 卸载

在插件市场里卸载，或：

```powershell
cd "$env:USERPROFILE\.dsh\profiles\desktop"
pnpm remove @chenacc/dsh-agentbridge
```

并把 `dsh.profile.bundles` 里的 `@chenacc/dsh-agentbridge` 删掉，然后重启 DSH Desktop。

## 兼容性

| 版本 | 需要 |
| --- | --- |
| 插件 0.1.x | DSH Desktop（`@deepseek-ai/dsh-commands`、`@deepseek-ai/cordis` 由 DSH 提供）、AgentBridge `0.1.x` |
| 插件 0.2.x | 同上；桥随插件安装并由插件自动拉起 |
| 插件 0.3.x | 同上 + 默认开 Cloudflare 隧道；`cloudflared` 缺了自动下载到 `~/.agentbridge/bin` |

当前版本：插件 `0.3.3` / 桥 `0.1.4`。插件把隧道逻辑交给桥包（`@chenacc/agentbridge/tunnel`），所以 CLI 的 `/phone` 和这里用的是同一份实现、同一条隧道、同一把访问密钥。

插件与 bridge 之间有一份集成版本号握手：bridge 侧要求的最低集成版本比插件旧时，手机端会提示"桌面端集成是旧版"，升级插件即可。

## 许可证

MIT

## 常见问题

### @chenacc/dsh-agentbridge 是什么？

Agent Bridge for DSH Desktop:在一次谈话中运行/手机,将电话控制台与那个精确的活的Agent对齐\.

### 如何安装 @chenacc/dsh-agentbridge？

在项目目录运行 npm install @chenacc/dsh-agentbridge，或使用 pnpm add / yarn add / bun add。

### @chenacc/dsh-agentbridge 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chenacc\_\_dsh-agentbridge 是否存在。

### @chenacc/dsh-agentbridge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chenacc/dsh-agentbridge 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chenacc/dsh-agentbridge 可以商用吗？

@chenacc/dsh-agentbridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chenacc/dsh-agentbridge 的下载量有多少？

根据 npm 官方下载统计，@chenacc/dsh-agentbridge 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,679 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chenacc/dsh-agentbridge 还在维护吗？

最新版本 0\.4\.3 发布于 2026/11/09（今天）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/11/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。