ChatCrystal：本地优先的 AI

25次阅读

获取下载链

微信关注「软件教程管家」公众号，回复 chatcrystal

官方渠道：GitHub 仓库

30秒速读：AI 编程对话散落在各个工具里，下次遇到同类问题还得重新问一遍。本篇讲清三个版本怎么选、Windows 桌面版的安装卡点、装完必改的设置，以及这款本地知识库到底适合谁。

软件信息表

软件名称	ChatCrystal
版本	滚动更新（GitHub Releases 持续发布桌面安装包，据项目说明）
平台	Windows（桌面应用）；CLI 版跨平台
运行环境	桌面版开箱即用；CLI 版需 Node.js ≥24
许可证	Apache-2.0 开源
语言	TypeScript 开发；官方文档含简体中文
数据存储	本地优先，笔记存本地，支持 Markdown 导出

版本	适合人群	优点	代价
桌面应用（推荐）	只想用、不折腾的开发者	图形界面，导入、搜索、图谱开箱即用	目前仅 Windows
CLI / Web（npm）	习惯终端、想脚本化的人	crystal import、search 可编排，Web 界面浏览器即开	需 Node.js ≥24，配置项稍多
Docker 自托管	多设备同步、个人或小团队	一处部署，多端访问	容器与数据卷要自己维护

明确取舍：先用桌面版。ChatCrystal 的核心价值是”把 AI 对话变成可复用的笔记”，桌面版把导入→提炼→搜索→图谱整条链路做成了点击流。只有当你需要把知识库接入脚本、或在多台设备间共享时，再考虑 CLI 或 Docker——为用而用反而增加维护负担。

打开 GitHub Releases 页面（文末按钮直达），下载最新版 Windows 安装包并安装。
首次启动后进 Settings，先配置 LLM 提供方和 Embedding（嵌入）提供方——不配这一步，语义搜索和笔记提炼都跑不起来，这是最多人卡住的地方。
点 Import，勾选你正在用的编程工具（Claude Code / Cursor / Codex CLI / Trae / GitHub Copilot），ChatCrystal 会扫描它们的本地数据目录并导入历史对话。
CLI 用户：npm install -g chatcrystal，然后 crystal serve -d 后台起服务，浏览器打开 http://localhost:3721。

设置 → LLM 提供方：选你已有账号或本地部署的模型。入口：Settings → Providers。体感差别：这是提炼笔记质量的上限，模型越强，自动生成的摘要、结论和标签越能直接用。
设置 → Embedding 模型：语义搜索全靠它。体感差别：配好之后搜”上次那个鉴权 bug 怎么修的”能按意思命中，而不是只按关键词碰运气。
导入源勾选：只勾你真正在用的工具。入口：Import → 数据源。不勾=库里混进无关对话，搜索噪音立刻大起来。
MCP 服务开关：打开后，你的 AI 编程智能体可以直接读取知识库里的经验、并把新的写回去。入口：Settings → MCP。这是 ChatCrystal 区别于普通笔记软件的关键，不开等于只用了它一半功力。
Markdown 导出目录：指定一个固定导出位置，定期导出一份。本地优先不等于不备份，导出文件也是防哪天想迁移的后路。

把官方文档里散在各处的工作流串成一条线：

对话导入（扫描各工具本地数据目录）→ 结构化提炼（标题 / 摘要 / 结论 / 代码片段 / 标签）→ 嵌入索引 → 语义搜索与标签知识图谱 → MCP 写回给智能体复用 → Markdown 导出备份。

两个实测细节值得注意：第一，提炼是增量的，新对话导入后可用 crystal summarize --all 批量补提炼，不用每次手动点；第二，crystal search "关键词" --limit 10 可在终端直接查库，写脚本做每日复盘很方便。

桌面应用目前只有 Windows 版，macOS / Linux 用户走 CLI/Web 或 Docker，别在 Releases 页找不存在的安装包。
CLI 版要求 Node.js ≥24，版本低了 npm 安装会直接报错，先 node -v 确认。
导入依赖各编程工具的本地数据目录——如果你重装过系统或清理过缓存，历史对话可能已经不在了，先确认目录里有数据再导入，否则会导进来一个空库。
Docker 自托管适合多设备，但数据卷备份要自己做：容器删了、卷没了，知识库就没了，务必把数据目录映射到宿主机固定位置。
项目迭代较快，遇到问题先看 Releases 的更新说明和官方 USER_GUIDE，多数疑问文档里都有答案。

适合：每天用 Claude Code、Cursor 等 AI 编程工具，想把”解决过的问题”沉淀成可搜索知识库的开发者；想让智能体记住项目经验、通过 MCP 复用的进阶用户。

不适合：不用 AI 编程工具的人（没有对话可导入，装了也是空库）；需要团队权限管理、审计合规的企业场景（先审查源码与文档再评估）。

结论先行：推荐先用桌面版。桌面版把导入、提炼、搜索、图谱做成了点击流，最省事；只有需要脚本化或多设备共享时，再考虑 CLI 或 Docker。

版本说明：桌面安装包随 GitHub Releases 滚动更新，具体版本号以官网为准。

入口：导出目录设置 + 你常用的备份或同步文件夹。做法：把 Markdown 导出目录设在日常备份盘里，定期导出一份。体感差别：换机或重装后不用翻旧硬盘找库，备份盘里直接有一份可用的。

入口：Settings → MCP。做法：先在一个非关键项目上开写回，确认智能体读到的经验是你想要的，再放开到主力项目。体感差别：写回范围可控，出问题只影响小范围，不会一下子污染主力知识库。

语义搜索搜不到刚导入的对话怎么办？先确认 Embedding 提供方已配置，并且提炼已完成；原文提到不配这一步语义搜索和提炼都跑不起来，提炼是增量的，可用 crystal summarize –all 批量补提炼。
换电脑怎么迁移？先用 Markdown 导出一份，再备份本地数据目录；两样都有，到了新机器才能接得上。
CLI 与桌面版的数据是不是同一份？以官网为准；迁移前先导出备份，不要假设两端自动同步。