dsh-aa-bridge-doctorv0.2.0

dsh-aa-bridge-doctor

AA Bridge Doctor（桥接医生） — 一个 DeepSeek Harness 插件：检测并恢复 Agents Anywhere 桥接的"持续离线"故障（Connector 进程活着但连接永久卡死，手机端一直显示设备离线，只能重启电脑上的进程才能恢复）。

• A DeepSeek Harness plugin that detects and auto-recovers the Agents Anywhere bridge "persistent offline" wedge — the Connector process is alive but its connection is permanently stuck, so your phone shows the device offline until someone restarts the process by hand.

它解决什么问题 / What it fixes

已确认的上游问题：

• Agents-Anywhere#381 — 认证请求陷入 60~120s 空超时死循环，设备永久离线，只能重启恢复
• dsh-desktop#1334 — Connector 进程静默退出后无人拉起，掉线数小时无人知晓
• #501 — DSH Runtime 永久卡在「正在同步 DSH 会话…」

共同形态（与内部故障类无关）：进程存活 + 连续鉴权失败 + 设备离线。官方重连机制只会用同一个（可能已坏死的）HTTP 客户端原样重试，永不重建——所以"每 3 秒重试"退化为"每 63~120 秒撞同一堵墙"。

工作原理 / How it works

每 pollSeconds 秒执行一次只读检查（三源信号）：

1. 进程信号：读取 ~/.agents-anywhere/connector-runtime.json 中的 pid，验证进程存活
2. 日志信号：扫描 ~/.agents-anywhere/logs/runtime-*.jsonl，统计时间窗口内的鉴权失败次数
3. 日志静默信号：进程存活但 AA 日志 ≥ logSilenceMinutes 无写入 → 事件循环挂死变体
4. （需开启 checkDeviceApi）云端信号：设备离线交叉验证（连续离线 → 提醒路由/代理问题）+ DSH Runtime 卡「正在同步」检测（#501）

护栏：冷却时间（cooldownMinutes）、每日上限（maxRestartsPerDay）、所有动作写入 ~/.agents-anywhere/bridge-doctor/bridge-doctor.log。

拉起方式：优先复用 DSH NEXT 内置的 uv（app.asar.unpacked/@dataiku/uv）直接构造 argv（空格路径安全），兜底 PATH 上的 uv，最后才尝试 ps 捕获的命令行（校验首个路径真实存在）。拉起的进程与官方插件拉起的一样，随 DSH NEXT 退出而退出，不改变任何归属关系。

安装 / Install

需要：已安装 DeepSeek Harness（社区 DSH NEXT 2.0.x 或官方 0.2.1+）且已安装 @agents-anywhere/dsh-bridge-next 并登录。

方式 A — npm（发布后）：

dsh plugin --profile desktop add dsh-aa-bridge-doctor

方式 B — 从源码：

git clone <repo> && cd dsh-aa-bridge-doctor
npm install && npm run check
dsh plugin --profile desktop add .

方式 C — 手动（无 dsh CLI 时，已实勘 DSH NEXT 的 profile 结构）：

1. 把本目录复制到固定位置（如 ~/plugins/dsh-aa-bridge-doctor），在该目录 npm install && npm run build 产出 lib/
2. 编辑 ~/.dsh/profiles/desktop/package.json： dependencies 加 "dsh-aa-bridge-doctor": "file:~/plugins/dsh-aa-bridge-doctor" dsh.profile.bundles 数组加 "dsh-aa-bridge-doctor"
3. 编辑 ~/.dsh/profiles/desktop/cordis.patch.yml，追加条目： ```yaml id: dsh-aa-bridge-doctor

name: dsh-aa-bridge-doctor config: {} ```

1. 在 profile 目录执行包管理器安装（该目录用 pnpm：pnpm install；若你的 profile 用 npm 则 npm install）
2. 重启 DSH（生效后：设置页出现「AA Bridge Doctor」；日志在 ~/.agents-anywhere/bridge-doctor/）

注：本插件为 host-only（无 dsh.client 客户端半区），不依赖 @deepseek-ai/dsh-client-ui-slots，因此不存在 #570 那类"官方桌面端装入后打不开"的兼容风险。

配置 / Configuration（DSH 设置页）

平台支持 / Platform

隐私 / Privacy

• 所有检测在本机完成；日志内容、会话数据永不离开电脑
• 唯一的网络访问是可选的 checkDeviceApi（只读查询设备在线状态），凭据只从本机文件读取、只用于该查询、永不写入日志
• 自动恢复动作与本机文件全部记录在 ~/.agents-anywhere/bridge-doctor/

开发 / Development

npm install
npm run check   # typecheck + build + 12 项单元测试

无原生打包依赖（纯 tsc），任何 Node ≥ 22.19 环境可构建。

镜像 / Mirror

Gitee 同步仓库：gitee.com/simonsxx/dsh-aa-bridge-doctor（国内访问更快的只读镜像，以 GitHub 为准）

作者 / Author

• 作者：simon，一个不懂代码的 AI 极客（）
• 微信交流群：simonsxxs
• 个人网站：
• GitHub：
• Gitee：

背景与技术分析：本插件源于一次真实的桥接故障取证，根因报告见 docs/ROOT_CAUSE.md。

License

MIT © simon (https://github.com/simonsxxs)