doc-vault-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vault Project

Manage multi-note research projects in an Obsidian vault with phased subdirectory structure.

借助分阶段子目录结构在Obsidian vault中管理由多条笔记组成的研究项目。

Prerequisites

前置要求

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

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

Directory Structure

目录结构

projects/{project-slug}/
├── _index.md              # MOC: status, component links, linked research
├── concept/               # Problem definition, threat models, requirements
├── research/              # Deep dives per component, tech evaluation
├── design/                # Architecture, API design, data models
└── implementation/        # Build plans, code refs, test plans

Projects live in

projects/

(top-level). Separate from

research/

(knowledge).

Four phases are always created. Empty dirs signal "not started yet."

projects/{project-slug}/
├── _index.md              # MOC: 状态、组件链接、关联研究
├── concept/               # 问题定义、威胁模型、需求
├── research/              # 各组件深度调研、技术评估
├── design/                # 架构、API设计、数据模型
└── implementation/        # 构建计划、代码参考、测试计划

项目存放在顶级

projects/

目录下，与存储知识的

research/

目录相互独立。

默认创建四个阶段的目录，空目录代表该阶段尚未启动。

Step 0: Setup

步骤0：初始化配置

Run before every operation:

bash

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

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

每次操作前都需要执行：

bash

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

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

Commands

命令

init — Scaffold New Project

init — 搭建新项目脚手架

Trigger: "create project {name}", "new project {name}", "project init {name}"

触发词： "create project {name}", "new project {name}", "project init {name}"

Workflow

工作流程

Parse project name → kebab-case slug (max 40 chars)
Check if
```
projects/{slug}/
```
exists — if yes, abort and show existing project
Create directory structure:

bash

VAULT=$(notesmd-cli print-default --path-only)
mkdir -p "$VAULT/projects/{slug}/concept"
mkdir -p "$VAULT/projects/{slug}/research"
mkdir -p "$VAULT/projects/{slug}/design"
mkdir -p "$VAULT/projects/{slug}/implementation"

Load

references/index-template.md

and

references/frontmatter-schemas.md

Build
```
_index.md
```
with project frontmatter and empty status table
Write
```
_index.md
```
:

bash

undefined

解析项目名称，转换为kebab-case格式的slug（最多40个字符）
检查
```
projects/{slug}/
```
是否存在，若存在则终止操作并展示现有项目信息
创建目录结构：

bash

VAULT=$(notesmd-cli print-default --path-only)
mkdir -p "$VAULT/projects/{slug}/concept"
mkdir -p "$VAULT/projects/{slug}/research"
mkdir -p "$VAULT/projects/{slug}/design"
mkdir -p "$VAULT/projects/{slug}/implementation"

加载

references/index-template.md

和

references/frontmatter-schemas.md

文件

构建包含项目frontmatter和空状态表格的
```
_index.md
```
文件
写入
```
_index.md
```
：

bash

undefined

Use Write tool → "$VAULT/projects/{slug}/_index.md"

使用写入工具 → "$VAULT/projects/{slug}/_index.md"


7. Re-index: `qmd update && qmd embed`
8. Confirm:

Created: [[{slug}]] Path: projects/{slug}/ Phases: concept/ research/ design/ implementation/ Components: 0

undefined


7. 重新索引：`qmd update && qmd embed`
8. 确认信息：

Created: [[{slug}]] Path: projects/{slug}/ Phases: concept/ research/ design/ implementation/ Components: 0

undefined

add — Add Component Note

add — 添加组件笔记

Trigger: "add {note} to project {name}", "project add {note} to {phase}"

触发词： "add {note} to project {name}", "project add {note} to {phase}"

Workflow

工作流程

