--- title: ChatCrystal 入门：从安装到第一条可搜索笔记 description: 按 ChatCrystal 0.6.1 的实际 CLI，依次验证安装、服务、两类模型、导入、摘要与搜索，区分 npm 包和桌面应用的使用入口。 image: "https://zengliangyi.com/og/blog/chatcrystal-getting-started.png" --- 把 AI 编程对话变成可以再次使用的笔记，需要先把几条链路分别跑通：工具能启动、历史能导入、模型能处理、笔记能检索。第一次使用时，先验证一条记录，比直接批量处理全部历史更容易定位问题。 本文以 [ChatCrystal](/projects/chatcrystal) 0.6.1、提交 [`7642768`](https://github.com/ZengLiangYi/ChatCrystal/tree/764276814e5c5a33ecbfeae63754f74b9261a3a8) 为基准，使用本机 CLI 工作流。模型下载和运行时间取决于网络与硬件，这里不承诺几分钟内完成。 ## 先选择使用入口 桌面应用和 npm 包不是同一个安装产物。想通过窗口浏览对话，可以从 [GitHub Releases](https://github.com/ZengLiangYi/ChatCrystal/releases) 选择适合平台的桌面发行包；本文下面的命令用于 npm CLI。 [npm 包的文件清单](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/package.json)包含编译后的服务端和共享模块，没有 `client/dist`。服务只有找到前端构建目录才会提供网页。因此，安装 npm 包后不能把“访问 3721 端口一定出现完整界面”当作验收条件；CLI 可以直接调用 API 完成下面的操作。 ## 安装并检查命令 该版本的包声明要求 Node.js 24 或更高。先检查运行环境，再安装本文对应版本： ```bash node --version npm install -g chatcrystal@0.6.1 crystal --version crystal --help ``` 如果找不到 `crystal`，先检查 `npm prefix -g` 对应的全局可执行文件目录是否在 `PATH`，以及当前终端是否使用刚才安装的 Node 环境。重新打开终端后再验证，避免在多个 Node 管理器之间反复重装。 ## 启动本机服务 ```bash crystal serve -d crystal status ``` 默认服务端口是 3721。[运行路径实现](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/runtime/paths.ts)默认把数据放在用户目录的 `.chatcrystal/data`，`DATA_DIR` 可以在启动前指定其他位置。记录实际目录，后续备份需要同时考虑数据库、配置与向量索引。 本文使用默认本机端口与隐式本机连接。端口冲突时，先确认占用端口的进程，协调使用默认端口。当前 CLI 会拒绝显式指定的、没有报告云模式的 loopback 连接，因此不能用改成 3722 再传 `--base-url` 的方式承诺跑通本机流程。已有远端连接配置也会改变命令的目标，应先查看状态中的连接信息。 ## 分别配置生成与检索模型 语言模型负责生成结构化笔记，Embedding 模型负责生成检索向量。下面使用当前默认配置中出现的两个 Ollama 模型，作为可复现的示例，选型仍需结合自己的硬件和内容评估。 安装并启动 [Ollama](https://docs.ollama.com/quickstart) 后： ```bash ollama pull qwen2.5:7b ollama pull nomic-embed-text crystal config get ``` 确认两类配置都指向本机模型服务。对于需要重设的配置： ```bash crystal config set llm.provider ollama crystal config set llm.baseURL http://localhost:11434 crystal config set llm.model qwen2.5:7b crystal config set embedding.provider ollama crystal config set embedding.baseURL http://localhost:11434 crystal config set embedding.model nomic-embed-text crystal config test ``` 已有索引时，部分 Embedding 变更会要求确认；先阅读警告和安排重建，不要直接追加 `--confirm`。连接测试分别报告 LLM 与 Embedding 的结果，应两项都看。它测试的是短请求，不能证明长对话的摘要质量或完整索引一定成功。 本地存储也不等于全部推理都在本地。远端端点会收到相应文本；详细边界见[本地优先与隐私](/blog/local-first-ai-data-boundaries)。两类模型的配置区别见 [LLM 与 Embedding](/blog/llm-and-embedding-separation)。 ## 导入并选择一条对话 ```bash crystal import crystal status crystal summarize ``` 空数据库首次启动时，[初始化代码](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/services/seed.ts)会尝试插入演示会话与笔记。`demo-` 开头的记录不是你的导入结果，状态总数大于零也不能证明真实历史已导入。 默认本机导入扫描已启用的数据源，将可解析的历史写入应用数据库，不会仅因为导入成功就生成笔记。无参数的 `summarize` 会列出待摘要对话，便于选择 ID。导入结果中的扫描、跳过和错误各有含义；对话数为零时，核对工具是否留下历史、数据源路径与服务进程的读取权限。 如果命令显示远端上传确认，先核对目标地址。云模式下，CLI 会扫描本机历史并上传解析后的对话，不能把这个过程解释成本机数据库导入。 ## 生成笔记并验证搜索 从真实导入结果中选一条包含具体问题、处理办法与验证或可复用经验的对话，用它的 ID 替换下面的示例位置，不要选择演示记录： ```text crystal summarize crystal notes list crystal --json search "曾经讨论的具体错误或解决方法" --limit 5 ``` 这里的搜索使用 `--json`，保证走传递 `--limit` 的非交互分支，返回值是结果数组。先检查摘要是否保留问题条件、解决办法和验证结果，再查看搜索返回的笔记。摘要流程还会先经过经验门槛：不满足条件的对话可以正常变为 `filtered`，返回空结果且不生成笔记，这与模型调用失败不同。选择下一条有实际经验的历史继续验证。会生成笔记，不代表向量已经可用；摘要、向量处理和查询端点都可能分别失败。搜索结果为空，也可能来自检索阈值或表达差异，不能只凭一次查询判断数据丢失。 成功标准是一条可定位的原始对话、一条内容可信的笔记，以及一次能读懂来源的检索结果。完成这条链路后，再考虑批量摘要和 Agent 接入。平时查看服务状态用 `crystal serve status`，停止本机后台服务用 `crystal serve stop`；停止服务不会代替数据备份。 分享： ## 相关文章 [## 从 ChatCrystal 导出到 Obsidian 的工作流 分页导出 ChatCrystal 笔记，用稳定 ID 建立 Obsidian 双向链接，并明确快照、人工编辑和增量同步之间的边界。 曾亮懿 2026年6月11日 阅读约 6 分钟 #ChatCrystal #Obsidian #Node.js #知识管理](/blog/chatcrystal-to-obsidian) [## AI 对话格式差异：事件、快照与跨库消息定位 对照五个固定适配器，区分 JSONL 容器、事件语义与 SQLite 键布局，用两个内存数据库观察消息索引、孤立数据和未知版本。 曾亮懿 2026年10月7日 阅读约 4 分钟 #ChatCrystal #Node.js #SQLite](/blog/ai-conversation-format-divergence) [## AI 对话管理方案：四种存储路径与迁移验收 比较 Claude Code、Cursor、Copilot、Trae 的固定适配器输入，区分原始副本、可读导出与知识库，并用合成清单验证身份和信息保留。 曾亮懿 2026年10月7日 阅读约 4 分钟 #ChatCrystal #Node.js #SQLite](/blog/ai-conversation-management-options) ## 从文章到代码 到我的 GitHub 看看 ChatCrystal、开发者工具和日常学习记录，欢迎交流实现细节。 [访问我的 GitHub](https://github.com/ZengLiangYi) ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "ZengLiangYi Blog", "alternateName": [ "Zeng Liangyi", "ZengLiangYi", "zengliangyi.com" ], "url": "https://zengliangyi.com", "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。" } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "ChatCrystal 入门：从安装到第一条可搜索笔记", "description": "按 ChatCrystal 0.6.1 的实际 CLI，依次验证安装、服务、两类模型、导入、摘要与搜索，区分 npm 包和桌面应用的使用入口。", "url": "https://zengliangyi.com/blog/chatcrystal-getting-started/", "image": "https://zengliangyi.com/images/blog/chatcrystal-getting-started.svg", "datePublished": "2026-10-03T00:00:00.000Z", "dateModified": "2026-10-03T00:00:00.000Z", "author": { "@type": "Person", "name": "曾亮懿", "url": "https://zengliangyi.com/about" }, "publisher": { "@type": "Organization", "name": "ZengLiangYi Blog", "logo": { "@type": "ImageObject", "url": "https://zengliangyi.com/favicon-96x96.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://zengliangyi.com/blog/chatcrystal-getting-started/" } } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "首页", "item": "https://zengliangyi.com/" }, { "@type": "ListItem", "position": 2, "name": "文章", "item": "https://zengliangyi.com/blog" }, { "@type": "ListItem", "position": 3, "name": "ChatCrystal 入门：从安装到第一条可搜索笔记", "item": "https://zengliangyi.com/blog/chatcrystal-getting-started/" } ] } ```