编写后台插件

把自己的功能做成一个本地插件:用户工作区的侧边栏入口、一个页面和一张仪表盘卡片,管理员可以随时启用和停用。

本地插件把你写的功能接入后台,不需要改外壳代码。本文做一个叫 notes 的插件:用户工作区侧边栏里的一个入口、/app/notes 页面,以及 /app 仪表盘上的一张卡片。管理后台的做法相同,只是换成 admin.nav 插槽。内核的工作方式见插件。

准备工作

  • 项目能用 pnpm dev 在本地运行。
  • 一个持有 config.read 和 config.write 的管理员账号,用来打开 设置 → 插件。
  • 想好插件 id:小写短横线形式,例如 notes,在 src/plugins/installed.ts 的插件里唯一。
  • 开始之前记录 pnpm validate:all 的通过和失败情况,方便之后确认没有检查由通过变为失败。

编写插件

写清单

清单是纯数据。kind: "local" 表示插件属于这个项目。routes 列出插件拥有的路径前缀,不含语言前缀。

src/plugins/notes/manifest.ts
import { defineManifest } from "../kernel/types";

export const notesManifest = defineManifest({
  id: "notes",
  version: "0.1.0",
  kind: "local",
  routes: ["/app/notes"],
});

加文案

导航文案是词典 key。在 src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts 的 appConsole 命名空间里都加上 notes。只在一种语言里存在的 key 会让 pnpm validate:app-i18n 失败。

加页面

在带语言前缀的路由树下创建路由。active 必须是下一步贡献的 app.nav 条目的 id。

src/routes/{-$locale}/app/notes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { useAuth } from "@/components/auth/auth-state";
import { AppConsoleLayout } from "@/components/layout/app-console-sidebar";
import { useI18n } from "@/i18n/use-i18n";

export const Route = createFileRoute("/{-$locale}/app/notes/")({
  component: NotesPage,
});

function NotesPage() {
  const { locale, t } = useI18n();
  const { user } = useAuth();
  return (
    <AppConsoleLayout active="notes" locale={locale} user={user}>
      <h1 className="text-lg font-medium">{t("appConsole.notes")}</h1>
    </AppConsoleLayout>
  );
}

页面自己不需要守卫。/app 布局负责鉴权,插件停用时同一个布局会让这条路由返回未找到。数据通过调用 requireCurrentUserId() 的 server function 加载,做法见新增页面。

写仪表盘卡片

仪表盘卡片是一个接收当前语言的组件。

src/plugins/notes/notes-card.tsx
import { Surface, SurfaceContent } from "@/components/motion/surface";
import { getDictionary, type Locale, localizedPath } from "@/i18n/messages";

export function NotesCard({ locale }: { locale: Locale }) {
  const { t } = getDictionary(locale);
  return (
    <Surface>
      <SurfaceContent>
        <a href={localizedPath("/app/notes", locale)}>{t("appConsole.notes")}</a>
      </SurfaceContent>
    </Surface>
  );
}

组件用 @workspace/beui、src/components/motion 和 Tailwind 工具类来写。src/plugins 下的文件如果 import 了 src/components/ui 或读取 process.env,pnpm validate:plugins 会失败。

向插槽贡献

src/plugins/notes/plugin.ts
import { NotebookPen } from "lucide-react";
import { definePlugin } from "../kernel/types";
import { notesManifest } from "./manifest";
import { NotesCard } from "./notes-card";

export const notesPlugin = definePlugin({
  manifest: notesManifest,
  contributes: {
    "app.nav": [
      {
        id: "notes",
        icon: NotebookPen,
        labelKey: "appConsole.notes",
        path: "/app/notes",
        section: "product",
        order: 50,
      },
    ],
    "app.dashboard.cards": [{ id: "notes.summary", order: 10, component: NotesCard }],
  },
});

基础版自己的 product 条目用的是 0 到 40,所以 50 会排在它们后面。每个字段的类型在 src/plugins/slots.ts 里,见客户端插槽与服务端插槽。

登记

把插件加进安装列表。写在所有 // @module: 区段之外。这些区段属于随仓库提供的模块,本地插件放进去会导致校验器失败。

src/plugins/installed.ts
import { notesPlugin } from "./notes/plugin";

export const installedPlugins: readonly Plugin[] = [
  foundationPlugin,
  // … 随仓库提供的模块的区段 …
  notesPlugin,
];

运行一次 pnpm dev,让 src/routeTree.gen.ts 收录新的路由文件。

增加服务端行为

需要提供 HTTP 接口或响应已支付订单的插件,再加一个用 defineServerPlugin 定义的 plugin.server.ts,向 api.routes 或 billing.fulfilment 贡献,并同时登记到 src/plugins/installed.server.ts。这个文件也会被 agent 服务 import,所以从它能到达的代码都不能 import React、图标或 @/ 别名。

插件的 server function 在鉴权之后调用 src/server/plugins/state.ts 里的 requirePluginEnabled("notes"),插件停用时拒绝调用。贡献给 api.routes 的接口不需要这样做,因为插件停用时宿主返回 404。支付插槽见交付已支付订单。

验证

  1. pnpm typecheck 通过。插槽名写错或贡献缺字段都是类型错误。
  2. pnpm validate:plugins 通过。它检查注册表能构建、导航项指向存在的路由文件、条目落在插件 routes 的前缀之下,以及页面的 active 值是某个已贡献的 app.nav id。
  3. 打开 /app:侧边栏里有 Notes 入口,卡片在账户概览上方。再打开 /app/notes。
  4. 打开 设置 → 插件(/admin/plugins)。notes 这一行列出了它的工作区入口和路由。把它停用。
  5. 刷新 /app:入口和卡片都消失,/app/notes 显示未找到页面。重新启用后两者恢复。
  6. pnpm validate:all 与之前记录的结果相比没有新增失败。

故障排查

应用启动失败,报 duplicate_slot_key

另一个插件已经向该插槽贡献了相同的 key:id 相同的 app.nav 条目,或 to 相同的 admin.nav 条目。错误信息里有插槽、key 和两个插件的名字。

应用启动失败,报 duplicate_plugin_route

两份清单在 routes 里声明了同一个前缀。一个前缀只能有一个所有者,把新路由放到自己的前缀下。

pnpm validate:plugins 报 module-entries-sit-in-their-own-routes

插件的导航项指向了清单前缀之外的路径。把前缀加进 routes;否则停用插件只会隐藏入口,页面仍然能访问。

下一步