boss/docs/architecture/development_subtasks_and_delivery_plan_cn.md

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、状态机、设备预部署、前端字段、验收脚本逐项冻结，然后直接进入开发。