doc-vault-save

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vault Save

Vault保存

Persist structured content from conversation to an Obsidian vault. Handles content detection, frontmatter generation, folder routing, deduplication, wikilink injection, and re-indexing.

This skill does NOT do research. It only persists content already in the conversation.

将会话中的结构化内容持久化到Obsidian vault，支持内容检测、frontmatter生成、文件夹路由、去重、wikilink注入和重新索引。

本技能不执行研究工作，仅持久化会话中已有的内容。

Prerequisites

前置要求

Skill	Required	Purpose
doc-obsidian	Yes	Vault CRUD via notesmd-cli + search via qmd

技能	是否必填	用途
doc-obsidian	是	通过notesmd-cli实现vault的增删改查，通过qmd实现搜索功能

Workflow

工作流

Step 0: Setup → Step 1: Detect Content → Step 2: Name & Route → Step 3: Dedup Check → Step 4: Build Note → Step 5: Save → Step 6: Wikilinks → Step 7: Re-index & Confirm

步骤0: 初始化设置 → 步骤1: 内容检测 → 步骤2: 命名与路由 → 步骤3: 去重检查 → 步骤4: 构建笔记 → 步骤5: 保存 → 步骤6: 生成Wikilink → 步骤7: 重新索引与确认

Step 0: Setup

步骤0: 初始化设置

Run before every save:

bash

undefined

每次保存前运行：

bash

undefined

1. Vault path (MANDATORY)

1. Vault路径（必填）

VAULT=$(notesmd-cli print-default --path-only)

2. Verify qmd available

2. 验证qmd可用

qmd status


If either fails, stop and tell the user to set up doc-obsidian first.

qmd status


如果任意命令执行失败，停止操作并告知用户先完成doc-obsidian的设置。

Step 1: Detect Content Type

步骤1: 检测内容类型

Examine conversation context. Use the FIRST matching rule:

Type	Detection	Signals
res-deep	Has header with `Framework:` field, has `Research Statistics` footer	COMPARISON / LANDSCAPE / DEEP_DIVE / DECISION
res-price-compare	Has price tables with PLN/EUR, has `TOP 3` or `PURCHASE RECOMMENDATION`	Shop comparison tables, warranty analysis
generic	Everything else	User-provided text, pasted content, dictated notes

Explicit override: User can force type with "save as research", "save as price comparison", "save as note".

检查会话上下文，使用第一个匹配的规则：

类型	检测规则	特征信号
res-deep	包含带 `Framework:` 字段的头部，有 `Research Statistics` 页脚	COMPARISON / LANDSCAPE / DEEP_DIVE / DECISION
res-price-compare	包含PLN/EUR计价的价格表，有 `TOP 3` 或 `PURCHASE RECOMMENDATION` 标识	商品对比表格、保修分析
generic	其他所有内容	用户提供的文本、粘贴的内容、口述笔记

显式覆盖： 用户可通过"save as research"、"save as price comparison"、"save as note"强制指定内容类型。

Step 2: Name & Route

步骤2: 命名与路由

Note Naming

笔记命名

Type	Pattern	Example
res-deep	`{topic-slug}` from Topic field	`agent-swarms-hardware-decision`
res-price-compare	`{product-slug}-pricing`	`mac-studio-m4-max-128gb-pricing`
generic	`{topic-slug}` from first heading or user instruction	`kubernetes-setup-notes`

Rules: kebab-case, lowercase, no special characters, max 60 chars. If user specifies a name, use it.

类型	命名规则	示例
res-deep	取自Topic字段的 `{topic-slug}`	`agent-swarms-hardware-decision`
res-price-compare	`{product-slug}-pricing`	`mac-studio-m4-max-128gb-pricing`
generic	取自第一个标题或用户指令的 `{topic-slug}`	`kubernetes-setup-notes`

规则：kebab-case格式、全小写、无特殊字符、最长60字符。如果用户指定了名称则使用用户提供的名称。

Folder Routing

文件夹路由

