obs-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Agent Memory

Obsidian Agent 记忆库

You have access to a persistent Obsidian knowledge vault — a graph-structured memory that persists across sessions. Use it to orient yourself, look up architecture and component knowledge, and write back discoveries.

你可以访问一个持久化的Obsidian知识库——一个跨会话保存的图结构记忆系统。你可以用它来获取上下文、查询架构和组件知识，并将新发现的内容写回库中。

Vault Discovery

知识库发现

Resolve the vault path using this chain (first match wins):

Environment variable:
```
$OBSIDIAN_VAULT_PATH
```
Agent config reference: Parse the vault path from the agent's project or global config (look for "Obsidian Knowledge Vault" section with a path like
```
~/Documents/SomeName/
```
)
Default:
```
~/Documents/AgentMemory
```

Store the resolved path as

$VAULT

for all subsequent operations. Derive

$VAULT_NAME

basename "$VAULT"

for CLI calls.

Verify the vault exists by checking for

$VAULT/Home.md

. If the vault doesn't exist, inform the user and suggest running the

init

command to bootstrap a new vault from the bundled template.

通过以下优先级链解析知识库路径（匹配到第一个即停止）：

环境变量：
```
$OBSIDIAN_VAULT_PATH
```
Agent配置引用：从Agent的项目或全局配置中解析知识库路径（查找包含路径如
```
~/Documents/SomeName/
```
的“Obsidian Knowledge Vault”章节）
默认路径：
```
~/Documents/AgentMemory
```

将解析后的路径保存为

$VAULT

，用于后续所有操作。通过

basename "$VAULT"

生成

$VAULT_NAME

，供CLI调用使用。

通过检查

$VAULT/Home.md

文件是否存在来验证知识库是否可用。如果知识库不存在，告知用户并建议运行

init

命令，从捆绑模板引导创建新的知识库。

Session Start — Orientation

会话启动——上下文获取

At the start of every session, orient yourself with at most 2 operations:

每次会话开始时，最多执行2项操作来获取上下文：

Step 1: Read TODOs

步骤1：读取待办事项

CLI-first:

bash

obsidian vault=$VAULT_NAME tasks path="todos" todo verbose

Fallback: Read the file at

$VAULT/todos/Active TODOs.md

Know what's pending, in-progress, and recently completed.

优先使用CLI:

bash

obsidian vault=$VAULT_NAME tasks path="todos" todo verbose

备选方案：读取

$VAULT/todos/Active TODOs.md

文件。

了解待处理、进行中以及最近完成的事项。

Step 2: Detect current project and read its overview

步骤2：检测当前项目并读取项目概述

Auto-detect the project from the current working directory:

bash

basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $(pwd)

Then check if a matching project exists by listing files in

$VAULT/projects/*/

. Match the git repo name (or directory name) against project folder names. If a match is found, read the project overview at

$VAULT/projects/{matched-name}/{matched-name}.md

This project overview contains wikilinks to all components, patterns, architecture decisions, and domains. Do not read those linked notes yet — follow them on demand when the current task requires that context.

从当前工作目录自动检测项目：

bash

basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $(pwd)

然后通过列出

$VAULT/projects/*/

下的文件，检查是否存在匹配的项目。将git仓库名称（或目录名称）与项目文件夹名称进行匹配。如果找到匹配项，读取

$VAULT/projects/{matched-name}/{matched-name}.md

中的项目概述。

该项目概述包含指向所有组件、模式、架构决策和领域的维基链接。暂时不要读取这些链接的笔记——仅当当前任务需要相关上下文时再访问。

What NOT to read at session start

会话启动时禁止读取的内容

```
Home.md
```
(only if you're lost and can't find the project)
```
sessions/
```
(only if the user references prior work)
Domain indexes (only if you need cross-project knowledge)
Component notes (only when working on that component)

```
Home.md
```
（仅当你无法找到项目时再读取）
```
sessions/
```
（仅当用户提及过往工作时再读取）
领域索引（仅当你需要跨项目知识时再读取）
组件笔记（仅当你处理该组件时再读取）

Automatic Behaviors

自动行为

These behaviors apply to any agent using this skill. They do not require explicit commands.

以下行为适用于所有使用该工具的Agent，无需显式命令触发。

On session start

会话启动时

Auto-orient (TODOs + project overview) without being asked, following the Session Start procedure above. If the vault doesn't exist at the resolved path, inform the user and suggest running

init

无需用户请求，自动执行上下文获取操作（待办事项 + 项目概述），遵循上述会话启动流程。如果解析路径下不存在知识库，告知用户并建议运行

init

命令。

On session end signals

会话结束信号触发时

When the user says "done", "wrapping up", "that's it", "let's stop", or similar end-of-session language — offer to write a session summary. Don't auto-run; ask first: "Want me to write a session summary to the vault before we wrap up?"

当用户说出“done”“wrapping up”“that's it”“let's stop”等表示会话结束的语句时——主动询问用户是否需要写入会话总结。不要自动执行，先询问：“会话结束前，需要我将本次会话总结写入知识库吗？”

On component discovery

发现新组件时

When you deeply analyze a component that has no vault note — and the project has an active vault — offer to create a component note and infer relationships from imports and dependencies. Example: "I noticed there's no vault note for the AuthMiddleware component. Want me to create one and map its dependencies?"

当你深入分析一个在知识库中没有对应笔记的组件——且该项目有可用的知识库时——主动询问用户是否需要创建该组件的笔记，并从导入和依赖关系中推断关联。例如：“我注意到AuthMiddleware组件在知识库中没有对应笔记，需要我创建该笔记并映射其依赖关系吗？”

On first run

首次运行时

When the vault doesn't exist at any resolved path, guide the user through

init

, then auto-scaffold the current project if inside a git repo.

当所有解析路径下都不存在知识库时，引导用户运行

init

命令，若当前处于git仓库中，则自动为当前项目搭建知识库结构。

During Work — Graph Navigation

工作过程——图谱导航

Principle: Use CLI queries first, file reads second. The Obsidian CLI provides structured access to properties, links, backlinks, tags, and search — prefer these over reading entire files.

原则：优先使用CLI查询，其次再读取文件。 Obsidian CLI提供对属性、链接、反向链接、标签和搜索的结构化访问——优先使用这些方式，而非读取整个文件。

CLI-first lookups (preferred)

优先使用CLI查询

Use these CLI commands for targeted queries without consuming file-read tokens:

bash

undefined

使用以下CLI命令进行定向查询，无需消耗文件读取配额：

bash

undefined

Query a component's dependencies

查询组件的依赖项

obsidian vault=$VAULT_NAME property:read file="Component Name" name="depends-on"

