agentcast-bridge

把 stdio-only 的 ACP（Agent Client Protocol）agent 暴露成 WebSocket 服务， 供 Agent Cast（鸿蒙客户端）远程连接。

一个 bridge 覆盖 ACP Registry 全量 agent —— OpenCode、Claude Code、Codex、GitHub Copilot CLI、 Cursor、Gemini CLI、Goose、Amp、Kimi…（完整列表）。

为什么需要它

ACP 的传输只有 stdio（客户端把 agent 拉起为子进程）。手机无法 spawn 进程， 所以中间需要一个 bridge。官方的 Streamable HTTP / WebSocket 传输目前仍是 draft RFD， 尚未落地 —— 这也是本工具存在的原因。

Agent Cast（手机） ──WS + JSON-RPC──> agentcast-bridge ──stdio──> opencode acp

快速开始

npx agentcast-bridge

启动后会打印可直接照抄的连接串：

  ACP bridge 已启动
  ─────────────────────────────────────────────
  Agent      opencode acp
  fs 白名单  /path/to/cwd

  在 Agent Cast 里添加 ACP 实例，填下面两行：

    Endpoint   ws://192.168.1.10:9315
    Token      371b2d9373cb0e6054a6f2c24240e1a3

把这两行填进 Agent Cast 的「添加实例 → ACP」即可。

前置条件：本机已安装并登录好对应的 ACP agent（如 opencode）。 bridge 只是转发，不负责安装 agent。 自检：先单独跑一次 opencode acp，能起来就说明环境没问题。

用法

agentcast-bridge [选项]

  --agent <cmd>    要拉起的 ACP agent 命令（默认 "opencode acp"）
                   例：--agent "hermes acp" / --agent "npx @zed-industries/claude-agent-acp"
  --port <n>       监听端口（默认 9315）
  --host <addr>    监听地址（默认 0.0.0.0）
  --token <s>      bridge token（默认随机生成并打印）
  --root <dir>     fs/* 白名单根目录，可重复（默认 = --cwd）
  --cwd <dir>      agent 工作目录（默认当前目录）
  --verbose        打印每一条中继帧（排障用）
  --quiet          不打印启动横幅

常用示例

# 换 agent
npx agentcast-bridge --agent "hermes acp"

# 固定 token（推荐：免得每次重启都要改手机端配置）
npx agentcast-bridge --token my-secret-token

# 限定 agent 只能读写某个项目目录
npx agentcast-bridge --root ~/projects/my-app --cwd ~/projects/my-app

# 排查连不上
npx agentcast-bridge --verbose

它做了什么

| 职责 | 说明 | |---|---| | 双向中继 | 客户端 ↔ agent 的 JSON-RPC 双向透传 | | 审批转发 | agent 的 session/request_permission 转发到手机，等用户拍板 | | 文件/终端代实现 | agent 反向调用的 fs/*、terminal/* 由 bridge 在本机完成（手机做不到） | | 路径白名单 | fs/* 只允许在 --root 内读写 |

安全

⚠️ bridge 具备在本机读写文件的能力，且默认监听 0.0.0.0。 请务必：

• 只在你信任的网络里运行（家庭/办公局域网，或经 Tailscale 等 VPN）
• 不要直接暴露到公网。若必须远程访问，请用隧道（cloudflared / frp / Tailscale）， 并设置强 --token
• 用 --root 限定目录，不要用默认的当前目录之外的宽范围
• 不使用时停掉它（Ctrl+C）

Token 是唯一屏障：任何拿到 Endpoint + Token 的人都能操作你的 agent。

明文传输说明

默认是 ws://（明文）。在同一局域网内通常可接受；跨网络请用 wss:// （如经隧道时）或 VPN。

退出码 / 排障

| 现象 | 原因 | |---|---| | 手机提示「连不上 bridge」 | bridge 没启动 / 端口不一致 / 不在同一网络 | | 手机提示「bridge token 不对」 | 填的 token 与启动时打印的不一致（随机 token 每次重启会变） | | 手机提示「bridge 连上了，但它没能拉起 agent」 | agent 本身起不来 —— 在本机单独跑一次 agent 命令看报错 | | 启动即报 EADDRINUSE | 端口被占用，换 --port |

开发

cd bridge
npm test        # 路径白名单单测
npm start       # 本地运行

零运行时依赖（内置最小 RFC6455 服务端，不引 ws）。

License

MIT