Obsidian+WorkBuddy+Gitee构建本地知识闭环

1. 为什么“Obsidian + WorkBuddy + Gitee”不是又一个工具堆砌方案，而是知识闭环的最小可行结构

你可能已经看过太多“用XX搭建个人知识库”的教程：Obsidian打底、加几个插件、再连个Notion或语雀同步——结果三个月后笔记散落在五个地方，搜索失效，双链断裂，本地文件夹里躺着十几个没命名的.md草稿。我试过七种组合，最后停在这三样上，不是因为它们最炫，而是因为只有这组能同时守住三个不可妥协的底线：本地主权、AI可介入性、跨设备确定性同步。

Obsidian 是骨架——它不联网、不上传、不锁死你的数据，所有笔记就是纯文本文件，存在你电脑硬盘某个文件夹里。WorkBuddy 是神经——它不是另一个聊天框，而是直接嵌在 Obsidian 里的本地 AI 工作台，能读你当前打开的笔记、调用你本地安装的 LLM（比如 Ollama 上的 Qwen2 或 Phi-3）、生成摘要、扩写段落、甚至帮你重写技术文档的语气。Gitee 不是“备份”，而是唯一被验证过的、对中文用户零摩擦的 Git 同步中枢：它不像 GitHub 那样偶尔抽风导致git pull卡住，也不像 iCloud 那样把.obsidian/plugins/文件夹同步成乱码，更不像 Syncthing 那样需要手动配端口和防火墙。它就老老实实跑在你自己的 Git 客户端里，每次git push都返回一行绿色的To https://gitee.com/xxx/xxx.git，稳得像电饭锅跳闸。

这三个工具之间没有“集成 SDK”，没有“官方 API 对接”，全靠 Unix 哲学式的松耦合：Obsidian 把笔记存成 Markdown；WorkBuddy 通过 Obsidian 的 Plugin API 读取当前编辑器内容；Gitee 只管把整个 Vault 文件夹当普通 Git 仓库推拉。这种“不亲密”的关系，反而让它抗折腾——去年 Obsidian 更新 1.6.0 时砍掉了旧版插件 API，WorkBuddy 没崩，因为它的核心逻辑压根不依赖 Obsidian 的 UI 层；Gitee 服务器维护升级那两天，我照样在本地写笔记、用 WorkBuddy 生成周报，等网络恢复git push一下全同步过去。

提示：很多人卡在第一步——以为要“配置 WorkBuddy 连接 Gitee”。根本不需要。WorkBuddy 只和 Obsidian 交互，Gitee 只和你的命令行或 VS Code Git 插件交互。它们之间唯一的“连接线”，是你自己每天按下的Ctrl+S（保存）和Ctrl+Shift+P → Git: Push（推送）。这个设计不是偷懒，是刻意为之：任何中间层都会成为单点故障源。

关键词“Obsidian”“WorkBuddy”“Gitee”在这里不是并列的工具名，而是代表三种能力维度：数据主权（Obsidian）、智能增强（WorkBuddy）、协同基座（Gitee）。少一个，知识流就断一环——没有 Obsidian，AI 处理的就是云端黑盒数据；没有 WorkBuddy，Obsidian 只是高级记事本；没有 Gitee，你的知识库永远困在一台电脑里，谈不上“个人”更谈不上“库”。

2. Obsidian Vault 的底层结构设计：不是文件夹堆砌，而是知识拓扑的物理映射

很多人把 Obsidian 当成 Word 替代品，建个Daily Notes文件夹，再建个Projects文件夹，最后塞一堆Untitled.md。这样用三个月，你会发现自己根本找不到上周写的那个接口设计思路——它可能在Projects/Backend/2024-05-12.md，也可能在Daily Notes/2024-05-12.md里被当成随笔记了一笔。Obsidian 的威力不在“双链”，而在文件系统即数据库。我们真正要设计的，不是笔记怎么写，而是 Vault 的目录骨架怎么长。

我现在的 Vault 结构只有 4 个一级文件夹，且全部小写、无空格、无中文：

vault/ ├── 00-index/ # 全局索引页，只放 [[00-index/README]] 和 [[00-index/Navigation]] ├── 10-domain/ # 领域知识：编程语言、协议标准、设计模式等，按主题分而非按项目分 ├── 20-project/ # 项目快照：每个子文件夹对应一个已交付/暂停的项目，含需求、设计、复盘 └── 30-personal/ # 个人日志：非事务性记录，如学习心得、会议纪要、灵感碎片

