Shared obsidian brain

LLM Wiki — 接入 Obsidian 并搭建通用第二大脑

一句话把 Obsidian 接进任意 agent，并在 vault 内长出「第二大脑」。全程纯 Markdown 指令，无外部脚本依赖。

从 0→1 流程（标准步骤）

所有步骤幂等：重复运行安全，已存在的跳过（创建文件前先确认不存在）。

第 0 步：确定 vault 根目录

# 优先读环境变量，否则询问用户；得到 $VAULT 绝对路径
echo "${VAULT:-未设置，请询问用户 vault 根目录（Obsidian vault 的绝对路径）}"

第 1 步：Obsidian 前置校验（必做，先于一切写入）

详见 references/obsidian-prereq.md：确认 Obsidian.app 常驻、官方 CLI 开启、obsidian vaults 可用；跑自检脚本，失败即提示用户修复，不盲写配置。

第 2 步：MCP 接入（查 agent → 提醒 → 按平台写 → 验证）

1. 查本地 agent：脚本见 references/platforms.md，只对接已安装的平台。
2. 提醒用户（用 AskUserQuestion）：是否接入、接哪些平台、接哪些 MCP——绝不静默替用户决定。MCP 接入是可选步骤，用户选"不接"则跳过本步。
3. 按平台写入（仅当用户选择接入）：各端写法与写后验证见 references/platforms.md，agent 直接执行对应配置命令。
4. （可选增强）单真源治理：若用户想要集中声明管理 MCP（而非只在各端散写），才读取 references/manifest-schema.md 建立 mcp-manifest.json，然后各端只写指针。这步非必需，默认路径是直接按 platforms.md 写配置。
5. 写后必验证：每个平台写完当场验证加载（Claude mcp list / WorkBuddy 看信任态 / Codex dump 确认段真写进），别凭记忆判断"已接入"。⚠ Codex 不热加载 MCP：改完 ~/.codex/config.toml 的 [mcp_servers.<id>] 后必须重启 Codex 会话，新会话才会真正拉起 server；当前会话内 tool_search 永远查不到新工具。验证只能在新会话做，且要先确认"当前 config 真实含该段"（grep/dump），而非依赖旧日志的 ✔。

第 3 步：建 vault 骨架 + 写守则

目录采用 扁平 5 目录约定（详见 references/paradigm.md 目录权限边界）：Inbox/（人投放，AI 只读）、Daily Notes/（外部生成，AI 严格只读）、Context/（AI 上下文沉淀）、Dashboards/（AI 产生的 KB 卡/报告）、Articles/（AI 全权输出）。隔离靠 AGENTS.md 守则强制 + 目录职责，不靠物理子树。

幂等检测（关键）：若 vault 已存在任一标记目录（Context/ 或 Daily Notes/ 或 Inbox/），视为已初始化，跳过整个 mkdir + 种子文件写入，仅补缺失项，避免新旧结构并存。

创建目录（已初始化则跳过）：

# 仅当未初始化时才批量建
if [ ! -d "$VAULT/Context" ] && [ ! -d "$VAULT/Daily Notes" ] && [ ! -d "$VAULT/Inbox" ]; then
  mkdir -p "$VAULT/Inbox" "$VAULT/Daily Notes" "$VAULT/Context/log" \
           "$VAULT/Dashboards" "$VAULT/Articles/articles"
  echo "已初始化 vault 骨架"
else
  echo "检测到已有结构，跳过骨架创建（仅补缺失项）"
fi

种子文件（创建前确认不存在再写）：Daily Notes/_README.md、Context/log.md、Articles/instructions.md、Inbox/第二大脑范式.md、Obsidian 第二大脑 Index.md、$VAULT/AGENTS.md（守则单真源模板与「三层+三动作」范式、含扁平 5 目录权限 + 多 agent 同步协议见 references/paradigm.md）。

第 4 步：桥接（真源 → 跨 agent 映射）

(a) 守则桥接（幂等）

[ -L "$VAULT/CLAUDE.md" ] || ln -s AGENTS.md "$VAULT/CLAUDE.md"   # Claude Code
WB="$HOME/.workbuddy/AGENTS.md"
if [ -L "$WB" ]; then :; elif [ -e "$WB" ]; then echo "冲突: $WB 是真实文件，跳过"; else mkdir -p "$HOME/.workbuddy" && ln -s "$VAULT/AGENTS.md" "$WB"; fi  # WorkBuddy
# Codex / IDE 直接读 $VAULT/AGENTS.md，无需链接

(b) Skill 桥接（只建 symlink 不复制，范围限项目本地 .agents/skills）

