krisolo/boss

Fork 0

Files

kris 90cb6b7ff1 feat: ship native boss android console

2026-03-26 23:16:56 +08:00

9.5 KiB

Raw Blame History

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

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

设备端如何上报线程上下文预算
手机端 / Web BFF 如何返回会话列表里的圆环进度标记
主 Agent 如何基于上下文预算做压缩前收尾、线程轮换和摘要接力
哪些字段是系统真相，哪些字段只是展示层映射

适用范围：

单主 Agent
多台 Mac / Windows / Cloud Worker
微信式会话列表首页
项目聊天页 / 线程详情页
API-first / local-first 极限轻云模式

1. 核心原则

首页圆环标记显示的是“线程上下文预算”，不是账号 5h / 7d 使用额度。
线程上下文预算必须由设备端 worker 统一上报，前端不能自行推算。
主 Agent 必须在发生背景信息压缩前完成关键收尾，而不是在压缩后补救。
线程上下文预算是主 Agent 的一等调度信号，优先级高于普通列表排序提示。
群聊型项目会话默认不在首页显示线程上下文预算，但项目详情页仍然可以展开查看各线程预算。

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

请求体：

{
  "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"
}

返回体：

{
  "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

示例：

{
  "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 默认调度策略

若线程进入 critical，优先处理该线程的收尾和交接。
若多个线程同时 critical，优先处理：
- 有未固化 patch 的
- 有未固化测试结果的
- 有硬件测试正在进行的
watch 和 urgent 阶段，主 Agent 应减少向该线程追加长背景信息。
新子任务应优先派给预算更健康的新线程或其他空闲线程。

8.3 压缩前收尾清单

主 Agent 触发 prepare_handoff 时，worker 必须尽量补齐：

当前修改涉及的文件清单
已完成和未完成的 patch
最近一次关键命令及其结果
最近一次测试结论
未决问题
下一线程建议动作
必需证据链接

9. 验收标准

满足以下条件，视为这块设计可直接进入开发：

设备端能统一上报线程上下文预算。
BFF 能返回首页圆环所需全部字段。
项目详情页能展开查看多线程预算。
主 Agent 能在 watch / urgent / critical 三个边界做出不同动作。
发生 compaction 前，系统能自动触发至少一次压缩前收尾和 handoff 准备。
首页显示、项目详情显示、设备端线程显示三处的预算语义一致。

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、前端同时作为实现依据

9.5 KiB Raw Blame History Unescape Escape

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

1. 核心原则

2. 术语定义

2.1 线程上下文预算

2.2 背景信息压缩

2.3 压缩前收尾

2.4 摘要接力

3. 设备端真相模型

3.1 新增数据对象

3.2 thread_context_snapshots

3.3 thread_handoff_packages

3.4 thread_context_alerts

4. 统一阈值策略

4.1 对应动作

4.2 must_finish_before_compaction

5. Worker 上报协议

5.1 上报频率

5.2 API

5.3 事件

6. 手机端 / Web BFF 协议

6.1 会话列表接口

6.2 项目详情接口

6.3 线程详情接口

6.4 SSE 事件

7. 首页 UI 映射规则

7.1 单设备项目会话

7.2 群聊型项目会话

7.3 主 Agent 会话

8. 主 Agent 调度逻辑

8.1 预算优先级排序

8.2 默认调度策略

8.3 压缩前收尾清单

9. 验收标准

10. 与现有文档关系

9.5 KiB

Raw Blame History

3.2 `thread_context_snapshots`

3.3 `thread_handoff_packages`

3.4 `thread_context_alerts`

4.2 `must_finish_before_compaction`