企业官网建设流程全解析

obsidian-skills 测试指南：从零跑通第一组用例的完整教程

【免费下载链接】obsidian-skillsAgent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.项目地址: https://gitcode.com/GitHub_Trending/ob/obsidian-skills

obsidian-skills 是给 AI 代理用的 Obsidian 技能套件，它教会代理怎么写 Obsidian Markdown、Bases、JSON Canvas，怎么调 Obsidian CLI 和网页提取工具。这些技能本质是一组"行为说明书"，代理照着写文件，但说明书里的细节稍有一点没执行对，生成的文件在 Obsidian 里就打不开。这篇 obsidian-skills 测试教程带你从空白环境开始，一步步把第一组测试用例跑起来，再慢慢扩展到五个技能。

1️⃣ 30分钟配好环境，先跑通第一条命令

先 clone 仓库到本地：

git clone https://gitcode.com/GitHub_Trending/ob/obsidian-skills

然后准备三样东西：一个装着几篇真实笔记的 Obsidian 库、装好并保持打开状态的 Obsidian CLI（CLI 要连着一个运行中的 Obsidian 实例才能工作）、以及 defuddle 命令行工具（npm install -g defuddle一条命令搞定）。

这里容易踩坑：CLI 相关的测试如果 Obsidian 没开着，命令会直接失败，别以为是技能写错了。

建一个专门的测试库：新建一个空库 TestVault，往里丢三篇笔记——一篇带 frontmatter 和标签的、一篇带[[双链]]的、一篇随便写写的。后面所有用例都拿它当靶子，别污染你的主力库。

2️⃣ 写下你的第一个最小用例

测试 obsidian-skills 有个特点：技能是 SKILL.md 这样的提示文档，不是可执行代码。所以"跑一个用例"的意思是：给代理一条指令 → 让它产出文件 → 检查产出 → 拿 Obsidian 亲自打开确认。

我们第一个用例就挑 JSON Canvas。给代理的指令可以是"生成一个只有两个文本节点、一条边的画布"。然后打开skills/json-canvas/SKILL.md，按里面的清单核对产出：

• JSON 能被正常解析（最基本要求）
• 每个节点的id都是 16 位十六进制，且节点和边之间没有重复
• 每条边的fromNode/toNode都能在 nodes 里找到
• 最后把.canvas文件丢进测试库双击打开，不报错就算过

最空的合法画布长这样，可以作为产出的对照基线：

{ "nodes": [], "edges": [] }

跑一下你会发现，新手最常挂的第一条就是"JSON 解析不过"——多半是文本节点里的换行没写成\n，而是把字面的反斜杠+n 写进去了。

3️⃣ 扩展覆盖：五种技能各一套检查项

用例通过之后，就可以按"文件格式"把覆盖扩到其余技能。简单说，每种格式记住 2~3 个最关键的检查点就够了，剩下的细节各 SKILL.md 里都有现成的清单。

文件类：Markdown、Bases、Canvas

• obsidian-markdown：让代理写一篇带 frontmatter、[[Note#Heading]]链接、> [!note]标注框的笔记，重点看 wikilink 和嵌入语法有没有拼错，然后切到阅读视图扫一眼渲染效果。
• obsidian-bases：让代理建一个带 filters 和 formulas 的.base，重点查两处——YAML 里带引号或冒号的字符串加引号了没；order里引用的formula.X在formulas里真的定义了吗。再打开 Obsidian 看视图能不能渲染出来。
• json-canvas：除了第一个用例的清单，再补一条"边界"检查：加节点时位置要和已有节点留 50~100px 间距，别重叠。

命令类：CLI 和 Defuddle

这两个不用查文件结构，直接看输出：

• obsidian-cli：走一遍"创建 → 读取 → 追加 → 再读取"的往返流程，确认create写进去的内容和read读出来的完全一致；再跑一条search看看结果条数对不对。
• defuddle：拿一篇真实博客页跑defuddle parse <url> --md，看导航和广告有没有被剥干净，再用-p title对照页面标题。注意它专门不处理.md结尾的链接，别拿 markdown 源文件测它。

4️⃣ 让 GitHub Actions 帮你盯回归

用例攒到五六个之后，每次改完 SKILL.md 都手动跑一遍就累了，这时候把回归交给 CI。

你不需要复杂的框架：CI 里做两件事就够——一是跑一段脚本，对代理产出的.canvas文件做 JSON 解析、ID 唯一性、边引用完整性这三项检查，对.base文件做 YAML 解析；二是检查 SKILL.md 文件本身没被改坏（frontmatter 里的 name 和 description 还在）。

配置就写在仓库的 workflow 文件里，触发器选 push 和 pull_request。具体字段名对着文档填就行，这里不贴完整脚本——结构很简单，一个解析检查步骤加一个报告步骤。

好处是：你半夜改了技能描述，第二天早上 PR 里就能看到红绿。CI 挂的时候先看哪一步红，基本就能定位到是哪个技能的产出格式变了。

5️⃣ 踩坑排错：三种最常见的翻车现场

文件打不开、报语法错误

九成是这两个原因。Canvas：ID 重复、边引用了不存在的节点、文本里换行转义写错。Bases：字符串里有冒号没加引号（displayName: Status: Active这种必挂）、公式里引号嵌套没处理好。拿报错的文件对着 SKILL.md 里的 Troubleshooting 一节逐条排，基本都能定位。

渲染出来了，但"看着不对"

这类问题 CI 查不出来，只能人眼过。最典型的是 Bases 里两个日期相减得到的是 Duration 而不是数字，直接对它取整会报错，正确姿势是先取.days再操作；还有属性可能为空时没写if()兜底，整列直接崩。

命令跑通了，但结果和预期不符

先检查环境变量而不是怀疑技能：Obsidian 开着没？是不是最近切换过库（CLI 默认操作最近聚焦的库，多库场景记得加vault=参数）？defuddle 拿到的标题为空时，先确认目标页面本身有没有 title。

到这里，你手里应该已经有一套能跑的用例了：五个技能各一两条，本地手动能过，CI 里自动盯着。接下来不用追求用例数量，每改一版技能就把这套跑一遍，哪个红了查哪个——obsidian-skills 的测试就是这种"小而勤"的节奏，用久了你会发现，大部分格式问题在第一次手动核对时就已经被记进你的检查清单里了。

【免费下载链接】obsidian-skillsAgent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.项目地址: https://gitcode.com/GitHub_Trending/ob/obsidian-skills