Type	Default Folder	Override
res-deep	`research/`	"save to {folder}"
res-price-compare	`research/`	"save to {folder}"
generic	vault root	"save to {folder}"

Load

references/folder-routing.md

for customization and sub-routing rules.

类型	默认文件夹	自定义规则
res-deep	`research/`	"save to {folder}"
res-price-compare	`research/`	"save to {folder}"
generic	vault根目录	"save to {folder}"

加载

references/folder-routing.md

获取自定义规则和子路由规则。

Confirm Before Saving

保存前确认

Save: research/agent-swarms-hardware-decision
Type: res-deep (DECISION framework)
Proceed? [Y / change name / change folder]

Skip confirmation if user already specified name and location.

保存路径: research/agent-swarms-hardware-decision
类型: res-deep (DECISION framework)
是否继续？ [Y / 修改名称 / 修改文件夹]

如果用户已经指定了名称和存储位置则跳过确认。

Step 3: Dedup Check

步骤3: 去重检查

bash

undefined

bash

undefined

Keyword search on the topic

按主题搜索关键词

qmd search "{topic}" --json -n 5

Check exact name match

检查是否有完全匹配的名称

notesmd-cli print "{folder}/{note-name}" 2>/dev/null

undefined

notesmd-cli print "{folder}/{note-name}" 2>/dev/null

undefined

Decision Matrix

决策矩阵

Existing Note	Action
No match	Create new → Step 4
Exact name match	Ask: overwrite / append / create with suffix (-2, -3)
Similar topic, different name	Show matches, ask: create alongside / overwrite existing / append to existing

Show found notes with dates so user can judge recency:

Found existing notes on this topic:
1. research/agent-swarms-analysis (2026-02-20, 43 sources)
2. research/ai-agents-hardware (2026-02-15, 28 sources)
Action: [create new / overwrite #1 / append to #1 / cancel]

现有笔记情况	执行动作
无匹配	创建新笔记 → 步骤4
名称完全匹配	询问用户：覆盖 / 追加 / 带后缀创建新笔记 (-2, -3)
主题相似但名称不同	展示匹配结果，询问用户：新建并存 / 覆盖现有笔记 / 追加到现有笔记

展示找到的笔记时附带日期，方便用户判断新旧：

找到该主题的现有笔记：
1. research/agent-swarms-analysis (2026-02-20, 43个来源)
2. research/ai-agents-hardware (2026-02-15, 28个来源)
操作选择: [新建 / 覆盖#1 / 追加到#1 / 取消]

Step 4: Build Note

步骤4: 构建笔记

Frontmatter

Load

references/frontmatter-schemas.md

for full schemas. Summary:

res-deep:

yaml

---
type: research
topic: {Topic from header}
date: {YYYY-MM-DD}
sources: {N}
framework: {comparison|landscape|deep-dive|decision}
depth: {quick|default|deep}
status: complete
tags: [{domain-tags}, research]
---

Use

type: decision

when framework is DECISION.

res-price-compare:

yaml

---
type: price-comparison
product: {Full product name}
date: {YYYY-MM-DD}
market: pl
status: complete
tags: [{product-category}, price-comparison]
---

generic:

yaml

---
type: note
topic: {From heading or user input}
date: {YYYY-MM-DD}
status: draft
tags: [{auto-derived}]
---

加载

references/frontmatter-schemas.md

获取完整schema，摘要如下：

res-deep:

yaml

---
type: research
topic: {头部提取的Topic}
date: {YYYY-MM-DD}
sources: {来源数量}
framework: {comparison|landscape|deep-dive|decision}
depth: {quick|default|deep}
status: complete
tags: [{领域标签}, research]
---

当framework为DECISION时使用

type: decision

。

res-price-compare:

yaml

---
type: price-comparison
product: {完整产品名称}
date: {YYYY-MM-DD}
market: pl
status: complete
tags: [{产品分类}, price-comparison]
---

generic:

yaml

---
type: note
topic: {来自标题或用户输入}
date: {YYYY-MM-DD}
status: draft
tags: [{自动推导标签}]
---

Tag Generation

标签生成

Auto-derive 2-5 tags:

Content type tag:
```
research
```
,
```
price-comparison
```
, or
```
note
```
Domain tags: key nouns from topic (e.g.,
```
ai
```
,
```
agents
```
,
```
hardware
```
)
User-specified tags if provided

自动推导2-5个标签：

内容类型标签：
```
research
```
、
```
price-comparison
```
或
```
note
```
领域标签：主题中的核心名词（例如
```
ai
```
、
```
agents
```
、
```
hardware
```
）
用户指定的标签（如有）

Body Construction

正文构建

res-deep: Strip the YAML-like header block (

Framework:

Topic:

Depth:

Sources:

Date:

lines) — that data moves to proper frontmatter. Keep everything else.

res-price-compare: Keep full report body. Strip any file-export artifacts.

generic: Use content as-is. Add

# {Topic}

if no heading exists.

res-deep： 移除类YAML头部块（

Framework:

Topic:

Depth:

Sources:

Date:

行），这些数据将迁移到frontmatter中，保留其余所有内容。

res-price-compare： 保留完整报告正文，移除所有文件导出的冗余内容。

generic： 保持内容原样，如果没有标题则添加

# {Topic}

。

Step 5: Save

步骤5: 保存

Create Mode (default)

创建模式（默认）

bash

notesmd-cli create "{folder}/{note-name}" --content "{frontmatter + body}" --overwrite

Use

--overwrite

only after Step 3 confirmed no conflict or user approved.

bash

notesmd-cli create "{folder}/{note-name}" --content "{frontmatter + 正文}" --overwrite

仅当步骤3确认无冲突或用户同意覆盖时才使用

--overwrite

参数。

Append Mode

追加模式

bash

notesmd-cli create "{folder}/{note-name}" --content "\n\n---\n\n## Update: {YYYY-MM-DD}\n\n{new content}" --append

bash

notesmd-cli create "{folder}/{note-name}" --content "\n\n---\n\n## 更新: {YYYY-MM-DD}\n\n{新内容}" --append

Update Mode (surgical edit)

更新模式（精准编辑）

For updating a specific section of an existing note:

bash

undefined

用于更新现有笔记的特定章节：

bash

undefined

1. Read current note

1. 读取当前笔记内容

notesmd-cli print "{folder}/{note-name}"

2. Edit via vault path

2. 通过vault路径编辑

VAULT=$(notesmd-cli print-default --path-only)

Use Edit tool on "$VAULT/{folder}/{note-name}.md"

对"$VAULT/{folder}/{note-name}.md"使用编辑工具

undefined

undefined

Large Content Fallback

大内容 fallback 方案

If content exceeds ~100KB,

notesmd-cli create --content

may hit shell argument limits. Use the Write tool directly:

bash

VAULT=$(notesmd-cli print-default --path-only)

如果内容超过约100KB，

notesmd-cli create --content

可能会触发shell参数长度限制，直接使用写入工具：

bash

VAULT=$(notesmd-cli print-default --path-only)

Write tool → "$VAULT/{folder}/{note-name}.md"

写入工具 → "$VAULT/{folder}/{note-name}.md"

undefined

undefined

Update Date After Save

保存后更新日期

bash

notesmd-cli fm "{folder}/{note-name}" --edit --key "date" --value "{YYYY-MM-DD}"

bash

notesmd-cli fm "{folder}/{note-name}" --edit --key "date" --value "{YYYY-MM-DD}"

Step 6: Wikilinks

步骤6: Wikilink关联

Find related notes and add a

Related:

block after frontmatter.

查找相关笔记，在frontmatter后添加

Related:

块。

Find Related

查找相关笔记

bash

qmd vsearch "{topic}" --json -n 10

Filter: exclude the note just saved, exclude score < 0.3, keep top 3-5.

bash

qmd vsearch "{topic}" --json -n 10

过滤规则：排除刚保存的笔记、排除得分<0.3的笔记、保留前3-5条。

Insert Related Line

插入关联行

After frontmatter closing

---

, before first

heading:

markdown

Related: [[note-a]] | [[note-b]] | [[note-c]]

If the note already has a

Related:

line, replace it (don't duplicate).

在frontmatter的闭合

---

之后、第一个

标题之前：

markdown

Related: [[note-a]] | [[note-b]] | [[note-c]]

如果笔记已有

Related:

行，直接替换（避免重复）。

Implementation

实现方式

bash

notesmd-cli print "{folder}/{note-name}"
VAULT=$(notesmd-cli print-default --path-only)

bash

notesmd-cli print "{folder}/{note-name}"
VAULT=$(notesmd-cli print-default --path-only)

Use Edit tool to insert/replace Related line

使用编辑工具插入/替换Related行

undefined

undefined

Step 7: Re-index & Confirm

步骤7: 重新索引与确认

bash

qmd update && qmd embed

bash

qmd update && qmd embed

Confirmation Output

确认输出

Saved: [[{note-name}]]
Path: {folder}/{note-name}
Type: {type}
Tags: {tags}
Related: [[note-a]], [[note-b]], [[note-c]]
Vault re-indexed: Yes

已保存: [[{note-name}]]
路径: {folder}/{note-name}
类型: {type}
标签: {tags}
关联笔记: [[note-a]], [[note-b]], [[note-c]]
Vault已重新索引: 是

Modes

模式

Mode	Trigger	Behavior
save (default)	"save to vault", "vault save"	Full workflow: Steps 0-7
quick	"quick save", "save, no dedup"	Skip Steps 3 + 6 (no dedup, no wikilinks)
update	"update vault note", "add to existing"	Surgical edit of existing note (Step 5 update mode)
dry-run	"where would this go?", "preview save"	Show name, folder, frontmatter, related notes — no save

模式	触发词	行为
save（默认）	"save to vault", "vault save"	完整工作流：步骤0-7
quick	"quick save", "save, no dedup"	跳过步骤3和6（不去重、不生成wikilink）
update	"update vault note", "add to existing"	精准编辑现有笔记（步骤5的更新模式）
dry-run	"where would this go?", "preview save"	展示名称、文件夹、frontmatter、相关笔记 - 不执行保存

Constraints

约束

DO:

Always run Step 0 first
Always detect content type before building frontmatter
Always check for duplicates before creating (unless quick mode)
Always re-index after saving
Resolve vault path dynamically via
```
notesmd-cli print-default --path-only
```
Present name + folder for user approval before saving
Read notes before editing — never guess content

DON'T:

Do research — this skill only persists content
Hardcode vault paths
Create notes without frontmatter
Skip dedup check (unless quick mode)
Duplicate what doc-daily-digest does
Modify notes from other skills without user approval
Save empty or stub notes

必须遵守：

始终优先运行步骤0
构建frontmatter前必须先检测内容类型
创建前必须检查重复（快速模式除外）
保存后必须重新索引
通过
```
notesmd-cli print-default --path-only
```
动态获取vault路径
保存前向用户展示名称和文件夹等待确认
编辑前先读取笔记内容 - 永远不要猜测内容

禁止操作：

执行研究工作 - 本技能仅持久化内容
硬编码vault路径
创建无frontmatter的笔记
跳过去重检查（快速模式除外）
重复doc-daily-digest的功能
未经用户同意修改其他技能生成的笔记
保存空笔记或占位笔记

References

参考文件

```
references/frontmatter-schemas.md
```
— Full schemas per content type, field extraction rules, tag generation, validation
```
references/folder-routing.md
```
— Routing rules, user overrides, sub-routing, conflict resolution

```
references/frontmatter-schemas.md
```
- 各内容类型的完整schema、字段提取规则、标签生成规则、校验规则
```
references/folder-routing.md
```
- 路由规则、用户自定义规则、子路由、冲突解决规则