Obsidian 插件开发如何用 Frontmatter Checker 完成测试打包

一个 Obsidian 插件从能运行到可发布，中间还隔着元数据校验、命令测试、构建产物和安装回归。本文以 Frontmatter Checker 为例，按目录、入口、命令、测试、打包和本地安装逐步验收，帮助插件作者把“本机能打开”提升为可重复交付的工程流程。文中只讨论可复现的步骤，不把单次结果扩展成产品承诺；每个结论都标注前提、证据和无法覆盖的边界。读者可以先完成最小验证，再按自己的版本、权限和数据补充实验。

前几篇我们把 Obsidian 装好，接上了画图、剪藏、同步和 Claudian，也建立了 CLAUDE.md、AGENTS.md 和 00-索引.md。

最后一步，是让 AI 帮我们开发一个小插件。

很多人听到“开发 Obsidian 插件”，第一反应是 TypeScript、Node.js、构建命令和发布市场。它们确实存在，但对于第一个插件，最重要的不是一次学完全部开发工具，而是把需求说清楚、用官方模板开始、在测试 Vault 验收，再决定要不要发布。

这篇以 Frontmatter Checker 为例。它的功能非常克制：检查当前笔记有没有 frontmatter，有就提示，没有就提醒补充；不自动改正文，不删除文件，不上传内容。

这正适合作为第一个 AI 辅助插件，因为每一项行为都能在界面上验证。

一、先理解插件要解决的问题

Frontmatter 是 Markdown 文件开头的一段 YAML 元数据，通常位于两个 --- 之间，例如：

---
title: "一篇测试笔记"
source: "https://example.com/article"
status: draft
tags:
  - AI
---

# 一篇测试笔记

它不是每篇 Obsidian 笔记都必须有的内容。Obsidian 可以打开没有 frontmatter 的普通 Markdown 文件，所以插件不能把“没有 frontmatter”当成错误，更不能未经确认直接修改笔记。

我们先把需求写成可验收的行为：

场景	预期结果	不允许的行为
当前笔记有 frontmatter	提示“当前笔记已有 frontmatter”	不改正文
当前笔记没有 frontmatter	提示需要补充元数据	不自动插入 YAML
当前没有打开笔记	提示先打开一篇 Markdown 笔记	不扫描整个 Vault
frontmatter 格式异常	提示需要人工检查	不覆盖原文
用户重复执行命令	每次只检查当前文件	不创建重复字段

插件名称可以叫 Frontmatter Checker，命令名称可以叫“检查当前笔记 Frontmatter”。名称和界面文本以后都能改，先保证行为边界清晰。

二、开发前准备测试 Vault

第一步：复制一个空的测试 Vault

不要直接在已经保存多年资料的真实 Vault 里试插件。新建一个空 Vault，或者复制一个不包含私密资料的副本，例如：

D:\Obsidian\FrontmatterChecker-Test

测试 Vault 里只放三篇笔记：

01-有frontmatter.md
02-无frontmatter.md
03-格式异常.md

示例内容可以是虚构文本。不要把客户资料、企业内部文档、同步配置、API Key 或个人登录信息放进测试文件。

第二步：准备官方 sample plugin

使用 Obsidian 官方提供的 sample plugin 作为起点，入口可以从 Obsidian 官方开发文档或官方示例仓库进入。当前开发模板的目录和构建命令可能随版本更新，交给 AI 操作前让它先核对 README 和官方文档。

不要直接复制网上一段来路不明的 main.js 到真实 Vault，也不要只因为插件能显示一个按钮，就认为它没有其他文件操作。

开发项目通常包含源码、依赖和构建配置；Obsidian 测试 Vault 中的插件目录只需要运行时文件。常见的运行时结构是：

FrontmatterChecker-Test/
└─ .obsidian/
   └─ plugins/
      └─ frontmatter-checker/
         ├─ manifest.json
         ├─ main.js
         └─ styles.css

main.ts 或其他源码文件可以留在开发项目中，不要把“还不能被 Obsidian 加载的源码文件”误当成最终插件。最终以当前官方模板生成的构建产物和文档要求为准。

三、把需求交给 AI，但要求它先分析

第一条 Prompt 不要直接说“帮我写一个插件”。先让 AI 把需求拆开：

