cass

CASS - 编码 Agent 会话搜索

用于索引和搜索本地编码 Agent 历史记录的统一高性能 CLI/TUI。汇总了 23 款 Agent 的会话，包括 Codex、Claude Code、Gemini CLI、Cline、OpenCode、Amp、Cursor、ChatGPT、Aider、Pi-Agent、Factory (Droid)、OpenHands、Antigravity 和 Grok Build。

重要提示：AI Agent 必须使用 Robot 模式

绝不要直接运行 cass —— 它会启动交互式 TUI，阻塞当前会话！

# WRONG - blocks terminal
cass

# CORRECT - JSON output for agents
cass search "query" --robot
cass search "query" --json  # alias

务必使用 --robot 或 --json 标志，以获取机器可读的输出。

---

AI Agent 快速参考

有界历史检索

对于快速查询项目历史记录，先执行一次范围明确的查询。 下面的标志组合已在 cass 0.8.0 上验证；每个安装版本只需检查一次 cass --version 和 cass search --help。如果不支持 --no-maintenance，请停止并报告版本不匹配；静默移除该标志会导致维护操作得以执行。

# Specific terms, one workspace, recent history, small cited result set
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

# Expand only a useful hit, using its exact source_path and line_number
cass view /path/to/session.jsonl -n 42 -C 3 --json --timeout 2000

--timeout 的单位是毫秒；--max-tokens 是近似输出预算， 不是 CPU 或内存限制。还应在调用方设置墙钟时间期限（例如，在命令前使用 GNU timeout 10s）。该包装命令返回 124 表示尝试未完成；被中断的 stdout 可能不是有效的 JSON。在 JSON 搜索输出中，即使退出码为 0，也要检查 budget.timed_out：超时后没有结果并不能证明不存在历史记录。

view -C 3 限制的是周边行数，而不是字节数或 Token 数；单条 JSONL 记录可能很大。将摘录添加到提示词前，请先检查输出大小。

混合模式仍是产品默认设置。显式使用词法模式可避免此工作流进行语义推断；--no-maintenance 可阻止索引修复、追赶更新和守护进程自动启动。如果返回 maintenance-required，请报告该阻碍并停止本次检索。不要把摘要请求变成索引、修复、安装模型、通配符聚合或反复检查健康状态的工作流。诊断就绪状态时，请使用就绪状态命令；开始单独的变更任务前，请先审查这些命令提出的操作。完成一次查询后，再有目的地扩大日期范围或搜索词；仅在需要概念检索且成本可接受时，才选择语义或混合模式。摘要中应保留来源和行号引用。

基本命令

# Find the current session for this workspace
cass sessions --current --json

# List recent sessions for a specific project
cass sessions --workspace "$(pwd)" --json --limit 5

# Common agent flow: find current session, then export it
cass export-html "$(cass sessions --current --json | jq -r '.sessions[0].path')" --json

# Search with JSON output
cass search "authentication error" --robot --limit 5

# Search with metadata (elapsed_ms, cache stats, freshness)
cass search "error" --robot --robot-meta

# Minimal payload (path, line, agent only)
cass search "bug" --robot --fields minimal

# View source at specific line
cass view /path/to/session.jsonl -n 42 --json

# Expand context around a line
cass expand /path/to/session.jsonl -n 42 -C 5 --json

# Capabilities discovery
cass capabilities --json

# Full API schema
cass introspect --json

# LLM-optimized documentation
cass robot-docs guide
cass robot-docs commands
cass robot-docs schemas
cass robot-docs examples
cass robot-docs exit-codes

---

为什么使用 CASS

跨 Agent 知识迁移

你的编码 Agent 会产生分散的知识：

• Claude Code 会话位于 ~/.claude/projects
• Codex 会话位于 ~/.codex/sessions
• Cursor 状态存储在 SQLite 数据库中
• Aider 历史记录存储在 Markdown 文件中

CASS 将所有这些内容统一起来，存入一个可搜索的索引中。遇到问题时，可以搜索过去所有 Agent 会话，查找相关解决方案。

