Codex 多机协作控制架构

目标是让你只和一个主 Agent 对话,由主 Agent 调度多台 Mac、Windows 和云服务器上的 Codex 线程进行开发。 每个项目都可以查看聊天记录、执行进度、命令历史和补丁结果,并通过外部记忆系统解决长上下文导致的“越写越钝”问题。

一、核心结论

产品形态
单主会话,多执行线程

手机端始终只有一个主对话入口,真正执行代码的是多个短上下文 Codex worker。

技术底座
LangGraph + Codex app-server / SDK

LangGraph 负责任务编排,Codex 负责本地和远程代码执行,会话历史由统一事件库镜像。

记忆策略
系统记忆外置,不依赖单线程上下文

项目事实、设计约束、决策记录和阶段摘要统一保存在控制平面,避免单个线程长期膨胀。

二、系统总览图

[ 手机 App / Web 控制台 ] | v [ API 网关 + WebSocket 实时推送 ] | v [ 运维层 / 运维审计层 ] ├─ 主运维层(可接管其他项目) ├─ Ops Control Plane ├─ Ops Policy Engine ├─ Chief Ops Audit Agent ├─ Ops Ledger ├─ Ops Extension Registry / Connector Runtime └─ 全局健康矩阵 / 修复工单 / Runbook / Rescue Mode | v [ Control Plane / 云服务器 ] ├─ Master Agent Runtime (LangGraph) ├─ Project Memory (决策账本 + 向量记忆) ├─ Event Store (聊天记录 / 命令 / Patch / 审批) ├─ Scheduler / Capability Router ├─ Thread Registry ├─ Inter-Thread Broker ├─ Audit Orchestrator ├─ Rules Audit Engine ├─ Specialist Audit Agents │ ├─ 软件审计 Agent │ ├─ 硬件审计 Agent │ ├─ 多模态审计 Agent │ └─ 总审计 Agent └─ Quota / Rate Limit Monitor | +--------------------+--------------------+--------------------+ | | | | v v v v [ Mac Worker ] [ Windows Worker ] [ Cloud Worker ] [ Standby Controller ] ├─ Codex app-server ├─ Codex app-server ├─ Codex app-server ├─ 冷/热备控制器 ├─ Repo Worktrees ├─ WSL2 + Repo ├─ Repo Worktrees ├─ 接管调度 ├─ MCP / 本地工具 ├─ GPU Service ├─ CI / 长任务 └─ 读取事件和状态 ├─ Thread Gateway ├─ Thread Gateway ├─ Thread Gateway ├─ Local Ops Agent ├─ Local Ops Agent ├─ Local Ops Agent ├─ Local Ops Audit ├─ Local Ops Audit ├─ Local Ops Audit ├─ Camera / Mic / Speaker └─ Test Rig Gateway ├─ Thumb Robot / USB / Relay └─ 心跳与事件上报 └─ 心跳与事件上报 └─ 心跳与事件上报

三、整体架构思维导图(完整版)

这张是完整的总架构脑图,不是摘要版。你可以把它理解成“整个产品怎么拼起来”的树状图。