Find what depends on a component

查询依赖某个组件的内容

obsidian vault=$VAULT_NAME property:read file="Component Name" name="depended-on-by" obsidian vault=$VAULT_NAME backlinks file="Component Name"

Find all outgoing links from a note

查询某条笔记的所有出站链接

obsidian vault=$VAULT_NAME links file="Component Name"

Find all notes of a type

查询所有指定类型的笔记

obsidian vault=$VAULT_NAME tag verbose name="component"

Search vault content

搜索知识库内容

obsidian vault=$VAULT_NAME search format=json query="search term" matches limit=10

Get note structure without full read

获取笔记结构而无需完整读取

obsidian vault=$VAULT_NAME outline file="Component Name"

Read a specific property

读取特定属性

obsidian vault=$VAULT_NAME property:read file="Component Name" name="key-files"


Where `$VAULT_NAME` is the vault folder name (basename of `$VAULT`).

obsidian vault=$VAULT_NAME property:read file="Component Name" name="key-files"


其中`$VAULT_NAME`是知识库文件夹名称（`$VAULT`的basename）。

File-read fallback (when CLI unavailable)

无法使用CLI时的备选方案（文件读取）

Fall back to file reads when the Obsidian CLI is not available:

Need to understand a component? The project overview links to it. Read that one note.
Need an architecture decision? The component note or project overview links to it. Follow the link.
Need cross-project knowledge? Component/pattern notes link to domain notes. Follow the link.
Need session history? Only read if you're stuck or the user references prior work.

当Obsidian CLI不可用时，退而读取文件：

需要了解组件？项目概述中包含指向它的链接，读取该笔记即可。
需要了解架构决策？组件笔记或项目概述中包含指向它的链接，访问该链接。
需要跨项目知识？组件/模式笔记中包含指向领域笔记的链接，访问该链接。
需要会话历史？仅当你遇到瓶颈或用户提及过往工作时再读取。

Frontmatter-first scanning

优先扫描前置元数据

When you need to scan multiple notes to find the right one, read just the first ~10 lines of each file. The

tags

project

type

, and

status

fields in the frontmatter tell you if the note is relevant before reading the full body.

当你需要扫描多条笔记以找到目标内容时，仅读取每个文件的前约10行。前置元数据中的

tags

、

project

、

type

和

status

字段可以帮你判断该笔记是否相关，无需读取完整内容。

Directory listing before reading

读取文件前先列出目录内容

List directory contents before reading files — know what exists without consuming tokens:

```
$VAULT/projects/{name}/**/*.md
```
— all notes for a project
```
$VAULT/domains/{tech}/*.md
```
— domain knowledge files

读取文件前先列出目录内容——无需消耗配额即可了解目录结构：

```
$VAULT/projects/{name}/**/*.md
```
——项目的所有笔记
```
$VAULT/domains/{tech}/*.md
```
——领域知识文件

Writing to the Vault

写入知识库

Write concisely. Notes are for your future context, not human documentation. Prefer:

Bullet points over prose
Wikilinks over repeated explanations (link to it, don't re-state it)
Frontmatter tags for discoverability over verbose descriptions

内容需简洁。笔记是为你未来的上下文服务，而非供人类阅读的文档。优先使用：

项目符号而非散文
维基链接而非重复解释（链接到对应内容，不要重复描述）
前置元数据标签而非冗长描述，提升可发现性

When to write

写入时机

New component discovered: Create a component note when you deeply understand a part of the codebase
Architecture decision made: Record ADRs when significant design choices are made
Pattern identified: Document recurring patterns that future sessions should follow
Domain knowledge learned: Write to domain notes when you discover cross-project knowledge

发现新组件：当你深入理解代码库的某个部分时，创建组件笔记
做出架构决策：当做出重要设计选择时，记录ADR（架构决策记录）
识别到模式：记录重复出现的模式，供未来会话参考
学到领域知识：当发现跨项目知识时，写入领域笔记

Scoping rules

范围规则

Knowledge type	Location	Example
One project only	`projects/{name}/`	How this API handles auth
Shared across projects	`domains/{tech}/`	How Go interfaces work
Universal, tech-agnostic	`patterns/`	SOLID principles
Session summaries	`sessions/`	What was done and discovered
TODOs	`todos/Active TODOs.md`	Grouped by project

知识类型	存储位置	示例
仅适用于单个项目	`projects/{name}/`	该API如何处理认证
跨项目共享	`domains/{tech}/`	Go接口的工作原理
通用、与技术无关	`patterns/`	SOLID原则
会话总结	`sessions/`	已完成的工作和发现的内容
待办事项	`todos/Active TODOs.md`	按项目分组

Frontmatter conventions

前置元数据规范

Always include in new notes:

yaml

---
tags: [category, project/short-name]
type: <component|adr|session|project>
project: "[[projects/{name}/{name}]]"
created: YYYY-MM-DD
---

新笔记必须包含以下前置元数据：

yaml

---
tags: [category, project/short-name]
type: <component|adr|session|project>
project: "[[projects/{name}/{name}]]"
created: YYYY-MM-DD
---

Wikilink conventions

维基链接规范

Link to related notes:

[[projects/{name}/components/Component Name|Component Name]]

Link to domains:

[[domains/{tech}/{Tech Name}|Tech Name]]

Link back to project:
```
[[projects/{name}/{name}|project-name]]
```

链接到相关笔记：

[[projects/{name}/components/Component Name|Component Name]]

链接到领域：

[[domains/{tech}/{Tech Name}|Tech Name]]

链接回项目：
```
[[projects/{name}/{name}|project-name]]
```

Note templates

笔记模板

Component Note:

yaml

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/{name}/{name}]]"
created: {date}
status: active
layer: ""
depends-on: []
depended-on-by: []
key-files: []
---

Sections: Purpose, Gotchas

Architecture Decision:

yaml

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/{name}/{name}]]"
status: proposed | accepted | superseded
created: {date}
---

Sections: Context, Decision, Alternatives Considered, Consequences

Session Note:

yaml

---
tags: [sessions]
type: session
projects:
  - "[[projects/{name}/{name}]]"
created: {date}
branch: {branch-name}
---

Sections: Context, Work Done, Discoveries, Decisions, Next Steps

组件笔记:

yaml

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/{name}/{name}]]"
created: {date}
status: active
layer: ""
depends-on: []
depended-on-by: []
key-files: []
---

章节：用途、注意事项

架构决策记录:

yaml

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/{name}/{name}]]"
status: proposed | accepted | superseded
created: {date}
---

章节：背景、决策、备选方案、影响

会话笔记:

yaml

