RelayDesk Miniapp

微信小程序客户端原型，用于通过付费 relay 远程连接用户电脑上的 Codex bridge。

定位：

• 小程序负责移动端交互、微信登录和支付入口。
• Relay 服务负责账号、订阅、设备在线状态和密文转发。
• 电脑 Bridge 负责本地 Codex session、项目、权限确认和工具调用。
• 小程序与 Bridge 端到端加密，Relay 默认只处理路由元数据和密文。

当前内容

• 原生微信小程序骨架
• 工作台、会话、对话、安全设备页
• Mock 数据兜底的核心 UI 状态
• 本地 WebSocket relay 开发服务
• Desktop bridge mock，用来模拟 Codex 会话、消息流和审批请求
• Local bridge，用来列出真实本机项目并预留 Codex CLI 执行路径
• 开发版配对骨架，展示 mobile/bridge 指纹、pairId 和 verify code
• 会话 cursor 恢复骨架，移动端重连时只补缺失事件
• 可部署的 hosted relay 服务入口，带健康检查和 token 门禁
• 产品与架构说明文档

本地开发链路

先不做支付。当前目标是跑通“手机小程序 -> relay -> 电脑 bridge -> relay -> 小程序”的主路径。

WeChat Mini Program
  -> ws://127.0.0.1:8787/ws
  -> scripts/relay-dev.js
  -> scripts/bridge-mock.js
  -> scripts/relay-dev.js
  -> WeChat Mini Program

安装依赖：

npm install

推荐直接启动完整本地链路：

npm run dev

这个命令会同时启动本地 relay 和 bridge mock。看到 relay listening on ws://127.0.0.1:8787/ws 后，再刷新微信开发者工具。

如果要用本机项目而不是 mock 数据：

npm run dev:local

dev:local 默认是 dry-run，会列出本机项目并模拟 Codex 执行，不会调用模型或写文件。小程序发起配对时，电脑终端会显示 mobile/bridge 指纹和 verify code；输入 YES 后才会确认配对。

如果只想做 UI 演示，可以用自动确认：

npm run dev:local:auto

真实运行 Codex CLI 需要显式开启：

BRIDGE_CODEX_MODE=exec npm run dev:local

真实模式会运行 codex exec，可能产生模型费用，也可能修改项目文件。

当前配对与 crypto 状态是开发骨架：协议里已经有 public key、fingerprint、pairId 和 cipher suite 元数据，但 payload 仍是 dev-plaintext。生产版需要替换成真实 X25519/AES-GCM，并在电脑 bridge 上做本地确认。

bridge-local 会在本地生成 bridge.trust.json 和 bridge.events.json，分别保存已信任手机和会话事件历史。这两个文件已被 .gitignore 忽略。

也可以分两个终端单独启动 relay：

npm run dev:relay

另开一个终端启动 bridge mock：

npm run dev:bridge

用微信开发者工具导入当前目录 /Users/monkeyin/projects/agent2miniapp。开发阶段已关闭 urlCheck，生产版本需要改成合法 HTTPS/WSS 域名。

如果控制台出现：

WebSocket connection to 'ws://127.0.0.1:8787/ws?...' failed

先确认 npm run dev 正在运行。真机预览不能使用 127.0.0.1，需要把 utils/config.js 里的 relayUrl 改成电脑的局域网 IP 或线上 WSS 域名。

Hosted Relay

公网测试 relay 使用独立入口：

npm run start:relay

部署时用 RELAY_TOKEN 做临时门禁。小程序和电脑 bridge 的 URL 都需要带同一个 token，并且 userId 要一致：

ws://SERVER_IP/relaydesk/ws?role=miniapp&userId=dev-user&deviceId=iphone-dev&token=TOKEN
ws://SERVER_IP/relaydesk/ws?role=bridge&userId=dev-user&deviceId=bridge-local-dev&token=TOKEN

当前服务器通过 Nginx 暴露 /relaydesk/healthz 和 /relaydesk/ws，Node relay 只监听 127.0.0.1:8787。IP 直连 ws:// 适合开发和微信开发者工具测试。正式微信小程序需要 wss:// 合法域名和 TLS 证书。

开发工具里可以临时切换小程序 relay URL，不要把 token 写进代码：

wx.setStorageSync("relaydesk.relayUrl", "ws://SERVER_IP/relaydesk/ws?role=miniapp&userId=dev-user&deviceId=iphone-dev&token=TOKEN")

本机 bridge 用同一个 token：