使用场景

# "I solved this before..."
cass search "TypeError: Cannot read property" --robot --days 30

# Cross-agent learning (what has ANY agent said about X?)
cass search "authentication" --robot --workspace /path/to/project

# Agent-to-agent handoff
cass search "database migration" --robot --fields summary

# Daily review
cass timeline --today --json

---

命令参考

索引

# Full rebuild of DB and search index
cass index --full

# Incremental update (since last scan)
cass index

# Watch mode: auto-reindex on file changes
cass index --watch

# Force rebuild even if schema unchanged
cass index --full --force-rebuild

# Safe retries with idempotency key (24h TTL)
cass index --full --idempotency-key "build-$(date +%Y%m%d)"

# JSON output with stats
cass index --full --json

搜索

# Basic search (JSON output required for agents!)
cass search "query" --robot

# With filters
cass search "error" --robot --agent claude --days 7
cass search "bug" --robot --workspace /path/to/project
cass search "panic" --robot --today

# Time filters
cass search "auth" --robot --since 2024-01-01 --until 2024-01-31
cass search "test" --robot --yesterday
cass search "fix" --robot --week

# Wildcards
cass search "auth*" --robot          # prefix: authentication, authorize
cass search "*tion" --robot          # suffix: authentication, exception
cass search "*config*" --robot       # substring: misconfigured

# Token budget management (critical for LLMs!)
cass search "error" --robot --fields minimal              # path, line, agent only
cass search "error" --robot --fields summary              # adds title, score
cass search "error" --robot --max-content-length 500      # truncate fields
cass search "error" --robot --max-tokens 2000             # soft budget (~4 chars/token)
cass search "error" --robot --limit 5                     # cap results

# Pagination (cursor-based)
cass search "TODO" --robot --robot-meta --limit 20
# Use _meta.next_cursor from response:
cass search "TODO" --robot --robot-meta --limit 20 --cursor "eyJ..."

# Match highlighting
cass search "authentication error" --robot --highlight

# Query analysis/debugging
cass search "auth*" --robot --explain    # parsed query, cost estimates
cass search "auth error" --robot --dry-run  # validate without executing

# Aggregations (server-side counts)
cass search "error" --robot --aggregate agent,workspace,date

# Request correlation
cass search "bug" --robot --request-id "req-12345"

# Source filtering (for multi-machine setups)
cass search "auth" --robot --source laptop
cass search "error" --robot --source remote

# Traceability (for debugging agent pipelines)
cass search "error" --robot --trace-file /tmp/cass-trace.json

会话分析

# Export conversation to markdown/HTML/JSON
cass export /path/to/session.jsonl --format markdown -o conversation.md
cass export /path/to/session.jsonl --format html -o conversation.html
cass export /path/to/session.jsonl --format json --include-tools

# Expand context around a line (from search result)
cass expand /path/to/session.jsonl -n 42 -C 5 --json
# Shows 5 messages before and after line 42

# View source at line
cass view /path/to/session.jsonl -n 42 --json

# Activity timeline
cass timeline --today --json --group-by hour
cass timeline --days 7 --json --agent claude
cass timeline --since 7d --json

# Find related sessions for a file
cass context /path/to/source.ts --json

状态与诊断

# Readiness diagnosis, when needed; not a prerequisite for every query
cass health --json

# Full status snapshot
cass status --json
cass state --json  # alias

# Statistics
cass stats --json
cass stats --by-source  # for multi-machine

# Full diagnostics
cass diag --verbose

---

聚合与分析

在服务端聚合搜索结果，以获取计数和分布，而无需传输完整结果数据：

聚合会减少输出量，但不一定会减少扫描工作量。对于快速查询历史记录，它并非首选步骤；请使用上面的范围明确的检索方法。

# Count results by agent
cass search "error" --robot --aggregate agent
# → { "aggregations": { "agent": { "buckets": [{"key": "claude_code", "count": 45}, ...] } } }

