# Obsidian官方下场，文件就是Agent的API ## 概述 本期不追新星榜单，拆一组特殊来头的东西：Obsidian 官方打包上架的 Claude Code 插件 `obsidian-skills`（本机缓存版本 1.0.0），内含三个官方技能——`obsidian-markdown`、`obsidian-bases`、`json-canvas`；再用一个社区件 `obsidian-mermaid` 作对照。核心发现有三：官方在 SKILL.md 第一句就写"skills-compatible agents"而不提 Claude；三件全是零脚本的纯手册型技能，把官方文档镜像进上下文；而社区件走了完全相反的守则型路线。一个领域、两种流派，恰好凑成一篇 SKILL.md 写法教科书。以下全部分析基于本机装机实测的原文。 ## 一、这四件是怎么凑到一起的 先交代来源。本机安装路径暴露了身份：`/root/.claude/plugins/cache/obsidian-skills/obsidian/1.0.0/skills/`。也就是说，Obsidian 官方不是零散上架技能，而是打成了一个 Claude Code 插件包，一次带出三个技能，走插件市场分发，目前版本 1.0.0。 三个官方技能各管一种文件格式： ```mermaid flowchart TD AG["Agent 拿到任务"] AG --> S1 AG --> S2 AG --> S3 AG --> S4 subgraph OFF["官方插件三件"] S1["obsidian-markdown"] S2["obsidian-bases"] S3["json-canvas"] end S4["obsidian-mermaid 社区件"] S1 -->|写对 .md| MD S2 -->|建对 .base| BASE S3 -->|画对 .canvas| CANVAS S4 -->|渲染不炸| MM subgraph VAULT["Obsidian 仓库"] MD["笔记文件"] BASE["数据库视图"] CANVAS["无限画布"] MM["内嵌图示"] end ``` 拼起来看意图就很清楚了：一个 Agent 装上这套东西，等于拿到了“住进 Obsidian 仓库”的整套手艺——会写带 wikilink 和 callout 的笔记，会建笔记数据库视图，会生成画布板，画内嵌图也不会踩渲染坑。官方没有给 Agent 开任何 API，因为 Obsidian 的本质是本地纯文本文件，**文件格式本身就是 API**。这是所有本地优先软件做 Agent 集成时最聪明的一条路，而 Obsidian 是第一个把它做成官方插件的大厂（笔记软件范畴内）。 ## 二、主角拆解：obsidian-bases 逐段讲 四个里最值得逐行看的是 `obsidian-bases`。Bases 是 Obsidian 较新版本推出的笔记数据库功能：用 `.base` 后缀的 YAML 文件，把整个仓库里带特定标签/文件夹/属性的笔记聚合成表格、卡片、列表视图——相当于给文件系统装了一层查询引擎。 这份 SKILL.md 的结构是一条完整的“知识产线”： **第一段：一句话定位。** 开头是 "This skill enables skills-compatible agents to create and edit valid Obsidian Bases (.base) files including views, filters, formulas"。注意两个细节：一是主语是 "skills-compatible agents"——**通篇没有出现 Claude 字样**，这份手册是写给所有兼容 Agent Skills 规范的 Agent 的，Claude Code 只是读者之一；二是 "valid" 这个词，它预告了整份文档的核心目标不是“教思想”，而是保证产出物语法合法。 **第二段：总览与格式声明。** 两句话说清 Bases 是什么（"YAML-based files that define dynamic views of notes"），并点出 `.base` 文件也能内嵌进 Markdown 代码块——一句话堵住了 Agent 后面可能犯的存放位置错误。 **第三段：完整 Schema。** 直接给一个带注释的 YAML 全家福，把 `filters`、`formulas`、`properties`、`summaries`、`views` 五个顶层区块一次摆齐，每个字段旁边挂行内注释（`type: table | cards | list | map`）。这是手册型的典型手法：**一个带注释的骨架，胜过十段散文**。Agent 写文件时回翻这一段就能对齐结构。 **第四段起：分区块深挖。** 过滤器部分给了单条件、AND、OR、NOT、嵌套五种写法各配代码块；接着是两张大表——过滤运算符表（`==`、`!=`、`>` 直到逻辑非）和 `file.*` 文件属性全表（`file.mtime`、`file.tags`、`file.backlinks` 等十几个元数据字段）。尤其贴心的是专门列出三类属性的区分：笔记 frontmatter 属性、文件元数据属性、公式计算属性——这是 Bases 新手最容易混的概念，文档用“三选一”的方式先立框架。 **第五段：公式语言全量函数表。** 这是全文最重的部分，按类型分了十几张表：全局函数（`date()`、`now()`、`if()`、`icon()`）、字符串函数（`contains`、`slice`、`split`）、列表函数（`filter`/`map`/`reduce` 一应俱全，连 `acc` 归并都写了）。一张技能文件硬生生写成了语言规范。 **第六段：那个最重要的 IMPORTANT。** 全文的高光在这一段： > **IMPORTANT:** Duration does NOT support `.round()`, `.floor()`, `.ceil()` directly. You must access a numeric field first (like `.days`), then apply number functions. 后面紧跟正误对照：`(date(due_date) - today()).days` 是对的，`((date(due) - today()) / 86400000).round(0)` 标注 "WRONG - will cause error"。这一段的设计价值远超一张语法表——它预判了模型最可能犯的错（把日期差当数字直接运算），用大写警告加反例的方式在出错路径上提前设卡。给 LLM 写文档，**反例比正例更省 token**，因为它直接封死了幻觉的出口。 **第七段：四个完整示例。** Task Tracker、Reading List、Project Notes、Daily Notes Index，每个都是可直接落盘的成品 YAML，覆盖了表格、卡片、分组、汇总列、正则过滤文件名（`/^\d{4}-\d{2}-\d{2}$/.matches(file.basename)` 过滤日记）等典型场景。示例即测试用例，Agent 可以照抄改造，比从零组装可靠得多。 **结尾：References 尾链。** 挂了 `help.obsidian.md/bases/syntax`、`/bases/functions`、`/bases/views` 三个官方文档链接。这个尾巴有两层作用：给 Agent 一个“原文在哪”的出口，同时也是权威性声明——我这份手册不是民间口口相传，是官方文档的镜像。 ## 三、另外两件官方件：同模板，不同侧重 `obsidian-markdown` 和 `json-canvas` 与 bases 件共用同一个写作模板（一句话定位 → 总览 → 全量语法 → 示例 → References），但侧重不同。 **obsidian-markdown** 是四件里最“重”的——篇幅最长，覆盖了 Obsidian 方言的全部表面：`[[wikilink#标题#^块引用]]`、十三种 callout 类型表、可折叠 callout 的 `-`/`+` 后缀、`![[图片|300]]` 尺寸语法、PDF 嵌页 `![[doc.pdf#page=3]]`、frontmatter 属性类型表、`%%隐藏注释%%`、脚注、以及表格里竖线要转义 `\|` 这种细到牙缝的坑。它的定位其实是：**模型都会 Markdown，但不会 Obsidian 的方言**——所以通用语法（标题、列表、表格）一带而过，篇幅全砸在方言差异上。这是手册型技能的正确花钱方式。 **json-canvas** 有个容易被忽视的亮点：除了 JSON Canvas 1.0 规范全量搬运（四类节点、边的六种挂点、色板 "1"-"6"），它还附了两张规范里没有的表——**推荐节点尺寸**（小文本 200-300 × 80-150，文件预览 300-500 × 200-400）和**间距指南**（节点间留 50-100px、组内留 20-50px 内边距、坐标对齐 10/20 的倍数）。这是把“排版审美”也写进了规格，Agent 生成的画布因此不会出现节点叠成一团的惨案。另外它对最高频翻车点专门设卡：JSON 字符串里换行必须写 `\n`，写成 `\\n` 会渲染出字面的反斜杠和 n——并给了两个示例对照。小瑕疵是这个对照没有标明哪个是错例，读者要靠上文自己分辨，比 bases 件的 WRONG 标注略欠一档火候。 还有个命名细节：三件里只有它不带 `obsidian-` 前缀。因为 JSON Canvas 是 Obsidian 推动的**开放格式**（规范独立挂在 jsoncanvas.org），官方自己都刻意不让品牌绑死开放标准。门牌上的克制是一以贯之的。 ## 四、对照件：obsidian-mermaid，守则型的活标本 社区件 `obsidian-mermaid`（本机装在 `~/.claude/skills/`，个人技能）走的是完全相反的路线。它不教你 Mermaid 语法——默认你会——只列六条“必须遵守”和五条“禁止事项”，每条都带原因和正误代码对照： - 用 `flowchart` 不用 `graph`，原因是兼容性； - 换行用 `
` 不用 `
`，"may cause parsing errors in Obsidian"； - sequenceDiagram 里**禁用一切 style 语句**，这是 Obsidian 的实测坑，文档连报错信息的样子都复现给你看（"Parse error on line 28"）； - `mindmap` 语法在 Obsidian 里不受支持，直接别用； - 六节点以上必须用竖版 TD 布局，还给了决策标准（≤5 节点可用 LR，≥6 必须 TD）。 它甚至有“验证工作流”一节（先在 mermaid.live 调通 → 套兼容规则 → 粘进 Obsidian 实测）和一个支持度矩阵表（哪些图型全支持、哪些不支持 style）。另外它是四件里唯一用了**渐进式披露**的：正文末尾挂 `references/PATTERNS.md`，模板库下沉到子文件，正文只留守则。 对比一下就看出两种流派的分工： | | 手册型（官方三件） | 守则型（mermaid件） | |---|---|---| | 解决的问题 | 不会写 | 会写但会写错 | | 知识形态 | 全量规范+示例库 | 规则清单+反例库 | | token 成本 | 重（触发后数K常驻） | 轻 | | 适用领域 | 模型没见过的私有格式（.base/.canvas） | 模型自以为会的通用格式（Mermaid） | | 防幻觉手段 | 正确Schema先行 | WRONG/CORRECT对照设卡 | 选择的判据就一条：**这个领域模型的失败模式是“不会”还是“会错”**。`.base` 是 2025 年才出现的新格式，模型必然不会，所以官方写手册；Mermaid 是训练语料里的老熟客，模型不是不会而是自信地写出 Obsidian 不认的语法，所以守则比手册有效。官方三件里 markdown 件其实是个混合体——通用部分当手册写，方言坑（转义、嵌套代码块）部分已经在悄悄用守则的写法了。 ## 五、评测对比表 | 技能 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃 | 总评 | |------|-----------|---------|---------|---------|---------|------| | obsidian-bases | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★☆ | ★★★★☆ | **4.7** | | obsidian-markdown | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★★ | ★★★★☆ | **4.3** | | json-canvas | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | **4.3** | | obsidian-mermaid | ★★★☆☆ | ★★★★☆ | ★★★★☆ | ★★★★★ | ★★★☆☆ | **3.8** | 说明：实战效果基于本机对四份原文的可生成性评估（产出物为纯文本文件，无脚本依赖，生成即可用）；社区活跃度上官方插件有 Obsidian 团队背书，mermaid 件为个人技能无法验证热度，故保守给分。 **分维度排行榜：** - 最值得装：**obsidian-bases**——新格式+全量手册+坑位标注，三要素齐活，装了就能让 Agent 给仓库建索引视图； - 最被低估：**json-canvas**——那两张布局指南表是同类技能里罕见的“审美规格化”，做路线图、读书板的人直接受益； - 最有学习价值：**obsidian-mermaid**——想学守则型 SKILL.md 怎么写，四百行不到的它就是模板； - 最快见效：**obsidian-markdown**——零学习成本，装上之后 Agent 写的 callout 和 wikilink 立刻不出错。 ## 六、适用与不适用 **适合装**：已有成规模 Obsidian 仓库、想让 Agent 批量整理笔记/建数据库视图/生成画布板的人；用 Agent 写带 Mermaid 图的文档、受够了渲染报错的人；想研究 SKILL.md 写法的技能作者（这是本期隐藏彩蛋——四份原文本身就是两流派的范本库）。 **不适合**：不用 Obsidian 的人（markdown 件的方言知识也随仓库绑定，离开 wikilink 生态价值减半）；期待“Agent 操控 Obsidian 应用内操作”的人——这套技能只产出文件，不会帮你点应用菜单；Obsidian 版本较旧的用户——`.base` 是较新版本才支持的格式，老版本打不开产出物。 ## 七、安装与使用 官方三件以 Claude Code 插件形式分发，在 Claude Code 会话内运行： ``` /plugin ``` 在插件市场里搜索 `obsidian-skills`（发布方 obsidian，本机版本 1.0.0），安装后三个技能随插件自动挂载，触发词对准“写 Obsidian 笔记 / 建 base 视图 / 生成 canvas 画布”即可。社区件可用 skills 生态的检索工具定位后安装： ```bash npx skills find obsidian-mermaid ``` 或直接把技能目录复制进 `~/.claude/skills/`（本机即为此形态）。装完用一句话验证：让 Agent “给标签为 #book 的笔记建一个带阅读状态图标的卡片视图 base”，产出物落盘后在 Obsidian 里打开不出红字，即为验收通过。 ## 参考来源 1. [Obsidian Bases Syntax 官方文档](https://help.obsidian.md/bases/syntax) — obsidian-bases 技能 References 尾链所指的官方语法页 2. [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/) — json-canvas 技能遵循的开放格式规范 3. [obsidianmd/jsoncanvas](https://github.com/obsidianmd/jsoncanvas) — JSON Canvas 官方仓库，Obsidian 官方组织的开放格式项目 4. [Obsidian 基础格式语法](https://help.obsidian.md/syntax) — obsidian-markdown 技能 References 首条 5. 本机实测：`obsidian-skills` 插件 1.0.0 缓存目录及 `~/.claude/skills/obsidian-mermaid` 原文 — 本文全部逐段引用均出自上述四份 SKILL.md > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。