obsidian-gh-knowledge

Obsidian GH Knowledge（CLI 优先）

TL;DR

• 目标： 根据环境上下文，使用最安全、最优的方法引导初始化并管理 Obsidian 库。
• 执行顺序： 0. 确认仓库后克隆到本地 -> 1. 本地 Obsidian CLI -> 2. 本地备用方案 -> 3. GitHub API 备用方案。
• Agent 规则： Agent 必须先读后写，包含 ## TL;DR，并且必须使用 Mermaid 图表进行可视化说明。
• 项目范围： 处理特定项目（cmux、trends 等）时，仅在 5️⃣-Projects/GitHub/<project>/ 下该项目的文件夹内操作。详见下文的“项目范围（关键）”部分。
• 本地封装脚本： 使用 scripts/local_obsidian_knowledge.py 执行可重复的本地 macOS 工作流，将 Obsidian CLI 操作与此库的项目规则和 Git 同步结合起来。
• 原始材料： 如果此库将 raw/ 挂载为 Git 子模块，应将其视为源输入存储区，而不是整理后的笔记区。
• 收件箱划分： raw/inbox 是外部源材料的默认接收区。0️⃣-Inbox 是已包含综合整理、仍需归类的笔记的整理暂存区。
• 健康检查默认方案： 如果此库难以阅读或难以信任，先使用 simplify-review；它会协调全库 Obsidian 计数、活跃范围的图谱检查和概览可读性审查。
• Git 同步： 更新笔记时，优先先拉取并变基再推送，绝不对 main 强制推送，并在任务完成时将同步结果记录到当天的日志中。
• Git 引导初始化： 即使 Obsidian CLI 不可用，本地引导初始化也必须配置 Git 和 raw/ 子模块。保持基线不含钩子且干净，并在引导初始化期间清理过时的 core.hooksPath 配置。

执行模式流程图

graph TB
    A[Start Vault Operation] --> B{Local vault exists}
    B -- Yes --> C{Obsidian CLI ready}
    B -- No --> D{Confirmed vault repo URL}
    D -- Yes --> E[Clone vault into Documents]
    D -- No --> F[Use GitHub mode]
    E --> C
    C -- Yes --> G[Use local CLI mode]
    C -- No --> H[Use local git fallback]
    G --> I[Run operation]
    H --> I
    F --> I

使用此技能可安全、一致地引导初始化并管理 Obsidian 库。

接收区划分（关键）

严格区分两个收件箱的用途：

• raw/inbox：剪藏文章、复制的帖子、转录文本、导入的 Markdown，以及其他保留的源材料。
• 0️⃣-Inbox：已包含综合整理、项目背景或结构化说明，但仍需归类的整理笔记。

判断规则：

• 如果用户希望保留源材料本身，使用 capture-raw 将其存入 raw/inbox。
• 如果用户需要的笔记已体现推理或综合整理，使用 capture 将其存入 0️⃣-Inbox，或直接写入最终项目文件夹。
• 不要将 0️⃣-Inbox 当作原始材料的倾倒区。
• 先搜索整理后的笔记，再搜索 raw/。

事实来源

• 主要实时文档：Context7 Obsidian CLI 索引（/websites/help_obsidian_md_cli）
• CLI 官方文档：https://help.obsidian.md/cli/index
• 介绍 CLI 的公开发行说明：https://obsidian.md/changelog/2026-02-27-desktop-v1.12.4/
• 上游可复用技能集：https://github.com/kepano/obsidian-skills

注意：CLI 文档的部分章节可能仍使用早期访问版的措辞。将公开变更日志（2026 年 2 月 27 日）视为发行标记。

推荐的技能分层

针对不同任务，分别使用通用上游技能和本地仓库专属技能：