# Multi-field aggregation
cass search "bug" --robot --aggregate agent,workspace,date

# Combine with filters
cass search "TODO" --agent claude --robot --aggregate workspace

聚合字段	描述
agent	按 Agent 类型分组（claude_code、codex、cursor 等）
workspace	按工作区／项目路径分组
date	按日期分组（YYYY-MM-DD）
match_type	按匹配质量分组（exact、prefix、fuzzy）

每个字段最多返回前 10 个分组，剩余项目计入 other_count。

---

远程来源（多机搜索）

通过 SSH/rsync 搜索多台机器上的会话。

设置向导（推荐）

cass sources setup

该向导会：

1. 从 ~/.ssh/config 中发现 SSH 主机
2. 探测每台主机上的 Agent 数据和 cass 安装情况
3. 可选择在远程主机上安装 cass
4. 在远程主机上为会话建立索引
5. 配置 sources.toml
6. 在本地同步数据

cass sources setup --hosts css,csd,yto  # Specific hosts only
cass sources setup --dry-run             # Preview without changes
cass sources setup --resume              # Resume interrupted setup

手动设置

# Add a remote machine
cass sources add [email protected] --preset macos-defaults
cass sources add dev@workstation --path ~/.claude/projects --path ~/.codex/sessions

# List sources
cass sources list --json

# Sync sessions
cass sources sync
cass sources sync --source laptop --verbose

# Check connectivity
cass sources doctor
cass sources doctor --source laptop --json

# Path mappings (rewrite remote paths to local)
cass sources mappings list laptop
cass sources mappings add laptop --from /home/user/projects --to /Users/me/projects
cass sources mappings test laptop /home/user/projects/myapp/src/main.rs

# Remove source
cass sources remove laptop --purge -y

配置存储在 ~/.config/cass/sources.toml（Linux）或 ~/Library/Application Support/cass/sources.toml（macOS）中。

---

深入了解机器人模式

自描述 API

CASS 会教 Agent 如何使用自身：

# Quick capability check
cass capabilities --json
# Returns: features, connectors, limits

# Full API schema
cass introspect --json
# Returns: all commands, arguments, response shapes

# Topic-based docs (LLM-optimized)
cass robot-docs commands   # all commands and flags
cass robot-docs schemas    # response JSON schemas
cass robot-docs examples   # copy-paste invocations
cass robot-docs exit-codes # error handling
cass robot-docs guide      # quick-start walkthrough
cass robot-docs contracts  # API versioning
cass robot-docs sources    # remote sources guide

宽容的语法（适合 Agent）

CASS 会自动纠正常见错误：

输入内容	CASS 的理解
cass serach "error"	cass search "error"（已纠正拼写错误）
cass -robot -limit=5	cass --robot --limit=5（已修正单短横线）
cass --Robot --LIMIT 5	cass --robot --limit 5（已统一大小写）
cass find "auth"	cass search "auth"（已解析别名）
cass --limt 5	cass --limit 5（Levenshtein 距离 <=2）

命令别名：

• find、query、q、lookup、grep → search
• ls、list、info、summary → stats
• st、state → status
• reindex、idx、rebuild → index
• show、get、read → view
• docs、help-robot、robotdocs → robot-docs

输出格式

# Pretty-printed JSON (default)
cass search "error" --robot

# Streaming JSONL (header + one hit per line)
cass search "error" --robot-format jsonl

# Compact single-line JSON
cass search "error" --robot-format compact

# With performance metadata
cass search "error" --robot --robot-meta

设计原则： stdout 仅输出 JSON；诊断信息发送到 stderr。

Token 预算管理

大模型有上下文限制。请控制输出大小：

标志	效果
--fields minimal	仅包含 source_path、line_number、agent
--fields summary	添加 title、score
--fields score,title,snippet	自定义字段选择
--max-content-length 500	截断较长字段（UTF-8 安全）
--max-tokens 2000	软预算（约 4 个字符/token）
--limit 5	限制结果数量

被截断的字段会包含 *_truncated: true 标记。

