xdb-plugin-skills

name	xdb-plugin-skills
description	Use this whenever creating, editing, or reviewing XDB plugin files (*.xdb.js), or authoring third-party extensions for the xdb module's plugin system. Covers the registration API exposed on the XdbApp context (registerView, registerDatabaseView, registerViewSettings, registerViewSettingsTab, registerDatabaseViewRowStyleProvider, registerCardCoverView, registerButtonStep, registerStyleSheet), the install/onUpdate/onDestroy lifecycle, configuration ownership, and repeatable rendering patterns. Trigger on .xdb.js files, XDB plugin authoring, xdb extension/extension-point work.
version	0.0.1
author	vran

XDB Plugin 开发技能

何时使用

做以下任何一件事之前，先读本技能再动手：

• 新建或修改 *.xdb.js 插件文件
• 为 xdb 注册第三方扩展点（视图 / 视图设置 / 行样式 / 卡片封面 / 按钮步骤 / 样式）
• 排查"插件没加载 / 改了不生效 / 配置没持久化 / 渲染越来越重"等问题

本技能是写 xdb 插件的权威说明：能力、生命周期、取数规则都以此为准。

运行流程

宿主扫描 *.xdb.js
  └─> 执行 module.exports.install(ctx)        // 只注册 + 返回 cleanup
        └─> ctx.registerXxx(...)              // 把扩展登记进宿主
              └─> 宿主按需创建实例
                    └─> 数据/配置变化时调用 instance.onUpdate(props)
                          └─> 实例替换/卸载时调用 instance.onDestroy()
        └─> 插件卸载/重载时执行 install() 返回的 cleanup

ctx 上所有方法都是面向插件开发者的能力（即 install(ctx) 收到的 ctx）。记住三条规则，能自检绝大多数问题：

1. install 只注册：install(ctx) 只注册扩展点、返回 cleanup，不做渲染。
2. 配置写对地方：view 配置写 viewDefinition.options；cover / button step 私有配置用 getData() / updateData()（存在 extensionData）。
3. onUpdate 可重复：它会被反复调用，每次都先清理旧资源，再从最新 props 重建。

Quick Start

const VIEW_TYPE = 'example-list';

module.exports = {
  id: 'example-list-view',
  name: 'Example List View',
  description: 'A minimal custom database view plugin.',
  author: 'Your Name',
  version: '1.0.0',

  install(ctx) {
    ctx.registerDatabaseView({
      id: VIEW_TYPE,
      name: 'Example List',
      icon: 'list',
      view() {
        return {
          onUpdate(props) {
            props.container.replaceChildren();
            const root = document.createElement('div');
            root.textContent = `Rows: ${props.viewData?.groups?.[0]?.rows?.length ?? 0}`;
            props.container.appendChild(root);
          },
          onDestroy() {},
        };
      },
    });

    ctx.registerViewSettings({
      id: VIEW_TYPE,
      settings() {
        return {
          onUpdate(props) {
            props.container.replaceChildren();
            const button = document.createElement('button');
            button.textContent = 'Enable compact mode';
            button.addEventListener('click', () => {
              void props.setViewDefinition((current) => ({
                ...current,
                options: { ...(current.options ?? {}), compact: true },
              }));
            });
            props.container.appendChild(button);
          },
          onDestroy() {},
        };
      },
    });

    return () => undefined;   // install 必须返回 cleanup 函数
  },
};

写完自检

写或改完 *.xdb.js 后，跑校验脚本自检——它复刻宿主加载方式 + skill 规则，给出确定性结论，比凭记忆核对可靠：

node docs/user-manuals/xdb-plugin-skills/scripts/validate-xdb-plugin.mjs path/to/your.xdb.js

检查：shape（id / name / description / install）、install 是否返回 cleanup、每个 registerXxx 的扩展形状（缺 id / name / view 工厂 / run 函数等，与宿主各 manager 的校验一致）、是否用了废弃的 registerDatabaseViewSettings、CSS 是否用了宿主保留前缀 components--，并打印注册了哪些扩展点（被宿主拒绝的会标 ✗ rejected）。退出码非 0 即有硬错。

查不了的（onUpdate 幂等性、配置写对位置、运行时是否抛错）仍按 lifecycle / conventions 自己核对。

扩展点速查

能力（ctx 方法）	用途	配置位置	详细
registerView()	注册视图（只用 viewDefinition，不读行数据）	viewDefinition.options	database-view
registerDatabaseView()	注册数据库视图（要读行数据 viewData）	viewDefinition.options	database-view
registerViewSettings()	扩展共享 View 设置 tab 的内容	viewDefinition.options	view-settings
registerViewSettingsTab()	新增一个独立的视图设置 tab item（有自己的 label / icon）	viewDefinition.options	view-settings-tab
registerDatabaseViewRowStyleProvider()	根据行数据 + view 配置输出样式	viewDefinition.options	row-style-provider
registerCardCoverView() / registerCardCoverViewSettings()	卡片封面渲染 + 设置面板	extensionData	card-cover
registerButtonStep() / registerButtonStepSettings()	按钮步骤执行 + 设置面板	extensionData	button-step
registerStyleSheet()	注册插件级样式	不存配置	style-sheet

迁移提示：registerDatabaseViewSettings() 已 @deprecated，请改用 registerViewSettings()。

参考文档

• conventions：文件格式、命名、配置写到哪、状态怎么更新，以及各扩展点共用的公共上下文 props。
• types：跨扩展点共享的类型——api（Database）的读写能力、FilterItem 过滤结构、行数据 $item（FileIndex / TaskIndex）。
• lifecycle：从加载到卸载的完整生命周期，以及性能、渲染、cleanup、Obsidian 风格等最佳实践。
• 各扩展点的类型与 props：见上面"扩展点速查"表的"详细"列。
• troubleshooting：常见问题对照——插件没加载、改了不生效、配置不持久化、渲染叠加。