[RFC] OpenViking Session 上下文优化：Turn-aware Retention、Pending/Failed 恢复与预算控制

[yeshion23333]

RFC：OpenViking Session 上下文优化

用 Turn 保证语义完整，用 token budget 控制长度，用 目录状态保证消息不丢。

关联背景：VikingBot 保留原始 assistant/tool 关系 #3236

要解决的三个问题

问题	当前结果	优化后
保留最后 10 条 Message	可能 10 条全是 assistant，User 已归档	保留完整 User anchor 和可理解的 Turn
一个 Turn 有很多工具轮次	完整保留会无限变长	早期步骤进 checkpoint，只保留最近 raw tail
commit pending / failed	pending 可能被 commit_count 隐藏；failed 原文退出上下文	完全按目录状态判断，未覆盖原文始终可见

---

以下两项不是二选一：改动一解决 active messages 的语义和长度问题；改动二解决异步 commit 的消息可靠性问题。两者共同组成此次优化。

目标

1. active context 必须保留真实 User query，不能只剩 assistant。
2. 一轮 assistant 文本及其 tool call/result 必须作为整体保留或整体压缩。
3. retained messages 同时受 Turn 数和 token budget 约束。
4. failed/pending 消息不能因异步 commit 暂时或永久消失。
5. checkpoint 必须只总结 checkpoint_source_message_ids 对应的 Assistant/Tool 前缀，不能从全局 overview 截取。
6. LLM 只生成摘要字符串，不处理 message ID、anchor、archive URI、token budget 和持久化映射。
7. overview 与 checkpoint 由 Phase 2 现有的同一次 LLM 调用同时产出，不新增 checkpoint 专用 LLM 调用。
8. 保持公开返回结构不变：

latest_archive_overview + messages

不保存模型私有 reasoning，也不保证所有 assistant/tool 历史永久以 raw message 保留。

---

改动一：优化 retained messages（Turn + Token）

两个原子单元

单元	定义	切分规则
User Turn	一个真实 User query，到下一个真实 User query 之前的所有执行	优先完整保留；超长时允许 checkpoint
Assistant Step	一轮 assistant text + 同轮全部 tool calls + 对应 results	永远不拆开

Tool-only 的 role=user transport message 不开启新 Turn。

选择算法

1. 把 Message 组织成 Turn / Assistant Step
2. 先按完整 Turn 聚合 externalize Tool 输出
3. 从最新 Turn 向前保留，同时满足：Turn 数 <= K、token <= B
4. 超预算时，先归档最老的完整 Turn
5. 如果最新 Turn 自己仍超预算：保留 User + checkpoint + 最近 Steps + final

优先级：

User anchor > final assistant > 最近 Assistant Steps > 更早 Steps > 更早 Turns

超长 Turn 如何处理

例如：

压缩前：U1 + A1...A18 + final              30k tokens
压缩后：U1 + checkpoint + A15...A18 + final  11k tokens

• A1...A14 的原文仍保存在 archive messages.jsonl；
• Phase 1 由代码确定 User anchor、checkpoint source 范围和 raw tail，不调用 LLM；
• Phase 2 只在现有 Working Memory 输入中给 source 范围加轻量标记；
• 同一次 LLM 调用保持原有 Working Memory 输出，并额外返回 checkpoint_summaries[]；
• OpenViking 按数组下标补齐真实 ID、范围、预算和持久化字段；
• A15...final 保持原始 text/tool/result 关系。

最小 LLM 契约

核心原则：代码决定“摘要谁”，LLM 只负责“写摘要”。

输入：只增加范围标记

Phase 1 已经知道 checkpoint_source_message_ids。Phase 2 格式化现有 archive messages 时，在对应的连续 Assistant/Tool Steps 外增加标记：

[User]
看下 peers

<checkpoint_source index="0">
[Assistant]
我检查一下 peers 目录。

[tool:openviking_list]
[]
</checkpoint_source>