• kepano/obsidian-skills/skills/obsidian-cli：规范的命令语法和当前 CLI 功能范围。
• kepano/obsidian-skills/skills/obsidian-markdown：通用的 Obsidian 风格 Markdown 编写规则。
• kepano/obsidian-skills/skills/obsidian-bases：.base 仪表板和结构化知识视图。
• 此仓库中的 obsidian-gh-knowledge：本地库引导初始化、项目范围、表情符号文件夹防护规则、Git 同步和 GitHub 备用方案。

本地辅助脚本 scripts/local_obsidian_knowledge.py 用于衔接上游通用 CLI 模式与此库特有的仓库约定。

执行模式（严格顺序）

0. 引导本地知识库
   • 当本地知识库缺失且用户确认了知识库仓库 URL 时使用。
   • 优先克隆到当前用户的 ~/Documents/<repo-name>，然后将 local_vault_path 写入配置。
1. 本地 Obsidian CLI 模式（引导后优先使用）
   • 当本地知识库存在且 obsidian CLI 可用并已启用时使用。
2. 本地文件系统/Git 回退模式
   • 当本地知识库存在但 CLI 未启用时使用。
3. GitHub 模式回退
   • 当本地知识库不可用、引导未获确认，或本地访问被明确禁用时使用。

此顺序旨在兼容桌面、服务器和沙盒环境。

模式选择（本地或 GitHub）

1. 确定 VAULT_DIR：
   • 如果 ~/.config/obsidian-gh-knowledge/config.json 中有 local_vault_path，则使用该路径。
   • 否则使用 ~/Documents/obsidian_vault/。
2. 如果 VAULT_DIR 不存在且用户已确认知识库仓库 URL，则运行引导脚本，然后重新确定 VAULT_DIR。
3. 如果 VAULT_DIR 存在且 prefer_local 不是 false，则使用本地模式。
4. 在本地模式下，仅在以下条件均满足时优先使用官方 Obsidian CLI：
   • command -v obsidian 执行成功，并且
   • obsidian help 执行成功（CLI 已启用且应用连接正常）。
5. 如果 CLI 检查失败，则回退到本地文件系统/Git 模式。
6. 如果本地模式不可用，则使用 GitHub 模式。

脚本路径辅助工具

使用一个辅助工具，在仓库本地和用户技能目录布局中查找打包的脚本：

resolve_obsidian_gh_script() {
  local name="$1"
  local path
  for path in \
    "skills/obsidian-gh-knowledge/scripts/$name" \
    "agent-skills/skills/obsidian-gh-knowledge/scripts/$name" \
    "scripts/$name" \
    "$HOME/.agents/skills/obsidian-gh-knowledge/scripts/$name"
  do
    if [ -f "$path" ]; then
      printf '%s\n' "$path"
      return 0
    fi
  done
  echo "Could not find obsidian-gh-knowledge script: $name" >&2
  return 1
}

首次工作区引导

当新工作区尚未在本地检出知识库时，使用此工作流。

规则：

• 不要猜测知识库仓库。先请用户确认准确的 GitHub 仓库 URL。
• 用户确认类似 https://github.com/karlorz/obsidian_vault 的仓库后，优先在本地克隆，而不是仅使用 GitHub 模式。
• 默认目标位置为 ~/Documents/<repo-name>。以上述示例为例，路径为 ~/Documents/obsidian_vault。
• ~ 因用户而异。如果当前用户是 root，默认目标位置将变为 /root/Documents/<repo-name>。
• 仅当用户明确要求使用其他目标位置时，才使用 --vault-dir。

确认后运行：

INIT_SCRIPT_PATH="$(resolve_obsidian_gh_script init_local_vault.py)"

python3 "$INIT_SCRIPT_PATH" \
  --repo-url "https://github.com/karlorz/obsidian_vault" \
  --repo-key personal

引导脚本的操作：