Codex 多机协作系统 ├─ 1. 用户入口 │ ├─ 手机 App / Web │ ├─ 单一主对话窗口 │ ├─ 项目列表 │ ├─ 线程详情页 │ └─ 审批 / 告警 / 节点状态 ├─ 2. 主控层(云服务器) │ ├─ API 网关 │ ├─ WebSocket 实时推送 │ ├─ Master Agent Runtime │ │ ├─ LangGraph 编排 │ │ ├─ 任务拆分 │ │ ├─ 节点选择 │ │ ├─ 上下文裁剪 │ │ └─ 人工协同 │ ├─ Scheduler / Capability Router │ ├─ Thread Registry │ ├─ Inter-Thread Broker │ ├─ Quota / Rate Limit Monitor │ └─ Standby Controller ├─ 2.5 运维层与运维审计层 │ ├─ 主运维层 │ │ ├─ 当前 Codex 协作系统 │ │ └─ 未来接入的其他项目运维域 │ ├─ Ops Control Plane │ ├─ Ops Policy Engine │ ├─ Chief Ops Audit Agent │ ├─ Ops Ledger │ ├─ Ops Extension Registry │ ├─ Ops Connector Runtime │ ├─ 高频模式巡检(5 分钟) │ ├─ 空闲模式巡检(1 小时) │ ├─ 主控反向抢救运维层 │ ├─ 主控在线审批修复 │ └─ 主控离线紧急接管修复 ├─ 3. 记忆与数据层(云服务器) │ ├─ Postgres │ │ ├─ 项目 │ │ ├─ 任务 │ │ ├─ 线程镜像 │ │ ├─ 审批记录 │ │ └─ 节点心跳 │ ├─ Vector Store │ │ ├─ 项目长期记忆 │ │ ├─ 阶段摘要 │ │ ├─ 设计约束 │ │ └─ 经验检索 │ ├─ Object Storage │ │ ├─ 原始事件日志 │ │ ├─ 导出的报告 │ │ └─ 补丁快照 │ └─ Redis / Queue │ ├─ 任务队列 │ └─ 事件广播 ├─ 4. 执行层(多节点) │ ├─ Mac Worker │ │ ├─ Codex app-server / SDK │ │ ├─ worktree / branch │ │ ├─ MCP / 本地工具 │ │ ├─ Thread Gateway │ │ ├─ Local Ops Agent │ │ ├─ Local Ops Audit Agent │ │ └─ 前端 / iOS / macOS 任务 │ ├─ Windows Worker(WSL2) │ │ ├─ Codex app-server / SDK │ │ ├─ GPU Bridge │ │ ├─ PowerShell / 原生工具桥 │ │ ├─ Thread Gateway │ │ ├─ Local Ops Agent │ │ ├─ Local Ops Audit Agent │ │ └─ CUDA / NVIDIA / Windows 任务 │ └─ Cloud Worker │ ├─ Codex app-server / SDK │ ├─ CI / 测试矩阵 │ ├─ Thread Gateway │ ├─ Local Ops Agent │ ├─ Local Ops Audit Agent │ ├─ 长耗时任务 │ └─ 批处理任务 ├─ 5. 审计层 │ ├─ Audit Orchestrator │ ├─ Rules Audit Engine │ │ ├─ 超时检测 │ │ ├─ 卡死检测 │ │ ├─ 重复失败检测 │ │ ├─ 上下文压缩过多检测 │ │ ├─ 视频流 / 摄像头在线检测 │ │ └─ 额度异常检测 │ ├─ 软件审计 Agent │ ├─ 硬件审计 Agent │ ├─ 多模态审计 Agent │ └─ 总审计 Agent ├─ 6. 测试硬件能力层 │ ├─ Capability Registry │ ├─ Device Lease / Preemption │ ├─ Camera / Mic / Speaker │ ├─ Thumb Robot / Relay / USB 控制器 │ └─ 视频流 / 关键帧 / 传感器采样 └─ 7. 容灾层 ├─ 主控故障切换 ├─ 数据库备份恢复 ├─ worker 重派 ├─ 账号额度切换 ├─ 运维紧急修复 └─ 人工接管

四、技术实现方案

1. 手机端

2. 控制平面

3. Worker 节点

4. 线程与记忆策略

上下文预算等级 阈值 主 Agent 默认动作
`safe` `>= 60%` 正常推进任务,但持续刷新阶段摘要和关键证据引用。
`watch` `40% ~ 59%` 不再向该线程追加大块背景信息,开始准备阶段摘要和下一线程交接包。
`urgent` `25% ~ 39%` 优先完成当前原子子任务,同时预创建接力线程,确保 compaction 前完成 handoff。
`critical` `< 25%` 禁止继续扩张上下文,立即执行“压缩前收尾”:固化 patch、命令、测试结论、关键决策、未决问题和证据链接。

5. 额度监控集成(直接复用 gptpluscontrol)

6. 跨节点线程对话机制

7. 开发规格:线程地址、消息协议与监管模式

设计项 规格
线程全局地址 `{node_id}:{thread_id}`,例如 `mac-01:thread-abc`、`win-gpu-02:thread-xyz`。
Thread Registry 保存 `project_id`、`node_id`、`thread_id`、`role`、`status`、`allowed_peers`、`access_mode`、`last_seen_at`、`context_budget`。
消息 Envelope 至少包含 `message_id`、`project_id`、`sender_thread_ref`、`receiver_thread_ref`、`intent`、`summary`、`attachments`、`ttl_seconds`、`approval_mode`、`created_at`。
监管模式 `observe`、`approve_first`、`strict` 三种。默认项目内线程采用 `approve_first`。
传输链路 `Sender Thread -> Local Thread Gateway -> Inter-Thread Broker -> Receiver Gateway -> Receiver Thread`。
结果回传 目标线程回复后,结果按原路返回并写入双方 thread mirror,同时产生 broker 级事件日志。
失败处理 目标线程离线、超时、拒绝、权限不足时进入重试或 dead-letter 队列,并由主 Agent 决定重派、降级或人工介入。

8. 线程对话的权限与审计要求

9. UI 表达与产品交互

10. 开放式审计与硬件接管

11. 运维层与运维审计层

五、每个服务运行在哪台机器

