cass

cass 会话搜索

目录

• 黄金矿藏原则
• 准确提示词 —— 发现工作流
• 版本固定注意事项
• 两步引导（替代“始终先执行”）
• 索引卡住与恢复决策树
• 快速参考
• 何时使用什么
• 关键规则
• 排除 Agent Harness
• 搜索模式
• 跨机器搜索（多工作站语料库）
• 反模式（不要这样做）
• 在原生 Harness 中恢复过去的会话
• 启发式方法
• jq 基础知识
• 隐藏的强大功能：旧版技能遗漏的功能
• 令牌与成本分析（额外用例）
• 恢复速查表（无需权限的操作）
• 参考索引
• 快速搜索（查找参考资料的 Grep 配方）
• 脚本
• 验证

核心见解： 你反复使用的提示词就是最好的提示词。如果你输入过 10 次以上，那它就有效。挖掘你的历史记录。

黄金矿藏原则

你的对话历史包含：

• 经过优化的提示词 —— 每次效果更好的改写都已记录
• 有效的惯例 —— 重复使用 10 次以上的提示词就是你的方法论
• 范围决策 ——“我们什么时候决定不做 X？”
• 恢复时刻 —— 丢失上下文后你搜索的内容，就是重要的内容

这一见解： 挖掘过去的经验，胜过发明新方法。

---

准确提示词 —— 发现工作流

1. Bootstrap: Check health, refresh only if stale (capped, in the background), get project overview
   cass status --json
   # if .index.stale == true:  ( timeout 600 cass index --json >/tmp/cass-index.$$.log 2>&1 </dev/null & )
   cass search "*" --workspace /data/projects/PROJECT --aggregate agent,date --limit 1 --json

2. Find prompts: Search for keywords, filter to user prompts (lines 1-3)
   cass search "KEYWORD" --workspace /data/projects/PROJECT --json --fields minimal --limit 50 \
     | jq '[.hits[] | select(.line_number <= 3)]'

3. Follow hits: View the actual content
   cass view /path/from/source_path.jsonl -n LINE -C 20

4. Expand context: See the full conversation flow
   cass expand /path/from/source_path.jsonl --line LINE --context 3

5. Discover related: Find the whole work cluster
   cass context /path/from/source_path.jsonl --json

此工作流为何有效

• 先做聚合 —— 先了解全局，再深入探索
• --fields minimal —— 输出减少 5 倍，同时保留上下文窗口
• line_number <= 3 —— 用户提示词位于会话开头
• 上下文聚类 —— 工作以集群形式开展；一个有效结果就能找到许多相关会话

---

版本固定注意事项

cass 发展迅速。此技能描述的是 HEAD 行为（/dp/coding_agent_session_search 中的最新源码）。已发布的 v0.3.6 二进制文件缺少之后新增的多项功能：

• cass sources agents {list,exclude,include} —— 于 2026-04-20 添加（提交 82d8d70e）
• 完整重建时对尾端写入竞态的容忍 —— 于 2026-04-22 修复（提交 e06342f2，bead zz8ni）
• 联邦安装的词法生成清单（提交 2b7b86a1、683ccd03、cf76fe15）
• 重建生产者停滞遥测（提交 73a86604）

如果某个标志或子命令返回“无法识别”，或行为与文档所述不同，请运行 cass --version 并检查 git log -- src/lib.rs，查找相关提交。每个受影响的章节都会注明其依赖的提交或版本。

检查你安装的二进制文件实际支持哪些功能：

cass capabilities --json | jq '{version: .crate_version, features, connectors}'
cass introspect --json   | jq '.commands[].name'

---

两步引导（取代“始终优先”）

有三种状态需要区分，切勿混为一谈。

状态	含义	操作
cass health exit 0	耗时不到 50ms 的预检已通过	立即搜索
cass health exit 1 + index.stale=true	索引可用但已过时	立即搜索，并在后台刷新，同时设置墙钟时间上限：( timeout 600 cass index --json &>/tmp/cass-bg.log </dev/null & )（切勿单独使用 &——cass index 可能会卡住）
cass status 返回 database.exists=false 或 documents=0	确实已损坏／未初始化	运行 cass doctor --fix --json，然后运行 cass index --full --json

陷阱： 把过时的索引视为已损坏，会触发不必要的完整重建（耗时 8–25 秒）；而增量刷新（耗时 1–3 秒），甚至使用过时但正确的索引进行查询，本来就足以解决问题。