• 将已确认的知识库仓库克隆到 ~/Documents/<repo-name>，除非用户提供了 --vault-dir。
• 如果该目录已是同一仓库的克隆，则复用该目录。
• 如果提供了 --raw-submodule-url 和 --init-raw-submodule，则可以选择初始化原始资料子模块，例如 raw/。
• 配置本地 Git 引导，无需 Obsidian CLI：
  • 启用 extensions.worktreeConfig=true
  • 清除共享和工作树本地 Git 配置中的过期 core.hooksPath 配置
  • 设置工作树本地 push.recurseSubmodules=on-demand
  • 初始化已配置的 raw/ 子模块（如果存在）
  • 在安全的情况下，将 raw/ 关联到其已配置的分支和上游
• 更新 ~/.config/obsidian-gh-knowledge/config.json：
  • 设置 local_vault_path
  • 将 prefer_local 设置为 true
  • 如果 default_repo 当前缺失，则设置该项
  • 如果提供了 --repo-key，则添加 repos.<key>
  • 如果 vault_name 当前缺失，则设置该项
  • 使用原始资料子模块引导时，设置 raw_submodule_path 和 raw_submodule_url

可选的原始资料子模块引导：

python3 "$INIT_SCRIPT_PATH" \
  --repo-url "https://github.com/karlorz/obsidian_vault" \
  --repo-key personal \
  --raw-submodule-url "https://github.com/karlorz/obsidian_vault_raw.git" \
  --init-raw-submodule

引导后，重新运行模式选择，并优先从新的 local_vault_path 使用本地 CLI 或本地 Git 回退模式。

注意：

• 此引导流程适用于未安装 obsidian 的无头或远程环境。
• Obsidian Git 插件设置仍是在桌面应用内长期运行的同步层；引导流程只负责准备 Git 和子模块状态。

护栏（避免错误路径）

• 检查路径时不要抑制错误（避免使用 2>/dev/null）；路径缺失时应一目了然。
• 如果本地 vault“缺失”，在决定是初始化还是回退到 GitHub 之前，先输出诊断信息：pwd、echo "$HOME" 和 ls -la "$(dirname "$VAULT_DIR")"。
• 不要手动输入带表情符号的文件夹名称。始终使用 ls/list 并复制准确路径。
• 此 vault 使用类似 5️⃣-Projects 的名称（中间没有空格）。5️⃣ -Projects 会导致本地 ls 和 GitHub 读取失败。
• 如果 read 返回“File not found”，立即 list 父文件夹或 search 文件名，不要猜测。
• 如果需要以编程方式获取带表情符号的文件夹名称：ls -1 "$VAULT_DIR" | rg -m1 "Projects$"（在此 vault 中返回 5️⃣-Projects）。
• 在用户确认 vault 仓库 URL 之前，不要克隆仓库或覆盖 local_vault_path。

项目范围（重要）

警告

常见错误 Agent 经常导航到错误的项目文件夹（例如，处理 cmux 时却进入 trends/）。这会浪费上下文并令用户困惑。

项目范围操作规则：

1. 进行任何 vault 操作前，首先确定当前项目上下文：

   • 检查当前工作目录（例如，/root/workspace -> 查找 CLAUDE.md 或 package.json 以确定项目）
   • 检查对话上下文中提及的项目
   • 如果不明确，询问用户指的是哪个项目

2. 将所有操作（读取和写入）限定在正确的项目文件夹中：

   • 项目文件夹位于 5️⃣-Projects/GitHub/<project>/ 下
   • 示例：cmux 项目 -> 5️⃣-Projects/GitHub/cmux/
   • 示例：trends 项目 -> 5️⃣-Projects/GitHub/trends/

3. 进行任何其他读取或写入之前，始终先读取 <project>/_Overview.md，确认位置正确。

4. 未经用户明确要求，绝不跨越项目边界：

   • 如果正在处理 cmux，不要读取或写入 trends/ 文件夹
   • 如果用户在 cmux 上下文中询问“路线图”，应查找 cmux/cmux-agent-dev-roadmap.md，而非 trends/trends-dev-roadmap.md

