會話與投遞

源码版本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 但不可或缺的可靠性層。