Obsidian 库（Git）简易操作

以 vault 根目录下的 Markdown 文件 为真源；不依赖 Obsidian 应用 API。文件操作用 Glob、Grep、Read 与编辑工具；Git 操作用 git -C "<vault>" ...，且 仅在该 vault 目录已是 Git 仓库时 执行（用户要求 git init 时再初始化）。

0. 变更后是否走同步 SOP

用户已声明采用「vault 同步 SOP」或同意安装后定时同步：每次对本 vault 的笔记 创建/修改/移动/删除 后，在同一轮对话中尽量按 vault-sync-sop.md 执行第 1～3 步；定时任务（每 2h）仅在用户同意后在有 openclaw CLI 的环境尝试配置（详见该文件第 0 节）。
未声明：日常仍可按第 5～6 节操作，不主动强推、不自动注册 cron。
能力边界：Skill 不会在无用户同意时自行创建定时任务；openclaw 不可用则说明并停止。

1. 解析 vault 根目录（每次先定根）

按优先级取 第一个有效 的目录（须为已存在的目录；解析路径时把 ~ 展开为用户主目录）：

环境变量 OBSIDIAN_VAULT（可在终端执行 echo "$OBSIDIAN_VAULT" 判断）。
用户在本对话中给出的 vault 绝对路径（仅本对话内沿用，不写入其它文件除非用户要求）。
当前 Cursor 工作区根目录：若根下存在 .obsidian 目录，可视为 vault 根。
约定默认目录：~/.openclaw/workspace/obsidian-git-vault（即 $HOME/.openclaw/workspace/obsidian-git-vault）在磁盘上已存在时作为 vault 根。

若以上皆无效：向用户索要 vault 绝对路径，或说明可 mkdir -p ~/.openclaw/workspace/obsidian-git-vault 后作为默认库再操作。禁止把上述列表以外的路径当作默认去猜。禁止操作落在所选 vault 根以外的未授权路径（防路径穿越）。

下文记 V="<vault 绝对路径>"，命令统一写 git -C "$V"。

1.1 默认 `.gitignore`

不单独提供 default.gitignore 文件。新建库时运行 bash "$SKILL_ROOT/scripts/init-default-vault.sh"，若尚无 $V/.gitignore 会 内联写入 规则：系统杂项、.env/密钥、编辑器、可选用「不同步的」.obsidian/workspace*.json、.trash/、以及 默认排除常见非文本附件（图片/音视频/压缩包/Office/字体等）；若 vault 需把图片或 PDF 纳入 Git，删掉 $V/.gitignore 里对应段或改规则。

1.2 Bash 脚本（`scripts/`）

SKILL_ROOT 指含本 SKILL.md 的目录（openclaw 内多为 .cursor/skills/obsidian-git-vault）。优先用脚本代替手写长命令：

bash "$SKILL_ROOT/scripts/resolve-vault.sh"：打印 $V；可传覆盖路径为第一个参数；支持 OBSIDIAN_VAULT、CURSOR_WORKSPACE、当前目录含 .obsidian、~/.openclaw/workspace/obsidian-git-vault（须已存在）。
bash "$SKILL_ROOT/scripts/init-default-vault.sh"：创建默认目录、git init、缺省时写入内置 .gitignore（含非文本附件忽略，见 §1.1）；可选参数为目标目录，默认 ~/.openclaw/workspace/obsidian-git-vault。
bash "$SKILL_ROOT/scripts/vault-sync.sh"：干净工作区下 fetch、判断领先/落后/分叉并 push / pull；见脚本内 --help。接受 SOP 强推时设 OBSIDIAN_SOP_FORCE_LEASE=1；OBSIDIAN_PULL_REBASE=1 则落后时 pull --rebase。
bash "$SKILL_ROOT/scripts/list-conflicts.sh"：列出合并冲突文件。
bash "$SKILL_ROOT/scripts/openclaw-cron-vault-sync.sh"：在本机有 openclaw 时注册约每 2 小时任务（需用户事前同意）；可用环境变量改 OBSIDIAN_CRON_EXPR 等。

冲突合并仍以人工/Agent 编辑 Markdown 为主；脚本不自动改冲突正文。

2. 检索

