+
+ 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. 手机端
+
+ - 建议先做 PWA 或响应式 Web 控制台,再按需要封装成 iOS / Android App。
+ - 页面包括:主对话页、项目列表页、项目线程页、审批中心、节点状态页、告警页。
+ - 所有实时状态通过 WebSocket 推送,点开项目后直接读取 thread mirror 和增量事件。
+ - 主对话页顶部增加一个非常轻量的“当前主控身份提示条”,只占一行小胶囊区域,显示当前主脑来源:`主 GPT`、`备用 GPT` 或 `API 容灾`。
+ - 这个提示条默认只显示 3 段信息:当前身份、所在线节点、最近切换时间;点击后再展开完整详情,不占据主聊天区。
+
+
+ 2. 控制平面
+
+ - 主控服务放在云服务器,避免主调度器依赖某一台个人电脑。
+ - LangGraph 负责任务拆解、状态流转、checkpoint 恢复和人工介入。
+ - Project Memory 负责保存项目目标、约束、阶段总结、未决问题、关键决策。
+ - Scheduler 根据节点能力、系统负载、Codex 限额和任务类型选择执行节点。
+
+
+ 3. Worker 节点
+
+ - 每台 Mac、Windows、云服务器都运行一个 worker daemon。
+ - worker daemon 连接本机 Codex app-server / SDK,启动和恢复线程,读取事件并上传到事件库。
+ - 每个任务使用独立 worktree / branch,避免不同线程直接写同一个工作目录。
+ - Windows 节点建议用 WSL2 跑 worker,本地 GPU、PowerShell、原生程序通过桥接服务暴露。
+
+
+ 4. 线程与记忆策略
+
+ - 每个项目不是一个超长线程,而是多个短线程:功能线程、修复线程、实验线程、评审线程。
+ - 线程执行结束后,worker 自动回传阶段摘要、关键文件、风险、测试结果和待办。
+ - 主控只把最小必要上下文派给下一次线程,避免长期上下文压缩导致能力下降。
+ - 每个 worker 必须持续上报线程上下文预算:`context_budget_remaining_pct`、`context_budget_level`、`compaction_expected_at`。
+ - 手机端会话列表第三层使用统一的圆环进度标记显示“背景信息窗口余量”,该标记与设备端线程页保持一致,不能由前端自行估算。
+ - 主 Agent 必须把“压缩前收尾”当成一等公民,在上下文预算进入危险区前优先完成关键结论固化、补丁固化、测试结论固化和线程交接。
+
+
+
+
+
+ | 上下文预算等级 |
+ 阈值 |
+ 主 Agent 默认动作 |
+
+
+
+
+ | `safe` |
+ `>= 60%` |
+ 正常推进任务,但持续刷新阶段摘要和关键证据引用。 |
+
+
+ | `watch` |
+ `40% ~ 59%` |
+ 不再向该线程追加大块背景信息,开始准备阶段摘要和下一线程交接包。 |
+
+
+ | `urgent` |
+ `25% ~ 39%` |
+ 优先完成当前原子子任务,同时预创建接力线程,确保 compaction 前完成 handoff。 |
+
+
+ | `critical` |
+ `< 25%` |
+ 禁止继续扩张上下文,立即执行“压缩前收尾”:固化 patch、命令、测试结论、关键决策、未决问题和证据链接。 |
+
+
+
+
+ 5. 额度监控集成(直接复用 gptpluscontrol)
+
+ - 不重新发明额度监控,直接复用 `/Users/kris/code/gptpluscontrol` 已有的后端、Agent、SSE 和数据结构。
+ - 手机 App 和 Web 控制台从控制平面读取“主控状态”,同时从 gptpluscontrol 读取“各 Codex 节点剩余额度和当前占用状态”。
+ - 建议先把 gptpluscontrol 作为独立服务并行部署,再由控制平面聚合其接口;后续若要统一,可再把其接口协议并入主系统。
+
+
+ 6. 跨节点线程对话机制
+
+ - 允许 Mac、Windows、云节点上的任意 Codex 线程在主 Agent 监管下进行线程到线程对话,但不采用裸点对点直连。
+ - 系统实现采用“逻辑直连、物理经主控转发”:发送线程把消息交给本地 `Thread Gateway`,再经 `Inter-Thread Broker` 路由到目标节点。
+ - 默认只允许同一项目内线程互通,跨项目通信必须显式授权。
+ - 消息默认只传任务摘要、必要上下文、附件引用和最近结论,不直接透传完整历史,避免上下文污染和容量膨胀。
+
+
+ 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. 线程对话的权限与审计要求
+
+ - 所有跨节点线程对话必须带 `project_id` 和 `intent`,禁止匿名消息。
+ - `Inter-Thread Broker` 必须检查 ACL:项目边界、角色边界、节点边界、监管模式、最大 turn 数和消息 TTL。
+ - 所有线程对话都必须写入 `Event Store`,手机端项目页可以查看“谁在向谁发起对话、原因是什么、结果是什么”。
+ - 主 Agent 对线程对话有冻结权、禁言权和强制断链权,审计层可对异常通信做告警。
+
+
+ 9. UI 表达与产品交互
+
+ - 项目线程页要显示“跨节点协作”时间线,突出展示 `发送线程`、`目标线程`、`intent`、`状态`、`摘要结果`。
+ - 节点详情页要显示该设备当前正在参与的跨节点对话数、最近交互对象和失败次数。
+ - 主对话页里,当主 Agent让某个线程去和其他节点线程协作时,应出现一条简短系统消息,例如“已让 Mac 前端线程向 Windows GPU 线程请求推理结果”。
+
+
+ 10. 开放式审计与硬件接管
+
+ - 审计层不只审代码,还要能在需要时接管真实测试硬件,因此必须设计成开放能力系统,而不是只读日志的观察者。
+ - 每台设备都可以注册自己的“测试能力”,例如摄像头、麦克风、扬声器、屏幕采集、串口、USB 控制器、拇指机器人、继电器、可编程电源等。
+ - 控制平面维护统一的 `Capability Registry`,记录每个能力所在节点、当前占用状态、优先级和可抢占性。
+ - 审计 Agent 在被授权后,通过 `Device Lease / Preemption` 机制秒级接管这些能力,完成交互测试、硬件回归和多模态验证。
+ - 视频流不建议长期整路上传,边缘节点先提取关键帧、短视频片段、OCR 和检测结果,再由多模态审计 Agent 复核。
+
+
+ 11. 运维层与运维审计层
+
+ - 在整个系统的最外层增加 `Ops Layer` 和 `Ops Audit Layer`,它们负责监管主控、Worker、审计层、硬件层、数据层、额度层是否健康。
+ - 每一台接入系统的终端设备,无论是 Mac、Windows、云工作机还是独立测试台,都必须常驻 `Local Ops Agent` 和 `Local Ops Audit Agent`。
+ - `Local Ops Agent` 负责巡检、分类、执行修复;`Local Ops Audit Agent` 负责监督运维 Agent、判定修复权限、执行修复复验。
+ - 巡检频率由 `Ops Policy Engine` 动态调节:高频使用状态下每 5 分钟一次;无人使用且没有现场工作时每 1 小时一次。
+ - 主 Agent 每小时至少检查一次整个运维层是否健康,确认所有节点的运维 Agent / 运维审计 Agent 在线且最近一次巡检成功。
+ - 当主 Agent 在线且能正常响应时,运维 Agent 发起修复必须先经主 Agent 同意;当主 Agent 失联时,运维审计 Agent 才能做最终修复执行判断。
+
+
+
+
+ 五、每个服务运行在哪台机器
+
+
+
+ | 服务 |
+ 建议部署位置 |
+ 原因 |
+
+
+
+
+ | 手机端 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. 推荐集成方式
+
+ - 把 `gptpluscontrol Backend` 部署在云服务器,与主控控制平面同域或同内网。
+ - 每台 Mac / Windows 设备同时运行 `worker daemon` 和 `gptpluscontrol agent`。
+ - 手机 App 和 Web 端通过控制平面 BFF 聚合两类数据:项目执行数据来自主控,额度和账号状态来自 gptpluscontrol。
+ - 前端只显示最终聚合后的统一视图,避免手机端同时直连多个系统。
+
+
+ 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. 当前可直接利用的关键字段
+
+ - `codex_current_display_name`:当前设备绑定的 Codex 账号显示名。
+ - `codex_current_window_5h_remaining`:当前 5 小时窗口剩余额度。
+ - `codex_current_window_7d_remaining`:当前 7 天窗口剩余额度。
+ - `codex_last_switch_at` / `codex_last_switch_from` / `codex_last_switch_to`:最近切号时间与来源目标。
+ - `codex_last_handoff_status` / `codex_last_handoff_reason`:最近交接状态和原因。
+ - `usage_state`:账号当前是否被占用、是谁在使用、角色优先级和最近动作。
+
+
+ 4. App 里的 UI 设计要求
+
+
+
轻量状态提示
+
主会话顶部显示主控身份
+
+ - 显示:`主 GPT` / `备用 GPT` / `API 容灾`。
+ - 可加一个很小的副文本:当前账号简称或当前节点名。
+ - 点击后展开完整状态,不默认铺满页面。
+
+
+
+
实时额度面板
+
项目页和节点页显示绑定 Codex 客户端剩余额度
+
+ - 每个节点卡片显示:设备名、在线状态、当前账号、5h 剩余、7d 剩余。
+ - 如果节点正在切号或等待人工登录,显示醒目的次级提示。
+ - 额度不足时以黄 / 红两级预警。
+
+
+
+
+ 5. 开发实现建议
+
+ - MVP 先不把 gptpluscontrol 代码强行并入主控服务,先作为独立服务部署,降低耦合。
+ - 主控服务新增一个 BFF 层,把 gptpluscontrol 的 API 结果转换成手机端需要的统一字段。
+ - 等主系统稳定后,再考虑把 gptpluscontrol 的 schema 和事件流整合进统一数据库。
+
+
+
+
+ 九、跨节点线程对话机制
+
+
+
核心原则
+
逻辑直连,物理经主控转发
+
+ 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 类型
+
+ - `ask_compute`:请求 GPU 推理、批处理或算力任务。
+ - `request_artifact`:请求文件、产物、日志、截图或模型输出。
+ - `request_hardware_check`:请求目标节点执行硬件检查。
+ - `request_ui_validation`:请求目标节点做 UI 或交互验证。
+ - `request_test_step`:请求目标节点执行测试步骤并返回结果。
+
+
+
+
+ 十、混合审计架构:规则审计 + 专项审计 Agent
+
+
+
风险
+
自我确认偏差
+
+ 如果主 Agent 既派任务又自己评价自己,就容易忽略执行偏差、低效率循环和错误判断。
+
+
+
+
更稳做法
+
规则审计和多种审计 Agent 并存
+
+ 规则引擎做硬性判断,专项审计 Agent 做语义判断,多模态和硬件场景由专门审计 Agent 接管。
+
+
+
+
主控职责
+
主 Agent 做调度,不独占系统真相
+
+ 所有关键信息都写入事件库和项目记忆,主控只是当前执行者,而不是唯一记忆体。
+
+
+
+
+ 建议的分工
+
+
+
+ | 组件 |
+ 职责 |
+
+
+
+
+ | 主 Agent |
+ 任务拆分、节点选择、上下文裁剪、上下文预算管理、压缩前收尾调度、阶段调度、人工沟通。 |
+
+
+ | Rules Audit Engine |
+ 检测超时、重复失败、压缩次数过多、rate limit、队列积压、worker 离线、视频流断开、测试进程缺失等硬规则异常。 |
+
+
+ | 软件审计 Agent |
+ 复核代码变更、测试覆盖、行为回归、接口契约、日志解释和发布风险。 |
+
+
+ | 硬件审计 Agent |
+ 复核固件版本、设备状态、串口日志、传感器读数、OTA 后行为和外设联动是否正确。 |
+
+
+ | 多模态审计 Agent |
+ 分析截图、关键帧、短视频、摄像头画面、音频片段,判断设备动作、屏幕状态和拟人化交互是否符合预期。 |
+
+
+ | 总审计 Agent |
+ 汇总规则审计和各专项审计的结论,给出通过、驳回、需人工复核和返工建议。 |
+
+
+
+
+ 开放式硬件接管要求
+
+ - 审计 Agent 必须可以接管任意在线节点上的测试硬件能力,只要该能力已在系统注册并被授权。
+ - 支持的能力包括但不限于:摄像头、麦克风、扬声器、屏幕采集、USB 设备、串口、继电器、拇指机器人、可编程电源、机械按键器。
+ - 接管不是直接抢占操作系统桌面,而是通过 `Test Rig Gateway` 暴露标准能力接口,便于审计层按能力调用。
+ - 所有接管都要有租约、超时、占用记录和回放证据,避免多个审计线程同时争抢同一个外设。
+ - 如果某个项目的交互逻辑需要完整拟人化测试,审计 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 定位原则
+
+ - 所有错误键统一采用:`<LAYER>.<DOMAIN>.<COMPONENT>.<ACTION>.<ERROR_CODE>`。
+ - 示例:`MASTER.SCHEDULER.DISPATCH.NODE_UNAVAILABLE`、`WORKER.CODEX.THREAD_START.RATE_LIMIT`、`OPS_AUDIT.REPAIR.VERIFY.RESTART_FAILED`。
+ - 每条日志至少带:`fault_key`、`severity`、`node_id`、`service_name`、`project_id`、`thread_ref`、`trace_id`、`runbook_id`。
+ - Ops Agent 汇报问题时优先输出 `fault_key`、受影响节点、首次/最近时间、建议动作和 runbook,不直接把长日志贴给主控。
+
+
+ 3. 除日志之外必须增加的救援手段
+
+ - 心跳与存活探针:主控、Worker、线程网关、审计层、硬件桥、gptpluscontrol 都要有 heartbeat。
+ - 合成探针:周期性模拟创建项目、启动轻量线程、读取 thread history、申请能力租约,验证业务链路没有“表面存活、实际已坏”。
+ - 事件流与队列监控:看 Event Store 写入延迟、WebSocket/SSE 推送中断、消息积压、线程停滞。
+ - 资源与依赖监控:CPU / 内存 / GPU / 磁盘、数据库复制延迟、对象存储写失败率、网络抖动。
+ - 认证与额度监控:Codex 登录态、API key、Plus 剩余额度、gptpluscontrol 新鲜度、账号切换结果。
+ - 孤儿状态清理:孤儿 lease、孤儿 thread、孤儿 repair ticket、无人接手的审计任务。
+ - 现场快照抽样:关键摄像头关键帧、OCR、串口短日志、设备状态采样,用于发现“服务活着但现场已经坏了”的情况。
+ - 开放运维域探针:对其他接入项目的 SSH、HTTP API、Docker、K8s、Windows Service、局域网 RPC 做统一健康采样和修复映射。
+ - 跨设备运维动作:支持远程拉日志、远程重启服务、远程切换账号、远程重连桥接服务、远程执行 Runbook,并统一经过主运维层审批与复验。
+
+
+ 4. 在线与离线两种修复模式
+
+
+
+ | 场景 |
+ 决策链路 |
+
+
+
+
+ | 主 Agent 在线且能正常返回 |
+ `Ops Agent` 发现问题后先提交修复建议,由主 Agent 审批;审批通过后执行修复,再由 `Ops Audit Agent` 复验并回报主 Agent。 |
+
+
+ | 主 Agent 失联 |
+ `Ops Audit Agent` 确认主控失联并升级到 `Chief Ops Audit Agent`;运维审计层做最终修复执行判断,`Ops Agent` 执行修复,运维审计层复验并写入账本,待主控恢复后同步。 |
+
+
+
+
+ 5. 当运维层自身挂了,但主 Agent 在线
+
+ - 如果 `Ops Control Plane`、`Ops Ledger`、`Ops Connector Runtime` 或大面积 `Local Ops Agent / Ops Audit Agent` 自身出问题,主 Agent 必须切到 `ops_rescue_mode`。
+ - 进入该模式后,主 Agent 通过独立的最小救援通道直连节点或备用控制器,对运维层发起反向抢救。
+ - 反向抢救不能依赖已经损坏的运维控制面本身,必须保留保底通道,例如紧急 RPC、备用控制器、本地 Watchdog 接口或只读健康快照通道。
+ - 运维层恢复后,仍然要由 `Ops Audit Agent` 做复验,再把结果回报主 Agent。
+
+
+ 6. 主控恢复后的回放要求
+
+ - 主 Agent 恢复后必须收到:故障摘要、影响范围、已执行修复动作、复验结论、剩余风险、是否建议人工复盘。
+ - 若运维修复在主控离线时发生,系统必须自动补发一条“修复回放报告”到主会话和运维中心。
+ - 若是主 Agent 自己发起的运维层反向抢救,也必须写入同一套运维账本,避免形成黑盒修复。
+
+
+
+
+
+
+ 十二、容灾与故障恢复
+ 1. 主控故障
+
+ - Master Agent 的任务状态和项目记忆不保存在上下文里,而是落在 Postgres、对象存储和向量记忆里。
+ - 启用 Standby Controller,持续订阅事件库和任务账本,主控故障后接管调度。
+ - LangGraph 的 checkpoint 用于恢复到最近一次可执行状态。
+
+
+ 2. 数据库故障
+
+ - Postgres 使用主从复制或云数据库高可用版本。
+ - 每天全量备份,按小时增量备份,保留至少 7 到 30 天。
+ - 事件日志追加写入对象存储,数据库损坏后仍可回放构建状态。
+
+
+ 3. 单台 worker 故障
+
+ - worker 维持心跳,超过阈值则标记离线,并触发重新调度。
+ - 每个任务都绑定 branch / worktree,失败后可以迁移到其他节点继续执行。
+ - Windows GPU 任务失败时,可降级转移到云 GPU 或改为排队等待恢复。
+
+
+ 4. 账号或额度问题
+
+ - Quota Monitor 记录每个 ChatGPT / Codex 节点的可用额度与速率限制。
+ - 单个账号额度不足时,自动切换到其他 worker 节点执行。
+ - 主脑如使用 API,可与 worker 层的 Plus 账号使用路径解耦。
+
+
+ 5. 网络故障
+
+ - 局域网内的 Mac 和 Windows 节点优先直连云控制平面。
+ - 如家庭宽带不稳定,可在云端部署轻量 relay,worker 与 relay 保持长连接。
+ - 手机端通过 HTTPS + WebSocket 访问,断线重连后根据事件序号补拉缺失记录。
+
+
+ 6. 人工接管
+
+ - 手机端和 Web 控制台提供“暂停调度”“冻结项目”“人工审核后继续”的按钮。
+ - 任何时刻都可以把某个 worker thread 升级为人工接管模式。
+ - 系统要支持导出项目摘要、当前分支、最近命令、失败原因,便于人工介入。
+
+
+
+
+ 十三、推荐的第一阶段落地方式
+
+
+
+ | 阶段 |
+ 目标 |
+ 部署 |
+
+
+
+
+ | 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` 四个等级下的默认动作。
+ - 把“压缩前收尾”提升成正式调度规则,而不是临时经验。
+
+
+
+
+
+ 建议的直接开发顺序
+
+
+
+ | 顺序 |
+ 先做什么 |
+ 原因 |
+
+
+
+
+ | 1 |
+ 建 `capability_providers` / `capabilities` / `capability_leases` / `audit_requests` 等基础表 |
+ 先把注册、租约、任务账本落库,后续协议才有稳定主键和状态流。 |
+
+
+ | 2 |
+ 做 Capability Gateway 的注册、心跳、租约接口 |
+ 这是摄像头、串口、机器人接入和后续抢占的最小闭环。 |
+
+
+ | 3 |
+ 做 Audit Orchestrator 和三类专项审计任务协议 |
+ 先打通任务下发和结构化结果回收,后面再接真实模型与硬件。 |
+
+
+ | 4 |
+ 接 Evidence Collector 和对象存储 |
+ 没有证据归档,多模态和硬件审计无法复盘。 |
+
+
+ | 5 |
+ 接前端项目页的能力占用、审计结果、抢占事件展示 |
+ 这样手机端和 Web 控制台才能真正看到系统状态,不只是跑后台逻辑。 |
+
+
+
+
+
+
+ 十六、当前流程思维导图图片版
+
+ 这张图把当前已经确定下来的主流程、执行层、审计层、能力层和容灾层压成一张图,适合直接对着讨论开发边界和服务拆分。
+
+
+
+
+
+
+ 十七、业务流程思维导图图片版
+
+ 这张图专门从业务推进角度整理,从你发起项目、主控拆任务、多机开发、审计复核、硬件测试到结果交付和异常恢复,每个环节都标了使用的关键技术。
+
+
+
+
+
+
+ 十八、业务流程泳道图图片版
+
+ 如果你想更直观看“谁在什么时候做什么”,就看这张泳道图。它现在把用户、主 Agent、Worker、审计层、硬件能力层、运维层 / 运维审计层、数据与容灾层拆成 7 条泳道,并标出了关键技术、开放式运维接入和反向抢救切换点。
+
+
+
+
+
+
+ 十九、运维与抢修泳道图图片版
+
+ 这张图专门把运维层和运维审计层拆开,展示动态巡检、日志命名、主控在线审批、主控离线紧急接管、修复复验和主控恢复回放的完整闭环。
+
+
+
+
+
+
+ 二十、详细技术栈建议
+
+ 下面这版是“可以直接开工”的技术选型,不再停留在抽象架构层,重点回答:用什么语言、什么数据库、什么消息总线、什么向量库、什么对象存储、什么观测体系。
+
+
+
+
+
前端
+
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 检索单独拆出。 |
+
+
+
+
+ 跨设备运维的具体落地
+
+ - 极轻云默认建议统一走:`Ops Control Plane -> Postgres job queue + LISTEN/NOTIFY -> target Local Ops Agent -> Ops Audit Agent -> Ops Ledger`。
+ - 首批支持的远程运维动作:`remote_exec`、`remote_restart_service`、`remote_fetch_logs`、`remote_collect_snapshot`、`remote_push_config`、`remote_switch_account`、`remote_run_runbook`。
+ - 首批连接器类型:`ssh`、`http_api`、`windows_service`、`docker`、`lan_rpc`。
+
+
+
+
+
+
+ 二十一、极限轻云方案(同时考虑容灾)
+
+ 这里不是因为服务器小才降配,而是无论云服务器配置如何,都主动把云端压缩到最轻;同时保留双云容灾,但让备云只承担接管准备,不承担常态重负载。
+
+
+
+
+
保留
+
云端只保留控制面核心
+
+ 建议保留 `FastAPI BFF + Master Agent + Audit Orchestrator + Ops Control Plane + PostgreSQL + pgvector`,其余尽量不常驻。
+
+
+
+
降配
+
去掉额外常驻中间件
+
+ 默认先不单独上 `Redis`、`NATS`、`Qdrant`、`ClickHouse`、`MinIO`,优先用单体服务 + Postgres 顶住。
+
+
+
+
下沉
+
把重活前移到终端
+
+ 视频流、音频流、OCR、检测、串口长采集都放到 Mac / Windows / Test Rig 节点先做边缘处理,只上传摘要、关键帧和异常片段。
+
+
+
+
+ 最值得做的减法
+
+ - 把控制平面做成 Python 单体,而不是多微服务。
+ - 把事件总线从 `NATS JetStream` 降到 `Postgres job table + LISTEN/NOTIFY`。
+ - 先不用 `Redis`,用 Postgres 行锁和应用内 TTL cache 替代。
+ - 先不用独立向量库,只保留 `pgvector`。
+ - 聊天发送走 HTTP,状态更新优先 `SSE`,不要一开始把所有实时能力都堆到 WebSocket 上。
+ - 审计 Agent 改成按需触发,不常驻。
+ - 运维层做成“轻控制面 + 重边缘执行”,跨设备运维动作由目标节点本地 Ops Agent 执行。
+
+
+ 双云容灾下怎么做轻量化
+
+ - `Cloud A`:主用,只跑控制面单体和 PostgreSQL 主库。
+ - `Cloud B`:热备 / 温备,只跑备用控制面单体、PostgreSQL 备库、关键快照和接管脚本。
+ - 目标不是让两台云都跑得很重,而是“主云承担业务,备云保持可接管”。
+
+
+ 不建议放在云端长期常驻的
+
+ - 持续视频流接入与转码
+ - 长时间音频流处理
+ - 大规模日志全文索引
+ - 独立向量数据库集群
+ - 全套 Prometheus + Grafana + Loki + ClickHouse 观测平台
+
+
+ 这套极轻云方案能保住什么
+
+ - 单主 Agent 入口
+ - 多机 Worker 调度
+ - 线程镜像和聊天记录查看
+ - 基础跨节点线程对话
+ - 按需审计
+ - 基础运维修复与主控失联应急链路
+
+
+
+
+
+
+ 二十二、矛盾点与取舍矩阵
+
+ 这里不是继续堆技术,而是明确说明:在“云端尽可能轻”和“原有业务能力不能砍”之间,哪些可以换实现位置,哪些是唯一真正的硬矛盾。
+
+
+
+
+
+ | 矛盾点 |
+ 推荐取舍 |
+
+
+
+
+ | 手机端要随时看项目进度,但云端又要极轻 |
+ 保留文本线程、状态、摘要、故障、修复结果实时上云;原始视频、音频、大日志改为按需回传,不持续上传。 |
+
+
+ | 要多机实时协作,但不想跑重消息系统 |
+ 保留跨节点协作能力,把 `NATS` 降成 `Postgres job queue + LISTEN/NOTIFY`;功能不砍,但吞吐上限降低。 |
+
+
+ | 要主控层、审计层、运维层都在,但云内存很小 |
+ 保留逻辑角色,不保留多常驻进程;改成单体服务里的模块 + 按需执行器。 |
+
+
+ | 要跨设备运维,还要开放式主运维层 |
+ 云端只做编排和审批,具体修复动作下沉到目标节点的 `Local Ops Agent` 本地执行。 |
+
+
+ | 要多模态、硬件测试,但云带宽和云成本都要压低 |
+ 保留测试闭环,放弃原始流持续上云;边缘先做裁剪、摘要、关键帧、短片段。 |
+
+
+ | 既要云端尽可能轻,又要云端容灾 |
+ 保留双云,但让 `Cloud B` 只做热备 / 温备,不承担常态重负载。主云承担业务,备云承担接管准备。 |
+
+
+
+
+ 最终建议
+
+ - 不砍功能边界,只改变物理部署位置。
+ - 云端只保留“系统真相”和“调度真相”。
+ - 重执行、重媒体、重测试、重运维动作全部边缘化。
+ - 证据上传分冷热两层:热数据立即上云,冷数据按需回传。
+
+
+
+
+
+
+ 二十三、极限轻云双云部署拓扑图图片版
+
+ 这张图把最终确定下来的部署原则画成了可落地的拓扑:`Cloud A` 只承担主用控制面和主库,`Cloud B`
+ 只承担热备 / 温备和接管准备,所有重执行、重媒体、重测试、重运维动作全部下沉到设备端。
+
+
+
+
+
+ - `Cloud A`:控制面单体、主 Agent 编排逻辑、PostgreSQL 主库、pgvector、HTTP + SSE。
+ - `Cloud B`:备用控制面单体、PostgreSQL 备库、接管脚本、快照和恢复钩子。
+ - 设备端:Codex Worker、审计执行器、Test Rig、跨设备运维动作、本地证据缓存。
+ - 默认不在云端常驻:`Redis`、`NATS`、独立对象存储、重媒体处理、重审计池。
+
+
+
+
+ 二十四、双云最低配置速览
+
+ 在“云端尽可能轻”且“不能明显降低稳定性和业务保障能力”的前提下,我建议按下面这个下限准备两台云服务器。
+
+
+
+
+
+ | 角色 |
+ 硬最低可跑 |
+ 推荐最低要求 |
+
+
+
+
+ | `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` |
+
+
+
+
+
+ - “硬最低可跑”更适合 PoC 或超低并发试运行,不建议拿它做业务保障下限。
+ - 真正推荐的最低要求是:`Cloud A = 2C8G / 100GB SSD`,`Cloud B = 2C8G / 100GB SSD`。
+ - 如果你们保留较多审计截图、短视频片段、修复证据和数据库 WAL,磁盘建议直接上到 `150 GB`。
+ - 带宽重点看稳定性,最低建议 `5 Mbps`,更稳建议 `10 Mbps` 以上。
+
+
+
+
+
+
+ 二十五、两种保活模式
+
+ 系统从设计上同时支持两种备用接管路径:`单云 + 单 Mac 备用控制器`,以及 `双云热备 / 温备`。部署时可以二选一,也可以同时启用。
+
+
+
+
+
+
+
+ | 模式 |
+ 组成 |
+ 优点 |
+ 边界 |
+
+
+
+
+ | `单云 + 单 Mac 备用控制器` |
+ `Cloud A` + 一台常开 `Standby Mac` |
+ 更省云成本,本地接管更快,适合已有常开 Mac mini 的环境。 |
+ 如果主云和现场 Mac 同时断电或断网,这条链路也会失效。 |
+
+
+ | `双云热备 / 温备` |
+ `Cloud A` + `Cloud B` |
+ 公网可达性更稳,不依赖现场某一台设备,接管路径更标准化。 |
+ 成本更高;最后一跳的硬件接管仍要依赖现场设备在线。 |
+
+
+
+
+ 模式 A:单云 + 设备端备用池(首选单 Mac)
+
+ - `Cloud A` 跑控制面单体和 PostgreSQL 主库。
+ - 默认首选一台 `Standby Mac`,但系统同时维护 `standby_device_pool`,允许其他接入设备自动成为后备容灾设备。
+ - 当前活动备用设备运行备用控制面轻实例、`Standby Controller`、`Ops Rescue Gateway`,以及备库或快照恢复实例。
+ - 手机 App 必须支持主 / 备 endpoint 列表切换。
+ - 必须准备一条不依赖主云的可达路径,例如同局域网、`Tailscale / WireGuard` 或长期反向隧道。
+ - `Standby Mac` 最低建议:`M1` 或同级 4 核、`8 GB RAM`、`50 GB` 可用 SSD;更稳建议 `16 GB RAM / 100 GB SSD`。
+
+
+ 模式 B:双云热备 / 温备
+
+ - `Cloud A` 跑主用控制面和 PostgreSQL 主库。
+ - `Cloud B` 只跑备用控制面、PostgreSQL 备库、接管脚本和恢复钩子。
+ - 推荐最低要求:`Cloud A = 2C8G / 100GB SSD`,`Cloud B = 2C8G / 100GB SSD`。
+ - 目标不是让两台云都很重,而是“主云承载业务,备云保持可接管”。
+
+
+ 统一抽象
+
+ - 开发时统一抽象成 `standby_provider`。
+ - 部署时可选:`standby_mac`、`cloud_b`、`both`。
+ - 这意味着同一套代码可以跑成:`Cloud A + Standby Mac`、`Cloud A + Cloud B`、或 `Cloud A + Cloud B + Standby Mac`。
+
+
+
+
+ 二十六、还能不能继续压缩云服务器
+
+ 可以,但要分清楚“功能还能跑”和“稳定性与业务保障能力不明显下降”不是一回事。这里把可继续压缩的边界和不能继续下沉的系统真相拆开。
+
+
+ 先给结论
+
+ - `2C8G / 100GB` 不是系统绝对最小,而是“双云容灾下,不明显降低稳定性和业务保障能力”的最低要求。
+ - 如果切到 `单云 + 设备端备用池`,并把更多执行、审计、媒体处理下沉到本地,云端可以继续压到 `2C4G / 80GB`。
+ - `1C2G ~ 1C4G` 只适合实验性极限压缩,不建议作为正式业务下限。
+
+
+ 哪些能力还能继续下沉到设备端
+
+
+
+ | 能力 |
+ 继续压云的做法 |
+ 云端仍需保留的真相 |
+
+
+
+
+ | Embedding 生成 |
+ 在 worker / audit 节点本地生成 embedding,再写回云端。 |
+ 向量、chunk 元数据、项目记忆索引。 |
+
+
+ | 长日志处理 |
+ 本地先裁剪、归类 fault_key、保留最后 N 行再上传。 |
+ fault ledger、工单、修复记录。 |
+
+
+ | 视频 / 音频处理 |
+ 本地做关键帧、短片段、OCR、检测,只传证据摘要。 |
+ 证据索引、审计结论、回放引用。 |
+
+
+ | 审计执行 |
+ 尽量在拥有能力的节点本地跑专项审计。 |
+ 审计工单、复验结论、风险等级。 |
+
+
+ | Test Rig 控制 |
+ 摄像头、串口、机器人、麦克风、扬声器一律本地网关执行。 |
+ 租约、抢占真相、任务结论。 |
+
+
+ | 运维修复动作 |
+ 重启、拉日志、切账号、跑 runbook 都在目标节点本地执行。 |
+ 审批、修复工单、复验结果。 |
+
+
+ | 额度轮询 |
+ 每台机器本地采集 Codex 额度,再定时回报精简状态。 |
+ 统一额度看板、切换历史。 |
+
+
+
+
+ 哪些东西不能继续往本地下沉
+
+ - 项目 / 任务 / 线程账本。
+ - 审计结论与修复结论。
+ - `standby_provider` 和 `standby_device_pool` 状态。
+ - 主备 endpoint 注册表。
+ - 审批结果与权限真相。
+
+
+ 单服务器 + 设备端保活时,设备端掉线怎么办
+
+ - 不能只做一个固定 `Standby Mac`,必须做成 `standby_device_pool`。
+ - 每台设备声明自己是否可作为容灾设备,并上报常开状态、内存、磁盘、网络可达性和 `takeover package` 版本。
+ - 控制面为前 `N` 个候选设备同步最小接管包。
+ - 当前活动备用设备心跳丢失后,系统自动提升下一台候选设备为新的 `active_standby_device`。
+ - 手机 App、Worker、运维层都读取最新的主 / 备 endpoint 清单。
+
+
+ 这个切换会不会很慢
+
+ - 如果备用设备是“冷备”,也就是平时没预部署接管组件,那你的理解是对的:切换会慢,而且容易出问题,因为它等于要临时重新部署一套设备端业务代码。
+ - 所以自动切换不能基于冷备,必须基于 `warm standby` 或 `hot standby`。
+ - `warm standby`:设备已预部署 `Standby Controller / Local Ops Agent / Local Ops Audit Agent / Ops Rescue Gateway`,并已同步最近的 `takeover package`。
+ - `hot standby`:在温备基础上做更高频状态同步,切换更快,但会多占一点本地资源。
+ - 目标时间建议:冷备 `3~10 分钟`,温备 `15~60 秒`,热备 `5~15 秒`。
+
+
+
+
+ 二十七、API-first / Local-first 极限压缩模式
+
+ 可以把云端进一步压轻。思路不是把业务砍掉,而是把“云端常驻重服务”改成“外部 API 调用 + 设备端本地执行”,让云端只做最小控制面和最小系统真相。
+
+
+ 这套模式的核心原则
+
+ - 能通过外部 API 调的,不在你的云端常驻算力。
+ - 能在本地设备完成的,不回云端执行。
+ - 云端只保留:`API Gateway / BFF`、`Master Agent Runtime`、`PostgreSQL`、最小 `pgvector`、endpoint 注册表、`standby_device_pool`、审批/审计/修复账本。
+
+
+ 哪些业务适合 API 化
+
+ - 模型推理:直接调用 OpenAI 或其他模型 API,不在你的云端常驻推理服务。
+ - OCR / 检测:优先本地执行,不够时再走外部 API。
+ - 文件 / 对象存储:优先本地或 NAS,云端只保留 manifest 和索引。
+
+
+ 哪些业务更适合本地化
+
+ - embedding 生成
+ - 长日志裁剪
+ - 视频 / 音频预处理
+ - 专项审计执行
+ - Test Rig 控制
+ - 运维修复动作
+ - gptpluscontrol 本地额度采集
+
+
+ 这条线下的起步配置
+
+ - 如果并发设备 `<= 3`,而且采用 `单云 + standby_device_pool + API-first + local-first`,起步云配置可以认真尝试 `2C4G / 80GB SSD`。
+ - `1C2G ~ 1C4G` 只建议当实验环境,不建议直接作为正式起步线。
+
+
+ 按设备数和任务数弹性升级
+
+ - 起步档:`1 个 Cloud A + standby_device_pool`,并发设备 `<= 3`,建议 `2C4G / 80GB SSD`。
+ - 如果同时接入设备数 `> 3`、活跃线程数 `> 10`、专项审计 / 硬件测试并发 `> 2`,就建议升到 `2C8G / 100GB` 或补上 `Cloud B`。
+ - 只有在再往上走时,才考虑依次增加 `Redis`、`NATS JetStream`、独立对象存储、独立向量库。
+
+
+
+
+
diff --git a/docs/architecture/current_runtime_and_deploy_status_cn.md b/docs/architecture/current_runtime_and_deploy_status_cn.md
new file mode 100644
index 0000000..525890f
--- /dev/null
+++ b/docs/architecture/current_runtime_and_deploy_status_cn.md
@@ -0,0 +1,238 @@
+# Boss 当前运行与部署状态
+
+更新时间:`2026-03-26`
+
+## 1. 本地状态
+
+当前本地已经验证通过:
+
+- `npm run lint`
+- `npm run build`
+- Web 健康检查:`http://127.0.0.1:3000/api/health`
+- 会话聚合接口:`http://127.0.0.1:3000/api/v1/conversations`
+- 主 Agent 项目详情:`http://127.0.0.1:3000/api/v1/projects/master-agent`
+- AI 账号摘要接口:`http://127.0.0.1:3000/api/v1/accounts`
+- 设备 Skill 同步接口:`http://127.0.0.1:3000/api/v1/devices/mac-studio/skills`
+- 登录接口:`POST http://127.0.0.1:3000/api/auth/login`
+- 登录态接口:`GET http://127.0.0.1:3000/api/auth/session`
+- 登录恢复接口:`POST http://127.0.0.1:3000/api/auth/restore`
+- 登出接口:`POST http://127.0.0.1:3000/api/auth/logout`
+- OTA 包下载接口:`GET http://127.0.0.1:3000/api/v1/user/ota/package`
+- 本地 agent 健康检查:`http://127.0.0.1:4317/health`
+- 本地 Skill 扫描接口:`http://127.0.0.1:4317/api/v1/skills`
+- 本地 agent 手动 heartbeat:`POST http://127.0.0.1:4317/api/v1/heartbeat`
+- `launchd` 已安装:`~/Library/LaunchAgents/com.hyzq.boss.local-agent.plist`
+
+本地已知运行方式:
+
+```bash
+cd /Users/kris/code/boss
+npm run build
+npm start
+```
+
+```bash
+cd /Users/kris/code/boss
+npm run apk:debug
+```
+
+```bash
+cd /Users/kris/code/boss
+npm run apk:release
+```
+
+```bash
+cd /Users/kris/code/boss
+./scripts/start-local-agent.sh ./local-agent/config.example.json
+```
+
+本地常驻安装:
+
+```bash
+cd /Users/kris/code/boss
+./scripts/install-local-launchagent.sh
+```
+
+如需切回本地回环开发控制面:
+
+```bash
+cd /Users/kris/code/boss
+./scripts/install-local-launchagent.sh /Users/kris/code/boss/local-agent/config.example.json
+```
+
+补充说明:
+
+- `npm run build` 现在会先自动清理 `.next`,避免 `ENOTEMPTY`
+- `npm start` 会显式带上 `BOSS_STATE_FILE=$PWD/data/boss-state.json`,避免 Next standalone 把状态写到 `.next/standalone/data`
+- `npm start`、服务器 `systemd` 与远端 `npm run build` 当前都显式设置了 `BOSS_RUNTIME_ROOT`,避免 `process.cwd()` 在 standalone / 服务器构建阶段误扫描整个仓库
+- `next.config.ts` 当前已把 `deployment / docs / design / local-agent / prompts / scripts / android` 等目录排除出 standalone tracing,服务器端构建不会再把非运行时资产卷进 `.next/standalone`
+- `data/boss-state.json` 的写入已经改成串行事务队列、原子替换和 `.bak` 备份恢复,`heartbeat` 与 APP 日志并发写入已复核通过
+- 当前登录成功后会写入 `boss_session` Cookie;`会话 / 设备 / 我的 / 线程` 页面以及主要 `/api/v1/*` 路由都要求有效会话
+- 当前 `boss_session` 默认保持 30 天,`Set-Cookie` 已验证为 `Max-Age=2592000`
+- 原生 Android 客户端当前会把登录返回的 `boss_session / restore token / account` 落到 `SharedPreferences`,并在 APP 启动时通过 `/api/auth/restore` 自动补回会话;已本地验证“登录 -> 取 restore token -> restore 接口恢复”链路
+- 登录成功后的客户端跳转当前已做稳态兜底:会先确认 `/api/auth/session` 已可读,再 `replace` 到 `/conversations`,并补一次 `window.location.replace` 防止真机 WebView 偶发卡在登录提示页
+- `POST /api/auth/send-code` 当前已增加 60 秒冷却和 15 分钟窗口限流
+- `POST /api/auth/send-code` 当前还会先按用途校验账号状态:登录 / 忘记密码必须是已存在账号,注册必须是未注册账号
+- 当前账号连续登录失败 5 次后会锁定 10 分钟
+- 当前登录页已临时切到免验证模式;点击“登录”会直接创建最高管理员会话,不再校验账号密码或验证码
+- 新注册和重置密码当前已切到 `scrypt` 哈希;历史 `sha256` 密码会在下一次密码登录时自动迁移
+- `launchd` 会保持 `com.hyzq.boss.local-agent` 常驻,所以本地 agent 被手动结束后会自动重启
+- `launchd` 默认加载 `local-agent/config.cloud.json`,控制面指向 `https://boss.hyzq.net`
+- `local-agent/config.example.json` 仍保留给本地 `127.0.0.1:3000` 回环开发
+- 本地 `launchd` 当前已把 `mac-studio` 作为 `17600003315` 的绑定 Codex 节点上报
+- 本地 agent 当前会递归扫描 `~/.codex/skills`,并把本机 Skill 同步到云端设备维度
+- 根布局当前会挂载 APP 日志桥,路由切换、运行时错误、消息发送和 OTA 操作会通过 `/api/v1/app-logs` 实时同步到服务器;日志绑定已改成按当前登录会话解析设备
+- 根布局当前还会挂载原生运行时桥:维护 APP 内导航历史、拦截 Android 返回键、防止根页直接退回桌面,并在 OTA / 同签名覆盖安装后自动尝试恢复登录态
+- UI 外壳已收口为真机态:移动端不再渲染假的 `9:41 / 5G` 状态栏,底部一级导航固定在视口底部,背景图按手机 viewport 全屏 cover,WebView 不再显示外层圆角矩形预览壳
+- 会话页、设备页、技能页和项目详情页当前都通过 `/api/v1/events` 的 SSE 自动刷新
+- 我的页当前新增 `AI 账号` 入口,支持查看 `主 GPT / 备用 GPT / API 容灾`,并明确主链路优先走已经在绑定电脑上登录 `ChatGPT Plus / Codex` 的 `Master Codex Node`
+- 主 Agent 当前真实对话链路已验证通过:`Boss Web -> /api/v1/projects/master-agent/messages -> master-agent task queue -> local-agent -> codex exec -> /complete -> 项目消息账本`
+- 主 Agent 同步等待窗口当前为 55 秒;若本机 Codex 节点回复更慢,项目页仍会通过 SSE 在任务完成后自动刷新出真实回复
+- `GET /api/v1/app-logs` 当前已支持登录态分页查询
+- `POST /api/v1/app-logs`、`POST /api/v1/devices/[deviceId]/skills`、`POST /api/v1/workers/[workerId]/thread-context` 当前都要求有效设备 token 或匹配登录会话
+- 设备页当前只保留生产设备;旧演示脏数据已经从设备、运维和审计聚合视图里剔除
+- `npm run apk:debug` 当前会自动把最新 APK 发布到 `public/downloads/boss-android-latest.apk`,并写入 `public/downloads/boss-android-latest.json`
+- `npm run apk:release` 当前会先准备本机 release keystore,再构建 signed release APK 并发布到 `public/downloads/boss-android-latest.apk`
+- APK 发布脚本当前还会额外保留带版本号的安装包:`public/downloads/boss-android-v{versionName}-{flavor}.apk`
+- 当前默认管理员账号:`17600003315`
+- 当前默认测试密码:`boss123456`
+- 登录页当前是临时免验证入口;Web 登录页和原生 Android 登录页都会直接创建会话
+- 当前已生成 Android debug APK:`android/app/build/outputs/apk/debug/app-debug.apk`
+- 当前已生成 Android signed release APK:`android/app/build/outputs/apk/release/app-release.apk`
+- 当前 release 构建还会额外生成带版本号的 APK:`android/app/build/outputs/apk/release/boss-android-v{versionName}-release.apk`
+- 当前最新 release 构建版本:`2.1.0`(`versionCode=7`)
+- 当前 release keystore 位于本机 `android/keystores/boss-release.keystore`,签名参数位于 `android/signing/release-signing.properties`
+- `2.0.1` 已在本机连接的华为真机上复核通过,修复了 `Theme.SplashScreen` 导致的 `AppCompatActivity` 启动闪退
+- `2.1.0` 已把 Web 一级页和主要二级页全部补成原生活动页:`MainActivity / ProjectDetailActivity / ProjectGoalsActivity / ProjectVersionsActivity / ProjectForwardActivity / ThreadDetailActivity / DeviceDetailActivity / DeviceEnrollmentActivity / SkillInventoryActivity / SecurityActivity / SettingsActivity / AiAccountsActivity / OpsCenterActivity / AboutActivity`
+- `2.1.0` 已完成签名包覆盖安装到本机连接的华为真机,并确认 `com.hyzq.boss` 可以成功拉起进程
+
+## 2. 服务器状态
+
+服务器信息:
+
+- 主机:`106.53.170.158`
+- 用户:`ubuntu`
+- 系统:`Ubuntu 24.04.4 LTS`
+- 代码路径:`/opt/boss`
+
+已验证服务:
+
+- `boss-web.service`:运行中
+- `caddy.service`:运行中
+- `postfix.service`:运行中
+- `dovecot.service`:运行中
+- `http://127.0.0.1:3000/api/health`:正常
+- `http://127.0.0.1:3000/api/v1/conversations`:正常
+- SMTP Submission 自测:`127.0.0.1:587` 可认证发信
+- IMAPS 监听:`127.0.0.1:993` 正常
+
+服务器上观察到的运行态:
+
+- `boss-web` 当前通过 `npm start` 启动
+- 实际监听端口为 `3000`
+- `boss-web.service` 显式设置了 `BOSS_STATE_FILE=/opt/boss/data/boss-state.json`
+- `Caddy` 反代 `127.0.0.1:3000`
+- `Postfix` 监听 `25 / 465 / 587`
+- `Dovecot` 监听 `993`
+- 当前部署脚本在远端重启服务后会自动执行一遍本机 health check
+- 当前部署脚本已排除 `data/` 目录,不会再用本地状态文件覆盖服务器上的 `boss-state.json`
+- 当前部署脚本会先在本机执行 `npm run build`,再把已经验证通过的 `.next` 构建产物同步到服务器
+- 当前部署脚本会在 rsync 前先删除服务器旧 `.next` 并修正 `/opt/boss` 所有权,避免历史 root 产物卡住同步
+- 服务器当前不再现编 Next standalone,而是直接重启使用本机同步过去的构建产物,避免服务器端 tracing / 权限差异导致构建失败
+- 当前部署脚本还会在远端重启前递归修正 `/opt/boss` 所有权到 `ubuntu:ubuntu`,避免运维文件被 root 覆盖后再次污染运行时目录
+
+## 3. 域名与 HTTPS 状态
+
+当前这部分不是简单的“好了/没好”,而是已经切清楚边界:
+
+已确认的事实:
+
+- `Caddy` 服务日志显示,曾在 `2026-03-25 12:33:51 CST` 成功为 `boss.hyzq.net` 获取证书
+- 服务器本机 `dig +short boss.hyzq.net` 返回 `106.53.170.158`
+- 服务器本机访问 `http://boss.hyzq.net` 会被 `308` 跳转到 `https://boss.hyzq.net`
+- 服务器本机执行 `curl --resolve boss.hyzq.net:443:127.0.0.1 https://boss.hyzq.net -I` 返回 `307` 并跳转到 `/auth/login`
+
+同时也确认了这些事实:
+
+- 当前本机网络 `dig +short boss.hyzq.net` 仍返回 `198.18.1.188`
+- 当前本机网络 `curl -I http://boss.hyzq.net` 返回 `308`
+- 当前本机网络 `curl -I https://boss.hyzq.net` 返回 `HTTP/2 307`,并跳转到 `/auth/login`
+- 当前本机网络 `curl https://boss.hyzq.net/api/health` 返回 `{"ok":true,"service":"boss-web",...}`
+- 当前本机网络 `curl https://boss.hyzq.net/api/v1/conversations` 已返回真实聚合数据
+- 当前本机网络 `nc -vz boss.hyzq.net 25 587 993` 全部成功
+- 服务器本机直接执行 `curl -I https://boss.hyzq.net` 也返回 `HTTP/2 307`
+- 服务器本机直接执行 `curl https://boss.hyzq.net/api/health` 也返回 `{"ok":true,"service":"boss-web",...}`
+- 服务器本机直接执行 `curl https://boss.hyzq.net/api/v1/conversations` 也返回真实聚合数据
+- 服务器本机通过 `swaks` 走 `127.0.0.1:587 + STARTTLS + AUTH LOGIN` 向 `verify@boss.hyzq.net` 发信成功,邮件已进入 `/home/bossmail/Maildir`
+- `boss-web` 已支持通过 `/opt/boss/.env.server` 切到 `email` 模式;本轮临时切到 `email` 后,`POST https://boss.hyzq.net/api/auth/send-code` 已成功向 `verify@boss.hyzq.net` 投递邮件,随后已恢复默认 `fixed`
+
+因此当前结论是:
+
+- 服务器端 `Caddy + TLS` 配置已经具备
+- 证书申请和续签链路已经具备
+- 当前网络下公网 `443` 已经可以实际访问
+- 公网域名下的 API 也已经可以直接对外提供服务
+- 服务器邮件栈 `Postfix + Dovecot` 已上线,公网 `25 / 587 / 993` 当前可达
+- 但当前网络下 `dig` 仍显示 `198.18.1.188`,说明入口前面可能还有代理层或分裂 DNS;排障时要以真实 HTTP/HTTPS 可达性为准,而不是只盯解析值
+
+## 4. 当前未完成或仅为 MVP 的部分
+
+- 当前服务器默认仍是 `fixed`,验证码为 `000000`
+- 当前虽然已经补齐 OTA 版本中心、检查更新、执行升级和 APK 包下载链路,但仍是文件型状态驱动的 MVP,不是原生增量更新基础设施
+- 当前“OTA / 重装后不掉登录”覆盖原生 Android 客户端的 `SharedPreferences` 恢复与同签名覆盖安装;如果用户先卸载 APP 再全新安装,仍可能丢失本地原生存储
+- 数据存储仍是文件型,而不是数据库
+- 设备发现、项目扫描和额度采集仍是静态配置驱动的 MVP
+- APP 实时日志当前已能同步到主 Agent 会话,但还没有单独的日志检索、分页和告警升级规则
+- Skill 清单当前按设备同步和展示已经可用,但还没有“安装 / 卸载 Skill”这种远程管理能力
+- 服务器侧主 Agent 实时回复依赖被绑定设备的 `local-agent` 在线并能执行 `codex exec`;如果设备离线,只能保留任务或走 API 容灾账号
+- API 容灾当前由用户在 APP 的 `我的 > AI 账号` 页面自行配置 `OpenAI API` 账号,不再依赖服务器预置 Key
+- 图片 / 视频真实文件上传仍未接对象存储
+- 认证虽然已有最小会话 Cookie,但还没有刷新令牌、跨端会话治理、CSRF 防护和更细的风控策略
+- 邮件对外正式投递仍缺少 DNS / 信誉相关的最终收口,例如 SPF、DKIM、DMARC、MX 与退信策略
+- 外部真实邮箱的 end-to-end 收件链路还没有在生产账号上完成最终验收
+
+## 5. 推荐的复核命令
+
+本地:
+
+```bash
+curl -sS http://127.0.0.1:3000/api/health
+curl -sS -H 'Content-Type: application/json' -d '{"account":"17600003315","password":"boss123456","method":"password"}' http://127.0.0.1:3000/api/auth/login
+curl -sS http://127.0.0.1:3000/api/auth/session
+curl -sS http://127.0.0.1:3000/api/v1/conversations
+curl -sS http://127.0.0.1:3000/api/v1/projects/master-agent
+curl -sS http://127.0.0.1:3000/api/v1/devices/mac-studio/skills
+curl -I http://127.0.0.1:3000/api/v1/user/ota/package
+curl -sS http://127.0.0.1:4317/health
+curl -sS http://127.0.0.1:4317/api/v1/skills
+curl -sS -X POST http://127.0.0.1:4317/api/v1/heartbeat
+```
+
+服务器:
+
+```bash
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" health
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status boss-web --no-pager"
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status caddy --no-pager"
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status postfix --no-pager"
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status dovecot --no-pager"
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "curl -sS http://127.0.0.1:3000/api/health"
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "curl -sS http://127.0.0.1:3000/api/v1/conversations"
+```
+
+域名:
+
+```bash
+dig +short boss.hyzq.net
+curl -I http://boss.hyzq.net
+curl -I https://boss.hyzq.net
+curl -I --resolve boss.hyzq.net:443:106.53.170.158 https://boss.hyzq.net
+nc -vz boss.hyzq.net 25 587 993
+```
+
+## 6. 运维判断原则
+
+- 判断 Web 是否正常,以 `/api/health` 和 `/api/v1/conversations` 为准
+- 判断本地设备端是否正常,以本地 agent `/health` 和手动 heartbeat 为准
+- 判断服务器是否正常,以 `systemd` 和本机 `curl` 为准
+- 判断公网是否真的可用,必须从外部网络重新验证 `boss.hyzq.net`
diff --git a/docs/architecture/detailed_technical_stack_cn.md b/docs/architecture/detailed_technical_stack_cn.md
new file mode 100644
index 0000000..b265b36
--- /dev/null
+++ b/docs/architecture/detailed_technical_stack_cn.md
@@ -0,0 +1,1374 @@
+# Codex 多机协作系统详细技术选型
+
+目标:
+
+- 把整体技术方案从“架构概念”细化到“可以开工”的选型级别
+- 明确每个核心模块建议用什么语言、数据库、中间件、向量库和部署方式
+- 保持技术栈尽量少而稳,同时满足多机协作、跨设备运维、审计、多模态和硬件测试
+
+---
+
+## 1. 总体选型原则
+
+1. 云端核心服务尽量少语言,优先统一到 `Python + TypeScript`。
+2. 和 `Codex app-server / SDK`、硬件测试、审计链路耦合最深的服务,优先用 `Python 3.12`。
+3. 手机端先做 `Web / PWA`,不要一开始就上双原生。
+4. 默认先把数据平面统一到 `Postgres + pgvector`,把 `Redis / NATS / S3/MinIO` 作为后续按规模增加的能力。
+5. 日志、指标、链路要从一开始就带上,不要后补。
+
+---
+
+## 2. 语言与框架建议
+
+### 2.1 前端
+
+- `TypeScript`
+- `Next.js 15`
+- `React 19`
+- `Tailwind CSS 4`
+- `shadcn/ui` 或自建轻量组件层
+
+用途:
+
+- 手机端 PWA
+- Web 控制台
+- 项目页、线程页、审批中心、节点状态页、运维中心
+
+### 2.2 云端控制平面
+
+- `Python 3.12`
+- `FastAPI`
+- `Pydantic 2`
+- `SQLAlchemy 2`
+- `LangGraph`
+
+用途:
+
+- Master Agent Runtime
+- API Gateway / BFF
+- 审计编排
+- 运维编排
+- Thread Registry / Broker 业务层
+
+### 2.3 Worker / Gateway / Audit / Ops Agent
+
+- `Python 3.12`
+
+原因:
+
+- 更适合直接对接 Codex SDK / app-server
+- 更适合硬件库、串口、音视频、自动化测试工具
+- 更适合复用审计与运维的同一套数据模型
+
+推荐模块:
+
+- `asyncio`
+- `httpx`
+- `websockets`
+- `pydantic`
+- `typer`
+- `tenacity`
+
+### 2.4 本地最小 Watchdog
+
+优先方案:
+
+- 先用 `Python` + 系统服务管理器实现
+ - macOS: `launchd`
+ - Linux / WSL2: `systemd`
+ - Windows: `Task Scheduler` 或 `nssm`
+
+后续如果要更强的单二进制守护能力,再考虑:
+
+- `Go`
+
+---
+
+## 3. 数据与中间件选型
+
+### 3.1 主数据库
+
+推荐:
+
+- `PostgreSQL 16`
+
+用途:
+
+- 项目、任务、线程镜像
+- 审计请求与结果
+- Capability Registry
+- 运维域、运维工单、Runbook
+- 主控状态、节点心跳、账号状态
+
+原因:
+
+- 事务能力强
+- JSONB 足够灵活
+- 能直接挂 `pgvector`
+- 备份、高可用、迁移都成熟
+
+### 3.2 向量库
+
+MVP 推荐:
+
+- `pgvector`
+
+原因:
+
+- 与主库同一套备份与权限体系
+- 项目记忆规模在前期不会大到必须拆独立向量库
+- 开发效率最高
+
+中后期可选:
+
+- `Qdrant`
+
+切换条件:
+
+- 检索量明显增长
+- 需要独立分片与更强 ANN 性能
+- 项目记忆规模、日志检索、经验检索都上来后
+
+### 3.3 缓存与短任务状态
+
+极轻云默认:
+
+- 先不用独立 `Redis`
+- 通过 `PostgreSQL 行锁 + 应用内 TTL cache` 处理
+
+后续放大再补:
+
+- `Redis 7`
+
+适用用途:
+
+- 会话级缓存
+- 去重 key
+- 短期锁
+- SSE / WebSocket 会话映射
+- 限流与节流
+
+### 3.4 事件总线 / 跨设备指令总线
+
+极轻云默认:
+
+- `PostgreSQL job table + LISTEN/NOTIFY`
+
+后续放大再升级:
+
+- `NATS JetStream`
+
+用途:
+
+- 跨设备运维动作
+- Worker 事件汇聚
+- 审计任务触发
+- Ops remote action
+- 心跳广播与告警事件
+
+说明:
+
+- MVP 极轻云阶段,`PostgreSQL job table + LISTEN/NOTIFY` 就足够
+- 当并发、订阅者数量、跨节点事件量明显上来后,再切到 `NATS JetStream`
+
+### 3.5 对象存储
+
+极轻云默认:
+
+- 云主机本地磁盘做短期证据缓存
+- 每日异步备份到低成本对象存储
+
+后续放大再升级:
+
+- `S3 兼容对象存储`
+- 自管可选 `MinIO`
+
+用途:
+
+- 视频片段
+- 音频片段
+- 截图与关键帧
+- 串口长日志
+- 报告导出
+- Patch 快照
+
+---
+
+## 4. 日志、指标、链路追踪
+
+### 4.1 应用日志
+
+MVP 推荐:
+
+- 结构化 JSON 日志直接写文件 + 上传对象存储
+- 核心 fault index 写 `Postgres`
+
+中期推荐:
+
+- `ClickHouse`
+
+用途:
+
+- 高吞吐故障检索
+- fault_key 聚类
+- 低 token 摘要查询
+
+### 4.2 指标
+
+极轻云默认:
+
+- 先做健康探针 + 结构化指标表 + 轻量节点看板
+
+后续放大再升级:
+
+- `Prometheus`
+- `Grafana`
+
+用途:
+
+- CPU / 内存 / 磁盘 / GPU
+- 进程在线率
+- 队列积压
+- 事件流延迟
+- 能力租约占用
+
+### 4.3 链路追踪
+
+极轻云默认:
+
+- 关键链路先记录 `trace_id` 到结构化日志和 Postgres
+
+后续放大再升级:
+
+- `OpenTelemetry`
+- 存储可接 `Grafana Tempo` 或兼容后端
+
+---
+
+## 5. 认证与密钥管理
+
+### 5.1 节点到云端认证
+
+推荐:
+
+- `mTLS` 或节点签名 token
+
+### 5.2 服务内部认证
+
+推荐:
+
+- `JWT` + 细粒度 service claims
+
+### 5.3 密钥存储
+
+推荐:
+
+- 云上:`1Password Secrets Automation`、`Vault` 或云 KMS
+- 本地节点:只保存最小必要 token,敏感密钥由云端短期签发
+
+---
+
+## 6. 服务到技术栈映射
+
+| 模块 | 推荐语言 / 框架 | 存储 / 中间件 | 说明 |
+|---|---|---|---|
+| 手机端 / Web 控制台 | TypeScript + Next.js | SSE + BFF | 统一入口,先做 PWA |
+| API Gateway / BFF | Python + FastAPI | Postgres | 聚合项目态、额度态、运维态 |
+| Master Agent Runtime | Python + LangGraph | Postgres、pgvector | 项目编排与记忆 |
+| Worker Daemon | Python | Postgres | 接 Codex、回传事件 |
+| Thread Gateway | Python | Postgres job queue + LISTEN/NOTIFY | 线程对话与跨节点消息 |
+| Audit Orchestrator | Python | Postgres | 审计任务编排 |
+| Specialist Audit Agents | Python | 本地证据目录 + Postgres | 软件 / 硬件 / 多模态 |
+| Capability Registry | Python | Postgres | 能力注册、租约、抢占 |
+| Test Rig Gateway | Python | 本地证据目录 + Postgres | 摄像头、机器人、串口等 |
+| Ops Control Plane | Python | Postgres | 主运维层控制面 |
+| Local Ops Agent | Python | 本地日志 + Postgres job queue | 本地巡检与修复 |
+| Local Ops Audit Agent | Python | Postgres | 复验、紧急修复判定 |
+| gptpluscontrol Backend | 保持现有实现 | Postgres / API | 直接复用现有项目 |
+
+---
+
+## 7. 跨设备运维的技术落地
+
+### 7.1 执行模式
+
+跨设备运维不做成“任意节点互相 SSH”,而做成:
+
+`Ops Control Plane -> Postgres job queue + LISTEN/NOTIFY -> target Local Ops Agent -> result -> Ops Audit Agent -> Ops Ledger`
+
+### 7.2 远程动作能力
+
+至少支持:
+
+- `remote_exec`
+- `remote_restart_service`
+- `remote_fetch_logs`
+- `remote_collect_snapshot`
+- `remote_push_config`
+- `remote_switch_account`
+- `remote_run_runbook`
+
+### 7.3 适配器类型
+
+建议首批支持:
+
+- `ssh`
+- `http_api`
+- `windows_service`
+- `docker`
+- `lan_rpc`
+
+第二批再支持:
+
+- `k8s`
+- `adb`
+- `serial_bridge`
+
+---
+
+## 8. 向量记忆与检索策略
+
+### 8.1 存什么
+
+- 项目摘要
+- 关键决策
+- 约束条件
+- 失败复盘
+- 审计结论
+- 运维修复经验
+- 已知故障与 runbook 关联
+
+### 8.2 不存什么
+
+- 全量源码原文
+- 全量长日志原文
+- 大体积视频
+
+这些留在对象存储,只在需要时做摘要与引用。
+
+### 8.3 检索策略
+
+- 项目级记忆按 `project_id`
+- 运维经验按 `fault_key`
+- 审计经验按 `audit_type`
+- 硬件经验按 `device_type / lab_tag`
+
+---
+
+## 9. 向量库迁移策略
+
+### 9.1 能不能迁移
+
+可以,而且建议从第一天就按“可迁移”去设计。
+
+可迁移目标包括:
+
+- 自建 `Postgres + pgvector`
+- 自建 `Qdrant / Milvus`
+- 腾讯云 `Tencent Cloud VectorDB`
+- 阿里云 `PolarDB PostgreSQL + PGVector`
+- 阿里云 `Milvus 版`
+- 其他自建服务器上的向量库
+
+### 9.2 为什么可以迁移
+
+因为真正的“系统真相”不应该只存在向量库里,而应该分成两层:
+
+- `Canonical Source`
+ 保存在主数据库和对象存储:
+ - chunk 原文
+ - chunk_id
+ - project_id
+ - metadata
+ - embedding_model
+ - embedding_dim
+ - content_hash
+- `Serving Vector Store`
+ 只是当前正在服务检索的向量后端
+
+只要 `Canonical Source` 在,我们就可以:
+
+- 直接导出已有向量并导入新向量库
+- 或者在新向量库里重新生成 embedding 后重建索引
+
+### 9.3 最推荐的可迁移设计
+
+建议增加一层:
+
+- `VectorStoreAdapter`
+- `RetrievalService`
+
+业务代码只调用 `RetrievalService`,不直接写死腾讯、阿里、pgvector、Qdrant 的 SDK。
+
+### 9.4 迁移时怎么做
+
+建议流程:
+
+1. 新向量后端先建空库 / 空 collection
+2. 从主数据库导出 chunk 与 metadata
+3. 选择:
+ - 复用原 embedding 直接导入
+ - 或重新 embedding 后导入
+4. 新后端做 shadow read
+5. 对比召回结果与延迟
+6. 通过后切主
+7. 保留一段双写 / 回滚窗口
+
+### 9.5 哪种迁移最平滑
+
+- 从 `Postgres + pgvector` 迁到阿里云 `PolarDB PostgreSQL + PGVector`
+ 这条路径最平滑,因为仍然是 PostgreSQL / pgvector 体系。
+- 迁到腾讯云 `VectorDB`
+ 也可行,但更像“后端替换”,需要通过适配层吸收查询、过滤、索引与导入方式差异。
+- 迁到 `Milvus / Qdrant`
+ 也可行,但更适合把向量层彻底独立出去,而不是继续走“单库一体化”模式。
+
+### 9.6 不建议怎么做
+
+- 不要把厂商私有特性直接写进核心业务逻辑
+- 不要让向量库成为唯一知识真相
+- 不要把 embedding 模型版本信息丢掉
+
+---
+
+## 10. 为什么主数据库选 PostgreSQL,而不是 MySQL
+
+先说结论:
+
+不是 `MySQL` 做不到,而是对你这套系统来说,`PostgreSQL` 更顺手、更稳,也更容易和向量层放在一起演进。
+
+### 10.1 这套系统的数据形态更像 PostgreSQL 的强项
+
+你的系统里不只是传统表结构,还有很多半结构化对象:
+
+- thread mirror
+- 审计请求与结果
+- capability metadata
+- runbook 定义
+- fault context
+- ops domain / connector 配置
+
+这些用 `PostgreSQL + jsonb` 更自然。PostgreSQL 官方文档也明确说过,绝大多数应用一般应优先使用 `jsonb`。
+来源:[PostgreSQL JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)
+
+### 10.2 PostgreSQL 和 pgvector 的一体化更成熟
+
+`pgvector` 官方项目就是围绕 PostgreSQL 构建的,支持精确检索、HNSW、IVFFlat,并且能直接结合 Postgres 的 ACID、PITR、JOIN 等能力。
+来源:[pgvector GitHub](https://github.com/pgvector/pgvector)
+
+这对我们非常重要,因为我们希望:
+
+- 项目元数据
+- 记忆向量
+- 审计结构化结果
+- 运维修复记录
+
+尽量先落在一套数据库体系里。
+
+### 10.3 后续云迁移更顺
+
+如果我们以后迁到阿里云 `PolarDB PostgreSQL + PGVector`,路径非常平滑,因为官方就是 PostgreSQL + PGVector 体系。
+来源:[阿里云 PolarDB PGVector](https://help.aliyun.com/zh/polardb/polardb-for-postgresql/pgvector)
+
+### 10.4 MySQL 什么时候也能选
+
+如果你们满足这几个条件,`MySQL` 也可以:
+
+- 团队强依赖 MySQL
+- 向量层准备独立出去
+- 复杂 JSON / 审计 / runbook / capability 元数据不想放主库
+- 你愿意多维护一套检索后端和更多同步逻辑
+
+但在当前这套产品里,我更建议默认 `PostgreSQL`。
+
+---
+
+## 11. 云服务器系统与最低配置建议
+
+### 11.1 推荐系统
+
+推荐主控云服务器使用:
+
+- `Ubuntu Server 24.04 LTS`
+
+备选:
+
+- `Debian 12`
+- `Rocky Linux 9`(如果你们团队偏 RPM 系)
+
+不推荐:
+
+- 用 Windows 作为主控制平面主机
+
+### 11.2 为什么优先 Ubuntu / Debian
+
+- `PostgreSQL + pgvector` 在 Debian / Ubuntu 体系安装最顺,官方 pgvector 也明确提供 Debian / Ubuntu 的 APT 包。
+ 来源:[pgvector 安装说明](https://github.com/pgvector/pgvector)
+- Python、NATS、Redis、Prometheus、Grafana、MinIO 的 Linux 运维生态更成熟
+- systemd、Docker、observability 工具链都更稳
+
+### 11.3 最低配置怎么分
+
+这里分 3 档看:
+
+#### A. 仅演示 / 极小规模 PoC
+
+- `4 vCPU`
+- `8 GB RAM`
+- `100 GB SSD`
+
+适用:
+
+- 1 个主控
+- 少量项目
+- 2 到 3 个活跃 Worker
+- 对象存储和监控可外置
+
+#### B. 推荐 MVP 起步配置
+
+- `8 vCPU`
+- `16 GB RAM`
+- `200 GB NVMe SSD`
+
+适用:
+
+- 控制平面
+- Postgres
+- Redis
+- NATS
+- 基础 WebSocket
+- 小规模审计与运维编排
+
+这是我最推荐的起步配置。
+
+#### C. 更稳的生产起步
+
+- 控制平面节点:`4 vCPU / 8-16 GB`
+- 数据节点:`4-8 vCPU / 16-32 GB`
+- 备用控制器:`2-4 vCPU / 4-8 GB`
+
+也就是至少拆成 2 到 3 个角色,而不是一切都塞一台机。
+
+### 11.4 磁盘建议
+
+- 系统盘建议 `NVMe SSD`
+- 不建议低于 `200 GB`
+
+原因:
+
+- 事件镜像
+- 截图 / 视频 / 音频临时文件
+- Postgres WAL
+- 运维日志
+- 审计证据缓存
+
+都比较吃磁盘。
+
+### 11.5 网络建议
+
+- 优先选公网稳定、到你局域网延迟较低的地域
+- 如果 Mac / Windows 都在同一局域网,云端主要扮演控制面和汇聚层,不需要极高带宽,但要稳定长连接
+- 如果视频 / 音频证据频繁上传,建议至少保证稳定的上行和对象存储带宽
+
+### 11.6 我的实际建议
+
+如果你们现在就要启动:
+
+- 主控云服务器先上 `Ubuntu 24.04 LTS`
+- 起步配置直接用 `8 vCPU / 16 GB / 200 GB NVMe`
+- 备用控制器先用 `2-4 vCPU / 4-8 GB`
+
+这比从 `4c8g` 硬挤要稳得多。
+
+---
+
+## 12. 极限轻云方案(同时考虑容灾)
+
+这部分不是“因为服务器小才降配”,而是一个更激进的原则:
+
+无论云服务器多大,都主动把云端压缩到最轻,只保留不可替代的控制面真相;
+同时保留双云容灾,但让备云只承担接管准备,不承担常态重负载。
+
+### 12.1 极限轻云下,云端最终只保留什么
+
+我建议云端最终只保留这 4 类东西:
+
+1. `控制面单体服务`
+ 包含:
+ - BFF / API
+ - Master Agent Runtime
+ - Scheduler
+ - Thread Registry / Broker 业务逻辑
+ - Audit Orchestrator
+ - Ops Control Plane
+ - Quota 聚合逻辑
+
+2. `PostgreSQL 16 + pgvector`
+ 同时承担:
+ - 主数据库
+ - 向量检索
+ - job queue
+ - repair ticket / audit request / thread mirror 持久化
+
+3. `HTTP + SSE`
+ - 聊天发送走 HTTP
+ - 状态推送优先 SSE
+ - 不在云端维持更重的实时基础设施
+
+4. `证据索引与短期缓存`
+ 云端只保留证据索引、摘要和引用关系
+ 原始大文件尽量不在云端长期常驻
+
+一句话:
+
+`主云一个 Python 单体 + 一个 PostgreSQL,备云一个极轻接管面`
+
+### 12.2 云端明确不要保留的
+
+- 不要独立 `Redis`
+- 不要独立 `NATS`
+- 不要独立 `Qdrant / Milvus`
+- 不要 `ClickHouse`
+- 不要自建 `MinIO`
+- 不要全套 `Prometheus + Grafana + Loki`
+- 不要常驻多模态媒体处理服务
+- 不要常驻重型审计 worker 池
+- 不要把跨设备运维动作直接在云端执行
+
+### 12.3 必须下沉到设备端本地的
+
+- 视频流解析
+- 连续音频流处理
+- 摄像头原始流上传
+- OCR / 检测的原始大批量处理
+- 串口长时间采集
+- 大日志全文上传
+- Test Rig 执行动作
+- 跨设备运维修复动作本体
+- 重型 Runbook 执行
+
+改为:
+
+- 设备端先做边缘预处理
+- 只上传关键帧、短片段、摘要、异常片段、压缩日志、结果结论
+
+### 12.4 业务上最值得做的减法
+
+1. 把控制平面做成单体,而不是多服务
+2. 把事件总线降级为 Postgres job queue
+3. 把 Redis 去掉
+4. 把独立向量库去掉,只保留 `pgvector`
+5. 把媒体处理前移到终端设备
+6. 把审计 Agent 改成按需启动,不常驻
+7. 把运维层做成“轻控制面 + 重边缘执行”
+8. 把原始证据留在边缘,只把摘要和索引上云
+
+### 12.5 哪些能力不能砍
+
+这些能力即使极限轻云也必须保留:
+
+- 单主 Agent 入口
+- 多机 Worker 调度
+- 线程镜像与聊天记录查看
+- 基础跨节点线程对话
+- on-demand 审计
+- 主运维层与运维审计层
+- 跨设备运维
+- 主控失联后的紧急修复链路
+- 关键故障与修复结果上云可见
+
+### 12.6 哪些能力只改实现位置,不改能力边界
+
+- 多模态审计:保留,但模型前处理放边缘
+- 硬件闭环:保留,但执行与采样放边缘
+- 运维抢修:保留,但修复动作本体放目标节点
+- 向量记忆:保留,但先和主库合并,不拆独立服务
+- 实时查看:保留,但优先 SSE,不追求最重实时架构
+
+### 12.7 双云容灾在极限轻云下怎么做
+
+既然你接受两台云服务器做备份,我建议:
+
+- `Cloud A`
+ 平时主用
+ 跑:
+ - 控制面单体
+ - PostgreSQL 主库
+
+- `Cloud B`
+ 平时热备 / 温备
+ 跑:
+ - 备用控制面单体
+ - PostgreSQL 备库
+ - 关键快照和接管脚本
+
+目标不是把两台云都跑满,而是:
+
+- 平时只让一台主扛业务
+- 另一台尽量轻,只负责接管准备
+
+### 12.8 矛盾点与取舍矩阵
+
+这里是最关键的一部分。
+
+#### 矛盾 1:你要手机随时看项目进度,但云端又要极轻
+
+取舍:
+
+- 保留:线程文本、任务状态、摘要、故障、修复结果实时上云
+- 下沉:原始媒体、大日志、长串口流、原始检测流
+
+结论:
+
+- “能看项目和聊天”必须保留在云端
+- “能看所有原始大证据”改为按需回传
+
+#### 矛盾 2:你要多机实时协作,但不想跑重消息系统
+
+取舍:
+
+- 保留:跨节点协作能力
+- 替换:`NATS` 改 `Postgres job queue + LISTEN/NOTIFY`
+
+结论:
+
+- 功能不砍
+- 吞吐上限降低
+- 对 MVP 可接受
+
+#### 矛盾 3:你要审计层、运维层、主控层都在,但云端还要极轻
+
+取舍:
+
+- 保留:逻辑角色
+- 改实现:不做多个常驻服务,而做一个单体里的模块 + 按需执行器
+
+结论:
+
+- 角色不砍
+- 物理进程数减少
+
+#### 矛盾 4:你要跨设备运维,还要主运维层开放式扩展
+
+取舍:
+
+- 保留:开放式主运维层
+- 下沉:具体修复动作在目标节点本地执行
+
+结论:
+
+- 云端只做决策与编排
+- 边缘做执行
+
+#### 矛盾 5:你要多模态、硬件测试,但云带宽只有 10Mbps
+
+取舍:
+
+- 保留:多模态审计和硬件闭环
+- 替换:边缘先做裁剪、摘要、关键帧、短片段
+
+结论:
+
+- 保留测试能力
+- 放弃原始流持续上云
+
+#### 矛盾 6:你要云端尽可能轻,但又要双云容灾
+
+取舍:
+
+- 保留:双云容灾
+- 改实现:第二台云机尽量只做热备 / 温备,不承担常态重负载
+
+结论:
+
+- 双云可以保留
+- 但只有主云承载主流量,备云尽量只承担接管准备
+
+### 12.9 最终取舍原则
+
+在你的约束下,最应该坚持的不是“所有东西都放云上”,而是:
+
+- 功能边界不砍
+- 云端只保留系统真相和调度真相
+- 执行、重媒体、重测试、重运维动作全部边缘化
+- 双云只保留“主用 + 备用”,不做“双主都很重”
+
+换句话说:
+
+- `业务能力保留`
+- `物理部署下沉`
+- `实时性分层`
+- `证据上传按冷热分级`
+
+---
+
+## 13. 推荐部署方式
+
+### 13.1 云端
+
+- `Cloud A`
+ - 控制面单体
+ - PostgreSQL 主库
+- `Cloud B`
+ - 备用控制面单体
+ - PostgreSQL 备库
+ - 接管脚本与关键快照
+
+默认不常驻:
+
+- Redis
+- NATS
+- 独立对象存储服务
+- 全套观测平台
+
+### 13.2 终端节点
+
+每台 Mac / Windows / Cloud Worker / Test Rig 至少部署:
+
+- Worker Daemon
+- Thread Gateway
+- Local Ops Agent
+- Local Ops Audit Agent
+- gptpluscontrol Agent
+
+---
+
+## 14. 极轻云双云最低配置要求
+
+这里给两档:
+
+- `硬最低可跑`
+ 能跑起来,但更适合 PoC 或很低并发试运行
+- `不明显降低稳定性和业务保障能力的最低要求`
+ 这是我真正建议你按它采购和部署的下限
+
+### 14.1 硬最低可跑
+
+`Cloud A(主用)`
+
+- `2 vCPU`
+- `4 GB RAM`
+- `80 GB SSD`
+
+`Cloud B(备用)`
+
+- `2 vCPU`
+- `4 GB RAM`
+- `80 GB SSD`
+
+前提:
+
+- 云端只跑控制面单体 + PostgreSQL
+- 不上 Redis / NATS / ClickHouse / MinIO / Prometheus
+- 终端承担全部重媒体和重测试
+- 审计全部按需执行
+- 并发项目数低
+
+这档能跑,但我不把它定义成“业务保障最低”。
+
+### 14.2 不明显降低稳定性和业务保障能力的最低要求
+
+`Cloud A(主用)`
+
+- `2 vCPU`
+- `8 GB RAM`
+- `100 GB SSD`
+
+`Cloud B(备用)`
+
+- `2 vCPU`
+- `8 GB RAM`
+- `100 GB SSD`
+
+原因:
+
+- PostgreSQL 主库 / 备库都要稳定吃下项目、线程、审计、运维修复账本
+- 主控切换时,不希望备云明显掉性能
+- 你要求“不放弃原来的业务和保障能力”,那备用云就不能太瘦
+
+### 14.3 为什么我不建议把备云做得更小
+
+如果 `Cloud B` 只有 `1C2G` 或 `1C4G`,在正常热备时也许没问题;
+但一旦切主,它就会同时承担:
+
+- 控制面单体
+- PostgreSQL 读写
+- SSE / API
+- 审计触发
+- 运维接管记录
+
+这时容易出现:
+
+- failover 后延迟明显抬高
+- PostgreSQL 内存压力过大
+- 恢复期间 SSE / API 不稳定
+
+所以如果你把“业务保障能力”也算进去,我建议两台云机至少对齐到 `2C8G`。
+
+### 14.4 磁盘最低建议
+
+最低不要低于:
+
+- `80 GB`
+
+更稳的起步:
+
+- `100 GB`
+
+如果你们会频繁保留:
+
+- 审计截图
+- 短视频片段
+- 修复证据
+- 数据库 WAL
+
+那 `150 GB` 会更舒服。
+
+### 14.5 带宽要求
+
+极轻云下,云端不承载原始媒体流,所以带宽要求并不高。
+
+最低建议:
+
+- 稳定公网
+- `5 Mbps` 以上可用上行 / 下行
+
+更稳建议:
+
+- `10 Mbps` 以上
+
+重点不是峰值,而是:
+
+- 长连接稳定
+- 丢包低
+- 抖动小
+
+### 14.6 最终一句话
+
+如果你要:
+
+- 极限轻云
+- 双云容灾
+- 不明显降低稳定性和业务保障能力
+
+那我建议把最低配置定成:
+
+- `Cloud A = 2C8G / 100GB SSD`
+- `Cloud B = 2C8G / 100GB SSD`
+
+这已经是我认为比较保守、也比较负责任的下限了。
+
+### 14.7 支持两种保活模式
+
+这套系统建议正式支持两种保活方式,而不是只绑定双云:
+
+#### 模式 A:单云 + 设备端备用池(首选单 Mac)
+
+适用场景:
+
+- 你想把云成本进一步压低
+- 现场本来就有一台常开 Mac,或者多台可接入设备
+- 你能接受“云机故障时,由设备端顶上最小控制面”
+
+部署方式:
+
+- `Cloud A`
+ - 控制面单体
+ - PostgreSQL 主库
+- `Preferred Standby Device`
+ - 默认首选一台常开 `Mac`
+ - 也允许其他接入设备作为后备候选
+ - 备用控制面轻实例
+ - PostgreSQL 备库或周期快照恢复实例
+ - `Standby Controller`
+ - `Ops Rescue Gateway`
+
+关键要求:
+
+- 至少一台首选备用设备必须常开
+- 其余接入设备可声明自己是否可作为后备容灾设备
+- 需要一条不依赖主云的可达通路,例如:
+ - 同一局域网直接访问
+ - `Tailscale / WireGuard`
+ - 独立长期反向隧道
+- 手机 App 要支持主 / 备 endpoint 列表切换
+- 控制面要维护 `standby_device_pool`
+- 每台候选设备都要同步最小 `takeover package`
+
+优点:
+
+- 比双云便宜
+- 救援动作离本地设备更近
+- 对局域网内设备接管更快
+
+边界:
+
+- 如果云机和全部候选设备所在现场一起断电、断网,这条链路也会失效
+- 它适合作为“低成本保活方案”,但上限不如双云
+
+`Preferred Standby Device` 最低建议:
+
+- `Apple Silicon M1` 或同级 Intel 4 核
+- `8 GB RAM`
+- `50 GB` 可用 SSD
+
+更稳建议:
+
+- `16 GB RAM`
+- `100 GB` 可用 SSD
+
+#### 模式 B:双云热备 / 温备
+
+适用场景:
+
+- 你更在意远程可达性和持续在线
+- 不希望把备援绑在某一台现场设备上
+- 希望主云故障时,备用云独立接管
+
+部署方式:
+
+- `Cloud A`
+ - 控制面单体
+ - PostgreSQL 主库
+- `Cloud B`
+ - 备用控制面单体
+ - PostgreSQL 备库
+ - 快照、恢复脚本、接管钩子
+
+优点:
+
+- 远程访问更稳
+- 不依赖现场某一台设备
+- 主控接管路径更标准化
+
+边界:
+
+- 成本高于“单云 + 单 Mac”
+- 对本地硬件接管的最后一跳,仍然要依赖现场设备在线
+
+#### 两种模式怎么选
+
+如果你要:
+
+- 最低云成本下仍然保留备援能力
+
+优先选:
+
+- `单云 + 单 Mac 备用控制器`
+
+如果你要:
+
+- 更强的远程持续在线
+- 更稳定的公网接管能力
+
+优先选:
+
+- `双云热备 / 温备`
+
+我的建议是:
+
+- 系统从设计上同时支持两种模式
+- 开发时统一抽象成 `standby_provider`
+- 实际部署时可选:
+ - `cloud_b`
+ - `standby_mac`
+ - `both`
+
+也就是说,这套产品以后可以跑成:
+
+- `Cloud A + Standby Mac`
+- `Cloud A + Cloud B`
+- `Cloud A + Cloud B + Standby Mac`
+
+其中最后一种是最强兜底,但不是 MVP 必需。
+
+### 14.8 还能不能继续压缩云服务器
+
+能,但要分清楚三条线:
+
+- `双云 + 不明显降低稳定性和业务保障能力`
+ - 最低仍然建议:`Cloud A = 2C8G / 100GB`
+ - `Cloud B = 2C8G / 100GB`
+- `单云 + 设备端备用池`
+ - 云端可以继续压到:`2C4G / 80GB`
+ - 前提是绝大多数重执行都下沉到设备端
+- `实验性极限压缩`
+ - 理论上可以再试 `1C2G ~ 1C4G`
+ - 但我不建议把它写成正式最低配置,因为它已经开始侵蚀稳定性和恢复速度
+
+一句话:
+
+- `2C8G / 100GB` 不是“系统绝对最小”
+- 它是“在双云容灾下,不明显降低稳定性和业务保障能力”的最低要求
+- 如果切到单云,并且把更多动作下沉到本地设备,云端可以继续压到 `2C4G / 80GB`
+
+### 14.9 哪些东西还能继续下沉到设备端
+
+下面这些能力,建议尽可能下沉:
+
+| 能力 | 现在建议放哪 | 还能继续怎么压云 | 不该牺牲什么 |
+|---|---|---|---|
+| Embedding 生成 | 设备端 | 由 worker / audit 节点本地生成 embedding,再把结果写回云库 | 云端仍保存向量和元数据真相 |
+| 长日志处理 | 设备端 | 本地先裁剪、归类 fault_key、保留最后 N 行,再上传 | 云端仍保留 fault ledger |
+| 视频 / 音频处理 | 设备端 | 本地抽关键帧、短片段、OCR、检测结果,只传证据摘要 | 云端仍保留证据索引和结论 |
+| 审计执行 | 设备端 | 软件/硬件/多模态审计尽量在拥有能力的节点本地完成 | 云端仍保留审计工单和结论 |
+| Test Rig 控制 | 设备端 | 摄像头、串口、机器人、麦克风、扬声器一律本地网关执行 | 云端仍保留租约和抢占真相 |
+| 运维修复动作 | 设备端 | 重启、拉日志、切账号、跑 runbook 都在目标节点本地执行 | 云端仍保留审批、工单、复验记录 |
+| 线程摘要压缩 | 设备端 | 每个 worker 本地先做任务摘要,再把结构化摘要写回云端 | 云端仍保留项目主记忆 |
+| gptpluscontrol 额度轮询 | 设备端 | 每台机器本地采集额度,再定时上报精简状态 | 云端仍保留统一额度视图 |
+
+### 14.10 哪些东西不能再往本地下沉
+
+下面这些是系统真相,不能完全放到某一台设备本地:
+
+- 项目 / 任务 / 线程账本
+- 审计结论与修复结论
+- `standby_provider` / `standby_device_pool` 状态
+- 主备 endpoint 注册表
+- 最小项目索引和恢复索引
+- 审批结果与权限真相
+
+也就是说,云端再怎么压,也至少要保留:
+
+- 控制面单体
+- PostgreSQL
+- SSE / API
+- 最小证据索引
+
+### 14.11 单服务器 + 单设备端保活时,设备端掉线怎么办
+
+这个场景不能只做“一个固定备用 Mac”,必须做成:
+
+- `preferred standby device`
+- `eligible standby devices`
+- `automatic standby promotion`
+
+实现方式:
+
+1. 控制面维护一个 `standby_device_pool`
+2. 每台设备声明:
+ - 是否可作为容灾设备
+ - 优先级
+ - 常开状态
+ - 可用内存 / 磁盘
+ - 网络连通性
+3. 控制面为前 `N` 个候选设备同步最小 `takeover package`
+4. 当前活动备用设备心跳丢失后,自动提升下一台候选设备
+5. 手机 App 与 Worker 端都读取新的主 / 备 endpoint 清单
+
+自动提升的评分建议:
+
+- 是否常开
+- 是否同局域网稳定在线
+- 是否具备足够内存和磁盘
+- 是否已具备最新 `takeover package`
+- 是否最近未发生故障
+
+一句话:
+
+- 在单服务器模式下,设备端容灾必须是“备用池”,不能是“唯一备用机”
+
+#### 14.11.1 你的判断是对的:如果是冷备,切换会很慢
+
+如果备用设备只是“连接在系统里,但平时没有预部署控制面与运维组件”,那一旦当前设备崩掉,就会出现:
+
+- 先发现故障
+- 再选备用设备
+- 再部署或拉起业务代码
+- 再下发配置、密钥、隧道、endpoint
+- 再恢复最小项目索引
+
+这条链路会明显变长,而且中间很容易出问题。
+
+所以真正的自动切换,不能建立在“临时重新部署一套设备端业务代码”上。
+
+#### 14.11.2 必须区分冷备、温备、热备
+
+- `冷备(cold standby)`
+ - 设备在线,但没有预部署接管组件
+ - 故障时才开始部署
+ - 结论:不适合自动切换,只适合人工应急
+- `温备(warm standby)`
+ - 设备已预部署接管组件
+ - 已同步 `takeover_package`
+ - 平时不承载主流量,只保留轻实例和心跳
+ - 结论:这是单云 + 设备端备用池的最低可接受形态
+- `热备(hot standby)`
+ - 设备已预部署并保持随时接管
+ - 关键状态同步更频繁
+ - 切换最快
+ - 结论:体验最好,但会多吃一点本地资源
+
+#### 14.11.3 我建议你们至少做温备,不要做冷备
+
+也就是说,每一个合格的备用候选设备上,都应该提前放好:
+
+- `Standby Controller`
+- `Local Ops Agent`
+- `Local Ops Audit Agent`
+- `Ops Rescue Gateway`
+- 最小运行时依赖
+- 最小配置模板
+- endpoint 清单
+- 最近的 `takeover_package`
+
+这样切换时做的就不是“重新部署”,而是:
+
+- 切换角色
+- 拉起轻实例
+- 刷新 endpoint
+- 恢复最小控制面
+
+#### 14.11.4 切换时间预期
+
+如果做成:
+
+- `冷备`
+ - 可能是 `3 ~ 10 分钟`,而且风险大
+- `温备`
+ - 目标应控制在 `15 ~ 60 秒`
+- `热备`
+ - 目标可进一步压到 `5 ~ 15 秒`
+
+所以如果你要“自动启动另外一台连接设备作为容灾设备”,正确前提不是“自动部署”,而是“提前预热好备用池”。
+
+### 14.12 API-first / Local-first 极限压缩模式
+
+可以,而且这恰恰是你现在这套系统最适合走的方向。
+
+因为你们的并发不高,只有 `2 ~ 3` 台电脑同时使用,所以没必要一开始就在云端常驻很多重服务。更合理的是:
+
+- 云端只保留最小控制面和最小系统真相
+- 能通过外部 API 调的,就不要自己在云端常驻算力
+- 能在本地设备做的,就尽量放到设备端
+
+#### 云端最终只保留什么
+
+- `API Gateway / BFF`
+- `Master Agent Runtime`
+- `PostgreSQL`
+- 最小 `pgvector`
+- 主备 endpoint 注册表
+- `standby_device_pool`
+- 审批、审计、修复账本
+
+#### 哪些业务可以直接 API 化
+
+- 模型推理
+ - 直接调用 OpenAI / 其他模型 API
+ - 不在你的云端常驻推理服务
+- OCR / 检测
+ - 优先本地执行
+ - 不够时再调用外部 API
+- 文件 / 对象存储
+ - 优先本地或 NAS
+ - 云端只保存 manifest 和索引
+
+#### 哪些业务更适合本地化
+
+- embedding 生成
+- 长日志裁剪
+- 视频 / 音频预处理
+- 审计执行
+- Test Rig 控制
+- 运维修复动作
+- gptpluscontrol 本地额度采集
+
+#### 这种模式下的最低云配置
+
+如果采用:
+
+- `单云`
+- `standby_device_pool`
+- `API-first`
+- `local-first`
+- 并发设备 `<= 3`
+
+那我建议把起步云配置定成:
+
+- `2C4G / 80GB SSD`
+
+这是一个我认为可以认真尝试的“极限压缩起步线”。
+
+如果想再压:
+
+- `1C2G ~ 1C4G`
+
+理论上能试,但只建议作为实验环境,不建议一开始就当生产起步线。
+
+### 14.13 按设备数和任务数弹性升级
+
+你说得对,不应该一上来就把最低配置拉很高。更合理的是按触发条件升级。
+
+#### 起步档
+
+- 场景:
+ - `1 个 Cloud A`
+ - `standby_device_pool`
+ - 并发设备 `<= 3`
+ - 同时活跃项目 `<= 3`
+- 建议:
+ - `2C4G / 80GB SSD`
+
+#### 升级到下一档的触发条件
+
+满足任意一条就建议升级:
+
+- 同时接入设备数 `> 3`
+- 同时活跃线程数 `> 10`
+- 同时运行专项审计 / 硬件测试 `> 2`
+- `Postgres` 内存持续高于 `70%`
+- API / SSE `p95` 延迟持续高于 `500ms`
+- 待处理修复工单和审计工单出现积压
+
+#### 第一步升级建议
+
+- 先升到:
+ - `2C8G / 100GB`
+- 或者补上:
+ - `Cloud B`
+
+#### 第二步升级建议
+
+- 增加 `Redis`
+- 再考虑 `NATS JetStream`
+- 再考虑独立对象存储
+- 再考虑独立向量库
+
+一句话:
+
+- 先把系统做成“轻云 + 重本地 + 可弹性升级”
+- 不要一开始就把所有重能力堆到云端
+
+---
+
+## 15. MVP 最小落地建议
+
+### 第一阶段
+
+- 前端:Next.js PWA
+- 云端:FastAPI + LangGraph
+- 数据:Postgres 16 + pgvector
+- 队列:Postgres job table + LISTEN/NOTIFY
+- 文件:本机磁盘短期缓存 + 异步备份
+- 运维:结构化 JSON 日志 + 健康探针 + Ops Ledger
+
+### 第二阶段
+
+- 视规模增加 Redis
+- 视并发增加 NATS JetStream
+- 增加 ClickHouse 做 fault_key 检索
+- 增加 Qdrant 作为独立向量库候选
+- 增加更多 Ops Connector
+
+---
+
+## 16. 一句话结论
+
+如果要兼顾多机 Codex、审计、多模态、硬件接管、开放式主运维层和跨设备运维,
+最稳的主栈是:
+
+`TypeScript + Next.js` 做前端,
+`Python + FastAPI + LangGraph` 做控制平面与 Agent 体系,
+`Postgres 16 + pgvector` 做最小数据底座,
+把 `Redis / NATS / 独立对象存储 / 重媒体处理 / 重运维执行` 尽量后移或下沉到边缘节点。
diff --git a/docs/architecture/development_subtasks_and_delivery_plan_cn.md b/docs/architecture/development_subtasks_and_delivery_plan_cn.md
new file mode 100644
index 0000000..a9ffae7
--- /dev/null
+++ b/docs/architecture/development_subtasks_and_delivery_plan_cn.md
@@ -0,0 +1,764 @@
+# 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、状态机、设备预部署、前端字段、验收脚本逐项冻结,然后直接进入开发。
diff --git a/docs/architecture/ops_layer_and_repair_protocol_cn.md b/docs/architecture/ops_layer_and_repair_protocol_cn.md
new file mode 100644
index 0000000..917aa26
--- /dev/null
+++ b/docs/architecture/ops_layer_and_repair_protocol_cn.md
@@ -0,0 +1,786 @@
+# 运维层与运维审计层开发规格
+
+适用范围:
+
+- Codex 多机协作控制系统
+- 主控、Worker、审计层、硬件测试层、数据层的统一运维与抢修
+- 每台接入终端设备上的本地运维 Agent 与本地运维审计 Agent
+
+目标:
+
+- 在整个系统最外层增加 `运维层` 和 `运维审计层`
+- 让运维层成为整个系统的 `主运维层`,并可继续接管其他项目的运维场景
+- 把运维层做成开放式能力底座,而不是只服务当前这一套 Codex 系统
+- 让任何一个环节发生故障时,都能用最省 token 的方式快速定位与修复
+- 定义主 Agent 在线与离线两种情况下的修复审批和复验机制
+- 定义运维层自身故障时,由主 Agent 反向抢救运维层的机制
+- 保证每一台接入系统的终端设备都具备本地自救与被监管能力
+
+---
+
+## 1. 总体原则
+
+1. 运维层是整个系统的外圈保护层,也是全局 `主运维层`,不只看主控,也看 Worker、审计层、硬件测试层、数据库、额度系统,以及后续接入的其他项目运维域。
+2. 每一台接入系统的设备都必须常驻两个本地角色:
+ - `Ops Agent`
+ - `Ops Audit Agent`
+3. `Ops Agent` 负责发现问题、执行修复、运行脚本、拉起服务、切换配置。
+4. `Ops Audit Agent` 负责监督 `Ops Agent` 是否健康、是否有权修复、修复是否成功、是否需要升级到紧急决策。
+5. 只要主 Agent 在线且能够正常返回信息,`Ops Agent` 的修复动作必须先得到主 Agent 同意。
+6. 当主 Agent 失联且超过阈值,`Ops Audit Agent` 才能代行最终修复执行判断。
+7. 运维层必须是开放式的,支持通过标准化 Connector / Adapter / Runbook 注册新的项目运维域。
+8. 如果运维层本身挂了,而主 Agent 仍然在线,主 Agent 必须具备反向抢救运维层的能力。
+9. 所有故障、修复、复验、切换都必须写入统一事件流和运维账本。
+
+---
+
+## 2. 组件设计
+
+### 2.1 云端组件
+
+- `Ops Control Plane`
+ 负责汇总节点健康、统一策略、下发巡检与修复任务。
+- `Ops Policy Engine`
+ 负责判断巡检频率、自动修复权限、紧急接管条件。
+- `Ops Ledger`
+ 负责记录故障、修复工单、复验结论、主控恢复后的同步结果。
+- `Chief Ops Audit Agent`
+ 负责跨节点复核、紧急情况下最终判定、主控恢复后的回填汇报。
+- `Ops Extension Registry`
+ 负责注册其他项目或其他系统的运维域、连接器、协议适配器、能力标签和 Runbook 集合。
+- `Ops Connector Runtime`
+ 负责装载 SSH、HTTP、Docker、Kubernetes、Windows Service、局域网 RPC 等运维连接器。
+
+### 2.2 每台终端设备上的本地组件
+
+- `Local Ops Agent`
+ 负责本机服务巡检、日志采集、健康探针、执行修复动作。
+- `Local Ops Audit Agent`
+ 负责监督本机 `Local Ops Agent`、校验修复结果、在主控失联时决定是否允许继续修复。
+- `Local Watchdog`
+ 负责当本地服务崩溃时自动拉起最小监控能力。
+
+### 2.3 被监管对象
+
+- 主 Agent / Master Agent Runtime
+- API 网关 / WebSocket
+- Worker Daemon / Thread Gateway
+- Audit Orchestrator / Specialist Audit Agents
+- Capability Registry / Test Rig Gateway
+- Postgres / Redis / Object Storage / Event Store
+- gptpluscontrol Backend / Agent
+- GPU Bridge / Windows Tool Bridge
+- 其他项目的运维域
+ - 外部服务
+ - 外部测试台
+ - 外部边缘盒子
+ - 外部 CI / 运维主机
+
+### 2.4 开放式运维扩展模型
+
+运维层不应该写死只服务这一套系统,建议增加 3 层开放接口:
+
+- `Ops Domain`
+ 表示一个被接管的运维域,例如:
+ - 当前 Codex 协作系统
+ - 某个独立设备云
+ - 某个视频分析服务
+ - 某个生产测试线
+- `Ops Connector`
+ 表示接入方式,例如:
+ - `ssh`
+ - `http_api`
+ - `docker`
+ - `k8s`
+ - `windows_service`
+ - `lan_rpc`
+- `Ops Runbook Pack`
+ 表示一组可被版本化管理的运维修复剧本。
+
+任何新项目要接入主运维层,只需要注册:
+
+- 它属于哪个 `Ops Domain`
+- 用什么 `Ops Connector`
+- 提供哪些健康探针
+- 有哪些修复 Runbook
+- 权限边界是什么
+- 是否允许自动修复
+
+### 2.5 跨设备运维能力
+
+运维层必须支持跨设备运维,而不是每台机器只能各修各的。
+
+建议至少支持以下跨设备能力:
+
+- 跨设备拉取日志
+- 跨设备读取健康快照
+- 跨设备重启服务
+- 跨设备下发配置与热更新
+- 跨设备切换账号 / 切换备用通道
+- 跨设备回收孤儿 thread / lease / repair ticket
+- 跨设备重连 Thread Gateway、GPU Bridge、Test Rig Gateway
+- 跨设备触发最小修复 Runbook
+
+建议把跨设备运维动作抽象成标准能力:
+
+- `remote_exec`
+- `remote_restart_service`
+- `remote_fetch_logs`
+- `remote_push_config`
+- `remote_switch_account`
+- `remote_reconnect_channel`
+- `remote_collect_snapshot`
+- `remote_run_runbook`
+
+跨设备运维的执行原则:
+
+1. 默认由云端 `Ops Control Plane` 发起跨设备动作。
+2. 实际执行仍然落在目标节点的 `Local Ops Agent` 上。
+3. `Local Ops Audit Agent` 负责复核跨设备动作是否成功、是否越权。
+4. 所有跨设备动作必须记录 `source_node_id` 和 `target_node_id`。
+5. 禁止未经授权的节点直接互相执行运维指令,必须经过主运维层或紧急救援通道。
+
+---
+
+## 3. 部署要求
+
+### 3.1 每个节点必须具备的最小组合
+
+每台接入系统的 Mac、Windows、云工作机、独立测试台,至少都要有:
+
+- `Local Ops Agent`
+- `Local Ops Audit Agent`
+- `Health Probe Runner`
+- `Repair Runbook Executor`
+- `Ops Event Uploader`
+
+### 3.2 云端部署
+
+云端至少部署:
+
+- `Ops Control Plane`
+- `Ops Policy Engine`
+- `Ops Ledger`
+- `Chief Ops Audit Agent`
+- `Ops Extension Registry`
+- `Ops Connector Runtime`
+- `Standby Controller`
+
+### 3.3 主 Agent 的运维监管规则
+
+- 主 Agent 每小时至少主动检查一次运维层是否健康。
+- 检查内容包括:
+ - 每个节点的 `Ops Agent` 是否在线
+ - 每个节点的 `Ops Audit Agent` 是否在线
+ - 最近一次巡检是否成功
+ - 是否存在未结清的修复工单
+ - 是否存在长时间未复验完成的修复动作
+ - 运维层本身的控制面、账本、连接器和扩展注册是否健康
+
+### 3.4 运维层作为主运维层的边界
+
+主运维层至少要覆盖两类对象:
+
+- `系统内域`
+ 当前这套 Codex 协作系统内部组件
+- `外部项目域`
+ 后续接入的其他项目、其他机器群、其他测试台、其他后台服务
+
+这意味着运维层的数据模型里必须有:
+
+- `domain_id`
+- `domain_type`
+- `connector_type`
+- `ownership_scope`
+- `runbook_pack_version`
+
+---
+
+## 4. 动态巡检频率
+
+### 4.1 高频模式
+
+以下任一条件满足时,巡检频率切到 `每 5 分钟`:
+
+- 有用户正在手机端 / Web 端活跃使用
+- 有项目正在执行
+- 有 Worker thread 正在跑任务
+- 有能力租约正在占用摄像头、串口、机器人等硬件
+- 有未完成的审计任务
+- 有未关闭的高优先级告警
+
+### 4.2 空闲模式
+
+以下条件全部满足时,巡检频率降到 `每 1 小时`:
+
+- 当前没有在线用户会话
+- 没有任何活跃项目或任务
+- 没有任何设备租约占用
+- 没有现场测试正在运行
+- 没有待处理高优先级故障
+
+### 4.3 模式切换策略
+
+- 由 `Ops Policy Engine` 根据近 10 分钟活动窗口判定模式。
+- 切换时写入事件:
+ - `ops_mode_switched_to_active`
+ - `ops_mode_switched_to_idle`
+
+---
+
+## 5. 故障命名与日志规范
+
+### 5.1 设计目标
+
+日志必须做到:
+
+- 一眼能看出故障发生在哪个环节
+- 一眼能看出受影响组件和动作
+- 能直接映射到修复 Runbook
+- 让主 Agent、Ops Agent、Ops Audit Agent 都能低 token 地总结问题
+
+### 5.2 统一命名格式
+
+建议所有错误键都遵循:
+
+`