我要开发一个 Obsidian 插件，名称为 Frontmatter Checker。

请先不要写代码，先根据当前版本的 Obsidian 官方插件开发文档和官方 sample plugin，输出：
1. 这个插件需要监听或调用哪些 Obsidian API。
2. 如何判断当前是否打开了一篇 Markdown 笔记。
3. 如何判断当前笔记是否存在 frontmatter。
4. 如何在 Obsidian 界面中提供一个可执行命令。
5. 哪些行为可能修改文件、读取全 Vault 或访问网络。
6. 需要在哪些测试场景中验收。

功能范围只有：
- 检查当前活动笔记。
- 有 frontmatter 时提示已经存在。
- 没有 frontmatter 时提醒用户补充标题、来源、主题和状态。
- 没有打开笔记时提示先打开笔记。

安全限制：
- 不删除、移动、重命名、覆盖或自动修改任何文件。
- 不扫描整个 Vault。
- 不读取、展示或记录登录信息、授权信息、Token、Cookie 和私密配置。
- 不发起网络请求，不上传笔记内容。
- 不自动安装依赖，不使用清单以外的第三方服务。

请先返回需求理解、拟修改的文件、风险点和测试清单，等待我确认后再实现。

这一步的价值是让 AI 先暴露自己的理解。如果它一开始就提出“自动给所有笔记补 frontmatter”“批量扫描整个 Vault”，说明需求已经跑偏，要先纠正再写代码。

四、让 AI 基于官方模板实现

确认需求后，再使用第二条 Prompt：

请基于已经核对过的 Obsidian 官方 sample plugin 实现 Frontmatter Checker，不要凭空发明项目结构。

实现要求：
1. 提供一个命令“检查当前笔记 Frontmatter”。
2. 命令只检查当前活动文件。
3. 当前没有活动文件时，用 Obsidian 的界面提示用户先打开一篇笔记。
4. 当前文件不是 Markdown 笔记时，提示不处理该文件。
5. 通过 Obsidian 当前版本推荐的元数据读取方式判断 frontmatter 是否存在；如果 API 无法确认，提示人工检查，不要修改文件。
6. 有 frontmatter 时显示确认提示。
7. 没有 frontmatter 时显示需要补充的字段：title、source、topic、status，但只提醒，不自动插入。
8. 不增加批量扫描、自动修复、删除、移动、重命名、网络请求或外部上传功能。

请把每次改动按文件说明，并告诉我：
- manifest.json 做了什么
- main.js 或源码做了什么
- styles.css 是否真的需要
- 如何构建
- 构建后哪些文件复制到测试 Vault
- 在 Obsidian 里具体点哪里验证

如果 AI 使用了源码文件和构建文件，先让它解释二者关系。不要把一段代码直接粘贴进真实 Vault，也不要为了“能跑”接受它偷偷加入网络请求或全库扫描。

五、让 AI 做一次安全审计

代码生成以后，还没有到测试阶段。先让 AI 逐行检查可能改变本地文件或上传内容的逻辑：

请对 Frontmatter Checker 做一次安全和范围审计，不要修改代码，先输出审计报告。

重点检查：
1. 是否调用了删除、移动、重命名、覆盖或写入 Markdown 文件的 API。
2. 是否调用了批量读取整个 Vault 的 API。
3. 是否发起 fetch、XMLHttpRequest、WebSocket 或其他网络请求。
4. 是否读取或记录登录信息、授权信息、Token、Cookie、环境变量和私密配置。
5. 是否安装或引入了需求之外的依赖。
6. 是否能在没有打开笔记时稳定提示，而不是报错。
7. 是否把“无法判断”错误地当成“没有 frontmatter”。
8. 是否把源码中的测试路径、个人路径或真实资料写入日志。

请给出：
- 发现的风险
- 对应文件和代码位置
- 是否需要修改
- 修改后如何在测试 Vault 验证

只允许这个插件检查当前活动笔记并显示提示。未经我明确确认，不要自动修改、删除、移动或覆盖任何文件。

AI 的静态审计不是安全证明，但它能先筛出明显问题。你还要自己查看构建后的文件，尤其是没有被 Prompt 重点提到的依赖和初始化逻辑。

六、把插件复制到测试 Vault

完成构建后，在测试 Vault 中创建插件目录：