服务 建议部署位置 原因
手机端 Web / App 手机浏览器 / App 只作为统一入口,不承担调度和记忆。
API 网关 + WebSocket 云服务器 保证外网访问稳定,统一所有设备接入。
Master Agent Runtime 云服务器主节点 主调度器不依赖个人电脑是否开机,适合持续运行。
Thread Registry / Inter-Thread Broker 云服务器 管理跨节点线程地址、权限、消息路由、重试和审计留痕。
Project Memory / Event Store / Postgres / Redis 云服务器或云数据库 需要集中存储,便于跨设备读取和灾难恢复。
gptpluscontrol Backend 云服务器 作为现成额度监控服务,提供账号、Agent、容量和 SSE 实时流。
Audit Orchestrator 云服务器 负责编排规则审计、软件审计、硬件审计、多模态审计和总审计结果汇总。
Ops Control Plane / Ops Policy Engine 云服务器 统一计算巡检模式、汇总节点健康、管理修复工单、审批策略与紧急接管规则。
Ops Extension Registry / Connector Runtime 云服务器 作为开放式主运维层的扩展入口,用来注册其他项目、其他服务、其他测试台的运维域、连接器和 Runbook Pack。
Chief Ops Audit Agent / Ops Ledger 云服务器 负责跨节点运维复核、主控离线时的最终修复判断、修复留痕与主控恢复后的同步汇报。
Rules Audit Engine 云服务器 与主控分离运行,持续监听任务和节点状态。
Specialist Audit Agents 云服务器 包含软件审计、硬件审计、多模态审计和总审计 Agent,按事件或策略触发。
Mac Worker Daemon 每台 Mac 本机 负责 Xcode、前端、macOS / iOS 相关开发任务。
Thread Gateway(Mac) 每台 Mac 本机 接收和发送本机线程消息,把跨节点对话接入 Broker。
gptpluscontrol Agent(Mac) 每台 Mac 本机 负责上报本机 Codex 当前账号、5h/7d 剩余额度、登录切换和心跳。
Local Ops Agent(Mac) 每台 Mac 本机 负责本机 Worker、Thread Gateway、Test Rig、gptpluscontrol Agent 等组件的巡检与修复执行。
Local Ops Audit Agent(Mac) 每台 Mac 本机 负责监督本机运维 Agent、复验修复动作、在主控离线时参与紧急修复判断。
Windows Worker Daemon Windows 本机的 WSL2 兼顾 Codex 兼容性和 NVIDIA / Windows 工具链调用。
Thread Gateway(Windows) Windows 本机的 WSL2 或本机桥接层 负责 Windows 线程与云端 Broker 之间的消息收发和状态同步。
gptpluscontrol Agent(Windows) Windows 本机 负责上报 Windows 节点的额度、当前绑定账号、Agent 在线状态和切换事件。
Local Ops Agent(Windows) Windows 本机或 WSL2 邻近桥接层 负责本机 Worker、GPU Bridge、Thread Gateway、测试桥的巡检与自愈执行。
Local Ops Audit Agent(Windows) Windows 本机或 WSL2 邻近桥接层 负责监督本机运维 Agent、复验修复动作、在主控离线时做本地紧急修复复核。
GPU Bridge / Windows 工具桥 Windows 本机 为 Mac 或云端 worker 暴露 GPU 推理和原生工具能力。
Test Rig Gateway / 硬件测试桥 挂载测试外设的 Mac / Windows / 独立测试台 向审计层暴露摄像头、麦克风、扬声器、拇指机器人、串口、继电器等可接管测试能力。
Cloud Worker Daemon 云服务器或云工作机 承担长耗时任务、批处理、CI、测试矩阵和后台流程。
Thread Gateway(Cloud) 云 worker 同机部署 负责云侧线程加入跨节点协作网络并接收主控监管。
Local Ops Agent(Cloud) 每台云 worker 同机部署 负责云 worker、线程网关、CI 进程、日志上报和修复脚本执行。
Local Ops Audit Agent(Cloud) 每台云 worker 同机部署 负责监督本机运维 Agent、复验修复动作、保障云侧节点自愈链路可用。
Standby Controller 第二台云服务器或同云异可用区 主控故障时接管调度。

六、主 Agent 怎么使用 ChatGPT 蓝色账号上的 Codex 额度

推荐方案
主控用 API,Worker 用 Plus 账号登录 Codex
  • 主 Agent 运行在云端,使用 API 模型做编排与决策。
  • 每个 worker 节点用一个 ChatGPT Plus 账号登录本机 Codex。
  • 调度器读取每个 worker 的限额和负载,把任务派给还有余量的节点。
  • 这种方式最稳,因为主脑不被单个桌面账号会话绑定。
可选方案
单独放一台 Master Codex Node
  • 单独一台机器运行“主控 Codex”,绑定一个蓝色账号。
  • 控制平面通过 Codex app-server / SDK 调用它,视它为主脑执行器。
  • 适合保留强烈的 Codex 使用体验,但稳定性低于 API 主脑方案。
  • 不建议把多个 Plus 账号设计成一个透明共享额度池,而是按节点账号分别调度。
关键澄清
云服务器上的纯主控服务,不能直接继承你的 ChatGPT Plus“最新模型额度”
  • 如果主 Agent 只是一个运行在云服务器上的 LangGraph / API 服务,它使用的是 API 计费和 API 限额,不会自动继承 ChatGPT Plus 的聊天或 Codex 订阅额度。
  • OpenAI 官方目前明确说明:ChatGPT 中的模型可用性与 Codex 分开管理,API 的可用性和价格也单独管理。
  • 所以你不能把“云上的主控 API 服务”直接视作“在吃 ChatGPT Plus 最新模型额度”。
