obsidian-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Init (Vault Onboarding)

Obsidian 初始化（Vault 接入）

Status: Active Author: Richard Fremmerlid Domain: Obsidian Integration

状态： 活跃 作者： Richard Fremmerlid 领域： Obsidian 集成

Purpose

用途

This skill is the entry point for any project adopting Obsidian. It handles:

Verifying (and guiding installation of) prerequisites
Initializing the vault configuration
Setting up exclusion filters
Validating the vault is ready for agent operations

本技能是所有采用Obsidian的项目的入口点，负责处理以下事项：

校验（并指导安装）前置依赖
初始化Vault配置
配置排除过滤器
校验Vault已就绪，可支持Agent操作

Phase 1: Prerequisites Installation

阶段1：前置依赖安装

1.1 Obsidian Desktop Application (Required)

1.1 Obsidian 桌面应用（必填）

The Obsidian desktop app must be installed on the host machine. It is the visual interface for browsing, editing, and viewing the Graph and Canvas.

macOS (Homebrew):

bash

brew install --cask obsidian

Manual Download:

https://obsidian.md/download

Verify:

bash

ls /Applications/Obsidian.app

主机上必须安装Obsidian桌面应用，它是用于浏览、编辑内容，查看关系图和Canvas的可视化界面。

macOS (Homebrew 安装)：

bash

brew install --cask obsidian

手动下载：

https://obsidian.md/download

校验安装：

bash

ls /Applications/Obsidian.app

1.2 Obsidian CLI v1.12+ (Recommended)

1.2 Obsidian CLI v1.12+（推荐）

The official CLI communicates with a running Obsidian instance via IPC singleton lock. It enables programmatic vault operations (read, search, backlinks, properties).

npm (global install):

bash

npm install -g obsidian-cli

Verify:

bash

obsidian --version

Note: The CLI requires an active Obsidian Desktop instance to communicate with. It operates in "silent" mode by default. For headless/CI environments where Obsidian is not running, our
vault_ops.py
(from
obsidian-vault-crud
) handles direct filesystem operations without requiring the CLI.

官方CLI通过IPC单例锁与运行中的Obsidian实例通信，支持程序化的Vault操作（读取、搜索、反向链接、属性管理）。

npm 全局安装：

bash

npm install -g obsidian-cli

校验安装：

bash

obsidian --version

注意：CLI需要与活跃的Obsidian桌面实例通信，默认以「静默模式」运行。对于未运行Obsidian的无界面/CI环境，可以使用
obsidian-vault-crud
中的
vault_ops.py
直接操作文件系统，无需依赖CLI。

1.3 ruamel.yaml (Required for CRUD Operations)

1.3 ruamel.yaml（CRUD操作必填）

Lossless YAML frontmatter handling requires

ruamel.yaml

bash

pip install ruamel.yaml

实现YAML frontmatter的无损处理需要依赖

ruamel.yaml

：

bash

pip install ruamel.yaml

1.4 Optional Community Plugins

1.4 可选社区插件

For advanced vault features, install these from within the Obsidian app:

Plugin	Purpose	Required For
Dataview	Database-style queries over frontmatter	Structured metadata queries
Canvas (built-in)	Visual boards with JSON Canvas spec	`obsidian-canvas-architect` skill
Bases	Table/grid/card views from YAML	`obsidian-bases-manager` skill

如需使用高级Vault功能，可以在Obsidian应用内安装以下插件：

插件	用途	所需场景
Dataview	对frontmatter执行数据库风格查询	结构化元数据查询
Canvas (内置)	符合JSON Canvas规范的可视化看板	`obsidian-canvas-architect` 技能
Bases	基于YAML生成表格/网格/卡片视图	`obsidian-bases-manager` 技能

Phase 2: Vault Initialization

阶段2：Vault 初始化

Interactive Init

交互式初始化

bash

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py --vault-root <path>

bash

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py --vault-root <path>

With Custom Exclusions

自定义排除规则

bash

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py \
  --vault-root <path> \
  --exclude "custom_dir/" "*.tmp"

bash

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py \
  --vault-root <path> \
  --exclude "custom_dir/" "*.tmp"

Validate Only (No Changes)

仅校验（不做修改）

bash

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py --vault-root <path> --validate-only

bash

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py --vault-root <path> --validate-only

What It Does

执行逻辑