关键不是目录名，而是每个文件夹的 README.md 承担着“领域地图”功能。比如10-domain/python/README.md里不写 Python 教程，而是这样组织：

# Python 知识域地图 ## 核心锚点 - [[10-domain/python/asyncio]] - [[10-domain/python/type-hinting]] - [[10-domain/python/venv-vs-poetry]] ## 边界界定 - ✅ 包含：CPython 实现细节、标准库模块行为、PEP 规范解读 - ❌ 不含：Django 框架用法（归入 `20-project/` 下具体项目）、Jupyter Notebook 技巧（归入 `30-personal/`） ## 最近更新 - 2024-06-15：补充 `asyncio.run()` 与 `asyncio.create_task()` 的调度差异 - 2024-06-10：修订 `typing.Union` 在 Python 3.10+ 的新语法

这个 README 不是目录列表，而是该知识域的宪法。它定义了什么该放进来、什么该踢出去、哪些笔记是权威参考。WorkBuddy 后续做知识图谱分析时，会优先扫描这类README.md获取领域边界；Gitee 同步时，这些文件天然成为 Pull Request 的审查焦点——如果有人改了10-domain/python/README.md，我们就知道他在动 Python 领域的认知框架，必须人工确认。

注意：绝对不要在00-index/下放“所有笔记链接”。真正的索引是动态生成的。我用 Obsidian 内置的Dataview插件写了一行查询：

TABLE file.ctime AS "创建时间", file.mtime AS "修改时间" FROM "10-domain" AND !"README" SORT file.mtime DESC LIMIT 10

它自动列出最近更新的 10 个领域笔记，比手维护的链接列表准确十倍，且永不 stale。

文件命名规则同样重要。拒绝接口设计_v2_final_really.md这种名字。采用YYYYMMDD-主题-关键词.md格式，例如20240615-api-design-restful-constraints.md。好处有三：

1. 文件系统排序即时间线：ls 10-domain/api/直接看到按时间倒序排列的设计演进；
2. WorkBuddy 可精准定位：当它分析“RESTful 约束”时，能直接匹配文件名中的restful-constraints，比全文扫描快 3 倍；
3. Gitee 提交历史可读：git log --oneline显示a1b2c3d 20240615-api-design-restful-constraints: add HATEOAS 示例，比update api notes清晰百倍。

3. WorkBuddy 的本地 AI 工作流：绕过 API Key 陷阱，构建真正属于你的智能体

WorkBuddy 最常被误解为“Obsidian 版 ChatGPT”。错。它的价值不在“能聊”，而在把大模型变成你知识库的肌肉记忆延伸。当你写完一段技术方案，不用切到浏览器问“这段描述是否准确”，WorkBuddy 能直接读取你当前编辑的 Markdown 文件、结合10-domain/下相关笔记、调用你本地运行的 Qwen2-7B 模型，给出带引用的修订建议——所有数据不出你的电脑。

实现这个的前提，是彻底放弃“在线 API 模式”。我见过太多人填了 OpenAI Key，结果发现：

• 模型回复里混着 Obsidian 笔记里没有的虚构引用；
• 处理 2000 字技术文档时，API 调用超时，返回半截句子；
• 更致命的是，你刚写完的未提交代码设计，被发到远端服务器，违背了 Obsidian 的本地主权原则。

WorkBuddy 的正确打开方式，是把它当作Ollama 的前端指挥官。步骤极简：

1. 本地部署模型（以 macOS 为例）：

   brew install ollama ollama pull qwen2:7b # 7B 模型在 M2 Mac 上推理速度 12 tokens/sec，足够日常 ollama run qwen2:7b # 首次运行会下载约 4GB 模型文件

2. WorkBuddy 配置指向本地 Ollama：
   在 Obsidian 设置 → WorkBuddy → Model Settings 中：

   • Provider:Ollama
   • Model Name:qwen2:7b
   • Base URL:http://localhost:11434（Ollama 默认监听地址）
   • 关键参数：temperature=0.3（降低随机性，保证技术表述稳定）、num_ctx=8192（上下文窗口设满，避免截断长文档）