如果你坚持要用 Plus 额度
要把主 Agent 变成一个“Master Codex Node”
  • 单独准备一台始终在线的机器,例如一台常开 Mac mini、常开 Windows WSL2 节点,或者你确认可稳定登录的云工作机。
  • 这台机器上登录一个 ChatGPT Plus 账号,让本机 Codex 作为“主脑执行器”。
  • 云上的控制平面不直接调用 Plus 额度,而是通过 app-server / SDK 去调用这台 Master Codex Node。
  • 这时消耗的是这台主控节点绑定账号的 Codex 配额,而不是云主控服务本身的 API 配额。
UI 要求
主控身份提示条的交互规范
  • 位置:主对话页顶部标题栏右侧,优先做成一个小胶囊标签,不占据大卡片区域。
  • 状态值:`主 GPT`、`备用 GPT`、`API 容灾`。
  • 展开信息:当前节点名、当前账号 display name、最近切换时间、切换原因。
  • 颜色建议:主 GPT 用蓝色,备用 GPT 用橙色,API 容灾用灰色或紫灰色。

七、向量库存在哪里

推荐位置
向量库放在云端,作为控制平面的集中记忆层
  • 建议和 `Postgres` 一起放在云服务器或云数据库中,MVP 阶段优先使用 `pgvector`,最简单也最稳。
  • 它保存的不是源代码本身,而是项目摘要、设计约束、阶段结论、排障经验、已知风险和历史决策。
  • 所有 worker 都只读写这一个“中心记忆库”,不要每台电脑各自维护一套主记忆。
为什么不放本地
本地只能有缓存,不能有主版本
  • 如果主记忆放在某台 Mac 或 Windows 本地,这台机器掉线时,主 Agent 就会失明。
  • 你要的是手机统一查看、跨设备协作,所以 canonical memory 必须在云端。
  • 本地 worker 可以保留短期缓存或索引副本,但最终真相必须回写到云端向量库和数据库。
方案 建议 适用阶段
Postgres + pgvector 最推荐,部署简单,备份和高可用可以与主数据库统一管理。 MVP 到中期产品
独立 Qdrant / Weaviate 当检索规模、性能、分片需求更高时再拆出。 中后期
每台 worker 本地向量库 不建议作为主记忆,只能做本地加速缓存。 仅优化阶段

八、Codex 剩余额度显示与 gptpluscontrol 集成

额度监控不新做,直接复用现有 `gptpluscontrol` 项目。当前项目已经具备云端 Backend、macOS / Windows Agent、REST API 和 SSE 实时刷新能力。

1. 推荐集成方式

2. 可以直接复用的数据接口

接口 用途
`GET /api/v1/agents` 读取每台设备的在线状态、当前 Codex 账号、5h/7d 剩余额度、最近切号和交接信息。
`GET /api/v1/accounts` 读取账号池列表、剩余额度、重置时间、当前使用状态、账号占用情况。
`GET /api/v1/accounts/{account_id}` 读取单个账号的详细历史、错误和趋势。
`GET /api/v1/dashboard/summary` 读取总账号数、正常数、失败数、在线 Agent 数量等总览卡片数据。
`GET /api/v1/capacity/report` 读取容量预警、剩余覆盖天数、预计耗尽时间和建议。
`GET /api/v1/events/stream` 通过 SSE 接收实时刷新事件,推动前端更新设备和额度状态。

3. 当前可直接利用的关键字段

4. App 里的 UI 设计要求

轻量状态提示
主会话顶部显示主控身份
  • 显示:`主 GPT` / `备用 GPT` / `API 容灾`。
  • 可加一个很小的副文本:当前账号简称或当前节点名。
  • 点击后展开完整状态,不默认铺满页面。
实时额度面板
项目页和节点页显示绑定 Codex 客户端剩余额度
  • 每个节点卡片显示:设备名、在线状态、当前账号、5h 剩余、7d 剩余。
  • 如果节点正在切号或等待人工登录,显示醒目的次级提示。
  • 额度不足时以黄 / 红两级预警。

5. 开发实现建议

九、跨节点线程对话机制

核心原则
逻辑直连,物理经主控转发

Mac、Windows、云节点上的线程可以互相对话,但消息必须经过 `Inter-Thread Broker` 和主控监管。

边界控制
默认同项目互通,跨项目需授权

线程通信受项目边界、角色边界、监管模式、TTL 和 turn 预算共同限制。

风险规避
不透传完整历史,防止上下文污染

默认只传摘要、必要附件和最近结论,避免两个线程互相放大无关上下文。

可开发的消息流

步骤 说明
1. 发送方封装请求 发送线程生成 `intent + summary + attachments`,交给本地 Thread Gateway。
2. Broker 做权限与策略检查 检查 sender / receiver 是否允许通信,是否同项目,是否超过 turn budget,是否需要主 Agent 审批。
3. 路由到目标节点 Broker 把消息转发到目标节点的 Thread Gateway,再交给目标 Codex 线程。
4. 目标线程执行 目标线程基于收到的摘要完成计算、读取文件、运行命令或请求本地硬件能力。
5. 结果回传 目标线程将摘要结果、状态、附件引用返回给 Broker,再回传给发送线程。
6. 留痕与展示 整段通信写入 Event Store,并在项目 UI 的“跨节点协作”时间线上展示。

