JSONL 儲存庫
當排程工作需要記住它已經做過的事情——例如發出的警報、已處理的 ID、捕獲的事件——但資料庫又顯得多餘時，使用此技能。JSON Lines（每行一個 JSON 物件）易於附加、人類可讀、可透過 grep 搜尋，並且無需載入整個檔案即可串流。此輔助工具提供了原子性附加、即使在損毀行也能繼續的串流讀取，以及 append_unique(record, key) 功能，確保相同 ID 在跨執行時絕不會被寫入兩次。
何時使用
- 使用者說：「將結果記錄到 JSONL 檔案」、「將事件附加到磁碟」、「根據 ID 跨執行去重」、「無需資料庫保留簡單的歷史記錄」。
- 一個 cron/排程腳本需要在平面檔案中持久化、可於執行之間存取的狀態。
何時不要使用
- 你需要查詢、索引或並發寫入者——請使用 SQLite（
sqlite-state）或真正的資料庫。 - 記錄內容龐大或為二進位——JSONL 適用於小型結構化行。
具體範例
使用者輸入：
每次執行後，將新的警報附加到 alerts.jsonl，但同一警報 ID 不得重複。
輸出：
# 將 assets/store.py 複製到你的專案中，然後：
from store import JsonlStore
store = JsonlStore("data/alerts.jsonl")
for alert in new_alerts:
if store.append_unique(alert, key="id"):
send(alert) # 僅對先前任何執行中未見過的 ID 觸發
print("歷史記錄大小：", store.count())
讀取操作逐行串流，因此一整年的歷史記錄永遠不會完全載入記憶體；而因崩潰產生的半寫入最後一行會被跳過，不會中斷下一次執行。
要套用的模式
- 每行一個 JSON 物件；以
ensure_ascii=False附加，使文字保持可讀。 - 使用生成器進行串流讀取；跳過空白或損毀行而非拋出例外。
- 使用
seen_keys(key)/append_unique(record, key)進行去重，讓執行達到冪等性。 - 與排程器搭配使用，使檔案成為兩次調用之間的持久記憶體。
參考：assets/store.py。
來源
源自作者的排程機器人狀態處理。v1.0.0。 另請參閱：[[sqlite-state]]、[[cron-dispatch]]、[[pipeline-orchestrator]]。
→ 使用 Trawlkit 構建完整的可執行機器人。