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`