Dicklesworthstone/coding_agent_session_search · 上手攻略

  • 仓库：Dicklesworthstone/coding_agent_session_search
  • 链接：https://github.com/Dicklesworthstone/coding_agent_session_search
  • 分类：开发工具 · AI 编程辅助
  • 作者：Jay
  • 更新：2026-09-03

这是什么

cass（Coding Agent Session Search）是一个用 Rust 编写的本地会话搜索工具，支持统一索引和检索来自 23 种 AI 编程工具的历史会话记录，包括 Codex、Claude Code、Claude Code（移动版）、Gemini CLI、Cline、OpenCode、Amp、Cursor、ChatGPT、Aider、Pi-Agent、Oh My Pi、GitHub Copilot Chat、Copilot CLI、OpenClaw、Clawdbot、Vibe、Crush、Goose、Hermes、Kimi Code、Muse Code、Qwen Code、Factory（Droid）、Antigravity、OpenHands 和 Grok Build。

每种工具存储会话的方式各不相同（JSONL、SQLite、Markdown 等），cass 的核心价值在于将这些碎片化数据统一标准化后存入 SQLite，再通过嵌入式全文搜索引擎 Tantivy 建立索引，实现跨工具、跨时间的毫秒级检索。所有数据留在本地，不上传任何内容。

状态：Alpha（Rust pinned nightly，MIT + OpenAI/Anthropic Rider 许可证）。

解决什么问题

AI 编程工具正在快速普及，但它们产生的大量对话记录存在严重的"数据孤岛"问题：

  • 存储格式割裂：每种工具用自己的方式存储——JSONL、SQLite、Markdown，各自不同。
  • 跨工具不可见：Cursor 里解决的问题，用 Claude Code 时完全找不到记录。
  • grep 无法语义搜索：文件级文本搜索根本不理解"第 42 行的 TypeError"对应什么上下文。
  • 历史记录难以复用：两周前的调试会话，找起来要手动翻文件。

cass 把这些散落的会话变成一个可查询的统一知识库，让你（和 AI agent 本身）都能从历史中快速捞到有价值的信息。

快速安装

Linux / macOS（推荐脚本）

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh?$(date +%s)" \
  | bash -s -- --easy-mode --verify

Windows PowerShell

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.ps1"))) -EasyMode -Verify

Homebrew（macOS Apple Silicon + Linux）

brew install dicklesworthstone/tap/cass

Scoop（Windows）

scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/cass

源码编译（需 Rust）

cargo install coding_agent_session_search

⚠️ 注意：v0.6.22 发布时 Windows 无预编译二进制（构建主机离线），Windows 用户可使用 install.ps1 脚本从源码构建，或等待后续版本恢复 Windows 资产。Linux ARM64 同样暂无预编译包，Homebrew formula 的 linux-arm64 分支可提供 v0.6.23 版本。

核心用法

⚠️ AI Agent 场景第一条铁律

永远不要在 agent 上下文中直接运行 cass——这会启动交互式 TUI 并阻塞终端。

# ❌ 错误：会阻塞
cass

# ✅ 正确：用 --robot 或 --json 输出机器可读格式
cass search "query" --robot
cass search "query" --json   # --robot 的别名

索引建立

首次安装后需要建立索引，后台增量索引会自动运行，也可以手动触发全量重建：

# 增量索引（新增/变更的会话文件）
cass index

# 全量重建（数据源有变化时）
cass index --full

# 监视模式：文件变化后自动重新索引
cass index --watch

# JSON 输出（agent 友好）
cass index --full --json

⚠️ cass index --full --force-rebuild 即使 schema 未变也会重建，适合 schema 升级后强制刷新。

检索搜索

基础搜索（默认混合模式：lexical 为快速路径，语义模型就绪后自动补充）：

# 搜索（JSON 输出）
cass search "authentication error" --robot --limit 5

# 带元数据的搜索（耗时、缓存命中率等）
cass search "error" --robot --robot-meta

