前言¶
在用 DeepSeek Harness（DSH）配合 Agents Anywhere 把手机当远端设备时，常见一种恼人状态：电脑上的 Connector 进程还在，手机端却一直显示设备离线；手动重启 Connector 或整台电脑上的相关进程才能恢复。官方重连往往沿用可能已经坏死的 HTTP 客户端反复重试，很难从根上跳出死循环。
AA Bridge Doctor（桥接医生） 是社区维护的 DSH 插件，在本机周期性做只读健康检查，在判定为进程退出或连接卡死时给出通知，并在配置允许时按护栏规则自动拉起或重启 Connector。下面介绍其定位、工作原理、安装与配置。
这是什么¶
- 仓库： simonsxxs/dsh-aa-bridge-doctor
- 社区目录：SkillHub 插件页（独立站点，与 DeepSeek / 幻方无官方从属关系）
- 维护者：simonsxxs（作者 simon）
- 分类：工作流
- 当前版本（package.json）：0.3.2
- 许可证：MIT
插件针对上游已讨论过的故障形态：进程仍存活、连续鉴权失败、设备长期离线。README 中引用了 Agents-Anywhere#381（认证空超时死循环）、dsh-desktop#1334（Connector 静默退出无人拉起）、#501（DSH Runtime 卡在「正在同步 DSH 会话…」）。本插件不替代官方修复，而是在本机做观测与有限自动恢复。
本插件为 host-only（无 dsh.client 客户端半区），不依赖 @deepseek-ai/dsh-client-ui-slots。
核心功能¶
周期性三源（及可选第四源）检查¶
默认每 pollSeconds 秒（默认 30）执行一次只读检查：
- 进程信号：读
~/.agents-anywhere/connector-runtime.json中的 pid，验证进程是否存活。 - 日志信号：扫描
~/.agents-anywhere/logs/runtime-*.jsonl，统计时间窗口内的鉴权失败次数。 - 日志静默：进程存活但 AA 日志在
logSilenceMinutes内无写入时，按事件循环挂死变体处理。 - 云端信号（需开启
checkDeviceApi）：用本机account.json的 token 只读查询设备在线状态，并辅助检测 DSH Runtime 长时间卡在同步会话。
判定与默认动作¶
| 判定 | 含义概要 | 默认动作 |
|---|---|---|
exited |
有记录但进程已死；按退出码与陈旧窗口决定是否允许自动拉起 | 通知；autoRestartExited 为 true 且通过甄别时可自动重新拉起 |
wedged |
进程存活且失败达阈值或日志长期静默 | 通知；autoRestartWedged 默认 false，开启后可自动重启 Connector |
stuck-syncing |
需 checkDeviceApi；同步卡住 ≥ 15 分钟 |
通知恢复指引（如设备页对 DSH 重新「一键配置」） |
healthy / not-installed |
其余情况 | 不动作 |
自动恢复前有 冷却（cooldownMinutes）与 每日重启上限（maxRestartsPerDay）。动作与诊断写入 ~/.agents-anywhere/bridge-doctor/bridge-doctor.log。
拉起 Connector 时优先使用 DSH NEXT 内置 uv（app.asar.unpacked/@dataiku/uv），失败则兜底 PATH 上的 uv；终止前做 PID 身份校验与预检，无法确认则放弃（Fail Closed）。拉起为分离进程，DSH 退出后其存续取决于系统，README 不承诺严格随 DSH 退出。
隐私¶
检测均在本机完成；可选 checkDeviceApi 为只读查询，凭据从本机文件读取且不写入日志。
安装与启用¶
前提（README 原文）：已安装 DeepSeek Harness（社区 DSH NEXT 2.0.x 或官方 0.2.1+），已安装 @agents-anywhere/dsh-bridge-next 并登录。
方式 A — npm（发布后）¶
在桌面 profile 下添加插件：
dsh plugin --profile desktop add dsh-aa-bridge-doctor
方式 B — 从源码（需自行 clone 与构建，见仓库 README）¶
git clone https://github.com/simonsxxs/dsh-aa-bridge-doctor.git && cd dsh-aa-bridge-doctor
npm install && npm run check
dsh plugin --profile desktop add .
方式 C — 手动¶
无 dsh CLI 时，可将构建产物以 file: 依赖写入 ~/.dsh/profiles/desktop/package.json，在 cordis.patch.yml 中注册 bundle，再在 profile 目录执行 pnpm install 或 npm install，最后重启 DSH。生效后设置页出现「AA Bridge Doctor」，日志目录为 ~/.agents-anywhere/bridge-doctor/。
注意：插件随当前 DSH 进程权限在本机读写上述路径并可能重启 Connector；安装前请阅读仓库源码与 MIT 许可证，自行评估是否纳入工作流。
配置（DSH 设置页）¶
| 配置项 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关 |
uvPath |
'' |
自定义 uv 可执行路径，留空自动发现 |
autoRestartExited |
true |
异常退出后自动拉起 |
autoRestartWedged |
false |
卡死时自动重启 Connector（默认仅通知） |
failureThreshold / windowMinutes |
4 / 10 |
鉴权失败签名阈值与时间窗 |
logSilenceMinutes |
15 |
日志静默判定（分钟） |
cooldownMinutes / maxRestartsPerDay |
60 / 6 |
冷却与每日自动恢复上限 |
pollSeconds |
30 |
检查间隔 |
checkDeviceApi |
false |
是否联网核对设备状态 |
典型用法：先保持默认仅自动处理 已退出 的 Connector；若你经常遇到「进程在、手机一直离线」且接受本机自动 SIGTERM 后重启，再在设置页将 autoRestartWedged 设为 true，并留意每日上限与冷却，避免与人工排障冲突。
平台与适用场景¶
| 平台 | 状态 |
|---|---|
| macOS（Apple Silicon / Intel） | 一等支持，全功能实测 |
| Linux | 尽力支持；通知依赖 notify-send（未装则静默） |
| Windows | 未测，欢迎反馈 |
适合：长期在桌面 DSH 上挂 Agents Anywhere 桥接、希望减少「半夜掉线无人知」或「卡死只能手动杀进程」的开发者。不适合：未安装 dsh-bridge-next 或未登录 AA 的环境。
根因与取证背景见仓库 docs/ROOT_CAUSE.md。国内只读镜像：Gitee 同步仓（以 GitHub 为准）。
结尾¶
桥接医生把「进程活着但桥已坏死」这类 wedge 当成可观测、可限额自动处理的本机问题，与 DSH「一切皆插件」的思路一致。需要细节时查 GitHub README 与 SkillHub 目录页。
