krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: ship native boss android console

Browse Source
This commit is contained in:
kris
2026-03-26 23:16:56 +08:00
parent 90e904814d
commit 90cb6b7ff1
261 changed files with 40051 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
docs/architecture/ai_handoff_index_cn.md Normal file
View File

@@ -0,0 +1,195 @@
# Boss 项目 AI 交接总入口
这份文档的目标是让另一个 AI 线程在不依赖当前对话上下文的情况下，直接接管 `/Users/kris/code/boss`。
## 1. 当前项目是什么
当前仓库已经落地了一个可运行的 Boss 控制台 MVP，包含：
- 一个基于 `Next.js App Router` 的移动端风格 Web 控制台
- 一个本地 `device-agent`
- 一个原生 Android 客户端，可直接构建 APK
- 一组已经落地的 `/api/v1/*` 聚合接口、线程预算接口和 SSE 出口
- 一套可工作的 `Caddy + systemd + launchd` 部署链路
- 已整理进仓库的 UI 原稿、架构文档、部署文档和交接提示词
## 2. 先读顺序
1. `README.md`
2. `docs/architecture/repo_map_cn.md`
3. `docs/architecture/current_runtime_and_deploy_status_cn.md`
4. `docs/architecture/api_and_service_inventory_cn.md`
5. `docs/architecture/boss_server_connection_and_deploy_cn.md`
6. `docs/architecture/wechat_project_conversation_mapping_cn.md`
7. `docs/architecture/thread_context_budget_and_handoff_protocol_cn.md`
8. `prompts/codex_fullstack_build_and_deploy_prompt_cn.md`
## 3. 当前有效实现边界
当前真正生效的内容只有这些：
- `src/app`：页面和 API
- `src/components`：共享 UI 和交互组件
- `src/lib/boss-data.ts`：当前状态模型和文件存储
- `src/lib/boss-auth.ts`：最小会话 Cookie 和页面 / API 鉴权辅助
- `src/lib/boss-device-auth.ts`：设备 token / 登录会话混合鉴权辅助
- `src/lib/boss-events.ts`：SSE 事件总线
- `src/lib/boss-master-agent.ts`：主 Agent 真实回复链路、Master Codex Node relay 与 API 容灾逻辑
- `src/lib/boss-ota.ts`：APK OTA 产物定位与元数据读取
- `src/lib/boss-projections.ts`：当前聚合 BFF 投影视图
- `src/components/app-runtime.tsx`：APP 日志桥、SSE 刷新和 Skill 面板
- `local-agent/server.mjs`：设备端心跳和 thread-context 上报服务
- `local-agent/config.cloud.json`：本机常驻 agent 对接 `https://boss.hyzq.net` 的生产配置
- `local-agent/config.example.json`：本地 `127.0.0.1:3000` 回环开发配置
- `deployment`：部署配置
- `scripts`：启动和部署脚本
- `android`：原生 Android 客户端工程
- `android/app/src/main/java/com/hyzq/boss/MainActivity.java`：原生入口 Activity
- `android/app/src/main/java/com/hyzq/boss/BossApiClient.java`：原生 API 客户端
- `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`：原生项目详情、消息、目标/版本/转发入口
- `android/app/src/main/java/com/hyzq/boss/DeviceDetailActivity.java`：原生设备详情和技能入口
- `android/app/src/main/java/com/hyzq/boss/AiAccountsActivity.java`：原生 AI 账号管理页
- `android/app/src/main/java/com/hyzq/boss/OpsCenterActivity.java`：原生运维 / 审计中心
- `android/signing/release-signing.properties.example`：release 签名模板
这些不是当前运行真相：
- `docs/source-material`
- `deploy`
- `src/boss_control`
- `src/boss_device_agent`
## 4. 当前运行真相
本地：
- Web 已可运行
- `GET /api/health` 正常
- `GET /api/v1/conversations` 正常
- `GET /api/v1/projects/master-agent` 正常，主 Agent 项目页已能看到 APP 实时日志
- `GET /api/v1/accounts` 正常，已返回主 GPT / 备用 GPT / API 容灾摘要
- `GET /api/v1/devices/mac-studio/skills` 正常
- `POST /api/auth/login` 正常，会写入 `boss_session`
- `boss_session` 当前默认保持 30 天
- `GET /api/auth/session` 正常
- `POST /api/auth/restore` 正常，原生 Android 客户端可用 `restore token` 自动恢复登录态
- `GET /api/v1/app-logs` 正常，可按登录态分页读取 APP 日志
- `POST /api/v1/projects/master-agent/messages` 正常，已验证通过 `local-agent -> codex exec -> complete` 返回真实主 Agent 回复
- `GET /api/v1/user/ota/package` 正常，当前会返回最新 APK
- `npm run apk:release` 正常，已能输出 signed release APK
- 当前原生 Android 页面已覆盖会话、设备、我的三栏和主要二级页，不再依赖 WebView 承载业务页面
- 本地 `device-agent` 正常
- 本地 agent 手动 heartbeat 后会同时上报 `thread-context`
- 本地 agent 会递归扫描 `~/.codex/skills` 并同步设备 Skill
- 设备写接口 `POST /api/v1/app-logs`、`POST /api/v1/devices/[deviceId]/skills`、`POST /api/v1/workers/[workerId]/thread-context` 已加设备 token / 会话鉴权
- fixed 验证码 `000000` 已改成先申请再校验；`send-code` 会按用途校验账号是否存在
- `launchd` 常驻已安装
服务器：
- 服务器地址：`106.53.170.158`
- 用户：`ubuntu`
- 代码路径：`/opt/boss`
- `boss-web.service` 正常
- `caddy.service` 正常
域名：
- 服务器日志显示 `Caddy` 已为 `boss.hyzq.net` 成功获取证书
- 服务器本机 `dig` 已解析到 `106.53.170.158`
- 服务器本机 `--resolve` 打 `127.0.0.1:443` 能正常返回 `307 /auth/login`
- 当前本机网络虽然 `dig` 仍显示 `198.18.1.188`，但 `http://boss.hyzq.net` 已 `308`、`https://boss.hyzq.net` 已 `307 /auth/login`
- 当前本机和服务器本机访问 `https://boss.hyzq.net/api/health` 与 `https://boss.hyzq.net/api/v1/conversations` 都已返回正常数据
- 当前结论是：外部 HTTPS 现在可达，公网域名下的 Web API 也已经可用，但入口前面可能还有代理层或分裂 DNS，不要再沿用“443 未打通”的旧判断
## 5. 当前最重要的产品逻辑
- 一级导航固定：`会话 / 设备 / 我的`
- `会话` 页按项目渲染聊天列表，主 Agent 永远置顶
- 单设备项目显示单头像，多设备协作显示群聊式组合头像
- 非群聊项目显示线程上下文余量圆环
- 项目聊天页必须展示活跃线程预算、handoff 状态和主 Agent 调度摘要
- 主 Agent 项目页会实时吸收 APP 端日志，用于边对话边指导 APK / Web 优化
- 移动端 UI 已去掉假的状态栏与桌面预览壳；底部一级导航固定在视口底部，返回逻辑不会再把 APP 根页直接弹回桌面
- `项目目标` 支持用户编辑、主 Agent 复核、完成项自动划线
- `版本迭代记录` 只读，由主 Agent 汇总
- `我的 > 运维与修复 > 运维对话 / 审计对话`
- `我的 > AI 账号` 必须可查看和切换 `主 GPT / 备用 GPT / API 容灾`
- `我的 > 技能` 必须按绑定设备展示 Skill，并支持一键复制调用语句
- `设备` 页当前只允许出现生产设备，旧演示脏数据不能回流到正式视图
- 登录后必须形成最小会话，受保护页面和核心 `/api/v1/*` 接口不能再裸奔
- 必须保留登录、注册、忘记密码和验证码入口
## 6. 当前技术路线
- Web：`Next.js 16.2.1 + React 19`
- 数据：当前是文件型持久化 `data/boss-state.json`
- 状态写入：串行事务队列 + 原子写入 + `.bak` 备份恢复
- device-agent：原生 Node HTTP 服务
- 部署：`systemd + Caddy + launchd`
- 邮件：`Postfix + Dovecot`
- Android：`AppCompatActivity + 原生 XML 布局 + HttpURLConnection`
- 原生登录恢复：`SharedPreferences + restore token`
- 当前最新原生 APK：`2.1.0`（`versionCode=7`）
当前不要误判成已经用了：
- PostgreSQL
- Redis
- NATS
- 真实用户会话系统
## 7. 接手后的第一批验证
本地：
```bash
cd /Users/kris/code/boss
npm install
npm run build
npm run lint
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
npm run apk:debug
```
服务器：
```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 "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"
```
## 8. 当前已知未完成项
- 认证仍是 MVP 级别：虽然已有最小会话 Cookie，但还没有刷新令牌、跨端会话治理和 CSRF 防护
- 当前已补“原生 restore token 自动恢复”，但这仍不是完整的多端会话系统
- 当前默认最高管理员账号是 `17600003315`，默认密码 `boss123456`，并已绑定本机 Codex 节点
- 主 Agent 实时回复当前依赖被绑定设备的 `local-agent` 在线，并能在本机跑通 `codex exec`
- API 容灾当前由用户在 APP 的 `我的 > AI 账号` 中自行配置 `OpenAI API` 账号
- 服务器默认固定验证码仍是 `000000`
- 服务器邮件栈已部署完成，应用内也已经支持 email 模式，但默认开关还没切到 email
- OTA 版本中心、检查更新、执行升级和 APK 包下载已接通，但当前仍是文件型状态驱动的 MVP
- APP 实时日志同步、主 Agent 日志镜像、SSE 自动刷新和 Skill 同步页已经接通，但日志检索、告警和远程 Skill 管理仍未做
- 数据库尚未替代文件存储
- 域名入口的代理 / 分裂 DNS 结构仍未完全摸清
- 图片 / 视频真实文件上传仍未接对象存储
- 认证没有真实 session 和令牌吊销
## 9. 继续开发时的工作原则
- 不要先重构，再理解现状
- 先以当前运行中的 MVP 为真相
- 每次改动都同步文档
- 只在有明确收益时再引入更重的基础设施

552
docs/architecture/api_and_service_inventory_cn.md Normal file
View File

@@ -0,0 +1,552 @@
# Boss API 与服务清单
这份文档只记录当前已经实现并可用的服务和接口。
## 1. 服务清单
### 1.1 boss-web
- 形态：Next.js App Router 服务
- 本地端口：`3000`
- 本地健康检查：`GET /api/health`
- 服务器进程：`boss-web.service`
- 服务器工作目录：`/opt/boss`
- 状态文件：通过 `BOSS_STATE_FILE` 显式指向 `data/boss-state.json`
- 当前登录态：`boss_session` HttpOnly Cookie
- 当前原生恢复态：`restore token + SharedPreferences`
### 1.2 boss-android-native
- 形态：原生 Android 客户端
- 原生入口：`android/app/src/main/java/com/hyzq/boss/MainActivity.java`
- API 客户端：`android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
- 当前导航：`会话 / 设备 / 我的`
- 当前原生活动页：
- `MainActivity`
- `ProjectDetailActivity`
- `ProjectGoalsActivity`
- `ProjectVersionsActivity`
- `ProjectForwardActivity`
- `ThreadDetailActivity`
- `DeviceDetailActivity`
- `DeviceEnrollmentActivity`
- `SkillInventoryActivity`
- `SecurityActivity`
- `SettingsActivity`
- `AiAccountsActivity`
- `OpsCenterActivity`
- `AboutActivity`
- 当前登录：临时免验证，点击登录直接创建最高管理员会话
- 当前会话恢复：`SharedPreferences` 中保存 `boss_session / restore_token / account`
### 1.3 boss-local-agent
- 形态：Node 原生 HTTP 服务
- 本地端口：默认 `4317`
- 健康检查：`GET /health`
- 当前常驻方式：`launchd`
- 当前额外职责：向云端上报 `thread-context`
- 当前新增职责：递归扫描本机 `~/.codex/skills` 并同步到设备 Skill 接口
### 1.4 Caddy
- 作用：反向代理和 HTTPS 自动续签
- 服务器服务名：`caddy.service`
- 配置文件：`deployment/Caddyfile`
### 1.5 boss-server-debug skill
- 作用：跨 Codex 窗口稳定连接 `106.53.170.158`
- 路径：`$HOME/.codex/skills/boss-server-debug/SKILL.md`
- 密码来源：优先读取 macOS Keychain
### 1.6 Postfix + Dovecot
- 作用：服务器侧邮件发送 / 接收基础设施
- SMTP 端口：`25 / 465 / 587`
- IMAPS 端口：`993`
- 本机测试邮箱：`bossmail`
- 当前别名：`verify@boss.hyzq.net`、`no-reply@boss.hyzq.net`
- 部署脚本：`scripts/install-server-mail.sh`
- 服务器配置目录：`deployment/mail/`
- Web 切换入口：`/opt/boss/.env.server`
## 2. Web 页面路由
### 2.1 一级页
- `GET /auth/login`
- `GET /conversations`
- `GET /devices`
- `GET /me`
### 2.2 二级页
- `GET /auth/register`
- `GET /auth/forgot-password`
- `GET /auth/help`
- `GET /conversations/[projectId]`
- `GET /conversations/[projectId]/forward`
- `GET /conversations/[projectId]/goals`
- `GET /conversations/[projectId]/versions`
- `GET /threads/[threadId]`
- `GET /devices/add`
- `GET /me/security`
- `GET /me/about`
- `GET /me/ai-accounts`
- `GET /me/ops`
- `GET /me/ops/audit`
- `GET /me/settings`
- `GET /me/skills`
## 3. Web API 路由
### 3.1 健康和状态
#### `GET /api/health`
- 用途：Web 健康检查
- 响应：`{ ok, service, now }`
#### `GET /api/state`
- 用途：读取当前完整状态
- 注意：这是内部 MVP 调试接口，会直接返回整个 `BossState`
### 3.2 认证相关
#### `POST /api/auth/send-code`
- 用途：生成验证码
- 输入：
- `account`
- `purpose`: `login | register | forgot-password`
- 当前行为：在邮件验证码正式切换前，固定验证码为 `000000`
- 当前说明：Web 侧已经支持 email 模式，email 模式下会通过本机 `sendmail` 调用 `Postfix` 发信；服务器默认仍保持 fixed
- 当前保护：60 秒冷却，同一账号 15 分钟窗口内超过 5 次会被限流
- 当前前置校验：
- `purpose=login | forgot-password` 时要求账号已存在
- `purpose=register` 时要求账号尚未注册
- 当前 fixed 模式：登录可直接输入 `000000`，不再依赖先申请验证码；注册和重置密码仍走 `send-code` 申请链路
#### `POST /api/auth/login`
- 输入：
- `account`
- `method`: `password | code`
- `password`
- `code`
- 当前行为：
- 当前已临时切到免验证模式，点击登录会直接创建 `17600003315` 的最高管理员会话
- 当前阶段不会因为账号、密码或验证码为空而拒绝登录
- 校验通过后会写入 `boss_session` Cookie
- 当请求头带 `x-boss-native-app: 1` 时，还会额外返回 `restoreToken`
- 当前 `boss_session` 默认保持 30 天
- 连续失败 5 次后会锁定 10 分钟
- 当前密码存储：新注册 / 重置密码使用 `scrypt`；历史 `sha256` 会在下次密码登录时自动迁移
- 当前默认管理员账号：`17600003315`
- 当前默认测试密码：`boss123456`
#### `GET /api/auth/session`
- 用途：读取当前登录会话信息
- 返回：
- `account`
- `role`
- `displayName`
- `loginMethod`
- `expiresAt`
- `lastSeenAt`
- 当请求头带 `x-boss-native-app: 1` 时，还会返回：
- `restoreToken`
#### `POST /api/auth/restore`
- 用途：原生 APP 使用 `restore token` 恢复 `boss_session`
- 输入：
- `restoreToken`
- 当前行为：
- 校验 `restoreToken` 是否对应未过期的登录会话
- 校验通过后重新写入 `boss_session` Cookie
- 用于 OTA / 同签名覆盖安装后的自动登录恢复
#### `POST /api/auth/logout`
- 用途：注销当前登录会话并清除 `boss_session`
#### `POST /api/auth/register`
- 输入：
- `account`
- `password`
- `confirmPassword`
- `code`
#### `POST /api/auth/forgot-password`
- 输入：
- `account`
- `password`
- `confirmPassword`
- `code`
### 3.3 设备心跳和当前老接口
#### `POST /api/device-heartbeat`
- 用途：设备端心跳上报
- 输入：
- `deviceId`
- `token`
- `pairingCode`
- `name`
- `avatar`
- `account`
- `status`
- `quota5h`
- `quota7d`
- `projects`
- `endpoint`
- 当前行为：
- 写入 `data/boss-state.json`
- 更新设备状态
- 若 `pairingCode` 合法，则 claim 设备绑定草稿并返回 token
#### `POST /api/projects/[projectId]/goals/[goalId]/toggle`
- 用途：切换目标完成状态
- 输出：更新后的 `goal`
#### `POST /api/projects/[projectId]/goals/update`
- 用途：编辑或新增目标
- 输入：
- `goalId`
- `text`
- `action`: `create | update`
- 输出：更新后的 `goal`
### 3.4 聚合 BFF / 实时接口
#### `GET /api/v1/conversations`
- 用途：返回首页会话列表聚合结果
- 关键字段：
- `conversationType`
- `manualPinned`
- `contextBudgetIndicator`
- `mustFinishBeforeCompaction`
#### `POST /api/v1/conversations/[projectId]/actions`
- 用途：会话置顶 / 标记已读
- 输入：
- `action`: `toggle_pin | mark_read`
#### `GET /api/v1/projects/[projectId]`
- 用途：项目详情聚合
- 返回：
- `activeThreadContexts`
- `threadsRequiringHandoff`
- `nextCompactionRiskThreadId`
- `masterContextStrategySummary`
- `recentAppLogs`
- `openFaults`
- `relatedAuditResults`
- `masterIdentity`（仅主 Agent 项目）
#### `POST /api/v1/projects/[projectId]/messages`
- 用途：向项目消息账本写文本/语音/图片/视频意图消息
- 输入：
- `body`
- `kind`: `text | voice_intent | image_intent | video_intent`
- 当前行为：
- 普通项目直接写入消息账本
- `projectId=master-agent` 且 `kind=text` 时，会继续触发主 Agent 真实回复链路
- 当前主链路优先走 `Master Codex Node`：`task queue -> local-agent -> codex exec -> complete`
- 如本机节点未接通，可切到 `OpenAI API` 容灾账号
#### `GET /api/v1/accounts`
- 用途：返回 AI 账号列表、当前主控身份和切换历史
#### `POST /api/v1/accounts`
- 用途：新增 AI 账号
- 当前 provider：
- `master_codex_node`
- `openai_api`
- 当前产品语义：
- `master_codex_node` 表示已经在绑定电脑上登录 `ChatGPT Plus / Codex` 的执行节点
- `openai_api` 只作为用户自行配置的 API 容灾
#### `GET /api/v1/accounts/[accountId]`
- 用途：读取单个 AI 账号详情
#### `PATCH /api/v1/accounts/[accountId]`
- 用途：更新 AI 账号配置、启停状态和说明
#### `DELETE /api/v1/accounts/[accountId]`
- 用途：删除非环境回退型 AI 账号
#### `POST /api/v1/accounts/[accountId]/activate`
- 用途：切换当前主控 AI 身份
#### `POST /api/v1/accounts/[accountId]/validate`
- 用途：校验指定 AI 账号是否可用
- 当前行为：
- `master_codex_node`：校验是否配置节点 ID，并提示由 local-agent relay 执行
- `openai_api`：实际调用模型返回探针结果
- 当前约束：
- `openai_api` 的容灾 Key 由用户在 APP 内配置，不走服务器默认预置
#### `POST /api/v1/projects/[projectId]/forwards`
- 用途：把消息转发到另一个项目
- 输入：
- `targetProjectId`
- `note`
#### `POST /api/v1/projects/[projectId]/goals`
- 用途：新增项目目标
- 输入：
- `text`
#### `GET /api/v1/threads/[threadId]/context-budget`
- 用途：查看单线程预算、handoff 包和 alert
#### `POST /api/v1/workers/[workerId]/thread-context`
- 用途：worker / local-agent 上报线程上下文预算
- 输入：
- `nodeId`
- `projectId`
- `taskId`
- `threadId`
- `title`
- `summary`
- `contextBudgetRemainingPct`
- `contextBudgetLevel`
- `mustFinishBeforeCompaction`
- `checklist`
- 返回：
- `accepted`
- `next_required_report_in_seconds`
- `master_actions`
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话
#### `GET /api/v1/devices`
- 用途：读取设备列表、绑定草稿和可选设备工作区详情
- 当前行为：只返回生产链路设备，旧演示设备不会再进入正式设备视图
#### `GET /api/v1/devices/enrollments`
- 用途：读取设备绑定草稿
#### `POST /api/v1/devices/enrollments`
- 用途：生成 `pairing code + token` 形式的设备绑定草稿
#### `PATCH /api/v1/devices/[deviceId]`
- 用途：修改设备名称、头像、账号、状态、endpoint、备注和项目列表
#### `GET /api/v1/devices/[deviceId]/skills`
- 用途：读取指定设备已经同步上来的 Skill 列表
- 返回：
- `device`
- `skills`
#### `POST /api/v1/devices/[deviceId]/skills`
- 用途：由 local-agent 覆盖式同步指定设备的 Skill 列表
- 输入：
- `skills[].name`
- `skills[].description`
- `skills[].path`
- `skills[].invocation`
- `skills[].category`
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话
#### `GET /api/v1/app-logs`
- 用途：分页查询 APP 日志
- 查询参数：
- `limit`
- `cursor`
- `deviceId`
- `projectId`
- `level`
- `category`
- `source`
- 当前保护：要求有效 `boss_session`
#### `POST /api/v1/app-logs`
- 用途：接收 APP 端实时日志
- 输入：
- `deviceId`
- `projectId`
- `level`
- `category`
- `message`
- `detail`
- `mirrorToMaster`
- 当前行为：
- 追加到状态文件 `appLogs`
- 可选镜像到主 Agent 项目消息账本
- 触发 `app.logs.updated`
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话
#### `POST /api/v1/settings`
- 用途：更新“我的 > 设置”
#### `GET /api/v1/user/ota`
- 用途：读取当前版本、待升级 OTA、权限和 OTA 日志
#### `POST /api/v1/user/ota`
- 用途：检查更新或触发当前 OTA 升级并回写版本号
- 输入：
- `action`: `check | apply`
#### `GET /api/v1/user/ota/package`
- 用途：下载当前已发布的最新 APK 安装包
- 当前来源：`public/downloads/boss-android-latest.apk`
- 当前归档：发布脚本还会额外保留 `public/downloads/boss-android-v{versionName}-{flavor}.apk`
- 当前保护：要求有效 `boss_session`
#### `GET /api/v1/ops/summary`
- 用途：读取运维 `fault / repair ticket / verification` 聚合数据
#### `POST /api/v1/ops/repair-tickets/[ticketId]/approve`
- 用途：主 Agent 批准修复工单
#### `POST /api/v1/ops/repair-tickets/[ticketId]/verify`
- 用途：运维审计复验修复工单
#### `GET /api/v1/audits/summary`
- 用途：读取 audit request / result / capability 聚合数据
#### `GET /api/v1/events`
- 用途：SSE 订阅会话、项目风险、设备、日志和 OTA 摘要事件
- 当前事件：
- `conversation.context_indicator.updated`
- `project.context_risk.updated`
- `conversation.updated`
- `project.messages.updated`
- `app.logs.updated`
- `devices.updated`
- `devices.skills.updated`
- `ota.updated`
- `master_agent.task.updated`
- 当前保护：要求有效 `boss_session`
#### `POST /api/v1/master-agent/tasks/claim`
- 用途：由 local-agent 认领分配给本机的主 Agent 任务
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话
#### `POST /api/v1/master-agent/tasks/[taskId]/complete`
- 用途：由 local-agent 回写主 Agent 任务完成结果
- 输入：
- `deviceId`
- `status`: `completed | failed`
- `replyBody`
- `errorMessage`
- `requestId`
- 当前行为：
- `completed` 时把真实主 Agent 回复写回 `master-agent` 项目消息账本
- `failed` 时写入 relay 失败消息，并更新 AI 账号健康状态
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话
## 4. local-agent 接口
### 4.1 `GET /health`
- 用途：本地 agent 健康检查
- 输出：
- `ok`
- `service`
- `runtime`
### 4.2 `GET /api/v1/device`
- 用途：读取本地 agent 配置和最近一次心跳结果
### 4.3 `GET /api/v1/skills`
- 用途：读取本机最近一次扫描到的 Skill 列表和同步状态
### 4.4 `POST /api/v1/heartbeat`
- 用途：手动触发一次心跳
- 当前行为：除了设备心跳，还会顺带触发 `thread-context` 上报和 Skill 同步
### 4.5 主 Agent 轮询任务
- local-agent 会周期性请求 `POST /api/v1/master-agent/tasks/claim`
- 认领到任务后会执行本机 `codex exec`
- 执行完成后会调用 `POST /api/v1/master-agent/tasks/[taskId]/complete`
## 5. 当前状态存储
当前没有正式数据库，真实数据来自：
- `data/boss-state.json`
关键对象：
- `user`
- `devices`
- `projects`
- `verificationCodes`
- `verificationDispatches`
- `authAccounts`
- `authSessions`
- `aiAccounts`
- `aiAccountSwitchHistory`
- `threadContextSnapshots`
- `threadHandoffPackages`
- `threadContextAlerts`
- `deviceEnrollments`
- `deviceSkills`
- `appLogs`
- `masterAgentTasks`
- `opsFaults`
- `opsRepairTickets`
- `opsRepairVerifications`
- `auditRequests`
- `auditResults`
- `capabilities`
## 6. 当前实现边界
当前这份清单只覆盖已经落地的接口，不覆盖设计文档里未来可能演进的能力。
不要误以为已经存在：
- 正式数据库
- 正式鉴权中间件
- 图片 / 视频真实文件上传和对象存储
- 完整的多端用户会话系统与刷新令牌体系

154
docs/architecture/boss_server_connection_and_deploy_cn.md Normal file
View File

@@ -0,0 +1,154 @@
# Boss 服务器连接与部署说明
## 1. 服务器信息
- 主机：`106.53.170.158`
- 用户：`ubuntu`
- 域名：`boss.hyzq.net`
当前优先连接方式不是手敲 `ssh`，而是仓库外已经建好的 skill：
- `~/.codex/skills/boss-server-debug/SKILL.md`
## 2. 连接方式
```bash
ssh ubuntu@106.53.170.158
```
或直接使用 skill：
```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" login
```
密码当前已经存入本机 macOS Keychain，避免后续 Codex 线程因背景压缩丢失连接方式。
## 3. DNS 与 HTTPS 前提
当前要启用 `https://boss.hyzq.net`，必须先满足：
- `boss.hyzq.net` 的 A 记录指向 `106.53.170.158`
仓库里已提供：
- `deployment/Caddyfile`
- `scripts/bootstrap-server.sh`
- `scripts/deploy-server.sh`
- Codex skill：`boss-server-debug`
DNS 生效后，`Caddy` 会自动申请和续签证书。
## 4. 服务器部署步骤
本地发起部署：
```bash
cd /Users/kris/code/boss
./scripts/deploy-server.sh
```
当前 `deploy-server.sh` 已支持：
- 优先读取 macOS Keychain 中保存的服务器密码
- 若 Keychain 不可用，则读取 `BOSS_SERVER_PASS`
- 远端 `npm run build` 前自动清理 `.next`
- 重启 `boss-web` / `caddy` 后自动执行 `curl -fsS http://127.0.0.1:3000/api/health`
如果需要覆盖服务器默认环境，可在服务器写入：
```bash
sudo cp /opt/boss/.env.server.example /opt/boss/.env.server
sudo systemctl restart boss-web
```
当前最重要的开关是：
- 默认固定码：`BOSS_AUTH_VERIFICATION_MODE=fixed`
- 临时切到真实邮件：`BOSS_AUTH_VERIFICATION_MODE=email`
部署服务器邮件栈：
```bash
cd /Users/kris/code/boss
./scripts/install-server-mail.sh
```
当前 `install-server-mail.sh` 会：
- 先复用 `deploy-server.sh` 同步代码和重启 Web
- 再通过 `boss-server-debug` skill 包装器执行远端邮件安装
- 在服务器上安装 `Postfix + Dovecot + swaks`
- 创建本机测试邮箱 `bossmail`
- 配置别名 `verify@boss.hyzq.net` 与 `no-reply@boss.hyzq.net`
- 将 Caddy 已签发的 `boss.hyzq.net` 证书同步给邮件服务
- 安装 `boss-mail-cert-sync.timer`，用于后续证书轮转同步
如果需要在服务器上单独补环境：
```bash
cd /opt/boss
sudo ./scripts/bootstrap-server.sh
npm install
npm run build
sudo systemctl restart boss-web
sudo systemctl restart caddy
```
## 5. 本机 device-agent 启动
```bash
cd /Users/kris/code/boss
./scripts/start-local-agent.sh ./local-agent/config.example.json
```
健康检查：
- 本机 agent：`http://127.0.0.1:4317/health`
- 云端 web：`http://127.0.0.1:3000/api/health`
## 6. 为什么要保留这份文档
这份文档的作用是避免 Codex 在背景信息压缩后遗忘：
- 服务器地址
- 登录用户
- 部署入口脚本
- HTTPS 的实际前提条件
- 本机 device-agent 的启动方式
## 7. 当前部署状态（2026-03-25）
已完成：
- 服务器 `106.53.170.158` 已安装 `nodejs` 和 `caddy`
- 服务器已安装 `Postfix`、`Dovecot`、`swaks`
- `/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` 已返回新聚合数据
- `Caddy` 日志中已经出现 `certificate obtained successfully`，说明服务端证书申请链路已跑通
- 邮件服务已经监听 `25 / 465 / 587 / 993`
- 服务器本机已通过 `swaks` 走 `127.0.0.1:587 + STARTTLS + AUTH LOGIN` 成功发送测试邮件到 `verify@boss.hyzq.net`
- 测试邮件已经进入 `/home/bossmail/Maildir`
- `boss-web` 已支持 email 模式，并已通过临时写入 `/opt/boss/.env.server` 做过一次真实邮件验证码投递验证
当前需要继续复核的点：
- 当前本机环境下 `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,...}`
- 当前本机环境下 `curl https://boss.hyzq.net/api/v1/conversations` 已返回真实聚合数据
- 当前本机环境下 `nc -vz boss.hyzq.net 25 587 993` 已全部成功
- 服务器本机 `dig +short boss.hyzq.net` 已返回 `106.53.170.158`
- 服务器本机 `curl --resolve boss.hyzq.net:443:127.0.0.1 https://boss.hyzq.net -I` 已返回 `307 /auth/login`
- 服务器本机 `curl https://boss.hyzq.net/api/health` 已返回 `{"ok":true,...}`
- 服务器本机 `curl https://boss.hyzq.net/api/v1/conversations` 已返回真实聚合数据
因此当前结论更新为：公网 `443` 已经实际可用，`Caddy` 配置本身没有问题，而且域名下的 Web API 已经可以直接返回健康探针和业务数据；服务器邮件栈也已经上线，公网 `25 / 587 / 993` 当前可达。后续如果要继续排障，重点应放在“为什么当前网络下 `dig` 显示的是 `198.18.1.188`”这个入口结构，以及邮件域名的 SPF / DKIM / DMARC / MX 收口，而不是继续假设 443 没打开

843
docs/architecture/capability_registry_and_audit_protocol_cn.md Normal file
View File

@@ -0,0 +1,843 @@
# Capability Registry 与审计 Agent 协议开发规格
适用范围：
- Codex 多机协作系统
- 开放式测试硬件能力接入
- 软件审计、硬件审计、多模态审计、总审计 Agent
目标：
- 定义摄像头、麦克风、扬声器、串口、继电器、拇指机器人等能力如何注册、租约、抢占
- 定义审计 Agent 如何声明需要哪些能力、如何领取任务、如何返回结果
- 为后续数据库表结构、API、消息总线和前端 UI 提供统一协议基础
---
## 1. 总体设计原则
1. 任何真实硬件都不能被 Agent 直接“拿桌面控制权”式使用，必须经过标准化能力层。
2. 所有可调用外设都先注册为 `Capability`，再由租约系统分配使用权。
3. 一个能力可以是独占的，也可以是共享只读的，必须在注册时声明。
4. 抢占必须有优先级、原因、宽限期、证据和审计日志。
5. 审计 Agent 与普通开发线程一样，都只能通过协议调用能力，不能绕过能力层。
6. 视频、音频、大体积流优先在边缘节点做预处理，只上传关键证据和必要片段。
---
## 2. Capability Registry 设计
### 2.1 组件划分
- `Capability Provider`
运行在具体设备附近，负责暴露本机或本测试台的能力。
- `Capability Registry`
运行在云端，保存所有能力的元数据、状态、租约和历史。
- `Lease Manager`
负责发放、续租、释放和过期清理。
- `Preemption Manager`
负责抢占判定、优先级比较、宽限期通知和安全降级。
- `Capability Gateway`
对外提供统一 API，屏蔽底层设备差异。
- `Evidence Collector`
负责把截图、视频片段、串口日志、音频片段等证据统一归档。
### 2.2 核心实体
#### 2.2.1 CapabilityProvider
表示能力提供方，通常是一台 Mac、Windows、Linux 测试台，或一个挂载了外设的专用盒子。
字段：
- `provider_id`
- `node_id`
- `hostname`
- `platform`
- `gateway_version`
- `online_status`
- `last_heartbeat_at`
- `network_zone`
- `owner_type`
- `owner_display_name`
- `auth_mode`
- `labels`
#### 2.2.2 Capability
表示一个可调用能力实例。
字段：
- `capability_id`
- `provider_id`
- `node_id`
- `capability_type`
- `display_name`
- `status`
- `health_status`
- `lease_mode`
值：
- `exclusive`
- `shared_read`
- `shared_stream`
- `preemptible`
- `default_priority`
- `safety_locked`
- `tags`
- `location_label`
- `metadata_json`
- `constraints_json`
- `supported_actions`
- `evidence_modes`
- `created_at`
- `updated_at`
#### 2.2.3 CapabilityLease
表示一个能力租约。
字段：
- `lease_id`
- `capability_id`
- `holder_type`
值：
- `worker_thread`
- `audit_agent`
- `human_operator`
- `system`
- `holder_ref`
例如：
- `mac-01:thread-abc`
- `audit:hardware-auditor-01`
- `project_id`
- `purpose`
- `priority`
- `status`
值：
- `requested`
- `granted`
- `active`
- `renew_pending`
- `preempt_requested`
- `grace_period`
- `released`
- `expired`
- `revoked`
- `failed`
- `requested_at`
- `granted_at`
- `expires_at`
- `grace_until`
- `preempt_reason`
- `evidence_required`
#### 2.2.4 CapabilitySession
表示实际执行过程。
字段：
- `session_id`
- `lease_id`
- `action`
- `started_at`
- `ended_at`
- `status`
- `input_summary`
- `result_summary`
- `artifact_refs`
- `error_message`
#### 2.2.5 CapabilityArtifact
表示证据或产物。
字段：
- `artifact_id`
- `session_id`
- `artifact_type`
值：
- `image`
- `video_clip`
- `audio_clip`
- `serial_log`
- `sensor_dump`
- `ocr_text`
- `detection_json`
- `transcript`
- `storage_uri`
- `content_type`
- `captured_at`
- `duration_ms`
- `checksum`
- `metadata_json`
---
## 3. 能力类型定义
### 3.1 Camera
用途：
- 观察设备动作
- 录制关键帧和短视频
- OCR、目标检测、界面识别
关键元数据：
- `device_path`
- `resolution_options`
- `max_fps`
- `supports_snapshot`
- `supports_clip_recording`
- `supports_audio`
- `supports_ptz`
- `field_of_view`
支持动作：
- `snapshot`
- `record_clip`
- `start_stream`
- `stop_stream`
- `set_ptz`
### 3.2 Microphone
关键元数据：
- `sample_rate_options`
- `channels`
- `noise_profile`
- `supports_vad`
支持动作：
- `record_audio`
- `start_audio_stream`
- `stop_audio_stream`
### 3.3 Speaker
关键元数据：
- `output_device_id`
- `supported_formats`
- `max_volume`
支持动作：
- `play_tts`
- `play_audio_file`
- `set_volume`
- `stop_playback`
### 3.4 SerialPort
关键元数据：
- `port_name`
- `baud_rates`
- `parity_modes`
- `supports_binary`
支持动作：
- `open`
- `read`
- `write`
- `expect_pattern`
- `capture_log`
### 3.5 ThumbRobot
关键元数据：
- `robot_model`
- `axis_count`
- `supported_targets`
例如：
- `touchscreen`
- `physical_button`
- `keyboard`
- `movement_precision_mm`
- `supports_long_press`
- `supports_drag`
支持动作：
- `tap`
- `double_tap`
- `long_press`
- `drag`
- `type_keys`
- `press_hardware_button`
### 3.6 Relay
支持动作：
- `switch_on`
- `switch_off`
- `pulse`
### 3.7 ProgrammablePowerSupply
支持动作：
- `power_on`
- `power_off`
- `set_voltage`
- `set_current_limit`
- `measure_output`
### 3.8 ScreenCapture
支持动作：
- `screenshot`
- `record_screen_clip`
- `ocr`
---
## 4. 注册协议
### 4.1 Provider 注册
`POST /api/v1/capability-providers/register`
请求示例：
```json
{
"provider_id": "provider-winlab-01",
"node_id": "win-gpu-02",
"hostname": "win-gpu-02.local",
"platform": "windows",
"gateway_version": "0.1.0",
"network_zone": "lan",
"labels": ["lab", "gpu", "hardware-test"]
}
```
返回：
```json
{
"provider_id": "provider-winlab-01",
"accepted": true,
"heartbeat_interval_seconds": 10
}
```
### 4.2 Capability 批量注册
`POST /api/v1/capabilities/register`
请求示例：
```json
{
"provider_id": "provider-winlab-01",
"capabilities": [
{
"capability_id": "cam-front-01",
"capability_type": "camera",
"display_name": "前置观察摄像头",
"lease_mode": "exclusive",
"preemptible": true,
"supported_actions": ["snapshot", "record_clip", "start_stream", "stop_stream"],
"evidence_modes": ["image", "video_clip", "ocr_text"],
"metadata_json": {
"resolution_options": ["1920x1080"],
"max_fps": 30
}
},
{
"capability_id": "thumb-robot-01",
"capability_type": "thumb_robot",
"display_name": "拇指机器人 1 号",
"lease_mode": "exclusive",
"preemptible": false,
"supported_actions": ["tap", "long_press", "drag"]
}
]
}
```
### 4.3 Heartbeat 与状态更新
`POST /api/v1/capabilities/heartbeat`
用途：
- 更新 provider 在线状态
- 更新能力健康状态
- 上报正在执行的租约
- 上报本地错误或故障
---
## 5. 租约设计
### 5.1 申请租约
`POST /api/v1/capability-leases/request`
请求字段：
- `capability_id` 或 `capability_selector`
- `holder_type`
- `holder_ref`
- `project_id`
- `purpose`
- `priority`
- `requested_duration_seconds`
- `evidence_required`
- `preempt_if_needed`
请求示例：
```json
{
"capability_id": "cam-front-01",
"holder_type": "audit_agent",
"holder_ref": "audit:multimodal-auditor-01",
"project_id": "proj_device_assistant",
"purpose": "验证设备 LED 与屏幕切换是否符合交互脚本",
"priority": 75,
"requested_duration_seconds": 120,
"evidence_required": true,
"preempt_if_needed": true
}
```
### 5.2 续租
`POST /api/v1/capability-leases/{lease_id}/renew`
### 5.3 释放
`POST /api/v1/capability-leases/{lease_id}/release`
### 5.4 过期清理
Lease Manager 负责：
- 定时回收过期租约
- 清理失联 provider 持有的会话
- 把证据未上传完成的 session 标记为 `incomplete_evidence`
---
## 6. 抢占设计
### 6.1 优先级建议
- `100`：安全/紧急停机
- `90`：人工操作员
- `80`：总审计 Agent
- `75`：硬件审计 Agent
- `70`：多模态审计 Agent
- `65`：软件审计 Agent
- `50`：普通 worker 线程
- `20`：后台采样/非关键任务
### 6.2 抢占条件
只有以下条件全部满足时允许抢占：
1. 目标能力 `preemptible=true`
2. 当前租约不是 `safety_locked`
3. 新租约优先级高于当前租约
4. 抢占原因在白名单中
5. 当前 holder 不处于“不可中断动作”窗口
### 6.3 抢占流程
1. 新请求进入 Lease Manager
2. Preemption Manager 评估是否允许抢占
3. 向当前持有者发送 `preempt_requested`
4. 进入 `grace_period`
5. 到期后自动释放或强制收回
6. 新租约转为 `granted`
7. 全过程写事件和审计日志
### 6.4 不可中断动作
以下动作默认不可中断：
- 机器人正在按压或拖拽
- 可编程电源处于切换瞬间
- 固件烧录
- 继电器脉冲动作未完成
---
## 7. Capability 事件流
`GET /api/v1/capability-events/stream`
事件类型：
- `provider_registered`
- `capability_registered`
- `capability_health_changed`
- `lease_requested`
- `lease_granted`
- `lease_renewed`
- `lease_release_requested`
- `lease_released`
- `lease_expired`
- `lease_preempt_requested`
- `lease_preempted`
- `session_started`
- `session_completed`
- `session_failed`
- `artifact_uploaded`
---
## 8. 审计 Agent 任务协议
### 8.1 通用任务请求格式
所有审计任务统一使用 `AuditTaskRequest`。
字段：
- `protocol_version`
- `audit_request_id`
- `project_id`
- `project_name`
- `task_id`
- `source_thread_ref`
- `trigger`
值：
- `milestone`
- `merge_candidate`
- `failure_escalation`
- `scheduled_check`
- `human_request`
- `audit_type`
值：
- `software`
- `hardware`
- `multimodal`
- `chief`
- `priority`
- `objective`
- `system_context_summary`
- `acceptance_criteria`
- `risk_focus`
- `evidence_refs`
- `artifact_refs`
- `capability_requirements`
- `time_budget_seconds`
- `response_mode`
- `created_at`
- `metadata_json`
请求示例：
```json
{
"protocol_version": "1.0",
"audit_request_id": "auditreq_001",
"project_id": "proj_device_assistant",
"task_id": "task_led_validation",
"source_thread_ref": "mac-01:thread-ui-22",
"trigger": "milestone",
"audit_type": "multimodal",
"priority": 70,
"objective": "验证设备被唤醒后，屏幕、LED、语音播报与交互脚本是否一致",
"system_context_summary": "设备端已刷入固件 v0.9.2，等待做端到端唤醒测试",
"acceptance_criteria": [
"LED 在 2 秒内变蓝",
"屏幕切换到 listening 状态",
"扬声器播报欢迎语",
"摄像头观测到机械动作完成"
],
"evidence_refs": [],
"artifact_refs": [],
"capability_requirements": [
{ "capability_type": "camera", "mode": "exclusive" },
{ "capability_type": "speaker", "mode": "exclusive" },
{ "capability_type": "microphone", "mode": "exclusive" },
{ "capability_type": "thumb_robot", "mode": "exclusive" }
],
"time_budget_seconds": 300,
"response_mode": "structured_json"
}
```
### 8.2 通用任务响应格式
所有审计任务统一使用 `AuditTaskResult`。
字段：
- `audit_request_id`
- `audit_type`
- `status`
值：
- `completed`
- `failed`
- `needs_retry`
- `needs_human_review`
- `decision`
值：
- `pass`
- `fail`
- `warning`
- `inconclusive`
- `confidence`
- `summary`
- `findings`
- `required_actions`
- `used_capabilities`
- `artifact_refs`
- `timeline`
- `duration_ms`
- `completed_at`
---
## 9. 软件审计 Agent 协议
### 9.1 输入
在通用格式上追加：
- `repo_ref`
- `base_commit`
- `head_commit`
- `changed_files`
- `diff_refs`
- `build_results`
- `test_results`
- `coverage_summary`
- `runtime_logs`
- `api_contract_refs`
- `release_notes_draft`
### 9.2 输出
- `regression_risk_level`
- `coverage_gap_summary`
- `release_blockers`
- `contract_breaking_changes`
- `log_anomalies`
- `recommended_owner`
### 9.3 findings 格式
每条 finding 至少包含：
- `finding_id`
- `severity`
值：
- `critical`
- `high`
- `medium`
- `low`
- `title`
- `description`
- `evidence_ref_ids`
- `suggested_fix`
---
## 10. 硬件审计 Agent 协议
### 10.1 输入
在通用格式上追加：
- `device_topology`
- `firmware_version`
- `hardware_revision`
- `serial_log_refs`
- `sensor_snapshots`
- `power_state`
- `ota_result`
- `expected_state_machine`
- `hardware_test_steps`
- `required_capabilities`
### 10.2 输出
- `device_state_assessment`
- `firmware_mismatch`
- `sensor_anomalies`
- `serial_log_findings`
- `hardware_blockers`
- `recovery_actions`
### 10.3 典型结论
- 固件版本正确但状态机卡死
- 串口日志与预期不一致
- 传感器波动超阈值
- OTA 成功但设备未进入预期模式
---
## 11. 多模态审计 Agent 协议
### 11.1 输入
在通用格式上追加：
- `frame_refs`
- `video_clip_refs`
- `audio_clip_refs`
- `screen_capture_refs`
- `ocr_text_refs`
- `detector_output_refs`
- `interaction_script`
- `expected_visual_states`
- `expected_audio_states`
- `expected_actuator_states`
### 11.2 输出
- `observed_timeline`
- `visual_mismatches`
- `audio_mismatches`
- `interaction_failures`
- `perceptual_verdict`
- `needs_human_review_reason`
### 11.3 典型场景
- 摄像头看设备灯光变化是否正确
- 通过视频确认机械动作是否完成
- 通过音频片段判断 TTS 是否播报了正确内容
- 通过屏幕截图和 OCR 判断 UI 状态是否正确切换
---
## 12. 总审计 Agent 协议
### 12.1 输入
总审计 Agent 不直接看全部原始数据，优先读取：
- `software_audit_result`
- `hardware_audit_result`
- `multimodal_audit_result`
- `rules_audit_summary`
- `human_notes`
### 12.2 输出
- `final_decision`
值：
- `approved`
- `rejected`
- `needs_human_review`
- `partial_pass`
- `overall_risk_level`
- `blocking_reasons`
- `recommended_next_step`
- `handoff_target`
---
## 13. 能力需求声明格式
用于审计 Agent 和 worker 线程声明需要哪些外设。
字段：
- `capability_type`
- `mode`
值：
- `exclusive`
- `shared_read`
- `min_duration_seconds`
- `preferred_node_tags`
- `fallback_allowed`
- `preempt_if_needed`
- `purpose`
示例：
```json
[
{
"capability_type": "camera",
"mode": "exclusive",
"min_duration_seconds": 90,
"preferred_node_tags": ["lab", "device-station-a"],
"fallback_allowed": true,
"preempt_if_needed": true,
"purpose": "记录设备启动后 30 秒内的状态变化"
}
]
```
---
## 14. 最小数据库表建议
建议至少有这些表：
- `capability_providers`
- `capabilities`
- `capability_health_snapshots`
- `capability_leases`
- `capability_sessions`
- `capability_artifacts`
- `audit_requests`
- `audit_results`
- `audit_findings`
- `thread_registry`
- `inter_thread_messages`
---
## 15. MVP 实现建议
### V1
- 先做 `camera`、`serial_port`、`thumb_robot`
- 先支持：
- 注册
- 独占租约
- 基础抢占
- session 留痕
- artifact 归档
- 先做：
- 软件审计 Agent
- 硬件审计 Agent
- 多模态审计 Agent
- 总审计 Agent
### V2
- 增加 `microphone`、`speaker`、`screen_capture`
- 增加共享只读租约
- 增加跨设备联合测试流程
### V3
- 增加策略化预调度
- 增加能力热迁移
- 增加自动抢占编排和更细粒度安全策略
---
## 16. 一句话总结
`Capability Registry` 解决“哪些硬件能被谁调用”的问题，
`Lease / Preemption` 解决“什么时候谁能占用硬件”的问题，
`Audit Agent Protocol` 解决“审计任务如何标准化下发和回收”的问题。
这三者合在一起，才能让你的审计 Agent 真正做到可扩展、可监管、可复盘地接管真实世界的测试硬件。

280
docs/architecture/china_ui_reference_apps_cn.md Normal file
View File

@@ -0,0 +1,280 @@
# 中国区 UI 参考 App 清单（面向 Codex 多机协作系统）
更新时间：`2026-03-25`
这份清单不是在找“和我们一模一样”的产品，而是在中国区里，尽可能多地找出最接近这套系统的 UI 参考对象。
我们的目标页面包括：
- 单主 Agent 对话入口
- 项目列表 / 项目详情
- 线程详情 / 实时进度
- 设备列表 / 设备状态 / 远程控制
- 运维中心 / 告警中心 / 修复工单
- 审计中心 / 硬件测试中心
- 账号额度与主备状态提示
所以我把参考对象拆成 6 类：
- `A. 协同与单入口`
- `B. 研发管理与项目流转`
- `C. 远程控制与设备列表`
- `D. 运维监控与告警`
- `E. 设备 / 场景 / 多模态控制`
- `F. AI 助手与聊天入口`
---
## 1. 最值得优先看的 12 个
如果时间有限，我建议先看这 12 个：
1. 飞书
2. 钉钉
3. 企业微信
4. 向日葵
5. ToDesk
6. 腾讯云助手
7. 阿里云 App
8. 观测云
9. PingCode
10. TAPD
11. 米家
12. 腾讯元宝
原因：
- 这 12 个基本覆盖了你这套产品最核心的 UI 组合：
- 单入口聊天
- 项目和任务推进
- 设备列表与远控
- 运维监控与告警
- 场景化设备控制
- AI 助手入口
---
## 2. 我们这套产品最适合借鉴的 UI 组合
不是照抄某一个 App，而是建议组合借鉴：
### 2.1 首页壳层
- 借鉴：`飞书 + 企业微信 + 钉钉`
- 适合借的：
- 底部导航结构
- 消息 / 工作台 / 审批 / 我的 四段式信息架构
- 聊天页和工作页之间的轻切换
### 2.2 设备中心
- 借鉴：`向日葵 + ToDesk + 米家`
- 适合借的：
- 设备卡片
- 在线 / 离线 / 忙碌状态点
- 最近使用设备置顶
- 场景分组和快捷操作
### 2.3 项目与线程中心
- 借鉴：`PingCode + TAPD + 云效 + 飞书项目`
- 适合借的：
- 项目列表到项目详情的层级
- 里程碑、任务、线程之间的关系
- 卡片化状态流转
- 评论 / 动态 / 审批汇总
### 2.4 运维和告警中心
- 借鉴：`腾讯云助手 + 阿里云 App + 观测云 + 监控宝`
- 适合借的：
- 首页总览 + 告警列表 + 指标趋势
- 卡片式故障摘要
- 告警分级
- 处理动作入口前置
### 2.5 硬件测试与多模态页
- 借鉴：`米家 + 涂鸦 + 萤石云视频`
- 适合借的：
- 场景分组
- 视频预览卡片
- 设备共享与权限
- 自动化规则入口
### 2.6 AI 交互壳层
- 借鉴：`腾讯元宝 + 通义 + 豆包 + Kimi`
- 适合借的：
- 单输入框主入口
- 工具 / 助手 / 历史记录次级入口
- 文件、图片、语音等多模态输入组织
---
## 3. 详细参考清单
## A. 协同与单入口
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 飞书 | 最接近“消息 + 项目 + 文档 + 审批 + AI”的一体化入口 | 底部导航、统一搜索、项目入口、轻量化移动端工作台 | [官网总览](https://www.feishu.cn/content/article/7598492868155608024) / [飞书项目移动端](https://www.feishu.cn/content/rych8h5r) |
| 钉钉 | 适合看“工作台型”首页壳层 | 首页工作台、项目入口、任务与审批并存、AI 入口前置 | [钉钉官网](https://www.dingtalk.com/) / [钉钉项目](https://page.dingtalk.com/wow/dingtalk/act/project) |
| 企业微信 | 适合看“消息优先、工具次级”的企业协同入口 | 聊天入口、工作台、机器人入口、企业通知风格 | [App Store](https://apps.apple.com/cn/app/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1/id1189898970) |
| Worktile | 更适合看移动端任务、OKR、审批在一个壳里的组织方式 | 项目列表、任务卡、目标页、表单/审批混排 | [官网](https://worktile.com/) |
| Teambition | 适合看项目协作的轻量信息层级 | 清爽任务视图、轻项目结构、卡片化任务关系 | [官网](https://www.teambition.com/) |
| Clarity Design（Teambition） | 不是 App，但很值得参考其交互与组件语言 | 组件层次、信息密度控制、设计系统命名 | [设计系统](https://design.teambition.com/) |
## B. 研发管理与项目流转
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| PingCode | 最贴近“研发管理 + AI + 流程” | 项目首页、需求/缺陷/版本分层、智能化研发入口 | [官网](https://pingcode.com/) / [App 发布](https://blog.pingcode.com/v1-0-0-app-release/) / [v6.0](https://blog.pingcode.com/pingcode-v6/) |
| TAPD | 适合参考研发流转和多工作流支撑 | 工作项状态、迭代视图、自动化任务引擎感 | [官网](https://www.tapd.cn/) |
| 腾讯云 CODING | 适合参考 DevOps 工具链首页和项目切换结构 | 项目列表、代码/需求/流水线入口并列、工具链导航 | [官网](https://cloud.tencent.cn/product/coding) |
| 云效 | 适合参考“云上研发管理”的一体化信息组织 | 产品级导航、环境管理、项目到部署的串联 | [产品概述](https://help.aliyun.com/zh/yunxiao/product-overview/) |
| 禅道 | 适合参考国产研发管理工具的移动端取舍 | 项目集、产品、项目、聊天卡片跳转 | [移动端与桌面端](https://www.zentao.net/download/zentao-client-80038.mhtml) |
| 飞书项目 | 适合看“业务需求 -> 项目执行”的联动页 | 移动端项目入口、需求到项目跳转、流程视图 | [案例](https://project.feishu.cn/home/customer/lisen) / [移动端使用指南](https://www.feishu.cn/content/rych8h5r) |
| 腾讯云 Cloud Studio | 不是移动主 App，但适合看“云工作区 / 开发环境”的管理方式 | 工作区卡片、环境状态、模板入口 | [官网](https://cloud.tencent.com.cn/product/cloudstudio) |
## C. 远程控制与设备列表
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 向日葵 | 最贴近“跨平台远程设备控制” | 设备列表、在线状态、远控入口、设备分组 | [官网](https://oraypc.com.cn/) / [产品页](https://sunlogin-orayc.com/) |
| ToDesk | 适合看远程控制的移动端快速入口 | 最近设备、连接状态、快捷控制按钮、跨平台切换 | [官网](https://www.todesk.com/) |
| 贝锐蒲公英管理 App | 适合看“设备网络 / 组网 / 节点管理” | 节点列表、组网状态、硬件管理入口 | [贝锐官网](https://www.oray.com/) / [蒲公英管理 App](https://sunlogin.oray.com/news/34353.html) |
## D. 运维监控与告警
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 腾讯云助手 | 很适合看移动端云资源管理 | 告警页、资源列表、历史趋势、小屏指标卡片 | [官网](https://cloud.tencent.com/product/tca) |
| 阿里云 App | 很适合看“轻量移动控制台” | 首页总览、实例详情、监控与告警入口 | [阿里云 App](https://help.aliyun.com/document_detail/52854.html) / [RDS 监控示例](https://help.aliyun.com/document_detail/2863833.html) |
| 观测云 | 适合看现代可观测性产品的信息结构 | 总览面板、日志/链路/告警切换、AI 故障分析入口 | [官网](https://www.guance.com/) |
| 监控宝 | 适合看移动告警和性能趋势页 | 告警列表、性能图表、网站/API/服务器多类型监控 | [官网](https://www.jiankongbao.com/about.html) / [App 页](https://www.jiankongbao.com/new_app) |
| 堡塔 APP | 适合看“手机运维面板” | 服务器卡片、文件管理、快捷运维动作 | [官网](https://www.bt.cn/new/product/btapp.html) |
## E. 设备 / 场景 / 多模态控制
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 米家 | 非常适合参考“设备中心 + 场景中心 + 全屋看板” | 场景页、全屋动态看板、设备卡片分组、自动化入口 | [App Store](https://apps.apple.com/cn/app/%E7%B1%B3%E5%AE%B6/id957323480) |
| 涂鸦 OEM App | 适合看“多品牌设备统一控制”的模板化结构 | App 模板、设备主页、服务与运营入口并存 | [OEM App](https://www.tuya.com/cn/platform/appdev/oemapp) / [官网](https://www.tuya.com/cn/) |
| Powered by Tuya | 适合看“一个 App 统一控制多品牌设备”的生态逻辑 | 多设备兼容、统一入口、品牌层和设备层的分离 | [Powered by Tuya](https://www.tuya.com/cn/partners/powered-by-tuya) |
| 萤石云视频 | 很适合看摄像头 / 视频流 / 消息中心 UI | 实时视频卡片、录像回放、设备消息、家庭共享 | [App Store](https://apps.apple.com/cn/app/%E8%90%A4%E7%9F%B3%E4%BA%91%E8%A7%86%E9%A2%91/id571195405) |
## F. AI 助手与聊天入口
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 腾讯元宝 | 适合看中国区“AI 助手主入口”外形 | 单输入框、历史入口、轻工具栏、下载入口前置 | [官网](https://yuanbao.tencent.com/AI) |
| 通义 | 适合看“AI 助手 + 文档阅读 + 代码模式”的壳层 | 助手页、历史记录入口、文件对话 | [官网](https://tongyi.aliyun.com/) / [历史记录说明](https://tongyi.aliyun.com/blog/192631944) |
| 豆包 | 适合看“智能体平台化”的主入口趋势 | 智能体入口、语音 / 文档 / 多模态能力聚合 | [App Store](https://apps.apple.com/cn/app/%E8%B1%86%E5%8C%85-%E5%AD%97%E8%8A%82%E8%B7%B3%E5%8A%A8%E6%97%97%E4%B8%8Bai%E5%8A%A9%E6%89%8B/id6459478672?platform=ipad) / [豆包语音模型说明](https://research.doubao.com/blog/doubao-realtime-voice-model-is-available-upon-release-high-eq-and-iq) |
| Kimi | 适合看简洁型 AI 聊天工具壳层 | 极简主会话、低干扰历史与附件交互 | [App Store](https://apps.apple.com/cn/app/kimi/id6474233312) |
---
## 4. 针对我们产品，建议直接借鉴的页面级组合
## 4.1 手机首页
建议参考：
- 飞书
- 企业微信
- 钉钉
建议做法：
- 底部 `4 tab`
- `会话`
- `项目`
- `设备`
- `运维`
- 顶部小胶囊显示：
- `主 GPT`
- `备用 GPT`
- `API 容灾`
## 4.2 项目页
建议参考：
- PingCode
- TAPD
- 飞书项目
建议做法：
- 顶部是项目状态和里程碑
- 中部是任务列表 / 线程列表
- 底部是动态、审计、修复记录
## 4.3 设备页
建议参考：
- 向日葵
- ToDesk
- 米家
建议做法：
- 用卡片列出所有设备
- 每张卡片有：
- 在线状态
- 账号额度
- 当前线程数
- 可用能力
- 一键进入
## 4.4 运维页
建议参考：
- 腾讯云助手
- 阿里云 App
- 观测云
- 监控宝
建议做法：
- 先总览，再告警，再工单
- 每条告警都能直接进入修复或回放
## 4.5 审计与硬件页
建议参考：
- 米家
- 涂鸦
- 萤石云视频
建议做法：
- 摄像头预览卡片
- Test Rig 能力卡片
- 审计任务列表
- 当前租约状态
---
## 5. 我对 UI 方向的最终建议
如果你让我用一句话定调：
这套产品不要做成“一个聊天机器人 App”，而要做成：
`飞书 / 企业微信式的壳层`
`+ PingCode / TAPD 式的项目推进`
`+ 向日葵 / ToDesk / 米家式的设备中心`
`+ 腾讯云助手 / 观测云式的运维中心`
也就是说：
- 外层像企业协作 App
- 中层像研发管理 App
- 底层像设备 / 运维控制台
这会比单纯模仿任何一个 AI App 更适合你。

2113
docs/architecture/codex_multi_machine_architecture_cn.html Normal file
View File

File diff suppressed because it is too large Load Diff

238
docs/architecture/current_runtime_and_deploy_status_cn.md Normal file
View File

@@ -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`

1374
docs/architecture/detailed_technical_stack_cn.md Normal file
View File

File diff suppressed because it is too large Load Diff

764
docs/architecture/development_subtasks_and_delivery_plan_cn.md Normal file
View File

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

786
docs/architecture/ops_layer_and_repair_protocol_cn.md Normal file
View File

@@ -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 统一命名格式
建议所有错误键都遵循：
`<LAYER>.<DOMAIN>.<COMPONENT>.<ACTION>.<ERROR_CODE>`
例如：
- `ENTRY.APP.PROJECT_CREATE.VALIDATION_FAIL`
- `MASTER.SCHEDULER.DISPATCH.NODE_UNAVAILABLE`
- `WORKER.CODEX.THREAD_START.RATE_LIMIT`
- `THREAD.BROKER.MESSAGE_ROUTE.PERMISSION_DENIED`
- `AUDIT.MULTIMODAL.VERIFY.EVIDENCE_MISSING`
- `CAPABILITY.CAMERA.LEASE.PREEMPT_TIMEOUT`
- `DATA.POSTGRES.WRITE.REPLICATION_LAG`
- `OPS.LOCAL_AGENT.HEARTBEAT.MISSED`
- `OPS_AUDIT.REPAIR.VERIFY.RESTART_FAILED`
### 5.3 每条错误日志最少字段
- `fault_key`
- `severity`
- `node_id`
- `service_name`
- `project_id`
- `thread_ref`
- `trace_id`
- `runbook_id`
- `first_seen_at`
- `last_seen_at`
- `summary`
- `suggested_next_action`
### 5.4 日志分层前缀建议
- `ENTRY`
- `MASTER`
- `WORKER`
- `THREAD`
- `AUDIT`
- `CAPABILITY`
- `DATA`
- `AUTH`
- `QUOTA`
- `OPS`
- `OPS_AUDIT`
- `RECOVERY`
### 5.5 Token 节省策略
`Ops Agent` 汇报时不直接贴长日志，而是优先输出：
- `fault_key`
- 影响节点数
- 首次时间 / 最近时间
- top 3 关联错误
- 绑定的 `runbook_id`
- 当前是否可自动修复
---
## 6. 除日志之外的运维检测方式
只靠日志不够，建议同时启用以下机制：
### 6.1 心跳与存活探针
- 每个服务定期发送 heartbeat
- 每个节点的 `Ops Agent` 和 `Ops Audit Agent` 互相监督 heartbeat
- 主控、Worker、审计层、硬件网关都要有独立存活探针
### 6.2 合成探针 / 端到端冒烟
- 周期性模拟：
- 创建一个测试项目
- 下发一个轻量任务
- 启动一个测试线程
- 拉取一次线程历史
- 触发一次能力租约
- 如果冒烟链路断掉，说明系统虽然“进程活着”，但业务已经不通
### 6.3 队列与事件流监测
- 检测消息队列积压
- 检测 Event Store 写入延迟
- 检测线程消息是否长时间停滞
- 检测 SSE / WebSocket 是否失去推送
### 6.4 资源与性能监测
- CPU / 内存 / 磁盘 / GPU 占用
- WSL2 健康度
- 数据库复制延迟
- 对象存储写入失败率
- 网络抖动和丢包
### 6.5 认证与额度健康监测
- ChatGPT / Codex 登录态有效期
- API key 可用性
- gptpluscontrol 上报的新鲜度
- 5h / 7d 剩余额度阈值预警
### 6.6 配置与版本漂移检测
- Worker 版本不一致
- Gateway 配置漂移
- Runbook 版本落后
- 审计协议版本不兼容
### 6.7 孤儿状态清理
- 孤儿 lease
- 孤儿 thread
- 孤儿 repair ticket
- 无人接管的审计任务
### 6.8 本地屏幕 / 设备快照抽样
在硬件项目中，可周期性采样：
- 关键设备截图
- 摄像头关键帧
- 串口短日志
- UI OCR 状态
用于快速判断“服务活着但现场已经坏了”的情况。
---
## 7. 修复权限与决策规则
### 7.1 当主 Agent 在线且能正常返回信息
流程：
1. `Ops Agent` 发现问题
2. 生成修复建议与最小证据包
3. 向主 Agent 请求批准
4. 主 Agent 同意后，`Ops Agent` 执行修复
5. `Ops Audit Agent` 做复验
6. 复验结果回报主 Agent
原则：
- `Ops Agent` 不得自行越权修复
- 主 Agent 有权拒绝、延后、改用人工介入
- 复验未通过则不能直接关闭工单
### 7.2 当主 Agent 失联
定义失联建议：
- 连续 3 次心跳缺失，或
- 超过 15 分钟无法返回健康响应
流程：
1. `Ops Audit Agent` 确认主 Agent 失联
2. 通知 `Chief Ops Audit Agent`
3. 进入紧急运维模式
4. `Ops Audit Agent` 依据策略与证据，做最终是否修复的执行判断
5. `Ops Agent` 执行修复
6. `Ops Audit Agent` 复验
7. 修复结果写入 `Ops Ledger`
8. 主 Agent 恢复后，向其回放修复详情
### 7.3 当主 Agent 恢复在线
恢复后必须同步：
- 故障摘要
- 故障影响范围
- 已执行修复动作
- 修复结果
- 复验结论
- 是否仍有残余风险
- 是否需要人工复盘
### 7.4 当运维层自身挂了，但主 Agent 在线
这是一个单独处理场景，不能等同于普通服务故障。
定义运维层自身故障示例：
- `Ops Control Plane` 无法响应
- `Ops Ledger` 写入失败
- `Ops Connector Runtime` 大面积失效
- 多个节点的 `Ops Agent` / `Ops Audit Agent` 同时失联
- 运维层事件流中断
流程：
1. 主 Agent 在每小时健康检查或告警事件中发现运维层异常
2. 主 Agent 切换到 `ops_rescue_mode`
3. 主 Agent 通过独立的最小救援通道直连节点或备用控制器
4. 主 Agent 对运维层发起反向修复任务
5. 节点上的最小本地 Watchdog / Standby 代理执行运维层恢复
6. 恢复后由 `Ops Audit Agent` 复验运维层是否重新可用
7. 恢复结果写入账本，并结束 `ops_rescue_mode`
要求：
- 主 Agent 抢救运维层时，不能依赖已经损坏的运维控制面本身
- 必须保留至少一条最小救援通道，例如：
- 直连节点的紧急 RPC
- 备用控制器通道
- 本地 Watchdog 的保底命令接口
- 只读日志和健康快照通道
---
## 8. 运维修复状态机
### 8.1 Repair Ticket 状态
- `detected`
- `classified`
- `approval_pending`
- `approved_by_master`
- `approved_by_ops_audit_emergency`
- `repairing`
- `repair_failed`
- `verification_pending`
- `verified_pass`
- `verified_fail`
- `reported_to_master`
- `closed`
### 8.2 自动修复白名单
仅允许以下低风险动作默认自动化：
- 重启本地 Agent 进程
- 重连 WebSocket / SSE
- 重试心跳上传
- 重拉轻量配置
- 恢复日志采集
以下动作必须更高权限：
- 切换主账号 / 备用账号
- 重启数据库
- 回滚 Worker 版本
- 强制释放能力租约
- 重启 GPU Bridge
- 重刷固件 / 重置测试设备
---
## 9. 修复动作与复验规范
### 9.1 RepairAction 输入字段
- `repair_ticket_id`
- `fault_key`
- `node_id`
- `service_name`
- `decision_source`
值：
- `master_agent`
- `ops_audit_agent_emergency`
- `runbook_id`
- `action_type`
- `risk_level`
- `expected_result`
- `timeout_seconds`
### 9.2 RepairVerification 输出字段
- `repair_ticket_id`
- `verification_status`
值：
- `pass`
- `fail`
- `partial_pass`
- `inconclusive`
- `post_health_summary`
- `remaining_risks`
- `evidence_refs`
- `recommended_followup`
### 9.3 复验最少检查项
- 原故障是否停止出现
- 关键进程是否恢复
- 事件流是否恢复
- 相关接口是否恢复
- 如涉及硬件，现场状态是否恢复
- 是否引入新的副作用
---
## 10. 建议 API / 事件
### 10.1 API
- `POST /api/v1/ops/nodes/heartbeat`
- `POST /api/v1/ops/health/report`
- `POST /api/v1/ops/domains/register`
- `POST /api/v1/ops/connectors/register`
- `POST /api/v1/ops/remote-actions/request`
- `POST /api/v1/ops/remote-actions/{action_id}/approve`
- `POST /api/v1/ops/remote-actions/{action_id}/result`
- `POST /api/v1/ops/repair-tickets`
- `POST /api/v1/ops/repair-tickets/{ticket_id}/approval-request`
- `POST /api/v1/ops/repair-actions/start`
- `POST /api/v1/ops/repair-actions/{action_id}/result`
- `POST /api/v1/ops/repair-verifications`
- `POST /api/v1/ops/rescue/enter`
- `POST /api/v1/ops/rescue/actions/start`
- `POST /api/v1/ops/rescue/complete`
- `GET /api/v1/ops/events/stream`
### 10.2 事件
- `ops_agent_heartbeat_missed`
- `ops_audit_agent_heartbeat_missed`
- `ops_domain_registered`
- `ops_connector_registered`
- `ops_remote_action_requested`
- `ops_remote_action_approved`
- `ops_remote_action_completed`
- `ops_remote_action_failed`
- `ops_fault_detected`
- `ops_fault_classified`
- `ops_repair_approval_requested`
- `ops_repair_approved_by_master`
- `ops_repair_approved_by_ops_audit_emergency`
- `ops_repair_started`
- `ops_repair_completed`
- `ops_repair_failed`
- `ops_repair_verification_passed`
- `ops_repair_verification_failed`
- `ops_layer_degraded`
- `ops_rescue_mode_entered`
- `ops_rescue_action_started`
- `ops_rescue_action_completed`
- `ops_layer_recovered`
- `master_agent_offline_confirmed`
- `master_agent_recovered`
- `ops_repair_report_synced_to_master`
---
## 11. 最小数据库表建议
- `ops_nodes`
- `ops_domains`
- `ops_connectors`
- `ops_agent_heartbeats`
- `ops_audit_agent_heartbeats`
- `ops_faults`
- `ops_fault_occurrences`
- `ops_repair_tickets`
- `ops_repair_actions`
- `ops_repair_verifications`
- `ops_runbooks`
- `ops_mode_history`
- `ops_rescue_actions`
- `ops_reports_to_master`
---
## 12. MVP 建议
### V1
- 每个节点部署 `Local Ops Agent` 与 `Local Ops Audit Agent`
- 实现 heartbeat、fault_key 命名、repair ticket、主 Agent 审批、修复复验
- 高频 / 空闲巡检切换
- 主 Agent 对运维层的每小时健康检查
### V2
- 加入合成探针、业务冒烟、孤儿状态清理、主控离线后的紧急修复授权
- 加入主 Agent 恢复后的修复回放
- 加入 `Ops Domain / Connector / Runbook Pack` 的开放式接入
### V3
- 加入更精细的 Runbook 路由
- 加入多节点联动修复
- 加入版本回滚与策略化自愈
- 加入主 Agent 对运维层自身的反向抢救通道与 `ops_rescue_mode`
---
## 13. 一句话总结
`运维层` 解决“谁去发现、执行和扩展运维修复”的问题，
`运维审计层` 解决“谁有权批准、谁来复验、主控失联时谁来兜底”的问题。
它们必须常驻在每个节点，并且站在整个系统最外层，持续保护主控、Worker、审计层、硬件层、数据层，以及后续接入的其他项目运维域；当运维层自己挂掉时，还要允许主 Agent 反向抢救它。
---
## 14. 支持两种保活模式
运维层和运维审计层也要兼容两种备用接管模式：
### 14.1 单云 + 设备端备用池
说明：
- `Cloud A` 作为主用控制面
- 一台首选 `Standby Mac` 或其他设备，作为首选备用控制器
- 同时维护一个 `standby_device_pool` 作为后备容灾池
最低要求：
- 至少一台首选备用设备必须常开
- 必须具备独立于主云的可达路径
- 每台候选备用设备至少运行：
- `Standby Controller`
- `Local Ops Agent`
- `Local Ops Audit Agent`
- `Ops Rescue Gateway`
当主云故障时：
1. 当前活动备用设备接收主控失联告警
2. 提升本机备用控制面
3. 恢复最小项目视图、工单视图、修复审批链路
4. 运维审计层继续做复验和修复回放
### 14.2 双云热备 / 温备
说明：
- `Cloud A` 主用
- `Cloud B` 备用
最低要求：
- `Cloud B` 只做接管准备，不承担常态重负载
- 保留备用控制面、备库、快照和恢复钩子
当主云故障时：
1. `Cloud B` 接管控制面
2. `Chief Ops Audit Agent` 继续保留紧急修复判定权
3. 现场各节点 `Local Ops Agent` 继续执行修复动作
4. 主云恢复后，再做账本回放与状态对账
### 14.3 统一抽象
无论采用哪种模式，运维层都应统一抽象为：
- `standby_provider = standby_mac | cloud_b | both`
这样修复流程、审计流程、修复复验、主控恢复回放都不需要重新设计，只替换备用提供者即可。
### 14.4 单服务器模式下的自动备用设备切换
如果采用“单服务器 + 设备端保活”，就必须支持自动切换备用设备。
#### 新增对象
- `standby_device_pool`
- `standby_device_candidate`
- `active_standby_device`
- `takeover_package`
- `standby_device_score`
#### 每台设备需要上报
- `device_id`
- `eligible_for_standby`
- `preferred_rank`
- `always_on`
- `memory_free_mb`
- `disk_free_mb`
- `lan_reachability`
- `tunnel_reachability`
- `last_heartbeat_at`
- `takeover_package_version`
#### 自动切换规则
1. 控制面维护 `standby_device_pool`
2. 为排名前 `N` 的设备同步最小 `takeover_package`
3. 如果当前 `active_standby_device` 心跳超时：
- 立即标记为 `degraded`
- 重新计算 `standby_device_score`
- 自动提升下一台候选设备
4. 新的备用设备接管后：
- 发布新的 endpoint 清单
- 更新 `ops_mode_history`
- 通知主 Agent、Worker、手机 App
#### 备用设备模式要求
- `cold standby`
- 未预部署接管组件
- 不允许进入自动切换路径
- `warm standby`
- 已预部署接管组件
- 已同步最近的 `takeover_package`
- 允许自动切换
- `hot standby`
- 已预部署接管组件
- 保持更高频状态同步
- 允许自动切换，且优先级更高
结论：
- 自动切换只允许选用 `warm standby` 或 `hot standby`
- `cold standby` 只能作为人工应急候选，不能当自动保活候选
#### `takeover_package` 最小内容
- 最近的项目 / 任务索引
- endpoint 注册表
- 修复工单索引
- 权限与审批快照
- 当前 `standby_epoch`
#### 新增事件
- `standby_device_registered`
- `standby_device_score_updated`
- `active_standby_device_changed`
- `takeover_package_synced`
- `standby_device_failed`
#### 新增数据库表
- `standby_devices`
- `standby_device_scores`
- `standby_device_packages`
- `standby_failover_history`
#### 候选设备预部署清单
每个 `warm/hot standby` 候选设备至少预部署：
- `Standby Controller`
- `Local Ops Agent`
- `Local Ops Audit Agent`
- `Ops Rescue Gateway`
- 最小运行时依赖
- 最小配置模板
- endpoint 注册表缓存
- 最近的 `takeover_package`

130
docs/architecture/repo_map_cn.md Normal file
View File

@@ -0,0 +1,130 @@
# Boss 仓库目录地图
这份文档只回答一个问题：哪些目录是当前有效的，哪些只是参考或占位。
## 1. 当前有效目录
| 路径 | 状态 | 作用 |
| --- | --- | --- |
| `src/app` | 当前有效 | Next.js 页面和 API 路由 |
| `src/components` | 当前有效 | 页面共享 UI 和交互组件 |
| `src/lib` | 当前有效 | 数据模型和聚合投影视图 |
| `local-agent` | 当前有效 | 本地设备端心跳与 thread-context 上报服务 |
| `deployment` | 当前有效 | `Caddy`、`systemd`、`launchd` 配置 |
| `scripts` | 当前有效 | 本地启动、安装、远端部署脚本 |
| `android` | 当前有效 | 原生 Android 客户端工程与 APK 构建目录 |
| `design/pencil` | 当前有效 | Pencil 原稿 |
| `design/exports/ui-codex-ops-mobile-v13` | 当前有效 | 最新导出图 |
| `docs/architecture` | 当前有效 | 当前权威中文文档 |
| `prompts` | 当前有效 | 交给其他 AI 的提示词 |
| `data/boss-state.json` | 当前有效 | 当前 MVP 的真实持久化状态文件 |
| `data/boss-state.json.bak` | 当前有效 | 状态文件解析失败时的自动恢复备份 |
| `.env.server.example` | 当前有效 | 服务器可覆盖环境变量示例 |
| `public/downloads` | 当前有效 | 当前已发布的 OTA APK 与元数据 |
| `local-agent/config.cloud.json` | 当前有效 | 本机常驻 agent 对接 `https://boss.hyzq.net` 的生产配置 |
| `local-agent/config.example.json` | 当前有效 | 本地 `127.0.0.1:3000` 回环开发配置 |
| `android/signing/release-signing.properties.example` | 当前有效 | release 签名参数模板 |
## 2. 当前参考目录
| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `docs/source-material` | 参考材料 | 历史方案、原始文档、图和外部资料备份，不是运行时真相 |
| `docs/diagrams` | 参考材料 | 架构和流程图素材 |
## 3. 当前占位或未启用目录
| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `deploy` | 空占位 | 不参与当前部署 |
| `src/boss_control` | 空占位 | 不参与当前 Web 运行 |
| `src/boss_device_agent` | 空占位 | 不参与当前 device-agent 运行 |
| `docs/deployment` | 预留 | 主要部署文档实际写在 `docs/architecture` |
| `docs/prompts` | 预留 | 当前实际提示词在 `prompts/` |
## 4. 生成目录
| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `.next` | 生成目录 | Next.js 构建产物 |
| `node_modules` | 生成目录 | 依赖安装目录 |
## 5. 当前最值得直接查看的文件
源码：
- `src/app/conversations/page.tsx`
- `src/app/conversations/[projectId]/page.tsx`
- `src/app/conversations/[projectId]/forward/page.tsx`
- `src/app/threads/[threadId]/page.tsx`
- `src/app/devices/page.tsx`
- `src/app/me/ai-accounts/page.tsx`
- `src/app/me/skills/page.tsx`
- `src/app/api/v1/accounts/route.ts`
- `src/app/api/v1/accounts/[accountId]/route.ts`
- `src/app/api/v1/accounts/[accountId]/activate/route.ts`
- `src/app/api/v1/accounts/[accountId]/validate/route.ts`
- `src/app/api/auth/session/route.ts`
- `src/app/api/auth/restore/route.ts`
- `src/app/api/auth/logout/route.ts`
- `src/app/api/v1/master-agent/tasks/claim/route.ts`
- `src/app/api/v1/master-agent/tasks/[taskId]/complete/route.ts`
- `src/app/api/v1/app-logs/route.ts`
- `src/app/api/v1/events/route.ts`
- `src/app/api/v1/user/ota/package/route.ts`
- `src/app/api/v1/devices/[deviceId]/skills/route.ts`
- `src/app/me/settings/page.tsx`
- `src/components/app-runtime.tsx`
- `src/lib/boss-app-client.ts`
- `src/app/api/device-heartbeat/route.ts`
- `src/app/api/v1/conversations/route.ts`
- `src/app/api/v1/projects/[projectId]/route.ts`
- `src/app/api/v1/workers/[workerId]/thread-context/route.ts`
- `src/lib/boss-data.ts`
- `src/lib/boss-auth.ts`
- `src/lib/boss-device-auth.ts`
- `src/lib/boss-events.ts`
- `src/lib/boss-mail.ts`
- `src/lib/boss-master-agent.ts`
- `src/lib/boss-ota.ts`
- `src/lib/boss-projections.ts`
- `local-agent/server.mjs`
部署：
- `deployment/Caddyfile`
- `deployment/mail/install-postfix-dovecot.sh`
- `deployment/mail/sync-caddy-mail-cert.sh`
- `deployment/mail/systemd/boss-mail-cert-sync.service`
- `deployment/mail/systemd/boss-mail-cert-sync.timer`
- `deployment/systemd/boss-web.service`
- `deployment/launchd/com.hyzq.boss.local-agent.plist`
- `scripts/deploy-server.sh`
- `scripts/publish-apk-to-public.sh`
- `scripts/prepare-android-signing.sh`
- `scripts/build-release-apk.sh`
- `scripts/install-server-mail.sh`
- `scripts/bootstrap-server.sh`
- `android/app/src/main/java/com/hyzq/boss/MainActivity.java`
- `android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
- `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
- `android/app/src/main/java/com/hyzq/boss/DeviceDetailActivity.java`
- `android/app/src/main/java/com/hyzq/boss/AiAccountsActivity.java`
- `android/app/src/main/java/com/hyzq/boss/OpsCenterActivity.java`
- `android/app/build/outputs/apk/debug/app-debug.apk`
文档：
- `README.md`
- `docs/architecture/ai_handoff_index_cn.md`
- `docs/architecture/current_runtime_and_deploy_status_cn.md`
- `docs/architecture/api_and_service_inventory_cn.md`
## 6. 目录判断原则
如果你需要继续开发：
- 以 `src/app`、`src/lib`、`local-agent`、`deployment` 为主线
- 以 `docs/architecture` 为权威描述
- 以 `docs/source-material` 为补充参考
- 不要把空占位目录误认成另一套现成实现

398
docs/architecture/thread_context_budget_and_handoff_protocol_cn.md Normal file
View File

@@ -0,0 +1,398 @@
# 线程上下文预算与压缩前接力协议
这份文档把“背景信息窗口余量”正式冻结成开发规格，覆盖：
- 设备端如何上报线程上下文预算
- 手机端 / Web BFF 如何返回会话列表里的圆环进度标记
- 主 Agent 如何基于上下文预算做压缩前收尾、线程轮换和摘要接力
- 哪些字段是系统真相，哪些字段只是展示层映射
适用范围：
- 单主 Agent
- 多台 Mac / Windows / Cloud Worker
- 微信式会话列表首页
- 项目聊天页 / 线程详情页
- `API-first / local-first` 极限轻云模式
---
## 1. 核心原则
1. 首页圆环标记显示的是“线程上下文预算”，不是账号 5h / 7d 使用额度。
2. 线程上下文预算必须由设备端 worker 统一上报，前端不能自行推算。
3. 主 Agent 必须在发生背景信息压缩前完成关键收尾，而不是在压缩后补救。
4. 线程上下文预算是主 Agent 的一等调度信号，优先级高于普通列表排序提示。
5. 群聊型项目会话默认不在首页显示线程上下文预算，但项目详情页仍然可以展开查看各线程预算。
---
## 2. 术语定义
### 2.1 线程上下文预算
指当前线程在发生背景信息压缩、上下文裁剪或显著细节丢失之前，还剩多少安全上下文空间。
### 2.2 背景信息压缩
指 Codex / worker 为继续运行而触发的上下文压缩、阶段性摘要替换、历史裁剪或其他会导致细节损失的机制。
### 2.3 压缩前收尾
指主 Agent 在预算即将耗尽前，主动要求线程完成的固化动作，包括：
- patch 固化
- 命令和日志固化
- 测试结果固化
- 关键决策固化
- 未决问题固化
- 证据引用固化
- handoff 摘要生成
### 2.4 摘要接力
指当前线程在压缩或结束前，把下一条线程继续工作所需的最小必要信息打包并交给主 Agent 或下一线程。
---
## 3. 设备端真相模型
### 3.1 新增数据对象
- `thread_context_snapshots`
- `thread_context_threshold_policies`
- `thread_handoff_packages`
- `thread_context_alerts`
### 3.2 `thread_context_snapshots`
最小字段：
- `snapshot_id`
- `project_id`
- `task_id`
- `thread_id`
- `node_id`
- `worker_id`
- `source_kind`
- `codex_app_server`
- `codex_sdk`
- `worker_estimator`
- `context_budget_remaining_pct`
- `context_budget_level`
- `safe`
- `watch`
- `urgent`
- `critical`
- `compaction_expected_at`
- `must_finish_before_compaction`
- `estimated_remaining_turns`
- `estimated_remaining_large_messages`
- `last_compaction_at`
- `compaction_count`
- `snapshot_version`
- `captured_at`
### 3.3 `thread_handoff_packages`
最小字段：
- `handoff_package_id`
- `project_id`
- `task_id`
- `from_thread_id`
- `to_thread_id`
- `package_status`
- `draft`
- `ready`
- `consumed`
- `expired`
- `summary_text`
- `open_questions`
- `critical_files`
- `critical_commands`
- `critical_tests`
- `critical_artifacts`
- `decision_links`
- `created_at`
- `ready_at`
- `consumed_at`
### 3.4 `thread_context_alerts`
最小字段：
- `alert_id`
- `thread_id`
- `project_id`
- `alert_type`
- `context_watch`
- `context_urgent`
- `context_critical`
- `compaction_risk`
- `handoff_missing`
- `alert_status`
- `opened`
- `acked`
- `resolved`
- `opened_at`
- `resolved_at`
---
## 4. 统一阈值策略
默认阈值：
- `safe`: `>= 60%`
- `watch`: `40% ~ 59%`
- `urgent`: `25% ~ 39%`
- `critical`: `< 25%`
### 4.1 对应动作
| 等级 | 说明 | 主 Agent 动作 |
| --- | --- | --- |
| `safe` | 线程仍可稳定推进 | 继续执行，但要求持续刷新阶段摘要 |
| `watch` | 预算开始收紧 | 不再追加大块背景信息，开始准备 handoff |
| `urgent` | 接近压缩边缘 | 优先完成当前原子子任务，预创建接力线程 |
| `critical` | 随时可能发生压缩 | 立即执行压缩前收尾，禁止继续扩张上下文 |
### 4.2 `must_finish_before_compaction`
该字段由主 Agent 或 worker 规则引擎在以下条件置为 `true`：
- 当前线程有未提交 patch
- 当前线程有未整理测试结论
- 当前线程有未写入项目记忆的关键决策
- 当前线程正在执行一次不可中断的硬件步骤
- 当前线程正在等待跨节点线程回复，但已有结论必须先固化
---
## 5. Worker 上报协议
### 5.1 上报频率
- 线程状态发生显著变化时立即上报
- 普通运行中每 `30s` 上报一次
- `watch` 级别每 `15s` 上报一次
- `urgent / critical` 级别每 `5s` 上报一次
### 5.2 API
`POST /api/v1/workers/{worker_id}/thread-context`
请求体：
```json
{
"node_id": "mac-01",
"worker_id": "worker-mac-01",
"thread_id": "thread-abc",
"project_id": "proj-001",
"task_id": "task-017",
"source_kind": "worker_estimator",
"context_budget_remaining_pct": 37,
"context_budget_level": "urgent",
"compaction_expected_at": "2026-03-25T16:08:30+08:00",
"must_finish_before_compaction": true,
"estimated_remaining_turns": 5,
"estimated_remaining_large_messages": 2,
"last_compaction_at": "2026-03-25T15:12:10+08:00",
"compaction_count": 1,
"captured_at": "2026-03-25T15:56:00+08:00"
}
```
返回体：
```json
{
"accepted": true,
"thread_id": "thread-abc",
"context_budget_level": "urgent",
"next_required_report_in_seconds": 5,
"master_actions": [
"prepare_handoff",
"avoid_large_context_append"
]
}
```
### 5.3 事件
每次有效更新都必须写事件流：
- `thread.context.updated`
- `thread.context.level_changed`
- `thread.context.compaction_risk_opened`
- `thread.context.compaction_risk_resolved`
---
## 6. 手机端 / Web BFF 协议
### 6.1 会话列表接口
`GET /api/v1/conversations`
项目会话项新增字段：
- `context_budget_indicator`
- `visible`
- `style`
- `percent`
- `level`
- `context_budget_source_node_id`
- `context_budget_updated_at`
- `must_finish_before_compaction`
示例：
```json
{
"conversation_id": "conv-proj-001",
"conversation_type": "single_device",
"project_title": "北区试产线回归",
"manual_pinned": true,
"latest_reply_at": "2026-03-25T09:26:00+08:00",
"context_budget_indicator": {
"visible": true,
"style": "ring_percent",
"percent": 52,
"level": "watch"
},
"must_finish_before_compaction": false
}
```
### 6.2 项目详情接口
`GET /api/v1/projects/{project_id}`
新增：
- `active_thread_contexts`
- `next_compaction_risk_thread_id`
- `threads_requiring_handoff`
- `master_context_strategy_summary`
### 6.3 线程详情接口
`GET /api/v1/threads/{thread_id}/context-budget`
返回：
- 当前百分比
- 当前等级
- 预计压缩时间
- 最近压缩时间
- 当前收尾清单
- handoff 包状态
### 6.4 SSE 事件
- `conversation.context_indicator.updated`
- `project.context_risk.updated`
- `thread.handoff.required`
- `thread.handoff.ready`
---
## 7. 首页 UI 映射规则
### 7.1 单设备项目会话
右侧第三层显示：
- 小圆环进度标记
- 百分比
样式要求：
- 必须与设备端线程页和项目详情页保持一致
- 默认使用中性灰环
- 低预算时通过主 Agent 摘要和项目详情强化提醒，不在首页堆叠过多告警文案
### 7.2 群聊型项目会话
默认不显示第三层圆环。
原因：
- 多线程、多设备协作项目不能把多个线程预算压成一个误导性的单值
- 这类项目应在项目详情页查看各线程预算
### 7.3 主 Agent 会话
可以显示单一圆环预算，但含义是：
- 主 Agent 当前主线程的工作预算
- 不是整个系统剩余额度总量
---
## 8. 主 Agent 调度逻辑
### 8.1 预算优先级排序
主 Agent 在每轮调度时，必须把以下因子一起排序：
- `context_budget_level`
- `must_finish_before_compaction`
- `compaction_expected_at`
- 任务重要性
- 是否持有未固化 patch
- 是否持有未固化测试结果
- 是否持有未固化硬件证据
### 8.2 默认调度策略
1. 若线程进入 `critical`，优先处理该线程的收尾和交接。
2. 若多个线程同时 `critical`，优先处理：
- 有未固化 patch 的
- 有未固化测试结果的
- 有硬件测试正在进行的
3. `watch` 和 `urgent` 阶段，主 Agent 应减少向该线程追加长背景信息。
4. 新子任务应优先派给预算更健康的新线程或其他空闲线程。
### 8.3 压缩前收尾清单
主 Agent 触发 `prepare_handoff` 时，worker 必须尽量补齐：
- 当前修改涉及的文件清单
- 已完成和未完成的 patch
- 最近一次关键命令及其结果
- 最近一次测试结论
- 未决问题
- 下一线程建议动作
- 必需证据链接
---
## 9. 验收标准
满足以下条件，视为这块设计可直接进入开发：
1. 设备端能统一上报线程上下文预算。
2. BFF 能返回首页圆环所需全部字段。
3. 项目详情页能展开查看多线程预算。
4. 主 Agent 能在 `watch / urgent / critical` 三个边界做出不同动作。
5. 发生 compaction 前，系统能自动触发至少一次压缩前收尾和 handoff 准备。
6. 首页显示、项目详情显示、设备端线程显示三处的预算语义一致。
---
## 10. 与现有文档关系
这份文档是以下文档的补充细化：
- `/Users/kris/code/Talking/codex_multi_machine_architecture_cn.html`
- `/Users/kris/code/Talking/wechat_project_conversation_mapping_cn.md`
- `/Users/kris/code/Talking/development_subtasks_and_delivery_plan_cn.md`
它的定位是：
- 专门冻结“线程上下文预算”和“压缩前接力”这条主线
- 供后端、设备端、主 Agent、前端同时作为实现依据

853
docs/architecture/wechat_project_conversation_mapping_cn.md Normal file
View File

@@ -0,0 +1,853 @@
# 微信式项目会话与聊天页规格
这份文档用于冻结“第一屏 = 微信式会话列表”的产品逻辑，避免后续开发时又回到“移动控制台首页”的方向。
视觉对标：
- 微信 iPhone 版会话列表页的核心结构
- 官方来源：[微信 App Store 页面](https://apps.apple.com/cn/app/id414478124)
适用范围：
- 手机 App 第一屏
- 设备页（对应微信通讯录位置）
- 我的页（对应微信“我”）
- 项目聊天页
- 主 Agent 置顶会话
- 项目会话列表
- 设备头像 / 协作群聊头像
- 手动置顶
- 项目目标
- 版本迭代记录
- 图片 / 视频 / 语音输入
- 消息转发
---
## 1. 首页定位
首页不是“主 Agent 聊天正文页”。
首页应该是：
- 一个微信式的会话列表页
- 列表中的每一条会话都代表一个“项目对话”
- 列表顶部固定一条 `主 Agent` 会话
- 用户点击任意一条会话，再进入该项目的具体对话页
一句话定义：
`第一屏 = 主 Agent 总会话 + 各项目会话列表`
底部导航要求：
- 第一项：`会话`
- 第二项：`设备`
- 第三项：`我的`
- 呈现方式：微信式扁平底栏，`图标在上 / 文案在下 / 激活项使用微信绿`
其中第二项 `设备` 对应微信中的“通讯录”位置。
第三项 `我的` 对应微信中的“我”。
项目入口不再占据底部一级导航，而是从 `会话` 首页进入。
---
## 2. 项目会话与设备项目文件夹的映射规则
每一个项目会话必须和设备端 GUI 界面里的项目文件夹一一对应。
映射规则如下：
1. 每台接入设备启动 `worker-daemon` 后，扫描并注册本机可见项目根目录。
2. 每个项目目录生成稳定的 `project_folder_key`。
3. 云端控制面把同名或同一仓库来源的文件夹，映射到同一个 `project_id`。
4. 主 Agent 不直接生成“虚拟项目名”，而是基于 `project_id` 做汇总。
5. 首页列表展示的项目会话标题，优先使用：
- 项目显式别名
- 仓库名 / 文件夹名
- 最后回退到 `project_id`
必须满足：
- 一个项目会话能追溯到具体设备上的具体文件夹
- 进入项目详情时，能看到这个项目当前挂在哪些设备上
---
## 3. 会话列表项类型
首页列表至少包含 3 类会话项：
### 3.1 主 Agent 会话
规则：
- 永远固定在最上面
- 永远视为置顶
- 不允许取消置顶
- 头像使用独立主 Agent 头像
- 最新摘要由主 Agent 汇总生成
展示字段：
- 标题：`主 Agent`
- 摘要：项目汇总、风险提醒、待确认事项
- 时间：主 Agent 最后一次完成汇总的时间
- 标签：`置顶`
### 3.2 单设备项目会话
规则：
- 一个项目当前只由一台设备执行
- 列表头像使用该设备独立头像
- 摘要使用该设备最近一次返回给主控的有效摘要
展示字段：
- 标题：项目名
- 摘要：`设备名 + 最新一句摘要`
- 右侧第一行：若已置顶则显示 `置顶`，未置顶留白
- 右侧第二行：该设备对这个项目的最后回传时间
- 右侧第三行：背景信息窗口余量指示器（圆环进度标记 + 百分比）
### 3.3 多设备协作项目会话
规则：
- 一个项目已经进入多设备协作
- 列表头像使用“组合头像”
- 逻辑上等价于微信中的群聊
展示字段：
- 标题：项目名
- 摘要：`设备A + 设备B + 最新一句协作摘要`
- 右侧第一行：留白，除非用户手动置顶
- 右侧第二行：参与设备中最后一次回传时间的最大值
- 右侧第三行：不显示剩余使用量
---
## 4. 头像规则
### 4.1 单设备头像
每台设备必须有自己独立头像。
建议最小字段：
- `device_id`
- `device_name`
- `device_type`
- `avatar_mode`
- `avatar_color`
- `avatar_label`
- `avatar_asset_url`
优先级：
1. 设备自定义头像
2. 系统生成头像
3. 文本缩写头像
建议默认缩写：
- `Mac Studio` -> `M`
- `Windows GPU` -> `W`
- `Cloud Worker` -> `C`
### 4.2 群聊式组合头像
当项目由多台设备协作时：
- 使用组合头像
- MVP 阶段支持 2 设备叠放头像
- 后续可扩展到 3~4 设备拼接头像
组合规则：
- 2 设备：左右叠放
- 3 设备：主头像 + 右上 / 右下
- 超过 3 台时：显示 2~3 个头像 + `+N`
排序规则：
- 优先主执行设备
- 再按最近活跃度排序
---
## 5. 列表排序规则
首页排序不能只是项目创建时间排序。
排序必须按以下优先级：
1. `主 Agent` 会话，永远第一
2. 用户手动置顶的项目会话
3. 未置顶项目，按 `latest_reply_at DESC`
其中：
- `latest_reply_at` = 该项目参与设备最后一次有效回传时间的最大值
- “有效回传”包括：
- 线程摘要
- 审计结论
- 运维修复结果
- 关键错误 / 告警事件
不应计入：
- 心跳包
- 纯监控噪声日志
- 无内容变化的重复状态刷新
---
## 6. 手动置顶规则
首页必须支持长按会话条置顶。
交互规则：
- 长按普通项目会话 -> 弹出操作菜单
- 菜单包含：
- `置顶`
- `取消置顶`
- `标记已读`
- `查看项目详情`
排序规则：
- 主 Agent 永远第一
- 用户置顶项目在主 Agent 之后
- 多个置顶项目按最近消息时间排序
注意：
- 主 Agent 不允许取消置顶
- 系统需要记录 `manual_pinned = true/false`
---
## 7. 首页列表项最小展示字段
每一条项目会话至少要有：
- `conversation_id`
- `conversation_type`
- `project_id`
- `project_title`
- `avatar_render_model`
- `latest_summary`
- `latest_reply_at`
- `manual_pinned`
- `context_budget_remaining_pct`
- `context_budget_indicator_style`
- `context_budget_level`
- `compaction_expected_at`
- `unread_count`
- `risk_level`
- `active_device_count`
可选增强字段：
- `device_names_preview`
- `audit_pending_count`
- `ops_alert_count`
- `compaction_risk`
- `must_finish_before_compaction`
---
## 8. 建议新增的数据对象
在现有 `projects / threads / thread_events` 之上，建议增加：
- `project_conversations`
- `project_conversation_items`
- `project_conversation_participants`
- `device_avatars`
- `conversation_pin_state`
### 8.1 `project_conversations`
核心字段：
- `conversation_id`
- `project_id`
- `conversation_type` (`master` / `single_device` / `multi_device`)
- `title`
- `latest_summary`
- `latest_reply_at`
- `manual_pinned`
- `sort_bucket`
### 8.2 `project_conversation_participants`
核心字段：
- `conversation_id`
- `device_id`
- `role`
- `is_primary`
- `last_reply_at`
### 8.3 `conversation_pin_state`
核心字段：
- `conversation_id`
- `pin_type` (`system` / `manual`)
- `pinned_by`
- `pinned_at`
---
## 9. 首页 UI 结构
建议结构：
1. 状态栏
2. 页面标题：`会话`
3. 搜索 / 说明条
4. 会话列表
5. 底部导航
会话列表项布局：
- 左侧：头像
- 中间：标题 + 最近摘要
- 右侧：三层信息轨
右侧三层信息轨规则：
- 第一层：`置顶` 标签；若未置顶则保留空白高度
- 第二层：最后一次有效会话时间
- 第三层：背景信息窗口余量指示器
- 群聊型项目会话不展示第三层额度信息
背景信息窗口余量指示器规则：
- 使用统一的小圆环进度标记 + 百分比数字
- 样式和设备端线程页保持一致，不允许手机端自行推导一套不同视觉
- 数据来源于设备端 `worker-daemon` 上报的线程上下文预算，而不是前端本地估算
- 指示器表达的是“当前线程在发生背景信息压缩前，还剩多少可安全使用空间”
- 该值越低，越需要主 Agent 在压缩前完成关键收尾、证据固化和线程交接
视觉要求：
- 更接近微信会话列表
- 不要做成项目管理后台
- 不要把大量设备、审计字段直接塞进首页列表
- 首页只保留最适合“扫一眼决定先点谁”的信息
- 对单设备项目允许展示轻量额度信息，但群聊型项目不显示额度
- 首页中的圆环指示器展示的是“线程上下文预算”，不是账号 5h / 7d 额度，两者不能混用
---
## 10.1 主 Agent 的上下文预算协作逻辑
这部分是整个系统里多线程协作的核心调度信号。
主 Agent 必须持续读取每个线程的：
- `context_budget_remaining_pct`
- `context_budget_level`
- `compaction_expected_at`
- `must_finish_before_compaction`
主 Agent 的默认策略：
- `safe`：`>= 60%`
- 允许继续正常推进任务
- `watch`：`40% ~ 59%`
- 不再给该线程追加大块背景信息
- 要求该线程开始产出阶段摘要
- `urgent`：`25% ~ 39%`
- 主 Agent 应优先让该线程完成当前原子子任务
- 同时预创建下一条接力线程和 handoff 摘要
- `critical`：`< 25%`
- 禁止继续扩张上下文
- 主 Agent 必须优先触发“压缩前收尾”
- 包括：补齐关键结论、未提交 patch、命令记录、测试结论、证据引用、未决问题
压缩前收尾的优先顺序：
1. 当前正在修改但尚未固化的代码和补丁
2. 解释问题所必需的命令、日志、文件路径和测试结果
3. 与下一线程交接有关的关键决策和未决问题
4. 硬件测试 / 多模态审计所需的证据引用
设计原则：
- 不要等发生 compaction 之后再补救
- 主 Agent 必须尽量在 compaction 之前完成关键任务或完成线程交接
- 首页会话列表里的圆环标记，必须能帮助用户和主 Agent 同时感知哪些项目最接近上下文风险边缘
---
## 10. 和整体系统设计的关系
这套首页设计不会改变整体架构，只改变第一屏的信息组织方式。
对应关系如下：
- `projects` 提供项目真相
- `threads` 提供线程真相
- `thread_events` 提供最近事件
- `worker_account_bindings` / `gptpluscontrol` 提供设备与账号状态
- `project_conversations` 负责把这些底层状态重组为“会话列表”
所以：
- 底层仍是多机多线程系统
- 首页表现层收敛成微信式会话列表
- 主 Agent 仍然是总入口
- 项目会话只是“主 Agent 汇总后暴露出来的二级会话壳”
---
## 11. 项目聊天页结构
点击首页任意项目会话后，进入“微信式聊天页”。
聊天页结构固定为：
1. 状态栏
2. 聊天页头部
3. 顶部能力入口
4. 消息流
5. 媒体 / 转发入口
6. 语音 / 文本输入区
页面要求：
- 尽量接近微信聊天详情页的层级和节奏
- 不显示底部 tab bar
- 重点是聊天，而不是后台字段
---
## 12. 顶部两个固定按钮
项目名称下面必须增加两个并列按钮。
布局要求：
- 同一行
- 横向总宽度 100%
- 两个按钮各占一半宽度
按钮定义：
- `项目目标`
- `版本迭代记录`
---
## 13. 项目目标规则
`项目目标` 的生成和维护规则：
- 初始目标由用户和主 Agent 沟通后创建
- 主 Agent 负责整理成结构化目标
- 用户允许手动编辑
- UI 以“圆形单选式完成标记”展示每一条目标
- 用户或主 Agent 将目标标记完成后，目标正文自动加删除线
- 主 Agent 根据项目目标做任务拆解、督促和规划
- 各线程都要以项目目标为约束执行开发和测试
建议数据对象：
- `project_goals`
- `project_goal_revisions`
- `project_goal_items`
- `project_goal_completion_logs`
核心字段：
- `project_id`
- `goal_title`
- `goal_body`
- `goal_order`
- `display_style` (`radio_checklist`)
- `completion_state` (`pending` / `completed`)
- `completed_by`
- `completed_at`
- `source` (`human` / `master_agent`)
- `is_active`
- `edited_by`
- `edited_at`
权限规则：
- 用户可编辑
- 用户可标记目标已完成
- 主 Agent 可整理和建议修改
- 主 Agent 可复核目标完成状态并修正排序
- 普通 worker 线程不能直接改项目目标
### 13.1 项目目标页交互
项目目标页必须明确体现以下交互：
- 每条目标左侧使用圆形单选式完成标记
- 标记完成后，当前目标正文自动加删除线
- 已完成目标显示 `已完成` 状态和完成时间
- 未完成目标显示 `进行中` 或 `待处理`
- 顶部仍保留 `编辑目标` 入口
- `编辑目标` 只允许用户和主 Agent 修改目标内容
- 普通 worker 线程只能读取，不可直接改写
---
## 14. 版本迭代记录规则
`版本迭代记录` 的生成和维护规则：
- 由主 Agent 监督各项目进程
- 定期自动汇报每一个版本号更新的内容
- 主 Agent 负责校验各线程提交上来的版本更新记录是否准确
- 版本迭代记录是只读记录
- 用户不能直接编辑版本记录正文
建议数据对象：
- `version_iteration_reports`
- `version_iteration_sources`
- `version_iteration_reviews`
核心字段：
- `project_id`
- `version_name`
- `change_summary`
- `source_thread_ids`
- `generated_by`
- `verified_by_master`
- `published_at`
权限规则：
- 主 Agent 可生成 / 复核 / 发布
- 用户可查看
- 用户不可直接改正文
- worker 线程只能提交候选更新，不可直接发布
---
## 15. 聊天能力范围
项目聊天页必须支持：
- 文本输入
- 语音输入
- 图片发送
- 视频发送
- 图片 / 视频 / 文本转发到其他聊天窗口
建议最小对象：
- `conversation_messages`
- `message_attachments`
- `message_forwards`
其中：
- `message_attachments` 支持 `image / video / file / voice`
- `message_forwards` 必须记录：
- `source_conversation_id`
- `target_conversation_id`
- `message_id`
- `forwarded_by`
- `forwarded_at`
---
## 16. 设备页规格
设备页对应底部第二个导航项，位置等价于微信的“通讯录”。
功能目标：
- 展示当前已接入设备
- 展示各设备登录账号
- 展示各设备当前运行项目
- 展示各设备剩余额度
- 支持新增设备
- 支持设备管理
### 16.1 页面结构
设备页结构固定为：
1. 状态栏
2. 页面标题：`设备`
3. 右上角 `+ 添加`
4. 长按操作提示
5. 设备列表
6. 底部导航
### 16.2 列表项最小字段
每一台设备至少展示：
- `device_name`
- `device_avatar`
- `account_display_name`
- `running_projects_summary`
- `quota_5h_remaining`
- `quota_7d_remaining`
- `device_status`
### 16.3 设备状态颜色
状态必须显式展示为圆点或小标记：
- 绿色：设备在线
- 红色：设备异常
- 灰色：设备掉线
建议枚举：
- `online`
- `abnormal`
- `offline`
### 16.4 新增设备
交互要求：
- 右上角点击 `+ 添加`
- 打开新增设备流程
- 可进入：
- 新设备绑定
- 登录引导
- token / pairing code 绑定
### 16.5 长按设备
长按任意设备条目，弹出操作菜单：
- `编辑设备名称`
- `编辑设备头像`
- `解绑设备`
### 16.6 建议新增数据对象
建议增加：
- `device_profiles`
- `device_status_snapshots`
- `device_project_bindings`
核心字段建议：
- `device_id`
- `device_name`
- `device_avatar_url`
- `device_type`
- `status`
- `account_id`
- `quota_5h_remaining`
- `quota_7d_remaining`
- `last_seen_at`
---
## 17. 我的页规格
我的页对应底部第三个导航项，位置等价于微信的“我”。
功能目标：
- 展示用户头像
- 展示账号名称
- 展示账号唯一二维码入口
- 展示账号与安全
- 展示设置
- 展示 `运维与修复` 入口
- 展示关于 / 版本号 / OTA 更新
### 17.1 页面结构
我的页结构固定为：
1. 状态栏
2. 用户信息头部
3. 功能列表
4. `关于` 及 OTA 红点
5. OTA 更新内容区
6. 底部导航
### 17.2 头部信息
头部至少展示：
- 用户头像
- 用户昵称 / 显示名
- 当前账号类型
- 右侧 `唯一二维码` 入口
二维码入口呈现规则：
- 放在头部信息卡的最右侧
- 以微信式小二维码图标呈现
- 与头像、昵称、账号类型处于同一个头部单元中
- 不再单独占一行文字说明
### 17.3 账号与安全
账号与安全页项的职责：
- 修改账号密码
- 设备安全管理
- 身份校验
MVP 要求：
- 当前先只冻结入口和字段
- 后续二级页再开发
### 17.4 设置
设置在当前版本只保留一级入口。
规则：
- 先展示
- 暂不开发二级页
### 17.5 关于与 OTA
关于项必须展示：
- 当前版本号
- 若有新 OTA，右侧显示红色 `OTA` 提示
点击后行为：
- 展示 OTA 更新内容
- 可触发 `立即 OTA`
### 17.6 OTA 更新内容区
更新内容区必须包含：
- 目标版本号
- 更新点摘要
- `立即 OTA` 按钮
建议新增数据对象：
- `user_profiles`
- `app_versions`
- `ota_updates`
- `ota_update_logs`
建议字段：
- `current_version`
- `target_ota_version`
- `has_ota_update`
- `ota_update_summary`
- `ota_update_status`
- `ota_triggered_at`
### 17.7 账号认证页
移动端必须补齐 3 个账号认证页面：
- `登录页`
- `注册页`
- `忘记密码页`
认证页规则：
- `登录页` 必须支持账号、密码、登录验证码
- `注册页` 必须支持账号、登录验证码、密码、确认密码
- `忘记密码页` 必须支持账号、登录验证码、新密码、确认新密码
- 3 个页面都要提供 `发送验证码`
- 登录验证码和找回验证码都必须进入后端校验链路
- 登录成功后才允许继续设备绑定与项目同步
- 重置密码成功后，旧设备登录态允许被系统要求重新校验
---
## 18. 已冻结的二级页面
为了避免开发时只做一级页壳子，下面这些二级页也已经纳入 UI 范围：
- `项目目标页`
- `版本迭代记录页`
- `转发到项目页`
- `添加设备页`
- `设备长按操作菜单`
- `账号与安全页`
- `关于 / OTA 页`
- `登录页`
- `注册页`
- `忘记密码页`
这些页面的目标是：
- 保持微信式的导航和扁平视觉
- 不把复杂系统状态直接做成后台面板
- 每个子页面都能对应明确的数据对象和入口来源
- 其中 `运维与修复` 必须作为 `我的` 页里的二级入口，不再作为底部一级导航
- `运维与修复` 内部再分为 `运维对话` 和 `审计对话` 两个子页
---
## 18. UI 上不直接暴露的后台逻辑
虽然聊天页外观接近微信，但底层仍然是多线程系统。
所以：
- 首页看到的是项目会话
- 聊天页看到的是主 Agent 汇总后的项目聊天流
- 底层真实 worker 线程、审计线程、运维线程仍继续工作
- 主 Agent 把底层线程状态整理成适合聊天页展示的消息
换句话说：
`UI 上是聊天，系统里仍然是多线程编排`
---
## 19. 当前 UI 原型对应
当前原型已按这套规则重绘整套核心页面：
- 主 Agent 置顶
- 单设备头像
- 双设备协作头像
- 手动置顶示例
- 会话按最近消息排序
- 项目聊天页双按钮
- 项目目标页圆形完成标记 + 自动划线
- 版本迭代记录只读展示
- 图片 / 视频 / 转发入口
- 语音输入入口
- 设备页第二导航位
- 设备在线 / 异常 / 掉线三种状态
- 右上角添加设备
- 长按设备管理提示
- 我的页第三导航位
- 账号与安全入口
- 设置入口
- 关于 + OTA 红点
- OTA 更新内容卡片
- 登录页 / 注册页 / 忘记密码页
- 登录验证码发送入口
对应文件：
- `/Users/kris/code/UI/.runtime/pencil/threads/ui-codex-ops-mobile/outputs/codex-ops-mobile-v1.pen`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/d5gpt.png`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/g8Qpr.png`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/CwqbE.png`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/i7IZ1.png`

137
docs/diagrams/business_flow_mindmap_cn.svg Normal file
View File

@@ -0,0 +1,137 @@
<svg width="2000" height="1320" viewBox="0 0 2000 1320" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="140" y1="60" x2="1860" y2="1260" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF5FF"/>
</linearGradient>
<linearGradient id="centerFill" x1="790" y1="472" x2="1210" y2="848" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F62FE"/>
<stop offset="1" stop-color="#4D91FF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="2000" height="1320" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="18" stdDeviation="20" flood-color="#17212F" flood-opacity="0.12"/>
</filter>
<style>
.title { font: 700 36px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #162235; }
.subtitle { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4C6075; }
.section-title { font: 700 25px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #14253B; }
.section-text { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #43566B; }
.section-text-small { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #54687E; }
.badge { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; }
.center-title { font: 700 34px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: white; }
.center-text { font: 500 17px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: rgba(255,255,255,0.92); }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #61758D; }
</style>
</defs>
<rect width="2000" height="1320" rx="36" fill="url(#bg)"/>
<text x="92" y="92" class="title">Codex 多机协作业务流程思维导图</text>
<text x="92" y="126" class="subtitle">只讲业务推进链路，不讲底层服务拆分。适合拿来讨论产品体验、协作方式、项目推进和异常处置。</text>
<g filter="url(#shadow)">
<rect x="780" y="470" width="440" height="380" rx="38" fill="url(#centerFill)"/>
</g>
<rect x="832" y="512" width="336" height="38" rx="19" fill="rgba(255,255,255,0.18)"/>
<text x="927" y="537" class="badge" style="fill:#FFFFFF">业务流程中心</text>
<text x="884" y="615" class="center-title">一个主 Agent</text>
<text x="850" y="662" class="center-title">贯穿整个项目周期</text>
<text x="848" y="716" class="center-text">你始终只对一个主会话说话</text>
<text x="842" y="748" class="center-text">它负责理解需求、拆任务、派机器、盯进度、收结果</text>
<text x="870" y="780" class="center-text">并在异常时切换账号、节点或执行策略</text>
<path d="M782 572C672 532 541 487 408 407" stroke="#3B82F6" stroke-width="7" stroke-linecap="round"/>
<path d="M780 656C642 653 531 673 410 738" stroke="#22C55E" stroke-width="7" stroke-linecap="round"/>
<path d="M1000 470C1002 368 1004 272 1004 180" stroke="#F59E0B" stroke-width="7" stroke-linecap="round"/>
<path d="M1220 572C1342 529 1452 488 1590 410" stroke="#A855F7" stroke-width="7" stroke-linecap="round"/>
<path d="M1220 666C1354 672 1465 700 1592 778" stroke="#EF4444" stroke-width="7" stroke-linecap="round"/>
<path d="M1000 850C1000 949 1000 1032 1000 1126" stroke="#0EA5E9" stroke-width="7" stroke-linecap="round"/>
<g filter="url(#shadow)">
<rect x="80" y="232" width="494" height="308" rx="30" fill="#FFFFFF"/>
<rect x="76" y="236" width="10" height="300" rx="5" fill="#3B82F6"/>
</g>
<rect x="122" y="266" width="164" height="34" rx="17" fill="#E8F1FF"/>
<text x="162" y="289" class="badge" style="fill:#0F62FE">需求进入</text>
<text x="122" y="346" class="section-title">1. 你在手机里发起一个项目</text>
<text x="122" y="394" class="section-text">• 你描述目标、优先级、设备条件、交付标准，始终只对一个主 Agent 说话</text>
<text x="122" y="430" class="section-text">• 主 Agent 先把需求转成项目卡：目标、边界、风险、里程碑、待确认项</text>
<text x="122" y="466" class="section-text">• 如果项目涉及硬件、摄像头、机器人、串口，也在这里声明测试需求</text>
<text x="122" y="502" class="section-text">• App 里马上生成项目视图，而不是只留下一串长聊天记录</text>
<text x="122" y="532" class="section-text-small">技术：Mobile App / Web、Control API、Project View、WebSocket</text>
<g filter="url(#shadow)">
<rect x="84" y="624" width="522" height="330" rx="30" fill="#FFFFFF"/>
<rect x="80" y="628" width="10" height="322" rx="5" fill="#22C55E"/>
</g>
<rect x="126" y="658" width="174" height="34" rx="17" fill="#EAF9EE"/>
<text x="165" y="681" class="badge" style="fill:#14803D">规划与分派</text>
<text x="126" y="740" class="section-title">2. 主 Agent 拆任务并分配节点</text>
<text x="126" y="788" class="section-text">• 按功能、平台、算力、风险把项目拆成多个短任务，而不是一条线程写到底</text>
<text x="126" y="824" class="section-text">• Mac 负责前端、Xcode、本地联调；Windows 负责 GPU、硬件桥接；云端负责 CI 和长任务</text>
<text x="126" y="860" class="section-text">• 同时选择主账号、备用账号或 API 容灾路径，避免主流程因单账号额度耗尽而停摆</text>
<text x="126" y="896" class="section-text">• 每个任务都落在独立 worker thread、独立 branch / worktree 中</text>
<text x="126" y="928" class="section-text-small">技术：LangGraph、Scheduler、Project Memory、Git worktree、Thread Registry</text>
<g filter="url(#shadow)">
<rect x="728" y="78" width="554" height="296" rx="30" fill="#FFFFFF"/>
<rect x="724" y="82" width="10" height="288" rx="5" fill="#F59E0B"/>
</g>
<rect x="772" y="112" width="180" height="34" rx="17" fill="#FFF3DD"/>
<text x="812" y="135" class="badge" style="fill:#A16207">执行推进</text>
<text x="772" y="190" class="section-title">3. 多台 Codex 并行开发与协作</text>
<text x="772" y="238" class="section-text">• 各机器上的 Codex 线程按自己的短上下文工作，减少长上下文退化</text>
<text x="772" y="274" class="section-text">• 线程可以在主控监管下跨节点对话，例如 Mac 线程请求 Windows 做 GPU 或硬件验证</text>
<text x="772" y="310" class="section-text">• 所有聊天、命令、补丁、失败和审批都被实时镜像回主项目页面</text>
<text x="772" y="346" class="section-text">• 你点开任意任务就能看见该线程的完整进度，不需要自己切电脑</text>
<text x="772" y="376" class="section-text-small">技术：Codex app-server / SDK、Worker Daemon、Inter-Thread Broker、Event Store</text>
<g filter="url(#shadow)">
<rect x="1448" y="230" width="468" height="316" rx="30" fill="#FFFFFF"/>
<rect x="1912" y="234" width="10" height="308" rx="5" fill="#A855F7"/>
</g>
<rect x="1490" y="264" width="188" height="34" rx="17" fill="#F4E8FF"/>
<text x="1534" y="287" class="badge" style="fill:#7E22CE">审计与验证</text>
<text x="1490" y="344" class="section-title">4. 审计层复核“做完了没，做对了没”</text>
<text x="1490" y="392" class="section-text">• 规则审计先发现超时、失败、断流、额度异常、重复压缩</text>
<text x="1490" y="428" class="section-text">• 软件审计看代码和测试，硬件审计看设备状态和串口，多模态审计看视频音频</text>
<text x="1490" y="464" class="section-text">• 审计不是只读日志，它可以在需要时接管测试硬件能力做完整验证</text>
<text x="1490" y="500" class="section-text">• 最后由总审计 Agent 给出通过、驳回、需人工复核或返工建议</text>
<text x="1490" y="532" class="section-text-small">技术：Rules Audit Engine、Audit Orchestrator、专项审计 Agent、Chief Auditor</text>
<g filter="url(#shadow)">
<rect x="1426" y="646" width="500" height="336" rx="30" fill="#FFFFFF"/>
<rect x="1922" y="650" width="10" height="328" rx="5" fill="#EF4444"/>
</g>
<rect x="1468" y="680" width="196" height="34" rx="17" fill="#FEEAEA"/>
<text x="1514" y="703" class="badge" style="fill:#B42318">硬件测试闭环</text>
<text x="1468" y="762" class="section-title">5. 硬件能力按需被审计 Agent 接管</text>
<text x="1468" y="810" class="section-text">• 摄像头、麦克风、扬声器、串口、继电器、拇指机器人先注册成能力</text>
<text x="1468" y="846" class="section-text">• 审计 Agent 通过租约领取能力，必要时按优先级抢占，而不是直接抢桌面</text>
<text x="1468" y="882" class="section-text">• 多模态测试能形成完整闭环：发声、拍摄、按压、观察、记录、判断</text>
<text x="1468" y="918" class="section-text">• 测试证据被归档，后续可以回放和复盘</text>
<text x="1468" y="950" class="section-text-small">技术：Capability Registry、Lease Manager、Preemption Manager、Test Rig Gateway、Evidence Collector</text>
<g filter="url(#shadow)">
<rect x="698" y="1044" width="610" height="224" rx="30" fill="#FFFFFF"/>
<rect x="694" y="1048" width="10" height="216" rx="5" fill="#0EA5E9"/>
</g>
<rect x="742" y="1078" width="196" height="34" rx="17" fill="#E4F6FD"/>
<text x="786" y="1101" class="badge" style="fill:#0369A1">交付与异常</text>
<text x="742" y="1160" class="section-title">6. 结果汇总、交付、异常恢复</text>
<text x="742" y="1208" class="section-text">• 主 Agent 汇总各线程结果和审计结论，输出阶段成果、风险、下一步建议</text>
<text x="742" y="1244" class="section-text">• 如果 worker 掉线、额度耗尽、主账号失效，系统自动切备用账号、备用主控或 API 容灾</text>
<text x="742" y="1276" class="section-text-small">技术：Event Store、Postgres、对象存储、gptpluscontrol、Standby Controller、API Fallback</text>
<rect x="84" y="1066" width="470" height="170" rx="22" fill="#FFFFFF" opacity="0.9"/>
<text x="118" y="1114" class="section-title" style="font-size:21px;">业务上最核心的变化</text>
<text x="118" y="1152" class="section-text-small">从“一个 Codex 长线程写到底”变成“一个主 Agent 驱动多个短线程协作”。</text>
<text x="118" y="1182" class="section-text-small">用户看到的是一个连续项目流程，系统内部则是拆分执行、持续审计、随时切换。</text>
<rect x="1450" y="1046" width="470" height="174" rx="22" fill="#FFFFFF" opacity="0.9"/>
<text x="1484" y="1094" class="section-title" style="font-size:21px;">适合讨论的产品问题</text>
<text x="1484" y="1132" class="section-text-small">• 手机端项目页长什么样</text>
<text x="1484" y="1160" class="section-text-small">• 主 Agent 什么时候自动审计、什么时候打断用户</text>
<text x="1484" y="1188" class="section-text-small">• 多机线程如何展示协作关系和失败重派</text>
<text x="92" y="1290" class="footer">图文件：/Users/kris/code/Talking/business_flow_mindmap_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/diagrams/business_flow_mindmap_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 MiB

213
docs/diagrams/business_flow_swimlane_cn.svg Normal file
View File

@@ -0,0 +1,213 @@
<svg width="2200" height="1780" viewBox="0 0 2200 1780" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="180" y1="40" x2="2020" y2="1740" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF4FF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="2200" height="1780" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#1F2937" flood-opacity="0.10"/>
</filter>
<style>
.title { font: 700 38px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17263C; }
.subtitle { font: 500 17px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4F647A; }
.stage { font: 700 20px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17314D; }
.lane { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.laneSub { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #5A6E84; }
.cardTitle { font: 700 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.cardText { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #43576D; }
.tech { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #60748C; }
</style>
</defs>
<rect width="2200" height="1780" rx="36" fill="url(#bg)"/>
<text x="90" y="92" class="title">Codex 多机协作业务流程泳道图</text>
<text x="90" y="128" class="subtitle">把“谁在什么时候做什么”拆开，并把主运维层、开放式运维接入、主 Agent 反向抢救运维层一起纳入业务流程。</text>
<g filter="url(#shadow)">
<rect x="250" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="570" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="890" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="1210" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="1530" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="1850" y="168" width="260" height="78" rx="20" fill="#FFFFFF"/>
</g>
<text x="346" y="214" class="stage">1. 立项进入</text>
<text x="653" y="214" class="stage">2. 规划与派发</text>
<text x="976" y="214" class="stage">3. 执行与协作</text>
<text x="1290" y="214" class="stage">4. 审计与测试</text>
<text x="1611" y="214" class="stage">5. 汇总与交付</text>
<text x="1913" y="214" class="stage">6. 异常与恢复</text>
<g opacity="0.97">
<rect x="60" y="286" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="486" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="686" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="886" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1086" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1286" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1486" width="2060" height="180" rx="26" fill="#FFFFFF"/>
</g>
<g stroke="#D8E2EF" stroke-width="2">
<line x1="230" y1="286" x2="230" y2="1666"/>
<line x1="550" y1="286" x2="550" y2="1666"/>
<line x1="870" y1="286" x2="870" y2="1666"/>
<line x1="1190" y1="286" x2="1190" y2="1666"/>
<line x1="1510" y1="286" x2="1510" y2="1666"/>
<line x1="1830" y1="286" x2="1830" y2="1666"/>
<line x1="60" y1="486" x2="2120" y2="486"/>
<line x1="60" y1="686" x2="2120" y2="686"/>
<line x1="60" y1="886" x2="2120" y2="886"/>
<line x1="60" y1="1086" x2="2120" y2="1086"/>
<line x1="60" y1="1286" x2="2120" y2="1286"/>
<line x1="60" y1="1486" x2="2120" y2="1486"/>
</g>
<rect x="78" y="316" width="126" height="48" rx="18" fill="#E8F1FF"/>
<text x="104" y="346" class="lane">用户 / 手机 App</text>
<text x="84" y="380" class="laneSub">你看到的产品流程入口</text>
<rect x="78" y="516" width="144" height="48" rx="18" fill="#EAF9EE"/>
<text x="102" y="546" class="lane">主 Agent / 主控</text>
<text x="84" y="580" class="laneSub">决策、拆解、调度、回收</text>
<rect x="78" y="716" width="160" height="48" rx="18" fill="#FFF3DD"/>
<text x="102" y="746" class="lane">Worker 执行层</text>
<text x="84" y="780" class="laneSub">Mac / Windows / Cloud Codex</text>
<rect x="78" y="916" width="134" height="48" rx="18" fill="#F4E8FF"/>
<text x="102" y="946" class="lane">审计层</text>
<text x="84" y="980" class="laneSub">规则 + 专项 Agent</text>
<rect x="78" y="1116" width="162" height="48" rx="18" fill="#FEEAEA"/>
<text x="102" y="1146" class="lane">硬件能力层</text>
<text x="84" y="1180" class="laneSub">Capability Registry / Test Rig</text>
<rect x="78" y="1316" width="188" height="48" rx="18" fill="#EEF2FF"/>
<text x="102" y="1346" class="lane">运维层 / 运维审计层</text>
<text x="84" y="1380" class="laneSub">主运维层 + 开放式接入 + 抢修</text>
<rect x="78" y="1516" width="178" height="48" rx="18" fill="#E4F6FD"/>
<text x="102" y="1546" class="lane">数据 / 容灾层</text>
<text x="84" y="1580" class="laneSub">Event Store / Quota / Standby</text>
<g filter="url(#shadow)">
<rect x="258" y="308" width="284" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1590" y="308" width="224" height="136" rx="20" fill="#FFFFFF"/>
<rect x="582" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="900" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1862" y="508" width="232" height="136" rx="20" fill="#FFFFFF"/>
<rect x="896" y="708" width="292" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1216" y="708" width="292" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="908" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="908" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="1108" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="1108" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="582" y="1308" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="1308" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="1308" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1862" y="1308" width="232" height="136" rx="20" fill="#FFFFFF"/>
<rect x="896" y="1508" width="292" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1862" y="1508" width="232" height="136" rx="20" fill="#FFFFFF"/>
</g>
<text x="278" y="340" class="cardTitle">发起项目需求</text>
<text x="278" y="368" class="cardText">输入目标、优先级、设备条件、交付标准。</text>
<text x="278" y="392" class="cardText">系统生成项目页，不再只是一串聊天。</text>
<text x="278" y="420" class="tech">技术：Mobile App / Web、Control API、Project View</text>
<text x="1610" y="340" class="cardTitle">查看结果与继续追问</text>
<text x="1610" y="368" class="cardText">看阶段成果、风险、审计结论、运维告警，再继续给主会话下指令。</text>
<text x="1610" y="420" class="tech">技术：项目页、线程页、时间线、通知中心</text>
<text x="602" y="540" class="cardTitle">项目结构化建模</text>
<text x="602" y="568" class="cardText">整理目标、里程碑、风险、待确认项。</text>
<text x="602" y="592" class="cardText">决定使用主 GPT、备用 GPT 还是 API 容灾。</text>
<text x="602" y="620" class="tech">技术：LangGraph、Project Memory、Quota Router</text>
<text x="920" y="540" class="cardTitle">任务拆解与派发</text>
<text x="920" y="568" class="cardText">按平台、算力、上下文体积拆成多个短任务。</text>
<text x="920" y="592" class="cardText">为每个任务挑选节点、账号、branch 与 worktree。</text>
<text x="920" y="620" class="tech">技术：Scheduler、Thread Registry、Git worktree</text>
<text x="1240" y="540" class="cardTitle">监管执行与审计触发</text>
<text x="1240" y="568" class="cardText">盯线程推进，必要时发起审计、重派或人工确认。</text>
<text x="1240" y="620" class="tech">技术：Audit Orchestrator、Rules Watchdog</text>
<text x="1560" y="540" class="cardTitle">汇总与阶段交付</text>
<text x="1560" y="568" class="cardText">归并子线程结果、审计结论、运维状态和下一步建议。</text>
<text x="1560" y="620" class="tech">技术：Decision Ledger、Summary Builder</text>
<text x="1882" y="540" class="cardTitle">主控异常切换</text>
<text x="1882" y="568" class="cardText">主账号或主控异常时切备用主控、备用账号或 API。</text>
<text x="1882" y="620" class="tech">技术：Standby Controller、Failover Policy</text>
<text x="916" y="740" class="cardTitle">多机并行开发</text>
<text x="916" y="768" class="cardText">Mac 做前端和本地联调，Windows 跑 GPU 或硬件桥接，云端跑长任务。</text>
<text x="916" y="820" class="tech">技术：Codex app-server / SDK、Worker Daemon</text>
<text x="1236" y="740" class="cardTitle">跨节点线程协作</text>
<text x="1236" y="768" class="cardText">Mac 线程可请求 Windows 线程做 GPU、硬件或平台验证。</text>
<text x="1236" y="820" class="tech">技术：Inter-Thread Broker、Thread Gateway、ACL</text>
<text x="1240" y="940" class="cardTitle">规则审计先筛异常</text>
<text x="1240" y="968" class="cardText">看超时、失败、断流、额度、反复压缩和卡住状态。</text>
<text x="1240" y="1020" class="tech">技术：Rules Audit Engine、Event Rules</text>
<text x="1560" y="940" class="cardTitle">专项审计与总审计</text>
<text x="1560" y="968" class="cardText">软件、硬件、多模态各自复核，再由总审计给出结论。</text>
<text x="1560" y="1020" class="tech">技术：Software Auditor、Hardware Auditor、Chief Auditor</text>
<text x="1240" y="1140" class="cardTitle">能力申请与租约</text>
<text x="1240" y="1168" class="cardText">审计 Agent 或 worker 先申请摄像头、串口、机器人等能力。</text>
<text x="1240" y="1220" class="tech">技术：Capability Registry、Lease Manager</text>
<text x="1560" y="1140" class="cardTitle">抢占、执行、证据回传</text>
<text x="1560" y="1168" class="cardText">按优先级抢占，执行测试动作，回传视频、音频、日志和检测结果。</text>
<text x="1560" y="1220" class="tech">技术：Preemption Manager、Test Rig Gateway、Evidence Collector</text>
<text x="602" y="1340" class="cardTitle">开放式主运维层接入</text>
<text x="602" y="1368" class="cardText">为其他项目注册运维域、连接器、健康探针和 Runbook Pack。</text>
<text x="602" y="1420" class="tech">技术：Ops Domain、Ops Extension Registry、Connector Runtime</text>
<text x="1240" y="1340" class="cardTitle">动态巡检、跨设备运维与修复授权</text>
<text x="1240" y="1368" class="cardText">高频使用时 5 分钟巡检，空闲时 1 小时；还能跨设备拉日志、重启服务、切账号、跑 Runbook。</text>
<text x="1240" y="1420" class="tech">技术：Ops Policy Engine、Local Ops Agent、Remote Actions、Postgres Queue</text>
<text x="1560" y="1340" class="cardTitle">运维修复复验与汇报</text>
<text x="1560" y="1368" class="cardText">修复后先由运维审计层复验，再把结论和剩余风险报告主会话。</text>
<text x="1560" y="1420" class="tech">技术：Repair Ticket、Verification、Ops Ledger</text>
<text x="1882" y="1340" class="cardTitle">反向抢救运维层</text>
<text x="1882" y="1368" class="cardText">如果运维层自己挂了，主 Agent 切到 rescue 模式，走最小救援通道恢复运维层。</text>
<text x="1882" y="1420" class="tech">技术：ops_rescue_mode、Emergency RPC、Standby Ops</text>
<text x="916" y="1540" class="cardTitle">全量事件镜像</text>
<text x="916" y="1568" class="cardText">线程消息、命令、patch、审批、协作、告警和修复工单都落库。</text>
<text x="916" y="1620" class="tech">技术：Event Store、Postgres、对象存储</text>
<text x="1882" y="1540" class="cardTitle">额度与容灾健康矩阵</text>
<text x="1882" y="1568" class="cardText">监控各 Codex 节点剩余额度、切换记录、Standby 状态与运维健康矩阵。</text>
<text x="1882" y="1620" class="tech">技术：gptpluscontrol、SSE、Capacity Report、Standby Controller</text>
<g stroke-linecap="round" stroke-width="5">
<path d="M542 376H586V546" stroke="#3B82F6"/>
<path d="M858 576H900" stroke="#22C55E"/>
<path d="M1176 576H1220" stroke="#22C55E"/>
<path d="M1496 576H1540" stroke="#22C55E"/>
<path d="M1816 576H1882" stroke="#EF4444"/>
<path d="M1050 644V708" stroke="#F59E0B"/>
<path d="M1360 644V908" stroke="#A855F7"/>
<path d="M1680 1044V1108" stroke="#EF4444"/>
<path d="M1042 844V1508" stroke="#0EA5E9"/>
<path d="M1360 644V1308" stroke="#6D28D9"/>
<path d="M1812 376H1838V1508" stroke="#0EA5E9"/>
<path d="M1496 1376H1540" stroke="#6D28D9"/>
<path d="M1816 1376H1882" stroke="#EF4444"/>
</g>
<text x="90" y="1736" class="footer">图文件：/Users/kris/code/Talking/business_flow_swimlane_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/diagrams/business_flow_swimlane_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.5 MiB

132
docs/diagrams/current_flow_mindmap_cn.svg Normal file
View File

@@ -0,0 +1,132 @@
<svg width="1800" height="1220" viewBox="0 0 1800 1220" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="200" y1="80" x2="1600" y2="1140" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EDF4FF"/>
</linearGradient>
<linearGradient id="centerFill" x1="730" y1="465" x2="1070" y2="755" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F62FE"/>
<stop offset="1" stop-color="#4A8DFF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="1800" height="1220" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="18" stdDeviation="20" flood-color="#1F2937" flood-opacity="0.12"/>
</filter>
<style>
.title { font: 700 34px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #152033; }
.subtitle { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4D6178; }
.section-title { font: 700 24px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.section-text { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #3D5066; }
.section-text-small { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4C6075; }
.center-title { font: 700 30px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: white; }
.center-text { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: rgba(255,255,255,0.92); }
.badge { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #5E7289; }
</style>
</defs>
<rect x="0" y="0" width="1800" height="1220" rx="36" fill="url(#bg)"/>
<text x="94" y="92" class="title">Codex 多机协作当前流程思维导图</text>
<text x="94" y="126" class="subtitle">围绕手机单入口、主控调度、多机 Codex、专项审计、硬件能力接管与容灾恢复的当前整体流程</text>
<g filter="url(#shadow)">
<rect x="690" y="450" width="420" height="300" rx="34" fill="url(#centerFill)"/>
</g>
<rect x="728" y="490" width="344" height="36" rx="18" fill="rgba(255,255,255,0.18)"/>
<text x="790" y="515" class="badge">当前主流程中心</text>
<text x="779" y="580" class="center-title">一个主 Agent</text>
<text x="758" y="622" class="center-title">统一调度全局</text>
<text x="776" y="665" class="center-text">手机端只和一个主会话对话</text>
<text x="742" y="694" class="center-text">外部记忆保存项目真相，不让单线程越聊越钝</text>
<path d="M690 566C594 534 484 490 390 425" stroke="#3B82F6" stroke-width="6" stroke-linecap="round"/>
<path d="M695 633C579 646 471 665 392 728" stroke="#22C55E" stroke-width="6" stroke-linecap="round"/>
<path d="M895 450C891 332 892 252 892 186" stroke="#F59E0B" stroke-width="6" stroke-linecap="round"/>
<path d="M1108 563C1229 533 1340 492 1410 426" stroke="#A855F7" stroke-width="6" stroke-linecap="round"/>
<path d="M1108 640C1230 651 1348 681 1410 744" stroke="#EF4444" stroke-width="6" stroke-linecap="round"/>
<path d="M900 752C902 852 905 918 905 1002" stroke="#0EA5E9" stroke-width="6" stroke-linecap="round"/>
<g filter="url(#shadow)">
<rect x="96" y="244" width="462" height="300" rx="28" fill="#FFFFFF"/>
<rect x="92" y="246" width="10" height="294" rx="5" fill="#3B82F6"/>
</g>
<rect x="132" y="274" width="124" height="32" rx="16" fill="#E8F1FF"/>
<text x="165" y="296" class="badge">用户入口</text>
<text x="132" y="346" class="section-title">1. 手机端 / Web 单入口</text>
<text x="132" y="388" class="section-text">• 只保留一个主对话窗口，不让用户自己分配线程</text>
<text x="132" y="420" class="section-text">• 项目列表可查看每个 Codex 线程的聊天、命令、补丁、状态</text>
<text x="132" y="452" class="section-text">• 顶部小胶囊显示当前主控身份：主 GPT / 备用 GPT / API 容灾</text>
<text x="132" y="484" class="section-text">• 实时显示各绑定 Codex 客户端剩余额度和切换情况</text>
<g filter="url(#shadow)">
<rect x="92" y="616" width="488" height="302" rx="28" fill="#FFFFFF"/>
<rect x="88" y="620" width="10" height="294" rx="5" fill="#22C55E"/>
</g>
<rect x="130" y="646" width="154" height="32" rx="16" fill="#EAF9EE"/>
<text x="168" y="668" class="badge" style="fill:#14803D">主控编排</text>
<text x="130" y="716" class="section-title">2. Master Agent Runtime</text>
<text x="130" y="758" class="section-text">• LangGraph 负责任务拆解、节点选择、上下文裁剪、阶段推进</text>
<text x="130" y="790" class="section-text">• Project Memory 保存目标、约束、摘要、决策和未决项</text>
<text x="130" y="822" class="section-text">• Scheduler 按平台能力、额度、负载和项目优先级派发任务</text>
<text x="130" y="854" class="section-text">• Inter-Thread Broker 监管 Mac / Windows / 云线程的对话</text>
<g filter="url(#shadow)">
<rect x="648" y="78" width="510" height="288" rx="28" fill="#FFFFFF"/>
<rect x="644" y="82" width="10" height="280" rx="5" fill="#F59E0B"/>
</g>
<rect x="686" y="108" width="164" height="32" rx="16" fill="#FFF4DA"/>
<text x="725" y="130" class="badge" style="fill:#A16207">执行层</text>
<text x="686" y="178" class="section-title">3. 多机 Codex Worker 执行</text>
<text x="686" y="220" class="section-text">• Mac Worker：前端、Xcode、轻量开发、本地联调</text>
<text x="686" y="252" class="section-text">• Windows Worker（WSL2）：GPU、CUDA、Windows 工具链、硬件桥接</text>
<text x="686" y="284" class="section-text">• Cloud Worker：CI、批处理、长任务、后台服务</text>
<text x="686" y="316" class="section-text">• 每个节点都运行自己的 Codex app-server / SDK 和独立账号</text>
<g filter="url(#shadow)">
<rect x="1236" y="244" width="474" height="300" rx="28" fill="#FFFFFF"/>
<rect x="1704" y="246" width="10" height="294" rx="5" fill="#A855F7"/>
</g>
<rect x="1272" y="274" width="160" height="32" rx="16" fill="#F4E8FF"/>
<text x="1307" y="296" class="badge" style="fill:#7E22CE">审计层</text>
<text x="1272" y="346" class="section-title">4. 混合审计与专项 Agent</text>
<text x="1272" y="388" class="section-text">• Rules Audit Engine：先看超时、失败、断流、额度、队列积压</text>
<text x="1272" y="420" class="section-text">• 软件审计 Agent：看代码、测试、接口契约、发布风险</text>
<text x="1272" y="452" class="section-text">• 硬件审计 Agent：看固件、串口、传感器、设备状态机</text>
<text x="1272" y="484" class="section-text">• 多模态审计 Agent：看视频、截图、音频、拟人交互效果</text>
<g filter="url(#shadow)">
<rect x="1228" y="620" width="492" height="312" rx="28" fill="#FFFFFF"/>
<rect x="1724" y="624" width="10" height="304" rx="5" fill="#EF4444"/>
</g>
<rect x="1268" y="650" width="184" height="32" rx="16" fill="#FEEAEA"/>
<text x="1304" y="672" class="badge" style="fill:#B42318">开放硬件能力</text>
<text x="1268" y="722" class="section-title">5. Capability Registry + Test Rig</text>
<text x="1268" y="764" class="section-text">• 摄像头、麦克风、扬声器、串口、继电器、拇指机器人统一注册</text>
<text x="1268" y="796" class="section-text">• Lease Manager 管租约，Preemption Manager 管抢占和宽限期</text>
<text x="1268" y="828" class="section-text">• 审计 Agent 通过标准能力接口接管硬件，不直接抢系统桌面</text>
<text x="1268" y="860" class="section-text">• Evidence Collector 归档视频片段、截图、音频、日志与检测结果</text>
<g filter="url(#shadow)">
<rect x="606" y="956" width="594" height="218" rx="28" fill="#FFFFFF"/>
<rect x="602" y="960" width="10" height="210" rx="5" fill="#0EA5E9"/>
</g>
<rect x="646" y="986" width="192" height="32" rx="16" fill="#E4F6FD"/>
<text x="683" y="1008" class="badge" style="fill:#0369A1">数据与容灾</text>
<text x="646" y="1058" class="section-title">6. Event Store / Quota / Standby</text>
<text x="646" y="1100" class="section-text">• Event Store 镜像 thread、命令、patch、审批、协作与告警</text>
<text x="646" y="1132" class="section-text">• gptpluscontrol 提供剩余额度、账号切换、实时监控和预警</text>
<text x="646" y="1164" class="section-text">• Standby Controller 和外部状态存储保证主控故障后仍可接管</text>
<rect x="104" y="1068" width="364" height="96" rx="20" fill="#FFFFFF" opacity="0.82"/>
<text x="132" y="1106" class="section-title" style="font-size:20px;">当前主流程一句话</text>
<text x="132" y="1138" class="section-text-small">用户只对一个主 Agent 说话，主 Agent 依靠外部记忆和事件流</text>
<text x="132" y="1162" class="section-text-small">去调度多台机器上的短上下文 Codex 线程，并在审计与容灾下持续推进。</text>
<rect x="1320" y="1012" width="406" height="136" rx="20" fill="#FFFFFF" opacity="0.9"/>
<text x="1348" y="1050" class="section-title" style="font-size:20px;">开发顺序建议</text>
<text x="1348" y="1082" class="section-text-small">1. 先打通 Worker + Event Store + Quota Monitor</text>
<text x="1348" y="1108" class="section-text-small">2. 再接 Inter-Thread Broker 和审计任务协议</text>
<text x="1348" y="1134" class="section-text-small">3. 最后接 Capability Registry 与硬件测试台</text>
<text x="94" y="1196" class="footer">图文件：/Users/kris/code/Talking/current_flow_mindmap_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/diagrams/current_flow_mindmap_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 MiB

93
docs/diagrams/ha_modes_cn.svg Normal file
View File

@@ -0,0 +1,93 @@
<svg width="1600" height="980" viewBox="0 0 1600 980" xmlns="http://www.w3.org/2000/svg">
<defs>
<style>
.bg { fill: #f7f8fc; }
.title { font: 700 34px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #1d2736; }
.sub { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #526070; }
.panel { fill: #ffffff; stroke: #d8deea; stroke-width: 2; rx: 24; ry: 24; }
.panelTitle { font: 700 24px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #17212e; }
.panelSub { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #5a6878; }
.boxBlue { fill: #eef5ff; stroke: #8cb5ff; stroke-width: 2; rx: 18; ry: 18; }
.boxGreen { fill: #eefaf2; stroke: #8dcca1; stroke-width: 2; rx: 18; ry: 18; }
.boxOrange { fill: #fff6ea; stroke: #f0b56a; stroke-width: 2; rx: 18; ry: 18; }
.boxGray { fill: #f5f7fb; stroke: #cfd8e6; stroke-width: 2; rx: 18; ry: 18; }
.boxTitle { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #1e2a39; }
.boxText { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #556273; }
.tech { font: 600 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #3d6fd6; }
.foot { font: 600 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #7a8796; }
.arrow { stroke: #6f7f95; stroke-width: 3; fill: none; marker-end: url(#arrowhead); }
</style>
<marker id="arrowhead" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
<polygon points="0 0, 10 4, 0 8" fill="#6f7f95"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1600" height="980"/>
<text class="title" x="70" y="70">容灾保活两种部署模式</text>
<text class="sub" x="70" y="104">系统同时支持“单云 + 单 Mac 备用控制器”和“双云热备 / 温备”，按成本与可用性选择。</text>
<rect class="panel" x="60" y="140" width="710" height="760"/>
<text class="panelTitle" x="90" y="190">模式 A：单云 + 单 Mac 备用控制器</text>
<text class="panelSub" x="90" y="220">更省云成本，适合已有常开 Mac 的现场环境。</text>
<rect class="boxBlue" x="100" y="270" width="250" height="150"/>
<text class="boxTitle" x="126" y="305">Cloud A（主用）</text>
<text class="boxText" x="126" y="338">控制面单体</text>
<text class="boxText" x="126" y="364">PostgreSQL 主库 + pgvector</text>
<text class="boxText" x="126" y="390">HTTP + SSE</text>
<rect class="boxGreen" x="420" y="270" width="290" height="180"/>
<text class="boxTitle" x="446" y="305">Standby Mac（备用）</text>
<text class="boxText" x="446" y="338">备用控制面轻实例</text>
<text class="boxText" x="446" y="364">PostgreSQL 备库 / 快照恢复实例</text>
<text class="boxText" x="446" y="390">Standby Controller</text>
<text class="boxText" x="446" y="416">Ops Rescue Gateway</text>
<path class="arrow" d="M350 345 C385 345, 390 345, 420 345"/>
<rect class="boxOrange" x="100" y="500" width="610" height="160"/>
<text class="boxTitle" x="126" y="536">必要前提</text>
<text class="boxText" x="126" y="570">1. 备用 Mac 必须常开，并保留可用磁盘做备份与恢复。</text>
<text class="boxText" x="126" y="598">2. 手机 App 必须支持主 / 备 endpoint 列表切换。</text>
<text class="boxText" x="126" y="626">3. 必须有一条不依赖主云的可达通路：同局域网、Tailscale/WireGuard 或长期反向隧道。</text>
<rect class="boxGray" x="100" y="700" width="610" height="150"/>
<text class="boxTitle" x="126" y="736">优点与边界</text>
<text class="boxText" x="126" y="770">优点：更省钱，本地接管更快，适合已有常开 Mac mini 的环境。</text>
<text class="boxText" x="126" y="798">边界：如果云和现场 Mac 同时断电 / 断网，这条备援链也会失效。</text>
<text class="tech" x="126" y="826">建议最低：M1 / 8GB / 50GB，可用更稳：16GB / 100GB</text>
<rect class="panel" x="830" y="140" width="710" height="760"/>
<text class="panelTitle" x="860" y="190">模式 B：双云热备 / 温备</text>
<text class="panelSub" x="860" y="220">更强的远程连续性，适合把备援独立于现场设备之外。</text>
<rect class="boxBlue" x="870" y="270" width="250" height="150"/>
<text class="boxTitle" x="896" y="305">Cloud A（主用）</text>
<text class="boxText" x="896" y="338">控制面单体</text>
<text class="boxText" x="896" y="364">PostgreSQL 主库 + pgvector</text>
<text class="boxText" x="896" y="390">HTTP + SSE</text>
<rect class="boxGreen" x="1190" y="270" width="290" height="180"/>
<text class="boxTitle" x="1216" y="305">Cloud B（备用）</text>
<text class="boxText" x="1216" y="338">备用控制面单体</text>
<text class="boxText" x="1216" y="364">PostgreSQL 备库</text>
<text class="boxText" x="1216" y="390">接管脚本 / 快照 / 恢复钩子</text>
<text class="boxText" x="1216" y="416">Standby Controller</text>
<path class="arrow" d="M1120 345 C1155 345, 1160 345, 1190 345"/>
<rect class="boxOrange" x="870" y="500" width="610" height="160"/>
<text class="boxTitle" x="896" y="536">必要前提</text>
<text class="boxText" x="896" y="570">1. Cloud B 只做热备 / 温备，不承担常态重负载。</text>
<text class="boxText" x="896" y="598">2. 手机 App 与控制面支持主 / 备云 endpoint 切换。</text>
<text class="boxText" x="896" y="626">3. 设备端继续承担重媒体、重审计、重运维执行动作。</text>
<rect class="boxGray" x="870" y="700" width="610" height="150"/>
<text class="boxTitle" x="896" y="736">优点与边界</text>
<text class="boxText" x="896" y="770">优点：公网可达性更稳，不依赖现场某一台设备，接管路径更标准化。</text>
<text class="boxText" x="896" y="798">边界：成本更高；最后一跳的硬件接管仍要依赖现场设备在线。</text>
<text class="tech" x="896" y="826">建议最低：Cloud A 2C8G/100GB，Cloud B 2C8G/100GB</text>
<text class="foot" x="70" y="940">统一抽象建议：standby_provider = standby_mac | cloud_b | both</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/diagrams/ha_modes_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 521 KiB

166
docs/diagrams/ops_repair_swimlane_cn.svg Normal file
View File

@@ -0,0 +1,166 @@
<svg width="2200" height="1420" viewBox="0 0 2200 1420" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="160" y1="40" x2="2040" y2="1380" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF5FF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="2200" height="1420" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="14" stdDeviation="18" flood-color="#1F2937" flood-opacity="0.10"/>
</filter>
<style>
.title { font: 700 36px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #15253B; }
.subtitle { font: 500 17px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #51657C; }
.stage { font: 700 20px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17314D; }
.lane { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.laneSub { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #5A6E84; }
.cardTitle { font: 700 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.cardText { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #44586E; }
.tech { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #60758C; }
</style>
</defs>
<rect width="2200" height="1420" rx="36" fill="url(#bg)"/>
<text x="90" y="92" class="title">运维层与运维审计层抢修流程泳道图</text>
<text x="90" y="126" class="subtitle">覆盖动态巡检、日志命名、在线审批修复、主控离线紧急接管、修复复验与主控恢复回放。</text>
<!-- Stage headers -->
<g filter="url(#shadow)">
<rect x="250" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="550" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="850" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="1150" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="1450" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="1750" y="162" width="330" height="76" rx="20" fill="#FFFFFF"/>
</g>
<text x="331" y="207" class="stage">1. 动态巡检</text>
<text x="623" y="207" class="stage">2. 异常分类</text>
<text x="929" y="207" class="stage">3. 审批 / 授权</text>
<text x="1231" y="207" class="stage">4. 修复执行</text>
<text x="1543" y="207" class="stage">5. 复验</text>
<text x="1831" y="207" class="stage">6. 汇报与回放</text>
<!-- Lane backgrounds -->
<g opacity="0.96">
<rect x="60" y="280" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="484" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="688" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="892" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1096" width="2060" height="184" rx="26" fill="#FFFFFF"/>
</g>
<!-- Grid -->
<g stroke="#D8E2EF" stroke-width="2">
<line x1="230" y1="280" x2="230" y2="1280"/>
<line x1="530" y1="280" x2="530" y2="1280"/>
<line x1="830" y1="280" x2="830" y2="1280"/>
<line x1="1130" y1="280" x2="1130" y2="1280"/>
<line x1="1430" y1="280" x2="1430" y2="1280"/>
<line x1="1730" y1="280" x2="1730" y2="1280"/>
<line x1="60" y1="484" x2="2120" y2="484"/>
<line x1="60" y1="688" x2="2120" y2="688"/>
<line x1="60" y1="892" x2="2120" y2="892"/>
<line x1="60" y1="1096" x2="2120" y2="1096"/>
</g>
<!-- Lanes -->
<rect x="78" y="310" width="134" height="48" rx="18" fill="#E8F1FF"/>
<text x="102" y="340" class="lane">主 Agent</text>
<text x="84" y="374" class="laneSub">在线审批与接收回放</text>
<rect x="78" y="514" width="144" height="48" rx="18" fill="#EAF9EE"/>
<text x="102" y="544" class="lane">Ops Agent</text>
<text x="84" y="578" class="laneSub">巡检、分类、执行修复</text>
<rect x="78" y="718" width="188" height="48" rx="18" fill="#F4E8FF"/>
<text x="102" y="748" class="lane">Ops Audit Agent</text>
<text x="84" y="782" class="laneSub">监督、判权、复验、紧急决策</text>
<rect x="78" y="922" width="162" height="48" rx="18" fill="#FEEAEA"/>
<text x="102" y="952" class="lane">终端服务层</text>
<text x="84" y="986" class="laneSub">主控 / Worker / 网关 / 硬件桥</text>
<rect x="78" y="1126" width="176" height="48" rx="18" fill="#E4F6FD"/>
<text x="102" y="1156" class="lane">数据与容灾层</text>
<text x="84" y="1190" class="laneSub">Ops Ledger / Event / Standby</text>
<!-- Cards -->
<g filter="url(#shadow)">
<rect x="552" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="552" y="710" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1752" y="302" width="320" height="136" rx="20" fill="#FFFFFF"/>
<rect x="852" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="852" y="710" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1152" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1452" y="710" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1152" y="914" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1452" y="914" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1152" y="1118" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1752" y="1118" width="320" height="136" rx="20" fill="#FFFFFF"/>
<rect x="252" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
</g>
<text x="272" y="538" class="cardTitle">动态巡检模式</text>
<text x="272" y="566" class="cardText">高频使用时每 5 分钟巡检，系统空闲时每 1 小时巡检。</text>
<text x="272" y="618" class="tech">技术：Ops Policy Engine、Mode Switch Rules</text>
<text x="572" y="538" class="cardTitle">日志归一与故障聚类</text>
<text x="572" y="566" class="cardText">按 `LAYER.DOMAIN.COMPONENT.ACTION.ERROR_CODE` 归类，生成最小证据包。</text>
<text x="572" y="618" class="tech">技术：fault_key、Runbook Map、Log Index</text>
<text x="872" y="538" class="cardTitle">主控在线时请求审批</text>
<text x="872" y="566" class="cardText">主 Agent 在线且可响应时，Ops Agent 先提修复建议，不能越权直接修。</text>
<text x="872" y="618" class="tech">技术：Approval Request、Repair Ticket</text>
<text x="872" y="742" class="cardTitle">主控失联时做最终判断</text>
<text x="872" y="770" class="cardText">确认主控失联后，Ops Audit Agent 联合 Chief Ops Audit Agent 决定是否抢修。</text>
<text x="872" y="822" class="tech">技术：Emergency Authority、Offline Quorum</text>
<text x="1172" y="538" class="cardTitle">执行修复 Runbook</text>
<text x="1172" y="566" class="cardText">重启服务、切换账号、恢复心跳、释放孤儿租约、重建连接等。</text>
<text x="1172" y="618" class="tech">技术：Runbook Executor、Safe Action Policy</text>
<text x="1472" y="742" class="cardTitle">复验修复是否真的成功</text>
<text x="1472" y="770" class="cardText">看原故障是否消失、服务是否恢复、事件流是否恢复、是否有副作用。</text>
<text x="1472" y="822" class="tech">技术：Ops Audit Verification、Synthetic Probe</text>
<text x="1172" y="946" class="cardTitle">被修复对象恢复服务</text>
<text x="1172" y="974" class="cardText">主控、Worker、Thread Gateway、Audit Orchestrator、Test Rig、gptpluscontrol 等恢复。</text>
<text x="1172" y="1026" class="tech">技术：Service Supervisor、Health Probe</text>
<text x="1472" y="946" class="cardTitle">产生新健康状态与证据</text>
<text x="1472" y="974" class="cardText">生成复验日志、关键快照、队列状态、额度状态和回放材料。</text>
<text x="1472" y="1026" class="tech">技术：Evidence Collector、Health Snapshot</text>
<text x="1172" y="1150" class="cardTitle">修复账本留痕</text>
<text x="1172" y="1178" class="cardText">写入 repair ticket、动作、复验结果、主控是否在线、后续风险。</text>
<text x="1172" y="1230" class="tech">技术：Ops Ledger、Event Store、Postgres</text>
<text x="1772" y="334" class="cardTitle">主控每小时检查运维层</text>
<text x="1772" y="362" class="cardText">确认各节点 Ops Agent / Ops Audit Agent 是否在线且最近巡检成功。</text>
<text x="1772" y="414" class="tech">技术：Master Health Check、Ops Node Matrix</text>
<text x="1772" y="1150" class="cardTitle">恢复后回放给主控</text>
<text x="1772" y="1178" class="cardText">主控恢复在线后，自动收到故障摘要、修复动作、复验结论和剩余风险。</text>
<text x="1772" y="1230" class="tech">技术：Repair Report Sync、Recovery Replay</text>
<text x="572" y="742" class="cardTitle">监督 Ops Agent 是否越权</text>
<text x="572" y="770" class="cardText">确认主控是否在线、当前动作是否在自动修复白名单、是否需要升级。</text>
<text x="572" y="822" class="tech">技术：Ops Audit Policy、Privilege Gate</text>
<!-- Flow arrows -->
<g stroke-linecap="round" stroke-width="5">
<path d="M510 574H552" stroke="#22C55E"/>
<path d="M810 574H852" stroke="#22C55E"/>
<path d="M1110 574H1152" stroke="#22C55E"/>
<path d="M1410 982H1452" stroke="#EF4444"/>
<path d="M1710 778H1752V1186" stroke="#A855F7"/>
<path d="M2012 438V1118" stroke="#0EA5E9"/>
<path d="M980 642V710" stroke="#A855F7"/>
<path d="M1280 642V914" stroke="#EF4444"/>
<path d="M1280 1050V1118" stroke="#0EA5E9"/>
<path d="M1610 846V914" stroke="#EF4444"/>
</g>
<text x="90" y="1376" class="footer">图文件：/Users/kris/code/Talking/ops_repair_swimlane_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/diagrams/ops_repair_swimlane_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 MiB

103
docs/diagrams/ultra_light_dual_cloud_topology_cn.svg Normal file
View File

@@ -0,0 +1,103 @@
<svg width="1900" height="1180" viewBox="0 0 1900 1180" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="120" y1="40" x2="1780" y2="1120" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF5FF"/>
</linearGradient>
<linearGradient id="cloudA" x1="520" y1="250" x2="900" y2="640" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F62FE"/>
<stop offset="1" stop-color="#4D91FF"/>
</linearGradient>
<linearGradient id="cloudB" x1="1010" y1="250" x2="1390" y2="640" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F766E"/>
<stop offset="1" stop-color="#2CB7A5"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="1900" height="1180" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#1F2937" flood-opacity="0.10"/>
</filter>
<style>
.title { font: 700 36px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17263C; }
.subtitle { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #51657C; }
.cardTitle { font: 700 24px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #FFFFFF; }
.cardText { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: rgba(255,255,255,0.92); }
.sectionTitle { font: 700 22px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #14263D; }
.sectionText { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #45586F; }
.tag { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #60748C; }
</style>
</defs>
<rect width="1900" height="1180" rx="36" fill="url(#bg)"/>
<text x="80" y="92" class="title">极轻云双云部署拓扑图</text>
<text x="80" y="126" class="subtitle">原则：云端只保留控制面真相和调度真相；主云承载业务，备云只承担接管准备；重执行全部下沉到设备端。</text>
<g filter="url(#shadow)">
<rect x="720" y="86" width="460" height="112" rx="26" fill="#FFFFFF"/>
</g>
<text x="852" y="132" class="sectionTitle">手机 App / Web</text>
<text x="780" y="166" class="sectionText">只看项目、线程、审计结论、运维状态，不直接连设备节点</text>
<g filter="url(#shadow)">
<rect x="520" y="250" width="390" height="360" rx="30" fill="url(#cloudA)"/>
<rect x="990" y="250" width="390" height="360" rx="30" fill="url(#cloudB)"/>
</g>
<text x="650" y="302" class="cardTitle">Cloud A 主云</text>
<text x="566" y="344" class="cardText">常态承载主业务流量</text>
<text x="566" y="380" class="cardText">• 控制面单体（FastAPI + LangGraph）</text>
<text x="566" y="412" class="cardText">• Master Agent / Scheduler / Audit / Ops</text>
<text x="566" y="444" class="cardText">• Thread Registry / Broker 逻辑</text>
<text x="566" y="476" class="cardText">• PostgreSQL 主库 + pgvector</text>
<text x="566" y="508" class="cardText">• HTTP + SSE</text>
<text x="566" y="556" class="cardText">不放：</text>
<text x="566" y="588" class="cardText">Redis / NATS / 独立向量库 / 重媒体处理</text>
<text x="1120" y="302" class="cardTitle">Cloud B 备云</text>
<text x="1036" y="344" class="cardText">平时只做热备 / 温备，不跑重负载</text>
<text x="1036" y="380" class="cardText">• 备用控制面单体</text>
<text x="1036" y="412" class="cardText">• PostgreSQL 备库</text>
<text x="1036" y="444" class="cardText">• 接管脚本 / 快照 / 恢复入口</text>
<text x="1036" y="476" class="cardText">• Standby Controller / Rescue hooks</text>
<text x="1036" y="556" class="cardText">目标：</text>
<text x="1036" y="588" class="cardText">保持“可接管”，而不是“平时跑满”</text>
<g filter="url(#shadow)">
<rect x="110" y="726" width="520" height="290" rx="28" fill="#FFFFFF"/>
<rect x="690" y="726" width="520" height="290" rx="28" fill="#FFFFFF"/>
<rect x="1270" y="726" width="520" height="290" rx="28" fill="#FFFFFF"/>
</g>
<rect x="150" y="758" width="172" height="32" rx="16" fill="#EAF9EE"/>
<text x="196" y="780" class="tag" style="fill:#14803D">Mac / Windows 节点</text>
<text x="150" y="834" class="sectionTitle">执行与边缘处理</text>
<text x="150" y="876" class="sectionText">• Worker Daemon</text>
<text x="150" y="906" class="sectionText">• Thread Gateway</text>
<text x="150" y="936" class="sectionText">• Local Ops Agent / Audit Agent</text>
<text x="150" y="966" class="sectionText">• OCR / 检测 / 视频裁剪 / 音频预处理</text>
<rect x="730" y="758" width="162" height="32" rx="16" fill="#FEEAEA"/>
<text x="767" y="780" class="tag" style="fill:#B42318">Test Rig / 硬件</text>
<text x="730" y="834" class="sectionTitle">硬件能力在边缘执行</text>
<text x="730" y="876" class="sectionText">• Camera / Mic / Speaker</text>
<text x="730" y="906" class="sectionText">• Thumb Robot / Relay / Serial</text>
<text x="730" y="936" class="sectionText">• Test Rig Gateway</text>
<text x="730" y="966" class="sectionText">• 只上传关键帧、短片段、摘要与异常证据</text>
<rect x="1310" y="758" width="182" height="32" rx="16" fill="#E4F6FD"/>
<text x="1353" y="780" class="tag" style="fill:#0369A1">为什么这样最省云</text>
<text x="1310" y="834" class="sectionTitle">云端不做重活</text>
<text x="1310" y="876" class="sectionText">• 不持续接原始媒体流</text>
<text x="1310" y="906" class="sectionText">• 不跑常驻重审计进程</text>
<text x="1310" y="936" class="sectionText">• 不做跨设备修复动作本体</text>
<text x="1310" y="966" class="sectionText">• 只保留真相、调度、索引、结论与接管能力</text>
<g stroke-linecap="round" stroke-width="6">
<path d="M950 198V248" stroke="#3B82F6"/>
<path d="M910 430H990" stroke="#94A3B8" stroke-dasharray="12 12"/>
<path d="M700 610V726" stroke="#22C55E"/>
<path d="M1180 610V726" stroke="#EF4444"/>
<path d="M1380 610V726" stroke="#0EA5E9"/>
</g>
<text x="80" y="1128" class="footer">图文件：/Users/kris/code/Talking/ultra_light_dual_cloud_topology_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
docs/diagrams/ultra_light_dual_cloud_topology_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 MiB

BIN
docs/source-material/WiFi音箱-技术实现逻辑与核心时序图_v1.docx Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-技术实现逻辑与核心时序图_v1.pdf Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-量产版AI接入与商业化方案设计_v1.docx Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-量产版AI接入与商业化方案设计_v1.pdf Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-量产版AI接入方案_客户汇报版_v1.docx Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-量产版AI接入方案_客户汇报版_v1.pdf Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-量产版AI接入方案_研发实施版_v1.docx Normal file
View File

Binary file not shown.

BIN
docs/source-material/WiFi音箱-量产版AI接入方案_研发实施版_v1.pdf Normal file
View File

Binary file not shown.

BIN
docs/source-material/assets/WiFi音箱-技术实现逻辑与核心时序图_v1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 242 KiB

137
docs/source-material/business_flow_mindmap_cn.svg Normal file
View File

@@ -0,0 +1,137 @@
<svg width="2000" height="1320" viewBox="0 0 2000 1320" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="140" y1="60" x2="1860" y2="1260" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF5FF"/>
</linearGradient>
<linearGradient id="centerFill" x1="790" y1="472" x2="1210" y2="848" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F62FE"/>
<stop offset="1" stop-color="#4D91FF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="2000" height="1320" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="18" stdDeviation="20" flood-color="#17212F" flood-opacity="0.12"/>
</filter>
<style>
.title { font: 700 36px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #162235; }
.subtitle { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4C6075; }
.section-title { font: 700 25px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #14253B; }
.section-text { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #43566B; }
.section-text-small { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #54687E; }
.badge { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; }
.center-title { font: 700 34px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: white; }
.center-text { font: 500 17px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: rgba(255,255,255,0.92); }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #61758D; }
</style>
</defs>
<rect width="2000" height="1320" rx="36" fill="url(#bg)"/>
<text x="92" y="92" class="title">Codex 多机协作业务流程思维导图</text>
<text x="92" y="126" class="subtitle">只讲业务推进链路，不讲底层服务拆分。适合拿来讨论产品体验、协作方式、项目推进和异常处置。</text>
<g filter="url(#shadow)">
<rect x="780" y="470" width="440" height="380" rx="38" fill="url(#centerFill)"/>
</g>
<rect x="832" y="512" width="336" height="38" rx="19" fill="rgba(255,255,255,0.18)"/>
<text x="927" y="537" class="badge" style="fill:#FFFFFF">业务流程中心</text>
<text x="884" y="615" class="center-title">一个主 Agent</text>
<text x="850" y="662" class="center-title">贯穿整个项目周期</text>
<text x="848" y="716" class="center-text">你始终只对一个主会话说话</text>
<text x="842" y="748" class="center-text">它负责理解需求、拆任务、派机器、盯进度、收结果</text>
<text x="870" y="780" class="center-text">并在异常时切换账号、节点或执行策略</text>
<path d="M782 572C672 532 541 487 408 407" stroke="#3B82F6" stroke-width="7" stroke-linecap="round"/>
<path d="M780 656C642 653 531 673 410 738" stroke="#22C55E" stroke-width="7" stroke-linecap="round"/>
<path d="M1000 470C1002 368 1004 272 1004 180" stroke="#F59E0B" stroke-width="7" stroke-linecap="round"/>
<path d="M1220 572C1342 529 1452 488 1590 410" stroke="#A855F7" stroke-width="7" stroke-linecap="round"/>
<path d="M1220 666C1354 672 1465 700 1592 778" stroke="#EF4444" stroke-width="7" stroke-linecap="round"/>
<path d="M1000 850C1000 949 1000 1032 1000 1126" stroke="#0EA5E9" stroke-width="7" stroke-linecap="round"/>
<g filter="url(#shadow)">
<rect x="80" y="232" width="494" height="308" rx="30" fill="#FFFFFF"/>
<rect x="76" y="236" width="10" height="300" rx="5" fill="#3B82F6"/>
</g>
<rect x="122" y="266" width="164" height="34" rx="17" fill="#E8F1FF"/>
<text x="162" y="289" class="badge" style="fill:#0F62FE">需求进入</text>
<text x="122" y="346" class="section-title">1. 你在手机里发起一个项目</text>
<text x="122" y="394" class="section-text">• 你描述目标、优先级、设备条件、交付标准，始终只对一个主 Agent 说话</text>
<text x="122" y="430" class="section-text">• 主 Agent 先把需求转成项目卡：目标、边界、风险、里程碑、待确认项</text>
<text x="122" y="466" class="section-text">• 如果项目涉及硬件、摄像头、机器人、串口，也在这里声明测试需求</text>
<text x="122" y="502" class="section-text">• App 里马上生成项目视图，而不是只留下一串长聊天记录</text>
<text x="122" y="532" class="section-text-small">技术：Mobile App / Web、Control API、Project View、WebSocket</text>
<g filter="url(#shadow)">
<rect x="84" y="624" width="522" height="330" rx="30" fill="#FFFFFF"/>
<rect x="80" y="628" width="10" height="322" rx="5" fill="#22C55E"/>
</g>
<rect x="126" y="658" width="174" height="34" rx="17" fill="#EAF9EE"/>
<text x="165" y="681" class="badge" style="fill:#14803D">规划与分派</text>
<text x="126" y="740" class="section-title">2. 主 Agent 拆任务并分配节点</text>
<text x="126" y="788" class="section-text">• 按功能、平台、算力、风险把项目拆成多个短任务，而不是一条线程写到底</text>
<text x="126" y="824" class="section-text">• Mac 负责前端、Xcode、本地联调；Windows 负责 GPU、硬件桥接；云端负责 CI 和长任务</text>
<text x="126" y="860" class="section-text">• 同时选择主账号、备用账号或 API 容灾路径，避免主流程因单账号额度耗尽而停摆</text>
<text x="126" y="896" class="section-text">• 每个任务都落在独立 worker thread、独立 branch / worktree 中</text>
<text x="126" y="928" class="section-text-small">技术：LangGraph、Scheduler、Project Memory、Git worktree、Thread Registry</text>
<g filter="url(#shadow)">
<rect x="728" y="78" width="554" height="296" rx="30" fill="#FFFFFF"/>
<rect x="724" y="82" width="10" height="288" rx="5" fill="#F59E0B"/>
</g>
<rect x="772" y="112" width="180" height="34" rx="17" fill="#FFF3DD"/>
<text x="812" y="135" class="badge" style="fill:#A16207">执行推进</text>
<text x="772" y="190" class="section-title">3. 多台 Codex 并行开发与协作</text>
<text x="772" y="238" class="section-text">• 各机器上的 Codex 线程按自己的短上下文工作，减少长上下文退化</text>
<text x="772" y="274" class="section-text">• 线程可以在主控监管下跨节点对话，例如 Mac 线程请求 Windows 做 GPU 或硬件验证</text>
<text x="772" y="310" class="section-text">• 所有聊天、命令、补丁、失败和审批都被实时镜像回主项目页面</text>
<text x="772" y="346" class="section-text">• 你点开任意任务就能看见该线程的完整进度，不需要自己切电脑</text>
<text x="772" y="376" class="section-text-small">技术：Codex app-server / SDK、Worker Daemon、Inter-Thread Broker、Event Store</text>
<g filter="url(#shadow)">
<rect x="1448" y="230" width="468" height="316" rx="30" fill="#FFFFFF"/>
<rect x="1912" y="234" width="10" height="308" rx="5" fill="#A855F7"/>
</g>
<rect x="1490" y="264" width="188" height="34" rx="17" fill="#F4E8FF"/>
<text x="1534" y="287" class="badge" style="fill:#7E22CE">审计与验证</text>
<text x="1490" y="344" class="section-title">4. 审计层复核“做完了没，做对了没”</text>
<text x="1490" y="392" class="section-text">• 规则审计先发现超时、失败、断流、额度异常、重复压缩</text>
<text x="1490" y="428" class="section-text">• 软件审计看代码和测试，硬件审计看设备状态和串口，多模态审计看视频音频</text>
<text x="1490" y="464" class="section-text">• 审计不是只读日志，它可以在需要时接管测试硬件能力做完整验证</text>
<text x="1490" y="500" class="section-text">• 最后由总审计 Agent 给出通过、驳回、需人工复核或返工建议</text>
<text x="1490" y="532" class="section-text-small">技术：Rules Audit Engine、Audit Orchestrator、专项审计 Agent、Chief Auditor</text>
<g filter="url(#shadow)">
<rect x="1426" y="646" width="500" height="336" rx="30" fill="#FFFFFF"/>
<rect x="1922" y="650" width="10" height="328" rx="5" fill="#EF4444"/>
</g>
<rect x="1468" y="680" width="196" height="34" rx="17" fill="#FEEAEA"/>
<text x="1514" y="703" class="badge" style="fill:#B42318">硬件测试闭环</text>
<text x="1468" y="762" class="section-title">5. 硬件能力按需被审计 Agent 接管</text>
<text x="1468" y="810" class="section-text">• 摄像头、麦克风、扬声器、串口、继电器、拇指机器人先注册成能力</text>
<text x="1468" y="846" class="section-text">• 审计 Agent 通过租约领取能力，必要时按优先级抢占，而不是直接抢桌面</text>
<text x="1468" y="882" class="section-text">• 多模态测试能形成完整闭环：发声、拍摄、按压、观察、记录、判断</text>
<text x="1468" y="918" class="section-text">• 测试证据被归档，后续可以回放和复盘</text>
<text x="1468" y="950" class="section-text-small">技术：Capability Registry、Lease Manager、Preemption Manager、Test Rig Gateway、Evidence Collector</text>
<g filter="url(#shadow)">
<rect x="698" y="1044" width="610" height="224" rx="30" fill="#FFFFFF"/>
<rect x="694" y="1048" width="10" height="216" rx="5" fill="#0EA5E9"/>
</g>
<rect x="742" y="1078" width="196" height="34" rx="17" fill="#E4F6FD"/>
<text x="786" y="1101" class="badge" style="fill:#0369A1">交付与异常</text>
<text x="742" y="1160" class="section-title">6. 结果汇总、交付、异常恢复</text>
<text x="742" y="1208" class="section-text">• 主 Agent 汇总各线程结果和审计结论，输出阶段成果、风险、下一步建议</text>
<text x="742" y="1244" class="section-text">• 如果 worker 掉线、额度耗尽、主账号失效，系统自动切备用账号、备用主控或 API 容灾</text>
<text x="742" y="1276" class="section-text-small">技术：Event Store、Postgres、对象存储、gptpluscontrol、Standby Controller、API Fallback</text>
<rect x="84" y="1066" width="470" height="170" rx="22" fill="#FFFFFF" opacity="0.9"/>
<text x="118" y="1114" class="section-title" style="font-size:21px;">业务上最核心的变化</text>
<text x="118" y="1152" class="section-text-small">从“一个 Codex 长线程写到底”变成“一个主 Agent 驱动多个短线程协作”。</text>
<text x="118" y="1182" class="section-text-small">用户看到的是一个连续项目流程，系统内部则是拆分执行、持续审计、随时切换。</text>
<rect x="1450" y="1046" width="470" height="174" rx="22" fill="#FFFFFF" opacity="0.9"/>
<text x="1484" y="1094" class="section-title" style="font-size:21px;">适合讨论的产品问题</text>
<text x="1484" y="1132" class="section-text-small">• 手机端项目页长什么样</text>
<text x="1484" y="1160" class="section-text-small">• 主 Agent 什么时候自动审计、什么时候打断用户</text>
<text x="1484" y="1188" class="section-text-small">• 多机线程如何展示协作关系和失败重派</text>
<text x="92" y="1290" class="footer">图文件：/Users/kris/code/Talking/business_flow_mindmap_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/source-material/business_flow_mindmap_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 MiB

213
docs/source-material/business_flow_swimlane_cn.svg Normal file
View File

@@ -0,0 +1,213 @@
<svg width="2200" height="1780" viewBox="0 0 2200 1780" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="180" y1="40" x2="2020" y2="1740" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF4FF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="2200" height="1780" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#1F2937" flood-opacity="0.10"/>
</filter>
<style>
.title { font: 700 38px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17263C; }
.subtitle { font: 500 17px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4F647A; }
.stage { font: 700 20px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17314D; }
.lane { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.laneSub { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #5A6E84; }
.cardTitle { font: 700 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.cardText { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #43576D; }
.tech { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #60748C; }
</style>
</defs>
<rect width="2200" height="1780" rx="36" fill="url(#bg)"/>
<text x="90" y="92" class="title">Codex 多机协作业务流程泳道图</text>
<text x="90" y="128" class="subtitle">把“谁在什么时候做什么”拆开，并把主运维层、开放式运维接入、主 Agent 反向抢救运维层一起纳入业务流程。</text>
<g filter="url(#shadow)">
<rect x="250" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="570" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="890" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="1210" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="1530" y="168" width="300" height="78" rx="20" fill="#FFFFFF"/>
<rect x="1850" y="168" width="260" height="78" rx="20" fill="#FFFFFF"/>
</g>
<text x="346" y="214" class="stage">1. 立项进入</text>
<text x="653" y="214" class="stage">2. 规划与派发</text>
<text x="976" y="214" class="stage">3. 执行与协作</text>
<text x="1290" y="214" class="stage">4. 审计与测试</text>
<text x="1611" y="214" class="stage">5. 汇总与交付</text>
<text x="1913" y="214" class="stage">6. 异常与恢复</text>
<g opacity="0.97">
<rect x="60" y="286" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="486" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="686" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="886" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1086" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1286" width="2060" height="180" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1486" width="2060" height="180" rx="26" fill="#FFFFFF"/>
</g>
<g stroke="#D8E2EF" stroke-width="2">
<line x1="230" y1="286" x2="230" y2="1666"/>
<line x1="550" y1="286" x2="550" y2="1666"/>
<line x1="870" y1="286" x2="870" y2="1666"/>
<line x1="1190" y1="286" x2="1190" y2="1666"/>
<line x1="1510" y1="286" x2="1510" y2="1666"/>
<line x1="1830" y1="286" x2="1830" y2="1666"/>
<line x1="60" y1="486" x2="2120" y2="486"/>
<line x1="60" y1="686" x2="2120" y2="686"/>
<line x1="60" y1="886" x2="2120" y2="886"/>
<line x1="60" y1="1086" x2="2120" y2="1086"/>
<line x1="60" y1="1286" x2="2120" y2="1286"/>
<line x1="60" y1="1486" x2="2120" y2="1486"/>
</g>
<rect x="78" y="316" width="126" height="48" rx="18" fill="#E8F1FF"/>
<text x="104" y="346" class="lane">用户 / 手机 App</text>
<text x="84" y="380" class="laneSub">你看到的产品流程入口</text>
<rect x="78" y="516" width="144" height="48" rx="18" fill="#EAF9EE"/>
<text x="102" y="546" class="lane">主 Agent / 主控</text>
<text x="84" y="580" class="laneSub">决策、拆解、调度、回收</text>
<rect x="78" y="716" width="160" height="48" rx="18" fill="#FFF3DD"/>
<text x="102" y="746" class="lane">Worker 执行层</text>
<text x="84" y="780" class="laneSub">Mac / Windows / Cloud Codex</text>
<rect x="78" y="916" width="134" height="48" rx="18" fill="#F4E8FF"/>
<text x="102" y="946" class="lane">审计层</text>
<text x="84" y="980" class="laneSub">规则 + 专项 Agent</text>
<rect x="78" y="1116" width="162" height="48" rx="18" fill="#FEEAEA"/>
<text x="102" y="1146" class="lane">硬件能力层</text>
<text x="84" y="1180" class="laneSub">Capability Registry / Test Rig</text>
<rect x="78" y="1316" width="188" height="48" rx="18" fill="#EEF2FF"/>
<text x="102" y="1346" class="lane">运维层 / 运维审计层</text>
<text x="84" y="1380" class="laneSub">主运维层 + 开放式接入 + 抢修</text>
<rect x="78" y="1516" width="178" height="48" rx="18" fill="#E4F6FD"/>
<text x="102" y="1546" class="lane">数据 / 容灾层</text>
<text x="84" y="1580" class="laneSub">Event Store / Quota / Standby</text>
<g filter="url(#shadow)">
<rect x="258" y="308" width="284" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1590" y="308" width="224" height="136" rx="20" fill="#FFFFFF"/>
<rect x="582" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="900" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="508" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1862" y="508" width="232" height="136" rx="20" fill="#FFFFFF"/>
<rect x="896" y="708" width="292" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1216" y="708" width="292" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="908" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="908" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="1108" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="1108" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="582" y="1308" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1220" y="1308" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1540" y="1308" width="276" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1862" y="1308" width="232" height="136" rx="20" fill="#FFFFFF"/>
<rect x="896" y="1508" width="292" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1862" y="1508" width="232" height="136" rx="20" fill="#FFFFFF"/>
</g>
<text x="278" y="340" class="cardTitle">发起项目需求</text>
<text x="278" y="368" class="cardText">输入目标、优先级、设备条件、交付标准。</text>
<text x="278" y="392" class="cardText">系统生成项目页，不再只是一串聊天。</text>
<text x="278" y="420" class="tech">技术：Mobile App / Web、Control API、Project View</text>
<text x="1610" y="340" class="cardTitle">查看结果与继续追问</text>
<text x="1610" y="368" class="cardText">看阶段成果、风险、审计结论、运维告警，再继续给主会话下指令。</text>
<text x="1610" y="420" class="tech">技术：项目页、线程页、时间线、通知中心</text>
<text x="602" y="540" class="cardTitle">项目结构化建模</text>
<text x="602" y="568" class="cardText">整理目标、里程碑、风险、待确认项。</text>
<text x="602" y="592" class="cardText">决定使用主 GPT、备用 GPT 还是 API 容灾。</text>
<text x="602" y="620" class="tech">技术：LangGraph、Project Memory、Quota Router</text>
<text x="920" y="540" class="cardTitle">任务拆解与派发</text>
<text x="920" y="568" class="cardText">按平台、算力、上下文体积拆成多个短任务。</text>
<text x="920" y="592" class="cardText">为每个任务挑选节点、账号、branch 与 worktree。</text>
<text x="920" y="620" class="tech">技术：Scheduler、Thread Registry、Git worktree</text>
<text x="1240" y="540" class="cardTitle">监管执行与审计触发</text>
<text x="1240" y="568" class="cardText">盯线程推进，必要时发起审计、重派或人工确认。</text>
<text x="1240" y="620" class="tech">技术：Audit Orchestrator、Rules Watchdog</text>
<text x="1560" y="540" class="cardTitle">汇总与阶段交付</text>
<text x="1560" y="568" class="cardText">归并子线程结果、审计结论、运维状态和下一步建议。</text>
<text x="1560" y="620" class="tech">技术：Decision Ledger、Summary Builder</text>
<text x="1882" y="540" class="cardTitle">主控异常切换</text>
<text x="1882" y="568" class="cardText">主账号或主控异常时切备用主控、备用账号或 API。</text>
<text x="1882" y="620" class="tech">技术：Standby Controller、Failover Policy</text>
<text x="916" y="740" class="cardTitle">多机并行开发</text>
<text x="916" y="768" class="cardText">Mac 做前端和本地联调，Windows 跑 GPU 或硬件桥接，云端跑长任务。</text>
<text x="916" y="820" class="tech">技术：Codex app-server / SDK、Worker Daemon</text>
<text x="1236" y="740" class="cardTitle">跨节点线程协作</text>
<text x="1236" y="768" class="cardText">Mac 线程可请求 Windows 线程做 GPU、硬件或平台验证。</text>
<text x="1236" y="820" class="tech">技术：Inter-Thread Broker、Thread Gateway、ACL</text>
<text x="1240" y="940" class="cardTitle">规则审计先筛异常</text>
<text x="1240" y="968" class="cardText">看超时、失败、断流、额度、反复压缩和卡住状态。</text>
<text x="1240" y="1020" class="tech">技术：Rules Audit Engine、Event Rules</text>
<text x="1560" y="940" class="cardTitle">专项审计与总审计</text>
<text x="1560" y="968" class="cardText">软件、硬件、多模态各自复核，再由总审计给出结论。</text>
<text x="1560" y="1020" class="tech">技术：Software Auditor、Hardware Auditor、Chief Auditor</text>
<text x="1240" y="1140" class="cardTitle">能力申请与租约</text>
<text x="1240" y="1168" class="cardText">审计 Agent 或 worker 先申请摄像头、串口、机器人等能力。</text>
<text x="1240" y="1220" class="tech">技术：Capability Registry、Lease Manager</text>
<text x="1560" y="1140" class="cardTitle">抢占、执行、证据回传</text>
<text x="1560" y="1168" class="cardText">按优先级抢占，执行测试动作，回传视频、音频、日志和检测结果。</text>
<text x="1560" y="1220" class="tech">技术：Preemption Manager、Test Rig Gateway、Evidence Collector</text>
<text x="602" y="1340" class="cardTitle">开放式主运维层接入</text>
<text x="602" y="1368" class="cardText">为其他项目注册运维域、连接器、健康探针和 Runbook Pack。</text>
<text x="602" y="1420" class="tech">技术：Ops Domain、Ops Extension Registry、Connector Runtime</text>
<text x="1240" y="1340" class="cardTitle">动态巡检、跨设备运维与修复授权</text>
<text x="1240" y="1368" class="cardText">高频使用时 5 分钟巡检，空闲时 1 小时；还能跨设备拉日志、重启服务、切账号、跑 Runbook。</text>
<text x="1240" y="1420" class="tech">技术：Ops Policy Engine、Local Ops Agent、Remote Actions、Postgres Queue</text>
<text x="1560" y="1340" class="cardTitle">运维修复复验与汇报</text>
<text x="1560" y="1368" class="cardText">修复后先由运维审计层复验，再把结论和剩余风险报告主会话。</text>
<text x="1560" y="1420" class="tech">技术：Repair Ticket、Verification、Ops Ledger</text>
<text x="1882" y="1340" class="cardTitle">反向抢救运维层</text>
<text x="1882" y="1368" class="cardText">如果运维层自己挂了，主 Agent 切到 rescue 模式，走最小救援通道恢复运维层。</text>
<text x="1882" y="1420" class="tech">技术：ops_rescue_mode、Emergency RPC、Standby Ops</text>
<text x="916" y="1540" class="cardTitle">全量事件镜像</text>
<text x="916" y="1568" class="cardText">线程消息、命令、patch、审批、协作、告警和修复工单都落库。</text>
<text x="916" y="1620" class="tech">技术：Event Store、Postgres、对象存储</text>
<text x="1882" y="1540" class="cardTitle">额度与容灾健康矩阵</text>
<text x="1882" y="1568" class="cardText">监控各 Codex 节点剩余额度、切换记录、Standby 状态与运维健康矩阵。</text>
<text x="1882" y="1620" class="tech">技术：gptpluscontrol、SSE、Capacity Report、Standby Controller</text>
<g stroke-linecap="round" stroke-width="5">
<path d="M542 376H586V546" stroke="#3B82F6"/>
<path d="M858 576H900" stroke="#22C55E"/>
<path d="M1176 576H1220" stroke="#22C55E"/>
<path d="M1496 576H1540" stroke="#22C55E"/>
<path d="M1816 576H1882" stroke="#EF4444"/>
<path d="M1050 644V708" stroke="#F59E0B"/>
<path d="M1360 644V908" stroke="#A855F7"/>
<path d="M1680 1044V1108" stroke="#EF4444"/>
<path d="M1042 844V1508" stroke="#0EA5E9"/>
<path d="M1360 644V1308" stroke="#6D28D9"/>
<path d="M1812 376H1838V1508" stroke="#0EA5E9"/>
<path d="M1496 1376H1540" stroke="#6D28D9"/>
<path d="M1816 1376H1882" stroke="#EF4444"/>
</g>
<text x="90" y="1736" class="footer">图文件：/Users/kris/code/Talking/business_flow_swimlane_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/source-material/business_flow_swimlane_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.5 MiB

843
docs/source-material/capability_registry_and_audit_protocol_cn.md Normal file
View File

@@ -0,0 +1,843 @@
# Capability Registry 与审计 Agent 协议开发规格
适用范围：
- Codex 多机协作系统
- 开放式测试硬件能力接入
- 软件审计、硬件审计、多模态审计、总审计 Agent
目标：
- 定义摄像头、麦克风、扬声器、串口、继电器、拇指机器人等能力如何注册、租约、抢占
- 定义审计 Agent 如何声明需要哪些能力、如何领取任务、如何返回结果
- 为后续数据库表结构、API、消息总线和前端 UI 提供统一协议基础
---
## 1. 总体设计原则
1. 任何真实硬件都不能被 Agent 直接“拿桌面控制权”式使用，必须经过标准化能力层。
2. 所有可调用外设都先注册为 `Capability`，再由租约系统分配使用权。
3. 一个能力可以是独占的，也可以是共享只读的，必须在注册时声明。
4. 抢占必须有优先级、原因、宽限期、证据和审计日志。
5. 审计 Agent 与普通开发线程一样，都只能通过协议调用能力，不能绕过能力层。
6. 视频、音频、大体积流优先在边缘节点做预处理，只上传关键证据和必要片段。
---
## 2. Capability Registry 设计
### 2.1 组件划分
- `Capability Provider`
运行在具体设备附近，负责暴露本机或本测试台的能力。
- `Capability Registry`
运行在云端，保存所有能力的元数据、状态、租约和历史。
- `Lease Manager`
负责发放、续租、释放和过期清理。
- `Preemption Manager`
负责抢占判定、优先级比较、宽限期通知和安全降级。
- `Capability Gateway`
对外提供统一 API，屏蔽底层设备差异。
- `Evidence Collector`
负责把截图、视频片段、串口日志、音频片段等证据统一归档。
### 2.2 核心实体
#### 2.2.1 CapabilityProvider
表示能力提供方，通常是一台 Mac、Windows、Linux 测试台，或一个挂载了外设的专用盒子。
字段：
- `provider_id`
- `node_id`
- `hostname`
- `platform`
- `gateway_version`
- `online_status`
- `last_heartbeat_at`
- `network_zone`
- `owner_type`
- `owner_display_name`
- `auth_mode`
- `labels`
#### 2.2.2 Capability
表示一个可调用能力实例。
字段：
- `capability_id`
- `provider_id`
- `node_id`
- `capability_type`
- `display_name`
- `status`
- `health_status`
- `lease_mode`
值：
- `exclusive`
- `shared_read`
- `shared_stream`
- `preemptible`
- `default_priority`
- `safety_locked`
- `tags`
- `location_label`
- `metadata_json`
- `constraints_json`
- `supported_actions`
- `evidence_modes`
- `created_at`
- `updated_at`
#### 2.2.3 CapabilityLease
表示一个能力租约。
字段：
- `lease_id`
- `capability_id`
- `holder_type`
值：
- `worker_thread`
- `audit_agent`
- `human_operator`
- `system`
- `holder_ref`
例如：
- `mac-01:thread-abc`
- `audit:hardware-auditor-01`
- `project_id`
- `purpose`
- `priority`
- `status`
值：
- `requested`
- `granted`
- `active`
- `renew_pending`
- `preempt_requested`
- `grace_period`
- `released`
- `expired`
- `revoked`
- `failed`
- `requested_at`
- `granted_at`
- `expires_at`
- `grace_until`
- `preempt_reason`
- `evidence_required`
#### 2.2.4 CapabilitySession
表示实际执行过程。
字段：
- `session_id`
- `lease_id`
- `action`
- `started_at`
- `ended_at`
- `status`
- `input_summary`
- `result_summary`
- `artifact_refs`
- `error_message`
#### 2.2.5 CapabilityArtifact
表示证据或产物。
字段：
- `artifact_id`
- `session_id`
- `artifact_type`
值：
- `image`
- `video_clip`
- `audio_clip`
- `serial_log`
- `sensor_dump`
- `ocr_text`
- `detection_json`
- `transcript`
- `storage_uri`
- `content_type`
- `captured_at`
- `duration_ms`
- `checksum`
- `metadata_json`
---
## 3. 能力类型定义
### 3.1 Camera
用途：
- 观察设备动作
- 录制关键帧和短视频
- OCR、目标检测、界面识别
关键元数据：
- `device_path`
- `resolution_options`
- `max_fps`
- `supports_snapshot`
- `supports_clip_recording`
- `supports_audio`
- `supports_ptz`
- `field_of_view`
支持动作：
- `snapshot`
- `record_clip`
- `start_stream`
- `stop_stream`
- `set_ptz`
### 3.2 Microphone
关键元数据：
- `sample_rate_options`
- `channels`
- `noise_profile`
- `supports_vad`
支持动作：
- `record_audio`
- `start_audio_stream`
- `stop_audio_stream`
### 3.3 Speaker
关键元数据：
- `output_device_id`
- `supported_formats`
- `max_volume`
支持动作：
- `play_tts`
- `play_audio_file`
- `set_volume`
- `stop_playback`
### 3.4 SerialPort
关键元数据：
- `port_name`
- `baud_rates`
- `parity_modes`
- `supports_binary`
支持动作：
- `open`
- `read`
- `write`
- `expect_pattern`
- `capture_log`
### 3.5 ThumbRobot
关键元数据：
- `robot_model`
- `axis_count`
- `supported_targets`
例如：
- `touchscreen`
- `physical_button`
- `keyboard`
- `movement_precision_mm`
- `supports_long_press`
- `supports_drag`
支持动作：
- `tap`
- `double_tap`
- `long_press`
- `drag`
- `type_keys`
- `press_hardware_button`
### 3.6 Relay
支持动作：
- `switch_on`
- `switch_off`
- `pulse`
### 3.7 ProgrammablePowerSupply
支持动作：
- `power_on`
- `power_off`
- `set_voltage`
- `set_current_limit`
- `measure_output`
### 3.8 ScreenCapture
支持动作：
- `screenshot`
- `record_screen_clip`
- `ocr`
---
## 4. 注册协议
### 4.1 Provider 注册
`POST /api/v1/capability-providers/register`
请求示例：
```json
{
"provider_id": "provider-winlab-01",
"node_id": "win-gpu-02",
"hostname": "win-gpu-02.local",
"platform": "windows",
"gateway_version": "0.1.0",
"network_zone": "lan",
"labels": ["lab", "gpu", "hardware-test"]
}
```
返回：
```json
{
"provider_id": "provider-winlab-01",
"accepted": true,
"heartbeat_interval_seconds": 10
}
```
### 4.2 Capability 批量注册
`POST /api/v1/capabilities/register`
请求示例：
```json
{
"provider_id": "provider-winlab-01",
"capabilities": [
{
"capability_id": "cam-front-01",
"capability_type": "camera",
"display_name": "前置观察摄像头",
"lease_mode": "exclusive",
"preemptible": true,
"supported_actions": ["snapshot", "record_clip", "start_stream", "stop_stream"],
"evidence_modes": ["image", "video_clip", "ocr_text"],
"metadata_json": {
"resolution_options": ["1920x1080"],
"max_fps": 30
}
},
{
"capability_id": "thumb-robot-01",
"capability_type": "thumb_robot",
"display_name": "拇指机器人 1 号",
"lease_mode": "exclusive",
"preemptible": false,
"supported_actions": ["tap", "long_press", "drag"]
}
]
}
```
### 4.3 Heartbeat 与状态更新
`POST /api/v1/capabilities/heartbeat`
用途：
- 更新 provider 在线状态
- 更新能力健康状态
- 上报正在执行的租约
- 上报本地错误或故障
---
## 5. 租约设计
### 5.1 申请租约
`POST /api/v1/capability-leases/request`
请求字段：
- `capability_id` 或 `capability_selector`
- `holder_type`
- `holder_ref`
- `project_id`
- `purpose`
- `priority`
- `requested_duration_seconds`
- `evidence_required`
- `preempt_if_needed`
请求示例：
```json
{
"capability_id": "cam-front-01",
"holder_type": "audit_agent",
"holder_ref": "audit:multimodal-auditor-01",
"project_id": "proj_device_assistant",
"purpose": "验证设备 LED 与屏幕切换是否符合交互脚本",
"priority": 75,
"requested_duration_seconds": 120,
"evidence_required": true,
"preempt_if_needed": true
}
```
### 5.2 续租
`POST /api/v1/capability-leases/{lease_id}/renew`
### 5.3 释放
`POST /api/v1/capability-leases/{lease_id}/release`
### 5.4 过期清理
Lease Manager 负责：
- 定时回收过期租约
- 清理失联 provider 持有的会话
- 把证据未上传完成的 session 标记为 `incomplete_evidence`
---
## 6. 抢占设计
### 6.1 优先级建议
- `100`：安全/紧急停机
- `90`：人工操作员
- `80`：总审计 Agent
- `75`：硬件审计 Agent
- `70`：多模态审计 Agent
- `65`：软件审计 Agent
- `50`：普通 worker 线程
- `20`：后台采样/非关键任务
### 6.2 抢占条件
只有以下条件全部满足时允许抢占：
1. 目标能力 `preemptible=true`
2. 当前租约不是 `safety_locked`
3. 新租约优先级高于当前租约
4. 抢占原因在白名单中
5. 当前 holder 不处于“不可中断动作”窗口
### 6.3 抢占流程
1. 新请求进入 Lease Manager
2. Preemption Manager 评估是否允许抢占
3. 向当前持有者发送 `preempt_requested`
4. 进入 `grace_period`
5. 到期后自动释放或强制收回
6. 新租约转为 `granted`
7. 全过程写事件和审计日志
### 6.4 不可中断动作
以下动作默认不可中断：
- 机器人正在按压或拖拽
- 可编程电源处于切换瞬间
- 固件烧录
- 继电器脉冲动作未完成
---
## 7. Capability 事件流
`GET /api/v1/capability-events/stream`
事件类型：
- `provider_registered`
- `capability_registered`
- `capability_health_changed`
- `lease_requested`
- `lease_granted`
- `lease_renewed`
- `lease_release_requested`
- `lease_released`
- `lease_expired`
- `lease_preempt_requested`
- `lease_preempted`
- `session_started`
- `session_completed`
- `session_failed`
- `artifact_uploaded`
---
## 8. 审计 Agent 任务协议
### 8.1 通用任务请求格式
所有审计任务统一使用 `AuditTaskRequest`。
字段：
- `protocol_version`
- `audit_request_id`
- `project_id`
- `project_name`
- `task_id`
- `source_thread_ref`
- `trigger`
值：
- `milestone`
- `merge_candidate`
- `failure_escalation`
- `scheduled_check`
- `human_request`
- `audit_type`
值：
- `software`
- `hardware`
- `multimodal`
- `chief`
- `priority`
- `objective`
- `system_context_summary`
- `acceptance_criteria`
- `risk_focus`
- `evidence_refs`
- `artifact_refs`
- `capability_requirements`
- `time_budget_seconds`
- `response_mode`
- `created_at`
- `metadata_json`
请求示例：
```json
{
"protocol_version": "1.0",
"audit_request_id": "auditreq_001",
"project_id": "proj_device_assistant",
"task_id": "task_led_validation",
"source_thread_ref": "mac-01:thread-ui-22",
"trigger": "milestone",
"audit_type": "multimodal",
"priority": 70,
"objective": "验证设备被唤醒后，屏幕、LED、语音播报与交互脚本是否一致",
"system_context_summary": "设备端已刷入固件 v0.9.2，等待做端到端唤醒测试",
"acceptance_criteria": [
"LED 在 2 秒内变蓝",
"屏幕切换到 listening 状态",
"扬声器播报欢迎语",
"摄像头观测到机械动作完成"
],
"evidence_refs": [],
"artifact_refs": [],
"capability_requirements": [
{ "capability_type": "camera", "mode": "exclusive" },
{ "capability_type": "speaker", "mode": "exclusive" },
{ "capability_type": "microphone", "mode": "exclusive" },
{ "capability_type": "thumb_robot", "mode": "exclusive" }
],
"time_budget_seconds": 300,
"response_mode": "structured_json"
}
```
### 8.2 通用任务响应格式
所有审计任务统一使用 `AuditTaskResult`。
字段：
- `audit_request_id`
- `audit_type`
- `status`
值：
- `completed`
- `failed`
- `needs_retry`
- `needs_human_review`
- `decision`
值：
- `pass`
- `fail`
- `warning`
- `inconclusive`
- `confidence`
- `summary`
- `findings`
- `required_actions`
- `used_capabilities`
- `artifact_refs`
- `timeline`
- `duration_ms`
- `completed_at`
---
## 9. 软件审计 Agent 协议
### 9.1 输入
在通用格式上追加：
- `repo_ref`
- `base_commit`
- `head_commit`
- `changed_files`
- `diff_refs`
- `build_results`
- `test_results`
- `coverage_summary`
- `runtime_logs`
- `api_contract_refs`
- `release_notes_draft`
### 9.2 输出
- `regression_risk_level`
- `coverage_gap_summary`
- `release_blockers`
- `contract_breaking_changes`
- `log_anomalies`
- `recommended_owner`
### 9.3 findings 格式
每条 finding 至少包含：
- `finding_id`
- `severity`
值：
- `critical`
- `high`
- `medium`
- `low`
- `title`
- `description`
- `evidence_ref_ids`
- `suggested_fix`
---
## 10. 硬件审计 Agent 协议
### 10.1 输入
在通用格式上追加：
- `device_topology`
- `firmware_version`
- `hardware_revision`
- `serial_log_refs`
- `sensor_snapshots`
- `power_state`
- `ota_result`
- `expected_state_machine`
- `hardware_test_steps`
- `required_capabilities`
### 10.2 输出
- `device_state_assessment`
- `firmware_mismatch`
- `sensor_anomalies`
- `serial_log_findings`
- `hardware_blockers`
- `recovery_actions`
### 10.3 典型结论
- 固件版本正确但状态机卡死
- 串口日志与预期不一致
- 传感器波动超阈值
- OTA 成功但设备未进入预期模式
---
## 11. 多模态审计 Agent 协议
### 11.1 输入
在通用格式上追加：
- `frame_refs`
- `video_clip_refs`
- `audio_clip_refs`
- `screen_capture_refs`
- `ocr_text_refs`
- `detector_output_refs`
- `interaction_script`
- `expected_visual_states`
- `expected_audio_states`
- `expected_actuator_states`
### 11.2 输出
- `observed_timeline`
- `visual_mismatches`
- `audio_mismatches`
- `interaction_failures`
- `perceptual_verdict`
- `needs_human_review_reason`
### 11.3 典型场景
- 摄像头看设备灯光变化是否正确
- 通过视频确认机械动作是否完成
- 通过音频片段判断 TTS 是否播报了正确内容
- 通过屏幕截图和 OCR 判断 UI 状态是否正确切换
---
## 12. 总审计 Agent 协议
### 12.1 输入
总审计 Agent 不直接看全部原始数据，优先读取：
- `software_audit_result`
- `hardware_audit_result`
- `multimodal_audit_result`
- `rules_audit_summary`
- `human_notes`
### 12.2 输出
- `final_decision`
值：
- `approved`
- `rejected`
- `needs_human_review`
- `partial_pass`
- `overall_risk_level`
- `blocking_reasons`
- `recommended_next_step`
- `handoff_target`
---
## 13. 能力需求声明格式
用于审计 Agent 和 worker 线程声明需要哪些外设。
字段：
- `capability_type`
- `mode`
值：
- `exclusive`
- `shared_read`
- `min_duration_seconds`
- `preferred_node_tags`
- `fallback_allowed`
- `preempt_if_needed`
- `purpose`
示例：
```json
[
{
"capability_type": "camera",
"mode": "exclusive",
"min_duration_seconds": 90,
"preferred_node_tags": ["lab", "device-station-a"],
"fallback_allowed": true,
"preempt_if_needed": true,
"purpose": "记录设备启动后 30 秒内的状态变化"
}
]
```
---
## 14. 最小数据库表建议
建议至少有这些表：
- `capability_providers`
- `capabilities`
- `capability_health_snapshots`
- `capability_leases`
- `capability_sessions`
- `capability_artifacts`
- `audit_requests`
- `audit_results`
- `audit_findings`
- `thread_registry`
- `inter_thread_messages`
---
## 15. MVP 实现建议
### V1
- 先做 `camera`、`serial_port`、`thumb_robot`
- 先支持：
- 注册
- 独占租约
- 基础抢占
- session 留痕
- artifact 归档
- 先做：
- 软件审计 Agent
- 硬件审计 Agent
- 多模态审计 Agent
- 总审计 Agent
### V2
- 增加 `microphone`、`speaker`、`screen_capture`
- 增加共享只读租约
- 增加跨设备联合测试流程
### V3
- 增加策略化预调度
- 增加能力热迁移
- 增加自动抢占编排和更细粒度安全策略
---
## 16. 一句话总结
`Capability Registry` 解决“哪些硬件能被谁调用”的问题，
`Lease / Preemption` 解决“什么时候谁能占用硬件”的问题，
`Audit Agent Protocol` 解决“审计任务如何标准化下发和回收”的问题。
这三者合在一起，才能让你的审计 Agent 真正做到可扩展、可监管、可复盘地接管真实世界的测试硬件。

280
docs/source-material/china_ui_reference_apps_cn.md Normal file
View File

@@ -0,0 +1,280 @@
# 中国区 UI 参考 App 清单（面向 Codex 多机协作系统）
更新时间：`2026-03-25`
这份清单不是在找“和我们一模一样”的产品，而是在中国区里，尽可能多地找出最接近这套系统的 UI 参考对象。
我们的目标页面包括：
- 单主 Agent 对话入口
- 项目列表 / 项目详情
- 线程详情 / 实时进度
- 设备列表 / 设备状态 / 远程控制
- 运维中心 / 告警中心 / 修复工单
- 审计中心 / 硬件测试中心
- 账号额度与主备状态提示
所以我把参考对象拆成 6 类：
- `A. 协同与单入口`
- `B. 研发管理与项目流转`
- `C. 远程控制与设备列表`
- `D. 运维监控与告警`
- `E. 设备 / 场景 / 多模态控制`
- `F. AI 助手与聊天入口`
---
## 1. 最值得优先看的 12 个
如果时间有限，我建议先看这 12 个：
1. 飞书
2. 钉钉
3. 企业微信
4. 向日葵
5. ToDesk
6. 腾讯云助手
7. 阿里云 App
8. 观测云
9. PingCode
10. TAPD
11. 米家
12. 腾讯元宝
原因：
- 这 12 个基本覆盖了你这套产品最核心的 UI 组合：
- 单入口聊天
- 项目和任务推进
- 设备列表与远控
- 运维监控与告警
- 场景化设备控制
- AI 助手入口
---
## 2. 我们这套产品最适合借鉴的 UI 组合
不是照抄某一个 App，而是建议组合借鉴：
### 2.1 首页壳层
- 借鉴：`飞书 + 企业微信 + 钉钉`
- 适合借的：
- 底部导航结构
- 消息 / 工作台 / 审批 / 我的 四段式信息架构
- 聊天页和工作页之间的轻切换
### 2.2 设备中心
- 借鉴：`向日葵 + ToDesk + 米家`
- 适合借的：
- 设备卡片
- 在线 / 离线 / 忙碌状态点
- 最近使用设备置顶
- 场景分组和快捷操作
### 2.3 项目与线程中心
- 借鉴：`PingCode + TAPD + 云效 + 飞书项目`
- 适合借的：
- 项目列表到项目详情的层级
- 里程碑、任务、线程之间的关系
- 卡片化状态流转
- 评论 / 动态 / 审批汇总
### 2.4 运维和告警中心
- 借鉴：`腾讯云助手 + 阿里云 App + 观测云 + 监控宝`
- 适合借的：
- 首页总览 + 告警列表 + 指标趋势
- 卡片式故障摘要
- 告警分级
- 处理动作入口前置
### 2.5 硬件测试与多模态页
- 借鉴：`米家 + 涂鸦 + 萤石云视频`
- 适合借的：
- 场景分组
- 视频预览卡片
- 设备共享与权限
- 自动化规则入口
### 2.6 AI 交互壳层
- 借鉴：`腾讯元宝 + 通义 + 豆包 + Kimi`
- 适合借的：
- 单输入框主入口
- 工具 / 助手 / 历史记录次级入口
- 文件、图片、语音等多模态输入组织
---
## 3. 详细参考清单
## A. 协同与单入口
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 飞书 | 最接近“消息 + 项目 + 文档 + 审批 + AI”的一体化入口 | 底部导航、统一搜索、项目入口、轻量化移动端工作台 | [官网总览](https://www.feishu.cn/content/article/7598492868155608024) / [飞书项目移动端](https://www.feishu.cn/content/rych8h5r) |
| 钉钉 | 适合看“工作台型”首页壳层 | 首页工作台、项目入口、任务与审批并存、AI 入口前置 | [钉钉官网](https://www.dingtalk.com/) / [钉钉项目](https://page.dingtalk.com/wow/dingtalk/act/project) |
| 企业微信 | 适合看“消息优先、工具次级”的企业协同入口 | 聊天入口、工作台、机器人入口、企业通知风格 | [App Store](https://apps.apple.com/cn/app/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1/id1189898970) |
| Worktile | 更适合看移动端任务、OKR、审批在一个壳里的组织方式 | 项目列表、任务卡、目标页、表单/审批混排 | [官网](https://worktile.com/) |
| Teambition | 适合看项目协作的轻量信息层级 | 清爽任务视图、轻项目结构、卡片化任务关系 | [官网](https://www.teambition.com/) |
| Clarity Design（Teambition） | 不是 App，但很值得参考其交互与组件语言 | 组件层次、信息密度控制、设计系统命名 | [设计系统](https://design.teambition.com/) |
## B. 研发管理与项目流转
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| PingCode | 最贴近“研发管理 + AI + 流程” | 项目首页、需求/缺陷/版本分层、智能化研发入口 | [官网](https://pingcode.com/) / [App 发布](https://blog.pingcode.com/v1-0-0-app-release/) / [v6.0](https://blog.pingcode.com/pingcode-v6/) |
| TAPD | 适合参考研发流转和多工作流支撑 | 工作项状态、迭代视图、自动化任务引擎感 | [官网](https://www.tapd.cn/) |
| 腾讯云 CODING | 适合参考 DevOps 工具链首页和项目切换结构 | 项目列表、代码/需求/流水线入口并列、工具链导航 | [官网](https://cloud.tencent.cn/product/coding) |
| 云效 | 适合参考“云上研发管理”的一体化信息组织 | 产品级导航、环境管理、项目到部署的串联 | [产品概述](https://help.aliyun.com/zh/yunxiao/product-overview/) |
| 禅道 | 适合参考国产研发管理工具的移动端取舍 | 项目集、产品、项目、聊天卡片跳转 | [移动端与桌面端](https://www.zentao.net/download/zentao-client-80038.mhtml) |
| 飞书项目 | 适合看“业务需求 -> 项目执行”的联动页 | 移动端项目入口、需求到项目跳转、流程视图 | [案例](https://project.feishu.cn/home/customer/lisen) / [移动端使用指南](https://www.feishu.cn/content/rych8h5r) |
| 腾讯云 Cloud Studio | 不是移动主 App，但适合看“云工作区 / 开发环境”的管理方式 | 工作区卡片、环境状态、模板入口 | [官网](https://cloud.tencent.com.cn/product/cloudstudio) |
## C. 远程控制与设备列表
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 向日葵 | 最贴近“跨平台远程设备控制” | 设备列表、在线状态、远控入口、设备分组 | [官网](https://oraypc.com.cn/) / [产品页](https://sunlogin-orayc.com/) |
| ToDesk | 适合看远程控制的移动端快速入口 | 最近设备、连接状态、快捷控制按钮、跨平台切换 | [官网](https://www.todesk.com/) |
| 贝锐蒲公英管理 App | 适合看“设备网络 / 组网 / 节点管理” | 节点列表、组网状态、硬件管理入口 | [贝锐官网](https://www.oray.com/) / [蒲公英管理 App](https://sunlogin.oray.com/news/34353.html) |
## D. 运维监控与告警
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 腾讯云助手 | 很适合看移动端云资源管理 | 告警页、资源列表、历史趋势、小屏指标卡片 | [官网](https://cloud.tencent.com/product/tca) |
| 阿里云 App | 很适合看“轻量移动控制台” | 首页总览、实例详情、监控与告警入口 | [阿里云 App](https://help.aliyun.com/document_detail/52854.html) / [RDS 监控示例](https://help.aliyun.com/document_detail/2863833.html) |
| 观测云 | 适合看现代可观测性产品的信息结构 | 总览面板、日志/链路/告警切换、AI 故障分析入口 | [官网](https://www.guance.com/) |
| 监控宝 | 适合看移动告警和性能趋势页 | 告警列表、性能图表、网站/API/服务器多类型监控 | [官网](https://www.jiankongbao.com/about.html) / [App 页](https://www.jiankongbao.com/new_app) |
| 堡塔 APP | 适合看“手机运维面板” | 服务器卡片、文件管理、快捷运维动作 | [官网](https://www.bt.cn/new/product/btapp.html) |
## E. 设备 / 场景 / 多模态控制
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 米家 | 非常适合参考“设备中心 + 场景中心 + 全屋看板” | 场景页、全屋动态看板、设备卡片分组、自动化入口 | [App Store](https://apps.apple.com/cn/app/%E7%B1%B3%E5%AE%B6/id957323480) |
| 涂鸦 OEM App | 适合看“多品牌设备统一控制”的模板化结构 | App 模板、设备主页、服务与运营入口并存 | [OEM App](https://www.tuya.com/cn/platform/appdev/oemapp) / [官网](https://www.tuya.com/cn/) |
| Powered by Tuya | 适合看“一个 App 统一控制多品牌设备”的生态逻辑 | 多设备兼容、统一入口、品牌层和设备层的分离 | [Powered by Tuya](https://www.tuya.com/cn/partners/powered-by-tuya) |
| 萤石云视频 | 很适合看摄像头 / 视频流 / 消息中心 UI | 实时视频卡片、录像回放、设备消息、家庭共享 | [App Store](https://apps.apple.com/cn/app/%E8%90%A4%E7%9F%B3%E4%BA%91%E8%A7%86%E9%A2%91/id571195405) |
## F. AI 助手与聊天入口
| 产品 | 为什么适合参考 | 最值得借的 UI 点 | 来源 |
|---|---|---|---|
| 腾讯元宝 | 适合看中国区“AI 助手主入口”外形 | 单输入框、历史入口、轻工具栏、下载入口前置 | [官网](https://yuanbao.tencent.com/AI) |
| 通义 | 适合看“AI 助手 + 文档阅读 + 代码模式”的壳层 | 助手页、历史记录入口、文件对话 | [官网](https://tongyi.aliyun.com/) / [历史记录说明](https://tongyi.aliyun.com/blog/192631944) |
| 豆包 | 适合看“智能体平台化”的主入口趋势 | 智能体入口、语音 / 文档 / 多模态能力聚合 | [App Store](https://apps.apple.com/cn/app/%E8%B1%86%E5%8C%85-%E5%AD%97%E8%8A%82%E8%B7%B3%E5%8A%A8%E6%97%97%E4%B8%8Bai%E5%8A%A9%E6%89%8B/id6459478672?platform=ipad) / [豆包语音模型说明](https://research.doubao.com/blog/doubao-realtime-voice-model-is-available-upon-release-high-eq-and-iq) |
| Kimi | 适合看简洁型 AI 聊天工具壳层 | 极简主会话、低干扰历史与附件交互 | [App Store](https://apps.apple.com/cn/app/kimi/id6474233312) |
---
## 4. 针对我们产品，建议直接借鉴的页面级组合
## 4.1 手机首页
建议参考：
- 飞书
- 企业微信
- 钉钉
建议做法：
- 底部 `4 tab`
- `会话`
- `项目`
- `设备`
- `运维`
- 顶部小胶囊显示：
- `主 GPT`
- `备用 GPT`
- `API 容灾`
## 4.2 项目页
建议参考：
- PingCode
- TAPD
- 飞书项目
建议做法：
- 顶部是项目状态和里程碑
- 中部是任务列表 / 线程列表
- 底部是动态、审计、修复记录
## 4.3 设备页
建议参考：
- 向日葵
- ToDesk
- 米家
建议做法：
- 用卡片列出所有设备
- 每张卡片有：
- 在线状态
- 账号额度
- 当前线程数
- 可用能力
- 一键进入
## 4.4 运维页
建议参考：
- 腾讯云助手
- 阿里云 App
- 观测云
- 监控宝
建议做法：
- 先总览，再告警，再工单
- 每条告警都能直接进入修复或回放
## 4.5 审计与硬件页
建议参考：
- 米家
- 涂鸦
- 萤石云视频
建议做法：
- 摄像头预览卡片
- Test Rig 能力卡片
- 审计任务列表
- 当前租约状态
---
## 5. 我对 UI 方向的最终建议
如果你让我用一句话定调：
这套产品不要做成“一个聊天机器人 App”，而要做成：
`飞书 / 企业微信式的壳层`
`+ PingCode / TAPD 式的项目推进`
`+ 向日葵 / ToDesk / 米家式的设备中心`
`+ 腾讯云助手 / 观测云式的运维中心`
也就是说：
- 外层像企业协作 App
- 中层像研发管理 App
- 底层像设备 / 运维控制台
这会比单纯模仿任何一个 AI App 更适合你。

2113
docs/source-material/codex_multi_machine_architecture_cn.html Normal file
View File

File diff suppressed because it is too large Load Diff

132
docs/source-material/current_flow_mindmap_cn.svg Normal file
View File

@@ -0,0 +1,132 @@
<svg width="1800" height="1220" viewBox="0 0 1800 1220" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="200" y1="80" x2="1600" y2="1140" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EDF4FF"/>
</linearGradient>
<linearGradient id="centerFill" x1="730" y1="465" x2="1070" y2="755" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F62FE"/>
<stop offset="1" stop-color="#4A8DFF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="1800" height="1220" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="18" stdDeviation="20" flood-color="#1F2937" flood-opacity="0.12"/>
</filter>
<style>
.title { font: 700 34px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #152033; }
.subtitle { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4D6178; }
.section-title { font: 700 24px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.section-text { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #3D5066; }
.section-text-small { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #4C6075; }
.center-title { font: 700 30px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: white; }
.center-text { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: rgba(255,255,255,0.92); }
.badge { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #5E7289; }
</style>
</defs>
<rect x="0" y="0" width="1800" height="1220" rx="36" fill="url(#bg)"/>
<text x="94" y="92" class="title">Codex 多机协作当前流程思维导图</text>
<text x="94" y="126" class="subtitle">围绕手机单入口、主控调度、多机 Codex、专项审计、硬件能力接管与容灾恢复的当前整体流程</text>
<g filter="url(#shadow)">
<rect x="690" y="450" width="420" height="300" rx="34" fill="url(#centerFill)"/>
</g>
<rect x="728" y="490" width="344" height="36" rx="18" fill="rgba(255,255,255,0.18)"/>
<text x="790" y="515" class="badge">当前主流程中心</text>
<text x="779" y="580" class="center-title">一个主 Agent</text>
<text x="758" y="622" class="center-title">统一调度全局</text>
<text x="776" y="665" class="center-text">手机端只和一个主会话对话</text>
<text x="742" y="694" class="center-text">外部记忆保存项目真相，不让单线程越聊越钝</text>
<path d="M690 566C594 534 484 490 390 425" stroke="#3B82F6" stroke-width="6" stroke-linecap="round"/>
<path d="M695 633C579 646 471 665 392 728" stroke="#22C55E" stroke-width="6" stroke-linecap="round"/>
<path d="M895 450C891 332 892 252 892 186" stroke="#F59E0B" stroke-width="6" stroke-linecap="round"/>
<path d="M1108 563C1229 533 1340 492 1410 426" stroke="#A855F7" stroke-width="6" stroke-linecap="round"/>
<path d="M1108 640C1230 651 1348 681 1410 744" stroke="#EF4444" stroke-width="6" stroke-linecap="round"/>
<path d="M900 752C902 852 905 918 905 1002" stroke="#0EA5E9" stroke-width="6" stroke-linecap="round"/>
<g filter="url(#shadow)">
<rect x="96" y="244" width="462" height="300" rx="28" fill="#FFFFFF"/>
<rect x="92" y="246" width="10" height="294" rx="5" fill="#3B82F6"/>
</g>
<rect x="132" y="274" width="124" height="32" rx="16" fill="#E8F1FF"/>
<text x="165" y="296" class="badge">用户入口</text>
<text x="132" y="346" class="section-title">1. 手机端 / Web 单入口</text>
<text x="132" y="388" class="section-text">• 只保留一个主对话窗口，不让用户自己分配线程</text>
<text x="132" y="420" class="section-text">• 项目列表可查看每个 Codex 线程的聊天、命令、补丁、状态</text>
<text x="132" y="452" class="section-text">• 顶部小胶囊显示当前主控身份：主 GPT / 备用 GPT / API 容灾</text>
<text x="132" y="484" class="section-text">• 实时显示各绑定 Codex 客户端剩余额度和切换情况</text>
<g filter="url(#shadow)">
<rect x="92" y="616" width="488" height="302" rx="28" fill="#FFFFFF"/>
<rect x="88" y="620" width="10" height="294" rx="5" fill="#22C55E"/>
</g>
<rect x="130" y="646" width="154" height="32" rx="16" fill="#EAF9EE"/>
<text x="168" y="668" class="badge" style="fill:#14803D">主控编排</text>
<text x="130" y="716" class="section-title">2. Master Agent Runtime</text>
<text x="130" y="758" class="section-text">• LangGraph 负责任务拆解、节点选择、上下文裁剪、阶段推进</text>
<text x="130" y="790" class="section-text">• Project Memory 保存目标、约束、摘要、决策和未决项</text>
<text x="130" y="822" class="section-text">• Scheduler 按平台能力、额度、负载和项目优先级派发任务</text>
<text x="130" y="854" class="section-text">• Inter-Thread Broker 监管 Mac / Windows / 云线程的对话</text>
<g filter="url(#shadow)">
<rect x="648" y="78" width="510" height="288" rx="28" fill="#FFFFFF"/>
<rect x="644" y="82" width="10" height="280" rx="5" fill="#F59E0B"/>
</g>
<rect x="686" y="108" width="164" height="32" rx="16" fill="#FFF4DA"/>
<text x="725" y="130" class="badge" style="fill:#A16207">执行层</text>
<text x="686" y="178" class="section-title">3. 多机 Codex Worker 执行</text>
<text x="686" y="220" class="section-text">• Mac Worker：前端、Xcode、轻量开发、本地联调</text>
<text x="686" y="252" class="section-text">• Windows Worker（WSL2）：GPU、CUDA、Windows 工具链、硬件桥接</text>
<text x="686" y="284" class="section-text">• Cloud Worker：CI、批处理、长任务、后台服务</text>
<text x="686" y="316" class="section-text">• 每个节点都运行自己的 Codex app-server / SDK 和独立账号</text>
<g filter="url(#shadow)">
<rect x="1236" y="244" width="474" height="300" rx="28" fill="#FFFFFF"/>
<rect x="1704" y="246" width="10" height="294" rx="5" fill="#A855F7"/>
</g>
<rect x="1272" y="274" width="160" height="32" rx="16" fill="#F4E8FF"/>
<text x="1307" y="296" class="badge" style="fill:#7E22CE">审计层</text>
<text x="1272" y="346" class="section-title">4. 混合审计与专项 Agent</text>
<text x="1272" y="388" class="section-text">• Rules Audit Engine：先看超时、失败、断流、额度、队列积压</text>
<text x="1272" y="420" class="section-text">• 软件审计 Agent：看代码、测试、接口契约、发布风险</text>
<text x="1272" y="452" class="section-text">• 硬件审计 Agent：看固件、串口、传感器、设备状态机</text>
<text x="1272" y="484" class="section-text">• 多模态审计 Agent：看视频、截图、音频、拟人交互效果</text>
<g filter="url(#shadow)">
<rect x="1228" y="620" width="492" height="312" rx="28" fill="#FFFFFF"/>
<rect x="1724" y="624" width="10" height="304" rx="5" fill="#EF4444"/>
</g>
<rect x="1268" y="650" width="184" height="32" rx="16" fill="#FEEAEA"/>
<text x="1304" y="672" class="badge" style="fill:#B42318">开放硬件能力</text>
<text x="1268" y="722" class="section-title">5. Capability Registry + Test Rig</text>
<text x="1268" y="764" class="section-text">• 摄像头、麦克风、扬声器、串口、继电器、拇指机器人统一注册</text>
<text x="1268" y="796" class="section-text">• Lease Manager 管租约，Preemption Manager 管抢占和宽限期</text>
<text x="1268" y="828" class="section-text">• 审计 Agent 通过标准能力接口接管硬件，不直接抢系统桌面</text>
<text x="1268" y="860" class="section-text">• Evidence Collector 归档视频片段、截图、音频、日志与检测结果</text>
<g filter="url(#shadow)">
<rect x="606" y="956" width="594" height="218" rx="28" fill="#FFFFFF"/>
<rect x="602" y="960" width="10" height="210" rx="5" fill="#0EA5E9"/>
</g>
<rect x="646" y="986" width="192" height="32" rx="16" fill="#E4F6FD"/>
<text x="683" y="1008" class="badge" style="fill:#0369A1">数据与容灾</text>
<text x="646" y="1058" class="section-title">6. Event Store / Quota / Standby</text>
<text x="646" y="1100" class="section-text">• Event Store 镜像 thread、命令、patch、审批、协作与告警</text>
<text x="646" y="1132" class="section-text">• gptpluscontrol 提供剩余额度、账号切换、实时监控和预警</text>
<text x="646" y="1164" class="section-text">• Standby Controller 和外部状态存储保证主控故障后仍可接管</text>
<rect x="104" y="1068" width="364" height="96" rx="20" fill="#FFFFFF" opacity="0.82"/>
<text x="132" y="1106" class="section-title" style="font-size:20px;">当前主流程一句话</text>
<text x="132" y="1138" class="section-text-small">用户只对一个主 Agent 说话，主 Agent 依靠外部记忆和事件流</text>
<text x="132" y="1162" class="section-text-small">去调度多台机器上的短上下文 Codex 线程，并在审计与容灾下持续推进。</text>
<rect x="1320" y="1012" width="406" height="136" rx="20" fill="#FFFFFF" opacity="0.9"/>
<text x="1348" y="1050" class="section-title" style="font-size:20px;">开发顺序建议</text>
<text x="1348" y="1082" class="section-text-small">1. 先打通 Worker + Event Store + Quota Monitor</text>
<text x="1348" y="1108" class="section-text-small">2. 再接 Inter-Thread Broker 和审计任务协议</text>
<text x="1348" y="1134" class="section-text-small">3. 最后接 Capability Registry 与硬件测试台</text>
<text x="94" y="1196" class="footer">图文件：/Users/kris/code/Talking/current_flow_mindmap_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/source-material/current_flow_mindmap_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.1 MiB

1374
docs/source-material/detailed_technical_stack_cn.md Normal file
View File

File diff suppressed because it is too large Load Diff

764
docs/source-material/development_subtasks_and_delivery_plan_cn.md Normal file
View File

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

93
docs/source-material/ha_modes_cn.svg Normal file
View File

@@ -0,0 +1,93 @@
<svg width="1600" height="980" viewBox="0 0 1600 980" xmlns="http://www.w3.org/2000/svg">
<defs>
<style>
.bg { fill: #f7f8fc; }
.title { font: 700 34px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #1d2736; }
.sub { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #526070; }
.panel { fill: #ffffff; stroke: #d8deea; stroke-width: 2; rx: 24; ry: 24; }
.panelTitle { font: 700 24px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #17212e; }
.panelSub { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #5a6878; }
.boxBlue { fill: #eef5ff; stroke: #8cb5ff; stroke-width: 2; rx: 18; ry: 18; }
.boxGreen { fill: #eefaf2; stroke: #8dcca1; stroke-width: 2; rx: 18; ry: 18; }
.boxOrange { fill: #fff6ea; stroke: #f0b56a; stroke-width: 2; rx: 18; ry: 18; }
.boxGray { fill: #f5f7fb; stroke: #cfd8e6; stroke-width: 2; rx: 18; ry: 18; }
.boxTitle { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #1e2a39; }
.boxText { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #556273; }
.tech { font: 600 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #3d6fd6; }
.foot { font: 600 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif; fill: #7a8796; }
.arrow { stroke: #6f7f95; stroke-width: 3; fill: none; marker-end: url(#arrowhead); }
</style>
<marker id="arrowhead" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
<polygon points="0 0, 10 4, 0 8" fill="#6f7f95"/>
</marker>
</defs>
<rect class="bg" x="0" y="0" width="1600" height="980"/>
<text class="title" x="70" y="70">容灾保活两种部署模式</text>
<text class="sub" x="70" y="104">系统同时支持“单云 + 单 Mac 备用控制器”和“双云热备 / 温备”，按成本与可用性选择。</text>
<rect class="panel" x="60" y="140" width="710" height="760"/>
<text class="panelTitle" x="90" y="190">模式 A：单云 + 单 Mac 备用控制器</text>
<text class="panelSub" x="90" y="220">更省云成本，适合已有常开 Mac 的现场环境。</text>
<rect class="boxBlue" x="100" y="270" width="250" height="150"/>
<text class="boxTitle" x="126" y="305">Cloud A（主用）</text>
<text class="boxText" x="126" y="338">控制面单体</text>
<text class="boxText" x="126" y="364">PostgreSQL 主库 + pgvector</text>
<text class="boxText" x="126" y="390">HTTP + SSE</text>
<rect class="boxGreen" x="420" y="270" width="290" height="180"/>
<text class="boxTitle" x="446" y="305">Standby Mac（备用）</text>
<text class="boxText" x="446" y="338">备用控制面轻实例</text>
<text class="boxText" x="446" y="364">PostgreSQL 备库 / 快照恢复实例</text>
<text class="boxText" x="446" y="390">Standby Controller</text>
<text class="boxText" x="446" y="416">Ops Rescue Gateway</text>
<path class="arrow" d="M350 345 C385 345, 390 345, 420 345"/>
<rect class="boxOrange" x="100" y="500" width="610" height="160"/>
<text class="boxTitle" x="126" y="536">必要前提</text>
<text class="boxText" x="126" y="570">1. 备用 Mac 必须常开，并保留可用磁盘做备份与恢复。</text>
<text class="boxText" x="126" y="598">2. 手机 App 必须支持主 / 备 endpoint 列表切换。</text>
<text class="boxText" x="126" y="626">3. 必须有一条不依赖主云的可达通路：同局域网、Tailscale/WireGuard 或长期反向隧道。</text>
<rect class="boxGray" x="100" y="700" width="610" height="150"/>
<text class="boxTitle" x="126" y="736">优点与边界</text>
<text class="boxText" x="126" y="770">优点：更省钱，本地接管更快，适合已有常开 Mac mini 的环境。</text>
<text class="boxText" x="126" y="798">边界：如果云和现场 Mac 同时断电 / 断网，这条备援链也会失效。</text>
<text class="tech" x="126" y="826">建议最低：M1 / 8GB / 50GB，可用更稳：16GB / 100GB</text>
<rect class="panel" x="830" y="140" width="710" height="760"/>
<text class="panelTitle" x="860" y="190">模式 B：双云热备 / 温备</text>
<text class="panelSub" x="860" y="220">更强的远程连续性，适合把备援独立于现场设备之外。</text>
<rect class="boxBlue" x="870" y="270" width="250" height="150"/>
<text class="boxTitle" x="896" y="305">Cloud A（主用）</text>
<text class="boxText" x="896" y="338">控制面单体</text>
<text class="boxText" x="896" y="364">PostgreSQL 主库 + pgvector</text>
<text class="boxText" x="896" y="390">HTTP + SSE</text>
<rect class="boxGreen" x="1190" y="270" width="290" height="180"/>
<text class="boxTitle" x="1216" y="305">Cloud B（备用）</text>
<text class="boxText" x="1216" y="338">备用控制面单体</text>
<text class="boxText" x="1216" y="364">PostgreSQL 备库</text>
<text class="boxText" x="1216" y="390">接管脚本 / 快照 / 恢复钩子</text>
<text class="boxText" x="1216" y="416">Standby Controller</text>
<path class="arrow" d="M1120 345 C1155 345, 1160 345, 1190 345"/>
<rect class="boxOrange" x="870" y="500" width="610" height="160"/>
<text class="boxTitle" x="896" y="536">必要前提</text>
<text class="boxText" x="896" y="570">1. Cloud B 只做热备 / 温备，不承担常态重负载。</text>
<text class="boxText" x="896" y="598">2. 手机 App 与控制面支持主 / 备云 endpoint 切换。</text>
<text class="boxText" x="896" y="626">3. 设备端继续承担重媒体、重审计、重运维执行动作。</text>
<rect class="boxGray" x="870" y="700" width="610" height="150"/>
<text class="boxTitle" x="896" y="736">优点与边界</text>
<text class="boxText" x="896" y="770">优点：公网可达性更稳，不依赖现场某一台设备，接管路径更标准化。</text>
<text class="boxText" x="896" y="798">边界：成本更高；最后一跳的硬件接管仍要依赖现场设备在线。</text>
<text class="tech" x="896" y="826">建议最低：Cloud A 2C8G/100GB，Cloud B 2C8G/100GB</text>
<text class="foot" x="70" y="940">统一抽象建议：standby_provider = standby_mac | cloud_b | both</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/source-material/ha_modes_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 521 KiB

786
docs/source-material/ops_layer_and_repair_protocol_cn.md Normal file
View File

@@ -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 统一命名格式
建议所有错误键都遵循：
`<LAYER>.<DOMAIN>.<COMPONENT>.<ACTION>.<ERROR_CODE>`
例如：
- `ENTRY.APP.PROJECT_CREATE.VALIDATION_FAIL`
- `MASTER.SCHEDULER.DISPATCH.NODE_UNAVAILABLE`
- `WORKER.CODEX.THREAD_START.RATE_LIMIT`
- `THREAD.BROKER.MESSAGE_ROUTE.PERMISSION_DENIED`
- `AUDIT.MULTIMODAL.VERIFY.EVIDENCE_MISSING`
- `CAPABILITY.CAMERA.LEASE.PREEMPT_TIMEOUT`
- `DATA.POSTGRES.WRITE.REPLICATION_LAG`
- `OPS.LOCAL_AGENT.HEARTBEAT.MISSED`
- `OPS_AUDIT.REPAIR.VERIFY.RESTART_FAILED`
### 5.3 每条错误日志最少字段
- `fault_key`
- `severity`
- `node_id`
- `service_name`
- `project_id`
- `thread_ref`
- `trace_id`
- `runbook_id`
- `first_seen_at`
- `last_seen_at`
- `summary`
- `suggested_next_action`
### 5.4 日志分层前缀建议
- `ENTRY`
- `MASTER`
- `WORKER`
- `THREAD`
- `AUDIT`
- `CAPABILITY`
- `DATA`
- `AUTH`
- `QUOTA`
- `OPS`
- `OPS_AUDIT`
- `RECOVERY`
### 5.5 Token 节省策略
`Ops Agent` 汇报时不直接贴长日志，而是优先输出：
- `fault_key`
- 影响节点数
- 首次时间 / 最近时间
- top 3 关联错误
- 绑定的 `runbook_id`
- 当前是否可自动修复
---
## 6. 除日志之外的运维检测方式
只靠日志不够，建议同时启用以下机制：
### 6.1 心跳与存活探针
- 每个服务定期发送 heartbeat
- 每个节点的 `Ops Agent` 和 `Ops Audit Agent` 互相监督 heartbeat
- 主控、Worker、审计层、硬件网关都要有独立存活探针
### 6.2 合成探针 / 端到端冒烟
- 周期性模拟：
- 创建一个测试项目
- 下发一个轻量任务
- 启动一个测试线程
- 拉取一次线程历史
- 触发一次能力租约
- 如果冒烟链路断掉，说明系统虽然“进程活着”，但业务已经不通
### 6.3 队列与事件流监测
- 检测消息队列积压
- 检测 Event Store 写入延迟
- 检测线程消息是否长时间停滞
- 检测 SSE / WebSocket 是否失去推送
### 6.4 资源与性能监测
- CPU / 内存 / 磁盘 / GPU 占用
- WSL2 健康度
- 数据库复制延迟
- 对象存储写入失败率
- 网络抖动和丢包
### 6.5 认证与额度健康监测
- ChatGPT / Codex 登录态有效期
- API key 可用性
- gptpluscontrol 上报的新鲜度
- 5h / 7d 剩余额度阈值预警
### 6.6 配置与版本漂移检测
- Worker 版本不一致
- Gateway 配置漂移
- Runbook 版本落后
- 审计协议版本不兼容
### 6.7 孤儿状态清理
- 孤儿 lease
- 孤儿 thread
- 孤儿 repair ticket
- 无人接管的审计任务
### 6.8 本地屏幕 / 设备快照抽样
在硬件项目中，可周期性采样：
- 关键设备截图
- 摄像头关键帧
- 串口短日志
- UI OCR 状态
用于快速判断“服务活着但现场已经坏了”的情况。
---
## 7. 修复权限与决策规则
### 7.1 当主 Agent 在线且能正常返回信息
流程：
1. `Ops Agent` 发现问题
2. 生成修复建议与最小证据包
3. 向主 Agent 请求批准
4. 主 Agent 同意后，`Ops Agent` 执行修复
5. `Ops Audit Agent` 做复验
6. 复验结果回报主 Agent
原则：
- `Ops Agent` 不得自行越权修复
- 主 Agent 有权拒绝、延后、改用人工介入
- 复验未通过则不能直接关闭工单
### 7.2 当主 Agent 失联
定义失联建议：
- 连续 3 次心跳缺失，或
- 超过 15 分钟无法返回健康响应
流程：
1. `Ops Audit Agent` 确认主 Agent 失联
2. 通知 `Chief Ops Audit Agent`
3. 进入紧急运维模式
4. `Ops Audit Agent` 依据策略与证据，做最终是否修复的执行判断
5. `Ops Agent` 执行修复
6. `Ops Audit Agent` 复验
7. 修复结果写入 `Ops Ledger`
8. 主 Agent 恢复后，向其回放修复详情
### 7.3 当主 Agent 恢复在线
恢复后必须同步：
- 故障摘要
- 故障影响范围
- 已执行修复动作
- 修复结果
- 复验结论
- 是否仍有残余风险
- 是否需要人工复盘
### 7.4 当运维层自身挂了，但主 Agent 在线
这是一个单独处理场景，不能等同于普通服务故障。
定义运维层自身故障示例：
- `Ops Control Plane` 无法响应
- `Ops Ledger` 写入失败
- `Ops Connector Runtime` 大面积失效
- 多个节点的 `Ops Agent` / `Ops Audit Agent` 同时失联
- 运维层事件流中断
流程：
1. 主 Agent 在每小时健康检查或告警事件中发现运维层异常
2. 主 Agent 切换到 `ops_rescue_mode`
3. 主 Agent 通过独立的最小救援通道直连节点或备用控制器
4. 主 Agent 对运维层发起反向修复任务
5. 节点上的最小本地 Watchdog / Standby 代理执行运维层恢复
6. 恢复后由 `Ops Audit Agent` 复验运维层是否重新可用
7. 恢复结果写入账本，并结束 `ops_rescue_mode`
要求：
- 主 Agent 抢救运维层时，不能依赖已经损坏的运维控制面本身
- 必须保留至少一条最小救援通道，例如：
- 直连节点的紧急 RPC
- 备用控制器通道
- 本地 Watchdog 的保底命令接口
- 只读日志和健康快照通道
---
## 8. 运维修复状态机
### 8.1 Repair Ticket 状态
- `detected`
- `classified`
- `approval_pending`
- `approved_by_master`
- `approved_by_ops_audit_emergency`
- `repairing`
- `repair_failed`
- `verification_pending`
- `verified_pass`
- `verified_fail`
- `reported_to_master`
- `closed`
### 8.2 自动修复白名单
仅允许以下低风险动作默认自动化：
- 重启本地 Agent 进程
- 重连 WebSocket / SSE
- 重试心跳上传
- 重拉轻量配置
- 恢复日志采集
以下动作必须更高权限：
- 切换主账号 / 备用账号
- 重启数据库
- 回滚 Worker 版本
- 强制释放能力租约
- 重启 GPU Bridge
- 重刷固件 / 重置测试设备
---
## 9. 修复动作与复验规范
### 9.1 RepairAction 输入字段
- `repair_ticket_id`
- `fault_key`
- `node_id`
- `service_name`
- `decision_source`
值：
- `master_agent`
- `ops_audit_agent_emergency`
- `runbook_id`
- `action_type`
- `risk_level`
- `expected_result`
- `timeout_seconds`
### 9.2 RepairVerification 输出字段
- `repair_ticket_id`
- `verification_status`
值：
- `pass`
- `fail`
- `partial_pass`
- `inconclusive`
- `post_health_summary`
- `remaining_risks`
- `evidence_refs`
- `recommended_followup`
### 9.3 复验最少检查项
- 原故障是否停止出现
- 关键进程是否恢复
- 事件流是否恢复
- 相关接口是否恢复
- 如涉及硬件，现场状态是否恢复
- 是否引入新的副作用
---
## 10. 建议 API / 事件
### 10.1 API
- `POST /api/v1/ops/nodes/heartbeat`
- `POST /api/v1/ops/health/report`
- `POST /api/v1/ops/domains/register`
- `POST /api/v1/ops/connectors/register`
- `POST /api/v1/ops/remote-actions/request`
- `POST /api/v1/ops/remote-actions/{action_id}/approve`
- `POST /api/v1/ops/remote-actions/{action_id}/result`
- `POST /api/v1/ops/repair-tickets`
- `POST /api/v1/ops/repair-tickets/{ticket_id}/approval-request`
- `POST /api/v1/ops/repair-actions/start`
- `POST /api/v1/ops/repair-actions/{action_id}/result`
- `POST /api/v1/ops/repair-verifications`
- `POST /api/v1/ops/rescue/enter`
- `POST /api/v1/ops/rescue/actions/start`
- `POST /api/v1/ops/rescue/complete`
- `GET /api/v1/ops/events/stream`
### 10.2 事件
- `ops_agent_heartbeat_missed`
- `ops_audit_agent_heartbeat_missed`
- `ops_domain_registered`
- `ops_connector_registered`
- `ops_remote_action_requested`
- `ops_remote_action_approved`
- `ops_remote_action_completed`
- `ops_remote_action_failed`
- `ops_fault_detected`
- `ops_fault_classified`
- `ops_repair_approval_requested`
- `ops_repair_approved_by_master`
- `ops_repair_approved_by_ops_audit_emergency`
- `ops_repair_started`
- `ops_repair_completed`
- `ops_repair_failed`
- `ops_repair_verification_passed`
- `ops_repair_verification_failed`
- `ops_layer_degraded`
- `ops_rescue_mode_entered`
- `ops_rescue_action_started`
- `ops_rescue_action_completed`
- `ops_layer_recovered`
- `master_agent_offline_confirmed`
- `master_agent_recovered`
- `ops_repair_report_synced_to_master`
---
## 11. 最小数据库表建议
- `ops_nodes`
- `ops_domains`
- `ops_connectors`
- `ops_agent_heartbeats`
- `ops_audit_agent_heartbeats`
- `ops_faults`
- `ops_fault_occurrences`
- `ops_repair_tickets`
- `ops_repair_actions`
- `ops_repair_verifications`
- `ops_runbooks`
- `ops_mode_history`
- `ops_rescue_actions`
- `ops_reports_to_master`
---
## 12. MVP 建议
### V1
- 每个节点部署 `Local Ops Agent` 与 `Local Ops Audit Agent`
- 实现 heartbeat、fault_key 命名、repair ticket、主 Agent 审批、修复复验
- 高频 / 空闲巡检切换
- 主 Agent 对运维层的每小时健康检查
### V2
- 加入合成探针、业务冒烟、孤儿状态清理、主控离线后的紧急修复授权
- 加入主 Agent 恢复后的修复回放
- 加入 `Ops Domain / Connector / Runbook Pack` 的开放式接入
### V3
- 加入更精细的 Runbook 路由
- 加入多节点联动修复
- 加入版本回滚与策略化自愈
- 加入主 Agent 对运维层自身的反向抢救通道与 `ops_rescue_mode`
---
## 13. 一句话总结
`运维层` 解决“谁去发现、执行和扩展运维修复”的问题，
`运维审计层` 解决“谁有权批准、谁来复验、主控失联时谁来兜底”的问题。
它们必须常驻在每个节点，并且站在整个系统最外层，持续保护主控、Worker、审计层、硬件层、数据层，以及后续接入的其他项目运维域；当运维层自己挂掉时，还要允许主 Agent 反向抢救它。
---
## 14. 支持两种保活模式
运维层和运维审计层也要兼容两种备用接管模式：
### 14.1 单云 + 设备端备用池
说明：
- `Cloud A` 作为主用控制面
- 一台首选 `Standby Mac` 或其他设备，作为首选备用控制器
- 同时维护一个 `standby_device_pool` 作为后备容灾池
最低要求：
- 至少一台首选备用设备必须常开
- 必须具备独立于主云的可达路径
- 每台候选备用设备至少运行：
- `Standby Controller`
- `Local Ops Agent`
- `Local Ops Audit Agent`
- `Ops Rescue Gateway`
当主云故障时：
1. 当前活动备用设备接收主控失联告警
2. 提升本机备用控制面
3. 恢复最小项目视图、工单视图、修复审批链路
4. 运维审计层继续做复验和修复回放
### 14.2 双云热备 / 温备
说明：
- `Cloud A` 主用
- `Cloud B` 备用
最低要求：
- `Cloud B` 只做接管准备，不承担常态重负载
- 保留备用控制面、备库、快照和恢复钩子
当主云故障时：
1. `Cloud B` 接管控制面
2. `Chief Ops Audit Agent` 继续保留紧急修复判定权
3. 现场各节点 `Local Ops Agent` 继续执行修复动作
4. 主云恢复后，再做账本回放与状态对账
### 14.3 统一抽象
无论采用哪种模式，运维层都应统一抽象为：
- `standby_provider = standby_mac | cloud_b | both`
这样修复流程、审计流程、修复复验、主控恢复回放都不需要重新设计，只替换备用提供者即可。
### 14.4 单服务器模式下的自动备用设备切换
如果采用“单服务器 + 设备端保活”，就必须支持自动切换备用设备。
#### 新增对象
- `standby_device_pool`
- `standby_device_candidate`
- `active_standby_device`
- `takeover_package`
- `standby_device_score`
#### 每台设备需要上报
- `device_id`
- `eligible_for_standby`
- `preferred_rank`
- `always_on`
- `memory_free_mb`
- `disk_free_mb`
- `lan_reachability`
- `tunnel_reachability`
- `last_heartbeat_at`
- `takeover_package_version`
#### 自动切换规则
1. 控制面维护 `standby_device_pool`
2. 为排名前 `N` 的设备同步最小 `takeover_package`
3. 如果当前 `active_standby_device` 心跳超时：
- 立即标记为 `degraded`
- 重新计算 `standby_device_score`
- 自动提升下一台候选设备
4. 新的备用设备接管后：
- 发布新的 endpoint 清单
- 更新 `ops_mode_history`
- 通知主 Agent、Worker、手机 App
#### 备用设备模式要求
- `cold standby`
- 未预部署接管组件
- 不允许进入自动切换路径
- `warm standby`
- 已预部署接管组件
- 已同步最近的 `takeover_package`
- 允许自动切换
- `hot standby`
- 已预部署接管组件
- 保持更高频状态同步
- 允许自动切换，且优先级更高
结论：
- 自动切换只允许选用 `warm standby` 或 `hot standby`
- `cold standby` 只能作为人工应急候选，不能当自动保活候选
#### `takeover_package` 最小内容
- 最近的项目 / 任务索引
- endpoint 注册表
- 修复工单索引
- 权限与审批快照
- 当前 `standby_epoch`
#### 新增事件
- `standby_device_registered`
- `standby_device_score_updated`
- `active_standby_device_changed`
- `takeover_package_synced`
- `standby_device_failed`
#### 新增数据库表
- `standby_devices`
- `standby_device_scores`
- `standby_device_packages`
- `standby_failover_history`
#### 候选设备预部署清单
每个 `warm/hot standby` 候选设备至少预部署：
- `Standby Controller`
- `Local Ops Agent`
- `Local Ops Audit Agent`
- `Ops Rescue Gateway`
- 最小运行时依赖
- 最小配置模板
- endpoint 注册表缓存
- 最近的 `takeover_package`

166
docs/source-material/ops_repair_swimlane_cn.svg Normal file
View File

@@ -0,0 +1,166 @@
<svg width="2200" height="1420" viewBox="0 0 2200 1420" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="160" y1="40" x2="2040" y2="1380" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF5FF"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="2200" height="1420" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="14" stdDeviation="18" flood-color="#1F2937" flood-opacity="0.10"/>
</filter>
<style>
.title { font: 700 36px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #15253B; }
.subtitle { font: 500 17px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #51657C; }
.stage { font: 700 20px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17314D; }
.lane { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.laneSub { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #5A6E84; }
.cardTitle { font: 700 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #132238; }
.cardText { font: 500 13px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #44586E; }
.tech { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #60758C; }
</style>
</defs>
<rect width="2200" height="1420" rx="36" fill="url(#bg)"/>
<text x="90" y="92" class="title">运维层与运维审计层抢修流程泳道图</text>
<text x="90" y="126" class="subtitle">覆盖动态巡检、日志命名、在线审批修复、主控离线紧急接管、修复复验与主控恢复回放。</text>
<!-- Stage headers -->
<g filter="url(#shadow)">
<rect x="250" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="550" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="850" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="1150" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="1450" y="162" width="280" height="76" rx="20" fill="#FFFFFF"/>
<rect x="1750" y="162" width="330" height="76" rx="20" fill="#FFFFFF"/>
</g>
<text x="331" y="207" class="stage">1. 动态巡检</text>
<text x="623" y="207" class="stage">2. 异常分类</text>
<text x="929" y="207" class="stage">3. 审批 / 授权</text>
<text x="1231" y="207" class="stage">4. 修复执行</text>
<text x="1543" y="207" class="stage">5. 复验</text>
<text x="1831" y="207" class="stage">6. 汇报与回放</text>
<!-- Lane backgrounds -->
<g opacity="0.96">
<rect x="60" y="280" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="484" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="688" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="892" width="2060" height="184" rx="26" fill="#FFFFFF"/>
<rect x="60" y="1096" width="2060" height="184" rx="26" fill="#FFFFFF"/>
</g>
<!-- Grid -->
<g stroke="#D8E2EF" stroke-width="2">
<line x1="230" y1="280" x2="230" y2="1280"/>
<line x1="530" y1="280" x2="530" y2="1280"/>
<line x1="830" y1="280" x2="830" y2="1280"/>
<line x1="1130" y1="280" x2="1130" y2="1280"/>
<line x1="1430" y1="280" x2="1430" y2="1280"/>
<line x1="1730" y1="280" x2="1730" y2="1280"/>
<line x1="60" y1="484" x2="2120" y2="484"/>
<line x1="60" y1="688" x2="2120" y2="688"/>
<line x1="60" y1="892" x2="2120" y2="892"/>
<line x1="60" y1="1096" x2="2120" y2="1096"/>
</g>
<!-- Lanes -->
<rect x="78" y="310" width="134" height="48" rx="18" fill="#E8F1FF"/>
<text x="102" y="340" class="lane">主 Agent</text>
<text x="84" y="374" class="laneSub">在线审批与接收回放</text>
<rect x="78" y="514" width="144" height="48" rx="18" fill="#EAF9EE"/>
<text x="102" y="544" class="lane">Ops Agent</text>
<text x="84" y="578" class="laneSub">巡检、分类、执行修复</text>
<rect x="78" y="718" width="188" height="48" rx="18" fill="#F4E8FF"/>
<text x="102" y="748" class="lane">Ops Audit Agent</text>
<text x="84" y="782" class="laneSub">监督、判权、复验、紧急决策</text>
<rect x="78" y="922" width="162" height="48" rx="18" fill="#FEEAEA"/>
<text x="102" y="952" class="lane">终端服务层</text>
<text x="84" y="986" class="laneSub">主控 / Worker / 网关 / 硬件桥</text>
<rect x="78" y="1126" width="176" height="48" rx="18" fill="#E4F6FD"/>
<text x="102" y="1156" class="lane">数据与容灾层</text>
<text x="84" y="1190" class="laneSub">Ops Ledger / Event / Standby</text>
<!-- Cards -->
<g filter="url(#shadow)">
<rect x="552" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="552" y="710" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1752" y="302" width="320" height="136" rx="20" fill="#FFFFFF"/>
<rect x="852" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="852" y="710" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1152" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1452" y="710" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1152" y="914" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1452" y="914" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1152" y="1118" width="258" height="136" rx="20" fill="#FFFFFF"/>
<rect x="1752" y="1118" width="320" height="136" rx="20" fill="#FFFFFF"/>
<rect x="252" y="506" width="258" height="136" rx="20" fill="#FFFFFF"/>
</g>
<text x="272" y="538" class="cardTitle">动态巡检模式</text>
<text x="272" y="566" class="cardText">高频使用时每 5 分钟巡检，系统空闲时每 1 小时巡检。</text>
<text x="272" y="618" class="tech">技术：Ops Policy Engine、Mode Switch Rules</text>
<text x="572" y="538" class="cardTitle">日志归一与故障聚类</text>
<text x="572" y="566" class="cardText">按 `LAYER.DOMAIN.COMPONENT.ACTION.ERROR_CODE` 归类，生成最小证据包。</text>
<text x="572" y="618" class="tech">技术：fault_key、Runbook Map、Log Index</text>
<text x="872" y="538" class="cardTitle">主控在线时请求审批</text>
<text x="872" y="566" class="cardText">主 Agent 在线且可响应时，Ops Agent 先提修复建议，不能越权直接修。</text>
<text x="872" y="618" class="tech">技术：Approval Request、Repair Ticket</text>
<text x="872" y="742" class="cardTitle">主控失联时做最终判断</text>
<text x="872" y="770" class="cardText">确认主控失联后，Ops Audit Agent 联合 Chief Ops Audit Agent 决定是否抢修。</text>
<text x="872" y="822" class="tech">技术：Emergency Authority、Offline Quorum</text>
<text x="1172" y="538" class="cardTitle">执行修复 Runbook</text>
<text x="1172" y="566" class="cardText">重启服务、切换账号、恢复心跳、释放孤儿租约、重建连接等。</text>
<text x="1172" y="618" class="tech">技术：Runbook Executor、Safe Action Policy</text>
<text x="1472" y="742" class="cardTitle">复验修复是否真的成功</text>
<text x="1472" y="770" class="cardText">看原故障是否消失、服务是否恢复、事件流是否恢复、是否有副作用。</text>
<text x="1472" y="822" class="tech">技术：Ops Audit Verification、Synthetic Probe</text>
<text x="1172" y="946" class="cardTitle">被修复对象恢复服务</text>
<text x="1172" y="974" class="cardText">主控、Worker、Thread Gateway、Audit Orchestrator、Test Rig、gptpluscontrol 等恢复。</text>
<text x="1172" y="1026" class="tech">技术：Service Supervisor、Health Probe</text>
<text x="1472" y="946" class="cardTitle">产生新健康状态与证据</text>
<text x="1472" y="974" class="cardText">生成复验日志、关键快照、队列状态、额度状态和回放材料。</text>
<text x="1472" y="1026" class="tech">技术：Evidence Collector、Health Snapshot</text>
<text x="1172" y="1150" class="cardTitle">修复账本留痕</text>
<text x="1172" y="1178" class="cardText">写入 repair ticket、动作、复验结果、主控是否在线、后续风险。</text>
<text x="1172" y="1230" class="tech">技术：Ops Ledger、Event Store、Postgres</text>
<text x="1772" y="334" class="cardTitle">主控每小时检查运维层</text>
<text x="1772" y="362" class="cardText">确认各节点 Ops Agent / Ops Audit Agent 是否在线且最近巡检成功。</text>
<text x="1772" y="414" class="tech">技术：Master Health Check、Ops Node Matrix</text>
<text x="1772" y="1150" class="cardTitle">恢复后回放给主控</text>
<text x="1772" y="1178" class="cardText">主控恢复在线后，自动收到故障摘要、修复动作、复验结论和剩余风险。</text>
<text x="1772" y="1230" class="tech">技术：Repair Report Sync、Recovery Replay</text>
<text x="572" y="742" class="cardTitle">监督 Ops Agent 是否越权</text>
<text x="572" y="770" class="cardText">确认主控是否在线、当前动作是否在自动修复白名单、是否需要升级。</text>
<text x="572" y="822" class="tech">技术：Ops Audit Policy、Privilege Gate</text>
<!-- Flow arrows -->
<g stroke-linecap="round" stroke-width="5">
<path d="M510 574H552" stroke="#22C55E"/>
<path d="M810 574H852" stroke="#22C55E"/>
<path d="M1110 574H1152" stroke="#22C55E"/>
<path d="M1410 982H1452" stroke="#EF4444"/>
<path d="M1710 778H1752V1186" stroke="#A855F7"/>
<path d="M2012 438V1118" stroke="#0EA5E9"/>
<path d="M980 642V710" stroke="#A855F7"/>
<path d="M1280 642V914" stroke="#EF4444"/>
<path d="M1280 1050V1118" stroke="#0EA5E9"/>
<path d="M1610 846V914" stroke="#EF4444"/>
</g>
<text x="90" y="1376" class="footer">图文件：/Users/kris/code/Talking/ops_repair_swimlane_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/source-material/ops_repair_swimlane_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 MiB

398
docs/source-material/thread_context_budget_and_handoff_protocol_cn.md Normal file
View File

@@ -0,0 +1,398 @@
# 线程上下文预算与压缩前接力协议
这份文档把“背景信息窗口余量”正式冻结成开发规格，覆盖：
- 设备端如何上报线程上下文预算
- 手机端 / Web BFF 如何返回会话列表里的圆环进度标记
- 主 Agent 如何基于上下文预算做压缩前收尾、线程轮换和摘要接力
- 哪些字段是系统真相，哪些字段只是展示层映射
适用范围：
- 单主 Agent
- 多台 Mac / Windows / Cloud Worker
- 微信式会话列表首页
- 项目聊天页 / 线程详情页
- `API-first / local-first` 极限轻云模式
---
## 1. 核心原则
1. 首页圆环标记显示的是“线程上下文预算”，不是账号 5h / 7d 使用额度。
2. 线程上下文预算必须由设备端 worker 统一上报，前端不能自行推算。
3. 主 Agent 必须在发生背景信息压缩前完成关键收尾，而不是在压缩后补救。
4. 线程上下文预算是主 Agent 的一等调度信号，优先级高于普通列表排序提示。
5. 群聊型项目会话默认不在首页显示线程上下文预算，但项目详情页仍然可以展开查看各线程预算。
---
## 2. 术语定义
### 2.1 线程上下文预算
指当前线程在发生背景信息压缩、上下文裁剪或显著细节丢失之前，还剩多少安全上下文空间。
### 2.2 背景信息压缩
指 Codex / worker 为继续运行而触发的上下文压缩、阶段性摘要替换、历史裁剪或其他会导致细节损失的机制。
### 2.3 压缩前收尾
指主 Agent 在预算即将耗尽前，主动要求线程完成的固化动作，包括：
- patch 固化
- 命令和日志固化
- 测试结果固化
- 关键决策固化
- 未决问题固化
- 证据引用固化
- handoff 摘要生成
### 2.4 摘要接力
指当前线程在压缩或结束前，把下一条线程继续工作所需的最小必要信息打包并交给主 Agent 或下一线程。
---
## 3. 设备端真相模型
### 3.1 新增数据对象
- `thread_context_snapshots`
- `thread_context_threshold_policies`
- `thread_handoff_packages`
- `thread_context_alerts`
### 3.2 `thread_context_snapshots`
最小字段：
- `snapshot_id`
- `project_id`
- `task_id`
- `thread_id`
- `node_id`
- `worker_id`
- `source_kind`
- `codex_app_server`
- `codex_sdk`
- `worker_estimator`
- `context_budget_remaining_pct`
- `context_budget_level`
- `safe`
- `watch`
- `urgent`
- `critical`
- `compaction_expected_at`
- `must_finish_before_compaction`
- `estimated_remaining_turns`
- `estimated_remaining_large_messages`
- `last_compaction_at`
- `compaction_count`
- `snapshot_version`
- `captured_at`
### 3.3 `thread_handoff_packages`
最小字段：
- `handoff_package_id`
- `project_id`
- `task_id`
- `from_thread_id`
- `to_thread_id`
- `package_status`
- `draft`
- `ready`
- `consumed`
- `expired`
- `summary_text`
- `open_questions`
- `critical_files`
- `critical_commands`
- `critical_tests`
- `critical_artifacts`
- `decision_links`
- `created_at`
- `ready_at`
- `consumed_at`
### 3.4 `thread_context_alerts`
最小字段：
- `alert_id`
- `thread_id`
- `project_id`
- `alert_type`
- `context_watch`
- `context_urgent`
- `context_critical`
- `compaction_risk`
- `handoff_missing`
- `alert_status`
- `opened`
- `acked`
- `resolved`
- `opened_at`
- `resolved_at`
---
## 4. 统一阈值策略
默认阈值：
- `safe`: `>= 60%`
- `watch`: `40% ~ 59%`
- `urgent`: `25% ~ 39%`
- `critical`: `< 25%`
### 4.1 对应动作
| 等级 | 说明 | 主 Agent 动作 |
| --- | --- | --- |
| `safe` | 线程仍可稳定推进 | 继续执行，但要求持续刷新阶段摘要 |
| `watch` | 预算开始收紧 | 不再追加大块背景信息，开始准备 handoff |
| `urgent` | 接近压缩边缘 | 优先完成当前原子子任务，预创建接力线程 |
| `critical` | 随时可能发生压缩 | 立即执行压缩前收尾，禁止继续扩张上下文 |
### 4.2 `must_finish_before_compaction`
该字段由主 Agent 或 worker 规则引擎在以下条件置为 `true`：
- 当前线程有未提交 patch
- 当前线程有未整理测试结论
- 当前线程有未写入项目记忆的关键决策
- 当前线程正在执行一次不可中断的硬件步骤
- 当前线程正在等待跨节点线程回复，但已有结论必须先固化
---
## 5. Worker 上报协议
### 5.1 上报频率
- 线程状态发生显著变化时立即上报
- 普通运行中每 `30s` 上报一次
- `watch` 级别每 `15s` 上报一次
- `urgent / critical` 级别每 `5s` 上报一次
### 5.2 API
`POST /api/v1/workers/{worker_id}/thread-context`
请求体：
```json
{
"node_id": "mac-01",
"worker_id": "worker-mac-01",
"thread_id": "thread-abc",
"project_id": "proj-001",
"task_id": "task-017",
"source_kind": "worker_estimator",
"context_budget_remaining_pct": 37,
"context_budget_level": "urgent",
"compaction_expected_at": "2026-03-25T16:08:30+08:00",
"must_finish_before_compaction": true,
"estimated_remaining_turns": 5,
"estimated_remaining_large_messages": 2,
"last_compaction_at": "2026-03-25T15:12:10+08:00",
"compaction_count": 1,
"captured_at": "2026-03-25T15:56:00+08:00"
}
```
返回体：
```json
{
"accepted": true,
"thread_id": "thread-abc",
"context_budget_level": "urgent",
"next_required_report_in_seconds": 5,
"master_actions": [
"prepare_handoff",
"avoid_large_context_append"
]
}
```
### 5.3 事件
每次有效更新都必须写事件流：
- `thread.context.updated`
- `thread.context.level_changed`
- `thread.context.compaction_risk_opened`
- `thread.context.compaction_risk_resolved`
---
## 6. 手机端 / Web BFF 协议
### 6.1 会话列表接口
`GET /api/v1/conversations`
项目会话项新增字段：
- `context_budget_indicator`
- `visible`
- `style`
- `percent`
- `level`
- `context_budget_source_node_id`
- `context_budget_updated_at`
- `must_finish_before_compaction`
示例：
```json
{
"conversation_id": "conv-proj-001",
"conversation_type": "single_device",
"project_title": "北区试产线回归",
"manual_pinned": true,
"latest_reply_at": "2026-03-25T09:26:00+08:00",
"context_budget_indicator": {
"visible": true,
"style": "ring_percent",
"percent": 52,
"level": "watch"
},
"must_finish_before_compaction": false
}
```
### 6.2 项目详情接口
`GET /api/v1/projects/{project_id}`
新增：
- `active_thread_contexts`
- `next_compaction_risk_thread_id`
- `threads_requiring_handoff`
- `master_context_strategy_summary`
### 6.3 线程详情接口
`GET /api/v1/threads/{thread_id}/context-budget`
返回：
- 当前百分比
- 当前等级
- 预计压缩时间
- 最近压缩时间
- 当前收尾清单
- handoff 包状态
### 6.4 SSE 事件
- `conversation.context_indicator.updated`
- `project.context_risk.updated`
- `thread.handoff.required`
- `thread.handoff.ready`
---
## 7. 首页 UI 映射规则
### 7.1 单设备项目会话
右侧第三层显示：
- 小圆环进度标记
- 百分比
样式要求：
- 必须与设备端线程页和项目详情页保持一致
- 默认使用中性灰环
- 低预算时通过主 Agent 摘要和项目详情强化提醒，不在首页堆叠过多告警文案
### 7.2 群聊型项目会话
默认不显示第三层圆环。
原因：
- 多线程、多设备协作项目不能把多个线程预算压成一个误导性的单值
- 这类项目应在项目详情页查看各线程预算
### 7.3 主 Agent 会话
可以显示单一圆环预算，但含义是：
- 主 Agent 当前主线程的工作预算
- 不是整个系统剩余额度总量
---
## 8. 主 Agent 调度逻辑
### 8.1 预算优先级排序
主 Agent 在每轮调度时，必须把以下因子一起排序：
- `context_budget_level`
- `must_finish_before_compaction`
- `compaction_expected_at`
- 任务重要性
- 是否持有未固化 patch
- 是否持有未固化测试结果
- 是否持有未固化硬件证据
### 8.2 默认调度策略
1. 若线程进入 `critical`，优先处理该线程的收尾和交接。
2. 若多个线程同时 `critical`，优先处理：
- 有未固化 patch 的
- 有未固化测试结果的
- 有硬件测试正在进行的
3. `watch` 和 `urgent` 阶段，主 Agent 应减少向该线程追加长背景信息。
4. 新子任务应优先派给预算更健康的新线程或其他空闲线程。
### 8.3 压缩前收尾清单
主 Agent 触发 `prepare_handoff` 时，worker 必须尽量补齐：
- 当前修改涉及的文件清单
- 已完成和未完成的 patch
- 最近一次关键命令及其结果
- 最近一次测试结论
- 未决问题
- 下一线程建议动作
- 必需证据链接
---
## 9. 验收标准
满足以下条件，视为这块设计可直接进入开发：
1. 设备端能统一上报线程上下文预算。
2. BFF 能返回首页圆环所需全部字段。
3. 项目详情页能展开查看多线程预算。
4. 主 Agent 能在 `watch / urgent / critical` 三个边界做出不同动作。
5. 发生 compaction 前，系统能自动触发至少一次压缩前收尾和 handoff 准备。
6. 首页显示、项目详情显示、设备端线程显示三处的预算语义一致。
---
## 10. 与现有文档关系
这份文档是以下文档的补充细化：
- `/Users/kris/code/Talking/codex_multi_machine_architecture_cn.html`
- `/Users/kris/code/Talking/wechat_project_conversation_mapping_cn.md`
- `/Users/kris/code/Talking/development_subtasks_and_delivery_plan_cn.md`
它的定位是：
- 专门冻结“线程上下文预算”和“压缩前接力”这条主线
- 供后端、设备端、主 Agent、前端同时作为实现依据

103
docs/source-material/ultra_light_dual_cloud_topology_cn.svg Normal file
View File

@@ -0,0 +1,103 @@
<svg width="1900" height="1180" viewBox="0 0 1900 1180" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
<linearGradient id="bg" x1="120" y1="40" x2="1780" y2="1120" gradientUnits="userSpaceOnUse">
<stop stop-color="#F8FBFF"/>
<stop offset="1" stop-color="#EEF5FF"/>
</linearGradient>
<linearGradient id="cloudA" x1="520" y1="250" x2="900" y2="640" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F62FE"/>
<stop offset="1" stop-color="#4D91FF"/>
</linearGradient>
<linearGradient id="cloudB" x1="1010" y1="250" x2="1390" y2="640" gradientUnits="userSpaceOnUse">
<stop stop-color="#0F766E"/>
<stop offset="1" stop-color="#2CB7A5"/>
</linearGradient>
<filter id="shadow" x="0" y="0" width="1900" height="1180" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#1F2937" flood-opacity="0.10"/>
</filter>
<style>
.title { font: 700 36px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #17263C; }
.subtitle { font: 500 16px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #51657C; }
.cardTitle { font: 700 24px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #FFFFFF; }
.cardText { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: rgba(255,255,255,0.92); }
.sectionTitle { font: 700 22px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #14263D; }
.sectionText { font: 500 15px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #45586F; }
.tag { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #0F62FE; }
.footer { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; fill: #60748C; }
</style>
</defs>
<rect width="1900" height="1180" rx="36" fill="url(#bg)"/>
<text x="80" y="92" class="title">极轻云双云部署拓扑图</text>
<text x="80" y="126" class="subtitle">原则：云端只保留控制面真相和调度真相；主云承载业务，备云只承担接管准备；重执行全部下沉到设备端。</text>
<g filter="url(#shadow)">
<rect x="720" y="86" width="460" height="112" rx="26" fill="#FFFFFF"/>
</g>
<text x="852" y="132" class="sectionTitle">手机 App / Web</text>
<text x="780" y="166" class="sectionText">只看项目、线程、审计结论、运维状态，不直接连设备节点</text>
<g filter="url(#shadow)">
<rect x="520" y="250" width="390" height="360" rx="30" fill="url(#cloudA)"/>
<rect x="990" y="250" width="390" height="360" rx="30" fill="url(#cloudB)"/>
</g>
<text x="650" y="302" class="cardTitle">Cloud A 主云</text>
<text x="566" y="344" class="cardText">常态承载主业务流量</text>
<text x="566" y="380" class="cardText">• 控制面单体（FastAPI + LangGraph）</text>
<text x="566" y="412" class="cardText">• Master Agent / Scheduler / Audit / Ops</text>
<text x="566" y="444" class="cardText">• Thread Registry / Broker 逻辑</text>
<text x="566" y="476" class="cardText">• PostgreSQL 主库 + pgvector</text>
<text x="566" y="508" class="cardText">• HTTP + SSE</text>
<text x="566" y="556" class="cardText">不放：</text>
<text x="566" y="588" class="cardText">Redis / NATS / 独立向量库 / 重媒体处理</text>
<text x="1120" y="302" class="cardTitle">Cloud B 备云</text>
<text x="1036" y="344" class="cardText">平时只做热备 / 温备，不跑重负载</text>
<text x="1036" y="380" class="cardText">• 备用控制面单体</text>
<text x="1036" y="412" class="cardText">• PostgreSQL 备库</text>
<text x="1036" y="444" class="cardText">• 接管脚本 / 快照 / 恢复入口</text>
<text x="1036" y="476" class="cardText">• Standby Controller / Rescue hooks</text>
<text x="1036" y="556" class="cardText">目标：</text>
<text x="1036" y="588" class="cardText">保持“可接管”，而不是“平时跑满”</text>
<g filter="url(#shadow)">
<rect x="110" y="726" width="520" height="290" rx="28" fill="#FFFFFF"/>
<rect x="690" y="726" width="520" height="290" rx="28" fill="#FFFFFF"/>
<rect x="1270" y="726" width="520" height="290" rx="28" fill="#FFFFFF"/>
</g>
<rect x="150" y="758" width="172" height="32" rx="16" fill="#EAF9EE"/>
<text x="196" y="780" class="tag" style="fill:#14803D">Mac / Windows 节点</text>
<text x="150" y="834" class="sectionTitle">执行与边缘处理</text>
<text x="150" y="876" class="sectionText">• Worker Daemon</text>
<text x="150" y="906" class="sectionText">• Thread Gateway</text>
<text x="150" y="936" class="sectionText">• Local Ops Agent / Audit Agent</text>
<text x="150" y="966" class="sectionText">• OCR / 检测 / 视频裁剪 / 音频预处理</text>
<rect x="730" y="758" width="162" height="32" rx="16" fill="#FEEAEA"/>
<text x="767" y="780" class="tag" style="fill:#B42318">Test Rig / 硬件</text>
<text x="730" y="834" class="sectionTitle">硬件能力在边缘执行</text>
<text x="730" y="876" class="sectionText">• Camera / Mic / Speaker</text>
<text x="730" y="906" class="sectionText">• Thumb Robot / Relay / Serial</text>
<text x="730" y="936" class="sectionText">• Test Rig Gateway</text>
<text x="730" y="966" class="sectionText">• 只上传关键帧、短片段、摘要与异常证据</text>
<rect x="1310" y="758" width="182" height="32" rx="16" fill="#E4F6FD"/>
<text x="1353" y="780" class="tag" style="fill:#0369A1">为什么这样最省云</text>
<text x="1310" y="834" class="sectionTitle">云端不做重活</text>
<text x="1310" y="876" class="sectionText">• 不持续接原始媒体流</text>
<text x="1310" y="906" class="sectionText">• 不跑常驻重审计进程</text>
<text x="1310" y="936" class="sectionText">• 不做跨设备修复动作本体</text>
<text x="1310" y="966" class="sectionText">• 只保留真相、调度、索引、结论与接管能力</text>
<g stroke-linecap="round" stroke-width="6">
<path d="M950 198V248" stroke="#3B82F6"/>
<path d="M910 430H990" stroke="#94A3B8" stroke-dasharray="12 12"/>
<path d="M700 610V726" stroke="#22C55E"/>
<path d="M1180 610V726" stroke="#EF4444"/>
<path d="M1380 610V726" stroke="#0EA5E9"/>
</g>
<text x="80" y="1128" class="footer">图文件：/Users/kris/code/Talking/ultra_light_dual_cloud_topology_cn.svg</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
docs/source-material/ultra_light_dual_cloud_topology_cn.svg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 MiB

853
docs/source-material/wechat_project_conversation_mapping_cn.md Normal file
View File

@@ -0,0 +1,853 @@
# 微信式项目会话与聊天页规格
这份文档用于冻结“第一屏 = 微信式会话列表”的产品逻辑，避免后续开发时又回到“移动控制台首页”的方向。
视觉对标：
- 微信 iPhone 版会话列表页的核心结构
- 官方来源：[微信 App Store 页面](https://apps.apple.com/cn/app/id414478124)
适用范围：
- 手机 App 第一屏
- 设备页（对应微信通讯录位置）
- 我的页（对应微信“我”）
- 项目聊天页
- 主 Agent 置顶会话
- 项目会话列表
- 设备头像 / 协作群聊头像
- 手动置顶
- 项目目标
- 版本迭代记录
- 图片 / 视频 / 语音输入
- 消息转发
---
## 1. 首页定位
首页不是“主 Agent 聊天正文页”。
首页应该是：
- 一个微信式的会话列表页
- 列表中的每一条会话都代表一个“项目对话”
- 列表顶部固定一条 `主 Agent` 会话
- 用户点击任意一条会话，再进入该项目的具体对话页
一句话定义：
`第一屏 = 主 Agent 总会话 + 各项目会话列表`
底部导航要求：
- 第一项：`会话`
- 第二项：`设备`
- 第三项：`我的`
- 呈现方式：微信式扁平底栏，`图标在上 / 文案在下 / 激活项使用微信绿`
其中第二项 `设备` 对应微信中的“通讯录”位置。
第三项 `我的` 对应微信中的“我”。
项目入口不再占据底部一级导航，而是从 `会话` 首页进入。
---
## 2. 项目会话与设备项目文件夹的映射规则
每一个项目会话必须和设备端 GUI 界面里的项目文件夹一一对应。
映射规则如下：
1. 每台接入设备启动 `worker-daemon` 后，扫描并注册本机可见项目根目录。
2. 每个项目目录生成稳定的 `project_folder_key`。
3. 云端控制面把同名或同一仓库来源的文件夹，映射到同一个 `project_id`。
4. 主 Agent 不直接生成“虚拟项目名”，而是基于 `project_id` 做汇总。
5. 首页列表展示的项目会话标题，优先使用：
- 项目显式别名
- 仓库名 / 文件夹名
- 最后回退到 `project_id`
必须满足：
- 一个项目会话能追溯到具体设备上的具体文件夹
- 进入项目详情时，能看到这个项目当前挂在哪些设备上
---
## 3. 会话列表项类型
首页列表至少包含 3 类会话项：
### 3.1 主 Agent 会话
规则：
- 永远固定在最上面
- 永远视为置顶
- 不允许取消置顶
- 头像使用独立主 Agent 头像
- 最新摘要由主 Agent 汇总生成
展示字段：
- 标题：`主 Agent`
- 摘要：项目汇总、风险提醒、待确认事项
- 时间：主 Agent 最后一次完成汇总的时间
- 标签：`置顶`
### 3.2 单设备项目会话
规则：
- 一个项目当前只由一台设备执行
- 列表头像使用该设备独立头像
- 摘要使用该设备最近一次返回给主控的有效摘要
展示字段：
- 标题：项目名
- 摘要：`设备名 + 最新一句摘要`
- 右侧第一行：若已置顶则显示 `置顶`，未置顶留白
- 右侧第二行：该设备对这个项目的最后回传时间
- 右侧第三行：背景信息窗口余量指示器（圆环进度标记 + 百分比）
### 3.3 多设备协作项目会话
规则：
- 一个项目已经进入多设备协作
- 列表头像使用“组合头像”
- 逻辑上等价于微信中的群聊
展示字段：
- 标题：项目名
- 摘要：`设备A + 设备B + 最新一句协作摘要`
- 右侧第一行：留白，除非用户手动置顶
- 右侧第二行：参与设备中最后一次回传时间的最大值
- 右侧第三行：不显示剩余使用量
---
## 4. 头像规则
### 4.1 单设备头像
每台设备必须有自己独立头像。
建议最小字段：
- `device_id`
- `device_name`
- `device_type`
- `avatar_mode`
- `avatar_color`
- `avatar_label`
- `avatar_asset_url`
优先级：
1. 设备自定义头像
2. 系统生成头像
3. 文本缩写头像
建议默认缩写：
- `Mac Studio` -> `M`
- `Windows GPU` -> `W`
- `Cloud Worker` -> `C`
### 4.2 群聊式组合头像
当项目由多台设备协作时：
- 使用组合头像
- MVP 阶段支持 2 设备叠放头像
- 后续可扩展到 3~4 设备拼接头像
组合规则：
- 2 设备：左右叠放
- 3 设备：主头像 + 右上 / 右下
- 超过 3 台时：显示 2~3 个头像 + `+N`
排序规则：
- 优先主执行设备
- 再按最近活跃度排序
---
## 5. 列表排序规则
首页排序不能只是项目创建时间排序。
排序必须按以下优先级：
1. `主 Agent` 会话，永远第一
2. 用户手动置顶的项目会话
3. 未置顶项目，按 `latest_reply_at DESC`
其中：
- `latest_reply_at` = 该项目参与设备最后一次有效回传时间的最大值
- “有效回传”包括：
- 线程摘要
- 审计结论
- 运维修复结果
- 关键错误 / 告警事件
不应计入：
- 心跳包
- 纯监控噪声日志
- 无内容变化的重复状态刷新
---
## 6. 手动置顶规则
首页必须支持长按会话条置顶。
交互规则：
- 长按普通项目会话 -> 弹出操作菜单
- 菜单包含：
- `置顶`
- `取消置顶`
- `标记已读`
- `查看项目详情`
排序规则：
- 主 Agent 永远第一
- 用户置顶项目在主 Agent 之后
- 多个置顶项目按最近消息时间排序
注意：
- 主 Agent 不允许取消置顶
- 系统需要记录 `manual_pinned = true/false`
---
## 7. 首页列表项最小展示字段
每一条项目会话至少要有：
- `conversation_id`
- `conversation_type`
- `project_id`
- `project_title`
- `avatar_render_model`
- `latest_summary`
- `latest_reply_at`
- `manual_pinned`
- `context_budget_remaining_pct`
- `context_budget_indicator_style`
- `context_budget_level`
- `compaction_expected_at`
- `unread_count`
- `risk_level`
- `active_device_count`
可选增强字段：
- `device_names_preview`
- `audit_pending_count`
- `ops_alert_count`
- `compaction_risk`
- `must_finish_before_compaction`
---
## 8. 建议新增的数据对象
在现有 `projects / threads / thread_events` 之上，建议增加：
- `project_conversations`
- `project_conversation_items`
- `project_conversation_participants`
- `device_avatars`
- `conversation_pin_state`
### 8.1 `project_conversations`
核心字段：
- `conversation_id`
- `project_id`
- `conversation_type` (`master` / `single_device` / `multi_device`)
- `title`
- `latest_summary`
- `latest_reply_at`
- `manual_pinned`
- `sort_bucket`
### 8.2 `project_conversation_participants`
核心字段：
- `conversation_id`
- `device_id`
- `role`
- `is_primary`
- `last_reply_at`
### 8.3 `conversation_pin_state`
核心字段：
- `conversation_id`
- `pin_type` (`system` / `manual`)
- `pinned_by`
- `pinned_at`
---
## 9. 首页 UI 结构
建议结构：
1. 状态栏
2. 页面标题：`会话`
3. 搜索 / 说明条
4. 会话列表
5. 底部导航
会话列表项布局：
- 左侧：头像
- 中间：标题 + 最近摘要
- 右侧：三层信息轨
右侧三层信息轨规则：
- 第一层：`置顶` 标签；若未置顶则保留空白高度
- 第二层：最后一次有效会话时间
- 第三层：背景信息窗口余量指示器
- 群聊型项目会话不展示第三层额度信息
背景信息窗口余量指示器规则：
- 使用统一的小圆环进度标记 + 百分比数字
- 样式和设备端线程页保持一致，不允许手机端自行推导一套不同视觉
- 数据来源于设备端 `worker-daemon` 上报的线程上下文预算，而不是前端本地估算
- 指示器表达的是“当前线程在发生背景信息压缩前，还剩多少可安全使用空间”
- 该值越低，越需要主 Agent 在压缩前完成关键收尾、证据固化和线程交接
视觉要求：
- 更接近微信会话列表
- 不要做成项目管理后台
- 不要把大量设备、审计字段直接塞进首页列表
- 首页只保留最适合“扫一眼决定先点谁”的信息
- 对单设备项目允许展示轻量额度信息，但群聊型项目不显示额度
- 首页中的圆环指示器展示的是“线程上下文预算”，不是账号 5h / 7d 额度，两者不能混用
---
## 10.1 主 Agent 的上下文预算协作逻辑
这部分是整个系统里多线程协作的核心调度信号。
主 Agent 必须持续读取每个线程的：
- `context_budget_remaining_pct`
- `context_budget_level`
- `compaction_expected_at`
- `must_finish_before_compaction`
主 Agent 的默认策略：
- `safe`：`>= 60%`
- 允许继续正常推进任务
- `watch`：`40% ~ 59%`
- 不再给该线程追加大块背景信息
- 要求该线程开始产出阶段摘要
- `urgent`：`25% ~ 39%`
- 主 Agent 应优先让该线程完成当前原子子任务
- 同时预创建下一条接力线程和 handoff 摘要
- `critical`：`< 25%`
- 禁止继续扩张上下文
- 主 Agent 必须优先触发“压缩前收尾”
- 包括：补齐关键结论、未提交 patch、命令记录、测试结论、证据引用、未决问题
压缩前收尾的优先顺序：
1. 当前正在修改但尚未固化的代码和补丁
2. 解释问题所必需的命令、日志、文件路径和测试结果
3. 与下一线程交接有关的关键决策和未决问题
4. 硬件测试 / 多模态审计所需的证据引用
设计原则：
- 不要等发生 compaction 之后再补救
- 主 Agent 必须尽量在 compaction 之前完成关键任务或完成线程交接
- 首页会话列表里的圆环标记，必须能帮助用户和主 Agent 同时感知哪些项目最接近上下文风险边缘
---
## 10. 和整体系统设计的关系
这套首页设计不会改变整体架构，只改变第一屏的信息组织方式。
对应关系如下：
- `projects` 提供项目真相
- `threads` 提供线程真相
- `thread_events` 提供最近事件
- `worker_account_bindings` / `gptpluscontrol` 提供设备与账号状态
- `project_conversations` 负责把这些底层状态重组为“会话列表”
所以：
- 底层仍是多机多线程系统
- 首页表现层收敛成微信式会话列表
- 主 Agent 仍然是总入口
- 项目会话只是“主 Agent 汇总后暴露出来的二级会话壳”
---
## 11. 项目聊天页结构
点击首页任意项目会话后，进入“微信式聊天页”。
聊天页结构固定为：
1. 状态栏
2. 聊天页头部
3. 顶部能力入口
4. 消息流
5. 媒体 / 转发入口
6. 语音 / 文本输入区
页面要求：
- 尽量接近微信聊天详情页的层级和节奏
- 不显示底部 tab bar
- 重点是聊天，而不是后台字段
---
## 12. 顶部两个固定按钮
项目名称下面必须增加两个并列按钮。
布局要求：
- 同一行
- 横向总宽度 100%
- 两个按钮各占一半宽度
按钮定义：
- `项目目标`
- `版本迭代记录`
---
## 13. 项目目标规则
`项目目标` 的生成和维护规则：
- 初始目标由用户和主 Agent 沟通后创建
- 主 Agent 负责整理成结构化目标
- 用户允许手动编辑
- UI 以“圆形单选式完成标记”展示每一条目标
- 用户或主 Agent 将目标标记完成后，目标正文自动加删除线
- 主 Agent 根据项目目标做任务拆解、督促和规划
- 各线程都要以项目目标为约束执行开发和测试
建议数据对象：
- `project_goals`
- `project_goal_revisions`
- `project_goal_items`
- `project_goal_completion_logs`
核心字段：
- `project_id`
- `goal_title`
- `goal_body`
- `goal_order`
- `display_style` (`radio_checklist`)
- `completion_state` (`pending` / `completed`)
- `completed_by`
- `completed_at`
- `source` (`human` / `master_agent`)
- `is_active`
- `edited_by`
- `edited_at`
权限规则：
- 用户可编辑
- 用户可标记目标已完成
- 主 Agent 可整理和建议修改
- 主 Agent 可复核目标完成状态并修正排序
- 普通 worker 线程不能直接改项目目标
### 13.1 项目目标页交互
项目目标页必须明确体现以下交互：
- 每条目标左侧使用圆形单选式完成标记
- 标记完成后，当前目标正文自动加删除线
- 已完成目标显示 `已完成` 状态和完成时间
- 未完成目标显示 `进行中` 或 `待处理`
- 顶部仍保留 `编辑目标` 入口
- `编辑目标` 只允许用户和主 Agent 修改目标内容
- 普通 worker 线程只能读取，不可直接改写
---
## 14. 版本迭代记录规则
`版本迭代记录` 的生成和维护规则：
- 由主 Agent 监督各项目进程
- 定期自动汇报每一个版本号更新的内容
- 主 Agent 负责校验各线程提交上来的版本更新记录是否准确
- 版本迭代记录是只读记录
- 用户不能直接编辑版本记录正文
建议数据对象：
- `version_iteration_reports`
- `version_iteration_sources`
- `version_iteration_reviews`
核心字段：
- `project_id`
- `version_name`
- `change_summary`
- `source_thread_ids`
- `generated_by`
- `verified_by_master`
- `published_at`
权限规则：
- 主 Agent 可生成 / 复核 / 发布
- 用户可查看
- 用户不可直接改正文
- worker 线程只能提交候选更新，不可直接发布
---
## 15. 聊天能力范围
项目聊天页必须支持：
- 文本输入
- 语音输入
- 图片发送
- 视频发送
- 图片 / 视频 / 文本转发到其他聊天窗口
建议最小对象：
- `conversation_messages`
- `message_attachments`
- `message_forwards`
其中：
- `message_attachments` 支持 `image / video / file / voice`
- `message_forwards` 必须记录：
- `source_conversation_id`
- `target_conversation_id`
- `message_id`
- `forwarded_by`
- `forwarded_at`
---
## 16. 设备页规格
设备页对应底部第二个导航项，位置等价于微信的“通讯录”。
功能目标：
- 展示当前已接入设备
- 展示各设备登录账号
- 展示各设备当前运行项目
- 展示各设备剩余额度
- 支持新增设备
- 支持设备管理
### 16.1 页面结构
设备页结构固定为：
1. 状态栏
2. 页面标题：`设备`
3. 右上角 `+ 添加`
4. 长按操作提示
5. 设备列表
6. 底部导航
### 16.2 列表项最小字段
每一台设备至少展示：
- `device_name`
- `device_avatar`
- `account_display_name`
- `running_projects_summary`
- `quota_5h_remaining`
- `quota_7d_remaining`
- `device_status`
### 16.3 设备状态颜色
状态必须显式展示为圆点或小标记：
- 绿色：设备在线
- 红色：设备异常
- 灰色：设备掉线
建议枚举：
- `online`
- `abnormal`
- `offline`
### 16.4 新增设备
交互要求：
- 右上角点击 `+ 添加`
- 打开新增设备流程
- 可进入：
- 新设备绑定
- 登录引导
- token / pairing code 绑定
### 16.5 长按设备
长按任意设备条目，弹出操作菜单：
- `编辑设备名称`
- `编辑设备头像`
- `解绑设备`
### 16.6 建议新增数据对象
建议增加：
- `device_profiles`
- `device_status_snapshots`
- `device_project_bindings`
核心字段建议：
- `device_id`
- `device_name`
- `device_avatar_url`
- `device_type`
- `status`
- `account_id`
- `quota_5h_remaining`
- `quota_7d_remaining`
- `last_seen_at`
---
## 17. 我的页规格
我的页对应底部第三个导航项，位置等价于微信的“我”。
功能目标：
- 展示用户头像
- 展示账号名称
- 展示账号唯一二维码入口
- 展示账号与安全
- 展示设置
- 展示 `运维与修复` 入口
- 展示关于 / 版本号 / OTA 更新
### 17.1 页面结构
我的页结构固定为：
1. 状态栏
2. 用户信息头部
3. 功能列表
4. `关于` 及 OTA 红点
5. OTA 更新内容区
6. 底部导航
### 17.2 头部信息
头部至少展示：
- 用户头像
- 用户昵称 / 显示名
- 当前账号类型
- 右侧 `唯一二维码` 入口
二维码入口呈现规则：
- 放在头部信息卡的最右侧
- 以微信式小二维码图标呈现
- 与头像、昵称、账号类型处于同一个头部单元中
- 不再单独占一行文字说明
### 17.3 账号与安全
账号与安全页项的职责：
- 修改账号密码
- 设备安全管理
- 身份校验
MVP 要求：
- 当前先只冻结入口和字段
- 后续二级页再开发
### 17.4 设置
设置在当前版本只保留一级入口。
规则：
- 先展示
- 暂不开发二级页
### 17.5 关于与 OTA
关于项必须展示：
- 当前版本号
- 若有新 OTA，右侧显示红色 `OTA` 提示
点击后行为：
- 展示 OTA 更新内容
- 可触发 `立即 OTA`
### 17.6 OTA 更新内容区
更新内容区必须包含：
- 目标版本号
- 更新点摘要
- `立即 OTA` 按钮
建议新增数据对象：
- `user_profiles`
- `app_versions`
- `ota_updates`
- `ota_update_logs`
建议字段：
- `current_version`
- `target_ota_version`
- `has_ota_update`
- `ota_update_summary`
- `ota_update_status`
- `ota_triggered_at`
### 17.7 账号认证页
移动端必须补齐 3 个账号认证页面：
- `登录页`
- `注册页`
- `忘记密码页`
认证页规则：
- `登录页` 必须支持账号、密码、登录验证码
- `注册页` 必须支持账号、登录验证码、密码、确认密码
- `忘记密码页` 必须支持账号、登录验证码、新密码、确认新密码
- 3 个页面都要提供 `发送验证码`
- 登录验证码和找回验证码都必须进入后端校验链路
- 登录成功后才允许继续设备绑定与项目同步
- 重置密码成功后，旧设备登录态允许被系统要求重新校验
---
## 18. 已冻结的二级页面
为了避免开发时只做一级页壳子，下面这些二级页也已经纳入 UI 范围：
- `项目目标页`
- `版本迭代记录页`
- `转发到项目页`
- `添加设备页`
- `设备长按操作菜单`
- `账号与安全页`
- `关于 / OTA 页`
- `登录页`
- `注册页`
- `忘记密码页`
这些页面的目标是：
- 保持微信式的导航和扁平视觉
- 不把复杂系统状态直接做成后台面板
- 每个子页面都能对应明确的数据对象和入口来源
- 其中 `运维与修复` 必须作为 `我的` 页里的二级入口，不再作为底部一级导航
- `运维与修复` 内部再分为 `运维对话` 和 `审计对话` 两个子页
---
## 18. UI 上不直接暴露的后台逻辑
虽然聊天页外观接近微信，但底层仍然是多线程系统。
所以：
- 首页看到的是项目会话
- 聊天页看到的是主 Agent 汇总后的项目聊天流
- 底层真实 worker 线程、审计线程、运维线程仍继续工作
- 主 Agent 把底层线程状态整理成适合聊天页展示的消息
换句话说：
`UI 上是聊天，系统里仍然是多线程编排`
---
## 19. 当前 UI 原型对应
当前原型已按这套规则重绘整套核心页面：
- 主 Agent 置顶
- 单设备头像
- 双设备协作头像
- 手动置顶示例
- 会话按最近消息排序
- 项目聊天页双按钮
- 项目目标页圆形完成标记 + 自动划线
- 版本迭代记录只读展示
- 图片 / 视频 / 转发入口
- 语音输入入口
- 设备页第二导航位
- 设备在线 / 异常 / 掉线三种状态
- 右上角添加设备
- 长按设备管理提示
- 我的页第三导航位
- 账号与安全入口
- 设置入口
- 关于 + OTA 红点
- OTA 更新内容卡片
- 登录页 / 注册页 / 忘记密码页
- 登录验证码发送入口
对应文件：
- `/Users/kris/code/UI/.runtime/pencil/threads/ui-codex-ops-mobile/outputs/codex-ops-mobile-v1.pen`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/d5gpt.png`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/g8Qpr.png`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/CwqbE.png`
- `/Users/kris/code/Talking/output/ui-codex-ops-mobile-v13/i7IZ1.png`

531
docs/source-material/研究版成熟方案_设备证书+AI网关+临时密钥+权威计量.md Normal file
View File

@@ -0,0 +1,531 @@
# 研究版成熟方案：设备证书、AI 网关、临时密钥与权威计量
## 1. 文档说明
这份文档是在前面几版方案基础上，结合 2026-03-14 检索到的官方资料，再收敛出来的一版“更成熟、可量产、可商业化”的方案。
这次研究的重点不是再凭经验拼一套架构，而是验证下面几件事：
1. 云厂商是否已经提供更成熟的临时凭证能力
2. 是否已有更成熟的托管网关、会话保持、Fallback、限流和鉴权能力
3. 是否已有更成熟的 authoritative metering（权威计量）与分账模式
4. IoT 行业里设备身份和短期凭证通常如何做
基于调研结果，我认为前面那版“媒体直连 + 任务网关 + 配额账本 + 长任务代理兜底”方向是对的，但还可以继续升级成一版更成熟的：
`设备证书 -> 临时凭证 -> 托管 AI 网关 -> 自建推理接入点 -> 权威计量与分账`
---
## 2. 调研得到的关键事实
## 2.1 火山方舟已经支持“临时 API Key”
在火山方舟管控面 API 中，`GetApiKey` 可以获取临时 API Key，用于在有效期内访问指定资源。
官方文档明确写到：
- 有效期 `DurationSeconds` 范围是 `0-30d`
- 资源类型支持 `endpoint` 和 `bot`
- 可以把授权收敛到指定的接入点或智能体
这说明：
`设备侧拿短期、资源范围受限的访问能力` 不是我们自己拍脑袋想出来的，而是方舟官方已经支持的一种更成熟模式。
## 2.2 火山方舟已经有查询用量和控制台用量统计能力
官方文档中，方舟既有：
- `GetUsage / GetInferenceUsage` 这类用量查询能力
- 控制台的 `用量统计`，支持按天/小时查看输入 tokens、输出 tokens、总 tokens，并可按接入点拆分
这说明：
`最终用量真相应以平台侧计量为准，而不是设备上报为准` 是完全合理且更成熟的落地方式。
## 2.3 火山方舟支持“数据回流”
官方文档说明，针对 `自定义推理接入点`，支持把调用数据（request + response）加密投递到 AI 数据湖；数据可见可能有约 10 分钟延迟。
这说明：
- 数据回流适合做审计、训练、分析、质检
- 不适合做毫秒级实时限额
- 但非常适合作为二级核对和模型优化的数据基础设施
## 2.4 生产级 QPS 建议使用“自建推理接入点”
火山官方在“模型推理接入点保障 QPS”里明确建议：
- 默认公共推理接入点适合试用和调试
- 有较高生产级 QPS 需求时，建议使用自建推理接入点
- 按模型单元计费可获得更高并发和更强确定性
这说明：
如果你要做量产，不应该把核心业务长期压在默认公共资源池上，而应该从一开始就预留：
- 自建接入点
- 主备接入点
- 模型单元 / TPM 保障
## 2.5 火山 API 网关已经具备成熟的网关能力
火山 API 网关官方文档显示，APIG 已经支持：
- HMAC 认证鉴权
- API Key 认证鉴权
- JWT 认证鉴权
- 自建认证鉴权
- 访问限流
- IP 黑白名单
- AI 网关
- AI 多模型代理
- AI 模型 Fallback
- LLM Session 亲和路由
- 全局限流插件
这意味着：
`托管网关 + 会话保持 + Fallback + 限流` 这些能力，不必全部自己从零手撸。
## 2.6 火山方舟高代码应用已经出现“APIG 触发器 + JWT”模式
方舟高代码应用官方文档的 APIG 触发器模式中，调用流程已经出现：
- 通过 APIG 调用
- 使用 JWT token 鉴权
- 适合对独立网关需求更强、对信息传输安全性要求更高的场景
这说明：
`设备先拿短期 JWT，再走托管网关，而不是直接裸连模型服务`，本身就是平台已经在推广的成熟思路。
## 2.7 IoT 领域的成熟模式是“设备证书换临时凭证”
AWS IoT Core 官方文档说明：
- 设备先用 X.509 证书认证
- 然后由 credentials provider 发放 temporary, limited-privilege security token
- 从而避免在设备上保存长期 AK/SK
这说明：
更成熟的设备安全模式不是“给设备发一个长期密钥”，而是：
`每台设备有硬件级或证书级身份，然后再换取短期、低权限凭证`
## 2.8 更成熟的商业计量模式是“权威事件 + Meter + Threshold”
Stripe 官方 usage-based billing 文档里，已经形成一套非常成熟的模式：
- Meter 负责聚合 usage event
- Meter 支持 sum/count/last
- Meter event 可以带 dimensions
- 可以做 usage threshold 和 alerts
这说明：
商业化量产不应该围绕“单个 token 的实时余额”去设计用户产品，而应该围绕：
- entitlement
- included usage
- overage
- threshold alert
- authoritative usage event
来设计。
---
## 3. 研究后的新结论
基于上面的事实，我认为更成熟的方案不是“让设备直接调用方舟文本 API，然后自己用业务 token 切片兜住”。
更成熟的方案应该是：
`设备证书身份 + 临时资源密钥 + 托管 AI 网关 + 自建接入点 + 平台侧权威计量 + 账本分账`
它比前面几版方案更成熟的点在于：
1. 安全模型更像成熟 IoT 平台
2. 网关能力更多利用托管能力而不是自建轮子
3. 计量更多依赖平台 authoritative usage 而不是设备估算
4. 商业化表达更多围绕 entitlement 和 threshold，而不是对用户暴露原始 token
---
## 4. 新版推荐方案
## 4.1 方案名称
`量产成熟版：设备证书 + AI 网关 + 临时 API Key / JWT + 权威计量账本`
## 4.2 方案总览
```text
设备
│
├─ 1. 用设备证书或安全芯片身份登录你的控制服务
│
├─ 2. 控制服务签发短期 JWT 或临时 API Key
│
├─ 3. 设备调用你的 APIG / AI Gateway
│
├─ 4. AI Gateway 做会话保持、限流、Fallback、统一鉴权
│
├─ 5. Gateway 再访问你绑定的方舟自建推理接入点
│
└─ 6. 云侧 usage / 回流 / 账单进入你的计量账本系统
你的服务端
│
├─ 设备身份中心
├─ 临时凭证签发中心
├─ 套餐与 entitlement 中心
├─ 会话中心
├─ 权威计量账本
├─ 风控与审计
└─ 运营与分账后台
```
---
## 5. 为什么这版更成熟
## 5.1 不再把设备当“可信模型客户端”
设备只做两件事：
- 证明“我是谁”
- 使用“短期、可撤销、范围受限”的调用能力
这样设备被逆向时，风险被压缩在：
- 当前短期凭证
- 当前资源范围
- 当前会话
而不是整个平台主能力。
## 5.2 把成熟网关能力拿来用
如果你自己从零实现：
- JWT/HMAC 鉴权
- 限流
- Fallback
- 会话亲和
- 黑白名单
- 路由切换
后面一定会花很多维护成本。
APIG / AI Gateway 已经提供了很多成熟基础设施，更适合量产阶段复用。
## 5.3 用“平台权威计量 + 内部账本”替代“设备估算真相”
成熟做法不是：
- 让设备自己算用了多少，然后服务端信它
成熟做法是：
- 设备估算只用于低水位续权
- 平台权威 usage 用于最终结算
- 内部账本做预占、扣减、释放、调整和审计
## 5.4 更适合商业化
你真正卖给用户的不是 token，而是：
- 月度权益
- 设备数
- 高级功能 entitlement
- 超额阈值
- overage 规则
这个思路和成熟 SaaS 的 usage-based billing 更接近。
---
## 6. 核心架构设计
## 6.1 设备身份层
建议量产设备从出厂开始就有唯一身份。
推荐做法：
- 每台设备一个 `device_id`
- 每台设备一对设备密钥
- 私钥尽量放在安全芯片或安全区
- 服务端保存设备公钥或设备证书链
设备登录时：
- 带设备签名
- 带时间戳
- 带随机 nonce
这样可以防重放和仿冒。
## 6.2 临时凭证层
优先顺序建议如下：
### 方案 A：设备拿短期 JWT，只能调你的 APIG
适用：
- 你希望所有 AI 请求都经过你的网关
- 更重视风控、商业控制和灰度能力
优点：
- 安全边界最清晰
- 最利于统一路由和计量
### 方案 B：设备拿方舟 `GetApiKey` 的临时 API Key，但必须资源绑定
适用：
- 你要让一部分能力更靠近云侧直连
- 但仍不想下发长期主 API Key
要求：
- 严格限制 `ResourceType` 和 `ResourceIds`
- TTL 尽量短
- 必须配合服务端会话状态控制
### 最终建议
量产第一版以 `JWT -> APIG / AI Gateway` 为主，
`临时 API Key` 作为少数场景的增强能力或旁路能力。
原因：
- JWT + APIG 更容易统一治理
- 临时 API Key 更适合当“平台能力”，不适合作为你主要商业控制面的唯一抓手
## 6.3 网关层
网关层建议使用托管 APIG / AI Gateway，而不是完全自研。
网关至少承担：
- JWT / HMAC 鉴权
- session affinity
- route 到不同 endpoint
- fallback 到备用模型
- 全局限流
- 黑白名单
- 灰度发布
## 6.4 模型接入层
建议为生产业务准备：
- 主自建推理接入点
- 备用推理接入点
- 高峰期保障并发的模型单元
不要把量产主链路长期依赖在共享公共资源池。
## 6.5 计量与账本层
推荐采用“双层计量”：
### 第一层：实时业务账本
用于：
- 会话预占
- 低水位续权
- entitlement 校验
- 前台提示
### 第二层：权威计量结算
基于：
- 平台 usage
- 平台账单
- 数据回流
用于：
- 最终扣费
- 差异纠偏
- 财务对账
- 客诉核查
---
## 7. 用户体验策略
## 7.1 续权必须无感
续权动作不要等额度用尽才触发。
建议：
- 低水位阈值 25% 到 35%
- 后台静默续权
- 当前流式任务不断流
## 7.2 长任务一定要有自然边界
长故事、长续写、长播报必须按：
- 句子
- 段落
- 章节片段
来切分租约，而不是按底层 token 生硬截断。
## 7.3 grace quota 必须保留
推荐为每个长任务都保留一个小额 `grace bucket`：
- 不用于常规消耗
- 只用于“把当前片段收完”
这样可以极大改善用户体感。
---
## 8. 商业化设计
## 8.1 面向用户的售卖方式
建议卖：
- 基础包：月度陪伴次数 / 时长
- 故事包：月度故事次数
- 高级包：高质量模型 entitlement
- 家庭包：可绑定设备数
- 企业包：独立配额池 + 分账报表
不要让最终用户直接理解内部 token。
## 8.2 entitlement 与 overage
更成熟的商业模式不是“余额归零就死停”，而是：
- 套餐内含额度
- 额度不足时触发告警
- 到阈值后做降级、限速、限制高级功能或 overage
## 8.3 分账
火山方舟已经给出分账最佳实践，维度包括：
- 账号
- 项目
- 标签
- 配置名称 / 计费单元
- createdBy
你自己的系统里建议同步保留：
- `tenant_id`
- `channel_id`
- `user_id`
- `device_id`
- `plan_id`
- `feature_id`
这样可以同时支持：
- 内部分账
- 渠道结算
- 用户级账单
---
## 9. 我建议的最终落地形态
如果只选一版，我建议你这样做：
### 9.1 主路径
`设备证书 -> 登录控制服务 -> 获取短期 JWT -> 调用 APIG / AI Gateway -> Gateway 调方舟自建 endpoint -> usage 回到账本`
### 9.2 媒体路径
如果场景有 RTC / 实时媒体：
- 媒体流尽量直连云侧
- 会话控制和高价值文本任务仍走你的控制面和网关
### 9.3 临时 API Key 的使用方式
`GetApiKey` 不建议作为所有设备的常规主调用方式。
更建议把它用于：
- 受控的旁路能力
- 少量可信环境
- 特定 bot / endpoint 的短期授权
不要把它变成所有量产设备的常驻主模式。
---
## 10. 这版方案和前面几版的关系
### 相比“设备直连方舟文本 API + 业务切片”
新方案更成熟，因为：
- 更像官方已经支持的临时凭证模式
- 更像成熟 IoT 的设备身份模式
- 更像成熟 SaaS 的权威计量模式
### 相比“全量自研代理网关”
新方案更成熟，因为：
- 充分复用托管 APIG / AI Gateway 能力
- 少造轮子
- 更利于量产阶段运维
### 相比“完全全量代理”
新方案更轻，因为：
- 不必让最重的媒体流全经过你
- 文本与控制流量依然可控
---
## 11. 最终推荐
经过这轮外部调研后，我给你的单一推荐结论是：
`量产成熟版 = 设备证书身份 + 短期 JWT 主路径 + APIG/AI Gateway + 自建方舟接入点 + 平台权威计量 + 内部账本分账`
这版是我目前看下来最平衡的一版：
- 比纯设备直连安全
- 比全量自研网关成熟
- 比完全全量代理更轻
- 比业务 token 切片思路更适合长期商业化
---
## 12. 参考来源
以下是本次收敛时重点参考的官方资料：
1. [火山方舟 GetApiKey - 获取临时 API Key](https://www.volcengine.com/docs/82379/1262825)
2. [火山方舟 管控面 API / 管理 API Key / 查询用量](https://www.volcengine.com/docs/82379/1359520)
3. [火山方舟 用量统计](https://www.volcengine.com/docs/82379/1159199)
4. [火山方舟 数据回流操作流程](https://www.volcengine.com/docs/82379/1528785)
5. [火山方舟 分账最佳实践](https://www.volcengine.com/docs/82379/1884418)
6. [火山方舟 模型推理接入点保障 QPS](https://www.volcengine.com/docs/82379/1330574)
7. [火山 API 网关文档总览（鉴权、限流、AI 网关、Fallback、Session 亲和）](https://www.volcengine.com/docs/6569)
8. [OpenAI Realtime Client Secrets（客户端临时密钥模式）](https://developers.openai.com/api/reference/resources/realtime/subresources/client_secrets)
9. [AWS IoT Core credentials provider（设备证书换短期凭证）](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html)
10. [Stripe Meter 配置](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure)
11. [Stripe Usage Monitor / Threshold](https://docs.stripe.com/billing/subscriptions/usage-based/monitor)

463
docs/source-material/设备直连方舟方案提炼与备选落地方案.md Normal file
View File

@@ -0,0 +1,463 @@
# 设备直连方舟方案提炼与备选落地方案
## 1. 文档目的
这份文档用于沉淀此前关于“设备端直连火山方舟 API / RTC 时，如何做授权、配额、监测、续授权、风控和服务端落地”的讨论结果，并补充几套可执行的备选方案，便于后续做产品决策、技术评审和开发拆分。
适用范围：
- 设备端直接访问大模型或实时交互云服务
- 希望按照用户、设备、套餐做差异化限制
- 既关心用户体感，也关心成本、风控和可运营性
---
## 2. 前面对话的核心结论
### 2.1 已经基本达成共识的判断
1. 云厂商的 `API Key`、平台 `token` 或 RTC 入房 `token`，都不能直接当“每台设备的额度控制器”。
2. 设备端是天然不可信环境，不能把长期主密钥或可无限调用的真实能力长期保存在设备里。
3. 真正的控制应该拆成两层：
- 云厂商鉴权层：只解决“能不能调云服务”。
- 业务授权层：由你自己的服务端控制“这台设备、这个用户、这个套餐此刻还能用多少”。
4. 精确用量不能只靠设备心跳、事件上报或会话时长估算，最终必须用云厂商侧的 `usage`、任务事件、账单或回流数据闭环。
5. 如果续授权做成同步阻塞，长内容生成时一定会卡；如果做成低水位异步预取，用户体感可以做到接近无感。
### 2.2 前面对话里识别出的主要漏洞
1. Token 泄露后，在有效期内可能被滥用。
2. 设备固件可被逆向，设备上报数据可伪造。
3. 如果不做单设备单活会话限制，同一设备可能并发开多个会话。
4. 如果 `/token/request` 一类接口不做风控和限流，容易被刷爆。
5. 如果所有设备在同一时刻续授权，容易产生惊群。
6. 如果授权与真实计费脱钩，会导致账单不可控。
7. 如果把“估算用量”直接拿来做结算，财务和用户侧都会出争议。
### 2.3 前面对话里形成的推荐主方向
推荐的基础方向是：
- 控制面在你自己的服务端
- 推理面或媒体面尽量直连云厂商
- 设备只拿短期业务授权，不拿长期主密钥
- 服务端做配额预占、风控、续权、用量回收和最终结算
这套方向的核心思想可以概括为一句话：
`设备直连推理面，服务端掌控授权面。`
---
## 3. 推荐主方案：控制面在服务端，推理面尽量直连
### 3.1 方案概述
设备在发起一次会话前，先向你的服务端申请“业务授权切片”。
服务端完成设备校验、用户校验、套餐校验、预算预占和风控检查后，再给设备发一个短期授权。
设备拿着这份短期授权去直连方舟 API 或 RTC 服务。
会话过程中，设备根据本次切片预算和实时用量做低水位预警，在快耗尽时后台静默申请下一片。
最终结算不以设备上报为准，而以云侧用量数据回流为准。
### 3.2 为什么推荐这套方案
优点：
- 延迟低，首包和流式输出更接近设备直连
- 服务端带宽压力小，不用全量转发模型输出
- 更容易扩容到 1000 台、1 万台甚至更多设备
- 风控和套餐控制权仍然在你自己手里
缺点：
- 系统设计复杂度高于“纯代理”
- 授权切片、用量回流、续授权、会话状态管理都要自己做
- 不能把设备上报当真，需要额外做闭环和审计
### 3.3 推荐的数据模型
建议至少有下面几类核心表：
1. `device_registry`
- 设备基础信息、激活状态、固件版本、设备指纹、公钥或签名信息
2. `user_subscription`
- 用户订阅档位、有效期、套餐预算、超额策略
3. `device_binding`
- 用户和设备的归属关系、多设备限制、共享规则
4. `session_grant`
- 一次业务授权切片，记录授权预算、过期时间、状态、续权关系
5. `device_session`
- 设备会话生命周期，包含开始时间、最后心跳、关闭原因、会话状态
6. `quota_ledger`
- 预算预占、释放、回补、扣减、人工修正的流水账
7. `vendor_usage_raw`
- 云厂商原始回流数据，按任务、请求或账单粒度保存
8. `device_usage_derived`
- 归因后的设备级、用户级、套餐级统计结果
### 3.4 推荐的授权流程
1. 设备启动会话，请求 `/session/grants/issue`
2. 服务端校验：
- 设备身份
- 用户身份
- 设备归属关系
- 套餐剩余额度
- 当前是否已有活跃会话
- 风控规则是否触发
3. 服务端预占一笔预算
4. 服务端签发短期业务授权切片
5. 设备带切片去直连云服务
6. 设备在低水位时后台请求 `/session/grants/renew`
7. 云侧回流真实用量
8. 服务端做最终扣减、释放未用完的预占额度、落账和统计
### 3.5 推荐的额度控制方式
建议不要只做“单一 token 池”，而是同时做三层配额：
1. 用户总额度
- 代表这个用户在一个计费周期内的总预算
2. 设备子额度
- 防止同一用户多台设备把总额度瞬间打穿
3. 单会话切片额度
- 防止单次长会话在短时间内无限消耗
推荐同时限制以下维度：
- 日预算
- 月预算
- 单次会话最大预算
- 单分钟最大请求次数
- 单设备并发会话数
- 单用户并发设备数
### 3.6 推荐的续授权策略
续授权不要等到额度耗尽再做，建议采用“低水位异步预取”：
1. 初次只发一小片预算
2. 设备本地维护剩余额度估算
3. 当剩余额度低于阈值时，后台静默续片
4. 当前生成链路继续跑，不等待续权结果
5. 下一片到账后无缝衔接
建议阈值：
- 文本生成：剩余 20% 到 30% 时触发
- 语音对话：剩余 30% 到 40% 时触发
- 长故事、长文本类任务：按分段生成边界提前预取
### 3.7 推荐的风控策略
至少做以下规则：
- 单设备单活会话限制
- 单用户同时在线设备数限制
- 单 IP / 单设备 / 单账号的授权请求速率限制
- 异常高频续权检测
- 授权后未消费比例过高告警
- 设备版本黑名单
- 签名失败或时间戳异常直接拒绝
- 同一授权切片重复使用检测
---
## 4. 服务端和设备端的开发边界
### 4.1 服务端应该负责什么
服务端负责：
- 设备注册与激活
- 用户和设备绑定关系
- 套餐和额度管理
- 业务授权切片签发
- 会话生命周期管理
- 用量回流接收和结算
- 风控和审计
- 运营报表和客服排障
服务端不应该依赖设备端做最终结算。
### 4.2 设备端应该负责什么
设备端负责：
- 安全保存设备身份证明和短期授权
- 会话发起和会话结束
- 低水位续授权预取
- 本地缓存当前切片剩余额度估算
- 断网重连和授权失效的兜底逻辑
- 心跳和状态上报
设备端可以做“估算”和“提示”，但不应该成为最终计费真相来源。
---
## 5. 其他有效落地方案
下面这些方案都能落地，只是权衡不同。
### 方案 A：全量代理网关方案
#### 方案定义
设备不直连方舟。所有模型请求先到你的网关，由你的网关统一转发到云厂商。
#### 适用场景
- 你最在意配额控制和审计
- 你需要做内容审核、提示词裁剪、统一缓存、统一日志
- 设备数量暂时不大，或者可以接受增加服务端带宽成本
#### 优点
- 控制力最强
- 真实用量和业务扣费天然更容易对齐
- 最容易做黑名单、限流、熔断和回放审计
- 不需要把云厂商调用能力直接暴露给设备
#### 缺点
- 服务端流量和带宽成本明显上升
- 首包和流式链路会多一跳
- 需要处理更多高并发连接和转发问题
#### 推荐度
如果你当前最担心的是“被刷爆”和“账单不可控”，这是最稳的方案。
---
### 方案 B：双通道混合方案
#### 方案定义
短请求、常规请求走设备直连。
长故事、长文本、长语音、多轮复杂任务走你的代理网关。
#### 适用场景
- 想兼顾用户体感和强控制
- 任务类型差异很大
- 部分任务天然更容易超预算或更需要审计
#### 优点
- 兼顾速度和控制
- 高风险场景可切到可控链路
- 能把最贵、最不稳定的任务单独隔离
#### 缺点
- 路由逻辑变复杂
- 设备端和服务端都要知道“什么时候切换通道”
- 运营和排障会比分单一路径稍复杂
#### 推荐做法
可以把以下任务默认走代理：
- 长故事生成
- 长时语音陪伴
- 需要强审计的企业客户任务
- 高价值套餐用户的高级功能
---
### 方案 C：边缘接入节点方案
#### 方案定义
设备不直接连中心控制服务，而是先连最近的区域接入节点。
接入节点负责授权校验、会话保持、低延迟续权和短期缓存；中心服务负责总账和全局策略。
#### 适用场景
- 设备分布地域广
- 网络质量不稳定
- 对低延迟和高在线率要求高
#### 优点
- 授权和续权时延更低
- 对弱网和抖动更友好
- 可缓解中心服务压力
#### 缺点
- 系统复杂度更高
- 要做多节点状态同步
- 部署和运维成本增加
#### 什么时候值得上
当你设备规模较大，且终端网络质量参差不齐时，这个方案很有价值。
---
### 方案 D：套餐桶包方案
#### 方案定义
不是每次都按精细 token 去分，而是先把套餐设计成“桶包”。
例如：
- 基础版：每月 300 次短对话
- 标准版：每月 1000 次中等对话
- 高级版：每月 300 次长故事生成
服务端内部再把每类任务映射成预算扣减规则。
#### 适用场景
- 你现在还不想让用户看到复杂的 token 概念
- 你希望先快速商业化
- 你的业务更适合卖“能力包”而不是卖“token”
#### 优点
- 产品表达清晰
- 用户更容易理解
- 客服和销售更容易沟通
#### 缺点
- 需要你自己维护任务到成本的映射
- 某些边界场景会有估算误差
#### 推荐度
如果你短期内更想先做商业闭环，这是非常有效的落地方案。
---
### 方案 E：企业租户隔离方案
#### 方案定义
针对 B 端、渠道商或大客户，给每个租户单独做配额池、单独风控策略，必要时单独接入点、单独结算域。
#### 适用场景
- 有渠道商、OEM、品牌合作方
- 需要租户级对账
- 需要更强的安全隔离和 SLA
#### 优点
- 财务和运营边界清晰
- 某租户异常不会拖垮全部业务
- 易于做分账和差异化商务策略
#### 缺点
- 配置和运维复杂度增加
- 需要更好的控制台和运维体系
#### 推荐度
如果未来会走 B2B2C，这是很值得提前预留的架构方向。
---
## 6. 各方案对比
| 方案 | 用户体感 | 控制力 | 实施复杂度 | 服务端成本 | 推荐场景 |
| --- | --- | --- | --- | --- | --- |
| 控制面在服务端，推理面直连 | 高 | 高 | 中高 | 低到中 | 当前最平衡的主方案 |
| 全量代理网关 | 中 | 很高 | 中 | 中到高 | 最重视安全和结算闭环 |
| 双通道混合 | 高 | 高 | 高 | 中 | 想同时兼顾体感和强控制 |
| 边缘接入节点 | 很高 | 高 | 很高 | 中到高 | 多地域、大规模、弱网 |
| 套餐桶包 | 高 | 中 | 中 | 低到中 | 先做商业闭环 |
| 企业租户隔离 | 中到高 | 很高 | 高 | 中到高 | B 端或渠道业务 |
---
## 7. 我对落地顺序的建议
如果要尽快做出第一版可上线系统，建议按下面顺序推进：
### 第一阶段：先把主方案做出来
先实现：
- 设备注册和激活
- 用户与设备绑定
- 套餐总额度
- 单会话授权切片
- 单设备单活会话
- 低水位异步续权
- 云侧用量回流
- 账本式扣减
### 第二阶段：补风控和运营能力
补上：
- 刷授权风控
- 异常续权检测
- 黑名单和熔断
- 设备版本治理
- 对账报表
- 人工纠偏工具
### 第三阶段：按业务形态选择备选方案
根据业务方向再补：
- 想更稳：增加全量代理通道
- 想更快：增加边缘接入节点
- 想更好卖：增加套餐桶包表达
- 想做渠道：增加租户隔离
---
## 8. 最终建议
如果你现在的目标是“尽快做出能上线、能控成本、体感也不错的一版”，我建议选择：
`主方案 + 套餐桶包表达`
也就是：
1. 技术底层用“控制面在服务端，推理面尽量直连”
2. 产品层面对用户不直接卖 token，而是卖套餐额度和能力包
3. 结算层内部仍然用真实用量和预算账本做闭环
这样做的好处是：
- 技术上能控住
- 运营上讲得清
- 用户侧更容易理解
- 后续还能平滑切到双通道或企业租户隔离
---
## 9. 建议的后续产出
下一步建议继续补这四类文档：
1. 接口定义文档
- `issue grant`
- `renew grant`
- `heartbeat`
- `close session`
- `usage callback`
2. 时序图文档
- 首次授权
- 异步续权
- 断网重连
- 授权失败兜底
3. 数据库设计文档
- 表结构
- 索引
- 状态机
4. 风控策略文档
- 限流规则
- 黑名单
- 人工处置流程
如果后续继续往下做，建议优先把“接口定义 + 时序图 + 账本模型”补齐，这三样最直接影响开发能不能落地。

768
docs/source-material/量产版综合解决方案_媒体直连任务网关账本结算.md Normal file
View File

@@ -0,0 +1,768 @@
# 量产版综合解决方案：媒体直连、任务网关、账本结算与代理兜底
## 1. 文档定位
这份文档是基于前面讨论进一步收敛出来的一版“量产优先”的综合方案。
目标不是追求理论上最轻，而是在下面几个维度同时拿到更好的平衡：
- 开发更便捷
- 安全性更高
- 更适合商业化和量产
- 不明显影响用户体感
- 服务器压力尽量小
这份方案相对于“设备直接调用方舟文本 API + 业务 token 切片”的版本，做了一个关键收敛：
`不让设备长期持有可直接消费方舟文本推理能力的真实主能力。`
也就是说：
- 媒体面尽量直连云侧
- AI 任务面由你的服务端托管
- 配额、续权、计量、结算由你的服务端统一掌控
- 长任务保留代理通道做兜底
---
## 2. 最终推荐结论
如果你要做量产交付，我建议采用这一版架构：
`媒体直连 + 任务网关 + 配额账本 + 长任务代理兜底`
一句话解释：
1. 设备可以直连低延迟媒体链路
2. 设备不直接持有长期方舟文本 API 能力
3. 所有高价值 AI 任务由你的服务端创建、放行、续权、停止和结算
4. 用户侧卖套餐能力，不直接卖 token
5. 用量以云侧回流为最终结算依据
这是我认为更适合商业化量产的原因：
- 对设备端更友好，开发边界更清晰
- 对服务端更可控，后续改套餐和风控不用动设备协议
- 对用户体感更稳，可以做自然边界续写和无感续权
- 对财务和运营更友好，能做账本、对账、客服排障和渠道分账
---
## 3. 为什么不直接沿用网页最后那套方案
网页最后那套方案的核心优点是：
- 链路短
- 服务器流量小
- 设备直连，用户体感好
但量产时它有四个硬伤：
### 3.1 设备端不可信
只要设备能直接消费方舟文本能力，理论上就总会面临：
- 固件被逆向
- 协议被重放
- 授权被抽取
- 请求被伪造
- 套餐控制被绕过
### 3.2 开发复杂度其实不低
看起来是“直连更轻”，但如果真的要补齐：
- 细粒度计量
- 低水位续权
- 中断恢复
- 长故事续写
- 用量回补
- 审计和客服排障
设备端和服务端两边都会变复杂。
### 3.3 商业化边界不够清晰
一旦你要支持：
- 不同套餐
- 多设备共享
- 家庭账户
- 渠道/OEM
- 试用版与正式版
- 企业版和标准版
“设备直连 + 业务 token 切片”会越来越难维护。
### 3.4 结算闭环不够硬
真正能拿来做最终扣费和纠纷处理的，不能是设备估算，必须是云侧真实用量。
如果设备可以绕开你的任务控制面，后续审计很容易出灰区。
---
## 4. 设计目标与非目标
### 4.1 设计目标
1. 用户说话和收听时延保持低
2. 套餐额度、续权和停用由你自己掌控
3. 设备端协议尽量稳定，后续套餐和规则升级尽量不改设备逻辑
4. 结算必须可追溯、可回放、可纠偏
5. 支持 1000 台到 1 万台设备平滑扩展
6. 支持后续做渠道版和企业版
### 4.2 非目标
1. 不追求所有能力都完全绕开服务端
2. 不追求把所有 token 精确暴露给最终用户
3. 不追求第一版就做极致复杂的租户隔离
---
## 5. 方案全貌
```text
设备
│
├─ 1. 设备认证 / 会话启动 / 续权 / 心跳
│ 走你的任务网关
│
├─ 2. RTC / 音频 / 媒体
│ 尽量直连云侧
│
└─ 3. 文本生成 / 故事生成 / 高价值任务
走你的任务网关或代理通道
你的服务端
│
├─ 设备身份中心
├─ 用户与套餐中心
├─ 任务网关
├─ 续权中心
├─ 配额账本
├─ 风控中心
├─ 用量归因与结算中心
└─ 运营与报表后台
云侧
│
├─ RTC / 媒体服务
├─ 方舟模型服务
└─ usage / task / bill 回流能力
```
---
## 6. 核心设计原则
### 6.1 媒体和任务分离
不要把“低延迟媒体链路”和“高价值 AI 计费链路”混成一个面。
建议划分：
- 媒体链路：尽量直连，追求低延迟
- 任务链路：服务端托管，追求控制权
### 6.2 设备侧只保存短期能力
设备最多保存：
- 设备身份凭证
- 当前会话的短期租约
- 当前任务的临时句柄
设备侧不应该保存：
- 长期主 API Key
- 可跨任务复用的高价值主能力
### 6.3 套餐卖能力，不卖底层计费单位
对用户展示：
- 月度陪伴时长
- 月度故事次数
- 高级模型次数
- 家庭共享设备数
内部映射：
- 预算单位
- 账本流水
- 云侧真实成本
### 6.4 真正的结算只认云侧回流
设备侧心跳和事件上报只能辅助判断：
- 在线状态
- 故障定位
- 体验追踪
不能拿来做最终结算真相。
---
## 7. 核心对象模型
### 7.1 设备身份
用于唯一识别一台量产设备。
建议字段：
- `device_id`
- `product_id`
- `firmware_version`
- `device_public_key`
- `activation_status`
- `risk_level`
### 7.2 用户订阅
用于控制套餐和可用能力。
建议字段：
- `user_id`
- `plan_id`
- `plan_start_at`
- `plan_end_at`
- `monthly_budget_units`
- `daily_budget_units`
- `max_active_devices`
- `max_active_sessions`
### 7.3 会话
一段连续的用户使用周期。
建议字段：
- `session_id`
- `device_id`
- `user_id`
- `session_type`
- `status`
- `started_at`
- `last_seen_at`
- `closed_at`
- `close_reason`
### 7.4 任务租约
这是这套方案的核心对象。
它不是云厂商 token，而是你自己的业务租约。
建议字段：
- `lease_id`
- `session_id`
- `user_id`
- `device_id`
- `task_type`
- `granted_units`
- `consumed_units_estimate`
- `soft_threshold`
- `hard_threshold`
- `grace_units`
- `expires_at`
- `state`
### 7.5 账本流水
所有额度变化必须流水化，而不是只存一份余额。
流水类型建议：
- `reserve`
- `consume`
- `release`
- `grace_consume`
- `refund`
- `manual_adjust`
- `settlement_delta`
---
## 8. 架构分层
## 8.1 设备侧模块
设备端建议只保留下面这些稳定模块：
1. 设备身份模块
- 保存设备身份和短期租约
2. 会话管理模块
- 开始、续权、结束、重连
3. 媒体模块
- 处理音频输入输出
4. 本地缓存与播放模块
- 缓冲流式文本、缓冲 TTS 播放
5. 状态上报模块
- 心跳、弱网状态、任务阶段
设备端不要自己做：
- 复杂套餐计算
- 最终结算
- 风控决策
- 多租户逻辑
## 8.2 服务端模块
### A. 设备身份中心
负责：
- 设备注册
- 激活
- 黑名单
- 固件版本治理
### B. 用户与套餐中心
负责：
- 订阅档位
- 套餐预算
- 设备绑定
- 家庭共享
- 试用和正式套餐切换
### C. 任务网关
负责：
- 会话启动
- AI 任务创建
- 模型路由
- 文本流式输出代理
- 任务停止与取消
### D. 续权中心
负责：
- 低水位续租
- 授权回收
- 租约失效
- 自然边界停机
### E. 配额账本
负责：
- 预算预占
- 实时估算扣减
- 最终结算
- 退款和纠偏
### F. 风控中心
负责：
- 单设备单活会话
- 请求速率限制
- 异常续权检测
- 风险分级处理
### G. 用量归因中心
负责：
- 接收云侧 usage 回流
- 归因到用户、设备、会话、任务
- 和账本做差异修正
---
## 9. 核心流程设计
## 9.1 设备激活
1. 设备首次启动，调用 `/device/activate`
2. 服务端下发设备身份和初始化配置
3. 设备绑定用户
4. 建立设备和用户关系
结果：
- 后续所有会话都可以挂到 `device_id + user_id` 上
## 9.2 开始一次会话
1. 设备调用 `/sessions/open`
2. 服务端校验：
- 设备有效
- 用户有效
- 套餐有效
- 当前并发不超限
- 风控未触发
3. 服务端创建 `session`
4. 服务端预占一笔预算
5. 服务端签发第一段 `lease`
6. 设备拿到可用会话句柄开始交互
## 9.3 正常生成
短任务流程：
1. 设备把请求发到你的任务网关
2. 任务网关决定模型、上下文、预算和任务类型
3. 任务网关调用云侧模型
4. 服务端把流式文本回给设备
5. 设备边播边显示
为什么这里不直接让设备调用云侧文本 API：
- 服务端才能稳定插入套餐控制
- 服务端才能统一做日志和风控
- 文本流量很小，代理成本远低于媒体流代理
## 9.4 低水位续租
设备本地不做最终计费，但可以做“估算预警”。
建议策略：
1. 当前租约只发一小段预算
2. 设备端收到服务端回传的预算阈值
3. 消费逼近低水位时，后台调用 `/leases/renew`
4. 服务端再次检查套餐余额和风险状态
5. 若可续，则下发下一段租约
6. 当前任务不阻塞
## 9.5 长故事续写
长故事和长文本不要按“耗尽就停”处理，而要按自然边界处理。
建议流程：
1. 服务端把故事拆成片段目标
2. 每一片都有独立租约预算
3. 到片尾或句尾时判断是否续租
4. 续租成功则继续下一片
5. 续租失败则在当前片自然结束时收口
这样用户的感知会明显更好。
## 9.6 grace quota 机制
为了避免“生成到一半突然断”，建议每个高价值任务都预留一小段 `grace_units`。
含义：
- 正常额度用完后，不立刻砍掉
- 允许把当前句、当前段或当前故事片收完
- 收完后再提示继续购买或等待下周期恢复
这部分一定要小，避免被长期滥用。
## 9.7 异常中断与重连
设备断网时：
1. 设备缓存最近的 `session_id` 和 `lease_id`
2. 恢复后调用 `/sessions/resume`
3. 服务端判断：
- 会话是否仍有效
- 租约是否仍有效
- 是否需要补发一段租约
## 9.8 结束与结算
1. 任务完成或用户主动结束
2. 设备调用 `/sessions/close`
3. 服务端标记会话结束
4. 云侧 usage 回流到服务端
5. 用量归因中心做最终结算
6. 账本释放未用完预占
7. 记录最终账单明细
---
## 10. 用户体验设计原则
## 10.1 不把续权做成显式动作
不要让用户看到：
- “正在续费中”
- “额度同步中”
- “请等待 token 刷新”
用户侧应该只感知：
- 正常继续
- 自然结束
- 结束后再提示套餐不足
## 10.2 所有中断都尽量在自然边界发生
自然边界包括：
- 一句话结束
- 一段故事结束
- 一轮语音回复结束
- 一个章节结束
## 10.3 设备侧必须有最小缓冲
为了避免轻微抖动造成体感卡顿，设备侧要有：
- 流式文本缓冲
- TTS 音频缓冲
- 最近一次租约状态缓存
## 10.4 续权失败的用户提示
不要提示“token 不足”。
建议提示业务语言：
- “本月故事额度已用完”
- “当前套餐已达上限”
- “请升级套餐继续使用”
---
## 11. 安全设计
## 11.1 基线原则
1. 设备不保存长期方舟主密钥
2. 所有租约都短期有效
3. 每次请求都有唯一 `request_id`
4. 设备请求必须带签名和时间戳
5. 所有可重放请求都要有去重机制
## 11.2 强制做的风控规则
- 单设备单活会话
- 单用户并发设备数限制
- 单 IP / 单设备 / 单账号速率限制
- 短时间异常高频续租熔断
- 固件版本黑名单
- 风险设备强制切代理通道
## 11.3 审计能力
至少保留以下审计链：
- 设备请求日志
- 会话启动日志
- 租约签发日志
- 云侧任务日志
- usage 回流日志
- 最终结算流水
这样客服和财务才能查账。
---
## 12. 商业化设计
## 12.1 用户侧套餐表达
建议对用户卖下面这些能力包：
- 基础版：短问答 + 基础陪伴
- 标准版：更多陪伴时长 + 更多故事次数
- 高级版：长故事、优先模型、更高并发家庭设备数
- 企业版：独立策略、独立配额池、独立报表
## 12.2 内部结算单位
内部不要只用一个 token 概念，建议统一成 `budget_units`。
映射规则举例：
- 1 次短问答 = X units
- 1 分钟语音陪伴 = Y units
- 1 次长故事片段 = Z units
真实云侧成本回来后，再做误差校准。
## 12.3 渠道/OEM 预留
从第一版就建议预留：
- `tenant_id`
- `channel_id`
- `plan_catalog`
- `billing_group`
这样以后做渠道版不用重构核心账本。
---
## 13. 数据模型建议
建议至少落下面这些表：
1. `device_registry`
2. `device_binding`
3. `user_subscription`
4. `plan_catalog`
5. `session`
6. `lease`
7. `quota_ledger`
8. `vendor_task`
9. `vendor_usage_raw`
10. `usage_settlement`
11. `risk_event`
12. `ops_adjustment`
### 核心关系
- 一个用户可以绑定多台设备
- 一台设备同一时刻只允许一个活跃主会话
- 一个会话可以有多段租约
- 多段租约统一归并到一次最终结算
---
## 14. 接口建议
第一版建议只做下面这组接口。
### 设备侧接口
- `POST /device/activate`
- `POST /device/login`
- `POST /sessions/open`
- `POST /sessions/heartbeat`
- `POST /leases/renew`
- `POST /sessions/close`
- `POST /sessions/resume`
### 云侧回调接口
- `POST /vendor/callback/task`
- `POST /vendor/callback/usage`
- `POST /vendor/callback/bill`
### 运营后台接口
- `POST /ops/device/blacklist`
- `POST /ops/session/terminate`
- `POST /ops/quota/adjust`
- `GET /ops/user/usage`
- `GET /ops/device/history`
---
## 15. 服务器压力控制思路
这套方案比全量代理轻，原因在于：
1. 媒体流不走你的服务端
2. 文本流量远小于音频/视频流量
3. 账本、续权、风控都是轻量 JSON 请求
4. usage 回流是异步的，不阻塞主链路
推荐压测关注点：
- `sessions/open`
- `leases/renew`
- 流式文本转发连接数
- usage 回调写库速度
- Redis 热键和并发锁
推荐基础组件：
- API 网关
- 应用服务
- Redis
- MySQL 或 PostgreSQL
- MQ
- 对象存储
- 可观测系统
---
## 16. 分阶段落地建议
## 第一阶段：可上线 MVP
先做：
- 设备激活
- 用户绑定
- 套餐档位
- 会话启动
- 低水位续租
- 单设备单活会话
- usage 回流
- 账本结算
## 第二阶段：量产增强
再补：
- 渠道/OEM
- 家庭账户
- 黑名单和熔断
- 运营后台
- 套餐促销和试用
## 第三阶段：企业化
最后补：
- 租户隔离
- SLA 分层
- 独立报表
- 分账能力
---
## 17. 这套方案最适合什么业务阶段
最适合：
- 正准备量产
- 需要卖套餐
- 设备长期在线
- 既有实时语音，也有高价值文本任务
- 后面可能要做渠道和企业客户
不那么适合：
- 纯内部测试 Demo
- 完全不考虑商业化
- 完全不在意设备破解风险
---
## 18. 最终建议
如果你要我给一个量产优先的单一结论，我的建议就是：
`不要做设备长期直连方舟文本 API。`
而要做：
`媒体直连 + 任务网关 + 配额账本 + 长任务代理兜底`
这是当前最平衡的一版：
- 比全量代理轻
- 比纯直连稳
- 比“设备直连 + 业务 token 切片”更适合量产和商业化
---
## 19. 后续建议继续补的文档
如果继续往下推进，下一批建议补：
1. 接口字段定义文档
2. 会话与租约状态机
3. 数据库表结构草案
4. 用户套餐与账本扣费规则
5. 异常流程和兜底时序图
6. 风控规则清单
这六样补齐后，就可以直接拆给开发排期了。

501
docs/source-material/顶级实时数字人_券后采购建议与全流程预算_v2.md Normal file
View File

@@ -0,0 +1,501 @@
# 顶级实时数字人：券后采购建议与全流程预算 v2
更新时间：2026-03-25
## 1. 这次重算后的核心结论
按你这次提供的活动页截图，券价已经明确：
- `HAI 8 小时使用券`：`1 元`
- `HAI 80 小时使用券`：`75 元`
- `HAI 250 小时使用券`：`225 元`
结合腾讯官方使用说明，这些券：
- 只适用于 `后付费 HAI 实例`
- 会被系统 `自动抵扣`
- `8 小时券` 有效期 `30 天`
- `80 / 250 小时券` 有效期 `90 天`
- 活动页明确写的是：这三种券都用于 `GPU 基础型算力套餐`
所以这次重算后的最重要结论是：
**1. 不要用 HAI 做前期爬虫。**
原因不是功能不行，而是 `经济性和效率都不划算`：
- HAI 基础型是 `1.2 元/小时起`
- 爬虫/下载/去重/元数据整理主要是 `网络 + CPU + 存储`，不是 GPU 问题
- 云上机房 IP 抓国内视频站点，往往比你本地/住宅网络更容易触发风控
所以最优策略是：
- `爬虫阶段`：本地电脑，或者便宜 CPU 机器
- `GPU 阶段`：只在进入姿态提取、面部裁切、数字人渲染、TTS 训练时再开 HAI
**2. 券的购买顺序，不是“越大越好”，而是看阶段。**
- `8 小时券`：一定买，性价比最高
- `80 小时券`：最灵活，适合首轮项目
- `250 小时券`：最适合已经确定自己会长期跑、或者要双机并行的人
**3. 对你当前项目，经济性和效率综合最优的主方案是：**
- 前期爬虫：`不用 HAI`
- 第一阶段 GPU：`1 台 HAI 基础型 16GB`
- 第二阶段短时冲刺：`按量加 1 台 HAI 进阶型 32GB`
- 券的购买建议：
- 如果先求稳：`8 小时券 + 2 张 80 小时券`
- 如果已经确定素材量大、要双机并行：`8 小时券 + 1 张 250 小时券`
## 2. 券的真实经济性
### 2.1 等效小时成本
- `8 小时券`：`1 / 8 = 0.125 元/小时`
- `80 小时券`：`75 / 80 = 0.9375 元/小时`
- `250 小时券`：`225 / 250 = 0.9 元/小时`
对比基础型原价 `1.2 元/小时`：
- `8 小时券`：极便宜，但只能买 1 张
- `80 小时券`：比原价便宜约 `21.9%`
- `250 小时券`：比原价便宜约 `25%`
所以：
- `灵活性最好`：`80 小时券`
- `大规模最划算`：`250 小时券`
### 2.2 券组合怎么选
#### 组合 A：`8h + 80h`
- 总价：`76 元`
- 总时长：`88 小时`
- 适合：
- 第一次试跑
- 原始视频量还不确定
- 先跑一轮姿态提取和小规模训练
#### 组合 B：`8h + 80h + 80h`
- 总价：`151 元`
- 总时长：`168 小时`
- 适合：
- 40 小时左右原始视频
- 单机完成 bulk 清洗
- 有一定试错空间
#### 组合 C：`8h + 250h`
- 总价：`226 元`
- 总时长：`258 小时`
- 适合：
- 已明确会做完整项目
- 计划双机并行
- 原始视频量大于 `80~100 小时`
#### 组合 D：`250h + 80h`
- 总价：`300 元`
- 总时长：`330 小时`
- 适合：
- 素材非常多
- 需要双机跑较长时间
- 项目已经进入稳定实施阶段
### 2.3 一个关键判断
如果你的预算已经来到 `226 元` 左右：
- 不要买 `8h + 80h + 80h + 80h`
- 直接买 `8h + 250h`
因为两者现金支出几乎一样：
- `8 + 3*80 = 248 小时，226 元`
- `8 + 250 = 258 小时，226 元`
同样的钱，`250 小时券` 多给你 `10 小时`。
## 3. 把“爬虫阶段”单独拆开后，最优流程是什么
这个项目最容易花冤枉钱的地方，就是把“采集”也放进 GPU 预算里。
实际最优做法是三段式：
### 3.1 第一段：源站发现
目标：
- 先找到所有候选视频链接
- 不急着全量下载
这一段做什么：
- 搜索平台内公开视频
- 抓标题、链接、封面、时长、发布时间、播放量、UP 主信息
- 建一个素材总表
这一段最优资源：
- `本地电脑`
- 或 `便宜 CPU 机器`
不需要 HAI。
### 3.2 第二段：选择性下载
目标：
- 只下载高价值素材
推荐规则：
- 优先下载：
- 清晰正脸
- 单人主讲
- 音乐少
- 语速自然
- 机位稳定
- 暂时不下载：
- 纯搬运混剪
- 远景多
- 背景音重
- 第三人频繁插话
这样做的好处是：
- 大幅减少后面 GPU 处理量
- 存储压力更小
- 动作提取质量更高
### 3.3 第三段：GPU 清洗和训练
这一段才轮到 HAI 出场：
- 人脸检测与裁切
- 姿态提取
- 手势切片
- 动作标签
- TTS 训练预处理
- 实时数字人渲染调试
## 4. 我建议你买几台、买什么配置
### 4.1 爬虫阶段
**结论：不要买 HAI 来做爬虫。**
最经济高效的方案是：
- `本地电脑` 跑采集和下载
- 如果你不想占本机，就用 `廉价 CPU 云机`
原因：
- 爬虫不吃 GPU
- HAI 的 GPU 基础型 `1.2 元/小时`，拿来跑下载器和转存，非常浪费
- 本地网络往往比云机房 IP 更适合抓公开视频
### 4.2 GPU 处理阶段：推荐机型
#### 主力机
- `HAI 基础型 16GB`
用途：
- bulk 视频清洗
- 人脸裁切
- 姿态/手势提取
- 初步数字人推理
原因：
- 券只适用于这一档
- 这档是你整个项目里性价比最高的 GPU
#### 冲刺机
- `HAI 进阶型 32GB`
用途：
- 更重的训练
- 更吃显存的推理
- 实时数字人联调
原因：
- 32GB 更稳
- 但不享受这些券
- 所以只建议在需要时短时开机
### 4.3 台数建议
#### 最省钱方案
- `1 台基础型 16GB`
- `需要时临时开 1 台进阶型 32GB`
这是当前最稳的默认方案。
#### 最平衡方案
- 常态：`1 台基础型 16GB`
- bulk 清洗高峰期：`临时再开 1 台基础型 16GB`
- 冲刺训练：`需要时再开 1 台进阶型 32GB`
这是我认为最适合你的方案。
#### 不建议方案
- 一上来就长期开两台或三台 HAI
原因：
- 你前期很多时间都会花在：
- 采集
- 整理
- 过滤
- 标注
- 这些阶段 GPU 利用率并不高
## 5. 基于你这个项目的实际预算重算
下面按一个更贴近你项目的现实版本来估：
- 原始候选视频：`80~120 小时`
- 最终下载入库：`30~50 小时`
- 其中高价值黄金语料：`3~5 小时`
### 5.1 爬虫与下载阶段
#### 方案 1：本地跑
- 增量 GPU 成本：`0`
- 增量云成本：`0`
这是最推荐的。
#### 方案 2：便宜 CPU 云机跑
- 只建议当你不想占用本机时用
- 这一部分不要放在 HAI 预算里
这里我不把它强行写死进总预算，因为你完全可以本地跑掉。
### 5.2 GPU 基础型预算
按更经济的做法，基础型只承担真正需要 GPU 的环节：
- 姿态提取 / 动作切片：`20~35 小时`
- 人脸裁切 / 素材筛选：`15~25 小时`
- 初步数字人推理 / 回归：`10~20 小时`
合计更现实的基础型需求：
- `45~80 小时`
这意味着：
**如果你控制得好，第一轮甚至 `8h + 80h = 88 小时` 就够。**
### 5.3 进阶型预算
进阶型只留给真正重负载环节：
- TTS 训练试错
- 更高显存的实时联调
建议预算：
- `10~20 小时`
- 成本：`36~72 元`
### 5.4 阿里 API 预算
只把高价值部分交给阿里：
- `SenseVoice` 精修 `3~5 小时黄金语料`：约 `7.56~12.6 元`
- 在线 ASR / RAG / LLM 调试预留：`20~40 元`
建议按：
- `30~50 元`
预留。
### 5.5 MiniMax 对照预算
如果只做小规模对照：
- 1 个音色克隆
- 少量 HD 文本测试
建议按：
- `20~40 元`
预留。
## 6. 最终采购建议
### 6.1 我最推荐的采购顺序
#### 第一步
- 买 `8 小时券 x1`
- 买 `80 小时券 x1`
总支出：
- `76 元`
用途：
- 先完成第一轮 bulk GPU 清洗
- 看真实素材量和 GPU 消耗速度
为什么这样买：
- 成本最低
- 足够完成第一轮验证
- 不会过早把钱压进 250 小时券
#### 第二步
如果第一轮下来你确认：
- 视频素材多
- 动作库要做深
- 需要第二轮或第三轮试错
再补：
- `80 小时券 x1`
这时总预算来到：
- `151 元`
- 可用基础型时长：`168 小时`
这个组合是当前最稳的中档方案。
#### 第三步
如果你已经确认：
- 项目会长期推进
- 素材量大
- 很可能双机并行
那么后续就不要继续堆 `80 小时券` 了，直接改买：
- `250 小时券`
### 6.2 什么时候直接买 250 小时券
满足下面任意两条，我就建议你直接上 `250 小时券`：
- 你确定会收集 `100 小时以上` 原始视频
- 你确定会开 `2 台基础型` 并行清洗
- 你确定这个项目不是试验，而是要落地
- 你希望未来 90 天内持续迭代
### 6.3 我的最终推荐
按你当前描述，我的最终建议不是一口气买满，而是：
#### 方案 A：当前最优默认方案
- 爬虫：`本地电脑`
- HAI：
- `基础型 16GB x 1`
- `进阶型 32GB x 0（按需开）`
- 券：
- `8 小时券 x1`
- `80 小时券 x1`
适合：
- 先把第一轮素材链路跑通
- 最低成本验证真实消耗
#### 方案 B：我最推荐的平衡方案
- 爬虫：`本地电脑`
- HAI：
- 常态 `基础型 16GB x 1`
- 高峰期 `基础型 16GB x 2`
- 训练冲刺 `进阶型 32GB x 1（临时）`
- 券：
- `8 小时券 x1`
- `80 小时券 x2`
适合：
- 真正开始做老师数字人
- 既看成本，也看效率
这是我当前最推荐的方案。
#### 方案 C：已明确长期投入方案
- 爬虫：`本地电脑 + 便宜 CPU 机器（可选）`
- HAI：
- `基础型 16GB x 2`
- `进阶型 32GB x 1（按需）`
- 券：
- `8 小时券 x1`
- `250 小时券 x1`
适合：
- 素材量大
- 双机并行
- 确定会做完整项目
## 7. 成本总额：按推荐的平衡方案计算
按 `方案 B` 算：
- `8h + 80h + 80h`：`151 元`
- `进阶型 32GB` 预留 `10~20 小时`：`36~72 元`
- 阿里 API：`30~50 元`
- MiniMax 对照：`20~40 元`
- 爬虫阶段：本地跑，按 `0 元` 增量计
总预算：
- `237~313 元`
为了防止试错超支，建议实际准备：
- `300~380 元`
## 8. 一句话结论
如果你问我现在最合适怎么买：
**先不要为爬虫买 HAI。**
**先买 `8 小时券 + 1 张 80 小时券`，开 `1 台基础型 16GB` 跑第一轮。**
如果第一轮确认素材量和试错量都不小，再补到：
**`8 小时券 + 2 张 80 小时券`，并在高峰时临时开第 2 台基础型。**
只有在你已经明确会长期做、而且会双机并行时，才直接上：
**`8 小时券 + 250 小时券`。**
## 9. 主要依据
- 用户提供的腾讯 HAI 活动页截图（2026-03-25）
- 腾讯 HAI 活动页：https://cloud.tencent.com/act/pro/hai
- 腾讯 HAI 使用现金券说明：https://cloud.tencent.com/document/product/1721/104127
- 腾讯 HAI 套餐类型：https://cloud.tencent.com/document/product/1721/112699
- 阿里百炼模型价格：https://help.aliyun.com/zh/model-studio/model-pricing
- MiniMax 中国大陆定价页：https://www.minimaxi.com/pricing

423
docs/source-material/顶级实时数字人_最终可靠方案与预算_v1.md Normal file
View File

@@ -0,0 +1,423 @@
# 顶级实时数字人：最终可靠方案与预算 v1
更新时间：2026-03-25
## 1. 目标与当前结论
当前项目目标已经收敛为：
- 第一目标：`还原度最高`
- 第二目标：`可以接受很大延迟`
- 第三目标：`不影响最终效果的前提下，能用 API 就优先用 API`
基于这个目标，当前最可靠的方案不是“把所有能力都交给 API”，而是：
- `阿里 API` 负责：`ASR / RAG / LLM`
- `腾讯 HAI` 负责：`数据清洗中的视频视觉处理、动作提取、自建模型训练/推理`
- `自建 TTS` 负责：`最终声音还原`
- `MiniMax TTS` 负责：`外部高质量对照组`
- `数字人渲染` 继续 `自建`
一句话版本：
`阿里做脑和耳朵，腾讯做算力底座，自建做嗓子和脸，MiniMax 做高质量外部对照。`
## 2. 最终可靠架构
### 2.1 在线交互主链路
```text
用户语音
-> 阿里实时 ASR
-> RAG 检索（老师原始资料库）
-> 阿里 LLM 生成回答草案
-> 风格约束器（口头禅/停顿/语气模板）
-> 自建 TTS（主链）
-> 上半身数字人渲染
-> 实时回传画面与语音
```
### 2.2 离线训练与素材生产链
```text
公开视频抓取
-> 音视频切段
-> 说话人分离 / VAD / 粗转写
-> 上半身动作提取 / 姿态关键点
-> 黄金语料筛选
-> 高精度转写与标注
-> TTS 训练集 / 动作资产库 / 知识库
```
### 2.3 模块分工
#### ASR
- 在线：阿里实时语音识别
- 离线高精度清洗：阿里 `SenseVoice`
- 备注：ASR 不决定“像不像老师本人”，优先 API 没问题
#### LLM / RAG
- 向量：阿里 `text-embedding-v4`
- 重排：阿里 `qwen3-rerank`
- 主对话模型：阿里 `qwen-plus`
- 高难度问题：阿里 `qwen-max`
- 关键约束：
- 回答必须绑定原始出处
- 风格模板和知识库分离
- 不让模型无限自由模仿人格
#### TTS
- 主方案：`自建`
- 冠军-挑战者结构：
- 候选 A：`FishAudio / Fish Speech`
- 候选 B：`CosyVoice 3`
- 外部对照组：`MiniMax speech-2.8-hd`
最终上线不建议把 API TTS 当唯一主引擎，原因很简单：
- 老师“像不像本人”，主要就输在这层
- 自建更容易持续调优音色、停顿、口头禅、情绪和说话习惯
- 长期可控性也更强
#### 数字人渲染
- 主方向：`上半身固定机位数字人`
- 面部与头部：`LivePortrait` 类驱动
- 口型：`MuseTalk` 类高精度嘴型同步
- 上半身动作：见下一节
## 3. 上半身肢体动作如何实现
上半身动作不要一开始就做“纯生成模型”，最可靠方案是：
`公开视频动作提取 -> 参数化 -> 动作资产库 -> 在线检索/插值 -> 驱动数字人`
### 3.1 推荐实现方式
#### 第一步：从公开视频里提动作
- `OpenPose`：提取肩、肘、腕、手、脸关键点
- `MediaPipe Pose Landmarker`：补充 3D 姿态趋势
#### 第二步：统一成可复用参数
- 把关键点统一成 `SMPL-X / FLAME` 这类参数表达
- 这样后面不管你是 2.5D 数字人、3D 角色、还是更重的渲染路线，都可以复用同一套动作数据
#### 第三步：建“老师动作风格库”
把动作切成可检索的小片段并打标签：
- 待机
- 解释
- 强调
- 反问
- 停顿思考
- 鼓励
- 否定提醒
#### 第四步：在线不是“生成整段动作”，而是“选择 + 插值”
在线运行时：
- 先根据回答语气、长度、节奏，从老师真实动作库里检索最像的片段
- 再用插值或轻量生成模型补过渡
这比端到端直接生成整段上半身动作更像本人，也更稳。
### 3.2 为什么不用“纯生成全包”
因为你的第一目标是还原度，不是炫技：
- 纯生成最容易出现“嘴对了、手假了”
- 老师这种讲解型人物，识别度最强的是：
- 头部微动
- 点头频率
- 停顿时的手势
- 强调时肩颈和前倾节奏
所以动作层优先做成：
`动作资产库 + 状态机 + 少量补帧`
而不是先做“大而全的动作生成模型”。
## 4. 数据清洗到底用腾讯还是阿里
### 4.1 当前最优解：混合，但重心偏腾讯
如果只看“整套项目的最终预算”，当前更推荐：
- ` bulk 清洗`：腾讯 HAI 自跑
- `黄金语料高精度转写`：阿里 API
理由：
- 你的项目反正要租腾讯 HAI 做视觉清洗、动作提取、训练和推理
- 那么把一部分音频清洗也顺手放在腾讯上做，整体更省
- 但阿里 `SenseVoice` 很适合给“最终 TTS 黄金语料”做高精度标注
### 4.2 为什么不是“全阿里”
如果全量都交给阿里 API：
- 语音转写很省事
- 但视觉动作清洗你还是逃不开腾讯 GPU
- 所以最终总账通常更高
### 4.3 为什么不是“全腾讯”
如果完全不碰阿里 API：
- 成本可能更低
- 但高价值语料的文本精修质量和工程效率不一定最好
所以最稳的组合是：
- `腾讯跑 bulk`
- `阿里跑 gold`
## 5. 腾讯 HAI 优惠券基线
### 5.1 当前页面能确认的内容
腾讯当前活动页可以直接确认这些信息：
- `HAI 8 小时 使用券`
- 购买后 `30 天内有效`
- 单用户最多 `1 张`
- 适用于抵扣 `后付费 HAI 实例`
- 适用于 `GPU 基础型`
- `HAI 80 小时 使用券`
- 购买后 `90 天内有效`
- 单用户最多 `3 张`
- 适用于 `GPU 基础型`
- `HAI 250 小时 使用券`
- 购买后 `90 天内有效`
- 单用户最多 `3 张`
- 适用于 `GPU 基础型`
- 基础型标价：`1.2 元/小时起`
- 进阶型标价：`3.6 元/小时起`
### 5.2 券面金额如何处理
活动页未登录状态下，券的购买金额显示为 `¥ -`。
因此预算里采用的券面购买价，使用的是腾讯云同域开发者社区的当前可见参考信息：
- `8 小时券 = 1 元`
- `80 小时券 = 75 元`
- `250 小时券 = 225 元`
这组价格适合做预算，但最终仍应以你实际购买页结算为准。
### 5.3 等效单价
- `8 小时券`：`0.125 元/小时`
- `80 小时券`：`0.9375 元/小时`
- `250 小时券`：`0.9 元/小时`
如果把页面允许购买的全部基础型券都买满：
- 总成本：`901 元`
- 总可用时长：`998 小时`
- 综合等效价：约 `0.903 元/小时`
## 6. 推荐预算模型
下面的预算，不是“永远总成本”，而是：
`做出首个可靠可用版本所需的项目现金流预算`
### 6.1 预算假设：推荐版 v1
假设你现在做的是：
- 原始公开视频：`40 小时`
- 目标产物：
- 一个高还原上半身数字人
- 可实时对话
- 自建 TTS 主链
- 动作资产库已经建立
### 6.2 腾讯 HAI 用量假设
#### 基础型 GPU 时长
- bulk 音视频清洗：`48 小时`
- 动作提取与姿态参数化：`32 小时`
- TTS 预处理与训练试错：`40 小时`
- 数字人渲染调试与回归：`28 小时`
合计：`148 小时 基础型 GPU`
#### 进阶型 GPU 时长
用于一些更吃显存的短时训练/渲染冲刺：
- `20 小时 进阶型 GPU`
### 6.3 预算结果：推荐版 v1
#### 腾讯 HAI
- 覆盖 `148 小时基础型` 的最低购买组合：
- `8 小时券 x1`
- `80 小时券 x2`
- 现金支出：`151 元`
- 可用总时长：`168 小时`
- 剩余时长：`20 小时`
#### 腾讯 HAI 进阶型
- `20 小时 x 3.6 元/小时`
- 现金支出：`72 元`
#### 阿里 API
推荐只把高价值部分交给阿里：
- `SenseVoice` 高精度转写 `5 小时黄金语料`：约 `12.6 元`
- 在线 ASR 联调预留：约 `5.4 元`
- 向量 / 重排 / LLM 调试预留：建议直接按 `20 元` 记
阿里 API 合计建议预留：`40 元`
#### MiniMax 对照测试
建议只把它当外部对照组，不要大规模烧钱：
- 1 个音色克隆
- 约 3 万字符 HD 测试
建议预算：`20.4 元`
为了保守起见，可按：`30~50 元` 预留
### 6.4 推荐版 v1 总预算
#### 核心可跑版
- 腾讯基础型：`151 元`
- 腾讯进阶型：`72 元`
- 阿里 API：`40 元`
合计：`263 元`
#### 含 MiniMax 对照组
- 核心可跑版：`263 元`
- MiniMax：`30~50 元`
合计：`293~313 元`
#### 含 20% 缓冲
建议你把首版可靠预算直接按：
- `350~380 元`
去准备。
## 7. 如果把 bulk 清洗改成阿里，会多花多少
以 `40 小时原始视频` 为例：
- 阿里 `SenseVoice` 全量转写：约 `100.8 元`
如果你本来就会买腾讯 HAI 券来做动作提取和训练，那么：
- 用腾讯顺手把 bulk 音频清洗一起跑掉，通常更省
- 再把 `3~5 小时黄金语料`送去阿里精修，质量和预算都更平衡
一个简单理解方式：
- `全量阿里`：省工程时间，但会额外增加约 `100 元` 级别的 API 成本
- `腾讯 bulk + 阿里 gold`：通常是当前性价比最高的组合
## 8. 两台腾讯服务器并行值不值得
值不值得，关键看你是看 `现金支出` 还是看 `墙上时间`。
### 8.1 现金支出
如果两台机器做的是可完全拆分的任务，例如：
- 视频切片 A-M 在机器 1
- 视频切片 N-Z 在机器 2
那么：
- 总 GPU 小时数基本不变
- 现金成本基本不变
- 只是消耗券的速度更快
也就是说：
`两台并行不会天然更贵，只要总 GPU 小时数没有显著增加。`
### 8.2 墙上时间
两台机器最适合并行这些环节：
- 视频切段
- 粗转写
- 姿态提取
- 关键帧筛选
- 动作片段打标签前的预处理
这些任务几乎都可以直接按视频文件分片并行。
### 8.3 推荐结论
如果你准备买 `80 小时券` 或 `250 小时券`，并且手头有大量原始视频：
- `开两台基础型 HAI 做 bulk 清洗` 是合理的
- 它的主要收益是 `把等待时间砍半`
- 不是为了再省钱
## 9. 当前最推荐的执行顺序
1. 先买 `8 小时券 x1` 和 `80 小时券 x2`
2. 开 `1~2 台基础型 HAI`
3. 完成 bulk 清洗、动作提取、初步语料筛选
4. 只把 `3~5 小时黄金语料`送去阿里 `SenseVoice`
5. 并行训练两路自建 TTS：
- `FishAudio / Fish Speech`
- `CosyVoice 3`
6. 用 `MiniMax speech-2.8-hd` 做小规模盲测对照
7. 冠军模型进入主链路
8. 再接上实时上半身数字人
## 10. 最终决策
在当前信息下，我认为最稳、最省钱、又不牺牲最后效果的方案是：
- `数据清洗`：腾讯 HAI 为主，阿里只做黄金语料精修
- `在线 ASR / LLM / RAG`：阿里 API
- `TTS`：自建为主，MiniMax 为对照组
- `上半身动作`：真实动作提取 + 参数化 + 动作资产库 + 在线检索/插值
这个方案的核心优势是：
- 最贵的“像不像本人”能力，掌握在自己手里
- API 只承担通用能力
- 腾讯优惠券能有效压低项目首期现金流
## 11. 主要来源
- 腾讯 HAI 活动页：https://cloud.tencent.com/act/pro/hai
- 腾讯 HAI 套餐类型：https://cloud.tencent.com/document/product/1721/112699
- 腾讯 HAI 使用券说明：https://cloud.tencent.com/document/product/1721/104127
- 腾讯开发者社区 HAI 优惠参考（1 元 8 小时券）：https://cloud.tencent.com/developer/article/2405436
- 阿里百炼模型价格：https://help.aliyun.com/zh/model-studio/model-pricing
- 阿里向量模型定价参考：https://help.aliyun.com/zh/dashscope/developer-reference/text-embedding-quick-start
- 阿里人声克隆概述：https://help.aliyun.com/zh/ims/user-guide/overview-of-human-voice-cloning
- MiniMax 中国大陆定价页：https://www.minimaxi.com/pricing
- MiniMax 语音定价说明：https://platform.minimaxi.com/docs/guides/pricing-speech
- MuseTalk：https://github.com/TMElyralab/MuseTalk
- LivePortrait：https://github.com/KlingAIResearch/LivePortrait
- OpenPose：https://github.com/CMU-Perceptual-Computing-Lab/openpose
- MediaPipe Pose Landmarker：https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker/python