runLoop 与上下文压缩

runLoop 是会话的 ReAct 外环：决定本轮先处理子任务、先压缩，还是再问一次模型。上下文膨胀时，系统用 compaction 生成摘要消息，再用 filterCompacted 在送模前截断更老原文。另有一套不调用模型的 SessionSummary，只统计工作区 diff，二者不要混用。

在主链路中的位置

flowchart TD
  Prompt[SessionPrompt.prompt] --> User[createUserMessage]
  User --> Loop[Runner.ensureRunning]
  Loop --> RL[runLoop while]
  RL --> Next{下一动作}
  Next --> Sub[subtask]
  Next --> Comp[compaction]
  Next --> LLM[processor + LLM]

同会话由 Runner 保证不并发两个 runLoop。见实例边界与并发调度。

每轮优先顺序

1. 读取 filterCompacted 历史并找锚点（lastUser / lastAssistant / 未决 tasks）。
2. 若助手已完整结束且无未决 tool-call，则退出。
3. 消费 tasks（后进先出）：优先 subtask，其次 compaction。
4. 溢出预判为真时创建 compaction 任务并继续。
5. 否则进入正常模型轮：解析工具、Processor 消费流。

flowchart TD
  A[读历史与锚点] --> B{已结束?}
  B -->|是| Z[返回]
  B -->|否| C{有 task?}
  C -->|subtask| S[handleSubtask] --> A
  C -->|compaction| P[compaction.process] --> A
  C -->|无| O{溢出?}
  O -->|是| N[创建 compaction] --> A
  O -->|否| L[LLM 轮] --> A

compaction 从哪来

来源	机制
溢出预判	runLoop 内判定上下文将溢出 → 创建 compaction
Processor 信号	步结束或上下文溢出错误 → 返回 compact → 创建 compaction
手动	会话 summarize / compaction API
队列	历史中已带 compaction Part 的用户消息，由外环消费

compaction.process 使用专用压缩角色与提示词调用模型生成文本摘要（禁止工具），写入 summary=true 的助手消息；自动模式下可能补一条合成用户消息以继续执行。返回 continue 或 stop（含上下文仍过大时的失败退出）。

与 filterCompacted 的配合

flowchart LR
  C[compaction 产出摘要助手消息] --> U[用户消息带 compaction Part]
  U --> F[下一轮 filterCompacted]
  F --> V[送模视图变短]

摘要保留语义锚点；更老原文不再展开。消息模型侧见消息模型与跨轮记忆。

SessionSummary 不是压缩

Processor 在 finish-step 可触发 SessionSummary：按快照 diff 统计增删与文件，写回会话级摘要字段。它不调用 LLM，也不制造 filterCompacted 边界。用途是施工统计，不是会议纪要式压缩。

边界与代价

• 压缩消耗额外模型调用与延迟；失败时外环可能停止而不是硬塞超限上下文。
• 摘要质量上限取决于压缩提示与模型；错误摘要会污染后续轮次，需靠会话回放与人工复核定位。
• 结构化输出（json_schema）命中后可提前结束外环，与压缩路径独立。

---

相关阅读：

• 端到端主链路
• Processor 与 LLM 适配
• 消息模型与跨轮记忆