Dicklesworthstone/coding_agent_session_search

🔎 coding-agent-search (cass) – 你的本地 AI 编码助手历史记录的统一高性能 TUI

是什么 – cass 是一个基于 Rust 的命令行/终端 UI 工具，它收集数十种流行编码助手（Claude Code、GitHub Copilot Chat、Cursor、Aider 等）的对话日志，将其归一化为统一的 JSON 模式，存储在本地 SQLite 归档中，并让你能够即时搜索。它完全离线运行；任何可选的语义搜索都在设备上使用你显式安装的小型 MiniLM 模型执行。

---

📦 安装

• 单行脚本（Linux/macOS/Windows PowerShell）：获取最新发布版本并验证二进制文件。
• Homebrew tap（brew install dicklesworthstone/tap/cass）—— 适用于 Linux 和 Apple Silicon macOS 的预构建 tarball。
• 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 编写，以单个二进制文件分发，所有数据都保留在你的机器上——无遥测，无云调用。