Identify project slug and target phase (concept/research/design/implementation)
If phase not specified, infer from content:
- Problem/threat/requirement →
```
concept
```
- Deep dive/evaluation/comparison →
```
research
```
- Architecture/API/data model →
```
design
```
- Plan/code/test/deploy →
```
implementation
```
If ambiguous, ask the user
Generate note slug (kebab-case, max 60 chars)
Check for duplicates in the phase directory
Load frontmatter schema from
```
references/frontmatter-schemas.md
```
Build component note with
```
type: project-component
```
frontmatter
Save:

bash

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

识别项目slug和目标阶段（concept/research/design/implementation）
若未指定阶段，从内容推断：
- 问题/威胁/需求 →
```
concept
```
- 深度调研/评估/对比 →
```
research
```
- 架构/API/数据模型 →
```
design
```
- 计划/代码/测试/部署 →
```
implementation
```
若存在歧义，询问用户确认
生成笔记slug（kebab-case格式，最多60个字符）
检查阶段目录下是否存在重复文件
从
```
references/frontmatter-schemas.md
```
加载frontmatter schema
构建包含
```
type: project-component
```
frontmatter的组件笔记
保存：

bash

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

Write tool → "$VAULT/projects/{project-slug}/{phase}/{note-slug}.md"

使用写入工具 → "$VAULT/projects/{project-slug}/{phase}/{note-slug}.md"


9. Update `_index.md`:
   - Add wikilink under the correct phase section
   - Update status table counts
   - Update `components:` and `updated:` in frontmatter
10. Re-index: `qmd update && qmd embed`
11. Confirm:

Added: [[{note-slug}]] Path: projects/{project-slug}/{phase}/{note-slug} Phase: {phase} Status: pending Project components: {N}

undefined


9. 更新`_index.md`：
   - 在对应阶段板块下添加wiki链接
   - 更新状态表格计数
   - 更新frontmatter中的`components:`和`updated:`字段
10. 重新索引：`qmd update && qmd embed`
11. 确认信息：

Added: [[{note-slug}]] Path: projects/{project-slug}/{phase}/{note-slug} Phase: {phase} Status: pending Project components: {N}

undefined

status — Show Project Status

status — 展示项目状态

Trigger: "project status", "project status {name}", "how is project {name}"

触发词： "project status", "project status {name}", "how is project {name}"

Workflow

工作流程

If no project specified, list all projects:

bash

VAULT=$(notesmd-cli print-default --path-only)
ls "$VAULT/projects/"

For a specific project, read
```
_index.md
```
frontmatter and list components:

bash

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

若未指定项目，列出所有项目：

bash

VAULT=$(notesmd-cli print-default --path-only)
ls "$VAULT/projects/"

针对指定项目，读取
```
_index.md
```
的frontmatter并列出组件：

bash

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

Read _index.md for project metadata

读取_index.md获取项目元数据

List files in each phase directory

列出每个阶段目录下的文件

Read frontmatter status from each component

读取每个组件的frontmatter状态


3. Display:

Project: {name} Status: {project-status} Updated: {date}

Phase	Component	Status
concept	[[threat-model]]	complete
concept	[[gap-analysis]]	in-progress
research	[[endpoint-security]]	pending
design	—	—
implementation	—	—

Progress: 1/3 complete

undefined


3. 展示内容：

Project: {name} Status: {project-status} Updated: {date}

阶段	组件	状态
concept	[[threat-model]]	complete
concept	[[gap-analysis]]	in-progress
research	[[endpoint-security]]	pending
design	—	—
implementation	—	—

Progress: 1/3 complete

undefined

link — Link Existing Research

link — 关联现有研究内容

Trigger: "link research to project {name}", "project link {note} to {name}"

触发词： "link research to project {name}", "project link {note} to {name}"

Workflow

工作流程

Identify project and target research notes
If no specific notes given, search for related research:

bash

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

Filter results: only notes in
```
research/
```
, exclude score < 0.3
Present candidates with scores, let user pick
Read project
```
_index.md
```
Add wikilinks under
```
### Linked Research
```
section:

markdown

undefined

识别目标项目和待关联的研究笔记
若未指定具体笔记，搜索相关研究内容：

bash

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

过滤结果：仅保留
```
research/
```
目录下的笔记，排除得分<0.3的内容
展示带得分的候选内容，让用户选择
读取项目的
```
_index.md
```
文件
在
```
### 关联研究
```
板块下添加wiki链接：

markdown

undefined

Linked Research

关联研究

[[existing-note]] — {brief relevance}


7. Do NOT move files — research stays in `research/`
8. Update `updated:` in frontmatter
9. Re-index: `qmd update && qmd embed`
10. Confirm:

Linked to [[{project}]]:

[[note-1]] — {relevance}
[[note-2]] — {relevance}

undefined

[[existing-note]] — {关联说明}


7. 不要移动文件，研究内容保留在`research/`目录下
8. 更新frontmatter中的`updated:`字段
9. 重新索引：`qmd update && qmd embed`
10. 确认信息：

Linked to [[{project}]]:

[[note-1]] — {关联说明}
[[note-2]] — {关联说明}

undefined

promote — Promote Research Topic to Project

promote — 将研究主题升级为项目

Trigger: "promote {topic} to project", "make {topic} a project"

触发词： "promote {topic} to project", "make {topic} a project"

Workflow

工作流程

Find existing research notes on the topic:

bash

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

Present candidates, let user confirm which notes relate
Run
```
init
```
to scaffold the project
Run
```
link
```
to wikilink the existing research notes
Optionally create initial component notes in
```
concept/
```
if the research already covers problem definition
Confirm:

Promoted: {topic} → [[{project}]]
Linked research: {N} notes
Components: {N} created

Promote does NOT move existing notes. It creates a project that references them.

查找该主题下的现有研究笔记：

bash

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

展示候选内容，让用户确认哪些笔记相关
执行
```
init
```
命令搭建项目脚手架
执行
```
link
```
命令关联现有研究笔记
如果现有研究已经覆盖问题定义，可选择在
```
concept/
```
目录下创建初始组件笔记
确认信息：

Promoted: {topic} → [[{project}]]
Linked research: {N} notes
Components: {N} created

升级操作不会移动现有笔记，只会创建一个引用这些笔记的新项目。

Constraints

约束

DO:

Always run Step 0 first
Always use fixed four phases (concept/research/design/implementation)
Always update
```
_index.md
```
after adding/linking components
Always re-index after changes
Resolve vault path dynamically via
```
notesmd-cli print-default --path-only
```
Keep research notes in
```
research/
```
— link, don't move
Read notes before editing

DON'T:

Create custom phases or skip phase directories
Move existing research notes into project directories
Create projects without
```
_index.md
```
Skip re-indexing
Hardcode vault paths
Auto-trigger — only respond to explicit project commands

应当遵守的规则：

始终先执行步骤0
始终使用固定的四个阶段（concept/research/design/implementation）
添加/关联组件后始终更新
```
_index.md
```
变更后始终重新索引
通过
```
notesmd-cli print-default --path-only
```
动态获取vault路径
研究笔记保留在
```
research/
```
目录下，仅关联不移动
编辑笔记前先读取原有内容

禁止操作：

创建自定义阶段或跳过阶段目录
将现有研究笔记移动到项目目录下
创建没有
```
_index.md
```
的项目
跳过重新索引步骤
硬编码vault路径
自动触发操作，仅响应明确的项目命令

References

参考

```
references/frontmatter-schemas.md
```
— Frontmatter for _index.md and component notes, field rules, status transitions
```
references/index-template.md
```
— _index.md scaffold template, status table update rules, linked research format

```
references/frontmatter-schemas.md
```
— _index.md和组件笔记的frontmatter、字段规则、状态流转说明
```
references/index-template.md
```
— _index.md脚手架模板、状态表格更新规则、关联研究格式说明