5. 项目检测启发式（按顺序）：

   # 1. Check if current workspace has project identifier
   if [ -f "CLAUDE.md" ]; then
     PROJECT=$(grep -m1 "project.*cmux\|project.*trends" CLAUDE.md | grep -oE "cmux|trends" | head -1)
   fi
   
   # 2. Check package.json name field
   if [ -z "$PROJECT" ] && [ -f "package.json" ]; then
     PROJECT=$(jq -r '.name // empty' package.json 2>/dev/null | grep -oE "cmux|trends" | head -1)
   fi
   
   # 3. Check git remote
   if [ -z "$PROJECT" ]; then
     PROJECT=$(git remote get-url origin 2>/dev/null | grep -oE "cmux|trends" | head -1)
   fi
   

6. 列出项目文件夹时，始终显示可用项目：

   ls "$VAULT_DIR/5️⃣-Projects/GitHub/"
   # Output: cmux  data-labeling  openclaw  trends
   

快速检查：

# Local vault path
python3 - <<'PY'
import json, os
p = os.path.expanduser('~/.config/obsidian-gh-knowledge/config.json')
if os.path.exists(p):
    c = json.load(open(p))
    print(os.path.expanduser(c.get('local_vault_path', '~/Documents/obsidian_vault')))
else:
    print(os.path.expanduser('~/Documents/obsidian_vault'))
PY

# CLI availability
command -v obsidian
obsidian help

如果 obsidian help 输出 Command line interface is not enabled，请在 Obsidian 设置中启用该功能之前，使用本地文件系统作为回退方案。

环境兼容性

• 正在运行 Obsidian 应用的 macOS/Windows 桌面环境：使用本地 Obsidian CLI 模式。
• 可使用 Obsidian 图形界面的 Linux 桌面环境：CLI 可能可用，请使用上述相同的检查。
• 无图形界面应用会话的无头 Linux/容器/沙盒环境：假定 Obsidian CLI 不可用，直接切换到本地文件系统或 GitHub 模式。
• 在许多沙盒中，~/.config/obsidian-gh-knowledge/config.json 和 ~/Documents/obsidian_vault 默认不存在。应准备使用已确认的仓库 URL 进行初始化，或明确使用 --repo。

在无头环境中，不要因等待 CLI 而阻塞执行。

本地 Obsidian CLI 模式（首选）

要求

• Obsidian 桌面版 1.12+。
• 在应用设置中启用 CLI：Settings -> General -> Advanced -> Command line interface。
• Obsidian 应用必须能够启动；如果尚未运行，第一个 CLI 命令可能会启动它。
• 在 macOS 上，确保 PATH 包含 /Applications/Obsidian.app/Contents/MacOS。
• 如果 CLI 命令失败，且标准错误输出显示 Unable to find helper app 或 Command line interface is not enabled，请在设置中重新启用 CLI 开关并重启终端。如果命令成功，但只输出了 helper 警告，则将其视为无关信息并继续。

指定 vault 和文件

• 如果当前目录就是 vault，命令将针对该 vault 执行。
• 否则，将 vault=<name> 作为第一个参数。
• 使用 file=<name> 进行维基链接式解析，或使用 path=<exact/path.md> 精确指定目标。

示例：

# Prefer running inside vault root
cd "$VAULT_DIR"

# Or target by vault name explicitly
obsidian vault="My Vault" search query="test"

# Exact file targeting
obsidian read path="5️⃣-Projects/GitHub/cmux/_Overview.md"

核心命令模式

# Search and read
obsidian search query="MOC" path="5️⃣-Projects/" format=json
obsidian read path="5️⃣-Projects/GitHub/cmux/_Overview.md"