.obsidian/plugins/frontmatter-checker/

只复制当前版本官方模板要求的运行时文件，通常包括：

manifest.json
main.js
styles.css  （如果插件确实使用样式）

不要把包含个人路径、构建缓存、依赖目录和调试日志的整个开发目录复制进去。复制前先让 AI 明确列出最终文件：

请只整理 Frontmatter Checker 的本地测试发布目录。

保留 manifest.json、构建后的 main.js、实际被使用的 styles.css，以及一份不含私密信息的 README.md。不要包含 node_modules、缓存、个人路径、日志、Token、授权信息或测试 Vault 的笔记内容。

不要发布到 Obsidian 社区插件市场，不要提交 GitHub，不要上传压缩包。只告诉我整理后的本地目录和复制到另一个测试 Vault 的方法。

如果 manifest.json 中的插件 ID、名称和目录名不匹配，Obsidian 可能无法识别或启用插件。这里不要照抄旧教程里的字段值，按当前官方 sample plugin 和 Obsidian 开发文档检查格式。

七、在 Obsidian 界面中启用

不同版本的设置名称可能略有差异，常见操作如下：

关闭并重新打开测试 Vault，或在设置中重新加载社区插件列表。
进入设置，打开“社区插件”或对应的第三方插件管理页面。
确认 Frontmatter Checker 出现在已安装插件列表中。
打开插件右侧的启用开关。
使用 Ctrl + P 打开命令面板，搜索“检查当前笔记 Frontmatter”。
打开一篇测试笔记，执行命令，观察 Obsidian 的提示信息。

如果插件没有出现，先检查三个地方：

插件目录是否正好位于当前 Vault 的 .obsidian/plugins/ 下。
manifest.json 是否位于插件目录根部。
main.js 是否是构建后的文件，而不是还没编译的 TypeScript 源码。

排查时不要把真实 Vault 复制来复制去。始终优先在测试 Vault 中修正路径和构建问题。

八、按场景验收功能

场景一：有 frontmatter 的笔记

打开 01-有frontmatter.md，执行命令。预期看到“当前笔记已有 frontmatter”之类的提示。关闭笔记、重新打开，检查文件内容没有变化。

场景二：没有 frontmatter 的笔记

打开 02-无frontmatter.md，执行命令。预期看到补充 title、source、topic、status 的提醒，但文件开头不应凭空出现 YAML。

场景三：没有活动笔记

切换到文件列表或空白页，再执行命令。预期是友好提示，而不是报错、卡死或扫描整个 Vault。

场景四：格式异常

把测试文件的 YAML 分隔线写错，重新执行命令。插件应该提示“无法确认，请人工检查”或等价信息，而不是把异常内容当成正常 frontmatter，也不应覆盖原文件。

场景五：重复执行和切换文件

先检查有 frontmatter 的笔记，再切换到没有 frontmatter 的笔记，连续执行几次。每次结果都应该跟当前活动文件一致，不能缓存上一次笔记的状态。

场景六：观察文件变化

在资源管理器或 Obsidian 编辑器中观察测试文件的修改时间和正文。一次只读检查不应该产生正文改动。若开发者工具或日志输出包含本地私密路径，也要在打包前清理。

九、用代码和文件检查辅助验收

界面验证之后，再做一次文件级检查。可以让 AI 生成检查报告，但命令执行结果要自己确认：

请检查 Frontmatter Checker 的最终本地目录，范围只限于 manifest.json、main.js、styles.css 和 README.md。

输出以下内容：
1. 实际存在的文件列表。
2. 是否包含删除、移动、重命名、覆盖或写入笔记的调用。
3. 是否包含网络请求、外部域名、Token、密码、Cookie 或个人路径。
4. 是否包含 node_modules、缓存和无关测试资料。
5. manifest.json 的 ID、名称、版本和入口文件是否与当前官方模板要求一致。

不要修改、删除或移动任何文件。不要读取测试 Vault 以外的内容。

你也可以在开发项目中搜索明显的危险调用，例如文件删除、重命名、写入和网络请求相关代码。但关键词搜索只能作为初筛，不能替代代码阅读和界面测试。第三方依赖也要看它们的用途，不能只看主文件。

十、常见问题和处理方式

插件列表里没有插件