[Assistant]
peers 文件夹为空。

source 原文只出现一次，同时服务于全局 Working Memory 和 checkpoint，不重复拼接。LLM 只看到稳定的序号 index，不接收真实 message ID、anchor ID、archive URI 或动态 token budget。

输出：只新增一个字符串数组

{
  "...现有 Working Memory 输出...": "保持原协议",
  "checkpoint_summaries": [
    "检查了 OpenViking peers 目录，结果为空。"
  ]
}

Working Memory 路径	原有输出	最小新增
首次创建	完整 Working Memory markdown	checkpoint_summaries: list[str]
增量更新	sections 更新操作	checkpoint_summaries: list[str]

数组下标与输入标记对应。多个 partial Turn 或 failed roll-forward 使用多个 index，仍在同一次调用中返回。LLM 不复制任何 provenance 字段。

OpenViking 本地补齐映射

checkpoint_requests[0]
  + checkpoint_summaries[0]
  + 本地 token 估算/截断
  = archive meta checkpoint record

OpenViking 本地负责：

• 将 index 映射回 turn_anchor_message_id 和 source_message_ids；
• 校验摘要数量与 request 数量一致；
• 计算 checkpoint 可用预算并做确定性截断；
• 构造 ContextPart，写入 archive metadata；
• 摘要缺失、数量不匹配或为空时按 Phase 2 失败处理。

生成约束只保留语义要求：摘要应覆盖执行意图、关键动作、工具结论、错误和未完成状态；不保存模型私有 reasoning。该方案不增加 LLM 调用次数，但 completion tokens 会小幅增加。

Checkpoint 持久化

checkpoint 不写入 root messages.jsonl，也不新增独立状态文件；作为可选字段合并写入对应 archive 的 .meta.json：

{
  "checkpoints": [
    {
      "turn_anchor_message_id": "msg_user_1",
      "source_message_ids": ["msg_a1", "msg_tool_1", "msg_a14"],
      "abstract": "检查了连接池指标，确认等待队列持续增长……",
      "estimated_tokens": 96
    }
  ]
}

上述 provenance 和 token 字段全部由 OpenViking 本地生成，不是 LLM 输出。

只有 overview 和所需 checkpoint 都成功落盘后才写 .done。对于启用了 Working Memory 的 partial Turn，checkpoint 生成或解析失败时 Phase 2 失败，archive raw 继续作为 uncovered raw 返回；working_memory=false 保持原行为，不生成 checkpoint，也不将 completed archive raw 放回 active。

旧 archive 没有 checkpoints 字段时继续使用 latest_archive_overview，但不再从 overview 合成重复 checkpoint。

Checkpoint 对外仍使用现有 ContextPart：

{
  "role": "assistant",
  "message_kind": "checkpoint",
  "parts": [{
    "type": "context",
    "context_type": "memory",
    "uri": "viking://.../history/archive_003",
    "abstract": "已确认连接池耗尽，当前正在验证回收配置。"
  }]
}

Tool 输出限制必须提升到 Turn 范围

当前单个 Assistant message 内：

单 Tool 输出 > 20,000 chars
或该 message 的 Tool 输出合计 > 100,000 chars

消息展开后，10 个 Steps × 10,000 chars 可能全部绕过限制。新逻辑应在完整逻辑 Turn 内聚合计算，再决定哪些 Tool 输出 externalize；原文继续存入 tool-results/。

---

改动二：修复 Archive 状态与消息恢复

状态定义

目录状态	状态	返回给模型
无 .done，无 .failed.json	pending	archive 原始消息
有 .done 且 overview 可读	completed	overview，不再返回已覆盖 raw
有 .failed.json，未被后续 coverage 覆盖	failed	archive 原始消息
有 .done 但 overview 损坏	invalid/uncovered	原始消息，并记录告警

commit_count 只保留为统计字段，不再判断 pending/completed boundary。

Context 始终按下面的公式组装：

