obsidian-dev-rules

Obsidian 开发规则

Obsidian 通过两种方式扩展：插件（基于 Obsidian API 的 TypeScript）和主题/片段 （CSS）。此技能以 https://docs.obsidian.md 上的官方开发文档为参考，让你无需重新获取文档，就能构建和 审查 Obsidian 插件/主题。API 以 obsidian npm 包的形式提供；权威的入门示例是 obsidian-sample-plugin。

何时使用此技能

• 构建、调试或审查 Obsidian 插件（生命周期、命令、设置、UI、视图）。
• 通过 Vault API 读取/写入笔记；通过 Editor API 操作当前笔记。
• 订阅事件、注册 Markdown 后处理器 / 代码块处理器，或使用 CodeMirror 6 编辑器扩展。
• 构建主题（CSS 变量、theme.css、清单）或片段。
• 发布/提交插件或主题到社区目录。

参考索引 — 加载所需文件

文件	涵盖内容
references/plugin-basics.md	项目设置、manifest.json、插件生命周期（onload/onunload）、资源注册与清理、事件、开发工作流 / 热重载、调试
references/vault-and-editor.md	Vault API（read/cachedRead/create/modify/process/delete、TFile/TFolder、adapter、normalizePath）、Editor API、Markdown 后处理与代码块处理器、CodeMirror 6 编辑器扩展
references/ui.md	命令（回调变体、快捷键）、设置（PluginSettingTab、load/saveData、Setting 控件）、模态框（Modal/SuggestModal/FuzzySuggestModal）、视图（ItemView、registerView、工作区叶节点）、功能区/状态栏
references/themes-and-release.md	主题（CSS 变量、theme.css/manifest、body 类、片段）、提交插件和主题、开发者政策与指南

速查表

import { Plugin, Notice, MarkdownView, TFile, normalizePath } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    await this.loadSettings();
    this.addRibbonIcon('dice', 'Greet', () => new Notice('Hello!'));
    this.addCommand({ id: 'do-x', name: 'Do X', callback: () => {/* ... */} });
    this.addSettingTab(new MySettingTab(this.app, this));
    // Auto-cleaned on unload — always register through these:
    this.registerEvent(this.app.vault.on('modify', (f) => {/* ... */}));
    this.registerInterval(window.setInterval(() => {/* ... */}, 1000));
    this.registerDomEvent(document, 'click', () => {/* ... */});
  }
  onunload() { /* release anything NOT registered via register*/ }
}

// Vault: prefer process() over read()+modify(); use cachedRead() for display only.
const file = this.app.vault.getFileByPath('Notes/x.md');
await this.app.vault.process(file, (data) => data.replace('foo', 'bar'));
// Editor of the active note (preserves cursor/selection):
const view = this.app.workspace.getActiveViewOfType(MarkdownView);
view?.editor.replaceSelection(view.editor.getSelection().toUpperCase());

插件文件：<vault>/.obsidian/plugins/<id>/ 中的 manifest.json + main.js（+ 可选的 styles.css）。 主题文件：<vault>/.obsidian/themes/<name>/ 中的 manifest.json + theme.css。

硬性规则

• 使用 this.app，绝不要使用全局 app（全局对象仅用于调试，且可能会被移除）。
• 通过 registerEvent / registerInterval / registerDomEvent / addCommand / registerView / registerMarkdownPostProcessor 注册所有需要清理的内容 —— Obsidian 会在卸载时自动清理这些内容。其他内容需在 onunload() 中手动释放。泄漏的监听器/ interval 会在插件停用后拖慢 Obsidian。
• 绝不要对动态内容使用 innerHTML / outerHTML / insertAdjacentHTML — 使用 createEl() / createDiv() / createSpan() 构建 DOM。
• 优先使用 Vault API，而非 Adapter API；使用 getFileByPath()（不要遍历所有文件）；始终对用户提供的路径使用 normalizePath()。使用 process()（原子操作），而不是依次调用 read()+modify()，以避免数据丢失；只有在不会写回内容时才使用 cachedRead()。
• 编辑当前笔记时，通过 Editor 接口操作，不要使用 Vault.modify — 这样可以保留 光标和选区。
• 不要存储视图实例的引用；Obsidian 可能会重新创建视图 — 使用 getLeavesOfType() / getActiveViewOfType() 获取视图。
• 分发的插件不要设置默认快捷键（依赖操作系统且容易冲突）。UI 文本使用句首字母大写格式。使用 CSS 类和 Obsidian CSS 变量，不要使用硬编码的内联样式。
• manifest.json 必填字段：id、name、version（semver x.y.z）、minAppVersion、 description、author、isDesktopOnly。id 不得包含 "obsidian"；name 必须使用基本拉丁字符，不得包含表情符号/ 标点，连字符除外。
• 发布：创建 GitHub release，且其标签与 manifest 中的 version 相同；将 main.js、 manifest.json 和可选的 styles.css 作为单独的二进制资源附上（不要打包成 zip）。
• 使用 async/await（不要使用 Promise 链）；使用 const/let（不要使用 var）。