通常是目录层级、文件名或 manifest.json 格式问题。确认不是多套了一层目录，例如：

错误：plugins/frontmatter-checker/frontmatter-checker/manifest.json
正确：plugins/frontmatter-checker/manifest.json

具体字段以当前官方文档为准，不要用网络文章里的旧版本示例硬改。

命令面板里没有命令

先确认插件已启用，再重新加载 Vault。检查插件初始化时是否注册了命令，以及命令注册代码是否因为当前文件为空而提前退出。

有 frontmatter 却提示没有

可能是 YAML 格式、文件类型、元数据缓存或插件读取方式的问题。先在测试笔记中使用最小的标准示例，再检查当前 Obsidian API 的返回值。不要为了让提示“看起来正确”直接正则替换原文。

AI 想自动补字段

这是功能范围漂移。自动补全可以作为另一个需求，但应当单独设计预览、确认、撤销和备份。当前版本只做检查和提醒，先不要加入写文件能力。

十一、打包和发布边界

测试通过后，最终可以整理一个本地发布目录：

frontmatter-checker-release/
├─ manifest.json
├─ main.js
├─ styles.css
└─ README.md

如果需要复制到另一个本地测试 Vault，就把整个目录复制到对应的 .obsidian/plugins/ 下，再在 Obsidian 中启用。每次复制前检查插件 ID、版本和入口文件。

这篇文章的目标只是本地开发和测试，不包括自动发布到 Obsidian 社区插件市场，也不包括自动提交 GitHub。真正发布前，还要补充许可证、作者信息、隐私说明、兼容版本、构建过程和人工代码审查。

十二、企业级 AI 编程的边界

个人用 Claudian、Claude Code 或其他 AI 工具辅助开发时，最容易忽略的是代码上下文和本地文件权限。企业环境还要多做几层：

让 AI 只读取测试项目，不直接打开生产 Vault。
使用企业级 API 网关或统一模型接入层管理调用凭据、模型路由和预算。
对发送给模型的源码做脱敏，避免把客户资料、内部域名和密钥混进上下文。
保留需求版本、代码变更、测试结果和发布审批记录。
对插件能访问的文件范围做最小化配置，重要 Vault 不默认启用未经审查的第三方插件。

如果通过上游 API 或其他 API 中转服务调用模型，配置时只在受控设置中填写 Key 和模型标识，文章、Prompt、日志和截图中使用占位符。模型接入稳定并不等于插件代码安全，二者要分别验收。

十三、完整验收清单

需求验收

只检查当前活动笔记。
有 frontmatter 时给出提示。
无 frontmatter 时只提醒，不自动写入。
没有活动笔记时给出可理解的提示。
格式异常时不覆盖原文。

工程验收

使用当前 Obsidian 官方 sample plugin 或官方文档作为基础。
manifest.json、main.js 和可选的 styles.css 结构正确。
插件能在测试 Vault 中被发现、启用和停用。
命令面板能找到并执行检查命令。
切换文件后检查结果不会串到上一篇笔记。

安全验收

没有删除、移动、重命名、覆盖和自动写文件行为。
没有批量扫描整个 Vault 的逻辑。
没有网络请求和外部上传。
没有读取、记录或展示私密配置。
代码、日志和 README 中没有真实路径、Key、Token 和测试资料。
只在测试 Vault 中完成了首次验收。

总结

AI 开发 Obsidian 插件最可靠的顺序不是“先让 AI 写完，再看看能不能用”，而是：

明确需求
  -> 采用官方模板
  -> 只在测试 Vault 构建
  -> 先做安全审计
  -> 在 Obsidian 界面验收
  -> 整理最小运行时文件
  -> 人工决定是否发布

Frontmatter Checker 的功能很小，但它把一套完整方法走通了：AI 负责加速理解、编码和整理，你负责范围确认、测试和发布决策。

到这里，Obsidian 从安装、插件、剪藏、同步、AI 对话、规则文件到插件开发的五篇入门系列就完整了。真正能长期使用的知识库，不是插件越多越好，而是每一步都知道资料在哪里、AI 能做什么，以及出错后怎样恢复。

结论

本文给出了问题定位、配置或创作流程的可执行路径。实际结果仍取决于当前版本、权限和运行环境，提交前应按官方文档复核可变字段，并保留失败证据和回滚边界。