SRC="$VAULT/.agents/skills"
for tgt in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.workbuddy/skills"; do
  [ -d "$SRC" ] || break
  for skill in "$SRC"/*/; do
    [ -d "$skill" ] || continue
    name=$(basename "$skill"); link="$tgt/$name"
    if [ -L "$link" ]; then :;
    elif [ -e "$link" ]; then echo "冲突: $link 非 symlink，跳过";
    else mkdir -p "$tgt" && ln -s "$skill" "$link" && echo "桥接 $link"; fi
  done
done

⚠️ 以上 (b) 仅处理「项目本地 .agents/skills → 全局 agent 目录」单向映射。 全局通用真源 ~/.agents/skills/ 的映射不在此步——它由用户级 agent 自动扫描或各自的桥接负责（见第 6 步铁律）。

第 5 步：打印自动化待办并提醒用户

回灌（文章定稿→KB 卡）+ 周巡检（只出报告不改文件）的逻辑见 references/paradigm.md。各平台壳：WorkBuddy 用 automation_update、Claude 用 hook、Codex 用 [cron.*]、Cursor 按 IDE 机制。AI 必须原样转达，不替用户静默决定。

第 6 步：真源变更后同步铁律（核心治理规则）

原则：.agents/skills/ 是 skill 的唯一真源（单真源）。任何 agent 在真源新增 / 修改 / 删除 skill 后，必须当场把变化同步到所有 agent 目录的软链接，保持零漂移。不做后台常驻脚本——因为变更的发起者本身就是 agent，规则由 agent 在收工前顺手执行即可（可 grep、可跨 agent、无冗余进程）。

真源有两个层级，分别映射：

真源	范围	映射目标
项目本地 .agents/skills/	项目专用 skill	全局 ~/.claude/skills、~/.codex/skills、~/.workbuddy/skills + 项目 .workbuddy/skills
全局通用 ~/.agents/skills/	跨项目通用 skill	全局 ~/.claude/skills、~/.codex/skills、~/.workbuddy/skills

收工同步（幂等，可反复跑，覆盖 增/改/删）：

# 收工同步：两级真源 → 各 agent 目录 symlink 对齐 + 悬空清理
# 幂等，可反复跑，覆盖增/改/删；冲突项只告警不自动删

VAULT="$VAULT"  # 已在上文确定

# 1) 项目专用真源 → 全局 agent 目录 + 项目 .workbuddy/skills
SRC_PROJ="$VAULT/.agents/skills"
# 全局通用真源 → 仅全局 agent 目录（不进项目 .workbuddy/skills）
SRC_GLOB="$HOME/.agents/skills"

# 目标目录
TGTS_GLOB=("$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.workbuddy/skills")
TGTS_PROJ=("${TGTS_GLOB[@]}" "$VAULT/.workbuddy/skills")

# 同步函数：遍历真源下每个 skill，建/修正 symlink
if [ -d "$SRC_PROJ" ]; then
  for skill in "$SRC_PROJ"/*/; do
    [ -d "$skill" ] || continue
    name=$(basename "$skill")
    for tgt in "${TGTS_PROJ[@]}"; do
      [ -d "$tgt" ] || mkdir -p "$tgt"
      link="$tgt/$name"
      if [ -L "$link" ]; then
        cur=$(readlink "$link")
        [ "$cur" = "$skill" ] || { rm "$link"; ln -s "$skill" "$link"; echo "修正: $link"; }
      elif [ -e "$link" ]; then
        echo "冲突（非 symlink，需人工处理）: $link"
      else
        ln -s "$skill" "$link"; echo "新增: $link"
      fi
    done
  done
fi