# Create/update content
obsidian create path="2️⃣-Drafts/new-note.md" content="# Title\n\n## TL;DR\n"
obsidian create path="2️⃣-Drafts/new-note.md" content="# Title\n\n## TL;DR\n- [ ] Follow up" overwrite
obsidian append path="2️⃣-Drafts/new-note.md" content="\n- [ ] Follow up"

# Move/rename and delete
obsidian move path="0️⃣-Inbox/note.md" to="5️⃣-Projects/GitHub/cmux/note.md"
obsidian delete path="2️⃣-Drafts/tmp-note.md"

# Tasks, tags, properties, templates, daily note
obsidian tasks path="5️⃣-Projects/GitHub/cmux/_Overview.md" todo format=json
obsidian tags counts
obsidian properties path="5️⃣-Projects/GitHub/cmux/_Overview.md"
obsidian templates
obsidian template:read name="github-project-template"
obsidian daily
obsidian daily:append content="- [ ] Review inbox"

高层本地封装器

对于常见的 macOS 工作流，优先使用仓库专用的辅助工具，而不是手动拼接命令序列：

LOCAL_WRAPPER="$(resolve_obsidian_gh_script local_obsidian_knowledge.py)"

python3 "$LOCAL_WRAPPER" doctor
python3 "$LOCAL_WRAPPER" dashboard
python3 "$LOCAL_WRAPPER" review
python3 "$LOCAL_WRAPPER" simplify-review
python3 "$LOCAL_WRAPPER" audit
python3 "$LOCAL_WRAPPER" fix-tldr --dry-run
python3 "$LOCAL_WRAPPER" structure-report --dry-run
python3 "$LOCAL_WRAPPER" structure-fix --dry-run
python3 "$LOCAL_WRAPPER" archive-fix --dry-run
python3 "$LOCAL_WRAPPER" capture-raw "Clipped article" --source "https://example.com/post"
python3 "$LOCAL_WRAPPER" capture "Curated summary note"
python3 "$LOCAL_WRAPPER" project-note cmux "Feature review"
python3 "$LOCAL_WRAPPER" organize "0️⃣-Inbox/feature-review.md" cmux
python3 "$LOCAL_WRAPPER" sync --message "Update vault notes"

--vault-dir 是全局选项。如果需要使用，请将其放在子命令前面，例如 python3 "$LOCAL_WRAPPER" --vault-dir "$VAULT_DIR" doctor。

封装器职责：

• 根据配置解析本地 vault 路径。
• 配置了 raw/ 子模块时，在 doctor 中报告其健康状况。
• 报告本地 Git/引导设置状态，例如工作树本地的 push.recurseSubmodules。
• 在可用时验证官方 obsidian CLI。
• CLI 缺失时不会直接失败；对于远程或无头工作区，doctor 仍会报告本地 Git/引导就绪状态。
• 运行一键式 review 汇总，包含 vault 健康指标、任务计数、近期文件、未解决链接示例，以及明确区分的 raw 与 curated 收录计数。
• 将 dashboard 和 review 中的孤立/死路数量视为 Obsidian 全 vault 信号，而非活动笔记的精确清理范围。
• 运行组合式 simplify-review，将 review、audit、活动范围结构分析、概览可读性检查，以及重复基名/别名检测整合到一份报告笔记中。
• 运行更严格的 audit，检查必需文件夹、项目 _Overview.md 覆盖情况、## TL;DR 位置、超大型 MOC、过期的 Structure Cleanup Inbox 积压项，以及 YAML frontmatter 解析情况。
• 可批量为缺少 ## TL;DR 的笔记插入占位章节。
• 可生成基于本地图谱的结构清理报告，检查活动范围内的孤立和死路笔记，不依赖不稳定的实时 CLI 列表输出。
• 可应用高置信度结构修复：将死路笔记链接到最近的 _Overview.md，并将孤立笔记加入项目 MOC 中自动生成的清理章节。
• 可创建缺失的 _Archive-Index.md 笔记，并为归档笔记添加反向链接，让归档文件夹保持可导航，同时避免污染活动 MOC。
• 在可读性和 TL;DR 审计中跳过 raw/ 子树，因为原始材料是源输入，而非整理后的笔记。
• 将 raw/inbox 视为外部源材料的默认收录通道，将 0️⃣-Inbox 视为整理中的暂存区。
• 在创建或整理项目范围内的笔记之前，先读取 _Overview.md。
• 使用 obsidian move 在 Obsidian 内移动笔记，而不是通过原始 shell 命令重命名。
• 可选地以 local_vault_git_sync.py 收尾。
• 默认在子模块有未提交更改或尚未初始化时阻止同步；只有确有需要时才使用 --allow-dirty-submodules。