---
tags: [sessions]
type: session
projects:
  - "[[projects/{name}/{name}]]"
created: {date}
branch: {branch-name}
---

章节：背景、已完成工作、发现的内容、做出的决策、下一步计划

Commands

命令

init

— Initialize the Vault

init

—— 初始化知识库

Bootstrap a new Obsidian Agent Memory vault from the bundled template.

Usage:

init [path]

从捆绑模板引导创建新的Obsidian Agent记忆知识库。

用法：

init [path]

Steps:

步骤:

Determine vault path: Use the first argument if provided, otherwise use the vault resolution chain (default:
```
~/Documents/AgentMemory
```
).
Check if vault already exists: Look for
```
$VAULT/Home.md
```
. If it exists, tell the user the vault already exists at that path and offer to open it.
Locate the bundled template: The template is at
```
vault-template/
```
relative to the skill package root. Search for the skill package installation directory — it may be in the agent's plugin/skill cache or a local checkout. Look for the
```
vault-template/Home.md
```
file to confirm the correct path.

Create the vault:

bash

mkdir -p "$VAULT"
cp -r "$TEMPLATE_DIR/vault-template/"* "$VAULT/"

Create Obsidian config directory:

bash

mkdir -p "$VAULT/.obsidian"

Write the following to

$VAULT/.obsidian/app.json

json

{
  "alwaysUpdateLinks": true,
  "newFileLocation": "folder",
  "newFileFolderPath": "inbox",
  "attachmentFolderPath": "attachments"
}

Create empty directories:

bash

mkdir -p "$VAULT/inbox"
mkdir -p "$VAULT/attachments"

Create

.gitkeep

files in each empty directory.

Report the created vault and provide next steps:
- Open in Obsidian: Vault Switcher → Open folder as vault →
```
$VAULT
```
- Set the vault path via
```
OBSIDIAN_VAULT_PATH
```
  environment variable or agent config
- Start working — the agent will build the knowledge graph as it goes
Generate agent config snippet: Output a vault path snippet appropriate for the user's agent. For Claude Code, output a
```
CLAUDE.md
```
snippet:
markdown
```
## Obsidian Knowledge Vault
Persistent knowledge vault at `$VAULT`.
```
For other agents, output a generic instruction: "Add
```
OBSIDIAN_VAULT_PATH=$VAULT
```
to your environment or agent config."
Auto-scaffold current project: If inside a git repo, automatically run the
```
project
```
command to scaffold the current project in the vault.
Concise output: Keep the final output to 5-8 lines max: vault path created, project scaffolded (if applicable), how to open in Obsidian, how to set the vault path.

确定知识库路径：如果提供了第一个参数，则使用该参数作为路径；否则使用知识库解析链（默认路径：
```
~/Documents/AgentMemory
```
）。
检查知识库是否已存在：查找
```
$VAULT/Home.md
```
文件。如果该文件存在，告知用户该路径下已存在知识库，并提供打开方式。
定位捆绑模板：模板位于技能包根目录下的
```
vault-template/
```
文件夹中。查找技能包的安装目录——可能位于Agent的插件/技能缓存或本地检出目录中。通过查找
```
vault-template/Home.md
```
文件确认正确路径。

创建知识库:

bash

mkdir -p "$VAULT"
cp -r "$TEMPLATE_DIR/vault-template/"* "$VAULT/"

创建Obsidian配置目录:

bash

mkdir -p "$VAULT/.obsidian"

将以下内容写入

$VAULT/.obsidian/app.json

json

{
  "alwaysUpdateLinks": true,
  "newFileLocation": "folder",
  "newFileFolderPath": "inbox",
  "attachmentFolderPath": "attachments"
}

创建空目录:

bash

mkdir -p "$VAULT/inbox"
mkdir -p "$VAULT/attachments"

在每个空目录中创建

.gitkeep

文件。

报告已创建的知识库并提供后续步骤:
- 在Obsidian中打开：Vault Switcher → Open folder as vault →
```
$VAULT
```
- 通过
```
OBSIDIAN_VAULT_PATH
```
  环境变量或Agent配置设置知识库路径
- 开始工作——Agent会在工作过程中构建知识图谱
生成Agent配置片段：根据用户的Agent输出合适的知识库路径片段。对于Claude Code，输出
```
CLAUDE.md
```
片段:
markdown
```
## Obsidian Knowledge Vault
Persistent knowledge vault at `$VAULT`.
```
对于其他Agent，输出通用说明：“将
```
OBSIDIAN_VAULT_PATH=$VAULT
```
添加到你的环境变量或Agent配置中。”
自动搭建当前项目结构：如果当前处于git仓库中，自动运行
```
project
```
命令，为当前项目在知识库中搭建结构。
简洁输出：最终输出控制在5-8行以内：已创建的知识库路径、是否已搭建项目结构（如适用）、在Obsidian中打开的方式、设置知识库路径的方法。

analyze

— Analyze Project & Hydrate Vault

analyze

—— 分析项目并填充知识库

Analyze the current codebase and populate the vault with interconnected, content-rich notes.

Usage:

analyze

(no arguments — uses current repo)

分析当前代码库，并将相互关联、内容丰富的笔记填充到知识库中。

用法：

analyze

（无参数——使用当前仓库）

Phase 1: Discovery — Scan for Knowledge Sources

阶段1：发现——扫描知识来源

Scan the repo for files that contain pre-existing knowledge:

Category	Files to scan
Agent configs	`CLAUDE.md` , `.claude/CLAUDE.md` , `.cursorrules` , `.windsurfrules` , `.clinerules` , `AGENTS.md` , `Agents.md`
Documentation	`README.md` , `CONTRIBUTING.md` , `ARCHITECTURE.md` , `docs/architecture.md` , `docs/ARCHITECTURE.md`
Existing ADRs	`docs/adr/ADR-.md` , `architecture/ADR-.md` , `adr/.md` , `docs/decisions/.md`
Project metadata	`package.json` , `go.mod` , `Cargo.toml` , `pyproject.toml` , `setup.py` , `Gemfile` , `pom.xml` , `build.gradle` , `*.csproj`
Build/CI	`Makefile` , `Dockerfile` , `docker-compose.yml` , `.github/workflows/*.yml` , `.gitlab-ci.yml`
Config	`tsconfig.json` , `.eslintrc.` , `jest.config.` , `.goreleaser.yml`

Read each discovered file. For large files (README, agent configs), read fully. For metadata files, extract key fields (name, version, dependencies).

Also gather:

Repo URL from
```
git remote get-url origin
```
Repo root path from
```
git rev-parse --show-toplevel
```
Active branch from
```
git branch --show-current
```
Directory tree (top 2 levels of source directories, excluding hidden/vendor/node_modules)
File extension frequency (for language detection)

