# Codex 多机协作系统开发子任务与交付计划 这份文档的目标不是重复架构，而是把“余下的设计工作”彻底拆成可以直接进入开发的子任务。 适用范围： - 单主 Agent - 多台 Mac / Windows / Cloud Worker - 审计层 / 运维层 / 容灾层 - `单云 + standby_device_pool` - `双云热备 / 温备` - `API-first / local-first` 极限轻云模式 相关主文档： - `/Users/kris/code/Talking/codex_multi_machine_architecture_cn.html` - `/Users/kris/code/Talking/detailed_technical_stack_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` --- ## 1. 设计完成定义 当下面这 6 件事全部完成时，就可以认为“余下设计工作收口完成”，开发可以正式展开： 1. 核心数据模型全部冻结。 2. 对外 API / 设备端 API / 事件协议全部冻结。 3. 关键状态机全部冻结。 4. 前端页面、字段、实时更新源全部冻结。 5. 部署形态、启动方式、主备切换方式全部冻结。 6. MVP 验收标准和演练清单全部冻结。 --- ## 2. 子任务总览 总共拆成 8 个工作包： - `A. 核心领域模型` - `B. API 与事件协议` - `C. 状态机与切换逻辑` - `D. 设备端运行时与预部署标准` - `E. 前端 / 手机端交互规格` - `F. 安全、配置与运维边界` - `G. 测试、演练与验收标准` - `H. 开发排期与并行策略` 建议优先级： - `P0`：A、B、C、D - `P1`：E、F - `P2`：G、H --- ## 3. 工作包 A：核心领域模型 ### A1. 项目 / 任务 / 线程账本模型 目标： - 冻结主数据库中的系统真相模型。 输出： - `projects` - `tasks` - `task_assignments` - `threads` - `thread_context_snapshots` - `thread_messages` - `thread_events` - `thread_artifacts` - `project_conversations` - `project_goals` - `project_goal_revisions` - `version_iteration_reports` - `message_forwards` 必须定义： - 主键策略 - 项目状态枚举 - 任务状态枚举 - 线程状态枚举 - 线程与任务、任务与项目的关联 验收： - 能支持“一个项目 -> 多任务 -> 多线程 -> 多节点” - 能支持线程镜像和聊天记录回放 - 能支持“首页项目会话列表 -> 项目聊天页 -> 底层线程系统”的映射 - 能支持“压缩前收尾 / 摘要接力 / 线程轮换”的上下文预算判断 依赖： - 无 优先级： - `P0` ### A2. 主控记忆与向量检索模型 目标： - 冻结项目主记忆、摘要和向量索引的最小模型。 输出： - `memory_documents` - `memory_chunks` - `memory_embeddings` - `decision_ledger` - `summary_snapshots` 必须定义： - chunk 粒度 - embedding model metadata - retrieval key - 热数据 / 冷数据分层 验收： - 支持“线程重启但项目记忆不丢” - 支持以后迁移到外部向量库 依赖： - A1 优先级： - `P0` ### A3. 额度与账号状态模型 目标： - 冻结主 GPT / 备用 GPT / API 容灾 / worker 额度态的统一模型。 输出： - `accounts` - `account_usage_snapshots` - `worker_account_bindings` - `account_switch_history` - `device_profiles` - `device_status_snapshots` 必须定义： - 主账号状态 - 备用账号状态 - API fallback 状态 - 5h / 7d 剩余额度字段映射 验收： - 手机端可显示统一账号态小胶囊和 worker 额度列表 - 手机端设备页可展示设备状态、账号、项目和 5h / 7d 额度 依赖： - 无 优先级： - `P1` ### A4. 审计与能力模型 目标： - 把 capability registry、租约、证据、审计工单、审计结果的数据库模型冻结。 输出： - `capability_providers` - `capabilities` - `capability_leases` - `capability_sessions` - `capability_artifacts` - `audit_jobs` - `audit_results` 验收： - 支持摄像头 / 串口 / 拇指机器人 / 麦克风 / 扬声器租约和审计闭环 依赖： - A1 优先级： - `P0` ### A5. 运维与容灾模型 目标： - 冻结运维账本、修复工单、备用池和接管包模型。 输出： - `ops_faults` - `ops_repair_tickets` - `ops_repair_verifications` - `standby_devices` - `standby_device_scores` - `standby_device_packages` - `standby_failover_history` 验收： - 支持单云备用池 - 支持双云热备 / 温备 - 支持主控恢复后的修复回放 依赖： - A1 优先级： - `P0` --- ## 4. 工作包 B：API 与事件协议 ### B1. 手机端 / Web BFF 协议 目标： - 冻结手机端所需的聚合接口。 输出： - 项目列表接口 - 项目详情接口 - 线程详情接口 - 线程上下文预算接口 - 主控身份状态接口 - worker 额度态接口 - 告警与修复工单接口 验收： - 手机端无需直接拼接多个后端来源 依赖： - A1 / A3 / A5 优先级： - `P0` ### B2. Worker 注册与心跳协议 目标： - 冻结每台 Mac / Windows / Cloud Worker 的接入协议。 输出： - worker register - worker heartbeat - worker capability update - worker account usage update - worker thread context update - worker artifact publish 验收： - 控制面能感知每台设备是否在线、能做什么、剩余额度多少 - 控制面能感知每条线程当前上下文预算、预计压缩时间和风险等级 依赖： - A1 / A3 / A4 优先级： - `P0` ### B3. Thread Broker 协议 目标： - 冻结跨节点线程对话的消息 envelope。 输出： - send - ack - reject - timeout - reply - escalation 必须定义： - `sender_thread_id` - `receiver_thread_id` - `intent` - `summary` - `attachments` - `ttl` - `approval_mode` 验收： - 可支持 Mac -> Windows、Windows -> Mac、Cloud -> Device 对话 依赖： - A1 优先级： - `P0` ### B4. 审计编排协议 目标： - 冻结软件审计、硬件审计、多模态审计、总审计的任务协议。 输出： - audit submit - audit claim - audit result - audit evidence manifest - audit final verdict 依赖： - A4 优先级： - `P0` ### B5. 运维与容灾协议 目标： - 冻结 repair、rescue、standby promotion、takeover package 的 API。 输出： - repair request - repair approval - repair result - rescue enter - rescue action - standby device register - takeover package sync - standby promotion 依赖： - A5 优先级： - `P0` --- ## 5. 工作包 C：状态机与切换逻辑 ### C1. 任务状态机 必须定义： - draft - planned - dispatched - running - waiting_review - blocked - done - failed - canceled 验收： - 任意任务都能追踪“由谁派发、在哪里运行、为何阻塞” ### C2. 线程状态机 必须定义： - idle - running - waiting_input - waiting_approval - context_watch - context_urgent - compacted - handoff_pending - completed - failed 验收： - 支持长上下文线程轮换与摘要接力 - 支持主 Agent 在压缩前优先收尾、切线程和提前交接 ### C3. 审计状态机 必须定义： - queued - claimed - executing - waiting_capability - waiting_evidence - verified - rejected - needs_human ### C4. Repair Ticket 状态机 必须定义： - opened - waiting_master_approval - waiting_ops_audit_decision - executing - verifying - verified - failed - replayed_to_master ### C5. `standby_provider` 状态机 必须定义： - single_cloud_with_device_pool - dual_cloud - both ### C6. `active_standby_device` 切换状态机 必须定义： - candidate - warm_standby - hot_standby - active_standby - degraded - ejected 关键规则： - `cold standby` 不允许走自动切换 - 只有 `warm/hot standby` 能被自动提升 优先级： - 全部 `P0` --- ## 6. 工作包 D：设备端运行时与预部署标准 ### D1. Worker 节点最小安装包 输出： - `worker-daemon` - `thread-gateway` - `local ops agent` - `local ops audit agent` - `gptpluscontrol agent` - 配置模板 - 日志目录约定 验收： - 一台新 Mac / Windows 节点可在 30 分钟内纳入系统 ### D2. `warm standby` 设备预部署清单 输出： - `Standby Controller` - `Ops Rescue Gateway` - 最小运行时依赖 - endpoint 缓存 - `takeover_package` 验收： - 备用设备不需要临时部署才能接管 ### D3. `takeover_package` 规范 输出： - 内容清单 - 同步频率 - 版本号规则 - 校验和规则 - 失效策略 验收： - 设备掉线时能在目标时间内完成角色切换 ### D4. Windows WSL2 / Mac / Cloud 差异表 输出： - 路径规范 - 服务启动方式 - GPU bridge 调用方式 - 串口 / USB / 音频 / 摄像头权限要求 优先级： - D1 / D2 / D3 为 `P0` - D4 为 `P1` --- ## 7. 工作包 E：前端 / 手机端交互规格 ### E1. 页面清单冻结 必须包含： - 登录页 - 注册页 - 忘记密码页 - 会话列表首页 - 设备页 - 我的页 - 项目聊天页 - 项目目标页 / 抽屉 - 版本迭代记录页 / 抽屉 - 转发到项目页 - 线程详情页 - 添加设备页 - 设备长按操作菜单 / Action Sheet - 账号与安全页 - 关于 / OTA 页 - 审批中心 - 运维与修复页（`我的 > 运维与修复`） - 审计对话页（`我的 > 运维与修复 > 审计对话`） - 额度与账号状态页 - 告警 / 修复记录页 ### E2. 每页字段冻结 必须明确： - 哪些字段来自 BFF - 哪些字段实时刷新 - 哪些字段只读 - 哪些字段可操作 必须额外冻结： - 首页会话列表的排序字段 - 单设备头像 / 群聊头像的渲染字段 - 首页会话列表右侧三层信息轨字段 - 首页会话列表第三层圆环上下文余量指示器字段和样式 - 设备页的状态点颜色、账号字段、项目摘要字段、额度字段 - 设备页长按菜单字段和权限 - 我的页的头像、账号、二维码、账号与安全、关于、OTA 字段 - 我的页头部资料卡中二维码的右侧入口布局 - OTA 红点显示条件与 `立即 OTA` 触发字段 - `项目目标` 的可编辑字段 - `项目目标` 的完成状态字段、完成时间字段、删除线展示规则 - `版本迭代记录` 的只读字段 - 登录 / 注册 / 忘记密码页的验证码字段和发送状态字段 - 图片 / 视频 / 语音 / 转发入口的交互状态 - 底部三栏导航的图标、激活态和页面映射 ### E3. 实时更新策略 必须明确： - `SSE` 订阅列表 - 首屏加载接口 - 离线重连策略 - endpoint 切换提示策略 ### E4. 主控身份提示条 必须明确： - 展示：`主 GPT / 备用 GPT / API 容灾` - 是否显示切换时间 - 是否显示节点名 - 点击后跳到什么详情页 优先级： - E1 / E2 / E3 为 `P1` - E4 为 `P1` --- ## 8. 工作包 F：安全、配置与运维边界 ### F1. 配置分层 必须明确： - 云端配置 - 设备端配置 - 站点级配置 - 机型差异配置 - 测试 rig 配置 ### F2. 密钥与令牌边界 必须明确： - 哪些密钥只能在云端 - 哪些只允许设备端短期持有 - 哪些通过短期签发下发 ### F3. 故障命名规范冻结 必须明确： - `LAYER.DOMAIN.COMPONENT.ACTION.ERROR_CODE` - fault severity - runbook 映射规则 ### F4. 权限边界 必须明确： - 主 Agent 能批准什么 - Ops Agent 能执行什么 - Ops Audit Agent 能否紧急批准什么 - 审计 Agent 能接管哪些能力 优先级： - 全部 `P1` --- ## 9. 工作包 G：测试、演练与验收标准 ### G1. 基础联调验收 验收项： - 手机端能看到项目、线程、额度和账号态 - 主 Agent 能派发到 2 台以上设备 - worker 事件能实时镜像 ### G2. 跨节点线程对话验收 验收项： - Mac 线程请求 Windows 线程 - Windows 线程回复 Mac 线程 - 全链路有审计和回放 ### G3. 审计验收 验收项： - 软件审计一条通过 - 硬件审计一条通过 - 多模态审计一条通过 - 总审计给出最终 verdict ### G4. 运维验收 验收项： - 主控在线修复链路跑通 - 主控失联时紧急修复链路跑通 - 修复后回放到主控 ### G5. 容灾验收 验收项： - `warm standby` 自动接棒 - `Cloud B` 接棒 - endpoint 清单切换 - 主控恢复后的状态对账 优先级： - G1 / G2 / G4 / G5 为 `P1` - G3 为 `P2` --- ## 10. 工作包 H：开发排期与并行策略 ### 第一波并行组 - `Track 1` - A1 / A2 / A5 - B1 / B2 / B5 - C1 / C4 / C5 / C6 - `Track 2` - A4 - B4 - D1 / D2 / D3 - `Track 3` - E1 / E2 / E3 / E4 - 与 BFF 协议联动 ### 第二波并行组 - `Track 4` - B3 - C2 - 跨节点线程对话联调 - `Track 5` - F1 / F2 / F3 / F4 - G4 / G5 ### 开发前必须先冻结的内容 - A1 - A5 - B1 - B2 - B5 - C6 - D2 - D3 - E1 如果这些没冻结，就不要正式开写主业务代码。 --- ## 11. 建议的直接开发顺序 1. 先冻结数据库表和状态机。 2. 再冻结 BFF、Worker、Ops、Standby 的 API。 3. 同时做设备端预部署清单和 `takeover_package`。 4. 然后做手机端页面字段和 SSE 刷新契约。 5. 最后补演练脚本和验收清单。 --- ## 12. 一句话结论 接下来不应该再继续扩架构想法了。 最合理的做法是：以这份子任务清单为边界，把数据库、API、状态机、设备预部署、前端字段、验收脚本逐项冻结，然后直接进入开发。