# Robust two-step bootstrap that never blocks the user.
# IMPORTANT: every cass index call gets a wall-clock cap. cass index has been
# observed to hang indefinitely under contention — without `timeout`, the
# bootstrap itself becomes the symptom.
cass status --json | jq '{healthy, fresh: .index.fresh, stale: .index.stale, db: .database.exists, sem: .semantic.available}'

# Refresh policy: stale → bg refresh (capped); never block search
if [ "$(cass status --json | jq -r '.index.stale')" = "true" ]; then
  ( timeout 600 cass index --json >"/tmp/cass-index.$$.log" 2>&1 </dev/null & ) 2>/dev/null
fi
# Search even with stale index — results are still useful
cass search "KEYWORD" --workspace /path --json --fields minimal --limit 10

如需此逻辑的生产级版本（每次调用均设置上限、损坏状态升级处理、钩子的退出代码语义），请使用 scripts/recover.sh——它通过超时和按 PID 记录日志，实现了完整的决策树。

cass health 在索引过时时返回 exit 1，这是为 cron/CI 设计的有意预检信号。在交互式 Agent 循环中，优先使用 cass status --json 并自行判断。

---

索引卡住与恢复决策树

我们在真实场景中遇到的错误（均在挖掘的会话中观察到）。从上到下检查——第一个匹配项优先。

症状	可能原因	自主修复（无需提示用户）
cass index --json 持续输出 phase: indexing, current: 0, total: N 超过 2 分钟	v0.3.6 中的 OPEN 问题 #196：此前运行 --force-rebuild 后，增量索引会卡住	终止本次运行，然后执行 cass index --full --force-rebuild --json（通常需 25 秒）
cass status 显示 index.rebuilding=true，且 pid 已过期（超过 1 小时）	索引器崩溃后遗留了锁	执行 cass doctor --fix --json（会自动移除过期的 .index.lock）
cass search 返回 0 条结果，但文件中明确包含该词	该词位于工具的 stdout/stderr 中（索引时已跳过）	改用 rg -n "TERM" /path/to/session.jsonl
cass search --workspace /X 返回 0 条结果；不带 --workspace 的相同查询能正常工作	工作区字符串不匹配	执行 cass search "KEYWORD" --aggregate workspace --limit 1 --json，查明规范路径后再重新运行
vtable constructor failed: fts_messages（较早的错误，已在 0.3.0+ 中修复）	升级后 DB↔FTS 架构不一致	执行 cass doctor --fix --json，从 SQLite 重建 Tantivy 侧
--limit 0 panic	较早版本的 cass 在 limit=0 时会触发 panic	聚合时始终传入 --limit 1（或 --limit 5）
cass 项目目录中出现大量 core.NNNNN 文件	先前索引器崩溃时生成了核心转储	可以安全保留；不会影响搜索。只有在用户明确许可后才能删除。
Windows 上的 cass models install 因 WSAENOTCONN 失败（已关闭的问题 #193）	下载 huggingface 时网络短暂中断	重试一次；如果仍然失败，使用 --mirror <URL> 指定其他 HF 镜像，或在本地已有模型缓存时使用 --from-file <DIR>。然后执行 cass models verify。
cass index 提示 "Index rebuild is already in progress"，但看不到任何任务	并发 Agent 触发了重建	不要强行处理——`cass status --json
cass index --full --force-rebuild --json 运行 200 秒以上，随后退出并显示 "index failed: updating last_indexed_at after index run ... database is busy"	persist_final_index_run_metadata 中的并发重建竞争。已在 HEAD（提交 e06342f2，bead zz8ni）修复；影响 v0.3.6 及更早版本。	验证索引数据是否正常：`cass search "X" --limit 1 --json
cass status 在看似成功的重建后仍一直显示 unhealthy	与上述情况相同——时间戳标记未写入	修复方法相同：确认搜索能返回结果，然后安静地运行一次 cass index --json 写入标记。升级到高于 v0.3.6 的版本以获得正确修复

绝不要为了应付问题而跳过 cass，改用手动 find/grep。 上述自主修复无需用户介入即可解决所有实际故障。要求用户“重建索引”是最糟糕的结果——他们的 Agent 正在等待。

---

快速参考

# Health first; refresh only when stale, always with a wall-clock cap (see Two-Step Bootstrap)
cass status --json
[ "$(cass status --json | jq -r '.index.stale')" = "true" ] && ( timeout 600 cass index --json >/tmp/cass-index.$$.log 2>&1 </dev/null & )

