1. 为什么我要折腾这套三联组合先说结论我用了大半年时间把 Obsidian、WorkBuddy 和 Gitee 这三样东西串成了一条流水线现在我的个人知识库已经能做到记进去就不用管需要的时候 AI 帮我翻出来。这套方案解决的核心问题就一个——笔记越攒越多但真正要用的时候找不到、用不上。我相信很多人跟我一样Obsidian 里躺着几百上千篇笔记标签打了一堆文件夹分了好几层可真到写方案、查资料的时候还是靠搜索框硬搜关键词搜出来的东西零零散散还得自己重新拼。这就是典型的知识库变成了知识坟场。而 AI 驱动的知识库本质上是给你的笔记加了一层语义理解你问它问题它去你的笔记里找答案而不是让你自己去翻。这套组合里三个角色分工很明确。Obsidian 是仓库负责本地存储、双链关联、Markdown 纯文本管理数据完全在你自己手里WorkBuddy 是大脑负责把笔记切片、向量化、建立语义索引让你能用自然语言提问Gitee 是保险柜加传送带负责版本管理和多设备同步顺便还能当备份。三者各司其职谁也不越界。适合谁来参考我觉得三类人最合适。第一类是已经有 Obsidian 使用习惯、笔记量在 200 篇以上的朋友你已经过了记什么的阶段现在卡在怎么用第二类是对 AI 感兴趣但不想把笔记传到别人服务器上的隐私敏感型用户这套方案全程本地或私有仓库第三类是喜欢折腾、愿意花一个周末把基础设施搭好的技术爱好者。如果你笔记还没超过 50 篇我建议先老老实实记别急着上 AI数据量不够的时候语义检索的优势体现不出来。下面我按整体设计思路 → 核心组件拆解 → 实操搭建 → 踩坑排查这个顺序讲每一步都会说清楚为什么这么做而不是只给命令。你照着做一个下午能跑通。2. 整体架构设计与选型逻辑2.1 三个组件各自解决什么问题很多人一上来就问用什么工具但我觉得更重要的是先想清楚每个环节要解决什么。我把知识库的完整链路拆成四段采集 → 存储 → 理解 → 调用。Obsidian 管存储和初步关联WorkBuddy 管理解和调用Gitee 管跨设备的存储同步和版本兜底。为什么不用 Notion 或者飞书这类云端一体方案因为它们把存储和理解绑死了你没法单独替换其中一环。而我这套是解耦的——哪天 WorkBuddy 不好用了我换一个向量化工具Obsidian 里的笔记一个字都不用动。这种可替换性是我选型时最看重的东西。再说不选纯云端 RAG 服务的原因。你的笔记里可能有工作草稿、个人思考、读书笔记这些东西传给第三方做向量化心理上总归不踏实。本地跑 WorkBuddy数据不出机器这是底线。2.2 为什么是 Gitee 而不是别的同步方式Obsidian 自带的同步要付费第三方网盘同步又容易产生冲突文件我见过最惨的一次一个笔记被同步出 7 个冲突副本。用 Git 做同步的好处是版本可追溯、冲突可合并、历史可回滚。你改错了一篇笔记git log一看就知道哪天改的git checkout一键还原。选 Gitee 而不是其他代码托管平台主要是两个考虑。一是国内访问速度稳定git push和git pull不用等半天二是私有仓库免费个人知识库这种敏感内容放私有仓库是必须的。至于开源许可证个人私有仓库根本用不上别被那些选什么许可证的教程带偏了那是给公开项目准备的。提示Gitee 单文件有大小限制普通 Markdown 笔记完全没问题但如果你往库里塞大附件比如几十兆的 PDF、视频需要单独处理后面实操部分我会讲。2.3 数据流向全景我把整条链路画成文字版方便你理解数据怎么流动你在 Obsidian 里写笔记存成.md文件放在本地 vault 目录WorkBuddy 监听这个目录把新增或修改的笔记切片、生成向量存进本地向量库你通过 WorkBuddy 的对话界面提问它检索向量库把相关笔记片段喂给大模型生成回答你写完一批笔记用 Git 命令提交到 Gitee 私有仓库换一台电脑git clone或git pull拉下来Obsidian 打开同一个 vaultWorkBuddy 重新索引一遍继续用。这个流程里Obsidian 的 vault 目录是唯一的数据源其他所有东西都是围绕它服务的。记住这一点后面出问题排查就有方向了。3. 核心组件深度拆解与配置要点3.1 Obsidian 的目录结构设计Obsidian 用得好不好八成看目录结构。我踩过的最大坑就是早期把所有笔记平铺在一个文件夹里等到 300 篇的时候侧边栏滚都滚不完。后来我改成了一套按用途分层的结构你可以直接抄vault/ ├── 00-Inbox/ # 临时收集每周清空 ├── 10-Notes/ # 永久笔记原子化一篇一个概念 ├── 20-Projects/ # 项目相关有明确起止时间 ├── 30-Areas/ # 长期关注的领域 ├── 40-Archive/ # 归档不再活跃 ├── 90-Attachments/ # 图片、附件统一放这里 └── 99-Templates/ # 模板文件这套结构借鉴了 PARA 方法但做了简化。核心逻辑是Inbox 负责快Notes 负责准Projects 和 Areas 负责用。你随手记的东西先扔 Inbox每周花半小时整理该拆成原子笔记的拆到 Notes该归项目的归 Projects。为什么附件要单独放90-Attachments因为 WorkBuddy 做向量化的时候主要是处理文本图片和 PDF 需要额外配置。把附件隔离出来可以让索引过程更干净也方便你后面单独处理图片类知识比如截图、扫描件。注意Obsidian 的附件默认会放在笔记同级目录一定要在设置里改成指定附件文件夹指向90-Attachments否则你的目录会越来越乱。3.2 WorkBuddy 的索引机制与参数选择WorkBuddy 这类工具的核心是文本切片 向量化 相似度检索。我重点讲切片策略因为这是最影响效果、又最容易被忽略的环节。切片chunking就是把一篇长笔记切成一段段小文本每段单独生成向量。切得太粗检索出来的片段包含太多无关信息大模型容易被干扰切得太细一段话被拆散语义不完整。我的经验值是中文笔记每片 300 到 500 字重叠 50 字。重叠是为了防止一句话正好被切在边界上导致语义断裂。WorkBuddy 的配置里通常有这几个参数需要调参数推荐值说明chunk_size400每片字符数中文按字符算chunk_overlap50相邻片段重叠字符数top_k5检索时返回最相关的片段数相似度阈值0.7低于这个值的结果丢弃top_k设 5 是我实测下来比较平衡的值。设 3 有时候漏掉关键信息设 10 又会把不相关的内容塞进上下文反而让模型答偏。相似度阈值 0.7 是个经验值低于这个分数的片段基本是沾边但不相关宁可少给也别给错。3.3 Gitee 仓库的初始化与密钥配置Git 同步的第一步是配置 SSH 密钥这样每次 push 不用输密码。流程是本地生成密钥对 → 把公钥贴到 Gitee → 测试连接。# 生成密钥邮箱换成你的 ssh-keygen -t ed25519 -C your_emailexample.com # 一路回车默认存在 ~/.ssh/id_ed25519 # 查看公钥内容复制它 cat ~/.ssh/id_ed25519.pub复制出来的那串以ssh-ed25519开头的内容贴到 Gitee 的设置 → SSH 公钥里。然后测试ssh -T gitgitee.com看到欢迎信息就说明通了。这一步很多人卡住八成是公钥复制的时候带了换行或者少了字符仔细核对。仓库建好后在本地 vault 目录初始化cd /path/to/your/vault git init git remote add origin gitgitee.com:yourname/your-repo.git3.4 大文件与附件的处理策略Gitee 对单文件和仓库总大小有限制附件多了会 push 失败。我的处理方式是用.gitignore排除大附件附件单独用网盘或对象存储同步。在 vault 根目录建一个.gitignore# 排除大附件 90-Attachments/*.pdf 90-Attachments/*.mp4 90-Attachments/*.zip # 排除 Obsidian 的工作区缓存 .obsidian/workspace.json .obsidian/workspace-mobile.json # 排除系统文件 .DS_Store Thumbs.db.obsidian/workspace.json记录的是你当前打开了哪些面板、光标在哪这个文件每台机器都不一样同步过去只会造成冲突必须排除。但.obsidian下的插件配置、主题设置是要同步的所以不能整个文件夹排除只排除 workspace 相关文件。4. 完整实操流程与关键环节4.1 环境准备与工具安装先把三样东西装齐。Obsidian 去官网下载对应系统的安装包装完新建一个 vault路径选一个你记得住的地方比如~/Documents/MyVault。WorkBuddy 按官方文档安装注意看清楚是桌面版还是命令行版两者配置方式不同。Git 用系统包管理器装Windows 用 Git for WindowsmacOS 用brew install git。装完之后验证一下git --version # 应该输出 git version 2.x.xWorkBuddy 装好后先别急着索引用一篇测试笔记跑通流程再说。新建10-Notes/测试笔记.md随便写点内容比如今天学习了向量检索的基本原理核心是把文本映射到高维空间。4.2 WorkBuddy 索引配置实操打开 WorkBuddy 的配置界面找到知识库或索引相关的设置项。不同版本菜单名称可能不一样但核心配置项就那几个知识库路径指向你的 Obsidian vault 目录注意是 vault 根目录不是某个子文件夹文件类型过滤只索引.md文件其他类型先排除减少噪音切片参数按前面说的 400/50 设置向量模型如果支持本地模型就选本地的隐私性更好如果只能用在线模型注意看它的数据处理政策。配置完点开始索引第一次会比较慢几百篇笔记可能要跑十几分钟。跑完之后在对话界面问一个你笔记里明确写过的问题看它能不能准确找出来。如果答非所问八成是切片参数或者相似度阈值需要调。实操心得索引完成后我建议你手动测试 5 到 10 个问题覆盖不同笔记。比如问我关于 XX 项目的笔记里提到了哪些风险看它能不能把分散在几篇笔记里的风险点都找出来。这一步能帮你提前发现配置问题。4.3 Git 首次提交与推送索引跑通后把 vault 提交到 Gitee。注意顺序先建.gitignore再git add否则会把不该传的文件也加进去。cd ~/Documents/MyVault # 确认 .gitignore 已创建 cat .gitignore # 添加所有文件 git add . # 查看将要提交的文件列表确认没有大附件 git status # 提交 git commit -m 初始化知识库Obsidian vault WorkBuddy 配置 # 推送到 Gitee git push -u origin mastergit status这一步千万别跳过。我有一次偷懒直接 commit结果把一个 200 兆的录屏文件传上去了push 卡了半小时最后失败还得用git reset回退重来。养成看git status的习惯能省很多事。4.4 多设备同步的日常工作流两台电脑之间同步标准流程是先拉后推# 早上到公司先拉最新 git pull # 写了一天笔记下班前提交 git add . git commit -m 更新XX 项目笔记 读书笔记 3 篇 git push这里有个关键点WorkBuddy 的索引数据要不要同步我的建议是不同步。索引文件通常很大而且换台机器重新索引一遍也就十几分钟没必要传。把索引目录加进.gitignore就行。如果你在两台机器上都改了笔记git pull时可能冲突。Markdown 文件的冲突其实好解决打开冲突文件会看到和标记手动选择保留哪部分就行。为了避免冲突我的习惯是同一篇笔记尽量只在一台机器上编辑跨设备时先 pull 再动手。4.5 让 AI 检索更准的三个技巧索引跑通只是及格线想让它真正好用还得在笔记写法上下功夫。我总结了三个立竿见影的技巧。第一每篇笔记开头写一句摘要句。比如一篇讲 Git 冲突解决的笔记开头就写本文解决 Git 多设备同步时的文件冲突问题。这句话会被向量化检索时命中率极高。很多人笔记开头直接是正文AI 抓不住重点。第二用双链建立概念关联。Obsidian 的[[双链]]不只是给人看的WorkBuddy 在切片时能识别这些链接把相关笔记串起来。你问XX 概念它可能同时返回定义笔记和应用案例笔记。第三标签要克制。我见过有人一篇笔记打十几个标签结果标签系统彻底失效。我的原则是每篇笔记最多 3 个标签且标签要成体系比如#方法论、#工具、#案例这种粗粒度分类细粒度靠双链和搜索。5. 常见问题排查与避坑实录5.1 索引相关的问题问题WorkBuddy 索引后提问总是答非所问。排查顺序先看切片参数是不是太大如果一篇 2000 字的笔记只切成 2 片每片 1000 字检索精度肯定差再看相似度阈值是不是太低把不相关的内容也放进来了最后看笔记本身是不是太口语化、缺乏明确的概念表述。我遇到过一篇笔记全是今天搞了半天终于弄好了这种流水账AI 根本提取不出有效信息。问题新增笔记后AI 检索不到。大概率是索引没有增量更新。WorkBuddy 有的版本需要手动触发重新索引有的支持文件监听自动更新。去配置里确认一下自动索引或监听文件变化的选项有没有开。如果开了还不生效重启一下 WorkBuddy 服务。5.2 Git 同步相关的问题问题push 时报错remote: error: File xxx is 100.00 MB; this exceeds file size limit。说明有大文件被提交了。解决步骤# 从暂存区移除大文件 git rm --cached path/to/bigfile # 把它加进 .gitignore echo path/to/bigfile .gitignore # 重新提交 git commit --amend -m 移除大文件 git push如果大文件已经在历史提交里了处理起来更麻烦需要用git filter-branch或者 BFG 工具清理历史。所以最好的办法是一开始就把 .gitignore 配好。问题git pull时提示冲突不知道怎么处理。先别慌冲突不是错误是 Git 在问你这两处改动你想保留哪个。打开冲突文件找到 HEAD到之间是你本地的改动到之间是远程的改动。手动编辑成你想要的结果删掉那些标记符号然后git add 冲突文件 git commit -m 解决冲突 git push5.3 常见问题速查表现象可能原因解决方法AI 答非所问切片过大/阈值过低调小 chunk_size调高阈值新笔记检索不到索引未更新手动重新索引或开启监听push 失败提示文件过大大附件被提交git rm --cached 后加 .gitignorepull 出现冲突多设备同时修改手动合并冲突标记Obsidian 打不开 vault路径含特殊字符换纯英文路径索引速度极慢笔记量过大/模型慢分批索引或换本地小模型附件图片搜不到未配置图片处理单独配置 OCR 或图片向量化5.4 几个我踩过的坑坑一把.obsidian整个同步了。结果两台电脑的插件配置互相覆盖A 电脑装的插件在 B 电脑上显示已安装但用不了。正确做法是只同步.obsidian/plugins和.obsidian/themes排除 workspace 文件。坑二笔记文件名用了特殊字符。比如如何解决 C 的 内存泄漏 问题.md引号在 Git 和某些系统上会出问题。文件名尽量用中文、英文、数字和连字符别用引号、斜杠、冒号。坑三以为索引一次就一劳永逸。知识库是活的你每天在写新东西索引也得跟着更新。我现在养成的习惯是每周五下班前手动触发一次全量重新索引顺便把 Inbox 里的临时笔记整理归档。坑四过度依赖 AI 检索自己不动脑。有段时间我什么问题都问 AI结果发现它给的答案虽然来自我的笔记但组合方式未必是我想要的。后来我改成AI 检索 自己精读原文效率反而更高。AI 是帮你缩小范围的不是替你做判断的。6. 进阶玩法与扩展方向6.1 接入更多数据源Obsidian 只是起点。你可以把 Zotero 的文献笔记导出成 Markdown 放进 vault把微信公众号文章用剪藏工具存进来甚至把网页书签转成笔记。数据源越丰富AI 能回答的问题范围越广。我现在的知识库里除了自己的笔记还有 200 多篇文献摘要和 100 多篇剪藏文章。导入 Zotero 笔记的常见做法是用 Zotero 的 Markdown 导出插件把文献笔记批量导出到10-Notes下的一个子文件夹。注意导出后检查一下格式有些插件导出的 Markdown 会带一堆元数据需要清理。6.2 用本地小模型降低成本如果你不想调用在线大模型可以在本地跑一个小参数模型做向量化和问答。卡帕西那种级别的知识库用大模型效果当然好但个人知识库用 7B 到 13B 的模型其实够用了。关键是向量化模型要选对中文场景下选专门针对中文优化的 embedding 模型检索准确率会高很多。本地模型的代价是速度慢、占内存但换来的是完全离线、数据不出机器。我的建议是向量化用本地小模型问答环节如果追求质量可以调在线模型两者分开配置。6.3 知识库的定期维护知识库跟花园一样不修剪就会荒。我给自己定了三条维护规则每月清理一次 Inbox把临时笔记要么归档要么删除每季度检查一次双链把断链修掉每半年做一次全量备份除了 Gitee 仓库再导出一份到移动硬盘。最后分享一个我最近在用的技巧在 WorkBuddy 里设置一个每周回顾的提示词让它自动从我这周新增的笔记里提取关键概念和待办事项生成一份周报草稿。这个用法把知识库从被动查询变成了主动推送体验完全不一样。你可以试试提示词大概是请阅读我本周新增的笔记总结三个核心主题并列出所有标记为待办的事项。