前言¶
智能体跑在云端，手里没有本地环境，就没法在你自己的机器上列目录、读 git 日志、跑一条构建命令。传统做法是自己写一个常驻服务，再想办法处理鉴权、超时、输出截断和断线重连，工程量不小；用 ssh 直连又要逐台维护密钥和端口映射。
dsh-pc-bridge 把这套东西压成一个 DSH 插件：在电脑上开一个只监听回环的小 HTTP 桥，对端（例如云端的 QQ 机器人）可以 ping 这台电脑，也能按需执行 shell 命令；可选同时维持一条 ssh 反向隧道，让远端在自己那台机器的回环上就能访问到这台电脑的桥。插件由 QIC-9821 维护，分类是「联网工具」，许可 MIT，仓库里也没有第三方运行时依赖。
下面介绍的事实来自 GitHub README 与
package.json。星标数以 skillhub.cn 目录页为准，当前为 0。
这是个什么插件¶
一句话：它把「这台机器能不能被远端调用」变成两个工具调用（pc_ping / pc_exec）和一个 curl 接口，而不是把一台电脑直接暴露到公网。
- Host 桥：
node:http服务，提供POST /exec、GET|POST /ping，每个请求都要带x-pc-secret头。 - 工具：Agent 侧可调用
pc_ping（探活）与pc_exec（执行命令），默认打http://127.0.0.1:18790。 - 隧道管理器：
tunnelEnabled: true时守着ssh -N -R ...，断了按 5/10/30/60 秒退避重连；远端 sshd 残留占用端口时先fuser -k再重试。 - CLI：仓库自带
pcctl，pcctl ping、pcctl exec -- "hostname"可以在终端里直接调桥，不依赖 Harness。
安装与启用¶
README 给了三种安装方式，选一即可。
# npm（推荐）
dsh plugin add dsh-pc-bridge
# 直接从 GitHub tag 装
dsh plugin add github:QIC-9821/dsh-pc-bridge#v0.1.0
# 本地目录（开发时）
dsh plugin add /absolute/path/to/dsh-pc-bridge
也可以在插件管理器里把本目录当 bundle 安装。要求 Node.js ≥ 22，没有任何第三方运行时依赖；package.json 里版本是 0.1.1。
安装后在 Harness 设置里找到「电脑执行桥」，按下面的键配置。
- id: dsh-pc-bridge
name: 'dsh-pc-bridge'
config:
role: both
listenHost: 127.0.0.1
listenPort: 18790
tunnelEnabled: true
sshHost: 203.0.113.10
sshUser: dsh
sshKeyPath: C:/Users/me/.ssh/id_ed25519
role 有 host（只开桥）、client（只注册工具/隧道）、both（全开）三种取值，默认 both。
配置要点¶
默认值全部来自 README 的配置表，别改的两条先说：listenHost 默认 127.0.0.1，README 明确写了不要改成 0.0.0.0。
| 键 | 默认 | 说明 |
|---|---|---|
role |
both |
host 只开桥；client 只注册工具/隧道；both 全开 |
listenHost |
127.0.0.1 |
监听地址，不要改成 0.0.0.0 |
listenPort |
18790 |
监听端口 |
secretFile |
$DSH_HOME/pc-bridge/secret |
密钥文件；不存在时 host 角色自动生成（32 字节 hex，权限 600） |
secretEnv |
DSH_PC_BRIDGE_SECRET |
优先级高于密钥文件的环境变量名 |
peerUrl |
http://127.0.0.1:18790 |
工具调用哪个桥 |
defaultTimeoutMs |
30000 |
默认命令超时 |
maxTimeoutMs |
600000 |
请求可指定的最大超时（10 分钟） |
maxOutputBytes |
2097152 |
stdout/stderr 各自截断上限，超出部分标记 truncated |
shellPath |
自动 | 默认 Windows 优先 Git Bash（C:\Program Files\Git\bin\bash.exe），没有才用 PowerShell；POSIX 用 /bin/bash |
cwd |
当前目录 | 命令工作目录 |
tunnelEnabled |
false |
是否维持 ssh 反向隧道 |
sshHost / sshUser |
空 | 隧道目标 |
sshKeyPath |
空 | 私钥路径；空 = 默认密钥 |
tunnelRemotePort / tunnelLocalPort |
18790 |
远端/本端端口（都绑 127.0.0.1） |
密钥有两条来源：DSH_PC_BRIDGE_SECRET 环境变量优先级最高，否则用 secretFile；host 角色在文件不存在时会自动生成。密钥不写进配置文件，日志只记录来源是 env: 还是 file:，不记录值。
典型用法¶
对端先用 curl 自测桥通不通，隧道建好之后对端的回环上就会出现这台电脑的桥：
curl -s http://127.0.0.1:18790/ping -H "x-pc-secret: $DSH_PC_BRIDGE_SECRET"
Agent 侧的工具签名是：
pc_ping：返回{ok, host, user, shell, now}或网络错误。pc_exec {"command":"...","timeoutSec":30}：返回{ok, exitCode, stdout, stderr, durationMs, timedOut, truncated}。
不写 Harness 集成、只想在终端调也行，pcctl 的地位和 curl 等价：
PC_BRIDGE_SECRET=... pcctl ping
PC_BRIDGE_SECRET=... pcctl exec -- "hostname; echo OK"
对端（以云服务器为例）的准备步骤是：
- 把电脑的公钥加到对端用户的
~/.ssh/authorized_keys。 - 对端把共享密钥放进进程环境，例如 systemd：
Environment=DSH_PC_BRIDGE_SECRET=替换成同一串。 - 对端执行上面的
curl自测；隧道通了之后这台电脑的桥就出现在对端回环上。 - 对端也可以直接用
pcctl。
README 里的演示路径就是这条链路：云端的 QQ 机器人问一句「这台机器在不在」，回的是主机名、用户、shell 类型和服务器时间；要拿东西就在电脑上跑命令，例如列目录、读 git 提交记录。
适用场景与注意¶
适合：有一台自己长期在线、又需要被云端 Agent 调用执行本地命令的电脑，且你愿意维护一条到对端的信任关系。桥本身只有回环接口，隧道也把两端都绑在 127.0.0.1，不向公网开端口。
调用侧可以按需要选择 role：只想让 Agent 发命令、不在这台机器上开端口，就配 client。
需要明确的几点：
- 桥提供的是任意命令执行能力。README 明确要求只把密钥给可信的对端，只在对端可信时才开隧道。
- 本插件以当前 dsh 进程的权限运行，能执行什么命令取决于启动 Harness 的那个用户。安装前请先读一遍源码和许可证（MIT），确认没有超出预期的行为。
- 命令经由 Git Bash 执行，PATH 里没有 Node，能用的命令以本机 Git Bash 为准；
defaultTimeoutMs默认 30 秒，长任务要显式传timeoutSec。 - 请求体上限 64 KiB、命令上限 8 KiB，输出按
maxOutputBytes截断并标记truncated，超时会杀进程树。
结尾¶
dsh-pc-bridge 的价值不在于发明新的远程执行方案，而在于把回环监听、共享密钥鉴权、超时/截断钳制、SSH 反向隧道的退避重连这四件事打包成一个能被 Agent 直接调用的工具，省掉自己写常驻服务的工作量。
目录页：https://www.skillhub.cn/plugins/QIC-9821/dsh-pc-bridge
仓库：https://github.com/QIC-9821/dsh-pc-bridge