# Project overview: who did what, when?
cass search "*" --workspace /path --aggregate agent,date --limit 1 --json

# Find keyword, minimal output
cass search "KEYWORD" --workspace /path --json --fields minimal --limit 50

# Follow a hit
cass view /path.jsonl -n LINE -C 20        # Line-oriented
cass expand /path.jsonl --line LINE --context 3  # Message-oriented

# Find related sessions
cass context /path.jsonl --json

# Export for parsing
cass export /path.jsonl --format json --include-tools -o /tmp/out.json

# Inspect or change persistent agent-harness exclusions
cass sources agents list --json
cass sources agents exclude openclaw
cass sources agents exclude openclaw --keep-indexed-data
cass sources agents include openclaw

---

何时使用什么

需求	使用方式	原因
项目概览	--aggregate agent,date --limit 1	仅统计数量，不包含内容
查找提示词	--fields minimal + jq select(.line_number <= 3)	用户提示词位于第 1-3 行
识别惯例	统计匹配项：>10 = 惯例	重复出现 = 正在使用
完整对话	cass expand --context 3	保留消息边界
解析原始 JSON	cass export --include-tools -o file.json	切勿通过管道传递导出内容
未找到内容	rg "string" /path.jsonl	cass 会跳过工具输出
嘈杂的 harness 使索引充斥内容	cass sources agents exclude <agent>	持续禁用后续索引

---

关键规则

规则	原因	后果
--limit 1 minimum	--limit 0 会触发 panic	聚合时使用 1
--fields minimal	提高 Token 使用效率	输出缩小 5 倍
导出到文件	管道传输会导致 broken pipe panic	始终使用 -o /tmp/out.json
工作区路径必须完全匹配	匹配区分大小写	使用 --aggregate workspace 进行发现
--include-tools	默认隐藏工具调用	完整导出时必需

---

排除 Agent Harness

当用户告诉你某个 Agent harness 产生了垃圾内容、陷入循环或占用过多磁盘空间时，应直接在 cass 中处理，而不是告诉用户无法排除它。

# See current state
cass sources agents list --json

# Persistently stop indexing this harness in future scans/syncs/watch mode
cass sources agents exclude openclaw

# Keep already indexed data but block future indexing
cass sources agents exclude openclaw --keep-indexed-data

# Re-enable later
cass sources agents include openclaw

exclude 的实际作用

• 将偏好写入 sources.toml，使设置在后续运行中继续生效
• 即使源文件仍在磁盘上，也会阻止后续索引
• 默认会清除该 harness 已归档的本地数据并重建词法搜索，因此排除操作也能释放空间

适用场景

• 某个 harness 不断输出循环或低价值内容
• 用户希望 cass 记住“今后忽略此来源”
• 你需要一种可撤销且适合 Agent 使用的方法，在不手动删除源文件的情况下减少归档膨胀

---

搜索模式

模式	适用场景	示例
lexical（默认）	精确字符串、文件名	"AGENTS.md"、"--workspace"
semantic	概念性内容、措辞未知	"scope reduction discussions"
hybrid	广泛探索	"architecture decisions"

默认使用 lexical。 只有在不知道确切措辞时才使用 semantic。

启用 Semantic / Hybrid（仅需一次）

cass models status --json    # state: not_installed | installed | partial
cass models install          # downloads ~90MB MiniLM bundle from HuggingFace
cass index --semantic --build-hnsw --json   # builds vector + HNSW
cass search "QUERY" --mode hybrid --json    # then queries fall back to lexical if semantic missing

如果模型为 not_installed，--mode hybrid 和 --mode semantic 会静默回退到 lexical——不会触发 panic，也不会降低使用体验。请参阅 SEMANTIC_AND_HYBRID.md。

---

跨机器搜索（多工作站语料库）

当用户在 css、csd、ts1、ts2 等机器上运行 Agent 时，每台机器上的 cass 语料库彼此独立。有三种跨机器访问方式：

# Option A: One-shot remote query (no setup, slow per call)
ssh css 'cass search "KEYWORD" --json --fields minimal --limit 20' | jq '.hits'

# Option B: Configured sources (preferred — caches the remote sessions locally)
cass sources setup                                      # interactive wizard, auto-discovers from ~/.ssh/config
cass sources add ssh://user@css --name css --preset linux-defaults
cass sources sync --source css --json                   # rsyncs new sessions, then re-indexes
cass search "KEYWORD" --json                            # results now span all configured sources
cass sources list --json                                # see what's wired up