# 最小负载（仅 path / line / agent）
cass search "bug" --robot --fields minimal

# 带高亮的搜索
cass search "authentication error" --robot --highlight

# 聚合统计（服务端计数，不传完整结果）
cass search "error" --robot --aggregate agent,workspace,date

时间过滤：

cass search "auth" --robot --days 7           # 最近 7 天
cass search "fix" --robot --yesterday         # 昨天
cass search "test" --robot --week            # 本周
cass search "auth" --robot --since 2024-01-01 --until 2024-01-31

通配符：

cass search "auth*" --robot           # 前缀：authentication, authorize
cass search "*tion" --robot           # 后缀
cass search "*config*" --robot       # 子串

Token 预算管理（对 LLM 场景关键）：

cass search "error" --robot --fields summary           # 加 title + score
cass search "error" --robot --max-content-length 500  # 截断字段
cass search "error" --robot --max-tokens 2000         # 软上限
cass search "error" --robot --limit 5                 # 结果数量上限

语义搜索（可选，需安装模型）

默认搜索是纯 lexical（基于 Tantivy 的倒排索引），语义搜索需要显式安装本地模型，不会自动下载：

# 安装默认语义模型 all-MiniLM-L6-v2（约 90 MB）
cass models install

# 安装多语言模型（支持中文/日文/韩文混合检索，约 480 MB）
cass models install --model multilingual-minilm

# 验证模型文件完整性
cass models verify --model minilm

# 模型状态
cass models status --json

# 检查更新
cass models check-update --json

安装后，混合搜索自动生效（lexical 兜底，语义模型就绪时补充 rerank）。模型不存在时，cass 返回 lexical-only 结果并报告 fallback_mode="lexical"，搜索从不因此阻塞。

会话管理

# 找当前工作区对应的会话
cass sessions --current --json

# 查找指定工作区的最近会话
cass sessions --workspace "$(pwd)" --json --limit 5

# 查看指定行的原始内容
cass view /path/to/session.jsonl -n 42 --json

# 展开上下文（某行 ±N 条消息）
cass expand /path/to/session.jsonl -n 42 -C 3 --json

# 导出会话为 Markdown
cass export /path/to/session.jsonl --format markdown -o conversation.md

# 导出为 HTML
cass export /path/to/session.jsonl --format html -o conversation.html

Agent 自查 API

cass 为 AI agent 提供了自描述接口，agent 可以通过这些命令了解 cass 自身的能力：

# 快速能力清单（健康检查 + 推荐命令）
cass triage --json
# 等价于：cass --json（零上下文时默认路由到 triage）

# 完整能力列表
cass capabilities --json

# 完整 API schema（所有命令的参数和响应结构）
cass introspect --json

# LLM 友好的分主题文档
cass robot-docs guide
cass robot-docs commands
cass robot-docs schemas
cass robot-docs examples
cass robot-docs exit-codes

⚠️ 重要：cass triage --json 是 agent 最安全的第一个命令——它综合了 readiness 状态、next_command 建议、recommended_commands[] 列表、文档指针和已接受的恢复方案，无需 agent 主动判断当前系统状态。

健康检查与诊断

# 快速健康检查（<50ms，退出码 0=健康 / 1=不健康）
cass health
cass health --json

# 完整状态快照
cass status --json

# 统计信息
cass stats --json

# 完整诊断（只读，不自动修复）
cass doctor --json

# 自动修复（仅对 dry-run 安全的操作生效）
cass doctor --fix --json

# 隔离诊断：仅检查二进制，不探测数据档案
cass health --binary-only --json

远程多机器搜索

cass 支持通过 SSH 索引和搜索其他机器上的会话——配置 sources.toml 后可统一查询局域网内所有机器的会话记录：

# 交互式向导（推荐首次配置）
cass sources setup

# 指定主机
cass sources setup --hosts css,csd,yto

# 预览（不实际修改）
cass sources setup --dry-run