推荐的 intent 类型

十、混合审计架构:规则审计 + 专项审计 Agent

风险
自我确认偏差

如果主 Agent 既派任务又自己评价自己,就容易忽略执行偏差、低效率循环和错误判断。

更稳做法
规则审计和多种审计 Agent 并存

规则引擎做硬性判断,专项审计 Agent 做语义判断,多模态和硬件场景由专门审计 Agent 接管。

主控职责
主 Agent 做调度,不独占系统真相

所有关键信息都写入事件库和项目记忆,主控只是当前执行者,而不是唯一记忆体。

建议的分工

组件 职责
主 Agent 任务拆分、节点选择、上下文裁剪、上下文预算管理、压缩前收尾调度、阶段调度、人工沟通。
Rules Audit Engine 检测超时、重复失败、压缩次数过多、rate limit、队列积压、worker 离线、视频流断开、测试进程缺失等硬规则异常。
软件审计 Agent 复核代码变更、测试覆盖、行为回归、接口契约、日志解释和发布风险。
硬件审计 Agent 复核固件版本、设备状态、串口日志、传感器读数、OTA 后行为和外设联动是否正确。
多模态审计 Agent 分析截图、关键帧、短视频、摄像头画面、音频片段,判断设备动作、屏幕状态和拟人化交互是否符合预期。
总审计 Agent 汇总规则审计和各专项审计的结论,给出通过、驳回、需人工复核和返工建议。

开放式硬件接管要求

十一、运维层与运维审计层

角色
Ops Agent 负责修,Ops Audit Agent 负责判与验

运维层负责发现问题和执行修复,运维审计层负责监督运维行为、判断权限、复验结果和紧急接管。

频率
高频使用时 5 分钟,空闲时 1 小时

高频模式看活跃用户、活跃任务、能力租约、现场测试和高优先级告警;全空闲时降到每小时一次。

兜底
主控失联后,运维审计层可紧急决策修复

只要主 Agent 在线且可正常响应,运维修复必须先经它同意;主控失联后才由运维审计层做最终修复判断。

主定位
运维层是主运维层,不只服务当前这一套系统

它既监管当前 Codex 多机协作系统,也作为统一运维底座接管后续其他项目、其他服务、其他测试台和其他机器群的运维场景。

开放式
通过 Domain / Connector / Runbook Pack 开放扩展

新项目接入时,不需要重写整套运维层;只要注册新的运维域、连接器类型、健康探针和修复剧本,就能接入主运维层统一监管。

1. 组件与职责

组件 职责
Ops Control Plane 汇总全局健康、管理巡检模式、修复工单、Runbook、开放式运维域和紧急接管策略。
Local Ops Agent 在每个节点本地巡检进程、日志、队列、额度、硬件桥和网关,并执行修复动作。
Local Ops Audit Agent 监督本地 Ops Agent 是否健康、是否越权、修复是否成功,并在主控离线时做紧急修复判断。
Chief Ops Audit Agent 做跨节点复核、处理主控失联下的最终修复判定、在主控恢复后回放修复结果。
Ops Extension Registry / Connector Runtime 负责把其他项目、外部服务、外部测试台通过标准化 Connector 与 Runbook Pack 接入主运维层。
Ops Ledger 保存故障、修复动作、复验结论、主控恢复回执和 Runbook 映射。

2. 日志命名与低 token 定位原则

3. 除日志之外必须增加的救援手段

4. 在线与离线两种修复模式

场景 决策链路
主 Agent 在线且能正常返回 `Ops Agent` 发现问题后先提交修复建议,由主 Agent 审批;审批通过后执行修复,再由 `Ops Audit Agent` 复验并回报主 Agent。
主 Agent 失联 `Ops Audit Agent` 确认主控失联并升级到 `Chief Ops Audit Agent`;运维审计层做最终修复执行判断,`Ops Agent` 执行修复,运维审计层复验并写入账本,待主控恢复后同步。

5. 当运维层自身挂了,但主 Agent 在线

6. 主控恢复后的回放要求

十二、容灾与故障恢复

1. 主控故障

2. 数据库故障

3. 单台 worker 故障

4. 账号或额度问题

5. 网络故障

6. 人工接管

十三、推荐的第一阶段落地方式

阶段 目标 部署
V1 先跑通 1 个主控 + 2 台 Mac + 1 台 Windows + 1 台云 worker 的项目调度、线程查看,以及每节点最小运维 Agent / 运维审计 Agent 心跳与修复工单。 主控和数据库在云端,worker 在各自本机;所有节点同步部署 Local Ops Agent 与 Local Ops Audit Agent。
V2 加入项目记忆、自动摘要、跨节点线程对话、规则审计、专项审计 Agent、限额调度、异常重派,以及主控离线下的运维紧急修复判定与复验。 新增向量库、线程 Broker、审计编排服务、Ops Control Plane、Chief Ops Audit Agent、备用控制器。
V3 加入开放式硬件接管、跨项目调度、GPU 任务编排、拇指机器人和多模态完整测试链路,以及多节点联动自愈和策略化运维。 扩展云 worker、Windows GPU 服务、硬件测试台、合成探针与更细粒度 Runbook 策略。

