[ChrAlpha]

Author

• Human
• Agent

Type

• bug
• feat
• test

Summary

压缩原来以覆盖层（overlay）表达会话上下文：每条摘要记录自己覆盖了哪些行，读路径把有效摘要与未覆盖的行合成上下文，并靠 coverage、epoch、claim、source hash、appeared rows 和修复路径维持一致性。这些机制大多为当前 writer 不会产生的状态而存在，读写两侧都要理解它们。本 PR 改为 history checkpoint，并让轮前与轮内共用一个折叠引擎。

History checkpoint

• 会话上下文由 bot_sessions.history_checkpoint_id 指向的 checkpoint 决定：一个位置 (turn_position, turn_message_seq)，加上按序排列的条目（按引用保留的行与摘要，至少一份摘要）。请求先渲染这些条目，再渲染位置之后的上下文行。每次折叠提交一个新 checkpoint，以父链相连。
• edit、retry、删除在替换或删除行的同一语句里沿父链回退（memoh_rewind_history_checkpoint）；run 的所有历史写入（含删除）都在 run 的 fence 内执行。
• fork 在创建事务里复制它所在轮次保留的 checkpoint；保留的行与摘要里引用的行（ref=<行>:<part>）都改指 fork 的副本，fork 里的 get_messages 能按摘要的 ref 读回原始结果，fork 后的第一个请求不会再折叠一次源会话已折叠的内容。
• 0170 建表，把每个会话的有效摘要及其跨度内未被覆盖的行转换成 checkpoint，并移除覆盖层的表、函数与触发器。

折叠引擎

• compaction.Service.Fold 对 run 即将发送的请求做 cache-safe fork，沿用 run 的 system、工具、cache key、推理与输出设置（run 不发 max_tokens 就不发），只读窗口在 run 输出额度之外容得下的部分，读不下的留给下一个 pass。provider 按 run 输出设定的参数（如 legacy Anthropic thinking 的 budget_tokens）对 fork 同样成立。规划先算最长的读取，其余二分查找。
• 保留什么在第一个 pass 前由引擎一次决定：一个原文预算，取请求在 system、工具与 runtime context 之外余量的四分之一，至多 32000 tokens。下一次调用要回答的输入与没有行承载的消息无条件保留，其余 anchor 与最新的完整调用组从新到旧放入，遇到第一个放不下的停止；放不下的最新 step 在同一 pass 里折叠，指令要求摘要写明工作进行到哪里并列出被折叠结果的 ref。工具结果只受工具自身上限约束。
• compaction.Service.Compact 用同一引擎从行折叠：字节预算截断的历史加载在构造请求前先折叠再重新加载，仍然截断就以 context.budget_unsatisfied 失败，不会以晚于 checkpoint 的起点静默继续；Discuss 的省略输入与组不下的批次同样走这里。按行读取以整个调用组为单位，调用不会与结果分在 checkpoint 两侧；交给不带工具的压缩模型时，消息写成文本。
• 每个 pass 独立提交且可单独恢复：中途失败时，已提交的 pass 保持有效，下一次从活动 checkpoint 继续。

删除

覆盖层的一致性机制，以及只为调用方不会传入的状态存在的守卫。保留的行加载不到、调用组无论怎么读都放不进 fork，这两种情况直接失败，不再静默降级。

docs/agent-runtime.md、docs/database.md、docs/observability.md、docs/design/context-memory-scheduling.md 已按新模型更新。

Related Issues

Builds on #1697（stack，base 为 #1697 的分支）。Supersedes #1699 与 #1701：checkpoint 存储与折叠引擎作为一个单元交付；#1699 的按 step 限额被原文预算取代，最终 diff 不含其机制。

Validation

均在 head 7154862c6（或与其行为相同、标注了 head 的提交）上执行。

• go test ./... -count=1：除 internal/container/docker 与 internal/workspace/shellenv 外全部通过；这两个包在 main 上以相同用例失败（本机 Docker API 与 shell 环境）。
• go test -tags=integration -p 1 ./internal/db/... ./internal/chat/... ./cmd/agent/... ./internal/agent/... ./internal/channel/...，指向一个已迁移的独立 PostgreSQL 库：全部通过。
• golangci-lint run ./...：通过。go vet -tags=integration 除 internal/settings（main 上已有的编译错误，本 PR 未触及）外通过。
• 升级：把一个 schema 169、带覆盖层数据的开发库（4 个会话，40 条有效摘要）恢复后执行 migrate up，0170 用时 47.7ms，每个会话都得到 checkpoint。0170 此后未改动。
• 真实 provider 长任务（Agent 验证，1db378ebc，与当前 head 行为相同；本地 devenv 栈，Web 操作全部经浏览器，模型 mimo-v2.6-pro，窗口 256k）：Bot 用 47 分钟审计 88 个真实源码文件（1.03MB），单次输入峰值 217,113 tokens，同一 run 内自然触发 3 次压缩（199,027→47,662、201,322→59,248、217,113→49,565），每次之后继续原任务；期间两次需求变更、刷新、排队消息、Retry、Edit、Fork 均通过，一次性收据保持不变，交付物包含全部变更后的约束。早期精确数值在三次压缩后未能直接回忆，模型用 5 次只读命令从源码找回。
• 真实 provider 复验（Agent 验证，当前 head，同一环境）：
  • 在经过三次压缩的长会话里追问，不调用工具即正确回答新代号、报告文件名与验收短语，上下文 25%。
  • 从该回答 fork：fork 得到自己的根 checkpoint（4 个保留行 + 1 份摘要，全部指向 fork 的副本，数据库核对）。
  • 把模型窗口临时设为 32k 后在 fork 里提问：system 与 46 个工具定义加输出预留已超过窗口，run 以“请求放不进上下文”明确失败，checkpoint 不变。
  • 改为 48k 后对该轮 Try again：run 内折叠 4 个 pass（62,148→30,122 tokens，额度 39,808），回答正确；fork 的 checkpoint 链为复制的根加 4 个依次相连的 checkpoint。测试后窗口恢复为 256k。
• 未覆盖：真实 IM 渠道投递、Discuss 的 IM 批处理、外部 Codex/Claude 运行时、分布式恢复、生产规模数据上 0170 的耗时与锁。
• 验收中发现、与本 PR 无关的既有问题（main 上同样存在）：服务重启后，待回答的 ask_user 变为 lost 且无法续跑（无压缩的对照会话同样复现）；run 内折叠之后，上下文圆环显示的是 run 开始时记录的组成（本例 104%），而不是折叠后的请求；压缩日志展开后的 common.usage 未翻译。

Screenshots / Recordings

截图由 Agent 通过浏览器自动化在运行中的应用里采集，不代表 Human QA。

Human QA

• Human QA passed