latest completed overview
+ 按 archive index 排序的 uncovered raw
+ root messages.jsonl

最后按 message.id stable dedup，防止崩溃恢复或并发切换时重复。

Pending：为什么不能使用 commit_count

当前 Phase 1 时序：

写 archive/messages.jsonl
→ 更新 commit_count
→ 返回 accepted
→ Phase 2 后台执行
→ 最后才写 .done

因此 commit_count=2 只能说明两个 Phase 1 已接受，不能说明 archive_001/002 已被 overview 覆盖。

两个 rapid commits 的正确行为：

目录状态	latest_archive_overview	raw messages
001 pending，002 pending	上一次已完成 overview	001 + 002 + root
001 done，002 pending	001 overview	002 + root
001 done，002 done	002 overview	root

Failed：恢复为逻辑 live

“恢复到 live”指 failed archive 原文重新进入 get_session_context().messages，不需要把文件物理搬回 root：

logical live = uncovered pending raw + uncovered failed raw + root live

这样可以避免 Phase 2 期间物理 prepend 导致重复、乱序或覆盖新消息。

Failed raw 不能永久留在 active。后续 archive 成功时必须 roll-forward：

archive_001 failed:  U1 A1
archive_002 pending: U2 A2

archive_002 Phase 2 输入：U1 A1 + U2 A2
archive_002 done 后：overview 覆盖 001...002

建议扩展 .done，记录 coverage：

{
  "starting_message_id": "msg_001",
  "ending_message_id": "msg_020",
  "coverage_start_archive": "archive_001",
  "coverage_end_archive": "archive_002",
  "covered_failed_archives": ["archive_001"]
}

旧 .done 没有 coverage 字段时，默认只覆盖自身。

---

结构差异

维度	当前	优化后
保留边界	最后 N 条 Message	最近 K 个 Turn + token budget
工具关系	可能在边界处断开	Assistant Step 原子化
Tool 聚合限制	单物理 message	完整逻辑 Turn
超长 Turn	全留或按 Message 切	User + checkpoint + raw tail
checkpoint	无	同一次 Phase 2 LLM 生成 Turn-local 摘要，与 overview 分离
pending 判定	commit_count + marker	仅目录 marker
failed 消息	跳过	uncovered raw 进入 logical live
failed 收敛	不会进入后续 overview	后续 .done coverage 吸收
对外结构	overview + messages	不变

---

详细改动

1. Message：增加可选语义字段

turn_id: Optional[str]
message_kind: Optional[
    "user_query" | "assistant_step" | "tool_transport" | "checkpoint"
]
source_message_ids: Optional[list[str]]

旧 Message 没有这些字段时继续推断；推断不确定时扩大原子范围，不能拆 call/result。

2. Commit API：新模式不改变旧参数语义

{
  "retention_mode": "turn_budget",
  "keep_recent_turn_count": 3,
  "retained_message_token_budget": 12000,
  "min_raw_tail_steps": 1
}

• 未传新字段：继续使用现有 keep_recent_count；
• 新模式先灰度，不直接改变旧 Session 行为；
• 默认值由接入方模型窗口决定，RFC 不强制统一值。

3. Session：抽出纯 Retention Planner

plan_retention(messages, turn_count, token_budget) -> RetentionPlan

输出至少包括：

archive_messages
retained_messages
turn_anchor
checkpoint_source_message_ids
raw_tail_start_message_id
estimated_active_tokens
budget_exceeded

Planner 不访问 filesystem、不调用 LLM，可以独立单测。

4. Archive：统一状态扫描

新增统一 _scan_archive_states()，供以下逻辑共用：

• latest completed overview；
• uncovered pending/failed raw；
• Phase 2 前序等待；
• coverage frontier；
• context stats。

删除 _get_pending_archive_messages() 对 self._meta.commit_count 的正确性依赖，重构为 _get_uncovered_archive_messages()。

5. Phase 1 / Phase 2

