用途
CASS(Coding Agent Session Search)是一个统一的命令行界面(CLI)和终端用户界面(TUI)工具,用于索引和搜索本地的编码智能体会话历史。它的主要目标是解决编码智能体产生的知识分散问题——Claude Code 的会话存储在 ~/.claude/projects、Codex 存储在 ~/.codex/sessions、Cursor 的状态存储在 SQLite 数据库中、Aider 历史存储在 markdown 文件中——CASS 将所有这些统一到一个可搜索的索引中。
CASS 聚合来自 23 个智能体的会话记录,包括 Claude Code、Codex、Gemini CLI、Cline、OpenCode、Amp、Cursor、ChatGPT、Aider、Pi-Agent、Factory(Droid)、OpenHands、Antigravity 和 Grok Build 等。当用户遇到问题时,可以跨所有历史智能体会话进行搜索以查找相关解决方案。
主要能力
索引与搜索
- 支持全量重建索引(cass index --full)和增量更新(cass index)
- 监听模式可自动在文件变更时重新索引(cass index --watch)
- 支持幂等键的安全重试(24 小时 TTL)
- 提供词汇(lexical/BM25 全文)、语义(semantic/向量相似度)和混合(hybrid/倒数排名融合 RRF)三种搜索模式,默认使用混合模式
智能体友好的机器人模式
- 必须使用 --robot 或 --json 标志获取机器可读输出,避免启动阻塞终端的交互式 TUI
- 提供自文档化 API:cass capabilities --json、cass introspect --json、cass robot-docs(guide/commands/schemas/examples/exit-codes/contracts/sources)
- 容错语法:自动纠正常见拼写错误(如 serach→search)、单破折号转双破折号、大小写规范化、编辑距离≤2 的参数纠正
- 命令别名映射:find/query/q/lookup/grep→search,ls/list/info/summary→stats 等
Token 预算管理
- --fields minimal 仅返回 source_path、line_number、agent
- --fields summary 增加 title、score
- --max-content-length 截断长字段(UTF-8 安全)
- --max-tokens 软预算(约 4 字符/token)
- --limit 限制结果数量
- 截断字段包含 *_truncated: true 指示器
会话分析
- 导出对话为 markdown/HTML/JSON(cass export)
- 展开行周围上下文(cass expand -n 42 -C 5)
- 查看源码行(cass view -n 42)
- 活动时间线(cass timeline --today --group-by hour)
- 查找文件相关会话(cass context)
聚合与分析
- 服务端聚合计数与分布:--aggregate agent,workspace,date
- 按智能体类型、工作空间/项目路径、日期、匹配质量分组
- 每字段返回前 10 个桶,其余归入 other_count
远程多机搜索
- 通过 SSH/rsync 搜索多台机器的会话
- 设置向导(cass sources setup)自动发现 SSH 主机、探测智能体数据、可选远程安装、索引远程会话、配置 sources.toml、本地同步
- 手动添加远程源(cass sources add)、同步(sync)、连通性检查(doctor)、路径映射(mappings)
- 配置文件位于 ~/.config/cass/sources.toml(Linux)或 ~/Library/Application Support/cass/sources.toml(macOS)
管道模式(链式搜索)
- 通过管道传递会话路径实现链式搜索:先找包含 auth 的会话,再在其中搜索 token 刷新
- 支持 --sessions-from - 从标准输入读取会话列表
- 可用于深入探索、交叉引用、构建过滤语料库
结构化错误处理
- JSON 错误包含 code、kind、message、hint、retryable
- 退出码 0-9 分别对应成功、健康检查失败、用法错误、索引/数据库缺失、网络错误、数据/维护失败、版本不兼容、锁/繁忙、部分结果、未知错误
- 搜索预算超时可返回退出码 0 且 budget.timed_out=true;会话路径输出超时使用退出码 10
使用方式
安装与验证
资料未提供安装命令。使用时建议先通过 cass --version 和 cass search --help 确认版本(资料中的标志集在 cass 0.8.0 上验证)。
快速检索示例
cass search "performance regression" --workspace /path/to/project --days 7 \\
--mode lexical --no-maintenance --robot --robot-meta --fields minimal \\
--limit 5 --max-tokens 2000 --timeout 2000
cass view /path/to/session.jsonl -n 42 -C 3 --json --timeout 2000
当前会话查找与导出
cass sessions --current --json
cass export-html "$(cass sessions --current --json | jq -r '.sessions[0].path')" --json
查询语言
- 基本查询:error(包含 error,不区分大小写)、python error(同时包含)、"authentication failed"(精确短语)
- 布尔运算:AND(默认)、OR、NOT、-(NOT 简写)
- 通配符:auth*(前缀)、*tion(后缀)、config(子串)
- 复杂查询:cass search "authentication AND (error OR failure) NOT test" --robot
适用场景
- "我之前解决过这个问题":按日期、工作空间搜索历史会话
- 跨智能体学习:搜索任何智能体对某主题的讨论
- 智能体间交接:搜索数据库迁移等主题
- 日常回顾:查看今日活动时间线
- 深入探索:广泛搜索后在结果中缩小范围
- 构建语料库:保存会话列表用于重复搜索
限制与注意事项
- 绝不要直接运行 cass(不带参数),会启动阻塞终端的交互式 TUI
- AI 智能体必须使用 --robot 或 --json 标志
- --timeout 单位为毫秒;--max-tokens 是近似输出预算,非 CPU 或内存限制
- 需在调用方设置墙钟截止时间(如 GNU timeout 10s)
- 退出码 124 表示未完成尝试,中断的 stdout 可能不是有效 JSON
- 即使退出码 0,也应检查 JSON 输出中的 budget.timed_out
- view -C 3 限制的是周围行数而非字节或 token,单条 JSONL 记录可能很大
- 若 --no-maintenance 不受支持,应停止并报告版本不匹配,静默移除会允许维护操作
- 若返回 maintenance-required,应报告阻塞并停止本次检索
- 聚合减少输出量,但不一定减少扫描工作
- 退出码是命令相关的,需查阅 cass robot-docs exit-codes 和 JSON 错误类型
- 搜索预算到期可返回退出码 0 且 budget.timed_out=true;会话路径输出超时使用退出码 10