Skip to main content
Glama
README.md
# 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` 世代文件。

## 快速开始

```bash
npm install
npm start
# 控制台输出:配对码:xxxxxx
```

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

## 暴露到公网(内网穿透)

按场景选:

### 方案 A(国内跨地区,推荐):frp + 国内轻量 VPS

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

```bash
# ── 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(海外车友 / 已有域名)

```bash
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 配置为例:

```json
{
  "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

TDQS

B3/5.0

Scored across 9 tools

Disambiguation3/5

Three log tools (logs_tail, logs_fetch, logs_file) and two user-prompt tools (notify, prompt_reproduce) overlap enough that an agent may hesitate despite the descriptions differentiating them. Other tools target clearly distinct actions such as status, APK push, commands, and stability configuration.

Naming Consistency3/5

Names are mostly snake_case but mix noun-first patterns (logs_tail, bridge_status) with verb-first patterns (offer_apk, watch_stability) and a bare abbreviation (cmd). The set remains readable, but the naming convention is not predictable throughout.

Tool Count5/5

Nine tools is well within the ideal range for a device bridge/debugging server. Each tool maps to a distinct operational area, even if the three logging tools could be consolidated in a stricter design.

Completeness4/5

The surface covers device status, log retrieval, APK push, whitelisted commands, user notifications, reproduction prompting, and stability configuration. Minor gaps exist around APK install verification, device selection, and log clearing, but core debugging workflows are covered.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues