编写后台插件
把自己的功能做成一个本地插件:用户工作区的侧边栏入口、一个页面和一张仪表盘卡片,管理员可以随时启用和停用。
本地插件把你写的功能接入后台,不需要改外壳代码。本文做一个叫 notes 的插件:用户工作区侧边栏里的一个入口、/app/notes 页面,以及 /app 仪表盘上的一张卡片。管理后台的做法相同,只是换成 admin.nav 插槽。内核的工作方式见插件。
准备工作
- 项目能用
pnpm dev在本地运行。 - 一个持有
config.read和config.write的管理员账号,用来打开 设置 → 插件。 - 想好插件 id:小写短横线形式,例如
notes,在src/plugins/installed.ts的插件里唯一。 - 开始之前记录
pnpm validate:all的通过和失败情况,方便之后确认没有检查由通过变为失败。
编写插件
写清单
清单是纯数据。kind: "local" 表示插件属于这个项目。routes 列出插件拥有的路径前缀,不含语言前缀。
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。
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 加载,做法见新增页面。
写仪表盘卡片
仪表盘卡片是一个接收当前语言的组件。
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 会失败。
向插槽贡献
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: 区段之外。这些区段属于随仓库提供的模块,本地插件放进去会导致校验器失败。
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。支付插槽见交付已支付订单。
验证
pnpm typecheck通过。插槽名写错或贡献缺字段都是类型错误。pnpm validate:plugins通过。它检查注册表能构建、导航项指向存在的路由文件、条目落在插件routes的前缀之下,以及页面的active值是某个已贡献的app.navid。- 打开
/app:侧边栏里有 Notes 入口,卡片在账户概览上方。再打开/app/notes。 - 打开 设置 → 插件(
/admin/plugins)。notes这一行列出了它的工作区入口和路由。把它停用。 - 刷新
/app:入口和卡片都消失,/app/notes显示未找到页面。重新启用后两者恢复。 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;否则停用插件只会隐藏入口,页面仍然能访问。