会话与投递

源码版本v2026.7.20

职责

两件事:① 会话(Session)——把「消息从哪来」(平台、chat、发送者)归到一个稳定 key,并持久化对话到磁盘,让 agent 跨重启续上下文;② 投递账本(Delivery Ledger)——为 agent 的最终回复记一笔「送达义务」,崩溃后能识别未投递的回复并补发,保证用户最终收到。两者都在网关层,与 agent 解耦。

关键文件

• class SessionSource:149-299 — 消息来源数据类(platform/chat/sender,带哈希)
• class SessionContext:299-700 — 会话上下文(key、来源、续接策略)
• id 哈希:40-74 — _hash_id / _hash_sender_id / _hash_chat_id(隐私 + 稳定)
• 路径安全校验:100-149 — _is_path_unsafe / _is_session_key_unsafe(session key 流入文件系统路径)
• auto_continue 新鲜窗:26-40 — auto_continue_freshness_window
• 投递账本文档:1-58 — 设计目标:best-effort,失败永不阻塞主流程
• compute_obligation_id:146-155 — 唯一义务 id(会话 key + 消息 ref + 内容)
• 状态机:155-203 — record_obligation / mark_attempting / mark_delivered / mark_failed
• sweep_recoverable:203-276 — 崩溃后扫描可恢复义务并补发
• SQLite 连接:77-102 — _db_path / _connect,持久化在本地 sqlite

数据流

1. 适配器收到平台事件,经 MessageEvent:1759 带出 SessionSource。
2. SessionSource:149 哈希出稳定的 chat/sender id(gateway/session.py:40)。
3. 构造 SessionContext:299,得到 session key(经 路径安全校验:109 后用作磁盘路径)。
4. session key 决定历史从哪个文件加载,喂给 agent 续上下文。
5. agent 产出最终回复后,网关在 record_obligation:155 记账 → 发送 → mark_delivered。
6. 若发送中崩溃,下次启动 sweep_recoverable(gateway/delivery_ledger.py:203)扫描 attempting 状态且属主进程已死的义务,补发或标记失败。

小结

会话层负责「这条消息属于哪段持续对话」,用哈希 + 路径校验把外部身份安全映射到磁盘文件。投递账本负责「agent 想发的最终回复是否真的到了用户手里」,用 sqlite 状态机做崩溃恢复。两者都是 best-effort 但不可或缺的可靠性层。