Validates the target directory exists and contains
```
.md
```
files
Creates the
```
.obsidian/
```
configuration directory (if not present)
Writes
```
app.json
```
with sensible exclusion filters for developer repos
Updates
```
.gitignore
```
to exclude
```
.obsidian/
```
(user-specific config)
Reports next steps for opening the vault in the Obsidian app

校验目标目录存在且包含
```
.md
```
文件
创建
```
.obsidian/
```
配置目录（若不存在）
写入适配开发者仓库的合理排除规则到
```
app.json
```
更新
```
.gitignore
```
排除
```
.obsidian/
```
（用户专属配置）
提示在Obsidian应用中打开Vault的后续步骤

Phase 3: Exclusion Configuration

阶段3：排除规则配置

Default Exclusions

默认排除规则

Pattern	Reason
`node_modules/`	NPM dependencies
`.worktrees/`	Git worktree isolation
`.vector_data/`	ChromaDB binary data
`.git/`	Git internals
`venv/`	Python virtual environments
`__pycache__/`	Python bytecode cache
`*.json`	Data/config files (not knowledge)
`*.jsonl`	Export payloads
`learning_package_snapshot.md`	Machine-generated bundle
`bootstrap_packet.md`	Machine-generated bundle
`learning_debrief.md`	Machine-generated bundle
`*_packet.md`	Audit/review bundles
`*_digest.md`	Context digests
`dataset_package/`	Export artifacts

匹配模式	原因
`node_modules/`	NPM依赖目录
`.worktrees/`	Git工作树隔离目录
`.vector_data/`	ChromaDB二进制数据
`.git/`	Git内部文件
`venv/`	Python虚拟环境
`__pycache__/`	Python字节码缓存
`*.json`	数据/配置文件（非知识内容）
`*.jsonl`	导出负载文件
`learning_package_snapshot.md`	机器生成的打包文件
`bootstrap_packet.md`	机器生成的打包文件
`learning_debrief.md`	机器生成的打包文件
`*_packet.md`	审计/评审打包文件
`*_digest.md`	上下文摘要文件
`dataset_package/`	导出产物目录

Why Exclude Machine-Generated Files?

为什么要排除机器生成的文件？

These are giant concatenated snapshots produced by bundler/distiller scripts. Indexing them in Obsidian would pollute the graph with thousands of false backlinks pointing into machine-generated text, not human-authored knowledge.

这些是打包/蒸馏脚本生成的大型拼接快照，在Obsidian中索引它们会在关系图中生成数千条错误反向链接，指向机器生成的文本而非人类创作的知识内容。

Phase 4: Post-Init Steps

阶段4：初始化后步骤

Open Obsidian → Click "Open Folder as Vault" → Select vault root
Verify indexing → Check that
```
01_PROTOCOLS/
```
,
```
ADRs/
```
, etc. appear in sidebar
Test wikilinks → Click any
```
[[link]]
```
to confirm navigation works
Set VAULT_PATH →
```
export VAULT_PATH=/path/to/vault
```

打开Obsidian → 点击「Open Folder as Vault」 → 选择Vault根目录
校验索引 → 确认
```
01_PROTOCOLS/
```
、
```
ADRs/
```
等目录出现在侧边栏
测试wikilink → 点击任意
```
[[link]]
```
确认跳转功能正常
设置VAULT_PATH →
```
export VAULT_PATH=/path/to/vault
```

Portability Note

可移植性说明

This skill is project-agnostic. It works on any Git repository with markdown files. The exclusion filters are sensible defaults for developer projects. When reusing this plugin in other projects, simply run the init script with the new project's root path.

本技能不绑定具体项目，适用于所有包含Markdown文件的Git仓库，排除规则是适配开发者项目的通用默认值。在其他项目中复用本插件时，只需传入新项目根路径运行初始化脚本即可。

Quick Reference: Full Install Sequence

快速参考：完整安装流程

bash

undefined

bash

undefined

1. Install prerequisites

1. 安装前置依赖

brew install --cask obsidian # Desktop app npm install -g obsidian-cli # CLI tools pip install ruamel.yaml # Lossless YAML

brew install --cask obsidian # 桌面应用 npm install -g obsidian-cli # CLI工具 pip install ruamel.yaml # 无损YAML处理库

2. Initialize vault

2. 初始化Vault

python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py
--vault-root /path/to/your/project

3. Set environment variable

3. 设置环境变量

export VAULT_PATH=/path/to/your/project

4. Open in Obsidian app

4. 打开Obsidian应用

open /Applications/Obsidian.app

undefined

open /Applications/Obsidian.app

undefined