按文件名：在 vault 根下 Glob，如 **/*.md 或 **/某目录/**/*.md。
按正文 / 链接 / 标签：在 vault 根下 Grep，可搜关键词、[[、tags:、aliases:、正文 #tag 等。
精读：对命中列表再 Read 必要文件；回答中引用内容须来自已读文件，勿编造。
按 Git 历史（用户要「谁改过 / 某文件历史」时）：git -C "$V" log --oneline -n 20 -- path/笔记.md，必要时 git -C "$V" log -p -n 3 -- path/笔记.md。
.obsidian 下配置默认不当成「笔记正文」去搜，除非用户明确要求。

输出时列出 相对 vault 的路径 与简短命中说明即可。

3. 管理

3.1 修改

小步修改正文或 YAML frontmatter，保持 Markdown 与 frontmatter 语法有效。不大段重写用户未要求的内容。

3.2 移动与重命名

用 git -C "$V" mv 旧路径新路径（已纳入 Git 跟踪时优先）或普通 mv 后再 git add。完成后：

对已知的 旧文件名 / 旧路径，在 vault 内 Grep 是否仍有 [[旧名]] 或旧相对链接。
向用户说明是否断链；若用户要求批量替换链接，再逐文件修改。不在未确认时大规模自动改链。

3.3 删除

仅当用户 明确要求删除 某文件时执行；恢复未提交删除可用 git -C "$V" restore --staged 路径 / git restore 路径（按当时状态）。

4. 创建

路径与文件名由用户指定或按 vault 现有习惯（如 inbox/、notes/）；文件名避免非法字符，空格可保留或与用户约定用 -。
新建后若需纳入版本控制：git -C "$V" add 路径（用户要求提交时再与其它变更一起 commit）。
可选 YAML frontmatter，例如：title、date、tags；无模板时最小可用：

yaml

---
title: 笔记标题
date: YYYY-MM-DD
tags: []
---

若需在索引/MOC 中挂链，仅在用户指定目标文件时向其中追加 [[新笔记名]]。

5. Git 版本控制（本地）

前提：git -C "$V" rev-parse --is-inside-work-tree 为真；否则仅在用户明确要求时 git init（初始化后提醒用户设置 user.name / user.email 若尚未配置）。

用户未要求时，不主动执行破坏性命令（见本节末）。

意图	典型命令（均在 `$V` 下）
看工作区	`git status`
看未暂存差异	`git diff`；看已暂存 `git diff --staged`
暂存	`git add 路径` 或 `git add -A`（用户确认范围后再用 `-A`）
提交	`git commit -m "说明"`；说明应简短、可辨（如 `note: 添加 xxx`、`note: 修改 xxx`）
最近提交记录	`git log --oneline -n 20`
某文件历史	`git log --oneline -- path`
分支	`git branch` / `git switch -c 新分支名`（用户要求时）
暂存手头改动	`git stash push -m "说明"`；恢复 `git stash pop` 或 `git stash apply`
撤销未提交修改	`git restore 路径`（丢弃工作区改动前需用户确认）
取消暂存	`git restore --staged 路径`

高风险：git reset --hard、裸 git push --force、git rebase 等——默认仅用户 逐字明确要求 时执行。若用户 已采用 vault-sync-sop.md，则其中写明的「本地领先时推送 / push --force-with-lease」条件 优先于 本句的保守默认。

不要直接编辑 .git 目录内文件；不把 .git 当笔记检索。

6. 远程仓库与同步

前提：网络与认证由用户环境解决（SSH key、credential、GitHub CLI 等）；推送/拉取需 full_network 类权限时由用户在环境中授权。

意图	典型命令
查看远程	`git -C "$V" remote -v`
添加远程	`git remote add origin <url>`（名称按用户习惯，不限于 `origin`）
修改远程 URL	`git remote set-url origin <url>`
删除远程	`git remote remove 名称`（用户明确要求时）
取回远程分支（不合并）	`git fetch origin` 或 `git fetch --all`
与当前分支合并	`git pull` 或 `git pull --rebase`（用户偏好 rebase 时再使用后者）
推送到远程	`git push`；首次跟踪上游：`git push -u origin 当前分支名`
查看分支与跟踪关系	`git branch -vv`

合并冲突：默认提示冲突路径并手工清标记后 git add、git commit。若用户已采用 vault-sync-sop.md，按其中 第 3 节（告警 + 按范围合并 Markdown）执行。

用户说「备份到 GitHub / 同步」时：先 status，再按需 add/commit，最后 push；若远程为空分支首次推送，可能需要 -u。

6.1 配置向导（检测 Git、远程与权限）

从零检测 Git、初始化、添加/修改远程、选择 SSH 或 HTTPS、权限收敛（最小 scope、不把密钥写进仓库），或说明 openclaw 仓库拉取 skill 与 笔记 vault 单独 git pull 的区别时：Read git-remote-wizard.md：先按其中 「使用前：向用户提示的最小配置」 说明仅需 user.name / email 与 remote，其余默认；再按该文件分步与用户确认。远程已配置且只做日常同步时可不读。

7. 能力边界（本 skill 不含）

批量重构全库链接、Canvas（.canvas）自动改写、Dataview 查询执行、Obsidian 插件设置修改——有需求时再单独约定。已采用 vault-sync-sop.md 时合并策略以该文件为准，不与此条冲突。