3. 创建专属 Skill：技术文档校验器
   WorkBuddy 的 Skill 不是预设功能，而是你用 YAML 写的指令模板。新建vault/.workbuddy/skills/tech-review.yaml：

   name: "技术文档校验" description: "检查当前笔记的技术准确性，引用本地知识库" prompt: | 你是一名资深 [{{domain}}] 工程师。请严格基于以下材料分析当前文档： - 当前笔记内容：{{current_content}} - 相关领域知识（来自 vault/10-domain/{{domain}}/）：{{domain_context}} - 要求： 1. 指出所有与事实不符的表述，标注原文位置（如第3段第2行） 2. 对模糊术语（如“高性能”）给出可量化定义建议 3. 补充 1-2 个本地知识库中已有的最佳实践案例链接 输出格式：仅用 Markdown 列表，不加解释性文字。

当我在写20240615-api-design-restful-constraints.md时，选中全文 → 右键 →WorkBuddy: Run Skill → 技术文档校验→ domain 填api，几秒后得到：

• ❌ 第2段：“RESTful 接口应避免使用 POST 更新资源” —— 错误。RFC 7231 明确允许 POST 用于非幂等更新，PUT 才要求幂等。见 [[10-domain/api/http-methods]]。
• ⚠️ 第4段：“响应时间需控制在 200ms 内” —— “高性能”需量化：建议改为“P95 响应时间 ≤ 200ms（基于生产环境 30 天监控数据）”。
• ✅ 补充案例：[[20-project/payment-gateway/20240322-optimization]] 中的异步回调降级方案可复用。

这个过程没有 API Key 泄露风险，没有网络延迟，所有引用都来自你本地 Vault。WorkBuddy 的本质，是让你把“查文档、比规范、找案例”这三步操作，压缩成一次右键点击。

实操心得：模型选型上，Qwen2-7B 比 Llama3-8B 在中文技术文档理解上更准，尤其对 RFC、ISO 标准编号识别率高；Phi-3-mini（3.8B）适合 M1/M2 Mac 做快速草稿润色，但处理复杂逻辑易幻觉。别迷信参数越大越好——在本地，推理速度和准确性平衡点往往在 4B~7B 区间。

4. Gitee 同步的确定性保障：从“能推上去”到“敢放心推”的工程化实践

很多人用 Gitee 同步 Obsidian，遇到的第一个问题是：git push成功了，但另一台电脑git pull后，Obsidian 打开报错“插件配置损坏”。根源在于：Obsidian 的.obsidian/文件夹里混着绝对路径、临时缓存、GUI 状态数据，这些根本不该进 Git。Gitee 同步的从来不是“整个 Vault”，而是“可重现的知识状态”。

我的.gitignore经过 17 次迭代，现在精简为 12 行，每行都有明确工程依据：

# Obsidian 运行时状态（绝对不进 Git） .obsidian/workspace.json .obsidian/workspace-mobile.json .obsidian/app.json .obsidian/launcher.json # 插件缓存与临时文件（由插件自身管理） .obsidian/plugins/**/cache/ .obsidian/plugins/**/temp/ .obsidian/plugins/**/node_modules/ # 用户生成的二进制附件（图片/PDF 用 Git LFS 管理，见下文） *.png *.jpg *.pdf # WorkBuddy 本地模型缓存（Ollama 自己管） ~/.ollama/

关键在最后三行：图片和 PDF 不是简单忽略，而是用Git LFS（Large File Storage）管理。Gitee 原生支持 LFS，配置只需两步：

# 1. 安装 git-lfs（macOS） brew install git-lfs git lfs install # 2. 声明大文件类型（在 Vault 根目录执行） git lfs track "*.png" git lfs track "*.pdf" git add .gitattributes

这样做的好处是：

• 普通git clone时，LFS 文件只下载轻量指针，Vault 秒开；
• 需要查看 PDF 时，git lfs pull单独下载，不拖慢日常同步；
• Gitee Web 界面能直接预览 PNG，PDF 点击下载，比丢网盘靠谱。

同步流程必须固化为原子操作。我写了个sync.sh放在 Vault 根目录：

