SuperAPI AI 工具集

cass

编程与开发

查看项目

更新于 10-17 00:38

技能介绍

用途

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