十四、中文思维导图

下面这块是压缩后的方案总览,适合快速过一遍全局逻辑,也方便你后面拿去继续讨论产品边界和开发排期。

Codex 多机协作产品 一个主 Agent,对接多台电脑上的 Codex 线程
产品目标
  • 手机端只保留一个主对话入口。
  • 同时调度 Mac、Windows、云服务器上的 Codex。
  • 每个项目可查看聊天记录、命令、补丁和状态。
  • 通过多短线程和外部记忆解决长上下文退化。
核心技术
  • LangGraph 作为主控编排引擎。
  • Codex app-server / SDK 作为 worker 接入层。
  • Project Memory 保存项目目标、约束、摘要和决策。
  • Event Store 镜像 thread、命令、patch、审批和告警。
  • Inter-Thread Broker 让 Mac / Windows / 云线程在监管下互相协作。
  • 混合审计层可接管摄像头、音频和机器人外设做硬件测试。
  • 运维层和运维审计层负责动态巡检、修复审批、复验和主控失联兜底。
部署位置
  • 云服务器运行主控、数据库、审计、实时推送。
  • 每台 Mac 本机运行 Mac Worker Daemon。
  • Windows 通过 WSL2 运行 Worker,并桥接 GPU 能力。
  • 云 worker 负责 CI、长任务、批处理和后台执行。
  • 所有接入节点都必须常驻 Local Ops Agent 和 Local Ops Audit Agent。
容灾策略
  • 主控状态外置,Standby Controller 可接管。
  • Postgres 高可用,事件日志回写对象存储。
  • worker 心跳检测,故障后自动重派任务。
  • 按节点监控 Codex 额度,账号异常时自动切换。
  • 主控失联时由运维审计层做紧急修复判断,恢复后自动回放修复报告。

十五、开发规格文档入口

下面这份文档已经单独整理成可直接开发的协议规格,建议后续数据库、API、消息总线、前端联调都以它为准,不再从正文里反复抽取定义。

主规格
Capability Registry 与审计 Agent 协议开发规格
  • 定义能力提供方、能力实例、租约、会话、证据的核心实体。
  • 定义摄像头、麦克风、扬声器、串口、拇指机器人、继电器、电源、屏幕采集等能力类型。
  • 定义注册、心跳、租约、续租、释放、抢占和事件流。
  • 定义软件审计、硬件审计、多模态审计、总审计的输入输出协议。
  • 包含最小数据库表建议和 MVP 演进路径。
开发拆解
开发子任务与交付计划
  • 把余下设计工作拆成 `A ~ H` 共 8 个工作包。
  • 覆盖数据库、API、状态机、设备端预部署、前端字段、安全边界、演练与验收。
  • 每个子任务都带目标、输出、依赖、优先级和验收标准。
  • 明确哪些内容必须先冻结,哪些内容可以并行开发。
  • 适合作为接下来正式开工的总任务入口。
UI 参考
中国区产品 UI 参考库
  • 按“单入口、项目页、设备页、运维页、硬件页、AI 助手页”拆分参考对象。
  • 覆盖飞书、钉钉、企业微信、向日葵、ToDesk、腾讯云助手、阿里云 App、观测云、PingCode、TAPD、米家、腾讯元宝等。
  • 每个参考对象都标出:为什么适合参考、最值得借的 UI 点、官方来源。
  • 适合直接作为后续产品原型和设计稿的输入清单。
首页冻结
微信式项目会话首页映射规格
  • 把第一屏冻结成“主 Agent 置顶 + 项目会话列表”的微信式结构。
  • 定义项目会话如何和设备端 GUI 项目文件夹一一对应。
  • 定义单设备头像、群聊式组合头像、最近消息排序和手动置顶规则。
  • 定义首页最小字段、建议新增的数据对象和前端展示边界。
  • 适合作为首页和会话列表开发的直接规格。
上下文预算
线程上下文预算与压缩前接力协议
  • 冻结设备端线程上下文预算的上报字段、阈值、事件和 handoff 包。
  • 定义首页圆环进度标记、项目详情页展开和 BFF 返回结构。
  • 明确主 Agent 在 `safe / watch / urgent / critical` 四个等级下的默认动作。
  • 把“压缩前收尾”提升成正式调度规则,而不是临时经验。
文档路径

Markdown 规格文档:
capability_registry_and_audit_protocol_cn.md

运维规格文档:
ops_layer_and_repair_protocol_cn.md

技术选型文档:
detailed_technical_stack_cn.md

开发子任务文档:
development_subtasks_and_delivery_plan_cn.md

中国区 UI 参考库:
china_ui_reference_apps_cn.md

微信式会话首页规格:
wechat_project_conversation_mapping_cn.md

上下文预算规格:
thread_context_budget_and_handoff_protocol_cn.md

本机绝对路径:
/Users/kris/code/Talking/capability_registry_and_audit_protocol_cn.md