# Option C: Parallel fan-out (when speed matters more than dedup)
for h in css csd ts1 ts2; do
  ssh "$h" 'cass search "KEYWORD" --json --fields minimal --limit 10' > "/tmp/cass-$h.json" &
done
wait
jq -s '[.[] | .hits[]] | unique_by(.source_path + (.line_number|tostring))' /tmp/cass-*.json

cass sources doctor 可诊断连接情况。来自已配置来源的结果会在其命中元数据中包含 origin_host——向用户汇报时请保留此信息。完整参考：REMOTE_SOURCES.md。

---

反模式（不要这样做）

反模式	为什么不对	应该怎么做
问用户“要不要重建索引？”	有 Agent 正在等待；重建是安全且幂等的	直接运行 cass doctor --fix --json（保留源数据）
每当 status 显示不健康时就运行 cass index --full	为一个陈旧 30 分钟的索引花 25 秒重建，纯属浪费	将 index.stale 与 database.exists 分开检查；优先增量处理
运行裸命令 cass 来“看看有什么”	会在 Agent 的会话中启动阻塞式 TUI	始终使用 --json 或 --robot；绝不要裸运行
将 cass export 的输出传给 head/jq	大型会话会触发管道断开崩溃	先运行 cass export ... -o /tmp/x.json，再处理文件
把子 Agent 文件当作与父会话相同的内容	子 Agent 是独立的对话日志，第 2 行有自己的提示词	使用 select(.source_path | contains("subagent")) 过滤
用 --limit 0 表示“不限数量”	较早版本的 cass 会崩溃；现代 cass 会限制到 RAM 上限，但通常仍不是你想要的	使用实际限制（--limit 50）或通过 --cursor 分页
使用 --workspace /X 搜索并相信 0 条命中	工作区字符串区分大小写，也受结尾斜杠影响	如果 0 条命中但你预期会有结果，使用 --aggregate workspace --limit 1 重新运行，以找出标准键
扫描大量结果时跳过 --fields minimal	默认的 full 每条命中会返回约 3KB；100 条命中会消耗 300KB 上下文	扫描大量结果时始终传入 --fields minimal；只对少数保留项升级到 summary/full
用 cat 读取会话文件来提取提示词	会将完整对话加载到上下文中	使用 cass view PATH -n LINE -C 5（窗口）或 cass expand PATH --line LINE --context 3（识别消息边界）
每次 cass search 都重新索引	浪费资源；索引由多个进程共享	索引是共享的。只有在 cass status 显示 stale 或 recommended_action 提示时才刷新

---

在原生运行环境中恢复过去的会话

cass resume 会将会话路径解析为其原生 CLI 用于继续对话的确切命令——Claude Code、Codex、Gemini、OpenCode、pi_agent。

# Find a relevant past session
cass search "KEYWORD" --json --fields minimal --limit 5 \
  | jq -r '.hits[0].source_path' > /tmp/sess.path

# Print the resume command without executing
cass resume "$(cat /tmp/sess.path)" --shell

# Or replace the current process with the resumed agent
cass resume "$(cat /tmp/sess.path)" --exec

注意事项： 子 Agent 文件（subagents/agent-*.jsonl）按设计无法恢复——它们由父级编排。你会收到 session_id_not_found，并看到提示要求传入 --agent claude。请先通过 cass context <path> --json 解析出父会话。参见 RESUME.md。

---

启发式规则

信号	含义	操作
line_number 1-3	用户提示词	过滤：select(.line_number <= 3)
/subagents/ 第 2 行	THE 提取提示词	可直接复制粘贴
total_matches > 10	固定模式	记录下来并重复使用
0 条结果 + 存在内容	工作区路径不匹配	使用 --aggregate workspace

---

jq 要点

# User prompts only
| jq '[.hits[] | select(.line_number <= 3)]'

# Source paths for follow-up
| jq '.hits[].source_path' -r

# Aggregation buckets
| jq '.aggregations.agent.buckets'

# Count matches
| jq '.total_matches'

# Find repeated prompts (ritual detection)
| jq '[.hits[] | select(.line_number <= 3) | .title[0:80]] | group_by(.) | map({prompt: .[0], count: length}) | sort_by(-.count) | .[0:20]'

---

隐藏的强大功能：旧版 Skill 遗漏的能力