扫描仓库中包含既有知识的文件：

类别	扫描文件
Agent配置	`CLAUDE.md` , `.claude/CLAUDE.md` , `.cursorrules` , `.windsurfrules` , `.clinerules` , `AGENTS.md` , `Agents.md`
文档	`README.md` , `CONTRIBUTING.md` , `ARCHITECTURE.md` , `docs/architecture.md` , `docs/ARCHITECTURE.md`
既有ADR	`docs/adr/ADR-.md` , `architecture/ADR-.md` , `adr/.md` , `docs/decisions/.md`
项目元数据	`package.json` , `go.mod` , `Cargo.toml` , `pyproject.toml` , `setup.py` , `Gemfile` , `pom.xml` , `build.gradle` , `*.csproj`
构建/CI	`Makefile` , `Dockerfile` , `docker-compose.yml` , `.github/workflows/*.yml` , `.gitlab-ci.yml`
配置	`tsconfig.json` , `.eslintrc.` , `jest.config.` , `.goreleaser.yml`

读取每个发现的文件。对于大文件（如README、Agent配置），完整读取。对于元数据文件，提取关键字段（名称、版本、依赖项）。

同时收集以下信息：

从
```
git remote get-url origin
```
获取仓库URL
从
```
git rev-parse --show-toplevel
```
获取仓库根路径
从
```
git branch --show-current
```
获取当前分支
目录树（源目录的前2层，排除隐藏目录/供应商目录/node_modules）
文件扩展名频率（用于检测开发语言）

Phase 2: Analysis — Extract & Synthesize

阶段2：分析——提取与合成

Using the discovered content, synthesize:

Project metadata: name, language(s), framework(s), repo URL, local path
Architecture summary: Entry points, layer organization (e.g.,
```
internal/
```
→ Go service layers,
```
src/components/
```
→ React app), build system
Component inventory: Major functional modules — each top-level source directory or logical grouping that represents a distinct unit. For each: purpose (from README/agent config context), key files, and relationships
Pattern inventory: Coding conventions, error handling strategies, testing approaches — extracted from agent config files (CLAUDE.md sections like "Coding Guidelines", "Testing", etc.)
Domain mapping: Detected technologies → vault domain notes (e.g., Go, TypeScript, Terraform, React)
Existing decisions: ADR files found in the repo → import as vault ADR notes
Dependency summary: Key dependencies from package manifests (listed in project overview, not separate notes)

利用发现的内容，合成以下信息：

项目元数据：名称、开发语言、框架、仓库URL、本地路径
架构摘要：入口点、分层结构（如
```
internal/
```
→ Go服务层，
```
src/components/
```
→ React应用）、构建系统
组件清单：主要功能模块——每个顶级源目录或代表独立单元的逻辑分组。每个模块包含：用途（来自README/Agent配置上下文）、关键文件、关联关系
模式清单：编码规范、错误处理策略、测试方法——从Agent配置文件中提取（如CLAUDE.md中的“Coding Guidelines”“Testing”章节）
领域映射：检测到的技术 → 知识库领域笔记（如Go、TypeScript、Terraform、React）
既有决策：仓库中已有的ADR文件 → 导入为知识库ADR笔记
依赖摘要：从包清单中提取的关键依赖项（仅在项目概述中列出，无需单独创建笔记）

Phase 3: Hydration — Write Vault Notes

阶段3：填充——写入知识库笔记

Idempotency rules:

If project directory doesn't exist → create everything (scaffold + populate)
If project directory exists but overview is a skeleton → replace overview with populated version
If individual component/pattern/ADR notes already exist → skip and report (don't overwrite manual work)
Domain notes: create if missing, append project link if existing

Notes to write:

Project overview (
```
$VAULT/projects/{name}/{name}.md
```
) — Fully populated:
yaml
```
---
aliases: []
tags: [project/{short-name}]
type: project
repo: {git remote url}
path: {repo root path}
language: {detected language(s)}
framework: {detected framework(s)}
created: {YYYY-MM-DD}
status: active
---
```
Sections:
- Architecture: Real description from analysis
- Components: Table with wikilinks to component notes
- Project Patterns: Table with wikilinks to pattern notes
- Architecture Decisions: List with wikilinks to ADR notes
- Key Dependencies: From package manifests
- Domains: Wikilinks to domain notes

Component notes (

$VAULT/projects/{name}/components/{Component}.md

) — One per major module:

yaml

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/{name}/{name}]]"
created: {YYYY-MM-DD}
status: active
layer: {detected layer}
depends-on: []
depended-on-by: []
key-files: [{key files list}]
---

Sections: Purpose, Gotchas

Pattern notes (

$VAULT/projects/{name}/patterns/{Pattern}.md

) — From agent config conventions:

yaml

---
tags: [patterns, project/{short-name}]
type: pattern
project: "[[projects/{name}/{name}]]"
created: {YYYY-MM-DD}
---

Sections: Pattern, When to Use, Implementation

ADR imports (

$VAULT/projects/{name}/architecture/ADR-{NNNN} {title}.md

) — From existing repo ADRs:

yaml

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/{name}/{name}]]"
status: accepted
created: {YYYY-MM-DD}
---

Preserve original content, add vault frontmatter.

Domain notes (
```
$VAULT/domains/{tech}/{Tech}.md
```
):
- If new: create with project link
- If existing: add this project to "Projects Using This Domain" section
Index updates:
- ```
$VAULT/projects/Projects.md
```
  — add/update row
- ```
$VAULT/domains/Domains.md
```
  — add/update rows for new domains

幂等性规则:

如果项目目录不存在 → 创建所有内容（搭建结构 + 填充内容）
如果项目目录存在但概述是骨架内容 → 替换概述为填充后的版本
如果单个组件/模式/ADR笔记已存在 → 跳过并报告（保留人工编辑的内容）
领域笔记：如果不存在则创建，如果已存在则追加项目链接

需要写入的笔记:

项目概述 (
```
$VAULT/projects/{name}/{name}.md
```
) —— 完整填充:
yaml
```
---
aliases: []
tags: [project/{short-name}]
type: project
repo: {git remote url}
path: {repo root path}
language: {detected language(s)}
framework: {detected framework(s)}
created: {YYYY-MM-DD}
status: active
---
```
章节:
- 架构：来自分析的真实描述
- 组件：包含指向组件笔记的维基链接的表格
- 项目模式：包含指向模式笔记的维基链接的表格
- 架构决策：包含指向ADR笔记的维基链接的列表
- 关键依赖项：来自包清单
- 领域：指向领域笔记的维基链接