---

结构化错误处理

错误以 JSON 格式提供，并附带可操作的提示：

{
  "error": {
    "code": 3,
    "kind": "index_missing",
    "message": "Search index not found",
    "hint": "Run 'cass index --full' to build the index",
    "retryable": false
  }
}

退出代码

代码	含义	操作
0	成功	解析 stdout
1	健康检查失败	检查报告的问题；不会自动重建
2	用法错误	修正语法（会提供提示）
3	索引/数据库缺失	报告缺失的资源；索引是单独的修改性任务
4	网络错误	检查连接
5	数据/维护失败	查看错误类型；保留存档并报告阻碍因素
6	版本不兼容	更新 cass
7	锁定/繁忙	稍后重试
8	部分结果	报告覆盖不完整；不要静默重试
9	未知错误	检查 retryable 标志

退出代码因命令而异：请查阅 cass robot-docs exit-codes 和 JSON 错误类型。搜索预算到期时，可能返回退出代码 0，并设置 budget.timed_out=true； 会话路径输出则在超时时使用退出代码 10。

---

搜索模式

三种搜索模式，可通过 --mode 标志选择：

模式	算法	适用场景
lexical	BM25 全文搜索	精确匹配词项、有界历史记录配方
semantic	向量相似度	概念查询、“查找相似内容”
hybrid（默认）	倒数排名融合	词汇检索，并在就绪时进行语义优化

cass search "authentication" --mode lexical --robot
cass search "how to handle user login" --mode semantic --robot
cass search "auth error handling" --mode hybrid --robot

Hybrid 使用 RRF 结合词汇和语义搜索：

RRF_score = Σ 1 / (60 + rank_i)

---

流水线模式（链式搜索）

通过管道传递会话路径，将搜索串联起来：

# Find sessions mentioning "auth", then search within those for "token"
cass search "authentication" --robot-format sessions | \
  cass search "refresh token" --sessions-from - --robot

# Build a filtered corpus from today's work
cass search --today --robot-format sessions > today_sessions.txt
cass search "bug fix" --sessions-from today_sessions.txt --robot

使用场景：

• 深入查询： 先进行广泛搜索 → 再在结果中缩小范围
• 交叉引用： 查找包含词项 A 的会话，再在其中查找词项 B
• 构建语料库： 保存会话列表，以便重复搜索

---

查询语言

基本查询

查询	匹配内容
error	包含 "error" 的消息（不区分大小写）
python error	同时包含 "python" 和 "error"
"authentication failed"	精确短语

布尔运算符

运算符	示例	含义
AND	python AND error	必须同时包含两个词项（默认）
OR	error OR warning	匹配任一词项
NOT	error NOT test	包含第一个词项，但排除第二个词项
-	error -test	NOT 的简写

# Complex boolean query
cass search "authentication AND (error OR failure) NOT test" --robot

# Exclude test files
cass search "bug fix -test -spec" --robot

# Either error type
cass search "TypeError OR ValueError" --robot

通配符模式

模式	类型	性能
auth*	前缀	快（边缘 n-gram）
*tion	后缀	较慢（正则表达式）
*config*	子串	最慢（正则表达式）

匹配类型

结果包含 match_type：

类型	含义	分数加成
exact	完全匹配	最高
prefix	通过前缀扩展匹配	高
suffix	通过后缀模式匹配	中
substring	通过子串模式匹配	较低
fuzzy	自动回退（结果较少时）	最低

自动模糊回退

当精确查询返回的结果少于 3 条时，CASS 会自动使用通配符重试：

• auth → *auth*
• 结果会标记为 wildcard_fallback: true

灵活的时间输入

CASS 接受多种时间／日期格式：

格式	示例
相对时间	-7d、-24h、-30m、-1w
关键词	now、today、yesterday
ISO 8601	2024-11-25、2024-11-25T14:30:00Z
美国日期格式	11/25/2024、11-25-2024
Unix 时间戳	1732579200（秒或毫秒）

---

排序模式

