本地离线知识库的folder-sync 第一次把文件夹挂成知识库
把一个文件夹挂成 chayuan-desktop 的知识库，是察元AI 桌面单机版上手之后第二件要做的事。第一件是配模型，这一件是有了内容才能问。folder-sync 是 chayuan-desktop 内置的文件夹同步机制，能让一个本地目录持续地被解析、入库、增量更新。这一篇讲怎么用它。
先讲清楚 folder-sync 在察元智库 里的位置。它是文档 RAG 的入口之一，对应的源类型是 doc:*。你给它一个目录，它会扫描目录下所有受支持的文件，逐个解析、切分、嵌入、入库。后面文件如果有变化，会增量同步，不需要每次手动重新建库。
支持的文件类型默认覆盖 PDF、Word、Excel、PPT、Markdown、HTML、txt，也支持图像（走 OCR）。文件大小没有硬上限，但单个文件超过几百兆建议另外处理。文件夹深度没有限制，但子目录嵌套太深会影响扫描速度。
操作步骤。在 chayuan-desktop 主界面左侧选 知识库 标签，点新建知识库，类型选 folder-sync 文件夹同步。给知识库起一个名字，比如 个人技术资料 或 部门规章。选择本地路径，比如 D:\Documents\TechArchive。可选的扫描间隔默认是每 10 分钟一次，可以改成手动同步或更频繁。
扫描规则有几条值得知道。第一，默认会忽略以点开头的隐藏文件和目录；第二，会忽略 .git、.svn、node_modules 之类的工程目录；第三，文件大小超过设定上限的会跳过；第四，临时文件比如 ~$ 开头的 Word 临时文件会忽略。这套规则在大多数办公场景都能直接用。
第一次扫描的耗时取决于文件数量和总大小。我自己挂过一个 200 多份 PDF 的目录，总大小 1.5G，第一次扫描加索引大约 8 分钟，期间 CPU 占用偏高。后续增量同步只处理新增和修改的文件，速度快很多。
入库过程出错怎么办。chayuan-desktop 的日志在 CHAYUAN_ROOT/logs/server.log 里有详细的解析过程。常见错误包括：损坏的 PDF 解析失败、加密的 Word 文档跳过、Excel 太大内存不够。每个错误都会在 KB 详情页有对应的诊断信息，提示哪个文件没入成功。这个机制让你不用去翻日志也能知道哪份文档有问题。
入库完成之后，回到对话窗口，新建对话，在知识库选择器里勾上这个新建的 folder-sync 库。问一句相关的问题，比如 这个目录里关于压力测试的内容总结一下。回答下面会出现引用气泡，每个气泡都能展开成原文段落。这就是 本地离线知识库 加 folder-sync 的最常见用法。
国产化支持下的几个细节。Linux 上挂 NTFS 外接硬盘的目录到 folder-sync 一般没问题，但建议先 mount 好再添加，避免目录变路径。麒麟 UOS 上长期运行扫描器要确认系统不会休眠掉电。Windows 上 OneDrive 同步的目录可以直接挂，但要注意 OneDrive 把文件标记为 在线 时实际本地没下载，folder-sync 解析这种文件会触发下载，影响速度。
跟 chayuan-wps WPS AI 插件 的协同。folder-sync 建好的知识库，在 WPS 文字里可以直接被引用。打开加载项，知识库选择器会列出当前已有的所有 KB，包括 folder-sync 类型。在 WPS 里写报告时，引用一份本机已索引的资料，体验和在桌面客户端里一样。
folder-sync 的几个反模式。一是不要把整个 C 盘或者用户根目录挂上来，文件数量太大解析会跑很久；二是不要把 OneDrive 整个云盘挂上，那些在线文件会全部触发下载，磁盘和带宽吃不消；三是建议按主题或部门拆成多个小 KB，不要把所有资料堆一个库里，回答时检索精度会下降。
把第一个文件夹挂好之后，察元智库 就有内容可问了。免费开源的AI软件 加 本地离线知识库 这两件事在你这台电脑上同时成立。