#!/bin/bash # 1. 保存所有未保存笔记（Obsidian 必须关闭或启用 Auto Save） osascript -e 'tell app "Obsidian" to activate' \ -e 'delay 0.5' \ -e 'tell app "System Events" to keystroke "s" using command down' # 2. 等待 Obsidian 写入磁盘（实测需 1.2 秒） sleep 1.2 # 3. Git 提交 git add . git commit -m "Sync $(date +%Y-%m-%d_%H:%M)" git push origin main echo "✅ Sync completed at $(date)"

每天下班前双击运行，或绑定 Alfred 快捷键cmd+opt+s。这个脚本的价值不在自动化，而在强制建立“保存→等待→提交”的心智节奏。Obsidian 的 Auto Save 有 1.5 秒延迟，如果没等完就git add，会提交半个写入的文件，导致另一台电脑解析失败。这个 1.2 秒是实测出来的——在 M2 Mac 上，touch test.md && sleep 0.1 && echo "a" > test.md的磁盘写入完成时间中位数。

踩坑实录：曾因忘记git lfs install，导致 PDF 文件被当作文本提交，Gitee 显示乱码，git push失败。修复方法不是删仓库重来，而是：

1. git lfs install
2. git lfs migrate import --include="*.pdf,*.png"
3. git push --force（仅第一次需强推）
   这个操作会重写历史，但 Gitee 支持，且只影响 LFS 文件，Markdown 内容完全保留。

5. 三联组合的日常工作流：从“写笔记”到“知识自生长”的闭环设计

这套组合的价值，不在搭建时的炫技，而在每日使用的“无感增强”。我把它拆解为四个原子动作，每个动作都由三者协同完成，且全部在 Obsidian 界面内闭环：

5.1 新建领域笔记：Ctrl+N触发的智能 scaffolding

当我按下Ctrl+N新建笔记，Obsidian 的Templater插件自动填充模板：

--- created: {{date:YYYY-MM-DD HH:mm:ss}} updated: {{date:YYYY-MM-DD HH:mm:ss}} tags: [{{tp.user.tag_prompt}}] --- # {{tp.user.title_prompt}} ## 背景动机 > 为什么需要这个知识点？解决什么问题？ ## 核心定义 - 关键术语 1： - 关键术语 2： ## 参考链接 - [[10-domain/{{tp.user.domain}}/README]] - RFC XXXX: {{tp.user.rfc_number}}

此时 WorkBuddy 的Domain Context LoaderSkill 自动运行：它扫描10-domain/下所有README.md，提取## 核心锚点链接，生成一个侧边栏面板，显示“当前领域已知知识图谱”。我不用翻文件，直接看到[[10-domain/python/asyncio]]和[[10-domain/python/type-hinting]]已存在，避免重复造轮子。

5.2 编辑中增强：Alt+Enter呼出上下文感知助手

光标停在某句话末尾，按Alt+Enter，WorkBuddy 弹出菜单：

• “扩写技术细节” → 调用 Qwen2，提示词为：“基于 [[10-domain/api/http-methods]] 和 [[20-project/payment-gateway/20240322-optimization]]，扩写当前句，增加 HTTP 状态码选择依据”
• “生成类比解释” → 调用 Phi-3，提示词为：“用快递物流类比 RESTful 资源操作，要求包含 GET/POST/PUT/DELETE 对应场景”
• “检查术语一致性” → 扫描全文，对比10-domain/下术语定义表，标红所有未定义的缩写（如首次出现JWT时提醒“请链接 [[10-domain/security/jwt]]”）

5.3 每日收尾：Cmd+Shift+P → Sync Vault的确定性交付

触发sync.sh后，Gitee 返回成功日志，同时 Obsidian 的Git Graph插件自动刷新，显示本次提交的 diff。我一眼看到：

• 修改了10-domain/api/README.md（新增了 HATEOAS 锚点）
• 新增了20240615-api-design-restful-constraints.md
• 未改动30-personal/下任何文件（说明今日专注领域建设）

这个可视化反馈，比任何 KPI 都真实——知识库的成长，就刻在 Git 提交图谱里。

5.4 跨设备激活：新电脑上的 3 分钟重生

在新 MacBook 上：

1. git clone https://gitee.com/yourname/obsidian-vault.git
2. cd obsidian-vault && git lfs pull（下载 PDF/PNG）
3. 打开 Obsidian → 打开此文件夹 → 安装 WorkBuddy 插件 → 配置 Ollama 地址
4. 所有笔记、双链、插件设置、Skill 模板全部就位。

