# 线程上下文预算与压缩前接力协议

这份文档把“背景信息窗口余量”正式冻结成开发规格，覆盖：

- 设备端如何上报线程上下文预算
- 手机端 / 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、前端同时作为实现依据