组件笔记 (

$VAULT/projects/{name}/components/{Component}.md

) —— 每个主要模块对应一个笔记:

yaml

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/{name}/{name}]]"
created: {YYYY-MM-DD}
status: active
layer: {detected layer}
depends-on: []
depended-on-by: []
key-files: [{key files list}]
---

章节：用途、注意事项

模式笔记 (

$VAULT/projects/{name}/patterns/{Pattern}.md

) —— 来自Agent配置规范:

yaml

---
tags: [patterns, project/{short-name}]
type: pattern
project: "[[projects/{name}/{name}]]"
created: {YYYY-MM-DD}
---

章节：模式、适用场景、实现方式

ADR导入 (

$VAULT/projects/{name}/architecture/ADR-{NNNN} {title}.md

) —— 来自仓库中已有的ADR:

yaml

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/{name}/{name}]]"
status: accepted
created: {YYYY-MM-DD}
---

保留原始内容，添加知识库前置元数据。

领域笔记 (
```
$VAULT/domains/{tech}/{Tech}.md
```
):
- 如果是新领域：创建笔记并添加项目链接
- 如果已存在：将该项目添加到“使用该领域的项目”章节
索引更新:
- ```
$VAULT/projects/Projects.md
```
  —— 添加/更新行
- ```
$VAULT/domains/Domains.md
```
  —— 为新领域添加/更新行

Phase 4: Report

阶段4：报告

Print a summary:

Analyzed: {project-name}
  Sources read: {N} knowledge files
  Created: project overview (populated)
  Created: {N} component notes
  Created: {N} pattern notes
  Imported: {N} architecture decisions
  Linked: {N} domain notes
  Skipped: {N} existing notes (preserved)

打印总结:

已分析: {project-name}
  读取的知识源: {N}个文件
  创建: 项目概述（已填充）
  创建: {N}个组件笔记
  创建: {N}个模式笔记
  导入: {N}个架构决策
  关联: {N}个领域笔记
  跳过: {N}个既有笔记（已保留）

recap

— Write Session Summary

recap

—— 写入会话总结

Write a session summary note and update TODOs.

Usage:

recap

写入会话总结笔记并更新待办事项。

用法：

recap

Steps:

步骤:

Gather session context by running:

bash

git log --oneline -20
git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat
git branch --show-current

Read current TODOs — CLI-first:

bash

obsidian vault=$VAULT_NAME tasks path="todos" todo verbose

Fallback: Read

$VAULT/todos/Active TODOs.md

Read project overview from
```
$VAULT/projects/$PROJECT/$PROJECT.md
```
(for wikilinks and context).

Write session note — CLI-first:

bash

obsidian vault=$VAULT_NAME create path="sessions/{YYYY-MM-DD} - {title}" template="Session Note" silent
obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="type" value="session" type="text"
obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="branch" value="{current-branch}" type="text"
obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="projects" value="[[projects/$PROJECT/$PROJECT]]" type="list"

Then append body content:

bash

obsidian vault=$VAULT_NAME append path="sessions/{YYYY-MM-DD} - {title}" content="..."

Fallback: Write the file directly at

$VAULT/sessions/{YYYY-MM-DD} - {title}.md

yaml

---
tags: [sessions]
type: session
projects:
  - "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
branch: {current-branch}
---

Sections to fill:

Context: What was being worked on (from git log context)
Work Done: Numbered list of accomplishments (from commits and diffs)
Discoveries: Technical findings worth remembering
Decisions: Design choices made during this session
Next Steps: What should happen next (checkboxes)

Update TODOs: Edit
```
$VAULT/todos/Active TODOs.md
```
:
- Move completed items to Completed section
- Add new items discovered during the session
- Keep items grouped by project
Update Session Log: Add an entry to
```
$VAULT/sessions/Session Log.md
```
with the date, project, branch, and a one-line summary.
Report what was written.

收集会话上下文，运行以下命令:

bash

git log --oneline -20
git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat
git branch --show-current

读取当前待办事项 —— 优先使用CLI:

bash

obsidian vault=$VAULT_NAME tasks path="todos" todo verbose

备选方案：读取

$VAULT/todos/Active TODOs.md

。

读取项目概述，来自
```
$VAULT/projects/$PROJECT/$PROJECT.md
```
（获取维基链接和上下文）。

写入会话笔记 —— 优先使用CLI:

bash

obsidian vault=$VAULT_NAME create path="sessions/{YYYY-MM-DD} - {title}" template="Session Note" silent
obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="type" value="session" type="text"
obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="branch" value="{current-branch}" type="text"
obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="projects" value="[[projects/$PROJECT/$PROJECT]]" type="list"

然后追加正文内容:

bash

obsidian vault=$VAULT_NAME append path="sessions/{YYYY-MM-DD} - {title}" content="..."

备选方案：直接写入文件

$VAULT/sessions/{YYYY-MM-DD} - {title}.md

yaml

---
tags: [sessions]
type: session
projects:
  - "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
branch: {current-branch}
---

需要填充的章节:

背景：本次会话的工作内容（来自git日志上下文）
已完成工作：已完成事项的编号列表（来自提交记录和差异）
发现内容：值得记录的技术发现
做出的决策：本次会话中做出的设计选择
下一步计划：后续需要完成的工作（复选框形式）

更新待办事项：编辑
```
$VAULT/todos/Active TODOs.md
```
:
- 将已完成的事项移动到“已完成”章节
- 添加本次会话中发现的新待办事项
- 保持事项按项目分组
更新会话日志：在
```
$VAULT/sessions/Session Log.md
```
中添加一条记录，包含日期、项目、分支和一行摘要。
报告已写入的内容。

project

— Scaffold New Project

project

—— 搭建新项目结构

Scaffold a new project in the vault. Uses the first argument as the project name, or defaults to

$PROJECT

Usage:

project [name]

在知识库中搭建新项目的结构。使用第一个参数作为项目名称，默认使用

$PROJECT

。

用法：

project [name]

Steps:

步骤:

Determine project name: Use the argument if provided, otherwise use
```
$PROJECT
```
.
Check if project exists: Look for
```
$VAULT/projects/{name}/{name}.md
```
. If it exists, tell the user and offer to open it instead.

Create directory structure:

```
$VAULT/projects/{name}/
```
```
$VAULT/projects/{name}/architecture/
```
```
$VAULT/projects/{name}/components/
```
```
$VAULT/projects/{name}/patterns/
```

Create project overview at

$VAULT/projects/{name}/{name}.md

yaml

---
aliases: []
tags: [project/{short-name}]
type: project
repo: {git remote url if available}
path: {working directory}
language: {detected from files}
framework:
created: {YYYY-MM-DD}
status: active
---

