cardeck-bridge

CarDeck 远程调试桥——一套面向「远程排障 + AI agent」的调试服务：

车机 ←→ 手机(CarDeck remoteDebug 变体) ←WSS/WS─ 内网穿透 ─ 本服务(WS) ⇄ MCP(stdio) → AI agent

一台普通电脑跑本服务即可：

• 设备面（WebSocket，默认 :8787）：手机上安装 CarDeck 的 remoteDebug 变体（assembleRemoteDebug 产物，包名带 .rd，可与日常版并存），在「CarDeck 远程调试」入口填入地址与配对码即接入。接入后：

  • App 持续推送运行日志（批量回补 + 实时流；服务端按 seq 去重、环形保留 5000 行/设备）

  • 服务端可下发白名单命令：发起连接 / 断开连接 / 查询状态 / ping

  • 服务端可下发悬浮窗提示（App 上可拖动）

  • 服务端可推送新 APK：App 下载并校验 sha256 → 悬浮窗提示「安装」→ 先停会话释放虚拟屏（防止系统安装确认弹窗落到车机侧虚拟屏）→ PackageInstaller 发起；重装后首启动询问「继续进入调试模式？」并自动重连

• 会话稳定提示（录制引导）：服务端盯实时日志——RECORD 完成/隐形屏已启动 判定会话激活， 静默 N 秒（默认 10，BRIDGE_STABLE_SECONDS）无 推流中止/Connection reset/SESSION 结束 即在手机悬浮窗提示**「连接已稳定——请现在开始复现问题」**（App 侧 RAW 转储与文件日志 常开，保证录到的段落干净可归因）；断线自动复位、下轮再提示。BRIDGE_AUTO_PROMPT=0 关闭。

• Agent 面（MCP over stdio）：bridge_status / logs_tail / logs_fetch / cmd / notify / prompt_reproduce（手动下发复现引导）/ watch_stability（查看/配置稳定判定）/ offer_apk

• 文件面：GET /apk/<file> 提供 APK 下载（重装闭环用）

日志通道（2026-10-24）

• 实时流：App 推送日志（批量回补 + 500ms 批），服务端按 seq 去重；例行高频行 （视频帧/keepAlive/timesync/采集样本）只进磁盘不进内存环形——环形里留下的 都是有用段。

• 磁盘事实源：全部日志行 JSONL 落盘 logs/<deviceId>.jsonl（20MB 自动轮换； 设备进程重启自动留档新开文件）。logs_fetch 读磁盘——历史完整、跨进程世代。

• logs_file 工具：拉设备 main_debug.log 尾部（文件日志才是含 RAW 协议 转储的完整事实源；内存环形怎么扩都有窗口）。gzip 单消息传输，落盘 logs/ 下的 .log 明文，可直接 grep。设备进程重启会重置服务端去重游标——重启前的 历史用 logs_file 或 logs/*.jsonl 世代文件。

Related MCP server: Karagöz

快速开始

npm install
npm start
# 控制台输出：配对码：xxxxxx

手机端（remoteDebug 变体）→「CarDeck 远程调试」→ 填 ws://<本机局域网IP>:8787 与配对码 → 连接。

暴露到公网（内网穿透）

按场景选：

方案 A（国内跨地区，推荐）：frp + 国内轻量 VPS

Cloudflare 免费版无大陆节点（流量绕美西）且默认 QUIC 受 UDP QoS 限速，国内长连接不稳—— 两端都在国内时 frp 直连 VPS 最快最稳（裸 IP 高位端口纯 TCP 转发，无需域名备案）。

# ── VPS 侧（阿里云/腾讯云轻量，几块钱/月）──
# 1) 下载 frp（https://github.com/fatedier/frp/releases，linux_amd64）
# 2) frps.toml：
#      bindPort = 7000
#      auth.token = "<强随机串>"
# 3) 启动（建议 systemd 常驻）：
./frps -c frps.toml
# 4) 安全组/防火墙放行 7000（frp 控制）与 8787（桥端口）

# ── 开发者电脑侧 ──
# frpc.toml：
#      serverAddr = "<VPS公网IP>"
#      serverPort = 7000
#      auth.token = "<同上强随机串>"
#      [[proxies]]
#      name = "cardeck-bridge"
#      type = "tcp"
#      localIP = "127.0.0.1"
#      localPort = 8787      # 必填：frp 0.7x 不默认继承 remotePort
#      remotePort = 8787
./frpc -c frpc.toml &
BRIDGE_PAIRING=<自定6位> PUBLIC_BASE=http://<VPS公网IP>:8787 npm start

# ── 手机侧（remoteDebug 变体）──
# 「CarDeck 远程调试」→ 地址填 ws://<VPS公网IP>:8787 → 配对码 → 连接

注意：明文 TCP（配对码只防误连，不防窃听）；调试日志含热点名/蓝牙地址，介意可换 自有域名 + HTTPS 网关终结 TLS 后再转发。

方案 B：国内穿透服务（免 VPS）

natapp / cpolar / 花生壳等，免费档有限速（传日志够用，推 APK 慢）。按其文档把本地 8787 映射为 tcp 隧道即可，手机端填 ws://<映射地址>。

方案 C：Cloudflare Tunnel（海外车友 / 已有域名）

cloudflared tunnel --protocol http2 --url http://127.0.0.1:8787
# 国内默认 QUIC 受 UDP QoS 限速，强制 http2 更稳；临时隧道（trycloudflare.com）线路质量差，
# 建议绑自有域名 + 优选 IP。手机端填 wss://<域名>；PUBLIC_BASE=https://<域名>

环境变量：PORT（默认 8787）、PUBLIC_BASE（APK 下载链接的公网基址）、BRIDGE_PAIRING（固定配对码，不设则随机生成）、BRIDGE_AUTO_PROMPT/BRIDGE_STABLE_SECONDS（稳定提示）。

接入 AI agent（MCP）

以 Claude/ZCode 类客户端的 MCP 配置为例：

{
  "mcpServers": {
    "cardeck": {
      "command": "npm",
      "args": ["--prefix", "/path/to/cardeck-bridge", "run", "start"]
    }
  }
}

之后 agent 可直接：bridge_status → logs_tail 看车友日志 → cmd(start_connection) 复现问题 → offer_apk 推新包让用户一键重装。

安全边界

• 配对码一次性握手，明文错误码即断开；建议始终经 TLS（wss/cloudflared）或可信网络（局域网）

• 命令为白名单（连接控制与状态查询），不提供任意 shell/文件读写

• 日志含热点名/蓝牙地址等，仅用于排障；MCP 与 WS 同进程同机，不外发第三方

• remoteDebug 变体是独立包名（.rd），发布渠道请单独标注实验性质，勿作为默认版本分发

License

MIT