BRIDGE_RELAY_URL='ws://SERVER_IP/relaydesk/ws?role=bridge&userId=dev-user&deviceId=bridge-local-dev&token=TOKEN' npm run dev:bridge:local

给同事试用时，不需要 clone 仓库、不需要手动填 token，也不需要指定项目目录。电脑终端执行：

npx relaydesk-bridge

第一次运行会自动向 relay 创建一次配对、在终端显示二维码、并把 bridge 放到后台运行。小程序进入 Relay 设置页，点击 扫码连接 扫终端二维码即可连接。

电脑重启、bridge 挂掉或手动停止后，不需要重新扫码，直接复用本机保存的配对启动。这个命令也可以作为统一启动命令：如果本机还没有配对过，会自动显示二维码；如果已经配对过，只会启动后台进程。

npx relaydesk-bridge start

只有需要换手机或重置配对时，才重新生成二维码：

npx relaydesk-bridge pair

如果只是想重新展示二维码，也可以用更直观的别名：

npx relaydesk-bridge qr

后台状态、日志和停止：

npx relaydesk-bridge status
npx relaydesk-bridge logs
npx relaydesk-bridge stop

想让同事电脑重启后自动恢复，可以安装用户级后台服务。macOS 使用 launchd，Windows 使用当前用户启动项，Linux 使用 systemd --user：

npx relaydesk-bridge install-service

服务状态和卸载：

npx relaydesk-bridge service-status
npx relaydesk-bridge uninstall-service

端到端联调：

npm run e2e:hosted

通过后再打开微信开发者工具，在 Relay 设置页选择 Hosted WSS，填入同一个 token，保存并重连。

需要兼容旧的邀请码流程时，也可以显式传邀请码：

npx relaydesk-bridge --invite=RD-XXXX

命令

| Command | Description | | --- | --- | | npm run dev | 同时启动本地 relay 和 bridge mock | | npm run dev:chain | 同 npm run dev | | npm run dev:local | 同时启动本地 relay 和 local bridge dry-run | | npm run dev:local:auto | local bridge dry-run，配对自动确认 | | npm run dev:relay | 启动本地 relay WebSocket 服务 | | npm run start:relay | 启动可部署的 hosted relay 服务 | | npm run dev:bridge | 启动桌面 bridge mock | | npm run dev:bridge:local | 只启动 local bridge | | npx relaydesk-bridge | 发布包入口；首次创建扫码配对，之后复用已有配对启动 | | npx relaydesk-bridge start | 复用已有配对启动 bridge，不重新扫码 | | npx relaydesk-bridge pair | 重新生成扫码配对并启动 bridge | | npx relaydesk-bridge qr | 同 pair，重新展示配对二维码并启动 bridge | | npx relaydesk-bridge status | 查看 npm 包后台 bridge 状态 | | npx relaydesk-bridge stop | 停止 npm 包后台 bridge | | npx relaydesk-bridge install-service | 安装用户级开机自启服务，并立即启动 bridge | | npx relaydesk-bridge service-status | 查看开机自启服务状态 | | npx relaydesk-bridge uninstall-service | 移除开机自启服务并停止 bridge | | npm run bridge -- --invite=RD-XXXX | 仓库内调试入口：邀请码换 token，并后台启动当前目录 bridge | | npm run bridge:status | 查看后台 bridge 状态 | | npm run bridge:stop | 停止后台 bridge | | npm run bridge:configure | 生成或更新本机 bridge 配置 | | npm run e2e:hosted | 跑 hosted relay + local bridge + miniapp 模拟端到端联调 | | npm run check | 对 Node 脚本和小程序 store 做语法检查 |

文档

• docs/product-architecture.md: 产品与系统架构
• docs/protocol.md: relay 消息协议
• docs/bridge-local.md: 本机 bridge 使用说明
• docs/deployment-relay.md: hosted relay 部署说明
• docs/decisions/ADR-001-local-relay-before-payments.md: 为什么先做本地链路、支付最后做
• docs/decisions/ADR-002-bridge-local-before-real-desktop-control.md: 为什么先做 local bridge
• docs/decisions/ADR-003-dev-pairing-before-production-e2ee.md: 为什么先做开发配对骨架
• docs/decisions/ADR-004-session-cursor-resume.md: 为什么用 per-session cursor 恢复会话
• docs/decisions/ADR-005-token-gated-hosted-relay.md: 为什么 hosted relay 先使用 token 门禁

打开方式

用微信开发者工具导入当前目录 /Users/monkeyin/projects/agent2miniapp。