本文面向：已经导入了对话数据，想体验语义搜索价值的开发者。 预计阅读时间：5 分钟
场景
周一你花了 2 小时调试一个 CORS 问题，和 Claude Code 聊了十几轮，最后用一个特殊的 header 配置解决了。周四你又遇到了同样的问题，但只记得「好像之前处理过」，具体怎么改的完全想不起来。
翻聊天记录？Claude Code 的 JSONL 文件有上百个，哪个文件、哪条消息、哪段回复？找不到。
用 ChatCrystal 的语义搜索，输入「CORS 跨域配置」，3 秒出结果。
前置条件
- 已导入对话数据（
crystal import） - 已配置 Embedding 模型（参考 LLM 和 Embedding 不能混用）
- 已生成笔记（
crystal summarize --all或等待自动摘要）
没有笔记的话，搜索只能匹配对话原文，效果会差很多。笔记是 LLM 提炼过的结构化知识，搜索质量更高。
搜索方式
方式一：CLI 搜索
crystal search "CORS 跨域配置"
输出示例：
Found 5 results:
1. [笔记] CORS 跨域问题排查与修复
项目: my-api-project 标签: #网络 #调试
摘要: 解决 Express + Nginx 反向代理下的 CORS 问题。关键是在 Nginx 配置
中添加 Access-Control-Allow-Origin 头，而不是在 Express 里处理...
相似度: 0.89
2. [笔记] Express 中间件配置踩坑记录
项目: my-api-project 标签: #Node.js #踩坑
摘要: 包括 CORS、body-parser 顺序、错误处理中间件等常见问题...
相似度: 0.76
3. [对话] 2026-05-12 CORS 报错排查
项目: my-api-project
摘要: 用户遇到 Access-Control-Allow-Origin 错误，逐步排查发现是 Nginx
proxy_pass 配置问题...
相似度: 0.72
每条结果包含：
- 来源类型（笔记 / 原始对话）
- 项目名和标签
- 摘要片段
- 相似度分数（0-1，越高越相关）
方式二：Web 界面
打开 http://localhost:3721，进入搜索页面，输入关键词。结果以卡片形式展示，点击可查看完整笔记。
方式三：MCP 集成
如果你在 Claude Code 里装了 ChatCrystal MCP Server，可以直接问：
> 我之前处理 CORS 问题的方案是什么？
Claude 会自动调用 search_knowledge 工具，从知识库里找到相关笔记并引用。
搜索原理
ChatCrystal 的搜索不是关键词匹配，是语义搜索：
你的查询 "CORS 跨域配置"
↓ Embedding 模型
向量 [0.12, -0.34, 0.56, ...]
↓ vectra 向量检索
匹配知识库里语义最接近的笔记
↓ 按相似度排序
返回结果
这意味着：
- 搜「跨域问题」能匹配到标题是「CORS 配置」的笔记（语义相同）
- 搜「登录验证失败」能匹配到「JWT token 过期处理」的笔记（相关主题）
- 搜「数据库连接超时」能匹配到「MySQL 连接池配置」的笔记（同一问题的不同表述）
关键词搜索做不到这些。
实际使用场景
场景 1：找回调试方案
crystal search "Redis 连接池耗尽"
→ 找到 3 天前的笔记，里面有完整的 redis.createClient 配置和 maxRetriesPerRequest 参数。
场景 2：查找代码片段
crystal search "React Table 排序实现"
→ 找到之前和 AI 讨论的排序逻辑代码，包含 useReactTable 的 sorting state 和 getSortedRowModel。
场景 3：回顾架构决策
crystal search "为什么选 Fastify 不选 Express"
→ 找到之前的架构讨论笔记，有性能对比数据和最终选型理由。
场景 4：查找配置方法
crystal search "Tailwind CSS 暗色模式配置"
→ 找到之前配好的 darkMode: 'class' 方案和自定义主题变量。
场景 5：跨项目经验复用
crystal search "Docker 多阶段构建优化"
→ 找到另一个项目里的 Dockerfile 优化经验，直接复制到当前项目。
搜索技巧
用自然语言，不要用关键词
❌ CORS header 配置
✅ 怎么解决 CORS 跨域请求被拦截的问题
❌ React 排序
✅ React Table 列排序怎么实现，点击表头切换升降序
语义搜索理解自然语言，描述越具体，结果越精准。
指定项目范围
crystal search "JWT 认证" --project my-api
只在指定项目的笔记里搜索，避免其他项目的噪音。
限定标签
crystal search "性能优化" --tag 调试
只在有特定标签的笔记里搜索。
结合 CLI 工具
# 搜索结果直接复制到剪贴板（macOS）
crystal search "Redis 配置" --limit 1 | pbcopy
# JSON 格式输出，方便脚本处理
crystal search "部署方案" --json
搜索质量优化
如果搜索结果不理想，可以从以下几个方面优化：
1. 重新生成笔记
笔记质量直接影响搜索质量。如果笔记摘要太笼统，搜索结果也会笼统。
# 重新生成某条对话的笔记
crystal summarize <conversation-id>
# 批量重新生成
crystal summarize --all
2. 检查 Embedding 模型
不同 Embedding 模型的语义理解能力不同。如果用的是 Ollama 本地模型，可以试试 OpenAI 的 text-embedding-3-small，质量更好。
3. 给笔记打标签
标签可以辅助筛选，让搜索更精准。在 Web 界面的笔记详情页可以编辑标签。
4. 合并重复笔记
如果同一个话题被多次讨论，可能生成了多条相似的笔记。可以用 crystal notes relations <id> 查看笔记关系，手动合并重复内容。
从「找东西」到「知识库」
一开始你可能只是用搜索来找之前的代码片段。但用久了会发现，真正的价值在于：
- 积累 — 每次和 AI 的对话都变成了可检索的知识
- 关联 — 不同项目、不同时间的经验通过语义搜索连接起来
- 复用 — 解决过的问题不需要再解决一遍
这就是 ChatCrystal 的核心理念：把 AI 对话从「一次性聊天」变成「持久化知识」。
