前言¶
智能體跑在雲端，手裏沒有本地環境，就沒法在你自己的機器上列目錄、讀 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
