本文面向：使用过 Claude Code、Cursor 等 AI 编程工具的开发者，无需任何前置知识。
预计阅读时间：8 分钟
最终效果：3 分钟内跑通安装、导入、生成笔记全流程。

---

最终效果预览

完成本文后，你将拥有一个本地运行的知识库，包含：

• 自动从你的 AI 编程工具导入的对话记录
• LLM 生成的结构化笔记（标题、摘要、关键结论、代码片段）
• 可按语义搜索的知识索引

前置条件

条件	说明
Node.js >= 20	node -v 检查版本
任意 AI 编程工具	Claude Code / Cursor / Codex CLI / Trae / Copilot，至少有一个
LLM 服务	本文用 Ollama（免费），也可以用 OpenAI 等云端 API

没有 Node.js？去 nodejs.org 下载 LTS 版本安装即可。

第一步：安装 ChatCrystal

npm install -g chatcrystal

验证安装：

crystal --version
# 输出类似：chatcrystal 0.4.10

如果提示 command not found 或 'crystal' 不是内部或外部命令，说明 Node.js 安装时没有正确配置环境变量。最简单的修复方式：

1. 去 nodejs.org 重新下载 Node.js 安装包
2. 运行安装程序，确保勾选「Add to PATH」选项（默认应该已勾选）
3. 安装完成后重新打开终端
4. 再试 crystal --version

第二步：配置 LLM

ChatCrystal 需要一个 LLM 来生成摘要，还需要一个 Embedding 模型来做语义搜索。

ChatCrystal 的核心亮点是本地私密运行——你的对话数据不会离开本机。推荐用 Ollama 在本地跑模型。

推荐：Ollama 本地运行（免费、私密）

安装 Ollama（ollama.com），然后拉取两个模型：

ollama pull qwen2.5:7b       # 摘要模型（约 4.7GB）
ollama pull nomic-embed-text  # Embedding 模型（约 274MB）

ChatCrystal 默认就是 Ollama 配置，拉完模型直接用，不需要手动改设置。

Ollama 的详细安装和配置见 Ollama 本地部署：零成本跑通全流程。

备选：云端 API

如果你更看重摘要质量，可以用 OpenAI 等云端 API：

字段	值
LLM Provider	openai
LLM API Key	sk-...
LLM Model	gpt-4o
Embedding Provider	openai
Embedding Model	text-embedding-3-small

支持的 Provider：OpenAI、Anthropic、Google AI、Azure OpenAI，以及任何 OpenAI 兼容服务。

踩坑提醒： LLM 和 Embedding 必须分开配置。大语言模型（如 GPT-4、Claude）不能当 Embedding 模型用——它们不支持 /v1/embeddings 端点。

第三步：启动服务

crystal serve -d

-d 表示后台运行。首次启动会在 ~/.chatcrystal/data 创建数据目录，存放数据库和配置。

验证服务运行：

crystal status
# 输出类似：
# Server: running on http://localhost:3721
# Database: 0 conversations, 0 notes

如果端口被占用，可以指定其他端口：

crystal serve -d -p 3722

第四步：导入对话

crystal import

ChatCrystal 会自动扫描本地 AI 编程工具的数据目录：

工具	默认扫描路径
Claude Code	~/.claude/projects/
Cursor	VS Code workspaceStorage
Codex CLI	~/.codex/sessions/
Trae	VS Code workspaceStorage
Copilot	VS Code chatSessions

导入完成后会显示：

Scanning claude-code: found 47 conversations
Scanning cursor: found 23 conversations
Imported 70 conversations (skipped 0 duplicates)

第五步：生成笔记

打开浏览器访问 http://localhost:3721，进入设置页面配置 LLM（如果第三步已经配置过 Ollama，这一步可以跳过）。

然后在对话页面点击「批量生成」，ChatCrystal 会把每条对话交给 LLM 提炼为结构化笔记。

生成过程中可以：

• 实时查看进度条
• 随时取消
• 已生成的笔记可以立即查看

第六步：搜索你的知识

进入搜索页面，输入你想找的内容。语义搜索会按含义匹配，而不是靠关键词精确匹配。

举个例子：

搜索词：内存泄漏修复
匹配结果：一篇标题为「Node.js heap out of memory 的排查过程」的笔记

即使笔记里没有「内存泄漏」这个词，语义搜索也能找到它——因为 Embedding 向量捕捉了语义相似度。

可选：桌面应用

不想用浏览器？下载 Electron 桌面应用：

去 GitHub Releases 下载最新版 Windows 安装包，安装后启动即可。桌面应用内嵌了服务端，不需要手动 crystal serve。

常见问题

导入时报错 “EACCES: permission denied”

数据目录权限问题。检查 ~/.claude/ 目录的读权限：

ls -la ~/.claude/

Ollama 连接失败

确保 Ollama 正在运行：

ollama list
# 如果报错，先启动 Ollama
ollama serve

---

项目地址：github.com/ZengLiangYi/ChatCrystal

有问题欢迎在 Issue 区交流。