yixiong/yixiong-claude-marketplace
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 新增 obsidian 插件族（9 个技能）

Browse Source 
- 新增 plugins/obsidian 插件目录，含 9 个 obsidian-* 技能
- 核心技能重构：去除 README.md 分散路由，合并 vault 自动检测
  SOP（.obsidian/ 目录置信度表 + 标准进入动作）到 SKILL.md
- 所有技能 description 精简重写：触发信号 + 边界 + .obsidian/
  联动激活信号，字数从 300+ 压缩至 220-250
- 更新 marketplace.json 追加 obsidian 插件条目

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SkyJourney
2026-05-01 13:20:31 +08:00
co-authored by Claude Sonnet 4.6
parent f13bd26f59
commit 1e35ee4d9f
11 changed files with 2473 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/marketplace.json
+5
View File
@@ -14,6 +14,11 @@
"name": "memcore", "name": "memcore",
"source": "./plugins/memcore", "source": "./plugins/memcore",
"description": "记忆体系核心引擎：memory-sync（全量同步）、memory-update（增量写入）、memory-lint（健康校验）" "description": "记忆体系核心引擎：memory-sync（全量同步）、memory-update（增量写入）、memory-lint（健康校验）"
},
{
"name": "obsidian",
"source": "./plugins/obsidian",
"description": "Obsidian 知识库 AI 协作插件族：检测到 .obsidian/ 目录自动激活，含 vault 管理、搜索图谱、frontmatter、任务、每日笔记、Bases 数据库、版本历史、插件配置、PKM 编排工作流共 9 个技能"
} }
] ]
} }
plugins/obsidian/.claude-plugin/plugin.json
+7
View File
@@ -0,0 +1,7 @@
{
"name": "obsidian",
"description": "Obsidian 知识库 AI 协作插件族。检测到 .obsidian/ 目录时自动激活全套技能：vault 管理（obsidian）、全文搜索与图谱（obsidian-search）、frontmatter 元数据（obsidian-meta）、Markdown 任务与 GTD（obsidian-tasks）、每日笔记（obsidian-daily）、Bases 数据库视图（obsidian-bases）、版本历史与恢复（obsidian-history）、插件与环境配置（obsidian-plugins）、PKM 编排工作流（obsidian-workflow-pkm）。",
"author": {
"name": "蚁熊团队"
}
}
plugins/obsidian/skills/obsidian-bases/SKILL.md
+266
View File
@@ -0,0 +1,266 @@
---
name: obsidian-bases
description: Obsidian 1.9+ 原生数据库视图（Bases）：查询 .base 文件中的结构化视图（JSON/CSV/MD 输出）、在 base 中创建新条目。触发词：Bases、base 视图、数据库视图、结构化查询笔记、base query。不用于 Dataview（社区插件，用其原生 DQL 语法）。依赖 YAML frontmatter 属性，与 obsidian-meta 配合使用；需 Obsidian ≥ 1.9。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Bases · 原生数据库视图
> **Obsidian 1.9+ 的杀手级特性**：把 vault 当成数据库，把每篇笔记当成一条记录，把 frontmatter 当成字段。用 `.base` 文件定义视图和筛选，不用写一行 JS（对比 Dataview）。
> **为什么 Bases 对 AI agent 意义重大**：它把"非结构化笔记 + frontmatter 属性"变成了"可查询的结构化数据"，agent 可以直接 `base:query` 拿到 JSON，不需要先全文搜索再解析。
---
## 何时使用
- 列出 vault 中所有 `.base` 数据库视图文件
- **查询某个 base** 的结果（支持多种输出格式）
- 在 base 中**创建新条目**（自动写入符合 base 视图规则的 frontmatter）
- 列出某 base 的所有**视图**（views）
- 把"项目管理面板"、"阅读清单"、"文章管理"等做成可视化看板
## 不用于
- **Dataview** 查询（社区插件，用 DQL 语法，不是 Bases）
- 简单的属性读写 → **obsidian-meta**
- 全文搜索 → **obsidian-search**
---
## 前置条件
- **Obsidian ≥ 1.9**（检查：`obsidian version`）
- 知识库中存在至少一个 `.base` 文件（通过 Obsidian UI 创建，或从社区模板复制）
- 参与 base 的笔记必须使用 **YAML frontmatter**（不是 Dataview inline 字段，Bases 不认）
---
## 命令速查
### Base 文件与视图管理
```bash
obsidian bases # 列出 vault 所有 .base 文件
obsidian base:views # 列出当前 base 的所有视图
obsidian base:views file="项目管理" # 列出某 base 的视图
```
### 查询 Base
```bash
# 基础查询（默认 JSON）
obsidian base:query file="项目管理"
obsidian base:query path="20-Areas/项目管理.base"
# 指定视图
obsidian base:query file="项目管理" view="进行中"
obsidian base:query file="项目管理" view="按截止日" format=csv
obsidian base:query file="项目管理" view="逾期" format=md # Markdown 表格
obsidian base:query file="项目管理" view="全部" format=paths # 只返回路径列表
obsidian base:query file="项目管理" view="全部" format=tsv
```
**输出格式**：
- `json`（默认）：最完整，含所有字段
- `csv`：表格，适合导出到 Excel
- `tsv`：表格，Bash 处理友好
- `md`：Markdown 表格，直接粘贴到笔记
- `paths`：只返回文件路径列表
### 在 Base 中创建新条目
```bash
# 在某视图下创建新笔记（自动套用该视图的默认字段）
obsidian base:create file="项目管理" view="进行中" name="新项目Alpha" \
content="# 新项目 Alpha" open
# 完整参数
obsidian base:create \
file="项目管理" \
view="进行中" \
name="新项目" \
content="初始内容" \
open \
newtab
```
> 💡 `base:create` 的威力：它会按视图规则**自动填充 frontmatter**（例如 "进行中" 视图可能强制 `status: active`），省去手动 `property:set`。
---
## Bases vs Dataview 选型表
| 维度 | Bases（官方 1.9+） | Dataview（社区插件） |
|-----|-------------------|---------------------|
| 语法 | YAML 配置（声明式） | JS/DQL（命令式） |
| 数据源 | 仅 YAML frontmatter | frontmatter + inline `Key::` |
| 写入 | ✅ 支持 `base:create` | ❌ 只读 |
| 性能 | ✅ 原生 C++，极快 | ⚠ JS 运行时，大 vault 卡 |
| 多视图 | ✅ 一个 base 多视图 | 每个查询一段代码 |
| AI agent 友好 | ✅ CLI 直接 query JSON | ⚠ 需要模拟 Dataview JS 运行 |
| 社区模板 | 🟡 起步阶段 | ✅ 海量模板 |
| 版本要求 | Obsidian ≥ 1.9 | 任意版本 |
**选型建议**：
- **新项目 / AI agent 驱动** → 首选 Bases
- **已有 Dataview 资产** → 继续用，或逐步迁移
- **需要复杂计算** → Dataview（Bases 未来会支持公式字段）
---
## AI Agent 最佳实践
### 场景 1 · 项目面板作为 AI 决策依据
```bash
# Agent 问："今天我该优先处理哪个项目？"
# Step 1: 查询"进行中"项目，按 due 排序
obsidian base:query file="项目管理" view="按截止日" format=json
# Step 2: Agent 分析返回的 JSON，找出：
# - due 最近的 3 个
# - priority 最高的 3 个
# - blocked 状态已解除的
# Step 3: 生成建议写入每日笔记
obsidian daily:append content="\n## 📌 AI 建议优先级\n..."
```
### 场景 2 · 阅读清单 Base 设计
创建 `30-Resources/reading-list.base`（通过 Obsidian UI），字段规划：
```yaml
# frontmatter 规范（每本书/文章一个笔记）
---
type: book | article | paper | video
title:
author:
url:
status: to-read | reading | done | abandoned
priority: 1-5
started: 2026-03-15
finished:
rating: 1-5
tags: [topic1, topic2]
---
```
视图设计：
- **待读**: `status == "to-read"`, 按 `priority desc`
- **在读**: `status == "reading"`
- **已读高分**: `status == "done" AND rating >= 4`
- **按主题**: group by `tags`
```bash
# Agent 查询：我的待读列表前 5
obsidian base:query file="reading-list" view="待读" format=md | head -20
```
### 场景 3 · 用 Base 做 AI 工作日志
创建 `99-Log/ai-actions.base`，每次 agent 写入操作创建一条记录：
```bash
# 不手动建笔记，直接通过 base:create
obsidian base:create \
file="ai-actions" \
view="今日" \
name="$(date +%Y%m%d%H%M%S)-property-set" \
content="---
action: property:set
target: 项目Alpha
field: status
value: done
agent: claude-sonnet-4-6
reason: 用户确认项目完成
---"
```
之后查询：
```bash
obsidian base:query file="ai-actions" view="今日" format=md
obsidian base:query file="ai-actions" view="本周 action 统计" format=csv
```
### 场景 4 · Base 作为 RAG 检索的结构化索引
传统 RAG：全文搜索 → 召回 → 喂模型。
Bases 增强：**先用 base 做结构化筛选，缩小召回范围，再做全文搜索**。
```bash
# 问题："最近 3 个月我写的关于虚拟线程的读书笔记"
# Step 1: 用 base 筛出结构化候选
obsidian base:query file="reading-list" view="近 3 个月" format=paths > /tmp/candidates.txt
# Step 2: 在候选范围内全文搜索
obsidian search query="虚拟线程" path="$(xargs -a /tmp/candidates.txt)" format=json
```
---
## Base 文件结构（了解即可，通常由 UI 生成）
`.base` 文件是 YAML 格式：
```yaml
# 20-Areas/项目管理.base
filters:
and:
- file.inFolder: "10-Projects"
- status: ["active", "paused"]
views:
- name: 进行中
type: table
filters:
- status: active
order:
- due ASC
columns:
- file.name
- status
- due
- priority
- owner
- name: 按截止日
type: table
order:
- due ASC
- name: 逾期
type: list
filters:
- due < today()
- status: active
```
> 💡 推荐通过 Obsidian UI 创建 `.base` 文件，再用 CLI 查询。直接手写 `.base` 容易语法错。
---
## 与其他技能的协作
| 场景 | 链路 |
|-----|------|
| 属性设计 → 视图落地 | **obsidian-meta**（frontmatter 规范）→ obsidian-bases（查询） |
| 结构化召回 + 全文精读 | obsidian-bases → **obsidian-search** |
| 决策支持 | obsidian-bases → **obsidian-daily**（写建议） |
| 项目看板自动化 | obsidian-bases + **obsidian-tasks**（进度） |
| AI 日志归档 | 所有技能写操作 → obsidian-bases（`base:create` 到 ai-actions.base） |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `bases` 命令返回空 | Obsidian 版本 < 1.9 | 升级到 1.9+ |
| `base:query` 字段缺失 | 笔记用了 Dataview inline 字段 | 改写到 YAML frontmatter |
| `base:create` 报错 | view 名称拼写错 | 先 `base:views` 列出 |
| 视图不更新 | 缓存 | `obsidian reload` |
| 日期排序错 | frontmatter 日期是 text 类型 | `property:set type=date` |
| 查询慢 | base filter 过于宽松 | 增加 `file.inFolder` 限定 |
| agent 写的 base 条目违反 schema | 没先读 base 规则 | `base:views` + 手动验证字段 |
plugins/obsidian/skills/obsidian-daily/SKILL.md
+248
View File
@@ -0,0 +1,248 @@
---
name: obsidian-daily
description: Obsidian 每日笔记工作流：读取/追加今日笔记内容、晨间规划注入、晚间回顾、AI 操作审计日志写入、快速灵感捕获。触发词：每日笔记、daily note、今天的笔记、晨间笔记、晚间回顾、写日志、快速捕获、quick capture。周报/月报汇总请用 obsidian-workflow-pkm，跨日搜索请用 obsidian-search。需 Obsidian Daily Notes 核心插件已启用。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Daily · 每日笔记工作流
> 每日笔记是 Obsidian 最重要的 AI 接入点——它是**时间轴的锚点**，是日常捕获、AI 操作日志、GTD 收集篮的统一载体。
---
## 何时使用
- 打开/读取**今天**的每日笔记
- 向今天的每日笔记**追加/前置**内容（AI 日志、完成任务、灵感片段）
- 实现**晨间模板**（计划、天气、任务列表）
- 实现**晚间回顾**（成就、反思、明日计划）
- 把 **AI agent 操作日志**写入当天笔记（可追溯）
## 不用于
- 跨日搜索/汇总 → **obsidian-search** + **obsidian-workflow-pkm**
- 周报/月报 → **obsidian-workflow-pkm**
- 任务列表管理 → **obsidian-tasks**
- 每日笔记的模板文件管理 → **obsidian-plugins**（Templates 插件）
---
## 命令速查
```bash
obsidian daily # 打开今天的每日笔记（UI 中）
obsidian daily paneType=split # 在分屏中打开
obsidian daily paneType=tab # 在新标签打开
obsidian daily paneType=window # 在新窗口打开
obsidian daily:read # 读取今日每日笔记内容（CLI 输出）
obsidian daily:path # 获取今日每日笔记的路径
obsidian daily:append content="- 一条日志" # 追加（自动换行）
obsidian daily:append content="## 新章节\n\n正文" open # 追加并打开
obsidian daily:append content="inline 内容" inline # 追加不换行
obsidian daily:prepend content="⚠ 顶部置顶" # 前置（自动换行）
obsidian daily:prepend content="紧急" inline # 前置不换行
```
> 💡 **前置依赖**：必须启用 Obsidian 内置的 **Daily Notes** 核心插件（Settings → Core plugins → Daily notes）。可在 **obsidian-plugins** 技能中操作。
---
## AI Agent 最佳实践
### 场景 1 · 晨间仪式（Morning Ritual）
每天早晨第一件事，agent 帮用户生成今日起点：
```bash
#!/bin/bash
TODAY=$(date +%Y-%m-%d)
WEEKDAY=$(date +%A)
# 1. 创建今天的每日笔记（如果还没有）
obsidian daily
# 2. 注入晨间模板
obsidian daily:append content="# ${TODAY} · ${WEEKDAY}
## 🌤 今日概览
- 天气：<agent 从 API 拉>
- 日程：<agent 从 Calendar 拉>
- 优先级：
## ✅ 今日任务（迁移自昨日未完成）
$(obsidian tasks todo verbose format=json | head -20)
## 📥 灵感捕获
-
## 🧠 深度工作
-
## 📝 AI 操作日志
"
```
### 场景 2 · 晚间回顾（Evening Review）
```bash
obsidian daily:append content="
---
## 🌙 晚间回顾 · $(date +%H:%M)
### 今日成就
$(obsidian tasks done verbose format=json | jq -r '.[] | "- ✅ \(.text)"')
### 未完成（需迁移）
$(obsidian tasks todo verbose format=json | jq -r '.[] | "- [ ] \(.text) @\(.file):\(.line)"')
### 反思
> （agent 生成的一段总结：今天做了什么、遇到什么阻塞、明天关注什么）
### 明日计划
- [ ] <从反思推导出的第一优先级>
"
```
### 场景 3 · AI 操作审计日志
**每次 AI agent 对 vault 做写入操作**，在今日笔记留一条记录：
```bash
# 包装成一个 bash 函数
log_agent_action() {
local action="$1"
local target="$2"
local reason="$3"
local ts=$(date +%H:%M)
obsidian daily:append inline content="
- \`${ts}\` **${action}** \`${target}\` — ${reason}"
}
# 使用示例
obsidian property:set name=status value=done file="项目A"
log_agent_action "property:set" "项目A" "用户确认项目完成"
obsidian move path="10-Projects/alpha/README.md" to="40-Archive/alpha/README.md"
log_agent_action "move" "alpha → Archive" "项目 Alpha 归档"
```
### 场景 4 · 从每日笔记反向提取事件
每日笔记是**时间机器**。可以从中提取：
```bash
# 读取今天所有任务
obsidian tasks daily
# 读取今天的所有内容（agent 做今日总结）
obsidian daily:read
# 获取路径做高级处理
DAILY_PATH=$(obsidian daily:path)
```
### 场景 5 · 快速捕获（Quick Capture）
CLI + daily:append 是**最轻量的知识库捕获入口**，甚至可以做成全局快捷键：
```bash
# 一行命令捕获想法（可配置系统快捷键调用）
obsidian daily:append content="- 💡 $(date +%H:%M) $*"
# 使用
obsidian daily:append content="- 💡 $(date +%H:%M) 虚拟线程配合 jOOQ 可能有死锁风险，待研究"
```
### 场景 6 · 会议记录一键入口
```bash
# 会议开始时
obsidian daily:append content="
## 🤝 会议 · $(date +%H:%M) · <会议主题>
**参会**：@张三 @李四
**议程**：
-
**要点**：
-
**行动项**：
- [ ]
"
```
---
## 晨间模板示例（可直接复制）
创建 `70-Templates/daily.md`（由 Obsidian Templates 插件自动填充 `{{date}}` 等变量）：
```markdown
---
date: {{date:YYYY-MM-DD}}
weekday: {{date:dddd}}
tags: [daily]
weather:
mood:
---
# {{date:YYYY-MM-DD}} · {{date:dddd}}
## 🌅 晨间规划
- **今日 Top 3**：
1.
2.
3.
- **时间预算**：
- 深度工作：
- 会议：
- 学习：
## ✅ 任务清单
- [ ]
## 📥 灵感捕获
## 📝 AI 操作日志
## 🌙 晚间回顾
### 成就
### 反思
### 明日准备
```
配置方式：Settings → Daily Notes → Template file location → `70-Templates/daily.md`
---
## 与其他技能的协作
| 场景 | 链路 |
|-----|------|
| 晨间任务收集 | **obsidian-tasks** → obsidian-daily（append） |
| AI 审计日志 | **所有写操作技能** → obsidian-daily（append） |
| 周报汇总 | obsidian-daily（read × 7）→ **obsidian-workflow-pkm** |
| 模板注入 | **obsidian-plugins**（Templates）+ obsidian-daily |
| 会议纪要回链 | **lark-minutes** / **lark-vc** → obsidian-daily |
| 日报生成 | obsidian-daily → **huanxi**（report_submit） |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `daily` 命令报错 | Daily Notes 插件未启用 | `obsidian plugin:enable id=daily-notes` |
| 每日笔记格式不对 | Daily 插件的文件名格式配置错 | Settings → Daily Notes → Date format |
| `daily:append` 没有换行 | 默认行为就是追加 | 不需要手动加 `\n` |
| 一天的笔记被覆盖 | 误用了 `create` 而非 `append` | 永远用 `daily:append` 或 `daily:prepend` |
| 时区错误 | 系统时区与 Obsidian 不一致 | 检查 `date +%Z` 与 Obsidian 设置 |
| AI 日志把笔记撑爆 | 无限追加 | 月末归档到 `40-Archive/Daily/YYYY-MM/` |
| Template 变量不解析 | 未配置 Templates 核心插件 | 启用 Templates 插件并设置路径 |
plugins/obsidian/skills/obsidian-history/SKILL.md
+236
View File
@@ -0,0 +1,236 @@
---
name: obsidian-history
description: Obsidian 版本历史与同步管理：查看/恢复/对比 File Recovery 本地快照（`history:*`）、管理 Obsidian Sync 的暂停与恢复（`sync:*`）、从云端回收站恢复误删文件。触发词：误删、恢复笔记、文件历史、版本恢复、版本对比、diff 笔记、Obsidian Sync、同步暂停。不用于 git 版本控制（直接 Bash git 命令）。Sync 相关命令需付费 Obsidian Sync 订阅。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian History · 版本历史与同步
> Obsidian 的**时间旅行层**：File Recovery（本地版本快照）+ Obsidian Sync（云端版本历史）。AI agent 的大规模写入操作需要这一层作为"后悔药"。
---
## 何时使用
- 查看某文件的**历史版本列表**
- **恢复**某文件的某个版本（误删/误改的救命稻草）
- **对比**两个版本的差异（diff）
- 查看 **Obsidian Sync 状态**（是否同步完成、积压多少）
- **暂停/恢复** Obsidian Sync（批量操作前关掉，避免抖动）
- 查看**已删除**的文件（云端回收站）
## 不用于
- Git 版本控制 → 普通 Bash git 命令
- Obsidian 自带回收站（已删除文件） → `obsidian delete` + 手动恢复
- 云盘历史版本（iCloud / Dropbox） → 云盘客户端
---
## 命令速查
### File Recovery（本地快照，核心插件）
> Obsidian 内置 "File Recovery" 核心插件自动快照本地版本（默认每 5 分钟，保留 7 天）。
```bash
obsidian history file="重要笔记" # 列出文件的历史版本
obsidian history path="10-Projects/alpha/README.md"
obsidian history:list # 列出所有有历史的文件
obsidian history:open file="重要笔记" # 在 Obsidian UI 中打开恢复界面
obsidian history:read file="重要笔记" version=1 # 读取第 1 个历史版本
obsidian history:read file="重要笔记" version=5 # 读取更早的版本
obsidian history:restore file="重要笔记" version=3 # ⚠ 恢复到第 3 个版本（覆盖当前）
```
### Diff 对比
```bash
obsidian diff file="重要笔记" # 列出所有可 diff 的版本
obsidian diff file="重要笔记" from=3 to=1 # 版本 3 到版本 1 的差异
obsidian diff file="重要笔记" filter=local # 只看本地版本
obsidian diff file="重要笔记" filter=sync # 只看 Sync 版本
```
### Obsidian Sync（付费功能）
```bash
obsidian sync:status # 当前同步状态
obsidian sync on # 恢复同步
obsidian sync off # 暂停同步（批量操作前）
obsidian sync:deleted # 列出已删除的文件（云端回收站）
obsidian sync:deleted total # 数量
obsidian sync:history file=<name> # 某文件的 Sync 版本历史
obsidian sync:history file=<name> total # 版本数
obsidian sync:open file=<name> # 在 Obsidian 中打开同步历史界面
obsidian sync:read file=<name> version=3 # 读取某 Sync 版本的内容
obsidian sync:restore file=<name> version=3 # ⚠ 恢复到某 Sync 版本
```
---
## AI Agent 最佳实践
### 场景 1 · 危险操作的"后悔药"流程
AI agent 做批量写入前，先做快照检查点：
```bash
#!/bin/bash
# 批量操作前的保险
OP_NAME="refactor-project-alpha"
BEFORE=$(date +%Y%m%d-%H%M%S)
# 1. 暂停 Sync（如果启用），避免抖动
obsidian sync off 2>/dev/null
# 2. 记录受影响的文件列表
obsidian files folder="10-Projects/alpha" format=json > /tmp/${OP_NAME}-${BEFORE}.json
# 3. 提交一个 git 检查点（vault 是 git 仓库的话）
cd "$(obsidian vault info=path)"
git add -A && git commit -m "checkpoint before ${OP_NAME}"
# 4. 执行批量操作
# ... obsidian move / property:set / delete ...
# 5. 恢复 Sync
obsidian sync on
# 6. 如果出错，用 history 或 git 回退
```
### 场景 2 · 恢复误删的笔记
```bash
# 1. 列出所有有历史的文件
obsidian history:list
# 2. 如果误删了"项目 Alpha"，先查是否还能找到历史
obsidian history file="项目Alpha"
# 3. 读取最近的版本内容
obsidian history:read file="项目Alpha" version=1
# 4. 确认无误后恢复
obsidian history:restore file="项目Alpha" version=1
```
### 场景 3 · AI 改写对比
AI agent 改完文章后，和上一版对比看变化：
```bash
# AI 修改完一篇文章
obsidian create path="drafts/article.md" content="新版本..."
# 对比与上一版的差异
obsidian diff file="article" from=2 to=1
```
### 场景 4 · Sync 状态监控
```bash
# 在脚本中检查同步是否完成再继续
while true; do
STATUS=$(obsidian sync:status)
if echo "$STATUS" | grep -q "synced"; then
echo "Sync 完成"
break
fi
sleep 5
done
```
### 场景 5 · 从云端回收站恢复
```bash
# 查看云端已删除文件
obsidian sync:deleted
# 对某个误删的文件恢复到某版本
obsidian sync:history file="重要笔记"
obsidian sync:read file="重要笔记" version=1 # 先确认内容
obsidian sync:restore file="重要笔记" version=1
```
---
## File Recovery vs Obsidian Sync 版本历史
| 特性 | File Recovery（本地） | Obsidian Sync（云端） |
|-----|---------------------|---------------------|
| 成本 | 免费（核心插件） | 付费订阅 |
| 触发 | 每 5 分钟自动（可配置） | 每次修改实时 |
| 保留 | 默认 7 天 | 默认 1 年 |
| 位置 | 本地 `.obsidian/` 内 | 云端服务器 |
| 跨设备 | ❌ | ✅ |
| 命令前缀 | `history:*` / `diff filter=local` | `sync:*` / `diff filter=sync` |
| 已删除文件恢复 | ❌ | ✅ `sync:deleted` |
**策略建议**：
- 个人单设备 → File Recovery 已够用
- 多设备 / 重度 AI 写入 → 强烈推荐 Sync（订阅值回票价）
- 强烈推荐同时把 vault 纳入 **git 仓库**，作为第三道保险
---
## 与 Git 协作的混合策略
Obsidian 的 history/sync 对**误操作**友好（分钟级粒度），git 对**语义变更**友好（按 commit message 回溯）。
```bash
# .gitignore（放在 vault 根目录）
.obsidian/workspace*
.obsidian/cache
.trash/
.DS_Store
```
```bash
# 批量 AI 操作的 git 惯例
cd $(obsidian vault info=path)
# 操作前：干净状态
git status --porcelain # 应为空
git commit --allow-empty -m "checkpoint: before AI refactor"
# 操作：agent 执行
# ...
# 操作后：按语义提交
git add -A
git commit -m "ai: refactor zettel links in 50-Zettel/
- 更新了 42 篇笔记的反链
- 重命名了 3 个文件
- 自动添加 created 字段到 15 篇旧笔记"
```
---
## 与其他技能的协作
| 场景 | 链路 |
|-----|------|
| 大批量写入前 | **obsidian-history**（checkpoint）→ 其他写入技能 |
| Agent 审计回溯 | **obsidian-daily**（审计日志）+ obsidian-history（版本对比） |
| 项目归档前 | obsidian-history（sync:status 确认）→ **obsidian**（move） |
| 回滚 AI 改写 | **obsidian-search** 找出受影响文件 → obsidian-history:restore |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `history` 命令返回空 | File Recovery 未启用 | `plugin:enable id=file-recovery` |
| `sync:*` 命令全部失败 | 未订阅 Obsidian Sync | 用 File Recovery + git 替代 |
| `history:restore` 后新改动丢失 | restore 是覆盖 | restore 前先 `read` 保存当前 |
| Sync 卡住不同步 | 网络或冲突 | `sync:status` 查看；必要时 `sync off; sync on` |
| 批量操作中途失败 | 没做检查点 | 永远先 git commit 或 sync off |
| version 编号混乱 | 不同来源混用 | 用 `diff filter=local` 或 `filter=sync` 区分 |
| AI 反复 restore 导致循环 | 无终止条件 | agent 写入前记录 baseline，只允许恢复一次 |
plugins/obsidian/skills/obsidian-meta/SKILL.md
+247
View File
@@ -0,0 +1,247 @@
---
name: obsidian-meta
description: 管理 Obsidian 笔记元数据：YAML frontmatter 属性（status/tags/created/due 等）读写、tag 统计与体系治理、aliases 别名、bookmarks 书签、为 Dataview/Bases 设计字段规范。触发词：frontmatter、设置属性、tag、标签、别名、书签、属性读写。不用于全文搜索（obsidian-search）或 Bases 视图查询（obsidian-bases）。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Meta · 元数据管理
> Frontmatter 属性、标签、别名、书签——Obsidian 的四大元数据系统。这是让 AI agent 结构化理解笔记的关键。
---
## 何时使用
- 给一篇笔记**设置或读取** frontmatter 属性（`status: draft` / `tags: [tech, arch]` / `due: 2026-05-01`）
- **批量维护** YAML 头（比如给所有 `50-Zettel/` 笔记补 `created` 字段）
- 统计 vault 中有哪些 tag、每个 tag 下有多少笔记
- 管理笔记的 **aliases**（别名，影响 wikilink 解析）
- 管理 **bookmarks**（收藏夹，快速跳转）
- 为 **Dataview** 或 **Obsidian Bases** 做字段规划
## 不用于
- 全文搜索 / 图谱分析 → **obsidian-search**
- Bases 视图的结构化查询 → **obsidian-bases**
- 任务状态管理（`- [ ]`/`- [x]`）→ **obsidian-tasks**
---
## 命令速查
### Tags 标签
```bash
obsidian tags # 列出 vault 所有 tag
obsidian tags counts # 含出现次数
obsidian tags sort=count # 按次数降序
obsidian tags format=json # JSON 输出
obsidian tags file=<name> # 某文件的 tags
obsidian tags active # 当前激活文件的 tags
obsidian tags total # 仅返回 tag 数量
obsidian tag name="tech" # 某 tag 详情
obsidian tag name="tech" verbose # 含使用该 tag 的文件列表
obsidian tag name="tech" total # 仅返回出现次数
```
### Properties（Frontmatter YAML）
```bash
obsidian properties # 列出 vault 所有属性名（YAML 默认）
obsidian properties counts # 含占用文件数
obsidian properties sort=count # 按出现次数排序
obsidian properties format=json # JSON 输出
obsidian properties file=<name> # 某文件的所有属性
obsidian properties name="status" # 查看某属性的使用情况
obsidian property:read name="status" file="项目A"
obsidian property:set name="status" value="done" file="项目A"
obsidian property:set name="tags" value="tech,arch,java" type=list file="技术笔记"
obsidian property:set name="due" value="2026-05-01" type=date file="项目A"
obsidian property:set name="priority" value=5 type=number file="项目A"
obsidian property:set name="published" value=true type=checkbox file="文章"
obsidian property:remove name="old_field" file="项目A"
```
**属性类型**：`text | list | number | checkbox | date | datetime`
### Aliases 别名
```bash
obsidian aliases # 列出 vault 所有别名
obsidian aliases verbose # 含文件路径
obsidian aliases total # 仅返回数量
obsidian aliases file=<name> # 某文件的别名
obsidian aliases active # 当前激活文件的别名
```
> 💡 Aliases 通过 frontmatter `aliases: [...]` 设置，影响 wikilink 解析——`[[别名]]` 会解析到原笔记。
### Bookmarks 书签
```bash
obsidian bookmarks # 列出所有书签（tsv 默认）
obsidian bookmarks verbose # 含类型（file/folder/search/url）
obsidian bookmarks format=json
obsidian bookmark file="重要笔记" # 添加文件书签
obsidian bookmark file="重要笔记" subpath="## 章节" # 指定标题/块
obsidian bookmark folder="10-Projects" # 文件夹书签
obsidian bookmark search="TODO" # 搜索书签
obsidian bookmark url="https://..." title="官方文档" # URL 书签
```
---
## AI Agent 最佳实践
### 场景 1 · Frontmatter 规范模板（写在 SCHEMA.md）
```yaml
---
# 身份
title: 笔记标题
aliases: [] # 别名列表
# 时间
created: 2026-04-09
updated: 2026-04-09
# 分类
type: note | project | area | resource | zettel | literature | moc
status: draft | active | done | archived
tags: [domain, subdomain]
# 项目专属
due: 2026-05-01
priority: 1-5
owner: name
# 永久笔记专属（Zettelkasten）
zettel_id: 202604091530
refs: [[[相关笔记1]], [[相关笔记2]]]
source: book | paper | url
---
```
**字段选型原则**：
- **通用字段**（所有笔记都有）：`title / created / updated / status / tags`
- **可选字段**（按 type 触发）：`due / priority / owner / zettel_id / source`
- **机器字段**（agent 写入）：`last_ai_touched / ai_summary / review_count`
### 场景 2 · 批量补全 created/updated 字段
```bash
# 找出所有缺 created 字段的笔记
obsidian files folder="50-Zettel" format=json | \
# 由 agent 逐个 property:read name=created file=...
# 如果返回空，则从文件 mtime 推断
# obsidian property:set name=created value="2024-01-15" type=date file=...
```
### 场景 3 · 状态机流转
```bash
# 项目从 active → done
obsidian property:read name=status file="项目Alpha" # 先读现状
obsidian property:set name=status value=done file="项目Alpha"
obsidian property:set name=updated value=$(date +%Y-%m-%d) type=date file="项目Alpha"
# 可配合 obsidian-workflow-pkm 做 PARA 归档：
# done → 2 周无动作 → 移到 40-Archive/
```
### 场景 4 · Tag 体系治理
```bash
# 1. 扫描所有 tag 统计
obsidian tags counts sort=count format=json > /tmp/tags.json
# 2. 由 agent 分析：
# - 低频 tag（< 3 次）是否可合并
# - 命名不一致（#Tech vs #tech）的归一化
# - 层级化（#area/tech、#area/design）
# 3. 找出含某 tag 的所有文件，批量替换
obsidian tag name="Tech" verbose # 拿到文件列表
# 对每个文件: property:set name=tags value="..." type=list
```
**tag 层级推荐**（结合 Obsidian 原生层级 tag 支持）：
```
#area/tech #status/draft
#area/design #status/active
#area/ops #status/done
#status/archived
#project/alpha
#project/beta #type/zettel
#type/moc
#type/literature
```
### 场景 5 · 用属性替代文件夹（动态视图）
Obsidian 的现代理念：**属性优于文件夹**。不用深层目录，而是用 frontmatter 做动态筛选。
```bash
# 所有 "active 项目" 用 property 查（配合 obsidian-bases）
obsidian property:set name=status value=active file="项目X"
# 然后在 obsidian-bases 里建一个视图：
# view: "进行中项目" where: status == "active" sort: due asc
```
### 场景 6 · 别名用于多语言/多写法
```yaml
---
title: Virtual Threads
aliases: [虚拟线程, 协程-Java 版, Project Loom]
---
```
wiki 中写 `[[虚拟线程]]` 或 `[[Project Loom]]` 都能链到同一篇。
---
## Dataview / Bases 字段设计建议
> 参考：dsebastien《Dataview frontmatter guide》、blacksmithgu/obsidian-dataview 文档
| 字段类型 | 示例 | Dataview 友好 | Bases 友好 | 备注 |
|---------|------|-------------|-----------|------|
| `text` | `title: 笔记` | ✅ | ✅ | 基础字符串 |
| `list` | `tags: [a,b]` | ✅ | ✅ | 多值用列表 |
| `number` | `priority: 3` | ✅（支持运算） | ✅ | 可排序可筛选 |
| `checkbox` | `done: true` | ✅ | ✅ | 布尔值 |
| `date` | `due: 2026-05-01` | ✅（支持 duration） | ✅ | 必须用 ISO 格式 |
| `datetime` | `created: 2026-04-09T10:30` | ✅ | ✅ | 含时间戳 |
| inline 字段 | `Key:: Value` | ✅ 仅 Dataview | ❌ Bases 不支持 | **Bases 只认 frontmatter，不认 inline** |
**铁律**：如果你用 Bases，**永远用 frontmatter**，不要用 `Key:: Value` inline 字段。
---
## 与其他技能的协作
| 场景 | 链路 |
|-----|------|
| 搜索命中后筛选 | **obsidian-search** → obsidian-meta（按 tag/status 二次过滤） |
| 批量属性维护 | obsidian-meta + **obsidian**（files 列出目标） |
| 按属性查询 | obsidian-meta（写入）→ **obsidian-bases**（查询展示） |
| 任务联动 | obsidian-meta（`status: done`）+ **obsidian-tasks**（`- [x]`） |
| 每日笔记自动打标签 | **obsidian-daily** + obsidian-meta |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `property:set` 后 Obsidian 不显示 | 打开的是缓存视图 | `obsidian reload` 或重新打开笔记 |
| 日期字段在 Dataview 里无法排序 | 写成了 text 类型 | `property:set type=date` 明确类型 |
| Bases 读不到 `Key:: Value` | Bases 只认 frontmatter | 把 inline 字段改写到 YAML 头 |
| 属性值含特殊字符报错 | YAML 特殊字符未引号 | 含 `: [] {} #` 的值必须加 `""` |
| tag 层级识别错误 | 中间有空格 | 层级 tag 不能有空格：`#area/tech` ✅，`#area/ tech` ❌ |
| 批量改 tag 覆盖了已有 tag | `property:set` 是覆盖不是追加 | 先 `property:read`，合并后再 `set` |
plugins/obsidian/skills/obsidian-plugins/SKILL.md
+284
View File
@@ -0,0 +1,284 @@
---
name: obsidian-plugins
description: 管理 Obsidian 环境配置：核心/社区插件的启用/禁用/安装/卸载、主题切换、CSS snippets 管理、Templates 模板管理、Obsidian 内置命令执行、快捷键查询。触发词：启用插件、社区插件、Obsidian 主题、CSS snippet、Templates、快捷键、hotkey、首次配置 vault。不用于笔记内容 CRUD（obsidian 核心技能）。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Plugins · 环境配置管理
> Obsidian 的"控制面板"：插件、主题、CSS、模板、命令、快捷键。一份技能管完所有环境配置。
---
## 何时使用
- **启用/禁用/安装/卸载**核心或社区插件
- 切换 / 安装 / 卸载**主题**
- 管理 **CSS snippets**（自定义样式片段）
- 管理 **Templates**（Obsidian Templates 核心插件的模板文件）
- 查看 / 执行 Obsidian 内置**命令**（`obsidian command id=...`）
- 查询 / 管理**快捷键**（hotkeys）
- 切换 **Restricted Mode**（安全模式，禁用社区插件）
## 不用于
- 笔记内容 CRUD → **obsidian** 核心技能
- Frontmatter 管理 → **obsidian-meta**
- Vault 层面同步设置 → **obsidian-history**
---
## 命令速查
### 插件（Plugins）
```bash
# 列出
obsidian plugins # 列出所有已安装插件（tsv 默认）
obsidian plugins filter=core # 只看核心插件
obsidian plugins filter=community # 只看社区插件
obsidian plugins versions # 含版本号
obsidian plugins format=json # JSON 输出
obsidian plugins:enabled # 只列启用的
obsidian plugins:enabled filter=community versions format=json
obsidian plugin id=dataview # 某插件详情
obsidian plugin id=<id> # 通过 ID 查询
```
```bash
# 启用/禁用/安装/卸载
obsidian plugin:enable id=daily-notes # 启用核心插件
obsidian plugin:enable id=dataview filter=community
obsidian plugin:disable id=dataview filter=community
obsidian plugin:install id=obsidian-git enable # 安装并立即启用（社区）
obsidian plugin:uninstall id=dataview
obsidian plugin:reload id=dataview # 开发用：重载插件
```
### 安全模式（Restricted Mode）
```bash
obsidian plugins:restrict on # 开启受限模式（禁用所有社区插件）
obsidian plugins:restrict off # 关闭
obsidian plugins:restrict # 查询状态
```
### 主题（Themes）
```bash
obsidian themes # 列出所有已安装主题
obsidian themes versions # 含版本号
obsidian theme # 当前主题
obsidian theme name="Minimal" # 某主题详情
obsidian theme:set name="Minimal" # 切换主题
obsidian theme:set name="" # 恢复默认
obsidian theme:install name="Minimal" enable # 安装并启用
obsidian theme:uninstall name="Minimal"
```
### CSS Snippets
```bash
obsidian snippets # 列出所有已安装 snippets
obsidian snippets:enabled # 已启用的
obsidian snippet:enable name="compact-tables"
obsidian snippet:disable name="compact-tables"
```
### Templates（核心插件）
```bash
obsidian templates # 列出所有模板
obsidian templates total # 数量
obsidian template:read name="daily" # 读取模板内容
obsidian template:read name="daily" resolve title="2026-04-09" # 解析变量后读取
obsidian template:insert name="meeting" # 插入到当前激活文件
```
> 💡 Templates 插件需要先启用：`obsidian plugin:enable id=templates` 并在设置中指定模板文件夹。
### Commands（Obsidian 内置命令系统）
```bash
obsidian commands # 列出所有可用命令
obsidian commands filter=editor # 按前缀筛选
obsidian commands filter=daily # 每日笔记相关命令
obsidian command id="editor:toggle-bold" # 执行命令（触发 Obsidian 内部动作）
obsidian command id="workspace:split-vertical"
obsidian command id="app:go-back"
```
### Hotkeys 快捷键
```bash
obsidian hotkeys # 列出所有快捷键（tsv）
obsidian hotkeys format=json
obsidian hotkeys all # 含未绑定快捷键的命令
obsidian hotkeys verbose # 显示是否自定义
obsidian hotkeys total # 数量
obsidian hotkey id="editor:toggle-bold" # 查询某命令的快捷键
obsidian hotkey id="editor:toggle-bold" verbose
```
---
## AI Agent 最佳实践
### 场景 1 · 首次配置检查清单
Agent 第一次进入某 vault，验证基础环境：
```bash
#!/bin/bash
# obsidian-doctor.sh：环境体检
echo "=== Vault 基础 ==="
obsidian vault info=name
obsidian version
echo "=== 核心插件启用状态 ==="
REQUIRED=("daily-notes" "templates" "file-recovery" "command-palette" "backlink" "outgoing-link")
for p in "${REQUIRED[@]}"; do
STATUS=$(obsidian plugin id=$p 2>/dev/null | grep -o 'enabled: true' && echo "✅" || echo "❌ $p 未启用")
echo "$STATUS"
done
echo "=== 社区插件 ==="
obsidian plugins filter=community versions
echo "=== 主题 ==="
obsidian theme
echo "=== 受限模式 ==="
obsidian plugins:restrict
```
### 场景 2 · 为 AI 工作流推荐的最小插件集
```bash
# 启用核心插件（最小集）
obsidian plugin:enable id=daily-notes
obsidian plugin:enable id=templates
obsidian plugin:enable id=file-recovery
obsidian plugin:enable id=backlink
obsidian plugin:enable id=outgoing-link
obsidian plugin:enable id=tag-pane
obsidian plugin:enable id=graph
obsidian plugin:enable id=properties # Obsidian 1.4+ 的属性面板
# 可选：启用 Bases（1.9+）
obsidian plugin:enable id=bases
```
**推荐社区插件**（AI 协作友好）：
| 插件 ID | 用途 | 何时需要 |
|---------|------|---------|
| `obsidian-git` | Git 集成 | 永远需要（vault 备份） |
| `templater-obsidian` | 高级模板（JS 可执行） | 动态模板 |
| `dataview` | 查询语言 | 还没迁移到 Bases |
| `tasks` | 高级任务管理 | 重度 GTD 用户 |
| `calendar` | 日历侧栏 | 频繁用每日笔记 |
| `advanced-uri` | URI 命令增强 | 脚本化自动化 |
```bash
# 批量安装
for p in obsidian-git templater-obsidian tasks calendar; do
obsidian plugin:install id=$p enable
done
```
### 场景 3 · 动态调用 Obsidian 内部命令
`obsidian command id=...` 可以执行**任意** Obsidian 命令，相当于 UI 层的自动化：
```bash
# 拆分工作区（左侧文件树 + 右侧编辑）
obsidian command id="workspace:split-vertical"
# 打开快速切换器
obsidian command id="switcher:open"
# 打开命令面板（不常用，因为命令面板本身是交互式 UI）
obsidian command id="command-palette:open"
# 切换 Reading View
obsidian command id="markdown:toggle-preview"
# 折叠所有标题
obsidian command id="editor:fold-all"
```
**发现命令 ID**：`obsidian commands | less` 或 `obsidian commands filter=<prefix>`。
### 场景 4 · 模板驱动的笔记创建
```bash
# 1. 先看有哪些模板
obsidian templates
# 2. 预览模板内容
obsidian template:read name="project-kickoff" resolve title="Alpha"
# 3. 基于模板创建新笔记（通过 create + content）
CONTENT=$(obsidian template:read name="project-kickoff" resolve title="Alpha")
obsidian create path="10-Projects/alpha/README.md" content="$CONTENT" open
```
### 场景 5 · CSS Snippet 自动切换（深色/浅色模式）
```bash
# 检测系统时间切换不同的 CSS snippet
HOUR=$(date +%H)
if [ "$HOUR" -ge 19 ] || [ "$HOUR" -lt 7 ]; then
obsidian snippet:enable name="dark-extra"
obsidian snippet:disable name="light-extra"
else
obsidian snippet:enable name="light-extra"
obsidian snippet:disable name="dark-extra"
fi
```
### 场景 6 · 快捷键审计
```bash
# 查自定义过的快捷键（避免冲突）
obsidian hotkeys verbose format=json | jq '.[] | select(.custom == true)'
# 查没有快捷键绑定的命令（发现可以加快捷键的命令）
obsidian hotkeys all format=json | jq '.[] | select(.hotkey == null)'
```
---
## 与其他技能的协作
| 场景 | 链路 |
|-----|------|
| 启用 Daily Notes 前置 | obsidian-plugins → **obsidian-daily** |
| 启用 Bases 前置 | obsidian-plugins（`plugin:enable id=bases`）→ **obsidian-bases** |
| 启用 Templates 前置 | obsidian-plugins → **obsidian-daily**（daily template） |
| 启用 File Recovery 前置 | obsidian-plugins → **obsidian-history** |
| 推荐插件清单 | obsidian-plugins + **obsidian-workflow-pkm** |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `plugin:install` 失败 | 处于 Restricted Mode | `plugins:restrict off` |
| 社区插件 ID 写错 | 大小写/连字符敏感 | 先 `plugins filter=community` 查正确 ID |
| `command id=...` 无效 | 命令 ID 写错 | `commands filter=<prefix>` 查询 |
| Template 变量未解析 | 没加 `resolve` 参数 | `template:read name=<n> resolve` |
| Templates 插件找不到模板 | 模板文件夹没配 | Settings → Templates → Template folder location |
| 切主题后样式错乱 | 新主题与某 snippet 冲突 | 临时 `snippet:disable` 所有 |
| 社区插件升级后命令失效 | 插件 API 变更 | `plugin:reload` 或重启 Obsidian |
| Restricted Mode 下 agent 脚本报错 | Community 插件全部禁用 | 脚本增加 `plugins:restrict` 检查 |
plugins/obsidian/skills/obsidian-search/SKILL.md
+185
View File
@@ -0,0 +1,185 @@
---
name: obsidian-search
description: Obsidian vault 全文搜索与链接图谱分析。触发场景：搜索笔记内容、查反链/出链、体检图谱健康度（孤立笔记 orphans、断头笔记 deadends、未解析链接 unresolved）、AI 回答前做语义召回（RAG）。触发词：搜索笔记、找笔记、反链、出链、孤立笔记、图谱体检、知识库体检。不用于 tag 查询（obsidian-meta）或 Bases 结构化查询（obsidian-bases）。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Search · 搜索与图谱分析
> 官方 `obsidian` CLI 的搜索与链接分析子集。让 AI agent 能像读取一个知识图谱数据库一样理解你的 vault。
---
## 何时使用
- 全文搜索笔记内容（关键词、正则、限定文件夹）
- 找到一篇笔记的**反链**（谁引用了我）或**出链**（我引用了谁）
- **图谱健康度体检**：找出孤立笔记、没有出链的断头、未解析的坏链
- 在 AI agent 做问答/总结前，**先做语义召回**，把最相关的几篇文章喂给模型
## 不用于
- 查找含某 **tag** 的笔记 → **obsidian-meta** (`tags`, `tag name=<tag> verbose`)
- 查询 frontmatter **property** → **obsidian-meta** (`properties`, `property:read`)
- 按 Bases 视图结构化查询 → **obsidian-bases**
---
## 命令速查
### 全文搜索
```bash
obsidian search query="云原生" # 基础全文搜索
obsidian search query="云原生" path="10-Projects" # 限定文件夹
obsidian search query="云原生" limit=20 # 限制结果数
obsidian search query="云原生" case # 区分大小写
obsidian search query="云原生" total # 只返回匹配计数
obsidian search query="云原生" format=json # JSON 输出（agent 友好）
obsidian search:context query="云原生" # 搜索 + 显示匹配行上下文
obsidian search:context query="云原生" format=json
obsidian search:open query="云原生" # 在 Obsidian 中打开搜索面板
```
### 出链 / 反链
```bash
obsidian links file="云原生运行时经济学" # 当前笔记出链
obsidian links file=<name> total # 只返回出链数
obsidian backlinks file=<name> # 反链（tsv 默认）
obsidian backlinks file=<name> counts # 含每个反链的引用次数
obsidian backlinks file=<name> format=json # JSON 输出
obsidian backlinks file=<name> total # 反链总数
```
### 图谱健康度（三件套）
```bash
obsidian orphans # 孤立笔记（没有任何反链 = 没人引用我）
obsidian orphans total # 仅返回数量
obsidian orphans all # 含非 markdown 文件
obsidian deadends # 断头笔记（没有任何出链 = 我没引用任何人）
obsidian deadends total
obsidian unresolved # 未解析链接（链接指向不存在的笔记）
obsidian unresolved counts # 含每个坏链的引用次数
obsidian unresolved verbose # 含源文件
obsidian unresolved format=json
```
---
## AI Agent 最佳实践
### 场景 1 · 做问答前的语义召回
AI agent 回答用户问题时，不要只凭记忆编造，而要先做召回：
```bash
# Step 1: 全文搜索，拿到 top-20 候选
obsidian search:context query="<用户问题关键词>" limit=20 format=json
# Step 2: 根据匹配摘要挑 3~5 篇最相关的，逐篇 read
obsidian read file="<候选 1>"
obsidian read file="<候选 2>"
# Step 3: 基于检索到的内容回答，并标注来源
```
这是 **RAG（Retrieval-Augmented Generation）的 CLI 实现**，无需向量数据库。
### 场景 2 · 知识库季度体检
每季度跑一次"三件套"健康检查，清理知识库：
```bash
# 孤立笔记（可能是废稿，或需要补反链）
obsidian orphans format=json > /tmp/orphans.json
# 断头笔记（需要补充关联阅读）
obsidian deadends > /tmp/deadends.txt
# 未解析链接（笔记被删除或重命名导致的坏链）
obsidian unresolved verbose format=json > /tmp/unresolved.json
```
**处理建议**（交给 AI agent 分类）：
| 类型 | 判定 | 处理 |
|------|------|------|
| 孤立笔记 | 正文 > 200 字 | 读内容，找相关主题补反链 |
| 孤立笔记 | 正文 ≤ 200 字 | 可能是废稿，移到 `00-Inbox/` 待清理 |
| 断头笔记 | 永久笔记（`50-Zettel/`） | 违反 Zettelkasten 原则，**必须补出链** |
| 断头笔记 | 日常笔记 | 一般可接受 |
| 未解析链接 | 指向已删除笔记 | 删除或修复链接 |
| 未解析链接 | 指向未来笔记（占位） | 保留，或创建占位笔记 |
### 场景 3 · 重命名前的安全检查
```bash
# 准备把 "旧标题" 改名为 "新标题"
obsidian backlinks file="旧标题" format=json # 先看谁引用我
# 如果反链数 > 0，且文件是 markdown 链接而非 wikilink，需要手动修复
# wikilink [[旧标题]] 会被 obsidian move 自动更新
# markdown [链接](旧标题.md) 需要手动替换
obsidian move path="50-Zettel/旧标题.md" to="50-Zettel/新标题.md"
```
### 场景 4 · 为新笔记找"相关阅读"
```bash
# 写完一篇新笔记后，自动找出 vault 中相关的旧笔记
TITLE="云原生运行时经济学"
KEYWORDS=("云原生" "运行时" "成本" "密度")
for kw in "${KEYWORDS[@]}"; do
obsidian search query="$kw" limit=5 format=json
done
# 由 agent 合并去重，挑出 top-3 ~ 5 篇，在新笔记末尾插入 "## 相关阅读" 区块
```
---
## Agent 写入模式：把搜索结果转成笔记
```bash
# 搜索 + 写入结果到一篇"检索报告"
QUERY="虚拟线程"
obsidian create path="99-Log/search-${QUERY}-$(date +%Y%m%d).md" content="# 检索报告: ${QUERY}
生成时间: $(date '+%Y-%m-%d %H:%M')
## 全文匹配
$(obsidian search:context query=\"${QUERY}\" limit=20)
## 反链分析
（针对 top-3 笔记的反链分析）
"
```
---
## 与其他技能的协作
| 前置 → 当前 → 后继 | 典型链路 |
|------------------|---------|
| **obsidian** → obsidian-search → **obsidian-meta** | 先发现 vault，再搜索定位，再读 frontmatter |
| **obsidian-search** → **obsidian-meta** | 搜索后用 tags 做二次筛选 |
| **obsidian-search** → **obsidian-workflow-pkm** | 搜索结果作为 Zettelkasten 补链、MOC 构建的输入 |
| **obsidian-search** → **obsidian** (`read`) | 搜索召回 → 逐篇精读 |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `search` 结果太多 | 未加 `limit` | `limit=20 path=<folder>` 双重限定 |
| `backlinks` 为空但确实有引用 | 用的是 markdown 链接而非 wikilink | `search query="[文件名]"` 兜底 |
| `orphans` 把每日笔记也列进来 | daily note 一般无人引用 | 在 agent 逻辑里过滤 `90-Daily/` 路径 |
| `unresolved` 出现"未来占位" | 预先写了 `[[未创建的笔记]]` | 占位是 Zettelkasten 合法模式，不要自动删 |
plugins/obsidian/skills/obsidian-tasks/SKILL.md
+218
View File
@@ -0,0 +1,218 @@
---
name: obsidian-tasks
description: 管理 Obsidian vault 中基于 Markdown 复选框（`- [ ]`/`- [x]`）的任务清单与 GTD 工作流：跨文件列出/筛选任务、切换单条任务状态、项目进度统计、收集-处理-执行流程。触发词：todo、待办、任务清单、完成任务、GTD、任务状态。不用于 Linear/飞书任务（linear/lark-task），不用于 frontmatter status 字段（obsidian-meta）。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Tasks · 任务清单管理
> 基于 Markdown 复选框语法 `- [ ]` / `- [x]` 的任务管理子集。每个任务 = 笔记某一行。适合 GTD（Getting Things Done）与 Zettelkasten 流程化任务。
---
## 何时使用
- 列出 vault 中**所有任务**（跨文件）
- 筛选**未完成**（todo）或**已完成**（done）的任务
- 按**状态字符**筛选（`- [ ]` 待办、`- [x]` 完成、`- [/]` 进行中、`- [?]` 存疑等）
- **切换单个任务**状态（ref = `path:line`）
- 配合每日笔记做 GTD 收集/回顾流程
## 不用于
- Linear issue → **linear** 技能
- 飞书任务 → **lark-task** 技能
- Frontmatter 级别的 `status: done` → **obsidian-meta**（那是笔记级状态，不是任务级）
- 任务的视觉化看板 → **obsidian-bases** + obsidian-tasks
---
## 命令速查
### 列出任务
```bash
obsidian tasks # vault 所有任务（text 默认）
obsidian tasks todo # 只列未完成
obsidian tasks done # 只列已完成
obsidian tasks verbose # 按文件分组，含行号
obsidian tasks format=json # JSON 输出（agent 友好）
obsidian tasks total # 仅返回任务总数
obsidian tasks file="项目Alpha" # 某文件的任务
obsidian tasks path="10-Projects/alpha/README.md"
obsidian tasks active # 当前激活文件的任务
obsidian tasks daily # 今天每日笔记的任务
obsidian tasks status="/" # 按自定义状态字符筛选（进行中）
obsidian tasks status="?" # 存疑
obsidian tasks status="!" # 重要
obsidian tasks status="-" # 取消
```
### 操作单个任务
```bash
# 方式 1：用 ref（path:line）
obsidian task ref="10-Projects/alpha/README.md:42" toggle
obsidian task ref="10-Projects/alpha/README.md:42" done
obsidian task ref="10-Projects/alpha/README.md:42" todo
obsidian task ref="10-Projects/alpha/README.md:42" status="/"
# 方式 2：用 file + line
obsidian task file="项目Alpha" line=42 done
# 方式 3：操作每日笔记
obsidian task daily line=7 toggle
```
---
## Task Emoji Shorthand 约定（社区标准）
Obsidian Tasks 插件广泛使用的状态字符：
| 字符 | 含义 | 渲染 |
|-----|------|------|
| ` ` | 待办 | `- [ ]` |
| `x` | 已完成 | `- [x]` |
| `/` | 进行中 | `- [/]` |
| `?` | 存疑/需澄清 | `- [?]` |
| `!` | 重要/关键 | `- [!]` |
| `-` | 已取消 | `- [-]` |
| `>` | 已转发/委派 | `- [>]` |
| `<` | 已调度（计划中） | `- [<]` |
CLI 的 `status="<char>"` 参数支持这些自定义字符。
---
## AI Agent 最佳实践
### 场景 1 · 每日任务收集（GTD 收集阶段）
每天早晨，扫描所有来源把任务汇总到当天每日笔记：
```bash
# 1. 收集昨天未完成的任务
obsidian tasks todo format=json > /tmp/open-tasks.json
# 2. 提取 vault 中所有 "TODO:" "FIXME:" "XXX:" 标记（这些不是正式 task）
obsidian search query="TODO:" limit=50 format=json
obsidian search query="FIXME:" limit=50 format=json
# 3. 由 agent 分类后，写入今天的每日笔记（见 obsidian-daily 技能）
obsidian daily:append content="\n## 今日任务\n- [ ] 处理 TODO: ...\n- [ ] 继续昨日未完成: ..."
```
### 场景 2 · 周回顾（Weekly Review）
GTD 的核心仪式，每周一次：
```bash
# 1. 本周已完成（展示成就）
obsidian tasks done verbose format=json > /tmp/done-this-week.json
# 2. 未完成且超期 7+ 天的任务（僵尸任务，需要决策）
obsidian tasks todo verbose format=json > /tmp/stale-tasks.json
# 3. 由 agent 生成周报
obsidian create path="99-Log/weekly-$(date +%Y-W%V).md" content="# 周回顾\n..."
```
### 场景 3 · 项目进度检查
```bash
# 某项目的完成度
obsidian tasks path="10-Projects/alpha/README.md" total # 总数
obsidian tasks path="10-Projects/alpha/README.md" done total # 已完成数
# 计算百分比后写回 frontmatter（配合 obsidian-meta）
# progress = done / total * 100
obsidian property:set name=progress value=65 type=number file="项目Alpha"
```
### 场景 4 · AI 生成任务的注入规范
当 AI agent 为用户拆解任务时，输出格式应遵循：
```markdown
## AI 拆解任务 · 2026-04-09
来源：用户需求"重构认证模块"
拆解方式：按 PR 颗粒度，每个任务 < 2h
- [ ] 📖 阅读现有认证中间件代码
- [ ] 🧪 补充现有逻辑的单元测试（无则写）
- [ ] ✂️ 抽取 Token 验证为独立函数
- [/] 🔧 引入 JWT 库替换自研实现
- [ ] 📝 更新 API 文档
- [ ] ✅ 回归测试
```
**约定**：
- Emoji 前缀标注任务类型（📖 阅读 / 🧪 测试 / ✂️ 重构 / 🔧 开发 / 📝 文档 / ✅ 验证）
- 带 `/`（进行中）的任务至多 1 个（WIP 限制）
- 每个任务自描述，不依赖上下文才能理解
### 场景 5 · 跨笔记任务聚合视图
```bash
# 把所有 `50-Zettel/` 下的待办聚合到一个 MOC 笔记
obsidian tasks path="50-Zettel" todo verbose format=json > /tmp/zettel-tasks.json
# 写入 MOC
obsidian create path="60-MOC/open-research-questions.md" content="# 待解决的研究问题\n..."
```
---
## Bash 脚本范式：完整的 Daily Standup
```bash
#!/bin/bash
# 每日站会助手：生成今日状态
TODAY=$(date +%Y-%m-%d)
YESTERDAY=$(date -d "yesterday" +%Y-%m-%d 2>/dev/null || date -v -1d +%Y-%m-%d)
echo "# Daily Standup · ${TODAY}"
echo ""
echo "## ✅ 昨日完成"
obsidian tasks done verbose format=json | \
jq -r '.[] | select(.completed >= "'${YESTERDAY}'") | "- \(.text) [\(.file):\(.line)]"'
echo ""
echo "## 🔄 今日计划"
obsidian tasks todo verbose format=json | \
jq -r '.[] | "- [ ] \(.text) [\(.file):\(.line)]"' | head -10
echo ""
echo "## 🚧 进行中"
obsidian tasks status="/" verbose format=json | \
jq -r '.[] | "- [/] \(.text) [\(.file):\(.line)]"'
```
---
## 与其他技能的协作
| 场景 | 链路 |
|-----|------|
| 每日任务注入 | obsidian-tasks → **obsidian-daily**（`daily:append`） |
| 项目进度同步 | obsidian-tasks（统计）→ **obsidian-meta**（`property:set progress`） |
| 任务可视化 | obsidian-tasks（写入）→ **obsidian-bases**（视图展示） |
| GTD 周回顾工作流 | **obsidian-workflow-pkm**（编排） |
| Linear 双向同步 | obsidian-tasks + **linear** |
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `task toggle` 不生效 | line 数字错了 | `tasks verbose` 先确认行号 |
| 缩进子任务被识别为独立任务 | Markdown 语法正常 | 接受：Obsidian 视子任务为独立 |
| 自定义 status 字符不显示 | 主题不支持 | 切换支持 Tasks Emoji 的主题 |
| tasks 命令返回空 | 路径/文件名错 | 用 `obsidian files` 先确认 |
| 每日任务重复出现 | 没有迁移机制 | 在每日模板里写"迁移昨日未完成"逻辑 |
| AI 滥加任务导致 WIP 爆炸 | 没设置上限 | 约定：进行中（`/`）至多 1~3 个 |
plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md
+535
View File
@@ -0,0 +1,535 @@
---
name: obsidian-workflow-pkm
description: Obsidian PKM 高阶编排工作流，组合调用多个 obsidian-* 子技能完成端到端流程：Inbox → Zettelkasten 原子化、MOC 主题地图构建、PARA 项目归档、Karpathy LLM-Wiki、周报/月报汇总、季度知识库体检、文献批量导入。触发词：整理 inbox、原子化笔记、构建 MOC、PARA 归档、LLM wiki、周报、月报、知识库体检、Zettelkasten 流程。单一原子操作请用对应专项子技能。检测到 .obsidian/ 时与核心技能同步激活。
---
# Obsidian Workflow · PKM 编排工作流
> 参照 `lark-workflow-*` 的命名与定位——这是**编排层**技能，调用各 `obsidian-*` 子技能完成端到端 PKM 流程。不用于单一原子操作，那些请用对应专项技能。
> **设计哲学**：每个工作流都是"**步骤序列 + 决策点 + 审计记录**"。AI agent 按步骤执行、在决策点等待用户确认（按项目 CLAUDE.md 规则）、所有写入记录到 daily note。
---
## 何时使用
| 场景 | 工作流 |
|------|--------|
| 清理 Inbox，把闪念变成永久笔记 | **Workflow 1: Inbox → Atomic → Permanent** |
| 从零构建一个主题的 MOC | **Workflow 2: MOC Builder** |
| 已完成项目归档到 Archive | **Workflow 3: PARA 归档** |
| 用 LLM 构建一个可维护的主题 Wiki | **Workflow 4: Karpathy LLM-Wiki** |
| 生成周报/月报 | **Workflow 5: 周报 / 月报汇总** |
| 季度知识库健康度体检 | **Workflow 6: 季度体检** |
| 从网页/PDF 批量导入并原子化 | **Workflow 7: 文献批量导入** |
---
## Workflow 1 · Inbox → Atomic → Permanent（Zettelkasten 核心流程）
**目标**：把 `00-Inbox/` 中的零散捕获，重写为 `50-Zettel/` 下的原子永久笔记，并自动补双向链接。
### 步骤
```
┌─────────────────┐
│ 1. 扫描 Inbox │ obsidian-search 列出 00-Inbox/ 所有文件
└────────┬────────┘
↓
┌─────────────────┐
│ 2. 逐篇读取 │ obsidian (read) 读原文
└────────┬────────┘
↓
┌─────────────────┐
│ 3. AI 原子化改写 │ 一个概念一篇笔记，标题 = 概念主干
└────────┬────────┘
↓
┌─────────────────┐ ┌ 决策点 ┐
│ 4. 用户确认 │ ───→│ 继续? │
└────────┬────────┘ └───┬────┘
↓ ↓
┌─────────────────┐
│ 5. 找相关永久笔记 │ obsidian-search (search + backlinks)
└────────┬────────┘
↓
┌─────────────────┐
│ 6. 创建新笔记 │ obsidian (create) 到 50-Zettel/
│ + 补反链 │ obsidian-meta (property:set refs)
└────────┬────────┘
↓
┌─────────────────┐
│ 7. 移除原 inbox │ obsidian (delete) 或 move 到 40-Archive
└────────┬────────┘
↓
┌─────────────────┐
│ 8. 审计日志 │ obsidian-daily (daily:append)
└─────────────────┘
```
### Bash 实现骨架
```bash
#!/bin/bash
# workflow_inbox_to_permanent.sh
set -e
# 审计函数
log() {
obsidian daily:append inline content="
- \`$(date +%H:%M)\` **inbox→permanent** $1"
}
# Step 1: 列 Inbox
INBOX_FILES=$(obsidian files folder="00-Inbox" ext=md format=json)
COUNT=$(echo "$INBOX_FILES" | jq 'length')
log "扫描 Inbox：共 ${COUNT} 个待处理文件"
# Step 2-6: 逐篇处理（由 agent 驱动）
echo "$INBOX_FILES" | jq -r '.[] | .path' | while read -r path; do
# Step 2: 读原文
ORIG=$(obsidian read path="$path")
# Step 3: AI 原子化（由 agent 完成，此处伪代码）
# - 分析 ORIG 内容，抽取 1~N 个原子概念
# - 为每个概念生成 ZID、标题、正文、建议标签
# Step 4: 展示拆解结果给用户，等待确认
echo "原文: $path"
echo "拆解为:"
echo " 1. 概念A - <标题>"
echo " 2. 概念B - <标题>"
read -p "继续? (y/N) " confirm
[ "$confirm" != "y" ] && continue
# Step 5: 搜索相关永久笔记
for concept in "$CONCEPTS"; do
RELATED=$(obsidian search query="$concept" path="50-Zettel" limit=5 format=json)
# agent 挑出 top-3 作为 refs
done
# Step 6: 创建永久笔记
ZID=$(date +%Y%m%d%H%M%S)
TITLE="<AI 生成的概念标题>"
CONTENT="---
zettel_id: ${ZID}
title: ${TITLE}
created: $(date +%Y-%m-%d)
source: ${path}
refs: [[[相关笔记1]], [[相关笔记2]]]
tags: [concept, <auto-tag>]
---
# ${TITLE}
<AI 原子化后的正文>
## 相关
- [[相关笔记1]]
- [[相关笔记2]]
"
obsidian create path="50-Zettel/${ZID} - ${TITLE}.md" content="$CONTENT"
# Step 7: 清理 Inbox 原文
obsidian move path="$path" to="40-Archive/inbox-$(date +%Y-%m)/$(basename "$path")"
log "处理完成：$path → 50-Zettel/${ZID}"
done
```
---
## Workflow 2 · MOC Builder（主题地图构建）
**目标**：给定一个主题关键词，自动从 vault 中召回相关笔记，组织成一个 MOC（Map of Content）入口。
### 步骤
```
1. 输入主题关键词（如"云原生运行时经济学"）
2. 多关键词扩展 → 由 agent 生成 3-5 个相关词
3. 对每个词跑 obsidian-search（限定到 50-Zettel/）
4. 合并去重 → 候选列表
5. 按笔记的 created 日期排序 → 时间线
6. 按 tags 聚类 → 主题分组
7. AI 生成 MOC 结构：
## 核心概念
## 实践案例
## 相关研究
## 时间线
8. 用户确认结构
9. 创建 60-MOC/<主题>.md
10. 为每篇被引用的笔记补反链（可选）
```
### 关键命令链
```bash
TOPIC="云原生运行时经济学"
KEYWORDS=("云原生" "运行时" "GraalVM" "虚拟线程" "冷启动")
# Step 3-4: 召回
RESULTS=""
for kw in "${KEYWORDS[@]}"; do
RESULTS+=$(obsidian search query="$kw" path="50-Zettel" limit=20 format=json)
done
# Step 5-6: 由 agent 合并/排序/聚类
# Step 9: 创建 MOC
obsidian create path="60-MOC/${TOPIC}.md" content="# MOC · ${TOPIC}
> 本主题地图由 AI 于 $(date +%Y-%m-%d) 构建
## 核心概念
- [[笔记1]]
- [[笔记2]]
## 实践案例
- [[笔记3]]
## 相关研究
- [[笔记4]]
## 时间线
- 2024-01 [[早期笔记]]
- 2025-06 [[中期笔记]]
- 2026-04 [[最新笔记]]
"
```
---
## Workflow 3 · PARA 归档
**目标**：扫描 `10-Projects/`，找出 `status: done` 且超过 14 天无更新的项目，批量移到 `40-Archive/`。
### 步骤
```bash
#!/bin/bash
# workflow_para_archive.sh
# 1. 找 done 状态项目
obsidian files folder="10-Projects" format=json | \
jq -r '.[] | .path' | while read -r path; do
# 2. 读 status
STATUS=$(obsidian property:read name=status path="$path" 2>/dev/null)
UPDATED=$(obsidian property:read name=updated path="$path" 2>/dev/null)
# 3. 判断是否符合归档条件
if [ "$STATUS" = "done" ]; then
DAYS_AGO=$(( ($(date +%s) - $(date -d "$UPDATED" +%s)) / 86400 ))
if [ "$DAYS_AGO" -gt 14 ]; then
# 4. 先检查反链（确保没有活跃项目仍在引用）
BACKLINKS=$(obsidian backlinks path="$path" total)
if [ "$BACKLINKS" -gt 0 ]; then
echo "⚠ 跳过（有 ${BACKLINKS} 个反链）：$path"
continue
fi
# 5. 用户确认（按项目 CLAUDE.md 规则）
read -p "归档 $path ? (y/N) " confirm
[ "$confirm" != "y" ] && continue
# 6. 移到 Archive
NEW_PATH="40-Archive/$(basename $(dirname $path))/$(basename $path)"
obsidian move path="$path" to="$NEW_PATH"
# 7. 审计
obsidian daily:append inline content="
- 📦 归档项目：$path → $NEW_PATH"
fi
fi
done
```
---
## Workflow 4 · Karpathy LLM-Wiki（AI 驱动主题 Wiki）
**目标**：针对一个研究主题，用 LLM 自动收集 → 综合 → 结构化成一份可维护的 Wiki。
> 参考：Karpathy《LLM Knowledge Bases in Obsidian》
### 步骤
```
1. 输入主题 + 10~20 个初始源（URL / PDF / 论文）
2. 对每个源：
- 下载/读取内容
- AI 提炼：核心观点 + 关键事实 + 术语表
- 写入 20-Literature/<source>.md
3. 综合阶段：
- AI 读所有 Literature 笔记
- 生成 Wiki 大纲（章节结构）
- 用户确认大纲
4. 写作阶段：
- 按大纲逐章生成内容
- 每个事实标注来源（[[20-Literature/xxx]]）
- 写入 30-Resources/wiki-<topic>.md
5. 迭代：
- 用户提新问题 → AI 查 Literature 补答
- 用户贡献新源 → Step 2~4 增量更新
6. 维护：
- 每次更新在 frontmatter 记录 `last_updated`
- 每月跑一次"过期源检测"（URL 404 / 事实过时）
```
### SCHEMA.md 片段（告诉 agent 如何维护 Wiki）
```markdown
## Wiki 维护约定
- Wiki 文件位于 `30-Resources/wiki-<topic>.md`
- 每个事实必须有 `[[20-Literature/xxx]]` 来源标注
- Frontmatter 必须包含：
- `topic: <主题>`
- `last_updated: <日期>`
- `sources_count: <数字>`
- `open_questions: <list>`
- 更新 Wiki 时，只追加或修订，不删除旧段落（保留版本演化）
```
---
## Workflow 5 · 周报 / 月报汇总
**目标**：自动从每日笔记、完成任务、git log、PR 列表中生成周报。
```bash
#!/bin/bash
# workflow_weekly_report.sh
WEEK=$(date +%Y-W%V)
LAST_MONDAY=$(date -d "last monday" +%Y-%m-%d 2>/dev/null || date -v -mon +%Y-%m-%d)
# 1. 收集本周每日笔记内容
DAILY_CONTENT=""
for i in {0..6}; do
DATE=$(date -d "${LAST_MONDAY} +${i} days" +%Y-%m-%d 2>/dev/null)
CONTENT=$(obsidian read path="90-Daily/${DATE}.md" 2>/dev/null)
DAILY_CONTENT+="$CONTENT\n\n"
done
# 2. 收集已完成任务
DONE=$(obsidian tasks done verbose format=json)
# 3. 收集搜索关键词（AI 写作/代码/会议/学习）
WRITING=$(obsidian search:context query="写作" limit=10 format=json)
MEETINGS=$(obsidian search:context query="会议" limit=10 format=json)
# 4. AI 生成周报
REPORT="# 周报 · ${WEEK}
## ✅ 本周完成
<agent 从 DONE 提取>
## 📝 主要产出
<agent 从 DAILY_CONTENT 提取>
## 🧠 学习与思考
<agent 从 DAILY_CONTENT 的晚间回顾提取>
## 📅 下周计划
<agent 从未完成任务推导>
"
# 5. 写入 vault
obsidian create path="99-Log/weekly-${WEEK}.md" content="$REPORT" open
```
---
## Workflow 6 · 季度知识库体检
**目标**：三件套 + 元数据一致性检查 + 归档建议。
### 检查项
```bash
# 1. 图谱健康三件套
obsidian orphans format=json > /tmp/q-orphans.json
obsidian deadends format=json > /tmp/q-deadends.json
obsidian unresolved verbose format=json > /tmp/q-unresolved.json
# 2. 元数据一致性
obsidian files format=json | jq -r '.[] | .path' | while read -r p; do
# 检查每篇是否有 created 字段
obsidian property:read name=created path="$p" 2>/dev/null || echo "MISSING_CREATED: $p"
# 检查每篇是否有 tags
obsidian property:read name=tags path="$p" 2>/dev/null || echo "MISSING_TAGS: $p"
done > /tmp/q-metadata.txt
# 3. Tag 体系审计
obsidian tags counts sort=count format=json > /tmp/q-tags.json
# 由 agent 找出：低频 tag、命名不一致、未层级化
# 4. 归档建议
obsidian files folder="10-Projects" format=json | \
jq -r '.[] | .path' > /tmp/q-projects.txt
# 由 agent 读每个项目的 status + updated，提 done + stale 归档建议
# 5. 生成体检报告
obsidian create path="99-Log/health-$(date +%Y-Q$((($(date +%m)-1)/3+1))).md" content="$REPORT"
```
### 输出报告模板
```markdown
# 知识库季度体检 · 2026-Q2
## 🧪 体检结论
- 总笔记数：X
- 孤立笔记：X（占 Y%）
- 断头笔记：X
- 未解析链接：X
- 元数据缺失：X
## 🔴 高危问题
- ...
## 🟡 优化建议
- ...
## 🟢 健康指标
- ...
## 行动项（自动生成 task）
- [ ] 清理 N 篇孤立笔记
- [ ] 修复 N 个未解析链接
- [ ] 合并 N 个低频 tag
```
---
## Workflow 7 · 文献批量导入
**目标**：从网页/PDF 批量导入到 `20-Literature/`，每篇自动生成：摘要、关键词、与现有知识库的关联。
```bash
# 依赖：Web Clipper 或 obsidian-advanced-uri 插件
# 简化流程：
URLS=("https://..." "https://..." "https://...")
for url in "${URLS[@]}"; do
# 1. 下载原文（用 Bash curl 或 Clipper）
CONTENT=$(curl -s "$url" | <html-to-markdown>)
# 2. AI 提炼
SUMMARY="<AI 生成的 300 字摘要>"
KEYWORDS="<AI 生成的关键词列表>"
# 3. 找已有相关笔记
RELATED=""
for kw in $KEYWORDS; do
RELATED+=$(obsidian search query="$kw" limit=5 format=json)
done
# 4. 创建 Literature 笔记
TS=$(date +%Y%m%d%H%M%S)
obsidian create path="20-Literature/${TS}-$(slugify).md" content="---
type: literature
title: <原文标题>
source: ${url}
created: $(date +%Y-%m-%d)
tags: [literature, ${KEYWORDS}]
related: [$(agent 填充)]
---
## 摘要
${SUMMARY}
## 关键词
${KEYWORDS}
## 原文要点
<AI 提炼的 bullet points>
## 与现有知识库的关联
- [[相关笔记 1]]
- [[相关笔记 2]]
## 原文链接
${url}
"
done
```
---
## 通用工作流约定
### 1. 决策点 × 步骤 × 审计
每个工作流都是 `执行 → 决策点 → 审计`：
- **执行**：由 agent 自动调用各 obsidian-* 技能
- **决策点**：在"写入前"、"删除前"、"移动前"三类操作必须等待用户确认（项目 CLAUDE.md 规则 4）
- **审计**：每个写入操作在 `obsidian-daily`（日志）+ `99-Log/ai-actions-<date>.md`（结构化记录）
### 2. 安全栏杆
- 批量操作前 **git checkpoint**（或 `obsidian-history` 手动快照）
- 批量操作前 **`obsidian sync off`**（避免同步抖动）
- Agent 一次只能动 1 个工作流；不能并发两个写入 workflow
### 3. 命名约定
- 工作流脚本：`workflow_<name>.sh`，放在 vault 根的 `99-Log/scripts/` 或用户 `~/.claude/scripts/`
- 工作流日志：`99-Log/workflow-<name>-YYYYMMDD.md`
- 工作流模板：`70-Templates/workflow-<name>.md`
---
## 与其他 obsidian-* 技能的调用关系
```mermaid
graph TD
WF[obsidian-workflow-pkm]
CORE[obsidian 核心]
SEARCH[obsidian-search]
META[obsidian-meta]
TASKS[obsidian-tasks]
DAILY[obsidian-daily]
BASES[obsidian-bases]
HIST[obsidian-history]
WF --> CORE
WF --> SEARCH
WF --> META
WF --> TASKS
WF --> DAILY
WF --> BASES
WF --> HIST
DAILY -.审计日志.-> WF
HIST -.检查点.-> WF
```
---
## 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| 工作流中途失败导致状态不一致 | 没有事务 | 先 git checkpoint；失败后从 checkpoint 恢复 |
| Agent 在决策点没等用户 | 没实现交互 | 脚本用 `read -p`，Claude Code 用 AskUserQuestion |
| 批量处理把同一笔记处理两次 | 没用 idempotent 标记 | 处理完在 frontmatter 加 `processed_by: inbox_workflow` |
| MOC 构建召回漏掉笔记 | 关键词单一 | 用 3~5 个扩展词 + 标签 + 出/反链三路召回 |
| 周报漏数据 | daily note 没写 | 先跑 `obsidian files folder=90-Daily` 检查覆盖 |
| 归档误移有反链的项目 | 没检查 backlinks | 归档前必须 `backlinks total == 0` 断言 |
| Literature 导入重复 | 未去重 | 用 URL hash 做 ID，frontmatter `source_hash` |
| LLM-Wiki 越改越乱 | 没版本化 | 每次大改前 git commit + `last_updated` 更新 |
---
## 参考
- **Andrej Karpathy** · LLM-Powered Knowledge Bases in Obsidian
- **Addo Zhang** · Obsidian Skills for AI Agents（Medium 2026.2）
- **Tiago Forte** · PARA Method
- **Niklas Luhmann** · Zettelkasten
- **Nick Milo** · Linking Your Thinking (LYT) + Maps of Content
- **dsebastien** · 16 Practical AI Use Cases with Obsidian
plugins/obsidian/skills/obsidian/SKILL.md
+242
View File
@@ -0,0 +1,242 @@
---
name: obsidian
description: 当前目录（或任一上级目录）存在 `.obsidian/` 文件夹，或项目 CLAUDE.md 含 obsidian/vault/知识库关键词时，主动激活整个 obsidian-* 技能族。本技能为核心入口：vault 发现、笔记 CRUD（read/create/append/move/delete）、建立 AI 协作约定文件（SCHEMA.md）。触发词：obsidian、vault、知识库、wikilink、笔记库。专项操作请路由到对应 obsidian-* 子技能。
---
# Obsidian · 核心技能
> vault 发现、笔记 CRUD、AI 协作约定层的入口。专项能力请跳转到对应 `obsidian-*` 子技能。
---
## 0. Vault 自动检测 SOP
**以下信号出现时主动激活，无需用户明确请求**：
| 检测项 | 置信度 |
|-------|-------|
| 当前目录或上级目录存在 `.obsidian/` 文件夹 | ⭐⭐⭐⭐⭐ |
| 项目 CLAUDE.md 含 `obsidian`/`vault`/`知识库` 关键词 | ⭐⭐⭐⭐ |
| 目录存在 `*.canvas` 或 `*.base` 文件 | ⭐⭐⭐⭐ |
| 根目录有 `SCHEMA.md`/`AGENTS.md` 且存在大量 `.md` 文件 | ⭐⭐⭐⭐⭐ |
| 用户话语含 `[[wikilink]]`/`PARA`/`Zettelkasten`/`MOC` | ⭐⭐⭐ |
**检测到 vault 后的标准动作**：
```bash
# 1. 确认 vault 身份
obsidian vaults
obsidian vault info=path
# 2. 查找约定文件（关键上下文）
obsidian read file="SCHEMA" 2>/dev/null || \
obsidian read file="AGENTS" 2>/dev/null || \
obsidian read file="CLAUDE" 2>/dev/null || \
obsidian read file="README" 2>/dev/null
# 3. 没有约定文件 → 主动建议用户创建（见本文档第 5 章 SCHEMA.md 模板）
# 4. 按用户意图路由到对应子技能（见第 2 节速查表）
```
---
## 1. 心智模型
- **Vault = 磁盘上一个普通文件夹**，里面是 `.md` 纯文本笔记
- **不需要数据库、不需要云服务**，可以直接用任何编辑器读写
- **官方 `obsidian` CLI** 通过本地协议与桌面应用通信，能做一切 Obsidian 内置操作
- **AI Agent 友好性**：文件纯文本可自由读写；vault 语义由 SCHEMA.md / AGENTS.md 承载，agent 读一次即可理解整个知识库
---
## 2. 子技能速查
| 场景 | 子技能 | 代表命令 |
|-----|-------|---------|
| 全文搜索、反链/出链、图谱健康度（orphans/deadends/unresolved） | **obsidian-search** | `search / backlinks / orphans` |
| tags、frontmatter properties、aliases、bookmarks | **obsidian-meta** | `tags / property:set / aliases` |
| Markdown 任务清单（`- [ ]`）、GTD | **obsidian-tasks** | `tasks / task toggle` |
| 每日笔记读写、晨间模板、晚间回顾 | **obsidian-daily** | `daily / daily:append / daily:read` |
| Obsidian Bases 数据库视图（1.9+） | **obsidian-bases** | `bases / base:query / base:create` |
| 版本历史、误删恢复、Obsidian Sync | **obsidian-history** | `history / sync / diff` |
| 插件、主题、快捷键、Templates | **obsidian-plugins** | `plugin:enable / theme:set / commands` |
| 端到端 PKM 工作流（Inbox→Zettel/MOC/PARA/周报/体检） | **obsidian-workflow-pkm** | 组合调用上述技能 |
---
## 3. 命令语法与基础约定
```
obsidian <command> [key=value ...]
obsidian vault=<name> <command> [key=value ...] # 指定 vault
```
**三条铁律**：
1. **`file=<name>` 按 wikilink 名称解析**（无需扩展名，全局查找）；**`path=<path>` 是精确路径**（如 `folder/note.md`）
2. 含空格的值必须引号：`name="My Note"`，内容换行用 `\n`，Tab 用 `\t`
3. **AI agent 输出格式一律用 `format=json`**，便于 `jq` 解析
---
## 4. Vault 基础命令速查
### Vault 管理
```bash
obsidian vaults # 列出所有已知 vault
obsidian vault # 当前 vault 信息
obsidian vault info=path # 只返回 vault 路径
obsidian vault=<name> <command> # 切换到指定 vault 执行命令
obsidian reload # 重载 vault
obsidian version # Obsidian 版本
```
### 文件列表与导航
```bash
obsidian files # 列出 vault 所有文件
obsidian files folder=<path> # 按文件夹筛选
obsidian files ext=md # 按扩展名筛选
obsidian files total # 只返回文件数
obsidian folders # 列出所有文件夹
obsidian folder path=<path> info=files # 某文件夹详情
obsidian recents # 最近打开的文件
obsidian tabs # 当前打开的标签页
obsidian random:read # 随机读一篇（灵感触发）
```
### 文件读与查看
```bash
obsidian read file=<name> # 按名读取
obsidian read path=<path> # 按路径读取
obsidian file file=<name> # 文件元信息（路径、大小、时间戳）
obsidian outline file=<name> format=md # 标题层级结构
obsidian wordcount file=<name> # 字数统计
```
### 文件写入与变更
```bash
obsidian create name="新笔记" content="# 标题\n\n正文" open
obsidian create path="Projects/Alpha/README.md" template="project"
obsidian append path=<path> content="\n- 追加的一行"
obsidian prepend path=<path> content="## 新的顶部章节\n\n"
obsidian move path="old/note.md" to="new/folder/note.md" # 自动更新 wikilinks
obsidian rename file=<name> name="新名称"
obsidian delete file=<name> # 移到回收站
obsidian delete file=<name> permanent # 永久删除（危险）
obsidian open file=<name> newtab # 在 Obsidian 中打开
```
> ⚠ **只读优先**：AI agent 写入操作默认走 `append`/`create`；`move`/`delete` 前先 `backlinks` 检查依赖。
---
## 5. AI Agent 协作原则
### 约定先行
Agent 进入 vault 第一件事：读 **SCHEMA.md**（或 AGENTS.md / CLAUDE.md）。它定义：
- 文件夹语义（`10-Projects/` 是什么）
- 命名规则
- Frontmatter 规范
- 标签体系
- Agent 行为准则
**没有 SCHEMA.md 的 vault → 主动建议用户创建**（见下方模板）。
### 安全与可追溯
- **只读优先**：查询命令（search/backlinks/tags/properties）永远安全，优先使用
- **写入前备份**：批量 move/rename 前先 `git commit` 或 `obsidian sync off` + history checkpoint
- **可审计**：每次 AI 写入在 `daily:append` 留一条记录，或写到 `99-Log/agent-actions-<date>.md`
- **避免魔改 frontmatter**：只新增字段，不删已有字段（除非用户明确要求）
### 命名与链接建议
- 笔记名：`<YYYYMMDDHHmm> <标题>` 或 `<主题> - <副标题>`，避免特殊字符 `:/\|?*`
- 文件夹：编号前缀便于排序（`00-Inbox/`、`10-Projects/`、`50-Zettel/`）
- **wikilinks 优先**于 markdown links：`[[Note Title]]` 可被 `obsidian move` 自动更新
---
## 6. SCHEMA.md 模板
创建到 vault 根目录（AI agent 每次进入 vault 必读）：
```bash
obsidian create path="SCHEMA.md" content="$(cat <<'EOF'
# Vault Schema
> AI agent 协作约定。修改本文件后请同步到项目 CLAUDE.md。
## 组织范式
- 框架：PARA + Zettelkasten 混合
- 主语言：简体中文
## 文件夹语义
| 路径 | 含义 | 准入规则 |
|------|------|---------|
| 00-Inbox/ | 未整理捕获 | 任何原始笔记 |
| 10-Projects/ | 有截止日期的项目 | 含 project_name/ 子目录 |
| 20-Areas/ | 长期责任领域 | 常绿笔记 |
| 30-Resources/ | 参考资料 | 主题知识 |
| 40-Archive/ | 已完成/过期 | 从其他目录移入 |
| 50-Zettel/ | 原子永久笔记 | 单一概念，双向链接 |
| 90-Daily/ | 每日笔记 | 自动生成 |
| 99-Log/ | Agent 操作日志 | 机器写入，永久保留 |
## Frontmatter 规范
\`\`\`yaml
---
title: 笔记标题
created: 2026-04-09
updated: 2026-04-09
status: draft | active | done | archived
tags: [tag1, tag2]
source: url | book | meeting
aliases: []
---
\`\`\`
## AI Agent 行为准则
1. 进入 vault 必须先读本文件
2. 写入前必须创建/维护 frontmatter
3. 删除/重命名前先 backlinks 检查
4. 每次写操作在 99-Log/agent-actions-<date>.md 追加记录
5. 永远不修改 .obsidian/ 目录下的任何文件
EOF
)" open
```
---
## 7. Windows 环境注意事项
| 项目 | 说明 |
|------|------|
| Obsidian 配置文件 | `%APPDATA%\obsidian\obsidian.json` |
| 桌面应用依赖 | 必须保持 Obsidian 桌面版运行，CLI 通过本地协议通信 |
| 路径分隔符 | CLI 内部使用正斜杠 `/`，即便在 Windows 上 |
| 中文文件名 | Git Bash 默认 UTF-8，双引号包裹即可 |
---
## 8. 常见陷阱
| 现象 | 原因 | 对策 |
|------|------|------|
| `file=<name>` 找到了错的笔记 | 名称不唯一 | 改用 `path=<full/path.md>` |
| `create` 报错 "vault not found" | 未指定 vault | 加 `vault=<name>` 或先 `obsidian vaults` |
| `append` 没有换行 | 未加 `\n` 前缀 | `content="\n- 新行"` |
| 批量操作后 wikilinks 失效 | 使用了系统 `mv` 而非 `obsidian move` | 永远用 `obsidian move`，它自动更新链接 |
| CLI 命令不响应 | Obsidian 桌面应用未运行 | 先启动 Obsidian |
| Agent 反复修改同一字段 | 没读 SCHEMA.md | 进入 vault 第一步必须读约定文件 |