在 TUI 中按 F12 循环切换，或使用 --ranking 标志：

模式	公式	适用场景
近期优先	relevance*0.3 + recency*0.7	“我之前在做什么？”
平衡	relevance*0.5 + recency*0.5	常规搜索
相关性优先	relevance*0.8 + recency*0.2	“X 的最佳解释”
匹配质量	对模糊匹配进行降权	精确的技术搜索
日期由新到旧	纯按时间顺序	近期活动
日期由旧到新	按时间倒序	“我最早是什么时候……”

分数构成

• 文本相关性（BM25）：词频、逆文档频率、长度归一化
• 时间近远：指数衰减（今天约为 1.0，上周约为 0.7，上个月约为 0.3）
• 匹配精确度：精确短语 = 1.0，前缀 = 0.9，后缀 = 0.8，子串 = 0.6，模糊匹配 = 0.4

混合评分公式

Final_Score = BM25_Score × Match_Quality + α × Recency_Factor

模式	α 值	效果
近期优先	1.0	时间近远占主导
平衡	0.4	适度提高近期结果的权重
相关性优先	0.1	BM25 占主导
匹配质量	0.0	纯文本匹配

---

支持的 Agent（23 个连接器）

Agent	位置	格式
Claude Code	~/.claude/projects	JSONL
Codex	~/.codex/sessions	JSONL（Rollout）
Gemini CLI	~/.gemini/tmp	JSON
Cline	VS Code 全局存储	任务目录
OpenCode	.opencode 目录	SQLite
Amp	~/.local/share/amp + VS Code	混合
Cursor	~/Library/Application Support/Cursor	SQLite（state.vscdb）
ChatGPT	~/Library/Application Support/com.openai.chat	JSON（v1 未加密）
Aider	~/.aider.chat.history.md + 各项目目录	Markdown
Pi-Agent	~/.pi/agent/sessions	含思考内容的 JSONL
Factory (Droid)	~/.factory/sessions	按工作区划分的 JSONL
GitHub Copilot Chat	VS Code 全局存储	JSON / SQLite
GitHub Copilot CLI	~/.copilot/session-state	JSONL
OpenClaw	~/.openclaw	JSONL
ClawdBot	~/.clawdbot	JSONL
Vibe	~/.vibe/logs/session	JSONL
Crush	~/.crush/crush.db	SQLite
Hermes	~/.hermes	JSONL
Kimi Code	~/.kimi/sessions	JSONL
Qwen Code	~/.qwen/tmp	JSON / JSONL
OpenHands	~/.openhands/conversations	JSON 事件流
Antigravity	~/.gemini/antigravity-cli	JSONL / SQLite
Grok Build	$GROK_HOME/sessions（默认 ~/.grok/sessions）	ACP 更新 JSONL

注意： ChatGPT v2/v3 使用 AES-256-GCM 加密（需要访问密钥链）。旧版 v1 未加密的对话会自动编入索引。

---

TUI 功能（面向用户）

不带标志运行 cass 即可启动：

键盘快捷键

导航：

• Up/Down：移动选中项
• Left/Right：切换窗格
• Tab/Shift+Tab：循环切换焦点
• Enter：在 $EDITOR 中打开
• Space：全屏详情视图
• Home/End：跳转到第一个／最后一个结果
• PageUp/PageDown：按页滚动

筛选：

• F3：Agent 筛选
• F4：工作区筛选
• F5/F6：时间筛选（起始／结束）
• Shift+F3：将范围限定为当前结果的 Agent
• Shift+F4：清除工作区筛选
• Shift+F5：循环切换预设（24h/7d/30d/all）
• Ctrl+Del：清除所有筛选条件

模式：

• F2：切换主题（6 种预设）
• F7：上下文窗口大小（S/M/L/XL）
• F9：匹配模式（prefix/standard）
• F12：排序模式
• Ctrl+B：切换边框样式

选择与操作：