# 恢复中断的设置
cass sources setup --resume

# 手动添加远程机器
cass sources add user@laptop.local --preset macos-defaults

# 列出所有来源
cass sources list --json

# 同步远程会话
cass sources sync

# 源级诊断
cass sources doctor --source laptop --json

# 删除来源
cass sources remove laptop --purge -y

典型适用场景

个人开发者：找回"我记得解决过这个问题"

# 搜索最近一个月内关于某类报错的讨论
cass search "TypeError: Cannot read" --robot --days 30 --agent claude

# 找某个文件相关的历史会话
cass context /path/to/source.ts --json

AI Agent：让当前 agent 学习历史 agent 的经验

# 当前工作区的历史会话
cass sessions --workspace "$(pwd)" --json --limit 5

# 找到相关讨论后导出给 agent 参考
cass expand /path/to/session.jsonl -n 42 -C 5 --json

团队：跨工具的知识复用

Cursor 用户解决了一个数据库迁移难题，Claude Code 用户通过搜索也能找到这个方案——不依赖任何人的记忆。

Token 预算紧张的 LLM 场景

# 精确控制输出大小
cass search "error" --robot --fields minimal --max-tokens 2000 --limit 3

坑与注意

  1. TUI 阻塞问题（最常见坑）：直接在 agent 脚本中运行 cass（无 --robot/--json）会启动交互式界面并永远卡住。所有 agent 调用必须带 --robot 或 --json。

  2. Windows 无预编译二进制：v0.6.22 发布时 Windows 构建主机离线，暂无 .zip 资产；Windows 用户需用 install.ps1 脚本从源码构建，或降级使用 v0.6.23（通过 Homebrew 的 linux-arm64 分支）。建议用 --verify 验证下载完整性。

  3. 语义搜索需要主动安装：不会自动下载模型，首次 cass models install 后才支持语义增强；安装前默认为 pure lexical，不影响基本使用。

  4. 多语言语义模型需显式选择：中文/日文/韩文检索需 cass models install --model multilingual-minilm，安装后还要 CASS_SEMANTIC_EMBEDDER=multilingual-minilm 环境变量切换空间。

  5. SQLite 是数据源，索引是派生状态：索引可从 SQLite 完全重建，索引文件损坏时运行 cass index --full --force-rebuild 即可。

  6. FTS 连续失败 5 次会退出：如果 FTS 修复连续失败 5 次，cass 会返回非零退出码（#434），此时需手动 cass doctor --rebuild-canonical-fts --yes --json。

  7. Homebrew Intel macOS 需从源码构建：Homebrew tap 在 Intel macOS 上没有预编译包，需加 --from-source 参数。

  8. Alpha 状态：接口和 schema 仍有变化可能，生产环境使用前建议关注 release 变更日志。

与同类对比

特性 cass aider.history.search OpenClaw 内置
支持工具数 23+ 种 仅 Aider 仅 OpenClaw
语义搜索 ✅（本地 MiniLM） ❌ ❌
多机器远程 ✅（SSH） ❌ ❌
Token 预算控制 ✅（--max-tokens 等） ❌ 部分
Agent 模式（--robot） ✅（完整 JSON API） ❌ 部分
导出格式 MD / HTML / JSON 仅 JSON 仅内嵌
平台 Linux/macOS/Win Linux/macOS 跨平台
许可 MIT+OpenAI/Anthropic Rider ISC 私有

cass 是目前支持最广的多 agent 会话搜索工具，对同时使用多种 AI 编程工具的开发者有不可替代的价值。aider.history.search 只服务 Aider 用户，而 OpenClaw 内置工具只服务 OpenClaw 本身。

一句话推荐

如果你同时使用两款以上的 AI 编程工具（Claude Code / Cursor / Aider / Codex 等），cass 是目前最完整的本地会话搜索方案——统一索引、毫秒检索、本地语义增强，让历史调试经验真正可复用，而非散落在各个工具的数据孤岛里。