vault-management

Obsidian 知识库管理

将 Obsidian 知识库作为开发者知识库和自动工作日志进行管理。

适用场景

在以下情况下启用此技能：

• 用户请求执行笔记操作（添加、搜索、更新、导入、链接、归档）
• 处理应存储在知识库中的项目文档
• 自动记录提交、任务或 Claude Code 组件
• 用户询问其笔记、文档或知识库
• 整理或查找知识库中的信息

知识库结构

~/guerra_vault/
├── projects/              # Project-specific documentation
├── technologies/          # Technology knowledge (Laravel, React, etc.)
├── claude-code/           # Claude Code components
│   ├── agents/
│   ├── hooks/
│   ├── skills/
│   └── tools/
├── ideas/                 # Feature ideas and experiments
├── personal/              # Career and learning goals
├── todo/                  # Tasks and checklists
├── references/            # Bookmarks, snippets, cheatsheets
├── journal/               # Auto-captured events
│   ├── commits/           # Git commit documentation
│   ├── tasks/             # Completed task summaries
│   └── creations/         # Component creation logs
└── _archive/              # Archived notes

Frontmatter 标准

所有笔记都必须包含以下 YAML frontmatter：

---
title: "Note Title"
description: "Brief description of the content"
tags: [tag1, tag2, category]
related: [[path/to/related-note]]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

规则：

• title：描述性标题，与主标题一致
• description：用一句话说明内容
• tags：始终将类别作为标签
• related：采用 Wiki 链接格式，相关时添加关联笔记
• created：创建时设置一次
• updated：笔记变更时更新

可用命令

命令	用途
/obsidian-vault:init	设置知识库配置和结构
/obsidian-vault:add <category> <title>	创建新笔记
/obsidian-vault:search <query>	按标题、内容或标签查找笔记
/obsidian-vault:update <note>	编辑笔记 frontmatter 或追加内容
/obsidian-vault:import <file>	导入外部文件并添加 frontmatter
/obsidian-vault:list [category]	列出笔记，可按类别筛选
/obsidian-vault:tags [--stats]	查看标签和使用统计信息
/obsidian-vault:link <note1> <note2>	创建双向关联链接
/obsidian-vault:archive <note>	将笔记移至归档

自动记录行为

该插件会自动记录：

Git 提交

• 创建 journal/commits/YYYY-MM-DD-<slug>.md
• 包含：提交消息、日期、项目、分支、变更文件
• 为“做了什么”和“为什么”添加占位部分（根据上下文填写）

任务完成情况

• 创建 journal/tasks/YYYY-MM-DD-<slug>.md
• 记录子 Agent 摘要
• 包含：摘要、完成的工作、所做的决策

Claude Code 组件

• 创建 claude-code/<type>s/<name>.md
• 跟踪：Agent、钩子、技能、工具
• 同时记录到 journal/creations/

最佳实践

创建笔记

1. 选择合适的类别
2. 使用描述性标题
3. 立即添加相关标签
4. 在关联关系明确时链接相关笔记

更新笔记

1. 更新 updated 日期（脚本会自动完成）
2. 随着关联关系的出现，添加新的相关链接
3. 保持描述为最新状态

搜索

1. 先进行宽泛搜索，再使用 --title、--content 或 --tag 缩小范围
2. 使用 --category 聚焦于特定领域
3. 查看相关笔记以获取更多上下文

组织

1. 在各类别中使用一致的命名方式
2. 归档而不是删除
3. 维护双向链接

与工作流集成

完成功能后

完成某项功能或修复后：

1. 确认提交已记录
2. 添加或更新项目文档
3. 将新笔记链接到项目 README

学习技术时

1. 在 technologies/ 中创建笔记
2. 链接到使用该技术的项目
3. 按需添加代码片段

记录想法和实验

1. 从 ideas/ 开始
2. 开始实施时移至 projects/
3. 放弃时归档

其他资源

参考文件

• references/frontmatter-spec.md —— frontmatter 详细规范

配置

• 配置文件：~/.claude/obsidian-vault.json
• 知识库路径：~/guerra_vault