Sections: Architecture, Components, Project Patterns, Architecture Decisions, Domains

Auto-detect and fill:

Language from file extensions in the repo
Repo URL from
```
git remote get-url origin
```
Link to relevant domains that exist in
```
$VAULT/domains/
```

Update Projects.md: Add a row to the project table in
```
$VAULT/projects/Projects.md
```
.
Report the scaffolded structure.

确定项目名称：如果提供了参数，则使用该参数作为项目名称；否则使用
```
$PROJECT
```
。
检查项目是否已存在：查找
```
$VAULT/projects/{name}/{name}.md
```
。如果该文件存在，告知用户并提供打开方式。

创建目录结构:

```
$VAULT/projects/{name}/
```
```
$VAULT/projects/{name}/architecture/
```
```
$VAULT/projects/{name}/components/
```
```
$VAULT/projects/{name}/patterns/
```

创建项目概述，保存到

$VAULT/projects/{name}/{name}.md

yaml

---
aliases: []
tags: [project/{short-name}]
type: project
repo: {git remote url if available}
path: {working directory}
language: {detected from files}
framework:
created: {YYYY-MM-DD}
status: active
---

章节：架构、组件、项目模式、架构决策、领域

自动检测并填充:

从仓库中的文件扩展名检测开发语言
从
```
git remote get-url origin
```
获取仓库URL
链接到
```
$VAULT/domains/
```
中已存在的相关领域

更新Projects.md：在
```
$VAULT/projects/Projects.md
```
的项目表格中添加一行。
报告已搭建的结构。

note

— Create a Note from Template

note

—— 从模板创建笔记

Create a note using a template. The first argument specifies the type:

component

adr

, or

pattern

Usage:

note <component|adr|pattern> [name]

使用模板创建笔记。第一个参数指定笔记类型：

component

、

adr

或

pattern

。

用法：

note <component|adr|pattern> [name]

note component [name]

note component [name]

Create at

$VAULT/projects/$PROJECT/components/{name}.md

yaml

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
status: active
layer: ""
depends-on: []
depended-on-by: []
key-files: []
---

Sections: Purpose, Gotchas

If a name argument is provided, use it as the component name. Otherwise, ask the user.

创建到

$VAULT/projects/$PROJECT/components/{name}.md

yaml

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
status: active
layer: ""
depends-on: []
depended-on-by: []
key-files: []
---

章节：用途、注意事项

如果提供了名称参数，使用该参数作为组件名称。否则，询问用户。

note adr [title]

note adr [title]

Determine the next ADR number by listing existing ADRs in

$VAULT/projects/$PROJECT/architecture/ADR-*.md

Create at

$VAULT/projects/$PROJECT/architecture/ADR-{NNNN} {title}.md

yaml

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/$PROJECT/$PROJECT]]"
status: proposed
created: {YYYY-MM-DD}
---

Sections: Context, Decision, Alternatives Considered, Consequences

通过列出

$VAULT/projects/$PROJECT/architecture/ADR-*.md

中的既有ADR，确定下一个ADR编号。

创建到

$VAULT/projects/$PROJECT/architecture/ADR-{NNNN} {title}.md

yaml

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/$PROJECT/$PROJECT]]"
status: proposed
created: {YYYY-MM-DD}
---

章节：背景、决策、备选方案、影响

note pattern [name]

note pattern [name]

Create at

$VAULT/projects/$PROJECT/patterns/{name}.md

yaml

---
tags: [patterns, project/{short-name}]
project: "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
---

Sections: Pattern, When to Use, Implementation, Examples

After creating any note, add a wikilink to it from the project overview.

创建到

$VAULT/projects/$PROJECT/patterns/{name}.md

yaml

---
tags: [patterns, project/{short-name}]
project: "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
---

章节：模式、适用场景、实现方式、示例

创建任何笔记后，在项目概述中添加指向该笔记的维基链接。

todo

— Manage TODOs

todo

—— 管理待办事项

View and update the Active TODOs for the current project.

Usage:

todo [action]

查看并更新当前项目的活跃待办事项。

用法：

todo [action]

Steps:

步骤:

Read current TODOs from
```
$VAULT/todos/Active TODOs.md
```
.
If no additional arguments: Display the current TODOs for
```
$PROJECT
```
and ask what to update.
If arguments provided: Parse as a TODO action:
- Plain text → Add as a new pending item under
```
$PROJECT
```
- ```
done: <text>
```
  → Move matching item to Completed
- ```
remove: <text>
```
  → Remove matching item
Write back the updated file.

读取当前待办事项，来自
```
$VAULT/todos/Active TODOs.md
```
。
如果没有额外参数：显示当前项目
```
$PROJECT
```
的待办事项，并询问用户需要更新的内容。
如果提供了参数：解析为待办事项操作:
- 纯文本 → 作为新的待处理事项添加到
```
$PROJECT
```
  分组下
- ```
done: <text>
```
  → 将匹配的事项移动到“已完成”章节
- ```
remove: <text>
```
  → 删除匹配的事项
写回更新后的文件。

lookup

— Search the Vault

lookup

—— 搜索知识库

Search the vault for knowledge. Supports targeted subcommands and freetext search.

Usage:

lookup <subcommand|freetext>

搜索知识库中的内容。支持定向子命令和自由文本搜索。

用法：

lookup <subcommand|freetext>

lookup deps <name>

lookup deps <name>

Query what a component depends on.

bash

obsidian vault=$VAULT_NAME property:read file="<name>" name="depends-on"

Fallback: Read the component note and parse the

depends-on

frontmatter list.

查询组件的依赖项。

bash

obsidian vault=$VAULT_NAME property:read file="<name>" name="depends-on"

备选方案：读取组件笔记并解析

depends-on

前置元数据列表。

lookup consumers <name>

lookup consumers <name>

Query what depends on a component (reverse dependencies).

bash

obsidian vault=$VAULT_NAME property:read file="<name>" name="depended-on-by"
obsidian vault=$VAULT_NAME backlinks file="<name>"

Combine results —

depended-on-by

gives explicit relationships,

backlinks

catches implicit references. Fallback: Read the component note and search for backlinks via Grep.

查询依赖该组件的内容（反向依赖）。

bash

obsidian vault=$VAULT_NAME property:read file="<name>" name="depended-on-by"
obsidian vault=$VAULT_NAME backlinks file="<name>"

合并结果 ——

depended-on-by

提供显式关联，

backlinks

捕获隐式引用。备选方案：读取组件笔记并通过Grep搜索反向链接。

lookup related <name>

lookup related <name>

