krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07ecce3d0dfe5d17233302dadb04fc07c196c2a5
boss/docs/architecture/development_subtasks_and_delivery_plan_cn.md

17 KiB
Raw Blame History

Codex 多机协作系统开发子任务与交付计划

这份文档的目标不是重复架构，而是把“余下的设计工作”彻底拆成可以直接进入开发的子任务。

当前阶段进度（2026-03-30）

当前仓库已经不再停留在“纯设计待开发”，而是完成了第一轮可运行闭环：

  • Web 控制面、主 Agent 任务队列、local-agent、原生 Android、部署链路均已跑通
  • 原生 Android 已完成微信式首页回退、线程=会话窗口、独立群聊、会话改名、消息转发、附件发送与 OTA 下载主链
  • 主 Agent 已具备 task queue -> local-agent -> codex exec -> complete 的基础执行链
  • 设备接入已具备草稿、pairing code/token、claim 与首次心跳的最小链路

当前真正还缺的是“业务主链补完”，尤其是下面两段：

  1. 会话/群聊/主 Agent 调度主链

    • 群聊消息先进入主 Agent
    • 主 Agent 推荐下发目标线程
    • 用户确认后再正式下发
    • 线程原始结果回群 + 主 Agent 汇总
    • development / approval_required 协作模式接入正式消息链

  2. 添加设备 -> 项目候选 -> Agent 理解 -> 会话导入主链

    • 不再只靠手填项目字符串
    • 设备首次接入后上报真实候选文件夹/线程
    • 用户勾选导入
    • 主 Agent 理解后映射成正式聊天窗口

当前建议把“余下开发”拆成 4 个工作包推进：

  • WP1. 当前进度与交接文档收口
  • WP2. 会话/群聊/主 Agent 编排与审批主链
  • WP3. 设备项目候选、勾选导入与 Agent 理解映射
  • WP4. 按现有 UI 全量功能做逻辑审计与补洞

本轮开发默认先做 WP1 + WP2，随后再进入 WP3 + WP4。

截至 2026-03-30 的最新进度补充：

  • WP1 已持续回写到 README.md、current_runtime_and_deploy_status_cn.md、api_and_service_inventory_cn.md
  • WP2 已完成到“可运行闭环”的第一阶段：
    • 群聊文本消息会先进入主 Agent 生成 dispatchPlan
    • 用户已可通过确认接口批准目标线程
    • 系统会创建真正的 dispatchExecution
    • local-agent 已可认领 dispatch_execution 任务
    • 执行完成后会把线程原始结果回群，并补一条主 Agent 汇总
  • WP3 已完成到“后端闭环第一阶段”：
    • 设备 heartbeat 可上报真实项目候选
    • 服务端会生成 deviceImportDraft
    • 用户可提交候选勾选结果
    • 系统可生成导入决议并应用到真实聊天窗口
    • 下一阶段重点转为 Web / Android 页面接线和真机回归

适用范围：

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

13. 2026-03-30 当前推进记录

已完成：

  • 群聊主链已经具备 主 Agent 推荐下发 -> 用户确认 -> dispatchExecution -> local-agent 认领 -> 线程原始结果回群 -> 主 Agent 汇总 的后端闭环
  • 新设备导入主链已经具备 heartbeat -> import draft -> select -> review -> apply 的后端闭环，并补了 owner/admin 鉴权与幂等保护
  • 已绑定的生产设备当前新增自动同步链路：如果 heartbeat 携带真实 projectCandidates[]，服务端会自动完成建议项选择、导入决议和应用，把真实 Codex 线程直接落成会话窗口
  • 本机 mac-studio 当前已经验证可通过 local-agent 直接从 ~/.codex/state_5.sqlite / logs_1.sqlite / session_index.jsonl / .codex-global-state.json 扫描真实 Codex 线程，并通过 heartbeat 自动导入到远端会话列表
  • 会话首页当前已切到“项目聚合 + 线程下钻”视图：单线程项目直接显示线程，多线程项目先聚合成文件夹归档，再进入线程列表页
  • Web / Android 当前都已补上“新设备候选项目勾选、决议预览、应用导入”的前台页面
  • 原生首页刷新失败策略当前已改成按当前 tab 独立判错，不会再因为旁路接口失败把会话刷新一并判成失败

当前仍待前台接线：

  • 群聊 development / approval_required 审批闸口的前台确认页
  • 真机逐页把新增业务流接入现有微信式 UI