文档
参考文档
会话管理与压缩（深入探究）

会话管理与压缩（深入探究）

适用场景

在以下情况下使用本页面：

  • 你需要调试会话 ID、对话记录 JSONL 或 sessions.json 字段
  • 你正在更改自动压缩行为或添加"预压缩"维护任务
  • 你想要实现内存刷新或静默系统轮次

本文档解释了 Moltbot 如何端到端地管理会话：

  • 会话路由（入站消息如何映射到 sessionKey）
  • 会话存储（sessions.json）及其跟踪内容
  • 对话记录持久化（*.jsonl）及其结构
  • 对话记录清理（运行前的特定提供商修复）
  • 上下文限制（上下文窗口 vs 跟踪的令牌数）
  • 压缩（手动 + 自动压缩）以及在哪里挂接预压缩工作
  • 静默维护（例如不应产生用户可见输出的内存写入）

如果你希望先获得高层次概述，请从以下内容开始：

真实来源：网关

Moltbot 围绕拥有会话状态的单个网关进程设计。

  • UI（macOS 应用、Web 控制台 UI、TUI）应向网关查询会话列表和令牌计数。
  • 在远程模式下，会话文件位于远程主机上；“检查本地 Mac 文件"无法反映网关正在使用的内容。

两个持久化层

Moltbot 在两个层中持久化会话：

  1. 会话存储（sessions.json）

    • 键/值映射：sessionKey -> SessionEntry
    • 小型、可变、可安全编辑（或删除条目）
    • 跟踪会话元数据（当前会话 ID、最后活动时间、开关、令牌计数器等）

  2. 对话记录（<sessionId>.jsonl）

    • 具有树结构的仅追加对话记录（条目具有 id + parentId）
    • 存储实际的对话 + 工具调用 + 压缩摘要
    • 用于重建未来轮次的模型上下文

磁盘位置

对于每个代理，在网关主机上：

  • 存储：~/.moltbot/agents/<agentId>/sessions/sessions.json
  • 对话记录：~/.moltbot/agents/<agentId>/sessions/<sessionId>.jsonl
    • Telegram 主题会话：.../<sessionId>-topic-<threadId>.jsonl

Moltbot 通过 src/config/sessions.ts 解析这些路径。

会话键（sessionKey）

sessionKey 标识你所在的对话桶（路由 + 隔离）。

常见模式：

  • 主/直接聊天（每个代理）：agent:<agentId>:<mainKey>（默认为 main）
  • 群组：agent:<agentId>:<channel>:group:<id>
  • 房间/频道（Discord/Slack）：agent:<agentId>:<channel>:channel:<id> 或 ...:room:<id>
  • Cron：cron:<job.id>
  • Webhook：hook:<uuid>（除非被覆盖）

规范规则记录在 /concepts/session 中。

会话 ID（sessionId）

每个 sessionKey 指向一个当前的 sessionId（继续对话的对话记录文件）。

经验法则：

  • 重置（/new、/reset）为该 sessionKey 创建新的 sessionId。
  • 每日重置（默认为网关主机本地时间凌晨 4:00）在重置边界后的下一条消息上创建新的 sessionId。
  • 空闲过期（session.reset.idleMinutes 或旧版 session.idleMinutes）在空闲窗口后收到消息时创建新的 sessionId。当每日 + 空闲都配置时，先到期的那个生效。

实现细节：决策发生在 src/auto-reply/reply/session.ts 的 initSessionState() 中。

会话存储架构（sessions.json）

存储的值类型是 src/config/sessions.ts 中的 SessionEntry。

关键字段（非详尽）：

  • sessionId：当前对话记录 ID（除非设置了 sessionFile，否则文件名由此派生）
  • updatedAt：最后活动时间戳
  • sessionFile：可选的显式对话记录路径覆盖
  • chatType：direct | group | room（帮助 UI 和发送策略）
  • provider、subject、room、space、displayName：用于群组/频道标签的元数据
  • 开关：
    • thinkingLevel、verboseLevel、reasoningLevel、elevatedLevel
    • sendPolicy（每会话覆盖）
  • 模型选择：
    • providerOverride、modelOverride、authProfileOverride
  • 令牌计数器（尽力而为/依赖于提供商）：
    • inputTokens、outputTokens、totalTokens、contextTokens
  • compactionCount：此会话键完成自动压缩的频率
  • memoryFlushAt：上次预压缩内存刷新的时间戳
  • memoryFlushCompactionCount：上次刷新运行时的压缩计数

存储可安全编辑，但网关是权威：它可能会在会话运行时重写或重新填充条目。

对话记录结构（*.jsonl）

对话记录由 @mariozechner/pi-coding-agent 的 SessionManager 管理。

文件是 JSONL 格式：

  • 第一行：会话头部（type: "session"，包括 id、cwd、timestamp，可选的 parentSession）
  • 然后：带有 id + parentId 的会话条目（树）

值得注意的条目类型：

  • message：用户/助手/toolResult 消息
  • custom_message：扩展注入的确实进入模型上下文的消息（可以对 UI 隐藏）
  • custom：不进入模型上下文的扩展状态
  • compaction：持久化的压缩摘要，具有 firstKeptEntryId 和 tokensBefore
  • branch_summary：导航树分支时的持久化摘要