• m：切换选中状态
• Ctrl+A：全选
• A：批量操作菜单
• Ctrl+Enter：加入队列
• Ctrl+O：打开队列中的所有项目
• y：复制路径／内容
• Ctrl+Y：复制所有选中项
• /：在详情窗格中查找
• n/N：下一个／上一个匹配项

视图与调色板：

• Ctrl+P：命令调色板
• 1-9：加载已保存的视图
• Shift+1-9：将视图保存到对应槽位

来源筛选（多机器）：

• F11：循环切换来源筛选（all/local/remote）
• Shift+F11：来源选择菜单

全局：

• Ctrl+C：退出
• F1 或 ?：切换帮助
• Ctrl+Shift+R：强制重新索引
• Ctrl+Shift+Del：重置所有 TUI 状态

详情窗格选项卡

选项卡	内容	切换方式
Messages	包含 Markdown 的完整对话	[ / ]
Snippets	提取关键词生成的摘要	[ / ]
Raw	未格式化的 JSON／文本	[ / ]

上下文窗口大小

大小	字符数	使用场景
Small	~200	快速浏览
Medium	~400	默认的均衡视图
Large	~800	较长的段落
XLarge	~1600	完整上下文、代码审查

Peek 模式（Ctrl+Space）：临时扩展到 XL，不更改默认设置。

---

主题预设

按 F2 循环切换 6 种内置主题：

主题	描述	适用场景
Dark	灵感源自 Tokyo Night 的深蓝色调	低光照环境
Light	高对比度浅色背景	明亮环境
Catppuccin	温暖的柔和色调，减轻眼部疲劳	全天编码
Dracula	紫色点缀的深色主题	广受欢迎的开发者主题
Nord	灵感源自北极的冷色调	平静、专注的工作
High Contrast	最高可读性	无障碍需求

所有主题均已通过 WCAG 对比度要求验证（文本最低为 4.5:1）。

按角色设置消息样式

角色	视觉样式
User	蓝色调背景、粗体
Assistant	绿色调背景
System	灰色／低饱和度背景
Tool	橙色调背景

---

已保存的视图

将筛选配置保存到 9 个槽位，方便快速调用。

保存的内容：

• 当前启用的筛选条件（Agent、工作区、时间范围）
• 当前排序模式
• 搜索查询

键盘快捷键：

• Shift+1 到 Shift+9：保存当前视图
• 1 到 9：加载对应槽位中的视图

通过命令调色板： Ctrl+P → "Save/Load view"

视图会跨会话保存在 tui_state.json 中。

---

密度模式

控制每个搜索结果显示的行数。按 Shift+D 循环切换：

模式	行数	适用场景
Compact	3	显示最多结果
Cozy	5	均衡视图（默认）
Spacious	8	详细预览

---

书签系统

为重要结果添加备注和标签并保存：

在 TUI 中：按 b 添加书签，并添加备注和标签。

书签结构：

• title：简短描述
• source_path、line_number、agent、workspace
• note：你的注释
• tags：以逗号分隔的标签
• snippet：提取的内容

存储位置：~/.local/share/coding-agent-search/bookmarks.db（SQLite）

---

可选语义搜索

使用 MiniLM 进行仅限本地的语义搜索（无需云服务）：

必需文件（放置在数据目录中）：

• model.onnx
• tokenizer.json
• config.json
• special_tokens_map.json
• tokenizer_config.json

向量索引存储为 vector_index/index-minilm-384.cvvi。

CASS 不会自动下载模型；你必须手动安装。

**哈希嵌入器回退：**未安装 MiniLM 时，CASS 会使用基于哈希的嵌入器来近似计算语义相似度。

---

监视模式

实时更新索引：

cass index --watch

• **防抖：**2 秒（等待一批事件处理完毕）
• **最长等待时间：**5 秒（持续有活动时强制刷新）
• **增量处理：**仅重新扫描已修改的文件

TUI 会自动在后台启动监视模式。

---

去重策略

CASS 使用多层去重：