命令	功能	使用时机
cass health	<50ms，仅返回退出码的预检	Cron / 钩子门控
cass index --watch --json	文件系统监视器可让索引保持最新；单次循环 = --watch-once /path	长期运行的编排器主机
cass index --idempotency-key K --json	将相同键的响应缓存 24h	重试 CI 运行
cass index --semantic --build-hnsw	O(log n) 近似向量搜索	执行 cass models install 后
cass doctor --fix --json	从 DB 自动重建索引；将损坏的 DB 备份为 .corrupt.<ts>	任何 status.healthy=false 时
cass resume PATH --shell	跨框架恢复命令生成器	继续之前的 Codex/Claude/Gemini 会话
cass sources setup	交互式、识别 ssh-config 的多机器向导	首次连接多台机器
cass sources sync --source NAME --json	rsync 远程会话，然后重新建立索引	定期刷新多台机器
cass sources doctor --json	连通性 + 路径探测	依赖跨机器结果前
cass sources mappings ...	将来源路径改写为本地对应路径	移动工作区后
cass sources agents {list,exclude,include}	持久化框架排除设置（在 ~/.config/cass/sources.toml 中写入 disabled_agents）	openclaw / 嘈杂的连接器导致索引内容过多时
cass models install / status / verify / remove	管理 MiniLM 包（约 90MB）	启用语义搜索
cass analytics tokens | tools | models	根据已索引会话统计每天 / 每个工具 / 每个模型的使用情况	成本报告、回归检查
cass analytics rebuild --json	当 coverage_pct 偏低时回填汇总表	批量执行 import 或 sources sync 后
cass analytics validate --json	检测原始行与汇总表之间的偏差	报告数据前的合理性检查
cass import chatgpt PATH	将 ChatGPT 网页版导出的 conversations.json 导入语料库	从 ChatGPT.com 迁移
cass export-html PATH --password ...	加密、自包含的 HTML 对话查看器	与队友分享单个会话
cass pages encrypt ARCHIVE --with-recovery	用于静态托管的加密可搜索归档	发布经过脱敏的语料库
cass introspect --json	所有命令及响应的完整架构转储	以编程方式发现功能
cass capabilities --json	用于自我配置的功能 / 连接器 / 限制信息	根据版本选择回退方案
cass robot-docs guide | commands | examples | schemas | contracts	内置的面向机器的文档	在 Agent 循环中，Skill 不足以满足需求时
cass --robot-format jsonl | compact | toon | sessions	流式 / 令牌优化 / 可通过 shell 管道传递的输出	大型结果集、链式搜索
cass --trace-file FILE	用于调试慢速运行的 Span 计时 JSONL	排查性能问题

如果此处列出的标志报错“unrecognized”，说明安装的 cass 二进制文件比源代码旧。请对照上游的 git log -- src/lib.rs 检查 cass --version——大多数缺失的命令都是在 v0.3.x 中添加的。

---

令牌与成本分析（额外用例）

# Daily token usage across your whole agent fleet
cass analytics tokens --days 30 --group-by day --json | jq '.data.buckets[].api_tokens'

# Per-agent tool-use intensity (rows are keyed by agent slug, not tool name)
cass analytics tools --days 30 --json | jq '.data.rows[0:10]'

# Top models by API tokens
cass analytics models --json | jq '.data.by_api_tokens.rows[0:10]'

# After import / sync, refresh rollups
cass analytics rebuild --json
cass analytics validate --json   # confirm no drift between raw and rollup

cass analytics status --json 会显示 coverage_pct：低于约 90% 时，表示应运行 analytics rebuild 进行回填。参见 ANALYTICS.md。

---

恢复速查表（无需权限的操作）

你已获得预先授权，可以执行以下任一操作，以确保语料库可搜索。这些操作都不会破坏源会话数据；它们只会重建派生的索引数据。

cass doctor --json --verbose         # Diagnose without changing anything
cass doctor --fix --json             # Apply safe rebuilds; backs up bad DB to .corrupt.<ts>
cass doctor --fix --force-rebuild --json   # Same, but rebuild even when healthy
cass index --full --force-rebuild --json   # Workaround for OPEN issue #196 (incremental hang)
cass sources doctor --json           # Probe remote sources
cass sources sync --source NAME --json     # Re-fetch and re-index a single source
cass models install                  # Restore missing semantic model
cass models verify                   # Validate model file checksums

