1. 产品职责
代码 Agent 需要读取项目、调用工具、执行命令并维持长时间运行的进程。Woodox 没有把这套环境搬到手机，而是把职责拆开：
- 电脑负责执行：保存项目与登录状态，运行 Codex、Claude Code、Kimi Code 或 Qwen Code，执行命令并维护历史会话。
- Android App 负责交互：查看时间线和实时进度，发送消息与附件，处理确认，必要时使用终端。
- 公网中转服务负责转发密文：让手机和电脑会合，按路由转发不透明二进制帧，不解析应用层消息。
因此 Android App 不能单独使用。电脑关机、休眠、断网或后台服务停止时，手机会失去连接，公网中转服务不会继续执行任务。
2. 组件说明
| 组件 | 职责 | 边界 |
|---|---|---|
| Windows 客户端 | 检测环境、选择项目、启动服务与 Agent、配置中转、生成连接信息、审批设备和诊断故障。 | 它是控制面，不代替第三方 Agent 账号和模型服务。 |
| WSL2 与 Ubuntu | 提供 Linux 运行平台、用户环境、文件系统和工具链。 | WSL2 是运行平台，Ubuntu 是其中的 Linux 发行版，两者不是同一个组件。 |
| Agent CLI 与 tmux | Agent 处理任务；tmux 维持受管终端会话，让窗口关闭或手机重连后仍能回到同一进程。 | 账号、会员、API Key 与模型费用由对应服务商管理。 |
| 电脑端 Rust 服务 | 只监听电脑回环地址的 8787，并作为 Noise 响应方处理解密后的历史、事件、附件、终端和会话控制。 | 不监听 Windows 网卡，不为手机开放电脑网络端口。 |
| Noise 安全会话 | 手机固定预期电脑静态公钥，双方通过 Noise XX 握手建立应用层加密通道。 | 中转终止外层 TLS 后仍只得到 Noise 密文。 |
| woodox-relayd 与账户中心 | 接受电脑和手机的 WSS 连接，按路由 ID 转发密文，并管理必要的账户与路由状态。 | 不运行用户 Agent，也不持有解密 Noise 会话所需的端点私钥。 |
| Android App | 保存设备身份和连接记录，展示历史与实时状态，并将用户操作发送回电脑。 | 不保存完整项目副本，也不在手机执行 Agent。 |
3. 公网中转服务的完整链路
Android AppNoise 发起方；固定电脑身份公钥
woodox-relayd按路由转发不透明二进制帧
Windows / WSLNoise 响应方；审批、历史与 Agent 控制
当前协议标识为 woodox-e2ee/1，加密套件为 Noise_XX_25519_ChaChaPoly_BLAKE2s。外层 WSS/TLS 保护到中转的网络连接，内层 Noise 负责手机到电脑的端到端机密性与完整性。
- Windows / WSL 中的 Woodox 服务只在本机处理明文和 Agent 操作，并主动连接 WSS 中转。
- Android App 扫码取得电脑身份公钥和一次性配对信息，随后主动连接同一中转。
- 双方执行 Noise XX 握手；手机校验电脑静态公钥，配对身份与一次性票据在握手密文中传递。
- woodox-relayd 仅根据路由 ID 配对连接并转发二进制密文，不解析内部
ControlEnvelope。 - 电脑批准设备后签发与手机公钥、电脑身份绑定的恢复凭据；撤销后旧设备不能继续访问。
4. 实时事件、历史与终端
Woodox 的日常交互不是反复替换整屏终端快照。当前实现把实时更新、持久历史、状态校正和终端回退分开：
| 机制 | 负责什么 | 使用时机 |
|---|---|---|
| 实时事件流 | 增量推送用户消息、Agent 回复、工具活动、文件修改和运行状态；短时断线可重放内存事件。 | 正常连接时的主要更新来源。 |
| 分页持久历史 | 电脑保存会话时间线，手机向上滚动时按游标加载更早记录。 | 查看完整上下文和断线期间记录。 |
| 状态校正 | 首次连接、事件缓冲不足或网络恢复后，核对会话是否运行以及终端末端状态。 | 恢复兜底，不是唯一交互来源。 |
| Codex app-server | 电脑端通过标准输入/输出启动 codex app-server，读取 Thread、Turn、Item 和结构化事件。 | Codex 的结构化历史与工具卡片。 |
| 终端时间线 | 根据受管终端变化保存可滚动记录，并保留原始终端与快捷键操作。 | Claude Code、Kimi Code、Qwen Code，以及 Codex 结构化接口不可用时的回退。 |
所以“断线后用当前状态校正”是恢复机制的一部分，但正常体验还依赖实时事件和持久历史。Claude Code、Kimi Code 与 Qwen Code 的终端时间线不会被包装成与 Codex 完全相同的结构化能力。
5. 端口和协议一览
| 端口 / 对象 | 监听位置 | 用途 | 公开范围 |
|---|---|---|---|
| 8787/TCP | 电脑 127.0.0.1 | Woodox 本机 HTTP 与事件接口 | 不对 Windows 网卡或云安全组开放 |
| 80/TCP | 云服务器 Nginx / Caddy | 跳转到 HTTPS 或完成 ACME 验证 | 公网 |
| 443/TCP | 公网入口 / woodox-relayd | 手机和电脑的 WSS 长连接；负载为 Noise 密文 | 公网 |
| 8790/TCP | 云服务器 127.0.0.1 | 中转账户中心控制服务 | 仅反向代理访问，不对公网开放 |
| 路由 ID | woodox-relayd 内存路由 | 为一台电脑配对手机与电脑连接 | 属于可见元数据，不包含会话正文 |
6. 数据保存与经过的位置
项目文件
保留在 Windows 项目目录或 Ubuntu 文件系统。Android App 与公网中转服务不建立完整项目副本。
Agent 登录状态
由对应 CLI 保存在电脑的 Ubuntu 用户环境，Woodox 不要求用户交出官方账号密码。
受管会话与历史
保存在运行 Woodox 的电脑；Codex 原始 Thread 仍由 Codex CLI 管理。
Android App 连接凭据
敏感值由 AndroidKeyStore 加密后存入应用私有数据，设备标识用于审批与重连。
中转账户状态
保存账户、密码哈希、设备公钥与指纹、租户、IP、时间、状态和审计记录。
传输中的正文
以 Noise 密文经过中转。运营者可观察 IP、时间、路由 ID、连接数和流量大小，但不能读取正文。
7. 断线与恢复
- 手机网络短时中断时，电脑上的 Agent 和 tmux 会话继续按电脑实际状态运行。
- Android 恢复连接后，先尝试从事件游标补发内存中的新事件。
- 事件窗口不足时，客户端重新读取电脑端持久历史。
- 最后用当前会话和终端状态校正是否仍在运行、是否已完成或是否等待交互。
- WSS 中转连接中断时，客户端会重试；电脑休眠或断网期间无法建立端到端会话。
8. 信任边界与权限
- Noise E2EE：
Noise_XX_25519_ChaChaPoly_BLAKE2s保护手机与电脑之间的正文机密性、完整性和身份绑定。 - 固定电脑身份：Android 校验扫码获得的预期电脑静态公钥；替换身份密钥会导致握手失败。
- WSS/TLS：保护端点到中转的传输，但它位于 Noise E2EE 外层，不承担正文解密。
- 配对与恢复：一次性票据在 Noise 握手中加密，恢复凭据摘要持久化并绑定双方身份。
- 设备审批：新手机必须在电脑端明确允许；设备可以单独撤销。
- 元数据边界：E2EE 不隐藏 IP、连接时间、路由 ID、连接数量和密文流量大小，也不保护已被入侵的端点。
9. 按层定位故障
- Agent 层：在电脑的目标 Ubuntu 中运行对应 CLI，确认登录与项目访问正常。
- 会话层：Windows 客户端能够打开受管会话，Agent 在 tmux 中正常响应。
- 本机服务层：全局概览显示后台在线，
127.0.0.1:8787健康检查通过。 - 中转层：电脑端显示 WSS 中转在线，路由配置与当前账户一致。
- 云端层：DNS、443/TLS、反向代理和 woodox-relayd 健康检查依次正常。
- E2EE 与审批层：Noise 握手、电脑身份固定、手机设备身份和批准状态均有效。
具体错误、命令和预期结果见问题排查。