/Users/kris/code/Talking/ops_layer_and_repair_protocol_cn.md

/Users/kris/code/Talking/thread_context_budget_and_handoff_protocol_cn.md

/Users/kris/code/Talking/detailed_technical_stack_cn.md

/Users/kris/code/Talking/development_subtasks_and_delivery_plan_cn.md

/Users/kris/code/Talking/china_ui_reference_apps_cn.md

/Users/kris/code/Talking/wechat_project_conversation_mapping_cn.md

建议的直接开发顺序

顺序 先做什么 原因
1 建 `capability_providers` / `capabilities` / `capability_leases` / `audit_requests` 等基础表 先把注册、租约、任务账本落库,后续协议才有稳定主键和状态流。
2 做 Capability Gateway 的注册、心跳、租约接口 这是摄像头、串口、机器人接入和后续抢占的最小闭环。
3 做 Audit Orchestrator 和三类专项审计任务协议 先打通任务下发和结构化结果回收,后面再接真实模型与硬件。
4 接 Evidence Collector 和对象存储 没有证据归档,多模态和硬件审计无法复盘。
5 接前端项目页的能力占用、审计结果、抢占事件展示 这样手机端和 Web 控制台才能真正看到系统状态,不只是跑后台逻辑。

十六、当前流程思维导图图片版

这张图把当前已经确定下来的主流程、执行层、审计层、能力层和容灾层压成一张图,适合直接对着讨论开发边界和服务拆分。

Codex 多机协作当前流程思维导图

十七、业务流程思维导图图片版

这张图专门从业务推进角度整理,从你发起项目、主控拆任务、多机开发、审计复核、硬件测试到结果交付和异常恢复,每个环节都标了使用的关键技术。

Codex 多机协作业务流程思维导图

十八、业务流程泳道图图片版

如果你想更直观看“谁在什么时候做什么”,就看这张泳道图。它现在把用户、主 Agent、Worker、审计层、硬件能力层、运维层 / 运维审计层、数据与容灾层拆成 7 条泳道,并标出了关键技术、开放式运维接入和反向抢救切换点。

Codex 多机协作业务流程泳道图

十九、运维与抢修泳道图图片版

这张图专门把运维层和运维审计层拆开,展示动态巡检、日志命名、主控在线审批、主控离线紧急接管、修复复验和主控恢复回放的完整闭环。

运维层与运维审计层抢修流程泳道图

二十、详细技术栈建议

下面这版是“可以直接开工”的技术选型,不再停留在抽象架构层,重点回答:用什么语言、什么数据库、什么消息总线、什么向量库、什么对象存储、什么观测体系。

前端
TypeScript + Next.js 15 + React 19

先做 PWA / Web 控制台,再视情况封装原生 App。这样手机端和管理后台可以共用一套组件和状态流。

云端控制平面
Python 3.12 + FastAPI + LangGraph

主控编排、审计编排、运维编排、Capability Registry、Thread Registry 都建议统一到 Python 栈。

Worker / Agent / Gateway
Python 3.12

因为需要深度对接 Codex app-server / SDK、串口、音视频、硬件测试和多模态审计,Python 最顺手。

推荐选型 理由
主数据库 `PostgreSQL 16` 项目、任务、线程、审计、Capability、运维工单都能统一管理,事务和 JSONB 足够稳。
向量库 `pgvector` 起步,后期再考虑 `Qdrant` MVP 阶段最简单,和主库同备份;规模上来后再拆独立向量库。
缓存 / 锁 极轻云默认先不用,后续按需补 `Redis 7` MVP 先用 Postgres 行锁和应用内 TTL cache 顶住,放大后再补 Redis。
事件总线 极轻云默认 `Postgres job table + LISTEN/NOTIFY`,后续可升级 `NATS JetStream` 先保住功能,不先引入额外常驻服务;等并发和消息量上来再升级。
对象存储 极轻云默认本机短期缓存 + 异步备份,后续可接 `S3 / MinIO` 云端不常驻对象存储服务,原始大证据尽量留在边缘节点。
监控指标 极轻云默认健康探针 + 结构化指标表,后续可接 `Prometheus + Grafana` 先保住健康检查和关键指标,不先上重型观测栈。
日志检索 MVP 用 `Postgres + JSON 日志`,中期补 `ClickHouse` 先快落地,后面再把高吞吐 fault_key 检索单独拆出。

跨设备运维的具体落地

二十一、极限轻云方案(同时考虑容灾)

这里不是因为服务器小才降配,而是无论云服务器配置如何,都主动把云端压缩到最轻;同时保留双云容灾,但让备云只承担接管准备,不承担常态重负载。

保留
云端只保留控制面核心

建议保留 `FastAPI BFF + Master Agent + Audit Orchestrator + Ops Control Plane + PostgreSQL + pgvector`,其余尽量不常驻。

降配
去掉额外常驻中间件

默认先不单独上 `Redis`、`NATS`、`Qdrant`、`ClickHouse`、`MinIO`,优先用单体服务 + Postgres 顶住。

下沉
把重活前移到终端

