关于obsidian + ai 搭建知识库, 构建第二大脑二三事

之前obsidian的笔记通过nextcloud同步三端, 感觉太笨重
后来了解到fast-note-sync-service,支持三端同步,MCP,GIT备份
顺手就把笔记接到hermes

下面的文章就是调教ai管理我笔记库的内容, 然后生成的操作指南
目前用着还行, 后面不定期更新

• 20260823更新
  • 指路-> 如何搭建第二大脑——一份来自 Homelab 实践者的完整教程
• 20260805更新
  • env机制不成熟, 维护繁琐, 弃用
  • 新增原笔记生命周期管理机制, 解决PARA与LLM WIKI兼容问题

title: 知识库操作指南
aliases:
- 知识库手册
- KB 操作指南
- Vault 操作指南
description: heyou 知识库的设计、实现与日常操作手册（Librarian 维护，2026-08-05 更新）
tags:
- knowledge-base
- ops
- meta
type: doc
status: active
ai_processed: true
created: 2026-08-04
updated: 2026-08-05
related_topics:
- PARA
- Zettelkasten
- LLM Wiki
- 资产整理

知识库操作指南

本文档由 Librarian 维护，描述 heyou vault 的设计、实现与用例（2026-08-05 更新）。
适用读者：用户（日常使用）、Librarian（自动化维护）、后续接手者（理解系统全貌）。

1. 总览

个人知识库 = PARA 物理分类 + Zettelkasten 链接网络 + LLM Wiki 编译层，三层融合：

• 物理存储：QNAP 上的 fast-note-sync-service 托管 vault heyou，服务端自动 git 提交 GitHub。
• 访问方式：Hermes Librarian 通过 obsidian-sync MCP（26 个工具）远程读写；用户通过 Obsidian 客户端同步编辑。
• 自动化：Hermes cron 负责分诊、编译、体检、资产整理。
• 安全：vault 内笔记由用户确保不含真实敏感数据；占位符 ${VAR} 无敏感值可保留。

角色分工

2. 设计

2.1 目录结构（PARA 变体）

00_Inbox/          待分诊（AI 未处理）；含 _README.md 占位，防空目录被同步清理
01_Projects/       有目标的进行中项目
02_Tech_Domains/   技术领域常青区：Linux / OpenWrt / QNAP / Windows / Docker / Nginx
03_Resources/      可复用脚本与文档：Python / Bash / JavaScript
04_Life_Work/      生活与工作
05_LLM_Wiki/       AI 编译的概念网络（与 PARA 平级，隔离）
99_Raw/            已编译源笔记冻结区（immutable raw 层，按域分类，含 assets/）
99_Archive/        归档
根级：00_Dashboard.md、🧭 Tech Index.md

PARA 原始四类中 Areas 拆成 Tech_Domains + Life_Work。EnvTemplates 目录已于 2026-08-05 随 env 机制废弃删除。

2.2 MOC 导航约定

每个领域一个 🧭 <Name> MOC.md 索引（如 🧭 Linux MOC）。笔记移入后必须补链到对应 MOC；根级 🧭 Tech Index.md 汇总全部入口。

2.3 Frontmatter 约定

（2026-08-05 起不再有 env_id 字段——env 机制废弃，已从全部笔记 frontmatter 移除。）

2.4 三层模型

• PARA → 管「放哪」：物理位置、行动导向（Projects 有 deadline，Areas 持续维护）
• Zettelkasten → 管「是什么」：原子笔记 + [[双链]] + MOC 导航
• LLM Wiki → 管「怎么长」：定期把源笔记编译成 entities/concepts 页，lint 体检

2.5 LLM Wiki 编译层（05_LLM_Wiki/）

• 与 00-04 PARA 平级，不进任何 00-04 MOC，只由 index.md 导航。
• 结构：SCHEMA.md（约定层）/ index.md（目录+Total pages 计数）/ log.md（append-only 操作日志）+ entities/ concepts/ comparisons/ queries/。
• 编译页 frontmatter 含 title/created/updated/type/tags/sources/confidence，agent_generated: true 为可选来源标注；每页 ≥2 出链；sources 指向源笔记路径。
• 完整编译原则（2026-08-05 用户明确）：用户确保笔记无真实密钥，编译不再「仅提炼结构」——概念/配置/命令/步骤如实写入，SKIP-LARGE 分 offset 读全文；不再因密钥顾虑删减内容。
• 源笔记生命周期（2026-08-05 修订）：缓冲区（00-04）→ wiki_raw: true 标记 → 编译成功 + confidence 非 low + ≥2KB → 迁移 99_Raw/<域>/（附件随源 assets/）→ 冻结 immutable。编译只读不删；删除任何源笔记前需用户确认并在 wiki log 登记（2026-08-03 事故铁律延续）。

2.6 密钥策略（2026-08-05 废弃 env 机制）

• env 机制整体废弃：不再有 env_id、.env、Env_Registry、脱敏脚本（envsub/secret_scan/env_ctx/env_sanitize/env_workflow/mcp_secret_scan/sanitize_mihomo/mcp_redact_read 均已删除）。
• 真实密钥由用户自行管理（vaultwarden 等）；vault 内笔记由用户确保不含真实敏感数据。
• 占位符 ${VAR} 只是变量名、无敏感值，可保留在笔记中。
• 对话/终端是泄露向量：不打印、不粘贴真实密钥值。
• 旧 env 产物归档于 Hermes 本机 workspace/archive/env-legacy-2026-08-05/（已被用户手动删除）。

