feat: ship native boss android console

2026-03-26 23:16:56 +08:00
parent 90e904814d
commit 90cb6b7ff1
261 changed files with 40051 additions and 135 deletions
--- a/docs/source-material/thread_context_budget_and_handoff_protocol_cn.md
+++ b/docs/source-material/thread_context_budget_and_handoff_protocol_cn.md
@@ -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、前端同时作为实现依据