Query all notes connected to a given note (both directions).

bash

obsidian vault=$VAULT_NAME links file="<name>"
obsidian vault=$VAULT_NAME backlinks file="<name>"

Fallback: Read the note and extract wikilinks, then Grep for

[[<name>

across the vault.

查询与给定笔记关联的所有笔记（双向）。

bash

obsidian vault=$VAULT_NAME links file="<name>"
obsidian vault=$VAULT_NAME backlinks file="<name>"

备选方案：读取笔记并提取维基链接，然后在整个知识库中Grep搜索

[[<name>

。

lookup type <type> [project]

lookup type <type> [project]

Find all notes of a given type (component, adr, session, project).

bash

obsidian vault=$VAULT_NAME tag verbose name="<type>"

[project]

is specified, filter results to notes also tagged

project/<short-name>

bash

obsidian vault=$VAULT_NAME search query="type: <type>" path="projects/<project>"

Fallback: Grep for

type: <type>

across

$VAULT

查找指定类型的所有笔记（component、adr、session、project）。

bash

obsidian vault=$VAULT_NAME tag verbose name="<type>"

如果指定了

[project]

，过滤出同时标记了

project/<short-name>

的结果:

bash

obsidian vault=$VAULT_NAME search query="type: <type>" path="projects/<project>"

备选方案：在

$VAULT

中Grep搜索

type: <type>

。

lookup layer <layer> [project]

lookup layer <layer> [project]

Find all components in a specific layer.

bash

obsidian vault=$VAULT_NAME search query="layer: <layer>" path="projects/<project>"

If no project specified, search across all projects:

bash

obsidian vault=$VAULT_NAME search query="layer: <layer>" path="projects"

Fallback: Grep for

layer: <layer>

across

$VAULT/projects/

查找指定层级的所有组件。

bash

obsidian vault=$VAULT_NAME search query="layer: <layer>" path="projects/<project>"

如果未指定项目，在所有项目中搜索:

bash

obsidian vault=$VAULT_NAME search query="layer: <layer>" path="projects"

备选方案：在

$VAULT/projects/

中Grep搜索

layer: <layer>

。

lookup files <component>

lookup files <component>

Query key files for a component.

bash

obsidian vault=$VAULT_NAME property:read file="<component>" name="key-files"

Fallback: Read the component note and parse the

key-files

frontmatter list.

查询组件的关键文件。

bash

obsidian vault=$VAULT_NAME property:read file="<component>" name="key-files"

备选方案：读取组件笔记并解析

key-files

前置元数据列表。

lookup <freetext>

lookup <freetext>

General search across the vault.

bash

obsidian vault=$VAULT_NAME search format=json query="<freetext>" matches limit=10

Fallback: Search file contents for the query across all

.md

files in

$VAULT

If the query looks like a tag (starts with

project/

bash

obsidian vault=$VAULT_NAME tags name="<query>"

If the query matches a note name:

bash

obsidian vault=$VAULT_NAME backlinks file="<query>"

Present results: Show matching notes with their frontmatter (first ~10 lines) so the user can decide which to read in full.

在知识库中进行通用搜索。

bash

obsidian vault=$VAULT_NAME search format=json query="<freetext>" matches limit=10

备选方案：在知识库中所有

.md

文件的内容中搜索查询词。

如果查询词看起来像标签（以

或

project/

开头）:

bash

obsidian vault=$VAULT_NAME tags name="<query>"

如果查询词匹配某个笔记名称:

bash

obsidian vault=$VAULT_NAME backlinks file="<query>"

结果展示：显示匹配的笔记及其前置元数据（前约10行），让用户决定是否需要完整读取。

relate

— Manage Relationships

relate

—— 管理关联关系

Create and query bidirectional relationships between notes via frontmatter properties.

Usage:

relate <subcommand> [args]

通过前置元数据属性在笔记之间创建和查询双向关联关系。

用法：

relate <subcommand> [args]

Supported relationship types

支持的关联类型

Forward property	Inverse property
`depends-on`	`depended-on-by`
`extends`	`extended-by`
`implements`	`implemented-by`
`consumes`	`consumed-by`

正向属性	反向属性
`depends-on`	`depended-on-by`
`extends`	`extended-by`
`implements`	`implemented-by`
`consumes`	`consumed-by`

relate <source> <target> [type]

relate <source> <target> [type]

Create a bidirectional relationship between two notes. Default type is

depends-on

depended-on-by

在两个笔记之间创建双向关联关系。默认类型为

depends-on

depended-on-by

。

Steps:

步骤:

Resolve note names: Use
```
file=
```
parameter for note display names. If ambiguity is possible (same name, different folders), use
```
path=
```
with full vault-relative path.
Read current property on source (forward direction):
bash
```
obsidian vault=$VAULT_NAME property:read file="<source>" name="<forward-property>"
```
Fallback: Read the source note frontmatter.
Check if relationship already exists: If
```
<target>
```
(as a wikilink) is already in the list, skip and report "already related".
Append to source (forward direction): Build the new list locally by appending
```
[[<target>]]
```
to the current values, then set:
bash
```
obsidian vault=$VAULT_NAME property:set file="<source>" name="<forward-property>" value="<full-list>" type="list"
```
Fallback: Edit the source note's frontmatter directly.

Read current property on target (inverse direction):

bash

obsidian vault=$VAULT_NAME property:read file="<target>" name="<inverse-property>"

Append to target (inverse direction):

bash

obsidian vault=$VAULT_NAME property:set file="<target>" name="<inverse-property>" value="<full-list>" type="list"

Report the created relationship.

Safety: Always read-then-set. Never blind-append. The full list is constructed locally and set atomically.

解析笔记名称：使用
```
file=
```
参数指定笔记显示名称。如果存在歧义（同名但位于不同文件夹），使用
```
path=
```
参数指定完整的知识库相对路径。
读取源笔记的当前属性（正向方向）:
bash
```
obsidian vault=$VAULT_NAME property:read file="<source>" name="<forward-property>"
```
备选方案：读取源笔记的前置元数据。
检查关联是否已存在：如果
```
<target>
```
（作为维基链接）已在列表中，跳过并报告“已关联”。
追加到源笔记（正向方向）: 在本地构建新列表，将
```
[[<target>]]
```
追加到当前值后，然后设置:
bash
```
obsidian vault=$VAULT_NAME property:set file="<source>" name="<forward-property>" value="<full-list>" type="list"
```
备选方案：直接编辑源笔记的前置元数据。

读取目标笔记的当前属性（反向方向）:

bash

obsidian vault=$VAULT_NAME property:read file="<target>" name="<inverse-property>"

追加到目标笔记（反向方向）:

bash

obsidian vault=$VAULT_NAME property:set file="<target>" name="<inverse-property>" value="<full-list>" type="list"

报告已创建的关联关系。

安全规则：始终先读取再设置。不要盲目追加。在本地构建完整列表后再原子性设置。

relate show <name>

relate show <name>

Display all relationships for a note.

显示某条笔记的所有关联关系。

Steps:

步骤:

Query all 8 relationship properties:

bash

obsidian vault=$VAULT_NAME property:read file="<name>" name="depends-on"
obsidian vault=$VAULT_NAME property:read file="<name>" name="depended-on-by"
obsidian vault=$VAULT_NAME property:read file="<name>" name="extends"
obsidian vault=$VAULT_NAME property:read file="<name>" name="extended-by"
obsidian vault=$VAULT_NAME property:read file="<name>" name="implements"
obsidian vault=$VAULT_NAME property:read file="<name>" name="implemented-by"
obsidian vault=$VAULT_NAME property:read file="<name>" name="consumes"
obsidian vault=$VAULT_NAME property:read file="<name>" name="consumed-by"

Fallback: Read the note frontmatter and parse all relationship properties.

Query structural links:

bash

obsidian vault=$VAULT_NAME links file="<name>"
obsidian vault=$VAULT_NAME backlinks file="<name>"

Present results grouped by relationship type. Show explicit (property) relationships first, then structural (wikilink) relationships that aren't already covered.

查询所有8个关联属性:

bash

obsidian vault=$VAULT_NAME property:read file="<name>" name="depends-on"
obsidian vault=$VAULT_NAME property:read file="<name>" name="depended-on-by"
obsidian vault=$VAULT_NAME property:read file="<name>" name="extends"
obsidian vault=$VAULT_NAME property:read file="<name>" name="extended-by"
obsidian vault=$VAULT_NAME property:read file="<name>" name="implements"
obsidian vault=$VAULT_NAME property:read file="<name>" name="implemented-by"
obsidian vault=$VAULT_NAME property:read file="<name>" name="consumes"
obsidian vault=$VAULT_NAME property:read file="<name>" name="consumed-by"

备选方案：读取笔记的前置元数据并解析所有关联属性。

查询结构化链接:

bash

obsidian vault=$VAULT_NAME links file="<name>"
obsidian vault=$VAULT_NAME backlinks file="<name>"

结果展示：按关联类型分组。先显示显式（属性）关联，再显示未被覆盖的结构化（维基链接）关联。

relate tree <name> [depth]

relate tree <name> [depth]

Walk the dependency tree via BFS. Default depth is 2.

通过广度优先搜索遍历依赖树。默认深度为2。

Steps:

步骤:

Initialize BFS: Start with
```
<name>
```
at depth 0. Maintain a visited set and a queue.

For each node in the queue:

bash

obsidian vault=$VAULT_NAME property:read file="<current>" name="depends-on"

Fallback: Read the note and parse

depends-on

from frontmatter.

Add unvisited dependencies to the queue at
```
current_depth + 1
```
. Stop when
```
depth
```
limit is reached.
Present the tree as an indented list showing the dependency chain.

初始化广度优先搜索：从
```
<name>
```
开始，深度为0。维护已访问集合和队列。
处理队列中的每个节点:
bash
```
obsidian vault=$VAULT_NAME property:read file="<current>" name="depends-on"
```
备选方案：读取笔记并从前置元数据中解析
```
depends-on
```
列表。
将未访问的依赖项添加到队列，深度为
```
current_depth + 1
```
。当达到深度限制时停止。
展示依赖树，使用缩进列表显示依赖链。

Token Budget Rules

配额预算规则

CLI over reads: Use
```
obsidian
```
CLI for property reads, backlinks, links, tags, and search — these return targeted data without full file reads
Session start: At most 2 operations (TODOs + project overview)
During work: Use
```
lookup
```
subcommands and
```
relate show
```
before reading full notes
Frontmatter first: When scanning, read ~10 lines before committing to full read
List before read: List directory contents before reading files
Write concisely: Bullet points, links, tags — no prose when bullets suffice

优先使用CLI而非读取文件：使用
```
obsidian
```
CLI读取属性、反向链接、链接、标签和搜索——这些操作返回定向数据，无需完整读取文件
会话启动：最多执行2项操作（待办事项 + 项目概述）
工作过程中：先使用
```
lookup
```
子命令和
```
relate show
```
，再读取完整笔记
优先读取前置元数据：扫描时，先读取约10行内容，再决定是否完整读取
读取文件前先列出目录：读取文件前先列出目录内容
简洁写入：使用项目符号、链接、标签——能用项目符号表达的内容就不要用散文

Error Handling

错误处理

If the vault doesn't exist → suggest running
```
/obs init
```
to bootstrap it
If the project doesn't exist in the vault → offer to run
```
/obs project
```
to scaffold it
If a note already exists → show it instead of overwriting, offer to edit
If no git repo is detected → use current directory name as project name
If CLI command fails → fall back to file read for the same data

如果知识库不存在 → 建议运行
```
/obs init
```
引导创建
如果项目在知识库中不存在 → 主动提出运行
```
/obs project
```
搭建结构
如果笔记已存在 → 显示该笔记而非覆盖，主动提出编辑
如果未检测到git仓库 → 使用当前目录名称作为项目名称
如果CLI命令失败 → 退而读取文件获取相同数据

Vault Structure Reference

知识库结构参考

$VAULT/
├── Home.md                           # Dashboard (read only if lost)
├── projects/{name}/
│   ├── {name}.md                     # Project overview — START HERE
│   ├── architecture/                 # ADRs and design decisions
│   ├── components/                   # Per-component notes
│   └── patterns/                     # Project-specific patterns
├── domains/{tech}/                   # Cross-project knowledge
├── patterns/                         # Universal patterns
├── sessions/                         # Session logs (read only when needed)
├── todos/Active TODOs.md             # Pending work (read at session start)
├── templates/                        # Note templates
└── inbox/                            # Unsorted

$VAULT/
├── Home.md                           # 仪表盘（仅当无法找到项目时读取）
├── projects/{name}/
│   ├── {name}.md                     # 项目概述 —— 从这里开始
│   ├── architecture/                 # ADR和设计决策
│   ├── components/                   # 组件笔记
│   └── patterns/                     # 项目特定模式
├── domains/{tech}/                   # 跨项目知识
├── patterns/                         # 通用模式
├── sessions/                         # 会话日志（仅当需要时读取）
├── todos/Active TODOs.md             # 待办工作（会话启动时读取）
├── templates/                        # 笔记模板
└── inbox/                            # 未分类内容