本地写入工作流

1. 先读后写（obsidian read ...）。
2. 对于大型编辑，先写入草稿笔记，再有意地合并。
3. 保持远程同步：拉取/变基、提交、推送（不要强制推送）。
4. 笔记成功同步后，如果 vault 工作流或任务上下文有此要求，则将简短的执行摘要追加到 /root/lifecycle/memory/daily/<YYYY-MM-DD>.md。

推荐方式（一条命令）：

LOCAL_SYNC_SCRIPT="$(resolve_obsidian_gh_script local_vault_git_sync.py)"

python3 "$LOCAL_SYNC_SCRIPT" \
  --vault-dir "$VAULT_DIR" \
  --message "Update vault notes"

手动工作流：

cd "$VAULT_DIR"
# If raw/ has changes: commit+push inside raw/ first, then return to parent.
git -C raw status --porcelain=v1   # use `git -C`, not `cd raw` — Bash CWD persists
# git -C raw add -A && git -C raw commit -m "..." && git -C raw push
git pull --rebase --autostash
git status --porcelain=v1
git add -A                          # includes bumped raw/ submodule pointer
git commit -m "Update vault notes"
git pull --rebase
git push

如果 git push 因远程已有更新而被拒绝，请获取并变基到新的 origin/main 最新提交，然后重试推送。不要通过强制推送来解决。

本地文件系统/Git 回退方案（CLI 不可用）

仅在无法使用本地 CLI 时使用。

VAULT_DIR="$HOME/Documents/obsidian_vault"

ls -la "$VAULT_DIR"
rg -n "keyword" "$VAULT_DIR"
sed -n '1,160p' "$VAULT_DIR/5️⃣-Projects/GitHub/cmux/_Overview.md"

编辑时，使用与本地 CLI 模式相同的同步工作流（提交 + 拉取/变基 + 推送）。

GitHub 模式回退方案

在本地 vault 不可用，或明确将 prefer_local 设为 false 时使用。

GitHub 读取协议（避免“找不到文件”）：

1. 对父文件夹执行 list，以复制准确路径
2. 如果文件名/关键词未知，则执行 search
3. 使用返回的准确路径执行 read

仓库解析策略

按以下顺序解析仓库：

1. 如果提供了 --repo <owner/repo>，则使用它。
2. 使用 --repo <key>（不含 /），根据配置中的 repos.<key> 解析。
3. 使用配置中的 default_repo。
4. 如果以上均不可用，则停止并请求提供仓库/配置。

绝不猜测仓库名称。

要求

• 已安装 GitHub CLI：gh
• 已完成身份验证：gh auth status
• 读写前检查仓库访问权限：
  • gh repo view <owner/repo> >/dev/null
  • 如果失败，请停止并请求提供当前账号/团队有权访问的仓库。

命令

SCRIPT_PATH="$(resolve_obsidian_gh_script github_knowledge_skill.py)"

python3 "$SCRIPT_PATH" \
  --repo <owner/repo> <command> [args]

可用命令：

• list --path <path>
• read <file_path>
• search <query>
• move <src> <dest> --branch <branch_name> --message <commit_msg>
• copy <src> <dest> --branch <branch_name> --message <commit_msg>
• write <file_path> --stdin|--from-file <path> --branch <branch_name> --message <commit_msg>