未经明确许可，你不得执行以下操作：删除 core.NNNNN 文件、删除 .beads/、运行 git reset --hard、手动编辑用户 .config/cass/sources.toml 中的任何内容。上述 CLI 命令已能安全地完成所有操作。

加密 Pages 归档的完整灾难恢复说明：RECOVERY.md。

---

参考索引

需求	参考资料
完整命令参考	COMMANDS.md
工作流示例	RECIPES.md
jq 模式	PATTERNS.md
陷阱与修复方法	PITFALLS.md
会话文件格式	SESSION_FORMATS.md
远程来源、多机器	REMOTE_SOURCES.md
语义／混合／模型	SEMANTIC_AND_HYBRID.md
Token／工具／模型分析	ANALYTICS.md
跨框架会话恢复	RESUME.md
Doctor + 自主恢复	RECOVERY.md
挖掘出的黄金标准提示词	PROMPTS.md
反模式（长篇）	ANTI_PATTERNS.md
健康状况与状态、索引的区别	OBSERVABILITY.md
Pages 加密归档 + HTML 导出	PAGES_AND_EXPORT.md
框架排除项（disabled_agents）	HARNESS_EXCLUSION.md
架构内省约定	INTROSPECTION.md

---

快速搜索（参考资料的 Grep 示例）

如果无法从标题判断该查阅哪份参考资料，可直接对 references 目录执行 grep——比将整个文件加载到上下文中更省资源。

REFS=.claude/skills/cass/references

# Find any anti-pattern by symptom keyword
grep -ni "limit 0\|broken pipe\|workspace path\|stale" "$REFS"/ANTI_PATTERNS.md "$REFS"/PITFALLS.md

# Find the recipe / jq for a task
grep -niE "ritual|user prompt|aggregate|subagent|cluster|timeline" "$REFS"/RECIPES.md "$REFS"/PATTERNS.md

# Find a recovery recipe (issue numbers, error strings, fix names)
grep -niE "doctor|--force-rebuild|issue #196|last_indexed_at|database is busy|core\." "$REFS"/RECOVERY.md "$REFS"/OBSERVABILITY.md

# Find a flag, command, or response field
grep -niE "robot-format|--mode|--cursor|_meta|fallback_mode|hits_clamped" "$REFS"/COMMANDS.md "$REFS"/INTROSPECTION.md

# Find a real "what did I ask" prompt template you've used before
grep -ni "use cass\|find that\|session history\|what worked" "$REFS"/PROMPTS.md

# Find harness/connector slugs and exclusion behavior
grep -niE "openclaw|disabled_agents|sources agents" "$REFS"/HARNESS_EXCLUSION.md "$REFS"/REMOTE_SOURCES.md

# Find resume / cross-harness behavior
grep -niE "resume|--shell|--exec|subagent.*not resumable" "$REFS"/RESUME.md

这些命令会在 <50ms 内搜索整个 references 目录，并显示一行匹配内容及其文件名，随后可用 Read 工具打开该文件——比读取整份参考资料省资源得多。

---

脚本

脚本位于 scripts/ 下。它们不会占用任何上下文 Token——只负责执行，不会加载。没有脚本会在未明确确认的情况下修改状态。

脚本	用法
./scripts/quick_analysis.sh /path	一条命令查看项目概况（状态 → 按 Agent／日期汇总 → 热门提示词）
./scripts/prompt_miner.py --workspace /path	查找重复提示词（检测惯例行为）
./scripts/validate.sh	验证 cass 安装和 skill 结构
./scripts/recover.sh	自主恢复决策树（READY → STALE_BUT_USABLE → BROKEN）；默认安全。可用作 cass search 前的 PreToolUse hook。每次调用 cass index 都会套用 timeout，以规避 issue #196 中的挂起问题
./scripts/multi_machine_search.sh "QUERY" [host…]	在整个集群中并行搜索（默认使用 css/csd/ts1/ts2）；合并结果，按 source_path:line 去重，并按分数排序。每台主机均设有 timeout 上限；可安全处理 shell 特殊字符形式的查询

---

验证

# Quick health check
cass status --json | jq '.index.fresh'

# Should return: true

如果结果为 false，请对照 .database.exists 检查 .index.stale（参见 Two-Step Bootstrap）：过期索引仍可搜索——现在即可搜索，并通过限时命令刷新：timeout 600 cass index --json（绝不要不设上限运行）；只有 database.exists=false 或 documents=0 时才需要运行 cass doctor --fix --json。