1. **消息哈希：**对 (role + content + timestamp) 计算 SHA-256 哈希——相同消息仅存储一次
2. **对话指纹：**对前 N 条消息的哈希计算哈希值——检测重复文件
3. **搜索时去重：**根据内容相似度对结果去重

噪声过滤：

• 空消息和纯空白内容
• 系统提示词（除非正在搜索它们）
• 重复的工具确认消息

---

性能特征

延迟和内存占用取决于存档大小、索引就绪状态、模型状态，以及进程是否处于冷启动状态。 历史上的小型语料库耗时并不代表大型存档的时限。 测量完整命令的耗时，为每次检索尝试设置上限，并区分成功结果与超时或维护拒绝。

---

响应格式

搜索响应：

{
  "query": "error",
  "limit": 10,
  "count": 5,
  "total_matches": 42,
  "hits": [
    {
      "source_path": "/path/to/session.jsonl",
      "line_number": 123,
      "agent": "claude_code",
      "workspace": "/projects/myapp",
      "title": "Authentication debugging",
      "snippet": "The error occurs when...",
      "score": 0.85,
      "match_type": "exact",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "_meta": {
    "elapsed_ms": 12,
    "cache_hit": true,
    "wildcard_fallback": false,
    "next_cursor": "eyJ...",
    "index_freshness": { "stale": false, "age_seconds": 120 }
  }
}

聚合响应：

{
  "aggregations": {
    "agent": {
      "buckets": [
        {"key": "claude_code", "count": 120},
        {"key": "codex", "count": 85}
      ],
      "other_count": 15
    }
  }
}

---

环境变量

变量	用途
CASS_DATA_DIR	覆盖数据目录
CHATGPT_ENCRYPTION_KEY	用于加密 ChatGPT 的 Base64 密钥
PI_CODING_AGENT_DIR	覆盖 Pi-Agent 会话路径
CASS_CACHE_SHARD_CAP	每个分片的缓存条目数（默认值为 256）
CASS_CACHE_TOTAL_CAP	缓存命中总数（默认值为 2048）
CASS_DEBUG_CACHE_METRICS	启用缓存调试日志
CODING_AGENT_SEARCH_NO_UPDATE_PROMPT	跳过更新检查

---

Shell 补全

cass completions bash > ~/.local/share/bash-completion/completions/cass
cass completions zsh > "${fpath[1]}/_cass"
cass completions fish > ~/.config/fish/completions/cass.fish
cass completions powershell >> $PROFILE

---

API 契约与版本控制

cass api-version --json
# → { "version": "0.4.0", "contract_version": "1", "breaking_changes": [] }

cass introspect --json
# → Full schema: all commands, arguments, response types

保证稳定：

• 退出代码及其含义
• --robot 输出的 JSON 响应结构
• 标志名称及其行为
• _meta 区块格式

---

与 CASS Memory (cm) 集成

CASS 提供情景记忆（原始会话）。CM 提取程序性记忆（规则和操作手册）：

# 1. CASS indexes raw sessions
cass index --full

# 2. Search for relevant past experience
cass search "authentication timeout" --robot --limit 10

# 3. CM reflects on sessions to extract rules
cm reflect

---

故障排除

问题	解决方案
“missing index” / maintenance-required	报告阻碍因素；将检索与经授权的索引构建/修复分开处理
过期警告	报告数据年龄/覆盖范围；另行决定是否刷新
无结果	检查 budget.timed_out；如果尝试已完成，再重新考虑查询范围
JSON 解析错误	使用 --robot-format compact
监视未触发	检查 watch_state.json，确认文件事件支持情况
重置 TUI 状态	使用 cass tui --reset-state 或按 Ctrl+Shift+Del

---

安装

# One-liner install
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh \
  | bash -s -- --easy-mode --verify

# Windows
irm https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.ps1 | iex

---

与 Flywheel 集成

工具	集成方式
CM	CASS 提供情景记忆，CM 提取程序性记忆
NTM	使用 Robot 模式标志搜索过往会话
Agent Mail	搜索 Agent 历史记录中的会话串
BV	将 beads 与过往解决方案交叉引用