阶段	改动
Phase 1	构建 Turn/Step；Turn 范围 externalize；执行 Retention Plan；保存 archive raw 和本地 checkpoint request 映射，再重写 root
Phase 2	在现有 Working Memory 输入中标记 source 范围；同一次 LLM 保持原输出并增加 checkpoint_summaries[]；本地补齐 ID/预算，全部落盘后最后写 .done
Context	overview + uncovered raw + root；stable dedup；读取 archive .meta.json.checkpoints，在仍 live 的 User anchor 后插入对应 checkpoint

Phase 2 写 overview_tokens 和 checkpoints 时必须 merge archive .meta.json，不能覆盖 Phase 1 保存的 retention plan。checkpoint request 应覆盖当前 archive 以及本次 roll-forward 吸收的 failed partial archives。

---

必须满足的不变量

1. archive raw 写成功后，才能从 root 移除消息。
2. .done 必须最后写；只有 .done + readable overview 才表示 raw 已覆盖。
3. .failed.json 是终态，但不是“消息已压缩”的证明。
4. assistant text + tool calls + results 永远不跨 retained/archive 边界拆分。
5. 任意已接受消息至少存在于一个位置：

overview coverage / uncovered archive raw / root messages.jsonl

6. checkpoint 只在对应 overview 和专用 checkpoint 产物都成功后出现；其 source_message_ids 必须完全属于被替代的 Assistant/Tool 前缀。
7. LLM 不生成或复制 provenance；真实 ID、anchor、预算和 archive 映射只由 OpenViking 本地处理。
8. 同一 Phase 2 archive summary 流程只发生一次主 LLM 调用，保持原 Working Memory 输出并增加 checkpoint_summaries[]。
9. failed 重放的 memory extraction、usage reporting 必须按 message/event ID 幂等。

---

测试与验收

场景	预期
1 User + 10 Assistant Steps	active 仍包含 User，不从 assistant 开始
一个 Turn 超预算	User + Turn-local checkpoint + raw tail，Step 不拆分；checkpoint 只总结 source messages
10 Steps × 10k Tool 输出	Turn 聚合 externalization 生效
2 个 rapid pending commits	两个 archive raw 都可见，与 commit_count 无关
Phase 2 failed	failed raw 立即回到 logical live
failed + next success	后续 .done coverage 吸收 failed raw
服务重启 / 多 worker	状态仅由目录恢复，顺序和去重一致
LLM 契约	输入只增加 source index 标记；输出只增加 checkpoint_summaries[]；不新增专用调用

完成标准：

• 正常完成 commit 后，active 不会只剩 assistant；
• completed retained tail 满足配置的 token budget；
• pending/failed 期间不丢消息；
• failed raw 不会永久占用 active；
• 对外 context 字段和旧 Session 兼容；
• 所有 call/result 配对保持完整；
• checkpoint 不再从 latest_archive_overview 截取，且能由本地映射按 source IDs 溯源；
• LLM 输入不包含内部 provenance/预算字段，输出只新增摘要字符串数组；
• 同一 archive 的 overview + checkpoints 只使用一次主 LLM 调用。

---

落地顺序

1. 可靠性修复：目录状态扫描、pending 修复、failed logical live、stable dedup、coverage。
2. Turn-aware Retention：Turn/Step parser、Retention Planner、Turn 范围 externalization。
3. 超长 Turn：给现有 Phase 2 输入增加 source index 标记、输出增加 checkpoint_summaries[]，本地完成映射和预算控制。
4. 灰度默认开启：观察 active tokens、Phase 2 延迟、failed replay 和 memory 幂等。

待确认

1. turn_id/message_kind 进入公共 Message schema，还是先放 optional metadata？
2. 单个超长 final assistant 是复用 tool-results/，还是提供通用 message result store？
3. pending 阶段默认 lossless 并允许临时超预算，是否需要 opt-in strict_budget？

[yeshion23333]

本方案已经实现