Obsidian

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

Pitfalls

-

-

Verification

-

-

-

-

1. 2. 3.

IO_CONTRACT

• input: request: str, context: dict — 用户请求描述、上下文信息
• output: result: dict — 技能执行结果（结构因技能而异）

对应原则：P2（机械原子暴露输入输出规范）

Obsidian Vault

Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, adding wikilinks, and initializing project knowledge bases.

Covers two tiers of work:

• Tier 1: Note ops — read, search, create, edit individual notes within an existing vault.
• Tier 2: Vault init — initialize a directory as an Obsidian knowledge base with MOC structure, frontmatter, symlinks to source files, and sync scripts.

Vault path

Use a known or resolved vault path before calling file tools.

The documented vault-path convention is the OBSIDIAN_VAULT_PATH environment variable, for example from ~/.hermes/.env. If it is unset, use ~/Documents/Obsidian Vault.

File tools do not expand shell variables. Do not pass paths containing $OBSIDIAN_VAULT_PATH to read_file, write_file, patch, or search_files; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.

If the vault path is unknown, terminal is acceptable for resolving OBSIDIAN_VAULT_PATH or checking whether the fallback path exists. Once the path is known, switch back to file tools.

Read a note

Use read_file with the resolved absolute path to the note. Prefer this over cat because it provides line numbers and pagination.

List notes

Use search_files with target: "files" and the resolved vault path. Prefer this over find or ls.

• To list all markdown notes, use pattern: "*.md" under the vault path.
• To list a subfolder, search under that subfolder's absolute path.

Search

Use search_files for both filename and content searches. Prefer this over grep, find, or ls.

• For filenames, use search_files with target: "files" and a filename pattern.
• For note contents, use search_files with target: "content", the content regex as pattern, and file_glob: "*.md" when you want to restrict matches to markdown notes.

Create a note

Use write_file with the resolved absolute path and the full markdown content. Prefer this over shell heredocs or echo because it avoids shell quoting issues and returns structured results.

Append to a note

Prefer a native file-tool workflow when it is not awkward:

• Read the target note with read_file.
• Use patch for an anchored append when there is stable context, such as adding a section after an existing heading or appending before a known trailing block.
• Use write_file when rewriting the whole note is clearer than constructing a fragile patch.

For an anchored append with patch, replace the anchor with the anchor plus the new content.

For a simple append with no stable context, terminal is acceptable if it is the clearest safe option.

Targeted edits

Use patch for focused note changes when the current content gives you stable context. Prefer this over shell text rewriting.

Vault setup — convert a code/research repo into an Obsidian knowledge base

For converting an existing project directory into an Obsidian knowledge base, see:

• references/vault-setup-workflow.md — class-level workflow

Related files

• references/vault-setup-workflow.md — full vault setup workflow

Tier 2: Vault Initialization — 项目知识库搭建

当需要把现有项目目录变成可导航的 Obsidian 知识库时，按以下步骤。

何时使用

• 项目已有大量 .md、.tex、.pdf 文件需要组织
• 需要跨文档导航（图谱、反链、标签）
• 需要区分笔记层（分析/注释）和源文件层（原文）

步骤

Step 1: 添加 .obsidian/ 配置

// core-plugins.json — 启用图谱、反链、标签、文件搜索
{
  "core:backlink": true,
  "core:graph": true,
  "core:tag-pane": true,
  "core:search": true,
  "core:file-explorer": true,
  "core:command-palette": true
}

同时把 .obsidian/ 加入 .gitignore。

Step 2: 创建 MOC 索引链

在每个子目录建 _INDEX.md（Map of Content），形成可导航的入口：

项目根/
├── _INDEX.md              ← 总入口（快速链接到各区域）
├── docs/_INDEX.md          ← 文档区
├── skills/_INDEX.md        ← 技能/知识点区
├── papers/_INDEX.md        ← 论文笔记区
└── outputs/papers/_INDEX.md ← 原文源文件区

Step 3: 添加 YAML frontmatter

---
tags: [paper, iris, segmentation]
aliases: [中文名, English Alt Name]
---

Step 4: 添加参照链接

每个笔记末尾添加：

## 参照
- [[papers/_INDEX|📝 论文目录]]
- [[_INDEX|← 返回根 MOC]]

Step 5: 链接外部源文件

用符号链接将已有文件（TeX、PDF、数据）映射到 vault 内：

ln -s /path/to/source/dir outputs/papers/paper-name/

Step 6: 建立与 fact_store 的同步

在 scripts/ 下放同步脚本。核心逻辑：

• 扫描修改过的 .md 文件
• 提取 **key**: value、表格行、frontmatter tags
• 写入 fact_store SQLite 数据库
• 重建 FTS 索引

已知陷阱

• 不要直接复制源文件：使用符号链接保持源目录干净，且 Git 不跟踪 vault 元文件
• MOC 命名：_INDEX.md 的 _ 前缀让它在 Obsidian 文件浏览器中置顶
• Wikilink 中的空格：Obsidian wikilink 支持空格，但路径中有 '（单引号）时需用 \ 转义
• frontmatter tag 格式：tags: [a, b, c] 比 tags: a, b, c 更兼容

相关文件

• references/synthos-vault-init-2026-05-27.md — Synthos 知识库搭建实例

验证清单 · VERIFICATION

• Vault 路径已解析为具体绝对路径（不含 $OBSIDIAN_VAULT_PATH 未展开变量），含空格的路径也正确传递
• 文件操作用原生工具完成：read_file / write_file / patch / search_files 替代 cat / find / grep / ls
• 新建/编辑笔记的 YAML frontmatter 用数组格式 tags: [a, b, c]，wikilink 中的单引号已用 \ 转义
• 局部修改用 patch 锚定追加（有稳定上下文时），仅在整体重写更清晰时才用 write_file
• Vault 初始化后：各子目录存在 _INDEX.md（_ 前缀置顶），.obsidian/ 已加入 .gitignore
• 外部源文件（PDF/TeX）以符号链接映射进 vault 而非复制，链接目标可访问

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Obsidian

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [OBSI-001] 当需要访问 Obsidian 笔记文件时 → 优先使用 read_file、write_file 等原生文件工具而非 Shell 命令，以避免路径空格和引号转义问题
• [OBSI-002] 当 Vault 路径包含环境变量（如 $OBSIDIAN_VAULT_PATH）时 → 必须先通过 terminal 解析为具体的绝对路径，再传递给文件工具，因为文件工具不支持变量展开
• [OBSI-003] 当需要搜索笔记文件名或内容时 → 统一使用 search_files 工具（分别指定 target: "files" 或 target: "content"），替代 grep、find 或 ls
• [OBSI-004] 当需要对笔记进行局部修改且存在稳定上下文锚点时 → 使用 patch 工具进行锚定追加或替换，仅在重写整个笔记更清晰时才使用 write_file
• [OBSI-005] 当初始化项目知识库（Vault Init）时 → 在每个子目录创建以 _ 开头的 _INDEX.md 作为 MOC（内容地图），利用前缀使其在文件浏览器中置顶以实现快速导航
• [OBSI-006] 当需要将外部源文件（如 PDF、TeX）纳入 Vault 时 → 使用符号链接（symlink）映射源文件而非直接复制，以保持源目录整洁并避免 Git 跟踪冗余数据
• [OBSI-007] 当编写笔记的 YAML frontmatter 标签时 → 使用数组格式 tags: [a, b, c] 而非逗号分隔字符串，以确保更好的兼容性