视频流、音频流、OCR、检测、串口长采集都放到 Mac / Windows / Test Rig 节点先做边缘处理,只上传摘要、关键帧和异常片段。

最值得做的减法

双云容灾下怎么做轻量化

不建议放在云端长期常驻的

这套极轻云方案能保住什么

二十二、矛盾点与取舍矩阵

这里不是继续堆技术,而是明确说明:在“云端尽可能轻”和“原有业务能力不能砍”之间,哪些可以换实现位置,哪些是唯一真正的硬矛盾。

矛盾点 推荐取舍
手机端要随时看项目进度,但云端又要极轻 保留文本线程、状态、摘要、故障、修复结果实时上云;原始视频、音频、大日志改为按需回传,不持续上传。
要多机实时协作,但不想跑重消息系统 保留跨节点协作能力,把 `NATS` 降成 `Postgres job queue + LISTEN/NOTIFY`;功能不砍,但吞吐上限降低。
要主控层、审计层、运维层都在,但云内存很小 保留逻辑角色,不保留多常驻进程;改成单体服务里的模块 + 按需执行器。
要跨设备运维,还要开放式主运维层 云端只做编排和审批,具体修复动作下沉到目标节点的 `Local Ops Agent` 本地执行。
要多模态、硬件测试,但云带宽和云成本都要压低 保留测试闭环,放弃原始流持续上云;边缘先做裁剪、摘要、关键帧、短片段。
既要云端尽可能轻,又要云端容灾 保留双云,但让 `Cloud B` 只做热备 / 温备,不承担常态重负载。主云承担业务,备云承担接管准备。

最终建议

二十三、极限轻云双云部署拓扑图图片版

这张图把最终确定下来的部署原则画成了可落地的拓扑:`Cloud A` 只承担主用控制面和主库,`Cloud B` 只承担热备 / 温备和接管准备,所有重执行、重媒体、重测试、重运维动作全部下沉到设备端。

极限轻云双云部署拓扑图

二十四、双云最低配置速览

在“云端尽可能轻”且“不能明显降低稳定性和业务保障能力”的前提下,我建议按下面这个下限准备两台云服务器。

角色 硬最低可跑 推荐最低要求
`Cloud A`(主用) `2 vCPU / 4 GB / 80 GB SSD` `2 vCPU / 8 GB / 100 GB SSD`
`Cloud B`(备用) `2 vCPU / 4 GB / 80 GB SSD` `2 vCPU / 8 GB / 100 GB SSD`

二十五、两种保活模式

系统从设计上同时支持两种备用接管路径:`单云 + 单 Mac 备用控制器`,以及 `双云热备 / 温备`。部署时可以二选一,也可以同时启用。

两种保活模式对比图
模式 组成 优点 边界
`单云 + 单 Mac 备用控制器` `Cloud A` + 一台常开 `Standby Mac` 更省云成本,本地接管更快,适合已有常开 Mac mini 的环境。 如果主云和现场 Mac 同时断电或断网,这条链路也会失效。
`双云热备 / 温备` `Cloud A` + `Cloud B` 公网可达性更稳,不依赖现场某一台设备,接管路径更标准化。 成本更高;最后一跳的硬件接管仍要依赖现场设备在线。

模式 A:单云 + 设备端备用池(首选单 Mac)

模式 B:双云热备 / 温备

统一抽象

二十六、还能不能继续压缩云服务器

可以,但要分清楚“功能还能跑”和“稳定性与业务保障能力不明显下降”不是一回事。这里把可继续压缩的边界和不能继续下沉的系统真相拆开。

先给结论

哪些能力还能继续下沉到设备端

能力 继续压云的做法 云端仍需保留的真相
Embedding 生成 在 worker / audit 节点本地生成 embedding,再写回云端。 向量、chunk 元数据、项目记忆索引。
长日志处理 本地先裁剪、归类 fault_key、保留最后 N 行再上传。 fault ledger、工单、修复记录。
视频 / 音频处理 本地做关键帧、短片段、OCR、检测,只传证据摘要。 证据索引、审计结论、回放引用。
审计执行 尽量在拥有能力的节点本地跑专项审计。 审计工单、复验结论、风险等级。
Test Rig 控制 摄像头、串口、机器人、麦克风、扬声器一律本地网关执行。 租约、抢占真相、任务结论。
运维修复动作 重启、拉日志、切账号、跑 runbook 都在目标节点本地执行。 审批、修复工单、复验结果。
额度轮询 每台机器本地采集 Codex 额度,再定时回报精简状态。 统一额度看板、切换历史。

哪些东西不能继续往本地下沉

单服务器 + 设备端保活时,设备端掉线怎么办

这个切换会不会很慢

二十七、API-first / Local-first 极限压缩模式

可以把云端进一步压轻。思路不是把业务砍掉,而是把“云端常驻重服务”改成“外部 API 调用 + 设备端本地执行”,让云端只做最小控制面和最小系统真相。

这套模式的核心原则

哪些业务适合 API 化

哪些业务更适合本地化

这条线下的起步配置

按设备数和任务数弹性升级