if [ -d "$SRC_GLOB" ]; then
  for skill in "$SRC_GLOB"/*/; do
    [ -d "$skill" ] || continue
    name=$(basename "$skill")
    for tgt in "${TGTS_GLOB[@]}"; do
      [ -d "$tgt" ] || mkdir -p "$tgt"
      link="$tgt/$name"
      if [ -L "$link" ]; then
        cur=$(readlink "$link")
        [ "$cur" = "$skill" ] || { rm "$link"; ln -s "$skill" "$link"; echo "修正: $link"; }
      elif [ -e "$link" ]; then
        echo "冲突（非 symlink，需人工处理）: $link"
      else
        ln -s "$skill" "$link"; echo "新增: $link"
      fi
    done
  done
fi

# 2) 悬空清理：删指向已不存在真源的残留 symlink
for tgt in "${TGTS_GLOB[@]}" "$VAULT/.workbuddy/skills"; do
  [ -d "$tgt" ] || continue
  for link in "$tgt"/*; do
    [ -L "$link" ] || continue
    [ -e "$link" ] || { rm "$link"; echo "清理悬空: $link"; }
  done
done

echo "✅ skill 同步完成"

铁律要点（任何 agent 必须遵守）：

1. 只建 symlink，绝不复制——真源改了，所有 agent 自动读到最新，零漂移。
2. 改完真源当场同步——不要等、不要靠定时任务；收工前跑一次上面命令块。
3. 删 skill 必须清悬空——第 2) 步专门处理，避免 agent 目录里挂着指向已删真源的死链。
4. 冲突不静默——遇到非 symlink 的真实目录残留（历史孤儿副本），只告警、不自动删，交人工决定。
5. 两个真源都管——项目专用 ($VAULT/.agents/skills) 与全局通用 (~/.agents/skills) 不能漏任一层。

从 1→N 增量更新（已初始化 vault 的日常变更）

以下场景不需要重跑 0→1 全流程，只做增量操作。

加新 MCP server

1. 在 mcp-manifest.json 的 required 或 optional 数组新增一项（若采用集中治理）。
2. 按需在各 agent 配置写入（写法见 references/platforms.md），写后必验证。
3. 追加 Context/log/YYYY-MM-DD.md 记录变更。

改守则（AGENTS.md）

1. 直接编辑 $VAULT/AGENTS.md（单真源），各 agent 自动读到最新。
2. 若改动影响目录结构（如新增目录），同步更新 Obsidian 第二大脑 Index.md。
3. 追加 Context/log/YYYY-MM-DD.md 记录变更。

接新 agent

1. 用 references/platforms.md 的"查本地 agent"命令确认新 agent 已安装。
2. 按该平台写法接入 MCP（第 2 步第 3 点）。
3. 跑第 4 步桥接（守则 symlink + skill symlink）。
4. 跑第 6 步的同步命令块对齐 skill symlink。

加新 skill

1. 在真源（.agents/skills/ 或 ~/.agents/skills/）新增 skill 目录。
2. 跑第 6 步的同步命令块对齐 symlink。
3. 追加 Context/log/YYYY-MM-DD.md 记录变更。

实战踩坑 / Pitfalls（经本项目验证，必读）

接入第二大脑时最易翻车的几处，均来自真实踩坑。核心纪律：配置写完后必须 dump 验证 + 新会话复测，状态记录随真实态更新，绝不凭记忆留 ✔。

#	现象	根因	处理	首次发现
1	Codex 改完 MCP 配置但当前会话查不到新工具	Codex 不热加载 MCP，改 ~/.codex/config.toml 后必须重启会话	重启 Codex 会话；验证前先 grep/dump 确认 config 真含该段	2026-07-17
2	mcp-manifest.json / 决策卡 / log 里留了假 ✔	某临时会话写入后未持久化、又没重启复核，旧 ✔ 误导后续所有会话	状态随复核结果翻转：✔ 必须基于 (a) 当前 config 确含该段 + (b) 新会话 dump/复测通过	2026-07-17
3	agent 目录里的真实 skill 目录落后于真源	symlink 漂移：真实目录（非 symlink）不会随真源更新，还可能夹带 .venv 等	收工跑第 6 步同步命令块；遇非 symlink 真实目录先 diff 确认无独有内容再替换	2026-07-17
4	.codex/skills 为空但 skill 仍可用	Codex 直接扫描项目真源 .agents/skills/ 与用户级 ~/.agents/skills/，侥幸可用	收工同步时显式补 symlink，避免某天扫描路径变了而断	2026-07-17

平台差异（速查）

平台	配置位置	写后自动生效？	关键坑
Claude Code	claude mcp add 项目级 local	✅	勿手改顶层 user scope
WorkBuddy	~/.workbuddy/mcp.json → mcpServers.<id>	❌	须 UI「信任」
Codex	~/.codex/config.toml → [mcp_servers.<id>]（含下划线）	需重启（不热加载）	dump 确认段真写进；重启后复测 34 工具，勿凭旧 ✔
Cursor	.cursor/mcp.json	✅（重启 IDE）	Reload MCP

完整写法与写后验证见 references/platforms.md；Obsidian 前置与 CLI 使用见 references/obsidian-prereq.md；守则模板与自动化逻辑见 references/paradigm.md；可选集中治理（manifest）见 references/manifest-schema.md。

相关 skill

• obsidian-vault：第二大脑建好后的日常双链 / 索引工作流（本 skill 负责"从 0 到 1 接入 + 搭骨架"，它负责"日常维护"）。

安全约束

• 只建软链接，绝不复制 skill 真源 → 零漂移。
• 巡检只产出报告，绝不自动修改文件，需用户确认。
• 不删除用户已有文件；冲突项报告后由用户决定。
• 所有文件创建前先检查是否存在，幂等安全。
• 接入前必须先过 Obsidian 前置校验（第 1 步），失败不写任何配置。

回滚 / 清理

若需撤回本 skill 的所有写入，按以下清单逐项清理（每步需用户确认）。

写入点	清理命令
守则 symlink	rm "$VAULT/CLAUDE.md" rm "$HOME/.workbuddy/AGENTS.md" （仅删 symlink，不删真源 AGENTS.md）
Skill symlink	跑第 6 步同步命令块后，手动删各 agent 目录下指向本 skill 的 symlink
MCP 配置	Claude: claude mcp remove obsidian -s local；WorkBuddy: 从 ~/.workbuddy/mcp.json 删除对应段 + UI 取消信任；Codex: 从 ~/.codex/config.toml 删除 [mcp_servers.obsidian] 段
mcp-manifest.json	rm "$VAULT/mcp-manifest.json"
骨架目录	不建议删（含用户数据）；若确认清空：rm -rf "$VAULT/Context" "$VAULT/Dashboards" 等；Inbox/Daily Notes 属用户数据，绝不自动删
种子文件	rm "$VAULT/Daily Notes/_README.md" "$VAULT/Context/log.md" "$VAULT/Articles/instructions.md" "$VAULT/Inbox/第二大脑范式.md" "$VAULT/Obsidian 第二大脑 Index.md"