1. 为什么我要把 Obsidian、WorkBuddy 和 Gitee 拼在一起用先说结论这套组合解决的核心问题只有一个——让个人知识库从“静态笔记堆”变成“能对话、能追溯、能回滚的活系统”。我用了三年 Obsidian笔记攒了四千多条但真正回头翻的不到百分之五。问题不在于记录而在于检索和再加工。WorkBuddy 这类 AI 工作台能把笔记内容变成可对话的上下文Gitee 则负责版本管理和多端同步的兜底。三者各司其职缺一不可。Obsidian 的定位是本地优先的 Markdown 知识库。所有笔记以纯文本形式存在本地文件夹里不依赖任何云端服务就能打开和编辑。这个特性决定了它天然适合做“知识底座”——数据完全归你掌控格式通用迁移成本极低。但 Obsidian 本身不具备 AI 能力搜索靠关键词匹配关联靠手动双链面对几千条笔记时想找“三个月前记的那个关于缓存穿透的解决方案”基本靠运气。WorkBuddy 在这套组合里扮演的是AI 交互层。它不是一个笔记软件而是一个能读取本地文件、理解上下文、执行多步任务的工作台。你可以把它理解成一个“能看懂你文件夹的智能助手”。把 Obsidian 的笔记库路径挂载给 WorkBuddy它就能基于你的全部笔记内容回答问题、生成摘要、提取待办、甚至帮你重写某段文字。关键在于WorkBuddy 支持自定义 Skill这意味着你可以把“读 Obsidian 笔记”这个动作封装成一个可复用的能力每次调用自动拉取最新内容。Gitee 的角色容易被低估但它是整套系统的安全网。Obsidian 的笔记库本质上就是一个文件夹用 Git 管理再合适不过。每次修改后提交到 Gitee 私有仓库相当于给知识库上了版本控制。误删了某条笔记回滚到上一个 commit 就行。换电脑了clone 下来直接继续用。更重要的是Gitee 的私有仓库免费且国内访问速度快作为个人知识库的远程备份非常合适。这三者拼在一起形成了一条完整的链路Obsidian 负责记录和存储WorkBuddy 负责理解和交互Gitee 负责版本和同步。下面我按实际搭建顺序把每个环节的细节和踩过的坑逐一拆开讲。2. 搭建前的环境准备与工具选型2.1 Obsidian 的安装与初始配置Obsidian 的下载渠道只有一个官方来源不要从第三方站点获取安装包。安装过程没什么好说的一路下一步即可。装完之后第一件事是关闭安全模式否则第三方插件无法启用。路径在设置 → 第三方插件 → 关闭安全模式。接下来创建一个 vault也就是笔记库文件夹。我的建议是不要把 vault 放在系统盘的用户目录下因为后续要用 Git 管理路径里带中文或空格容易出问题。我自己的做法是在 D 盘或移动硬盘根目录建一个纯英文路径比如D:/KnowledgeBase。这个文件夹就是整个知识库的物理载体所有笔记、附件、配置都在里面。初始配置里有两个选项值得注意。一是附件文件夹路径默认是 vault 根目录建议改成attachments子文件夹保持根目录整洁。二是新笔记的默认位置我习惯设为inbox文件夹所有临时记录先扔进去后续再整理归档。这两个设置花不了两分钟但能省掉后期大量整理时间。2.2 WorkBuddy 的获取与基础设置WorkBuddy 目前有国际版和国内版之分功能上略有差异。国内版对中文语境的理解更自然国际版在某些代码生成任务上表现更好。我两个版本都装了日常笔记问答用国内版涉及代码片段处理时切到国际版。安装过程不复杂官网下载对应平台的安装包双击运行即可。装完之后第一件事是配置工作目录。WorkBuddy 需要知道去哪里读取文件在设置里把 Obsidian vault 的路径添加为“工作区”或“上下文目录”。不同版本的叫法可能不一样有的叫 Workspace有的叫 Context Folder本质都是告诉 AI“你可以读这个文件夹里的东西”。添加之后WorkBuddy 就能索引 vault 里的 Markdown 文件后续对话时自动带入相关内容。这里有个细节不要一次性把整个 vault 都挂载进去。如果你的笔记库有几千条全量索引会拖慢响应速度而且很多内容跟当前任务无关。更好的做法是按主题分文件夹比如work、study、life需要处理哪个主题就挂载哪个子目录。WorkBuddy 支持多工作区切换这个设计很实用。2.3 Gitee 仓库的创建与 SSH 密钥配置Gitee 这边需要做三件事创建私有仓库、配置 SSH 密钥、初始化本地 Git 仓库。创建仓库时务必选私有知识库内容不适合公开。仓库名随意我一般叫knowledge-base或notes。开源许可证选“不使用”即可个人私有仓库不需要许可证。SSH 密钥配置是新手最容易卡住的地方。流程是这样的先在本地生成密钥对命令是ssh-keygen -t rsa -b 4096 -C 你的邮箱一路回车即可。生成的公钥在~/.ssh/id_rsa.pub用文本编辑器打开全选复制。然后到 Gitee 的设置 → SSH 公钥粘贴进去保存。验证是否配置成功用ssh -T gitgitee.com看到欢迎信息就说明通了。注意生成密钥时如果之前已经有过密钥不要覆盖而是指定一个新的文件名比如id_rsa_gitee。然后在~/.ssh/config里配置对应的 Host否则多个平台之间会冲突。本地这边进入 Obsidian vault 文件夹执行git init然后git remote add origin gitgitee.com:你的用户名/knowledge-base.git。先不要急着 commit因为 Obsidian 的.obsidian文件夹里有一些工作区状态文件每次打开都会变需要先配置.gitignore。3. 核心环节一让 Obsidian 笔记库适配 Git 管理3.1 .gitignore 的编写与必要排除项Obsidian 的 vault 里不是所有文件都适合纳入版本控制。.obsidian文件夹里的workspace.json、workspace-mobile.json记录的是当前打开的标签页和面板布局每次关闭都会变提交上去只会制造无意义的 diff。.trash文件夹是回收站也没必要同步。还有.DS_StoremacOS和Thumbs.dbWindows这类系统文件同样应该排除。我的.gitignore内容如下.obsidian/workspace.json .obsidian/workspace-mobile.json .obsidian/cache .trash/ .DS_Store Thumbs.db但注意.obsidian下的其他文件比如app.json、community-plugins.json、hotkeys.json是应该提交的这样换设备后插件配置和快捷键能直接恢复。所以不能整个.obsidian都忽略要精确到具体文件。3.2 首次提交与远程推送的完整流程配置好.gitignore之后执行以下命令完成首次提交git add -A git commit -m init: 初始化知识库 git branch -M main git push -u origin main这里有一个坑Gitee 默认分支可能是master但 Obsidian 社区习惯用main。用git branch -M main重命名本地分支后再推送远程会自动创建main分支。如果远程已经有master需要在 Gitee 仓库设置里把默认分支改成main否则每次 push 都要指定分支名。推送成功后去 Gitee 仓库页面刷新应该能看到所有笔记文件。如果发现某些文件夹没传上去检查是不是被.gitignore误伤了。我遇到过attachments文件夹被忽略的情况原因是之前在某处写了*.png规则后来删掉了但 Git 缓存还在需要git rm -r --cached attachments再重新 add。3.3 日常同步的自动化脚本手动 commit 和 push 太麻烦我写了一个简单的 shell 脚本放在 vault 根目录双击就能执行#!/bin/bash cd /d/KnowledgeBase git add -A git commit -m sync: $(date %Y-%m-%d %H:%M) git push origin mainWindows 下可以用.bat文件实现类似效果echo off cd /d D:\KnowledgeBase git add -A git commit -m sync: %date% %time% git push origin main pause这个脚本我放在桌面每天下班前点一下。commit message 自动带时间戳方便回溯。如果某天忘了同步第二天打开 Obsidian 看到笔记还在但 Gitee 上没有最新版本点一下脚本就补上了。实操心得不要用 Obsidian 的 Git 插件自动提交因为它的提交频率太高每次编辑都触发一次 commit历史记录会变得非常臃肿。手动或定时提交更可控。4. 核心环节二WorkBuddy 接入 Obsidian 笔记库的实操4.1 工作区挂载与索引策略WorkBuddy 挂载 Obsidian vault 的方式取决于版本。国内版通常在设置里有“添加工作目录”的按钮选择 vault 路径即可。国际版可能需要通过配置文件或命令行参数指定。挂载完成后WorkBuddy 会开始索引 Markdown 文件索引时间取决于笔记数量四千条笔记大概需要两三分钟。索引策略上我建议按文件夹分批挂载。比如先挂载work文件夹处理完工作相关的问题后再切换到study文件夹。这样每次对话的上下文更聚焦AI 的回答也更精准。如果一次性挂载整个 vaultAI 在回答时会引入大量无关笔记反而降低质量。WorkBuddy 的 Skill 机制是这套组合的精髓。你可以创建一个自定义 Skill名字叫“查笔记”描述写“根据用户问题检索 Obsidian 笔记库并给出答案”然后在 Skill 配置里指定工作目录和检索方式。这样每次提问时WorkBuddy 会自动执行“读取笔记 → 理解问题 → 生成回答”的流程不需要手动粘贴内容。4.2 用 WorkBuddy 做笔记问答与摘要生成挂载完成后直接在工作台对话框里提问就行。比如“帮我找一下关于 Redis 缓存穿透的笔记”WorkBuddy 会扫描 vault 里的 Markdown 文件找到相关段落并整理成回答。实测下来对于有明确关键词的问题召回率很高对于语义模糊的问题比如“我之前记过一个关于性能优化的思路”就需要 WorkBuddy 的语义理解能力国内版在这类场景下表现更好。摘要生成是另一个高频用法。我经常把一篇长笔记的路径丢给 WorkBuddy让它“用三句话总结这篇笔记的核心观点”。它会读取文件内容生成简洁的摘要。这个功能在整理旧笔记时特别有用——快速判断一条笔记是否还有保留价值不需要逐字重读。还有一个进阶用法让 WorkBuddy 对比多条笔记找出矛盾或重复的内容。比如我有好几条关于“数据库索引优化”的笔记时间跨度两年里面有些结论已经过时了。我让 WorkBuddy 把这些笔记都读一遍列出观点不一致的地方然后我手动合并成一条最新版本。这个操作如果靠人眼做至少花半小时WorkBuddy 几秒钟就搞定了。4.3 WorkBuddy Skill 的编写与复用Skill 的编写不复杂本质就是一段描述加一组配置。以下是我常用的“笔记检索”Skill 的核心配置思路name: 笔记检索 description: 根据用户问题在 Obsidian 笔记库中查找相关内容并整理回答 workdir: D:/KnowledgeBase file_pattern: **/*.md max_results: 10workdir指定笔记库路径file_pattern限定只读 Markdown 文件max_results控制返回的笔记数量上限。这个 Skill 创建一次后续所有笔记问答都能复用。WorkBuddy 支持 Skill 导入导出换设备时直接把 Skill 文件拷过去就行。注意Skill 里的workdir路径要用绝对路径不要用相对路径。相对路径在不同工作目录下执行时会解析到不同位置导致找不到文件。5. 核心环节三Gitee 作为知识库版本控制的完整方案5.1 分支策略与提交规范个人知识库不需要复杂的分支模型但也不能全在main上裸奔。我的做法是main分支保持稳定日常编辑在draft分支上进行每周合并一次到main。这样即使某次编辑出了问题main上的内容始终是可用的。提交信息的格式我固定为类型: 描述类型包括add新增笔记、update修改内容、fix修正错误、sync自动同步。比如add: 缓存穿透解决方案对比、update: 补充 Redis 集群配置细节。这样翻看提交历史时一目了然找某个时间点的改动很快。5.2 多设备同步的冲突处理多设备同步是 Git 管理笔记库最容易出问题的地方。场景是这样的你在公司电脑上改了笔记 A 并 push 了回家后用家里电脑打开 Obsidian忘了先 pull 就直接编辑笔记 A然后 push 时就会冲突。我的处理流程是每次打开 Obsidian 之前先 pull每次关闭之前先 push。把这两个动作做成脚本放在桌面养成习惯后基本不会冲突。如果确实冲突了Git 会在文件里插入和标记手动选择保留哪个版本即可。Obsidian 能正常打开带冲突标记的文件只是显示上会有些乱解决后保存再 commit 就行。还有一种情况是附件冲突。图片、PDF 这类二进制文件无法像文本一样合并Git 会直接报错。我的做法是附件文件夹单独处理不纳入日常同步而是用网盘或移动硬盘定期备份。笔记正文里的附件链接用相对路径这样即使附件暂时缺失笔记本身还能正常阅读。5.3 利用 Gitee Pages 做笔记发布可选Gitee Pages 可以把仓库里的静态文件发布成网页。Obsidian 笔记是 Markdown 格式理论上可以用静态站点生成器转成 HTML 后发布。但我不建议把整个知识库都发布出去因为很多笔记包含个人信息或工作内容。如果确实需要分享某部分笔记可以单独建一个public文件夹里面放整理好的内容然后用 Gitee Pages 发布这个子目录。这个功能我用的不多因为个人知识库的核心价值在于“自己用”而不是“给别人看”。但如果你有写公开教程或分享笔记的需求Gitee Pages 是一个零成本的方案。注意 Gitee Pages 需要实名认证才能开通而且免费版有访问频率限制不适合高流量场景。6. 常见问题与排查技巧实录6.1 Obsidian 打不开或插件失效Obsidian 打不开最常见的原因是插件冲突。特别是同时装了多个社区插件时某个插件更新后可能与 Obsidian 主程序不兼容。排查方法是进入安全模式启动时按住 Shift如果安全模式下能正常打开就逐个启用插件定位问题源。另一个原因是配置文件损坏。.obsidian文件夹里的app.json或community-plugins.json如果格式错误Obsidian 会卡在启动界面。解决办法是备份后删除这两个文件Obsidian 会重新生成默认配置。笔记内容不受影响只是插件需要重新启用。6.2 WorkBuddy 读不到笔记内容WorkBuddy 读不到笔记通常有三个原因。一是工作目录路径写错了检查设置里的路径是否与 vault 实际路径一致注意 Windows 下反斜杠和正斜杠的区别。二是文件权限问题如果 vault 放在系统保护目录下WorkBuddy 可能没有读取权限把 vault 移到用户目录或非系统盘即可。三是索引未完成刚挂载工作区时 WorkBuddy 需要时间建立索引等几分钟再试。还有一个隐蔽的问题笔记文件编码不是 UTF-8。Obsidian 默认用 UTF-8 保存但如果你从其他软件导入的笔记是 GBK 编码WorkBuddy 读取时会出现乱码。用 VS Code 打开文件右下角切换编码为 UTF-8 后保存即可。6.3 Gitee 推送失败与密钥问题推送失败最常见的报错是Permission denied (publickey)说明 SSH 密钥没配置好。检查步骤ssh -T gitgitee.com是否返回欢迎信息如果没有说明密钥没生效。可能是公钥粘贴时多了空格或换行重新复制粘贴一次。也可能是~/.ssh/config里配置了多个 Host 导致冲突临时重命名 config 文件再试。另一个常见报错是failed to push some refs通常是因为远程仓库有本地没有的提交。先git pull --rebase origin main把远程改动拉下来再 push。如果 pull 时提示refusing to merge unrelated histories加--allow-unrelated-histories参数强制合并。问题现象可能原因解决方式Obsidian 启动卡住插件冲突或配置损坏安全模式启动逐个排查插件WorkBuddy 读不到笔记路径错误或权限不足检查工作目录路径和文件权限Gitee 推送报 publickey 错误SSH 密钥未生效重新配置密钥检查 config 文件Git 冲突标记出现在笔记里多设备同时编辑同一文件手动解决冲突后重新提交附件文件无法同步二进制文件冲突附件单独备份不纳入 Git6.4 实操避坑清单以下是我踩过的坑按严重程度排序不要用 Obsidian 的 Git 插件自动提交提交频率过高历史记录臃肿回滚时找不到关键节点。不要把 vault 放在 OneDrive 或 iCloud 同步目录下云盘同步和 Git 同步会互相干扰导致文件锁死或版本混乱。WorkBuddy 的工作区不要挂载整个 vault按主题分文件夹挂载响应更快回答更准。Gitee 仓库务必设为私有知识库内容可能包含工作信息或个人隐私公开仓库有泄露风险。定期检查 .gitignore 是否误伤新增文件夹时确认是否被忽略规则覆盖避免笔记没传上去。换设备后先 pull 再编辑这个习惯能避免百分之九十的冲突问题。7. 我在这套组合上的一些个人体会这套组合我用了大半年最大的感受是知识库的“可对话性”比“可检索性”重要得多。以前我花大量时间给笔记打标签、建双链试图用结构化的方式组织知识。但实际使用中我很少按标签去翻笔记而是直接问 WorkBuddy“我之前记的那个关于 XX 的方案在哪”。AI 把检索这件事从“人找笔记”变成了“笔记找人”效率提升是数量级的。Gitee 这边我现在的习惯是每天下班前跑一次同步脚本周末花十分钟看看这周的提交记录回顾一下改了哪些笔记。这个动作本身也是一种知识复盘——哪些笔记反复修改说明是核心关注点哪些笔记提交后再没动过可能需要归档或删除。WorkBuddy 的 Skill 机制我还在探索中目前只用了笔记检索和摘要生成两个。后续想尝试的是“自动整理 inbox”——让 WorkBuddy 每天定时读取inbox文件夹里的临时笔记自动分类到对应主题文件夹并生成一条汇总。这个如果能跑通知识库的维护成本会进一步降低。最后分享一个小技巧在 Obsidian 里建一个meta文件夹专门放关于知识库本身的笔记。比如“我的笔记分类规则”、“常用 WorkBuddy Skill 列表”、“Gitee 同步操作手册”。这些元笔记不参与日常检索但在换设备或重新搭建环境时能省很多事。我上次换电脑照着meta文件夹里的手册操作半小时就把整套环境恢复了。