Dicklesworthstone/coding_agent_session_search

🔎 coding-agent-search (cass) – 統一、高效率的 TUI，專為你的本地 AI 編碼助手歷史記錄設計

是什麼 – cass 是一個基於 Rust 的命令列/終端 UI 工具，可收集數十種流行編碼助手（Claude Code、GitHub Copilot Chat、Cursor、Aider 等）的對話日誌，將其歸一化為共通的 JSON 模式，儲存於本地 SQLite 歸檔中，並讓你立即搜尋。它完全離線運作；任何可選的語意搜尋皆在裝置上使用你明確安裝的小型 MiniLM 模型執行。

---

📦 安裝

• 單行指令碼（Linux/macOS/Windows PowerShell）：取得最新版本並驗證二進位檔。
• Homebrew tap（brew install dicklesworthstone/tap/cass）—— 預先建構好的 tarball，適用於 Linux 與 Apple Silicon macOS。
• Scoop 桶（Windows 專用）。
• 也可使用 --version <tag> 將套件固定至特定版本。

---

🚀 快速「機器人」（機器可讀）工作流程

步驟	命令	作用
1	cass triage --json	檢查歸檔健康狀態，並告知代理下一步該做什麼（next_command、recommended_commands 等）。
2	cass search "…" --robot --limit 5 --fields minimal	執行混合搜尋（快速詞法 + 可選 MiniLM 精煉），回傳適合自動化的 JSON 結果。
3	cass sessions --current --json	找到目前工作區的最新會話。
4	cass view <session>.jsonl -n 42 --json	從儲存的會話中取得單筆訊息（第 42 行）。
5	cass capabilities --json	列出完整的機器 API 表面（triage、search、models、doctor 等）。
6	cass sources agents exclude openclaw	停止未來索引中包含一個吵鬧的代理。

所有機器人命令僅將資料輸出至 stdout，診斷資訊輸出至 stderr，成功時回傳退出碼 0。

---

✨ 核心功能（口語化說明）

• 跨代理聚合 – 從超過 30 種不同編碼助手提取日誌，整合至一個可搜尋的時間軸中。
• 即時詞法搜尋 – 基於邊緣 n-gram 索引，即使在 10 GB 歸檔中也能實現 60 毫秒以下的查詢延遲。
• 可選語意搜尋 – 執行 cass models install 後，可獲得基於 MiniLM 的向量搜尋，仍為離線運作，當模型不存在時會回退至純詞法結果。
• 原子性、崩潰安全索引 – 每次詞法發布皆為原子重命名；保留前一版本的備份，支援一鍵回滾。
• 強健的診斷功能 – cass doctor 與 cass diag 可列舉被隔離的資產，建議安全清理操作，並可自動套用已驗證的修復。
• 穩定的 JSON 協定 – 所有機器人模式輸出遵循版本化模式，由黃金檔案測試保護，確保下游自動化安全。
• 離線運作 – 可自行提供 MiniLM 檔案（--from-file），安裝後無需網路存取。
• 可擴充的「機器人」模式 – 可被其他代理（如 LLM 驅動的工作流程）呼叫，以取得相關歷史對話作為上下文。

---

🛠️ 內部運作原理（高階）

1. 攝取 – 後台索引器讀取各種代理專用日誌格式，將每則訊息轉換為統一的 JSON 記錄，並寫入 SQLite 資料庫。
2. 詞法索引 – 基於 Tantivy 的自訂全文引擎建構邊緣 n-gram 索引，實現快速前綴匹配。
3. 語意向量 – 安裝 MiniLM 模型後，每則訊息被嵌入並儲存於 Frankensearch FSVI 向量檔案中；守護程序可為跨搜尋重用這些嵌入。
4. 混合查詢 – 搜尋首先返回詞法命中，若存在模型，則使用向量的餘弦相似度對排名進行精煉。
5. 原子發布 – 新的詞法版本透過原子交換發布；任何中斷的發布將在下次啟動時恢復。

---

👥 誰會受益

• 獨立開發者：在 Copilot、Cursor、Claude 等之間切換，但需要快速回憶過去解決方案，而無需翻閱大量檔案。
• 團隊：希望擁有共享、隱私保護的知識庫，記錄所有編碼助手的互動。
• AI 代理流程：可在機器人模式下呼叫 cass，用歷史回答豐富自身上下文。
• 高階使用者：希望在穩定 JSON API 上建構自訂分析（如 token 使用統計）。

---

📚 進一步閱讀

• 截圖 – 三面板 TUI，以顏色區分代理、Markdown 渲染的對話視圖、內建幫助畫面。
• 設計文件 – README 解釋了詞法發布耐久性模型、隔離/GC 政策，以及精確的錯誤封裝模式。
• 模型細節 – 英文用 all-minilm-l6-v2（約 90 MB），CJK/混合文字用 multilingual-minilm（約 480 MB）。

---

✅ 總結

cass 為你提供了一個快速、離線、跨代理的搜尋引擎，可搜尋你曾使用過的所有 AI 編碼助手歷史，並配備穩健的 CLI/JSON 接口，讓其他工具（或代理本身）可存取此知識庫。它以 Rust 編寫，以單一二進位檔分發，所有資料皆保留在你的機器上——無遙測、無雲端呼叫。