Moltbot 故意不“修复"对话记录；网关使用 SessionManager 来读取/写入它们。

上下文窗口 vs 跟踪的令牌

两个不同的概念很重要：

  1. 模型上下文窗口：每个模型的硬上限（模型可见的令牌）
  2. 会话存储计数器：写入 sessions.json 的滚动统计（用于 /status 和仪表板）

如果你正在调整限制：

  • 上下文窗口来自模型目录（可以通过配置覆盖）。
  • 存储中的 contextTokens 是运行时估计/报告值；不要将其视为严格保证。

更多信息，请参阅 /token-use。

压缩：它是什么

压缩将较旧的对话总结为对话记录中的持久化 compaction 条目，并保持最近的消息完整。

压缩后，未来的轮次将看到：

  • 压缩摘要
  • firstKeptEntryId 之后的消息

压缩是持久化的（与会话修剪不同）。请参阅 /concepts/session-pruning。

自动压缩何时发生（Pi 运行时）

在嵌入式 Pi 代理中，自动压缩在两种情况下触发：

  1. 溢出恢复：模型返回上下文溢出错误 → 压缩 → 重试。
  2. 阈值维护：在成功的轮次后，当：

contextTokens > contextWindow - reserveTokens

其中：

  • contextWindow 是模型的上下文窗口
  • reserveTokens 是为提示 + 下一个模型输出保留的余地

这些是 Pi 运行时语义（Moltbot 使用事件，但 Pi 决定何时压缩）。

压缩设置（reserveTokens、keepRecentTokens）

Pi 的压缩设置位于 Pi 设置中：

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000
  }
}

Moltbot 还为嵌入式运行强制执行安全底线：

  • 如果 compaction.reserveTokens < reserveTokensFloor，Moltbot 会提高它。
  • 默认底线是 20000 个令牌。
  • 设置 agents.defaults.compaction.reserveTokensFloor: 0 以禁用底线。
  • 如果它已经更高，Moltbot 不会动它。

原因：在压缩变得不可避免之前，为多轮"维护”（如内存写入）留出足够的余地。

实现：src/agents/pi-settings.ts 中的 ensurePiCompactionReserveTokens() （从 src/agents/pi-embedded-runner.ts 调用）。

用户可见的表面

你可以通过以下方式观察压缩和会话状态：

  • /status（在任何聊天会话中）
  • moltbot status（CLI）
  • moltbot sessions / sessions --json
  • 详细模式：🧹 Auto-compaction complete + 压缩计数

静默维护（NO_REPLY）

Moltbot 支持用于后台任务的"静默"轮次，其中用户不应看到中间输出。

约定：

  • 助手以其输出以 NO_REPLY 开头来指示"不要向用户发送回复”。
  • Moltbot 在传递层中剥离/抑制它。

从 2026.1.10 开始，当部分块以 NO_REPLY 开头时，Moltbot 还会抑制草稿/输入流，因此静默操作不会在轮次中途泄漏部分输出。

预压缩"内存刷新"（已实现）

目标：在自动压缩发生之前，运行一个静默代理轮次，将持久化状态写入磁盘（例如代理工作区中的 memory/YYYY-MM-DD.md），这样压缩就无法擦除关键上下文。

Moltbot 使用预阈值刷新方法：

  1. 监控会话上下文使用情况。
  2. 当它跨越"软阈值"（低于 Pi 的压缩阈值）时，向代理运行静默的"现在写入内存"指令。
  3. 使用 NO_REPLY，以便用户什么也看不到。

配置（agents.defaults.compaction.memoryFlush）：

  • enabled（默认：true）
  • softThresholdTokens（默认：4000）
  • prompt（刷新轮次的用户消息）
  • systemPrompt（为刷新轮次附加的额外系统提示）

注意事项：

  • 默认提示/系统提示包含 NO_REPLY 提示以抑制传递。
  • 刷新每个压缩周期运行一次（在 sessions.json 中跟踪）。
  • 刷新仅适用于嵌入式 Pi 会话（CLI 后端跳过它）。
  • 当会话工作区是只读的（workspaceAccess: "ro" 或 "none"）时，跳过刷新。
  • 有关工作区文件布局和写入模式，请参阅 Memory。

Pi 还在扩展 API 中公开了 session_before_compact 钩子，但 Moltbot 的刷新逻辑目前位于网关端。

故障排除清单

  • 会话键错误？从 /concepts/session 开始，并确认 /status 中的 sessionKey。
  • 存储与对话记录不匹配？确认网关主机和 moltbot status 中的存储路径。
  • 压缩垃圾邮件？检查：
    • 模型上下文窗口（太小）
    • 压缩设置（reserveTokens 对于模型窗口来说太高可能会导致更早压缩）
    • 工具结果膨胀：启用/调整会话修剪
  • 静默轮次泄漏？确认回复以 NO_REPLY 开头（确切的令牌），并且你处于包含流抑制修复的版本上。
发布检查清单（npm + macOS）设备型号数据库（友好名称）