obsidian-vault-crud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Vault CRUD

Obsidian Vault 增删改查（CRUD）

Status: Active Author: Richard Fremmerlid Domain: Obsidian Integration Depends On:

obsidian-markdown-mastery

(WP05)

状态： 已启用 作者： Richard Fremmerlid 领域： Obsidian 集成 依赖：

obsidian-markdown-mastery

(WP05)

Core Mandate

核心使命

This skill provides the disk I/O layer for all agent interactions with the Obsidian Vault. It does NOT handle syntax parsing (that belongs to

obsidian-markdown-mastery

). Instead, it ensures that every file write is:

Atomic — via POSIX
```
os.rename()
```
from a
```
.tmp
```
staging file
Locked — via an advisory
```
.agent-lock
```
file at the vault root
Conflict-aware — via
```
mtime
```
comparison before/after read
Lossless — via
```
ruamel.yaml
```
for frontmatter (never PyYAML)

本技能为所有与Obsidian Vault交互的Agent提供磁盘I/O层支持。它不负责语法解析（该功能属于

obsidian-markdown-mastery

），而是确保每一次文件写入都满足以下要求：

原子性——通过POSIX的
```
os.rename()
```
方法，从
```
.tmp
```
临时文件重命名实现
锁定机制——通过库根目录下的
```
.agent-lock
```
建议性锁定文件实现
冲突感知——通过读取前后的
```
mtime
```
（修改时间）对比实现
无损性——使用
```
ruamel.yaml
```
处理前置元数据（绝不使用PyYAML）

Available Commands

可用命令

Read a Note

读取笔记

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py read --file <path>

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py read --file <path>

Create a Note

创建笔记

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py create --file <path> --content <text> [--frontmatter key=value ...]

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py create --file <path> --content <text> [--frontmatter key=value ...]

Update a Note

更新笔记

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py update --file <path> --content <text>

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py update --file <path> --content <text>

Append to a Note

追加内容到笔记

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py append --file <path> --content <text>

bash

python plugins/obsidian-integration/skills/obsidian-vault-crud/scripts/vault_ops.py append --file <path> --content <text>

Safety Guarantees

安全保障

Atomic Write Protocol

原子写入协议

Write content to
```
<target>.agent-tmp
```
Verify the
```
.agent-tmp
```
file was written completely

os.rename('<target>.agent-tmp', '<target>')

— atomic on POSIX

If any step fails, the
```
.agent-tmp
```
is cleaned up

将内容写入
```
<target>.agent-tmp
```
临时文件
验证
```
.agent-tmp
```
文件已完全写入
```
os.rename('<target>.agent-tmp', '<target>')
```
— 在POSIX系统上此操作是原子性的
若任意步骤失败，自动清理
```
.agent-tmp
```
文件

Advisory Lock Protocol

建议性锁定协议

Before any write batch: create
```
<vault_root>/.agent-lock
```
After write batch completes: remove
```
.agent-lock
```
Other agents check for
```
.agent-lock
```
before writing
This is advisory (does not block Obsidian UI)

在任意批量写入操作前：创建
```
<vault_root>/.agent-lock
```
文件
批量写入操作完成后：删除
```
.agent-lock
```
文件
其他Agent在写入前会检查
```
.agent-lock
```
文件
此为建议性锁定（不会阻塞Obsidian界面）

Concurrent Edit Detection

并发编辑检测

Capture
```
os.stat(file).st_mtime
```
before reading
Before writing, check
```
st_mtime
```
again
If mtime changed → another process edited the file → ABORT

读取前记录
```
os.stat(file).st_mtime
```
（文件修改时间）
写入前再次检查
```
st_mtime
```
若修改时间发生变化→说明其他进程已编辑该文件→终止操作

Frontmatter Handling

前置元数据处理

Uses
```
ruamel.yaml
```
(NOT
```
PyYAML
```
) to preserve comments, indentation, and array styles
Ensures Dataview and Obsidian Properties remain intact

使用
```
ruamel.yaml
```
（而非
```
PyYAML
```
）来保留注释、缩进和数组格式
确保Dataview和Obsidian属性保持完整