对话历史与上下文压缩机制解析

表述：本文面向 开发与运维，说明 Cadau 在对话历史 越来越多 时，界面展示、数据库持久化、模型上下文 三层分别如何处理，以及与工作智能体 跨会话记忆 的分工。产品侧用户说法见 docs/core-mechanisms/智能体记忆.md；记忆文件落盘见 工作智能体记忆存储位置解析。

日期：2026-07-16（补充工具循环检查点） 相关代码：backend/internal/api/handlers/chat.go、backend/internal/api/handlers/chat_context_roll.go、backend/internal/store/chat.go、backend/internal/agentmemory/flush.go

结论

Cadau 对「对话历史变多」采用 三层分离 策略：

工作智能体 在压缩前还会把即将滚出的片段 flush 到日笔记，并可选 提炼为长期记忆，避免重要信息随摘要丢失。

三层架构概览

flowchart LR
    subgraph UI["前端展示"]
        A1[最近 100 条]
        A2[cursor 加载更早]
    end
    subgraph DB["数据库"]
        B1[chat_messages 全量]
        B2[chat_sessions.context_summary]
    end
    subgraph LLM["模型调用"]
        C1[历史摘要]
        C2[最近原文]
        C3[当前用户消息]
    end
    UI --> DB
    DB --> LLM

三者 不是一回事：用户在界面能看到完整历史（分页拉取），数据库里消息 不会 因上下文压缩而删除，但发给模型的 payload 会被 控在字符预算内。

1. 持久化：数据库全量保留

表结构

Schema 见 backend/internal/db/schema_postgres.sql（SQLite 见 schema.sql）。chat_messages.session_id 外键 ON DELETE CASCADE，删会话时级联删消息。

当前策略

• 无 按时间自动清理、归档或 TTL。
• 历史会一直增长，直到用户或管理员 主动删除会话，或通过 编辑重发 截断后续消息（POST /api/v1/chat/truncate）。

相关 API

2. 前端：分页加载与窗口化

前端通过 GET /chat/history 按需加载，不必一次拉全：

• 默认先取 最近一页（客户端常用 limit=50；服务端默认/上限见接口）。
• 响应含 older_cursor / newer_cursor / at_live_edge（next_cursor 兼容旧义 = 更早方向）。
• 有界窗口：内存只保留视口附近约百条，向上/向下双向加载并回收对侧；机制见 会话消息窗口化加载（微信式）。
• 提问导航：GET /chat/history/turns 提供轻量索引，与消息窗口解耦。
• 会话列表同样分页（GET /chat/sessions，默认 limit=20）。

实现：client/web/src/api.ts、client/web/src/chatMessageWindow.ts、client/web/src/useChatSessions.ts。

UI 不因会话总轮数到上千而持有全部气泡正文；数据库里仍是完整记录。

3. 模型上下文：滚动摘要（核心）

真正受 上下文窗口 限制的是每次调用 LLM 时塞进模型的内容。入口：

• prepareLLMConversationWithRollingContext — backend/internal/api/handlers/chat_context_roll.go
• 发消息时先 ListChatMessages(..., 8000) 读库，再滚动压缩 — backend/internal/api/handlers/chat.go

默认配置

环境变量（亦可在 mindlink.json → chat_context 覆盖）：

预算计算：Config.ChatContextInputBudgetRunes() — backend/internal/config/config.go。

工作流程

flowchart TD
    A[用户发新消息] --> B[从库读最多 8000 条历史]
    B --> C{估算字符量是否超阈值/硬上限?}
    C -->|否| D[摘要 + 最近原文 + 当前消息 → 调模型]
    C -->|是| E[取 priorRows 最早 batch 条]
    E --> F{是否工作智能体?}
    F -->|是| G[FlushBeforeCompaction: 日笔记 + 可选长期记忆提炼]
    F -->|否| H[跳过 flush]
    G --> I[LLM mergeRollingSummary 合并进 context_summary]
    H --> I
    I --> J[更新 verbatim_since 锚点并写库]
    J --> C
    D --> K[返回回复 + context_budget]

压缩细节

1. 从 verbatim_since_* 锚点起取 保留原文 的消息子集；锚点之前的内容已体现在 context_summary。
2. 估算 system prompt + 对话正文 字符量（estimateLLMPayloadRunes）。
3. 若超过 阈值（默认 88%）或 硬上限：

- 从 priorRows 头部取一批（默认 4 条）； - 工作智能体：先 agentmemory.FlushBeforeCompaction； - 调用 LLM mergeRollingSummary 合并进摘要； - 更新 context_summary 与 verbatim_since_*，写回 chat_sessions。

1. 循环最多 48 次，直到低于阈值或无法再滚（仍保留 min_verbatim 条原文）。
2. 摘要拼入 system prompt 前缀：

`` 【历史对话摘要（较早轮次已压缩；下文为多轮原文）】 …摘要正文… ``

重要边界

前端反馈

聊天响应含 context_budget：used_runes、limit_runes、used_pct。Web 端展示 上下文用量圆环（client/web/src/api.ts → parseContextBudget）。

4. 工作智能体：压缩前记忆抢救

若是 工作区「我的智能体」 会话，滚入摘要前调用 FlushBeforeCompaction（backend/internal/agentmemory/flush.go）：

1. 日笔记：片段追加到 memory/YYYY-MM-DD.md（标题含「上下文压缩归档」）。
2. 长期记忆提炼（可选）：若 memory_auto_extract 为 true（默认开启），调用 ExtractFromBatch 写入 memory/entries/*.md。

对应产品机制：docs/core-mechanisms/智能体记忆.md — 「上下文压缩前归档」。

开关位于智能体 config_json：

MemoryAutoAppend  *bool  `json:"memory_auto_append,omitempty"`   // 默认关
MemoryAutoExtract *bool  `json:"memory_auto_extract,omitempty"`  // 默认开

定义：backend/internal/runtimews/agentconfig.go。

5. 与长期记忆的分工

对话历史变多 不会自动 全部变成长期记忆；需用户点 「记住」、对话中明确「记住/别忘了」、压缩前自动提炼、或智能体调用 memory_write。

详见 工作智能体记忆存储位置解析。

6. 其它相关截断与压缩（非会话滚动摘要）

以下机制 独立 于「会话级」滚动摘要，但同样为避免单次请求上下文膨胀。

6.1 工具结果：主对话不截断

工具循环写入模型上下文的 tool 返回为 全文（ unner.go）。前端 SSE 展示仍可对超长输出做展示层截断，不影响模型所见。

知识注入、附件提取等其它 rune 上限见各自模块，与工具循环检查点无关。

6.2 工具循环内：接近预算才做 LLM 检查点摘要

单条用户消息触发的 多轮 tools（RunAgentToolLoop）里，上下文可能因反复取数 / 写文件膨胀。

日志：chat_agent_context_compact_llm、chat_agent_context_compact_llm_failed、chat_agent_context_compact_skipped。

与会话滚动摘要的分工：会话摘要压缩跨轮 user/assistant 历史；本节压缩同一轮内 tool 往返。

7. 排查与运维参考

日志关键字

本机查看

1. 数据库：查 chat_sessions.context_summary、erbatim_since_* 与 chat_messages 条数。
2. 运行时记忆：{RUNTIME_DIR}/{智能体ID}/memory/ 下日笔记与 entries（本地多为 ackend/tmp/runtime/）。
3. 配置：环境变量或 mindlink.json → chat_context 段。

已知缺口（日后可处理）

8. 相关文档