2.7 资产约定

• 附件统一存 <笔记目录>/assets/<笔记名>/。
• 进入 assets/ 后永不移动；多笔记共享只移动一次、其余链接转 ![[filename]]；同 contentHash 去重；孤儿进 .trash。
• 外链图片 ≤5MB 自动本地化，命名 image-<md5前8位>.<ext>。

2.8 边界红线（Librarian 绝不执行）

• 不修改/替换/删除代码块中的环境变量占位符（如 ${DB_PASSWORD}）。
• 不删原始知识卡片——只移动/重命名；删除需用户确认。
• 不读/不打印真实密钥值（含 env 生成物）；只做路径级操作。

3. 实现

3.1 物理层

• 服务：fast-note-sync-service @ http://192.168.5.162:9000（Web 管理面板 + /api/health）。
• vault：heyou（ID 1）。
• git：服务端自动 commit 到 GitHub；历史只在服务端 Web 面板查看，API 不暴露 git 端点（勿探测 /git /status 等路径）。
• MCP 端点：/api/mcp（Bearer MCP_OBSIDIAN_SYNC_API_KEY）。

3.2 Hermes 侧（profile: librarian）

统一工作区 ~/.hermes/profiles/librarian/workspace/（2026-08-05 收拢）：

关键脚本：

3.3 Cron 任务（系统时区 Asia/Shanghai，排期按上海时间）

时区注意：Hermes 系统时区为 Asia/Shanghai（config.yaml timezone 字段，cron 按此调度）；写 schedule 直接按上海时间，无需 UTC 换算。

3.4 已知陷阱速查

• note_list 单次上限 100 条 → 按文件夹 keyword + searchMode:path 分目录查询。
• note_get 的 content 可能是 list（块数组） → 先 normalize 再处理字符串。
• note_replace 对 CRLF 笔记（Windows 创建）匹配失败 → regex=true + [\s\S]*?。
• note_replace 可能假成功：返回 Replaced 1 occurrences 但 contentHash 未变 = 实际没写入 → 核对返回的 contentHash/version 变化。
• note_rename 参数是 oldPath/newPath，不是 path。
• file_write 只收 base64 → 文本用 note_create_or_update；大文件直调 HTTP JSON-RPC。
• 处理类 cron 必须收尾 --init 重建基线，否则下一轮把自己改的再报为变更 → 无限循环。
• ingest_state.json 指纹是增量同步依据：首次运行自动建基线（log.md 已登记源全部视为已同步）；[UPDATE] 触发后脚本立即推进指纹，若 agent 编译失败该变更不会重报——靠 lint 90 天过期检查兜底。
• 空目录会被同步服务清理 → 放 _README.md 占位；脚本一律跳过 _ 前缀元文件。

4. 用例

4.1 新建普通笔记

1. 直接丢进 00_Inbox（或任意位置）。
2. 编辑完成后无需等待——每日凌晨 03:00 分诊+编译 cron 统一处理（原分诊 cron 已删除合并，2026-08-06；用户对延迟不敏感）。
3. 自动流程：补 frontmatter → PARA 归类移动 → 补 MOC 链 → ≥2KB 且有价值 → LLM Wiki 完整编译。
4. 用户无需做任何格式/分类操作。

4.2 含环境变量/占位符的笔记

1. 正文用 ${VAR} 占位符即可（无敏感值）。
2. 真实密钥由用户自行管理（vaultwarden 等），不在 vault 内、不经对话传递。
3. 无需 env_id / 注册表 / 脱敏脚本——env 机制已废弃。

4.3 附件 / 截图

• 自动整理（每 6 小时）：吸入 assets/<笔记名>/、hash 去重、外链 ≤5MB 本地化、孤儿回收。
• 手动预览/执行：python3 asset_manager_mcp.py --dry-run / --execute。

4.4 LLM Wiki

• 导航入口：05_LLM_Wiki/index.md。
• 完整编译：概念/配置/命令/步骤如实写入；SKIP-LARGE 分 offset 读全文。
• 增量同步（delta sync v3）：源笔记增删改后，每日凌晨 03:00 分诊+编译 cron 自动触发——新增 → [NEW] 建页；修改 → [UPDATE] 重编译更新已有页；删除 → 自动给对应编译页加 ⚠️ 源已删标注。指纹在 state/ingest_state.json。
• raw 生命周期（TORAW）：源笔记 frontmatter 加 wiki_raw: true 后，编译校验通过（confidence 非 low）自动迁移 99_Raw/<域>/（附件随源），冻结 immutable。手动触发：note_patch_frontmatter 加 wiki_raw: true。
• 排除 AI 生成物：Dataview 按 agent_generated 过滤，或图谱排除 05_LLM_Wiki。
• 体检：python3 llm_wiki_lint.py（无输出 = 健康）。

4.5 排查「谁改了 / 删了什么」

1. cron 取证：cronjob list → 运行输出（cron/output/<job_id>/）。
2. 服务端 Web 面板 git 历史（Storage/Backup）。
3. 回收站：note_restore / file_restore。
4. 元数据对比：mcp_vault_watch.py（version/mtime/clientName 可溯源到客户端）。

4.6 常见操作速查

5. 相关文档

• [[🧭 Tech Index]]
• [[03_Resources/🧭 Scripts MOC|Scripts MOC]]
• [[05_LLM_Wiki/SCHEMA|LLM Wiki SCHEMA]]
• [[05_LLM_Wiki/index|LLM Wiki Index]]
• [[00_Inbox/_README|Inbox 说明]]