From 1e35ee4d9ffee2430a57ef56055bd699107c1bb3 Mon Sep 17 00:00:00 2001 From: SkyJourney Date: Fri, 1 May 2026 13:20:31 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20obsidian=20?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E6=97=8F=EF=BC=889=20=E4=B8=AA=E6=8A=80?= =?UTF-8?q?=E8=83=BD=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 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 --- .claude-plugin/marketplace.json | 5 + plugins/obsidian/.claude-plugin/plugin.json | 7 + .../obsidian/skills/obsidian-bases/SKILL.md | 266 +++++++++ .../obsidian/skills/obsidian-daily/SKILL.md | 248 ++++++++ .../obsidian/skills/obsidian-history/SKILL.md | 236 ++++++++ .../obsidian/skills/obsidian-meta/SKILL.md | 247 ++++++++ .../obsidian/skills/obsidian-plugins/SKILL.md | 284 ++++++++++ .../obsidian/skills/obsidian-search/SKILL.md | 185 ++++++ .../obsidian/skills/obsidian-tasks/SKILL.md | 218 +++++++ .../skills/obsidian-workflow-pkm/SKILL.md | 535 ++++++++++++++++++ plugins/obsidian/skills/obsidian/SKILL.md | 242 ++++++++ 11 files changed, 2473 insertions(+) create mode 100644 plugins/obsidian/.claude-plugin/plugin.json create mode 100644 plugins/obsidian/skills/obsidian-bases/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-daily/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-history/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-meta/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-plugins/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-search/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-tasks/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md create mode 100644 plugins/obsidian/skills/obsidian/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 65efa9d..c2b89d5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -14,6 +14,11 @@ "name": "memcore", "source": "./plugins/memcore", "description": "记忆体系核心引擎：memory-sync（全量同步）、memory-update（增量写入）、memory-lint（健康校验）" + }, + { + "name": "obsidian", + "source": "./plugins/obsidian", + "description": "Obsidian 知识库 AI 协作插件族：检测到 .obsidian/ 目录自动激活，含 vault 管理、搜索图谱、frontmatter、任务、每日笔记、Bases 数据库、版本历史、插件配置、PKM 编排工作流共 9 个技能" } ] } diff --git a/plugins/obsidian/.claude-plugin/plugin.json b/plugins/obsidian/.claude-plugin/plugin.json new file mode 100644 index 0000000..9cd91f7 --- /dev/null +++ b/plugins/obsidian/.claude-plugin/plugin.json @@ -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": "蚁熊团队" + } +} diff --git a/plugins/obsidian/skills/obsidian-bases/SKILL.md b/plugins/obsidian/skills/obsidian-bases/SKILL.md new file mode 100644 index 0000000..2e304ad --- /dev/null +++ b/plugins/obsidian/skills/obsidian-bases/SKILL.md @@ -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` + 手动验证字段 | diff --git a/plugins/obsidian/skills/obsidian-daily/SKILL.md b/plugins/obsidian/skills/obsidian-daily/SKILL.md new file mode 100644 index 0000000..fc43422 --- /dev/null +++ b/plugins/obsidian/skills/obsidian-daily/SKILL.md @@ -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} + +## 🌤 今日概览 +- 天气： +- 日程： +- 优先级： + +## ✅ 今日任务（迁移自昨日未完成） +$(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 插件并设置路径 | diff --git a/plugins/obsidian/skills/obsidian-history/SKILL.md b/plugins/obsidian/skills/obsidian-history/SKILL.md new file mode 100644 index 0000000..d69d68e --- /dev/null +++ b/plugins/obsidian/skills/obsidian-history/SKILL.md @@ -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= # 某文件的 Sync 版本历史 +obsidian sync:history file= total # 版本数 +obsidian sync:open file= # 在 Obsidian 中打开同步历史界面 +obsidian sync:read file= version=3 # 读取某 Sync 版本的内容 +obsidian sync:restore file= 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，只允许恢复一次 | diff --git a/plugins/obsidian/skills/obsidian-meta/SKILL.md b/plugins/obsidian/skills/obsidian-meta/SKILL.md new file mode 100644 index 0000000..c95d0c8 --- /dev/null +++ b/plugins/obsidian/skills/obsidian-meta/SKILL.md @@ -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= # 某文件的 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= # 某文件的所有属性 +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= # 某文件的别名 +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` | diff --git a/plugins/obsidian/skills/obsidian-plugins/SKILL.md b/plugins/obsidian/skills/obsidian-plugins/SKILL.md new file mode 100644 index 0000000..46f9538 --- /dev/null +++ b/plugins/obsidian/skills/obsidian-plugins/SKILL.md @@ -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 查询 +``` + +```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=`。 + +### 场景 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=` 查询 | +| Template 变量未解析 | 没加 `resolve` 参数 | `template:read name= resolve` | +| Templates 插件找不到模板 | 模板文件夹没配 | Settings → Templates → Template folder location | +| 切主题后样式错乱 | 新主题与某 snippet 冲突 | 临时 `snippet:disable` 所有 | +| 社区插件升级后命令失效 | 插件 API 变更 | `plugin:reload` 或重启 Obsidian | +| Restricted Mode 下 agent 脚本报错 | Community 插件全部禁用 | 脚本增加 `plugins:restrict` 检查 | diff --git a/plugins/obsidian/skills/obsidian-search/SKILL.md b/plugins/obsidian/skills/obsidian-search/SKILL.md new file mode 100644 index 0000000..167395a --- /dev/null +++ b/plugins/obsidian/skills/obsidian-search/SKILL.md @@ -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= 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= total # 只返回出链数 + +obsidian backlinks file= # 反链（tsv 默认） +obsidian backlinks file= counts # 含每个反链的引用次数 +obsidian backlinks file= format=json # JSON 输出 +obsidian backlinks file= 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=` 双重限定 | +| `backlinks` 为空但确实有引用 | 用的是 markdown 链接而非 wikilink | `search query="[文件名]"` 兜底 | +| `orphans` 把每日笔记也列进来 | daily note 一般无人引用 | 在 agent 逻辑里过滤 `90-Daily/` 路径 | +| `unresolved` 出现"未来占位" | 预先写了 `[[未创建的笔记]]` | 占位是 Zettelkasten 合法模式，不要自动删 | diff --git a/plugins/obsidian/skills/obsidian-tasks/SKILL.md b/plugins/obsidian/skills/obsidian-tasks/SKILL.md new file mode 100644 index 0000000..5e1f44c --- /dev/null +++ b/plugins/obsidian/skills/obsidian-tasks/SKILL.md @@ -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=""` 参数支持这些自定义字符。 + +--- + +## 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 个 | diff --git a/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md b/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md new file mode 100644 index 0000000..b3d46f9 --- /dev/null +++ b/plugins/obsidian/skills/obsidian-workflow-pkm/SKILL.md @@ -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="" + CONTENT="--- +zettel_id: ${ZID} +title: ${TITLE} +created: $(date +%Y-%m-%d) +source: ${path} +refs: [[[相关笔记1]], [[相关笔记2]]] +tags: [concept, ] +--- + +# ${TITLE} + + + +## 相关 +- [[相关笔记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/.md +3. 综合阶段： + - AI 读所有 Literature 笔记 + - 生成 Wiki 大纲（章节结构） + - 用户确认大纲 +4. 写作阶段： + - 按大纲逐章生成内容 + - 每个事实标注来源（[[20-Literature/xxx]]） + - 写入 30-Resources/wiki-.md +5. 迭代： + - 用户提新问题 → AI 查 Literature 补答 + - 用户贡献新源 → Step 2~4 增量更新 +6. 维护： + - 每次更新在 frontmatter 记录 `last_updated` + - 每月跑一次"过期源检测"（URL 404 / 事实过时） +``` + +### SCHEMA.md 片段（告诉 agent 如何维护 Wiki） + +```markdown +## Wiki 维护约定 + +- Wiki 文件位于 `30-Resources/wiki-.md` +- 每个事实必须有 `[[20-Literature/xxx]]` 来源标注 +- Frontmatter 必须包含： + - `topic: <主题>` + - `last_updated: <日期>` + - `sources_count: <数字>` + - `open_questions: ` +- 更新 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} + +## ✅ 本周完成 + + +## 📝 主要产出 + + +## 🧠 学习与思考 + + +## 📅 下周计划 + +" + +# 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" | ) + + # 2. AI 提炼 + SUMMARY="" + KEYWORDS="" + + # 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} + +## 原文要点 + + +## 与现有知识库的关联 +- [[相关笔记 1]] +- [[相关笔记 2]] + +## 原文链接 +${url} +" +done +``` + +--- + +## 通用工作流约定 + +### 1. 决策点 × 步骤 × 审计 + +每个工作流都是 `执行 → 决策点 → 审计`： + +- **执行**：由 agent 自动调用各 obsidian-* 技能 +- **决策点**：在"写入前"、"删除前"、"移动前"三类操作必须等待用户确认（项目 CLAUDE.md 规则 4） +- **审计**：每个写入操作在 `obsidian-daily`（日志）+ `99-Log/ai-actions-.md`（结构化记录） + +### 2. 安全栏杆 + +- 批量操作前 **git checkpoint**（或 `obsidian-history` 手动快照） +- 批量操作前 **`obsidian sync off`**（避免同步抖动） +- Agent 一次只能动 1 个工作流；不能并发两个写入 workflow + +### 3. 命名约定 + +- 工作流脚本：`workflow_.sh`，放在 vault 根的 `99-Log/scripts/` 或用户 `~/.claude/scripts/` +- 工作流日志：`99-Log/workflow--YYYYMMDD.md` +- 工作流模板：`70-Templates/workflow-.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 diff --git a/plugins/obsidian/skills/obsidian/SKILL.md b/plugins/obsidian/skills/obsidian/SKILL.md new file mode 100644 index 0000000..3c633a8 --- /dev/null +++ b/plugins/obsidian/skills/obsidian/SKILL.md @@ -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 [key=value ...] +obsidian vault= [key=value ...] # 指定 vault +``` + +**三条铁律**： + +1. **`file=` 按 wikilink 名称解析**（无需扩展名，全局查找）；**`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= # 切换到指定 vault 执行命令 +obsidian reload # 重载 vault +obsidian version # Obsidian 版本 +``` + +### 文件列表与导航 + +```bash +obsidian files # 列出 vault 所有文件 +obsidian files folder= # 按文件夹筛选 +obsidian files ext=md # 按扩展名筛选 +obsidian files total # 只返回文件数 + +obsidian folders # 列出所有文件夹 +obsidian folder path= info=files # 某文件夹详情 + +obsidian recents # 最近打开的文件 +obsidian tabs # 当前打开的标签页 +obsidian random:read # 随机读一篇（灵感触发） +``` + +### 文件读与查看 + +```bash +obsidian read file= # 按名读取 +obsidian read path= # 按路径读取 +obsidian file file= # 文件元信息（路径、大小、时间戳） +obsidian outline file= format=md # 标题层级结构 +obsidian wordcount file= # 字数统计 +``` + +### 文件写入与变更 + +```bash +obsidian create name="新笔记" content="# 标题\n\n正文" open +obsidian create path="Projects/Alpha/README.md" template="project" + +obsidian append path= content="\n- 追加的一行" +obsidian prepend path= content="## 新的顶部章节\n\n" + +obsidian move path="old/note.md" to="new/folder/note.md" # 自动更新 wikilinks +obsidian rename file= name="新名称" +obsidian delete file= # 移到回收站 +obsidian delete file= permanent # 永久删除（危险） + +obsidian open file= 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-.md` +- **避免魔改 frontmatter**：只新增字段，不删已有字段（除非用户明确要求） + +### 命名与链接建议 + +- 笔记名：` <标题>` 或 `<主题> - <副标题>`，避免特殊字符 `:/\|?*` +- 文件夹：编号前缀便于排序（`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-.md 追加记录 +5. 永远不修改 .obsidian/ 目录下的任何文件 +EOF +)" open +``` + +--- + +## 7. Windows 环境注意事项 + +| 项目 | 说明 | +|------|------| +| Obsidian 配置文件 | `%APPDATA%\obsidian\obsidian.json` | +| 桌面应用依赖 | 必须保持 Obsidian 桌面版运行，CLI 通过本地协议通信 | +| 路径分隔符 | CLI 内部使用正斜杠 `/`，即便在 Windows 上 | +| 中文文件名 | Git Bash 默认 UTF-8，双引号包裹即可 | + +--- + +## 8. 常见陷阱 + +| 现象 | 原因 | 对策 | +|------|------|------| +| `file=` 找到了错的笔记 | 名称不唯一 | 改用 `path=` | +| `create` 报错 "vault not found" | 未指定 vault | 加 `vault=` 或先 `obsidian vaults` | +| `append` 没有换行 | 未加 `\n` 前缀 | `content="\n- 新行"` | +| 批量操作后 wikilinks 失效 | 使用了系统 `mv` 而非 `obsidian move` | 永远用 `obsidian move`，它自动更新链接 | +| CLI 命令不响应 | Obsidian 桌面应用未运行 | 先启动 Obsidian | +| Agent 反复修改同一字段 | 没读 SCHEMA.md | 进入 vault 第一步必须读约定文件 |