无头 Linux 冒烟检查

在沙盒中进行大量工作之前运行以下检查：

command -v obsidian || true
gh auth status
python3 "$SCRIPT_PATH" --repo <owner/repo> list --path ""
python3 "$SCRIPT_PATH" --repo <owner/repo> read "README.md"
python3 "$SCRIPT_PATH" --repo <owner/repo> search "filename:_Overview.md"

近期验证中的预期行为：

• 无头 Linux 中通常无法使用 obsidian。
• 指定 --repo 且 gh 有访问权限时，GitHub 模式可正常工作。
• 引号括起的表情符号路径受支持：
  • python3 "$SCRIPT_PATH" --repo <owner/repo> list --path "0️⃣-Inbox"

安全规则（关键）

1. 绝不要对 main 执行强制推送。
2. 在 GitHub 模式下，始终在功能分支上写入。
3. 在 GitHub 模式下，合并前始终创建 PR 以供审查。
4. 先读后写。
5. 保持提交小而专注。
6. 只要可行，优先使用本地库操作。

实用技巧（路径与表情符号）

• 始终用引号括起路径（"..."），尤其是表情符号文件夹。
• 优先从命令输出中复制准确路径，而不是重新输入。
• 在 GitHub 模式下遇到 404/路径错误时，先用 list 验证。
• 如果对仓库根目录执行 list 也失败，应视为仓库权限或账号/团队上下文错误，而不只是路径拼写错误。

Obsidian 笔记撰写规则

如果存在仓库级 AGENTS.md，请先遵循其中的要求。

Agent Markdown 规则

• 必需： 始终在靠近顶部的位置添加简短的 ## TL;DR，便于人类快速浏览。
• 必需： 始终使用 Mermaid 图表（graph TB 或 sequenceDiagram）以直观说明架构、工作流或复杂概念。
• 使用 Obsidian 双链（[[note-title]]）链接内部笔记。
• 除非请求重命名/移动，否则保持标题稳定。
• 需要时使用 YAML frontmatter 添加元数据。

Mermaid（兼容 Obsidian）

• 优先使用 graph TB / sequenceDiagram。
• 使用 subgraph "Title"（避免使用 subgraph ID[Label]）。
• 避免在标签中使用 \n；改用 <br/> 或单行标签。
• 节点 ID 保持简单并使用 ASCII 字符（CMUX_DB、OC_GW）。

项目文件夹约定

5️⃣-Projects/ 下的每个项目文件夹都必须包含作为 MOC 的 _Overview.md。

创建项目文件夹时：

1. 在正确的类别中创建文件夹（GitHub、Infrastructure、Research）。
2. 首先创建 _Overview.md。
3. 添加快速导航和文档索引。
4. 从 _Overview.md 链接相关笔记。

模板

GitHub 项目笔记请使用 100-Templates/github-project-template.md。

GitHub 模式示例：

python3 ~/.agents/skills/obsidian-gh-knowledge/scripts/github_knowledge_skill.py \
  --repo <owner/repo> read "100-Templates/github-project-template.md"

配置文件

首次运行时，优先通过 scripts/init_local_vault.py 创建 ~/.config/obsidian-gh-knowledge/config.json。仅在需要调整仓库或库名称时手动编辑该文件。

配置格式：

{
  "default_repo": "<owner>/<vault-repo>",
  "repos": {
    "personal": "<owner>/<vault-repo>",
    "work": "<org>/<work-vault-repo>"
  },
  "local_vault_path": "~/Documents/obsidian_vault",
  "prefer_local": true,
  "vault_name": "My Vault"
}

vault_name 是可选项；在库目录之外运行 CLI 命令时使用它。

工作流参考

有关具体的笔记整理工作流模式，请参阅 references/obsidian-organizer.md。

相关内容

• [[vault-operations-index|库操作索引]]