没有账号绑定，没有云同步等待，没有“正在加载 127 个插件”的焦虑。Vault 就是 Git 仓库，知识就是可执行的代码。

这套流程跑顺后，知识生产不再是“写完存好就结束”，而是进入自生长循环：新笔记 → 触发 WorkBuddy 校验 → 发现知识缺口 → 自动生成待办[[00-index/TODO]]→ 同步到 Gitee → 另一台电脑上看到待办 → 点击跳转 → 开始补全。Obsidian 是土壤，WorkBuddy 是雨露，Gitee 是阳光——三者缺一，植物就长不成。

6. 避坑指南：那些让三联组合失效的“温柔陷阱”

即使严格按上述配置，仍有几个看似合理实则危险的实践，会让整个体系在 3 个月内退化为“又一个失败的知识库项目”。这些都是我亲手踩过的坑，按严重程度排序：

6.1 “用 Obsidian Sync 服务替代 Gitee”——主权让渡的甜蜜毒药

Obsidian 官方 Sync 服务每月 $8，承诺“端到端加密”。但它的加密密钥由 Obsidian Inc. 控制，你无法审计其客户端加密实现。更实际的问题是：当你的 Vault 超过 5GB（常见于存大量 PDF/截图），Sync 服务会频繁中断同步，错误日志只显示Sync failed: unknown error。而 Gitee 的git push失败时，会明确告诉你error: RPC failed; curl 56 LibreSSL SSL_read: SSL_ERROR_SYSCALL，意味着网络抖动，重试即可。真正的数据主权，体现在你能读懂每一个错误代码，并有 100% 把握修复它。Gitee 给你这个能力，Obsidian Sync 不给。

6.2 “把 WorkBuddy 当搜索引擎用”——注意力稀释的加速器

很多人喜欢用 WorkBuddy 的/search命令全局搜笔记。但实测发现：当 Vault 超过 2000 个文件，/search响应时间从 0.8 秒升至 4.2 秒，且返回结果常包含无关的30-personal/日志。正确做法是：用 Obsidian 内置搜索（Cmd+P）查文件名，用 Dataview 查结构化内容，WorkBuddy 只处理“当前上下文”。它不该是 Google，而该是你的副驾驶——只在你写到一半卡壳时，才递上精准的参考资料。

6.3 “在 Gitee 创建私有仓库后开启‘私有部署’”——过度工程的典型

Gitee 企业版提供“私有部署”选项，听起来很安全。但 Obsidian Vault 同步根本不需要服务器端逻辑——它只是 Git 仓库。私有部署反而引入新故障点：你需要维护 Nginx 配置、SSL 证书更新、数据库备份。而 Gitee 公共版的私有仓库，通过 SSH Key 认证，传输全程加密，且 Gitee 的 SLA 99.95% 比你自建服务器靠谱得多。简单性本身就是最高级的安全。别为不存在的风险，制造真实的运维负担。

6.4 “用 WorkBuddy 自动生成所有笔记”——知识失真的温床

WorkBuddy 能根据20-project/payment-gateway/自动生成20240615-payment-api-spec.md，但初稿常混淆“支付通道”和“清算通道”概念。我的修正流程是：

1. WorkBuddy 生成初稿 → 存为20240615-payment-api-spec-draft.md
2. 手动对照10-domain/finance/payment-systems/README.md逐条核对
3. 将修正后的版本存为20240615-payment-api-spec.md
4. 在 draft 文件末尾添加[[20240615-payment-api-spec]]双链

这个“AI 初稿 → 人工校验 → 正式发布”的三步法，确保知识源头可控。WorkBuddy 是产科医生，不是父母——它帮你把知识“生”出来，但养育责任永远在你。

最后分享一个硬核技巧：Gitee 的Webhook可以触发自动化。我在 Gitee 仓库设置里添加 Webhook，Payload URL 指向本地ngrok http 8000，当有push事件时，一个 Python 脚本自动运行：

# 检查是否修改了 10-domain/ 下的 README.md if "10-domain/*/README.md" in changed_files: # 调用 WorkBuddy CLI 重新生成领域知识图谱 subprocess.run(["obsidian-workbuddy", "generate-graph", "--domain=all"])

这样，每次更新领域定义，知识图谱自动刷新，无需手动操作。技术细节可展开，但核心思想不变：让工具链自己运转，你只负责思考。