` - `seo.meta.description`：串行改写 SEO meta description - `breadcrumb.items`：串行改写面包屑条目数组异步 waterfall（`registerAsyncWaterfallHook`）： - `navigation.primary.items`：主导航项数组 - `home.sidebar.hot-topics.items`：首页热点帖子列表 - `settings.post-management.tabs`：设置页“帖子管理”插件 tab 列表 - `feed.posts.items`：原始帖子流（首页 / 分类 / 列表页，`payload.displayMode` 表示当前列表模式） - `post-list.display.items`：映射后的帖子列表展示项；微博模式会包含 `previewMedia`、`contentPreviewMarkdown`、`contentPreviewHtml`、点赞 / 收藏 / 打赏等统计字段 - `search.results.rerank`：搜索结果重排（`payload` 含 `{ query, scope }`） - `notification.dispatch.targets`：通知分发目标（`payload` 含当前通知 `draft`） - `sitemap.entries`：sitemap.xml 条目列表 - `post.related.items`：详情页相关推荐 - `post.content.render`：帖子正文渲染后 HTML（代码高亮 / LaTeX / Mermaid）示例： ```js api.registerAsyncWaterfallHook({ key: "prepend-navigation", hook: "navigation.primary.items", async transform(context) { return [ { label: "活动", href: "/events", activePrefix: "/events" }, ...context.value, ] }, }) ``` 补充约定： - `feed.posts.items` 发生在原始记录阶段，适合插入广告位、置顶、重排或过滤；`post-list.display.items` 发生在宿主完成展示映射之后，适合微调卡片字段。插件应返回新的数组或新的 item 对象，避免直接原地修改 `context.value`。 - 微博模式的正文预览会在服务端去重首个媒体并预渲染 Markdown HTML，宿主会做轻量内存 LRU 缓存；插件如果改写 `contentPreviewMarkdown`，应同步更新或清空 `contentPreviewHtml`，否则客户端会优先使用旧 HTML。 - `post.content.value` 当前在帖子创建、普通编辑和超时后的追加内容链路里执行；它只改写公开正文 / 追加正文，不会自动改写 `loginUnlockContent`、`replyUnlockContent`、`purchaseUnlockContent` 这些附加文本。 - `message.body.value` 在宿主敏感词处理以及 `message.send.before` action hook 之前执行；`payload` 当前包含 `recipientId?`、`conversationId?` 和 `conversationKind`（`DIRECT` / `SITE_CHAT`）。 - `message.send.before` / `message.send.after` 的 payload 现在也会携带 `conversationKind`，其中 `after` 里的 `contentAdjusted` 会同时反映插件文本改写和宿主敏感词替换。 - `report.reasonDetail.value` 在举报补充说明为空时也会执行；插件可按 `reasonType`、`targetType` 自动补全模板文本。 - `report.create.after` 会拿到结构化 `report` 快照；其 `contentAdjusted` 同时反映插件对补充说明的改写和宿主敏感词替换。 - `user.profile.bio.value` / `user.profile.introduction.value` 允许返回空串，宿主会按显式清空处理；`user.profile.nickname.value` 仍带非空保护，空串会回退到原始昵称。 - `user.update.after` 会拿到结构化 `profile` 快照；其 `contentAdjusted` 同时反映昵称 / 简介 / 个人介绍的插件改写和宿主敏感词替换。 - `task.complete.after` 只会在任务首次完成并成功结算奖励后触发；payload 当前包含 `triggerType`、`eventKey`、`pointName`、`rewardPoints` 以及结构化 `task` / `progress` 快照。 - `check-in.submit.before` 在普通签到或补签写入前触发，并以 `throwOnError: true` 执行；payload 包含 `userId`、`username`、`action`、`date`、`reward`、`pointName`，补签时额外包含 `makeUpCost`。 - `check-in.submit.after` 在签到或补签成功后触发；payload 包含 `finalReward`、`points`、`currentStreak`、`maxStreak`、`alreadyCheckedIn`，补签时额外包含 `makeUpCost`。 `settings.post-management.tabs` 的返回值约定为 tab 描述数组，单项通常至少包含： - `key`：tab 唯一标识 - `label`：tab 文案 - `order`：排序，数值越小越靠前 - `panel`：一个与 `AddonRenderResult` 同构的对象；当前推荐使用 `clientModule + clientProps` 示例： ```js api.registerAsyncWaterfallHook({ key: "purchased-attachments-tab", hook: "settings.post-management.tabs", async transform(context) { return [ ...context.value, { key: "purchased-attachments", label: "购买的附件", order: 200, addonId: context.manifest.id, panel: { clientModule: context.asset("post-management-purchased-attachments.js"), clientProps: { endpoint: context.publicApi("purchased-attachments-posts"), }, }, }, ] }, }) ``` 运行规则： - 按 `order` 升序串行执行 - `context` 至少包含 `hook`、`value`，宿主在有额外语义时还会传 `payload` - 某个 hook 返回 `undefined` 时，保留上一个值继续向后传递 - 某个 hook 报错时，宿主会记录 lifecycle log，并默认继续后续 hook - `throwOnError` 只在宿主显式要求时才中断主流程完整点位请看 [`docs/插件 Hook 清单.md`](/D:/dev/bbs/site/docs/插件%20Hook%20清单.md)。 #### 8.11.1 Waterfall 实战示例下面 4 个例子覆盖最常见的"批量数据改写"场景，每个例子都给出了**注册代码 + 注意事项 + 常见反模式**。 **例 1：给所有用户头像套一层 CDN / 占位兜底** ```js // server.js api.registerWaterfallHook({ key: "avatar-cdn-wrap", hook: "user.avatar.url.value", order: 50, transform(context) { const { value, payload } = context // payload: { userId, size? } if (!value) { return `https://cdn.example.com/avatar/default-${(payload.userId ?? 0) % 8}.png` } if (value.startsWith("/")) { return `https://cdn.example.com${value}` } return value }, }) ``` 注意： - 该 hook 在宿主的 `ensureUserDisplay()` 管道里执行，同一次 SSR 渲染会命中一批用户，**保持 transform 轻量**（纯字符串拼接即可，不要在里面发请求） - 如果需要异步查询 CDN 签名，请改用 `registerAsyncWaterfallHook` - 返回 `undefined` 会让宿主保留上一个值继续传给下一个 hook **例 2：串行改写用户展示名（加 VIP 前缀 / 敏感词遮蔽）** ```js api.registerWaterfallHook({ key: "vip-badge-prefix", hook: "user.displayName.value", order: 100, transform(context) { const { value, payload } = context // payload: { userId, role?, badges? } if (payload.badges?.includes("vip")) { return `⭐ ${value}` } return value }, }) ``` 注意： - `displayName` 会出现在帖子列表、详情、评论、@ 提示等几乎所有 UI 上，改写要幂等（多次 transform 不会叠加前缀） - 需要辨识"已经加过前缀"时，优先用 `payload.badges` 判断，不要对 `value` 做 `startsWith("⭐")` 这种脆弱匹配 **例 3：SEO title / description 串改** ```js api.registerWaterfallHook({ key: "seo-site-suffix", hook: "seo.meta.title", order: 900, // 放在最后追加站点名 transform(context) { const { value } = context if (!value) return "我的论坛" if (value.endsWith(" - 我的论坛")) return value return `${value} - 我的论坛` }, }) api.registerWaterfallHook({ key: "seo-desc-fallback", hook: "seo.meta.description", transform(context) { return context.value || "一个由论坛驱动的社区站点。" }, }) ``` 注意： - `seo.meta.*` 是**同步** waterfall，不能 `await` - 同一页面上多个插件都注册时按 `order` 串行，**越晚执行的越靠外包装** - 默认站点后缀类逻辑建议放到 `order: 900+`，避免挤占前序 transform 语义空间 **例 4：扩展 sitemap.xml（异步）** ```js api.registerAsyncWaterfallHook({ key: "sitemap-extra-pages", hook: "sitemap.entries", order: 200, async transform(context) { const { value } = context const staticEntries = [ { loc: "/about", lastmod: "2026-01-01", changefreq: "monthly", priority: 0.5 }, { loc: "/help", lastmod: "2026-01-01", changefreq: "monthly", priority: 0.4 }, ] // 也可以 await context.data.list(...) 动态生成 return [...value, ...staticEntries] }, }) ``` 注意： - `sitemap.entries` 是**异步** waterfall，可以 `await` 数据查询 - 宿主只要求返回的每项至少包含 `loc`；`lastmod` / `changefreq` / `priority` 缺省时宿主会保留原样 - `loc` 可以是绝对 URL 也可以是 `/xxx` 形式；相对路径宿主会拼接站点域名 **通用反模式（所有 waterfall 都要避免）** - ❌ 在 transform 里 `throw`：会被宿主吞并写 lifecycle log，但后续 hook 拿到的仍是改写前的 value，业务上往往不是你想要的 - ❌ 在 transform 里直接 mutate `context.value`（数组 / 对象）：虽然当前能跑，但破坏了 waterfall 的"串行值传递"语义，换个执行顺序就会出 bug。**始终返回新值** - ❌ 在同步 waterfall 里调用 Promise / `fetch`：返回值会被当作普通对象处理，不会被 await - ❌ 让 transform 依赖 `window` / `document`：waterfall 大多在服务端 SSR 管道里执行，碰 DOM 就会 500 ### 8.12 Provider Registry 宿主内部现在已经把 provider 消费层统一到一个 registry/capability 层，而不是每种 provider 都各自重新扫描插件目录。对插件作者来说，接口没有变化： - 仍然通过 `api.registerProvider()` 注册 provider - 仍然在 `provider.data.runtime` 里暴露 runtime 方法但宿主侧会统一完成这些事情： - 按 `kind` 收集 provider - 构造 provider context - 进入统一 addon execution scope - 执行权限检查 - 执行外网访问守卫这意味着： - 新增 provider kind 时，宿主只需要补 capability 消费逻辑 - 不再需要每个 consumer 自己手写一套 addon 扫描 / context 构造 / runtime 调用包装 ### 8.13 宿主内容与互动 API 除了 `config / secret / backgroundJobs / data`，运行时上下文现在还开放了宿主内容与互动接口，适合“后台巡检型插件”： - `context.database.queryRaw(sql, values?)`：直接查询插件自定义 SQL 表 - `context.database.executeRaw(sql, values?)`：直接执行插件自定义 SQL - `context.database.transaction(task)`：把多步 SQL 包进一个事务 - `context.database.prisma`：在声明 `database:orm` 时复用宿主 Prisma Client - `context.posts.create(input)`：以指定账号创建帖子 - `context.posts.query(options?)`：按节点、分区、作者、时间、回复数、浏览数、点赞数等条件查询帖子 - `context.posts.like(input)`：以指定账号确保帖子已点赞 - `context.comments.create(input)`：以指定账号创建评论 / 回帖 - `context.comments.query(options?)`：按帖子、作者、状态、时间、点赞数等条件查询评论 - `context.comments.like(input)`：以指定账号确保评论已点赞 - `context.messages.send(input)`：以指定账号发送站内私信 - `context.notifications.create(input)`：创建一条系统通知 - `context.notifications.createMany(inputs)`：批量创建系统通知 - `context.emails.send(input)`：给指定用户的已验证邮箱发送邮件 - `context.follows.followUser(input)`：以指定账号确保已关注某个用户 - `context.points.adjust(input)`：增减指定用户积分 - `context.badges.list(options?)`：读取当前站点可供插件使用的勋章列表 - `context.badges.getGrantedIds(input)`：读取指定用户已经持有的勋章 ID 列表 - `context.badges.grant(input)`：向指定用户发放一个站点勋章 - `context.posts.tip(input)`：以指定账号执行帖子打赏典型用法就是自动顶贴 / 自动回帖机器人；如果你的插件本身还维护自定义订单、奖池、库存、报名表，也可以把 `database.*` 和这些宿主互动 API 组合起来： 1. 用 `scheduler.ensure()` 自我续期后台任务 2. 在任务里通过 `posts.query()` 找候选帖子 3. 通过 `comments.query({ postId, authorUsernames })` 判断某贴已经被哪些马甲账号参与过 4. 选出“当前帖子还没用过的账号”和一条回复文案 5. 调用 `comments.create()` 发出回复 6. 如果还需要造热度，再调用 `posts.like()` 或 `comments.like()` 7. 如果还需要联动运营动作，再调用 `messages.send()`、`notifications.create()`、`emails.send()`、`follows.followUser()`、`points.adjust()` 或 `posts.tip()` #### 8.13.1 `posts.query()` 适合解决的问题 - 只扫描指定分区 / 节点 - 只扫描最近 N 天的帖子 - 跳过回复数过多的帖子 - 优先处理回复少 / 浏览少 / 长时间没人回复的帖子常用筛选字段包括： - `boardIds` / `boardSlugs` - `zoneIds` / `zoneSlugs` - `authorIds` / `authorUsernames` - `statuses` - `createdAfter` / `createdBefore` - `publishedAfter` / `publishedBefore` - `lastCommentedAfter` / `lastCommentedBefore` - `activityAfter` / `activityBefore` - `minCommentCount` / `maxCommentCount` - `minViewCount` / `maxViewCount` - `minLikeCount` / `maxLikeCount` - `sort` - `limit` / `offset` - `includeTotal` 返回结果会包含帖子基础信息、原始内容、节点 / 分区信息、作者信息和互动统计。 #### 8.13.2 `comments.query()` 适合解决的问题 - 某个帖子已经有哪些账号参与过 - 某个马甲账号是否已经在目标帖子下回复 - 最近一段时间哪些评论被点过赞常用筛选字段包括： - `postId` / `postIds` - `authorIds` / `authorUsernames` - `statuses` - `parentId` - `createdAfter` / `createdBefore` - `updatedAfter` / `updatedBefore` - `minLikeCount` / `maxLikeCount` - `sort` - `limit` / `offset` - `includeTotal` #### 8.13.3 `comments.create()` 与 `posts.like()` / `comments.like()` 的行为约定 - `comments.create()` 不是直接裸写数据库，而是复用宿主服务链 - 节点回复权限、禁言状态、回复间隔、积分门槛、审核规则仍然会生效 - `posts.like()` / `comments.like()` 采用 ensure-liked 语义，不会执行取消点赞 - 如果目标已经点赞，返回值里的 `liked` 仍然是 `true`，但 `changed` 会是 `false` 这套设计是为了让后台插件更容易实现幂等逻辑，避免任务重试时把原本点过的赞又取消掉。 #### 8.13.4 私信、系统通知、邮件与用户关注 - `messages.send()` 适合后台客服机器人、自动欢迎私信、任务完成通知 - `notifications.create()` / `createMany()` 适合给用户发系统通知，而不是伪造点赞 / 回复类通知 - `emails.send()` 适合需要明确触达用户邮箱的运营、活动或后台任务通知 - `follows.followUser()` 适合运营号、机器人号自动建立关注关系 - `points.adjust()` 适合插件自己的积分奖惩、活动结算、签到补偿 - `badges.list()` / `getGrantedIds()` / `grant()` 适合活动插件、成就插件、勋章联动奖励 - `posts.tip()` 适合运营号 / 机器人号给帖子造支持度，复用宿主原有打赏结算行为约定： - `messages.send()` 复用宿主私信主链，会继续执行黑名单校验、敏感词替换、消息实时事件和 `message.send.before/after` - `notifications.create()` / `createMany()` 当前创建的是 `SYSTEM` 通知，并会继续触发未读数刷新与站外 webhook 派发 - `emails.send()` 只允许按 `recipientId` / `recipientUsername` 投递到用户已验证邮箱；如果用户不存在、邮箱未验证或 SMTP 未配置，会直接抛错 - `follows.followUser()` 采用 ensure-followed 语义；如果目标已经关注，会返回 `changed: false` - `points.adjust()` 默认按你传入的 `delta` 直接结算；如果额外提供合法的 `scopeKey`，则会先走 point-effect 规则再入账 - `badges.list()` 默认只返回“启用且非隐藏”的勋章；传入 `includeHidden` / `includeDisabled` 后可放宽筛选 - `badges.getGrantedIds()` 适合在活动开奖前排除“用户已持有勋章”的奖品，避免重复发放 - `badges.grant()` 采用 ensure-granted 语义；如果目标用户已经拥有该勋章，返回值会标记 `alreadyGranted: true` - `posts.tip()` 会继续执行余额校验、次数限制、积分日志、分账和系统通知 ## 9. 渲染结果格式 slot 和 page 的 `render()` 返回的是 `AddonRenderResult` 或重定向对象。 ### 9.1 可用字段 ```ts { html?: string text?: string clientModule?: string clientProps?: Record<string, unknown> containerTag?: "div" | "section" | "aside" containerClassName?: string stylesheets?: Array<string | { href: string; media?: string }> scripts?: Array<string | { src: string; strategy?: "beforeInteractive" | "afterInteractive" | "lazyOnload"; type?: "module" | "text/javascript" }> inlineScripts?: string[] } ``` ### 9.2 使用建议 - 纯静态内容优先用 `html` 或 `text` - 需要交互时再使用 `clientModule` - 样式、脚本、图片等都应该通过 `context.asset("...")` 指向 `assets/` 目录 - 可独立安装的插件如有页面级样式，必须返回 `stylesheets: [context.asset("xxx.css")]`；宿主不会在插件安装后重新运行 `next build` 或 Tailwind 扫描 ### 9.3 页面重定向页面也可以返回： ```js return { redirectTo: "/login" } ``` 宿主会把它当成重定向页面结果处理。 ## 10. 浏览器侧 `clientModule` 如果你要渲染交互式前端，可以在服务端返回： ```js return { stylesheets: [context.asset("hello-client.css")], clientModule: context.asset("hello-client.js"), clientProps: { title: "Hello" } } ``` ### 10.1 `clientModule` 的放置位置重要： - `clientModule` 必须是浏览器能访问到的 URL - 最常见的做法是把编译后的浏览器脚本放进 `assets/` - 然后通过 `context.asset("xxx.js")` 生成 `/_addons/<addonId>/xxx.js` ### 10.2 浏览器模块支持的导出形式宿主支持三种形式： 1. 导出 `createComponent(sdk)` 2. 导出 `Component` 3. 导出 `mount(container, props, sdk)`，可选配对 `unmount` 最简单的 `mount` 版本示例： ```js export function mount(container, props) { container.innerHTML = `<button type="button">Hello ${props.title ?? "Addon"}</button>` const button = container.querySelector("button") const onClick = () => { button.textContent = "clicked" } button?.addEventListener("click", onClick) return () => { button?.removeEventListener("click", onClick) container.innerHTML = "" } } ``` ### 10.3 `sdk` 能力浏览器模块会拿到一个 `sdk`，目前包含： - `React` - `createRoot` - `toast` - `cn` - 一批宿主 UI 组件（基于 `shadcn/ui`） - 一批宿主自定义展示组件 - 一批宿主工具函数 - 一批常用 `lucide-react` 图标 - 一个公开到 `window._rhex` 的宿主前端全局对象如果你的浏览器模块要长期维护，建议把它当成“宿主注入能力”，不要假设宿主之外的内部路径长期稳定。当前已注入的 `sdk.ui` 常用稳定组件包括： - 反馈与弹层：`AlertDialog*`、`Dialog*`、`DropdownMenu*`、`HoverCard*`、`Popover*`、`Sheet*`、`Tooltip*` - 导航与布局：`Breadcrumb*`、`Collapsible*`、`NavigationMenu*`、`Pagination*`、`ScrollArea`、`Separator`、`Tabs*` - 表单与选择：`Button`、`Checkbox`、`IconPicker`、`Input`、`InputGroup*`、`Textarea`、`Select*`、`Combobox*`、`Slider`、`Switch`、`Toggle`、`ToggleGroup*` - 数据与展示：`Avatar*`、`Badge`、`Card*`、`Command*`、`Skeleton`、`Spinner`、`Table*` - 宿主扩展 UI：`Modal`、`FormModal`、`Sidebar*`、`useSidebar` 当前已注入的 `sdk.custom` 宿主自定义组件包括： - 内容流：`ForumPostStreamView` - 节点选择：`BoardSelectField` - 等级与图标：`LevelIcon`、`LevelBadge` - 用户身份：`UserAvatar`、`UserStatusBadge`、`UserVerificationBadge`、`UserDisplayedBadges` - VIP 展示：`AvatarVipBadge`、`VipLevelIcon`、`VipNameTooltip`、`VipDisplayName` - 当前已注入的 `sdk.utils` 宿主工具包括：`escapeHtml`、`isRecord`、`normalizeOptionalString`、`loadScriptOnce` 当前已注入的 `sdk.icons` 常用图标包括： - 导航与方向：`ArrowRight`、`ArrowUpRight`、`ChevronDown`、`ChevronLeft`、`ChevronRight`、`ChevronUp` - 状态与提示：`AlertCircle`、`CheckCircle2`、`CircleHelp`、`Info`、`ShieldCheck`、`Sparkles` - 通用动作：`Check`、`Download`、`ExternalLink`、`Eye`、`EyeOff`、`Filter`、`Loader2`、`MoreHorizontal`、`Pencil`、`Plus`、`Save`、`Search`、`Trash2`、`Upload`、`X` - 内容与社交：`FileText`、`Heart`、`ImageIcon`、`Link2`、`MessageCircle`、`MessageSquareMore`、`Pin`、`Star` - 用户与站点：`Clock3`、`Lock`、`Palette`、`Settings2`、`User`、`UserRound`、`Users` - 音频播放：`ListMusic`、`Music4`、`Pause`、`Play`、`SkipBack`、`SkipForward`、`Volume2`、`VolumeX` 注意： - 这里是宿主**显式公开**给插件的稳定集合 - 它不等于 `src/components/ui/` 目录下的所有文件都会自动成为插件 API - `sdk.custom` 里的组件属于宿主站点语义组件，不是通用 `shadcn/ui` - `sdk.utils` 适合放插件资产脚本里经常重复的小工具 - 后续如果宿主继续扩充公开集合，应以 `src/addons-host/sdk/client.tsx` 为准 ### 10.3.1 `window._rhex` 全局对象除了 `clientModule` 里收到的 `sdk` 参数，宿主还会在浏览器里暴露一个全局对象： ```js window._rhex ``` 它的作用： - 让插件的普通浏览器脚本也能拿到宿主公共 SDK，而不必每个文件自己重复实现工具函数 - 让不走 React `createComponent(sdk)` 的脚本，也能读取宿主公开的前端上下文当前 `window._rhex` 里主要包括： - `sdkVersion` - `getSdk()` - `ui` - `custom` - `icons` - `utils` - `toast` - `cn` - `React` - `createRoot` - `session` - `site` 其中： - `window._rhex.session.isAuthenticated`：当前用户是否已登录 - `window._rhex.session.user`：当前登录用户的公开摘要；未登录时为 `null` - `window._rhex.site`：当前站点的公开设置快照；字段集合与宿主 `getSiteSettings()` 返回值保持一致当前 `window._rhex.session.user` 公开字段包括： - `id` - `username` - `nickname` - `avatarPath` - `role` - `status` - `level` - `points` - `vipLevel` - `vipExpiresAt` 当前 `window._rhex.site` 不再只暴露少量摘要字段，而是直接暴露宿主的公开站点设置快照。这意味着插件前端脚本可以直接读取大部分“前台本来就能看到、且宿主认为可公开”的站点设置，例如： - 站点品牌与展示：`siteName`、`siteSlogan`、`siteDescription`、`siteLogoPath`、`siteIconPath` - 交互与显示模式：`pointName`、`postLinkDisplayMode`、`leftSidebarDisplayMode`、`homeFeedPostListDisplayMode` - 页面与分页参数：`homeFeedPostPageSize`、`zonePostPageSize`、`boardPostPageSize`、`commentPageSize` - 公开功能开关：`friendLinksEnabled`、`checkInEnabled`、`inviteCodePurchaseEnabled`、`tippingEnabled` - 上传与附件能力：`markdownImageUploadEnabled`、`attachmentUploadEnabled`、`attachmentDownloadEnabled`、`attachmentAllowedExtensions` - 可公开导航与文案：`footerLinks`、`headerAppLinks`、`redeemCodeHelpEnabled`、`redeemCodeHelpTitle`、`redeemCodeHelpUrl` 完整字段范围请以宿主源码中的 `SiteSettingsData` 为准： - `src/lib/site-settings.types.ts` - `src/lib/site-settings.ts` 里的 `getSiteSettings()` 使用示例： ```js const rhex = window._rhex const isLoggedIn = Boolean(rhex?.session?.isAuthenticated) const username = rhex?.session?.user?.username ?? "" const pointName = rhex?.site?.pointName ?? "积分" const html = rhex?.utils?.escapeHtml(username) ?? username ``` 约束： - `window._rhex` 只应读取宿主明确公开的字段，不要假设还有未文档化的内部结构 - 这里公开的是“前端可安全暴露摘要”，不是完整用户对象 - `window._rhex.site` 虽然字段明显变多，但仍然只包含公开站点设置，不包含后台敏感配置 - 不会通过 `window._rhex` 暴露任何 secret、session token、后台敏感配置 ### 10.4 UI 约束与 `shadcn/ui` 可以。当前宿主前端就是基于 `shadcn/ui`，插件的浏览器侧模块也允许使用宿主注入的 `shadcn/ui` 组件。推荐做法： - 不走组件模式时，静态 HTML 也应配套插件自带命名空间 CSS；不要把 ZIP 后装插件的页面级布局建立在宿主 Tailwind utility 是否已生成之上 - 在 `clientModule` 里优先通过 `sdk.ui` 使用宿主提供的通用 UI 组件 - 需要宿主站点语义时，通过 `sdk.custom` 使用头像、等级、VIP、徽章、节点选择器等自定义组件 - 通过 `sdk.toast`、`sdk.cn`、`sdk.icons` 复用宿主现成能力 - 前台和后台页面都优先复用宿主已提供的组件组合，保证视觉和交互风格一致 - 如果插件发现宿主其实已经有某个组件，但 SDK 还没公开，优先补 SDK 暴露，不要在插件里复制一份 - 插件自带 CSS 应尽量只负责插件独有布局、密度、响应式和复杂交互状态；颜色、边框、背景、文字等应通过宿主 CSS 变量取值，保持主题一致 - 如果宿主页面已经给插件内容包了一层 Card / Section 壳，插件第一层不要再套一层同级 Card，避免双层边框和重复内边距 - 插件交互页建议按 `model/controller/view` 分层组织代码，避免把数据转换、网络请求和渲染混在一起示例： ```js export function createComponent(sdk) { const { React, ui, icons, toast } = sdk const { Button, Card, CardContent, CardHeader, CardTitle } = ui const { Play } = icons return function DemoCard() { return React.createElement( Card, null, React.createElement( CardHeader, null, React.createElement(CardTitle, null, "Hello Widget") ), React.createElement( CardContent, null, React.createElement( Button, { onClick: () => toast.success("clicked") }, React.createElement(Play, { "data-icon": "inline-start" }), "Run" ) ) ) } } ``` 不要这样做： - 不要在插件源码里直接 import 宿主内部别名，例如 `@/components/ui/button`、`@/lib/utils` - 不要在插件源码里直接 import 宿主自定义组件路径，例如 `@/components/user/user-avatar`、`@/components/level-icon` - 不要把宿主仓库里的 `shadcn/ui` 源码路径当成插件公共 API - 不要假设宿主未来一定会继续暴露完全相同的组件集合原因： - 插件是独立产物，最终通过 `addons/<addonId>/dist` 和 `assets/` 被加载 - zip 安装后的插件运行环境里，并不存在宿主源码别名解析 - 当前真正稳定的浏览器侧 UI 接口，是宿主传给你的 `sdk.ui` 和 `sdk.custom` 额外约束： - 如果插件只需要现有那批组件，优先使用 `sdk.ui` - 如果插件需要头像、等级、VIP、徽章等站点语义组件，优先使用 `sdk.custom` - 如果插件需要宿主当前未暴露的 `shadcn/ui` 组件，不要直接引用宿主源码；应把所需实现打包进你自己的前端产物 - 如果插件需要宿主当前未暴露的站点自定义组件，也不要直接引用宿主源码；应先扩充宿主公开 SDK，或把自己的实现打包进插件产物 - 动态安装插件不能要求宿主重新构建 CSS。新增或修改插件 UI 时，同步更新插件自己的 `assets/*.css` 和 `stylesheets` 注入声明 - 内置插件如果复用宿主 Tailwind utility class，必须确认这些源码会在部署镜像 `next build` 前进入仓库 / 镜像；否则按动态插件处理，自带 CSS ## 11. 插件上下文能力宿主在执行 slot / surface / page / api 时会传入运行时上下文对象；在安装、升级、卸载 lifecycle hook 里会传入一套扩展上下文。所有上下文都包含： - `manifest` - `state` - `enabled` - `rootDir` - `assetRootDir` - `assetBaseUrl` - `publicBaseUrl` - `adminBaseUrl` - `publicApiBaseUrl` - `adminApiBaseUrl` - `permissions` - `hasPermission(permission)` - `assertPermission(permission, message?)` - `getCurrentUser()` - `getSiteSettings()` - `getBoardSelectOptions()` - `asset(path)` - `publicPage(path)` - `adminPage(path)` - `publicApi(path)` - `adminApi(path)` - `readAssetText(path)` - `readAssetJson(path)` - `readConfig(configKey, fallback)` - `writeConfig(configKey, value)` - `readSecret(secretKey, fallback)` - `writeSecret(secretKey, value)` - `backgroundJobs.enqueue(jobKey, payload, options?)` - `backgroundJobs.remove(jobId)` - `scheduler.inspect({ enabled, configured, state })` - `scheduler.ensure(currentState, { enabled, configured, jobKey, delayMs, ... })` - `scheduler.cancel(currentState)` - `database.queryRaw(sql, values?)` - `database.executeRaw(sql, values?)` - `database.transaction(task)` - `database.prisma` - `posts.create(input)` - `posts.query(options?)` - `posts.like(input)` - `comments.create(input)` - `comments.query(options?)` - `comments.like(input)` - `messages.send(input)` - `notifications.create(input)` - `notifications.createMany(inputs)` - `emails.send(input)` - `follows.followUser(input)` - `points.adjust(input)` - `badges.list(options?)` - `badges.getGrantedIds(input)` - `badges.grant(input)` - `posts.tip(input)` - `files.save(input)` - `data.*` 补充说明： - `getCurrentUser()` 会基于当前请求的 cookie / headers 解析宿主登录态；没有请求上下文时返回 `null` - `getSiteSettings()` 返回宿主的公开站点设置快照，字段集合与前端 `window._rhex.site` 保持一致 - `getBoardSelectOptions()` 返回按分区分组的节点选项，可直接喂给浏览器侧 `sdk.custom.BoardSelectField` - `backgroundJobs.enqueue()` 会返回包含 `jobId`、`attempt`、`maxAttempts`、`availableAt` 的任务句柄；`remove()` 会返回实际删除位置 - `scheduler.*` 适合“每天/每小时/固定延迟后执行一次”的插件级定时任务；宿主会统一复用 `backgroundJobs` 做调度与取消 - `database.queryRaw()` / `executeRaw()` / `transaction()` 现在在插件运行态和 lifecycle 阶段都可用；自定义业务表推荐优先通过它们维护 - `database.queryRaw()` / `executeRaw()` 使用 PostgreSQL 风格的 `$1`、`$2` 参数占位符；所有动态值都应通过第二个 `values` 数组传入，不要把用户输入直接拼进 SQL 字符串 - `database.prisma` 仍然只适合访问宿主已有 Prisma 模型；插件自定义表不应依赖 Prisma schema 自动发现 - `posts.create()` 复用宿主发帖主链，仍会触发状态校验、敏感词、审核、通知、等级与 action hook - `comments.create()` 复用宿主评论主链，仍会触发状态校验、回帖权限、积分门槛、审核、通知、等级、AI 提及回复与 action hook - `posts.like()` / `comments.like()` 是幂等的 ensure-liked 语义：如果目标已点赞，会返回 `changed: false`，不会像前台 UI 那样执行 toggle 取消点赞 - `messages.send()` 复用宿主私信主链，仍会触发状态校验、黑名单校验、敏感词、消息事件总线与 `message.send.*` action hook - `notifications.create()` / `createMany()` 当前创建的是宿主 `SYSTEM` 类型通知，并会复用未读数刷新和站外 webhook 分发 - `emails.send()` 复用宿主 SMTP 配置，按用户 ID / 用户名投递到该用户已验证邮箱，不会向插件暴露邮箱地址 - `follows.followUser()` 是幂等的 ensure-followed 语义：如果目标已关注，会返回 `changed: false`，不会触发取消关注 - `points.adjust()` 复用宿主积分结算能力，可按需应用 point-effect 规则，并继续写入积分日志 / 审计 - `badges.list()` / `getGrantedIds()` / `grant()` 复用宿主勋章体系，适合活动奖励、成就联动和后台批处理插件 - `badges.grant()` 当前是 ensure-granted 语义：重复发放不会新增第二条用户勋章记录，返回值会带 `alreadyGranted` - `posts.tip()` 复用宿主帖子打赏结算能力，会继续执行余额校验、税率分账、积分日志和系统通知 - `files.save()` 复用宿主上传存储配置保存插件生成文件，适合 AI 生图、海报、导出文件等场景；详见 §8.9.1 - `posts.query()` / `comments.query()` 是插件运行时的宿主数据读取接口，适合后台巡检、定时机器人、批处理插件；它们读取的是宿主原始业务数据，不会自动继承当前访客页面的可见性视角 - `data.*` 包括 `ensureCollection`、`get`、`put`、`delete`、`query`、`cleanup`、`getSchemaVersion` lifecycle 上下文在上面这套基础能力之外，还额外包含： - `action`：`install` / `upgrade` / `uninstall` - `readFileText(path)` / `readFileJson(path)`：读取插件根目录内任意文件，可直接读取 `migrations/*.sql` - `database.queryRaw(sql, values?)` - `database.executeRaw(sql, values?)` - `database.transaction(task)` - `database.prisma` 补充说明： - `database.*` 只建议在 lifecycle hook 里处理安装表、升级表和清理表 - `database.prisma` 复用的是宿主 Prisma Client，更适合访问宿主已有模型；插件自建表不会自动进入宿主 Prisma schema 页面上下文额外包含： - `scope` - `routePath` - `routeSegments` API 上下文额外包含： - `scope` - `routePath` - `routeSegments` - `method` - `request` - `pathname` - `searchParams` slot 上下文额外包含： - `slot` surface 上下文额外包含： - `surface` - `props` ## 12. 配置与状态存储 ### 12.1 状态插件状态当前主要包括： - 是否启用 - 安装时间 - 禁用时间 - 最近错误时间 - 最近错误信息另外，注册表模型里仍保留 `uninstalledAt` 字段用于兼容旧数据；运行时会把这类记录视为不可用，但当前后台和 CLI 已不再提供“逻辑卸载 / 恢复”动作。状态读取规则当前是： 1. 读取数据库 `addon_registry` 2. 如果表不存在，则返回空状态，运行时回退到 manifest 默认值和本次扫描结果说明： - 当前没有 `addons/.runtime/addons-state.json` 这套状态文件读写链路 - 管理页面向管理员展示的稳定状态只有 `enabled` / `disabled` ### 12.2 配置普通插件配置由 `readConfig` / `writeConfig` 访问。当前实现只走数据库 `addon_config`： - `readConfig()`：查 `addon_config`，没查到则返回调用方传入的 `fallback` - `writeConfig()`：upsert `addon_config` 注意： - 当前没有 `addons/.runtime/addons-config.json` 文件兜底 - 如果 `addon_config` 表不存在，`readConfig()` 会退回 `fallback`，`writeConfig()` 不会形成持久化 ### 12.3 敏感配置敏感配置由 `readSecret` / `writeSecret` 访问。读取规则： 1. 先尝试读取站点敏感状态 `site_settings.sensitiveStateJson` 里的 addon secret 命名空间 2. 数据库不可用，或没有对应值时，再回退到 `addons/.runtime/addons-secrets.json` 写入规则： - 总是先写文件态 secret - 再尽力同步到站点敏感状态；数据库不可用时保留文件态作为兜底建议： - API 私钥、平台公钥、第三方密钥、Token 一律放 secret - 可公开展示或可导出的业务参数仍放普通 config ### 12.4 结构化插件数据除了 `config / secret`，宿主现在还提供结构化插件数据存储： - `context.data.ensureCollection()` - `context.data.get()` - `context.data.put()` - `context.data.delete()` - `context.data.query()` - `context.data.cleanup()` - `context.data.clear()` - `context.data.getSchemaVersion()` 这套数据层当前是文件态文档仓库，根目录在： - `addons/.runtime/data/<addonId>/` 每个 collection 是独立文件，宿主会维护： - collection 定义 - 文档记录 - 简单索引映射 - schema version 推荐写法： ```js await context.data.ensureCollection({ name: "orders", indexes: [ { name: "by-user", fields: ["userId"] }, { name: "by-status-user", fields: ["status", "userId"] }, ], }) await context.data.put("orders", { id: "order_001", value: { userId: 1, status: "paid", amount: 99, }, }) const result = await context.data.query("orders", { where: { userId: 1, }, sort: [ { field: "status", direction: "asc" }, ], limit: 20, includeTotal: true, }) ``` 当前特点： - 支持按 `where` 做等值过滤 - 支持 `sort` - 支持 `limit / offset / cursor` - 支持 TTL 清理 - 支持 collection 级索引声明 #### 12.4.1 数据迁移插件现在还可以注册数据迁移： ```js api.registerDataMigration({ version: 1, async migrate(context) { await context.data.ensureCollection({ name: "orders", }) }, }) ``` 当前迁移规则： - 迁移按 `version` 升序执行 - 宿主记录每个 addon 当前 `schemaVersion` - 只执行尚未跑过的迁移 - 迁移失败会让 addon load 失败，并记录 lifecycle log ### 12.5 权限执行与审计 `addon.json` 里的 `permissions` 现在不再只是展示字段，宿主已经开始做真实 enforcement。可以把它理解成两层： - 注册期权限：插件在 `setup(api)` 里调用 `registerSlot()`、`registerProvider()`、`registerActionHook()` 等注册函数时检查 - 执行期权限：插件在运行过程中调用 `context.readConfig()`、`context.writeSecret()`、`context.data.*()`，或 provider runtime 访问外网时检查当前会被宿主检查的能力包括： - `config:read` - `config:write` - `secret:read` - `secret:write` - `background-job:register` - `background-job:enqueue` - `background-job:delete` - `database:sql` - `database:orm` - `data:read` - `data:write` - `data:delete` - `data:migrate` - `file:write` - `slot:register` - `surface:register` - `page:public` - `page:admin` - `api:public` - `api:admin` - `provider:register` - `hook:register` - `post:create` - `post:query` - `post:like` - `comment:create` - `comment:query` - `comment:like` - `message:send` - `notification:create` - `email:send` - `follow:user` - `points:adjust` - `badge:query` - `badge:grant` - `post:tip` - `network:external` - `auth:integrate` - `captcha:integrate` - `payment:integrate` 敏感能力额外约束： - 登录 / 注册相关 slot 和 `auth` / `external-auth` provider 需要 `auth:integrate` - `captcha` provider 和验证码 slot 需要 `captcha:integrate` - `payment` provider 需要 `payment:integrate` - `context.backgroundJobs.enqueue()` 需要 `background-job:enqueue` - `context.backgroundJobs.remove()` 需要 `background-job:delete` - `context.database.queryRaw()` / `executeRaw()` 需要 `database:sql` - `context.database.prisma` 需要 `database:orm` - `context.posts.create()` 需要 `post:create` - `context.posts.query()` 需要 `post:query` - `context.posts.like()` 需要 `post:like` - `context.comments.create()` 需要 `comment:create` - `context.comments.query()` 需要 `comment:query` - `context.comments.like()` 需要 `comment:like` - `context.messages.send()` 需要 `message:send` - `context.notifications.create()` / `createMany()` 需要 `notification:create` - `context.emails.send()` 需要 `email:send` - `context.follows.followUser()` 需要 `follow:user` - `context.points.adjust()` 需要 `points:adjust` - `context.badges.list()` / `getGrantedIds()` 需要 `badge:query` - `context.badges.grant()` 需要 `badge:grant` - `context.posts.tip()` 需要 `post:tip` - `context.files.save()` 需要 `file:write` - 插件执行期访问外部 HTTP(S) 资源需要 `network:external` - 相对地址、同源地址以及 `localhost` / `127.0.0.1` / `::1` 默认不受 `network:external` 限制兼容与迁移说明： - `route:public` / `route:admin` 仍会被归一化为 `page:public` / `page:admin` - 历史上的 `slot:<slotName>` 仍会被归一化为 `slot:register` - 新插件应直接声明标准化权限名，不要继续依赖旧写法当前审计行为： - 权限拒绝会写 lifecycle log - 外网访问被拒绝会写 lifecycle log - 事件执行失败会写 lifecycle log ## 13. 安装、启停与卸载 ### 13.1 zip 安装要求安装器支持两种压缩包结构： 1. zip 根目录直接放 `addon.json` 2. zip 里包一层目录，目录下放 `addon.json` 安装时会做这些事情： 1. 解压到 `addons/.staging` 2. 查找唯一的 `addon.json` 3. 解析清单 4. 校验 `id` 5. 校验服务端入口存在，并从 staging 预加载 server entry 6. 首次安装时，先执行新插件的 `lifecycle.install` 7. 覆盖安装时，先在 staging 执行新插件的 `lifecycle.upgrade` 8. 上一步成功后，覆盖安装才会把旧版本移动到 `.trash` 9. 把新插件移动到 `addons/<addonId>` 10. 写入状态和注册表 11. 重新同步宿主注意： - 安装器当前会校验 zip 结构、`id` 和服务端入口是否存在 - 安装 / 升级 lifecycle hook 失败时，当前目录替换不会发生 - 但不会预先校验 `permissions` 是否覆盖了 `setup(api)` 里真实用到的能力 - 所以“安装成功”不等于“插件一定能成功加载”；权限缺失通常会在同步 / 加载阶段暴露为 `loadError` - 后台安装表单当前额外支持 `replaceExisting`（升级）和 `enableAfterInstall` 两个开关 ### 13.2 生命周期动作当前公开的管理动作： - `enable`：启用插件 - `disable`：禁用插件 - `remove`：物理卸载；会先尝试执行 `lifecycle.uninstall`，成功后再把目录移到 `.trash` - `sync`：重新扫描并同步注册表 - `clear-cache`：清理运行时缓存，并清掉已恢复正常插件的残留最近错误状态说明： - 当前后台和 CLI 都不再暴露 `uninstall` / `reinstall` - 旧注册表里的 `uninstalledAt` 只作为兼容字段保留，运行时会把它视为不可用状态 ### 13.3 后台管理入口后台可直接使用： - 页面：`/admin/addons` - 接口：`/api/admin/addons` - 安装接口：`/api/admin/addons/install` 当前后台管理页支持的操作包括： - 上传 zip 安装插件 - 覆盖已有插件目录 - 安装后立即启用 - 同步扫描插件目录 - 清除插件宿主缓存 - 对单个插件执行启用、禁用、物理卸载 ## 14. 静态资源规则静态资源通过 `/_addons/<addonId>/...` 暴露。已内置的内容类型包括： - `.css` - `.js` - `.mjs` - `.json` - `.mp3` - `.wav` - `.ogg` - `.jpg` - `.jpeg` - `.png` - `.gif` - `.webp` - `.svg` - `.ico` - `.woff` - `.woff2` - `.ttf` 缓存策略： - `.js` / `.mjs` / `.css` / `.json`：`no-cache, must-revalidate` - 其他资源：默认 `max-age=3600` 安全规则： - 所有资源路径都会做目录逃逸校验 - 不能通过 `../` 访问插件目录外的文件 ## 15. 当前开发约束与建议 ### 15.1 强约束 - 服务端入口必须是已编译完成、可直接被 Node `import()` 的文件 - 浏览器模块必须是已编译完成、可直接被浏览器 `import()` 的文件 - 不要依赖宿主会帮你编译插件源码 - 需要浏览器访问的文件必须放在 `assets/` - 可动态安装插件的 CSS 必须随插件发布；页面级 class 应使用插件命名空间，避免污染宿主或其他插件 - 插件样式必须优先使用宿主 `shadcn/ui` 语义 CSS 变量，例如 `hsl(var(--card))`、`hsl(var(--background))`、`hsl(var(--border))`、`hsl(var(--foreground))`、`hsl(var(--muted-foreground))` - 插件前端如果要用宿主 UI 或宿主自定义展示组件，稳定入口是 `sdk.ui` / `sdk.custom`，不是宿主内部源码 import - 插件不要在运行时引入 `https://cdn.tailwindcss.com`；如需 Tailwind，必须由插件自己的发布流程预编译为 `assets/*.css` - 宿主 Tailwind 扫描只对随宿主一起构建的内置插件可靠；后台 ZIP 安装、覆盖安装、热更新的插件都要按“自带 CSS”处理 ### 15.2 建议 - 保持插件目录名与 `id` 一致 - `path` 一律写相对路径，不要加前导 `/` - `key` 在单插件内保持唯一 - 所有管理面操作都优先通过后台或 CLI 走，不要手动改 `.runtime` - `permissions` 尽量在开发早期就按最小权限集写全，不要等到功能做完再补 - `provides`、`dependencies` 仍然建议写全；其中 `dependencies/conflicts` 现在会参与安装预检和运行时校验 ### 15.3 现在最容易踩的坑 - `render()` 返回了内容，但挂错 slot，页面上永远不显示 - 页面 `path` 以为支持动态参数，结果始终 404 - `clientModule` 指向了 `dist/` 文件，浏览器无法访问 - 服务端入口里用了宿主源码别名，但最终安装产物里没有正确打包 - 插件 zip 能安装，但 `permissions` 没写全，导致 `setup(api)` 直接报权限错误 - 插件已启用，但 `loadError` 不为空，导致所有注册项都不生效 - 覆盖安装后忘了检查 `.trash`，以为旧版本已经彻底删除 ### 15.4 跨模块契约与增量修改约定（ESM / 配置 / Slot / 自检）本节给出一组硬性约定，专门用于**在已有插件上做增量功能**的场景。本仓库的插件 server 入口全是 ESM（`.mjs`），一旦跨文件契约错位，宿主启动时会直接抛： ``` SyntaxError: The requested module './xxx.mjs' does not provide an export named 'yyy' ``` 这类错误的根因永远是「导入方和导出方对同一个名字没对齐」或「宿主仍在使用旧的模块缓存」。以下约定按出错概率排序，请按顺序遵守。 #### 15.4.1 ESM 跨模块契约（强约束） - **一次改动两边原子化**：新增 / 重命名 / 删除一个 `export` 时，必须在同一次编辑里把**所有 import 方**一起改到位；严禁只改一侧提交一次、再改另一侧提交一次的串行推进。 - **命名完全一致**：ES Module 的 named import 是**大小写敏感、无容错**的。`loadCardPositionConfig` 和 `loadCardPositionconfig` 是两个不同的东西，宿主不会帮你纠正。 - **相对路径写全**：`import ... from './config.mjs'`，必须有前导 `./` 和显式 `.mjs` 后缀。不要依赖扩展名省略，Node 的 ESM loader 默认不解析。 - **单一事实源**：同一个配置 key、同一个默认值、同一个校验器只能在**一个文件**里声明（本仓库里是 `config.mjs`）。其它文件一律 `import` 这些常量与函数，不要就地再写一份字面量。 - **默认导出只用于插件入口**：`dist/server.mjs` 用 `export default { setup }`；所有业务模块（model / controller / view）一律用 named export，禁止「默认导出一个大对象再解构」的反模式——这种写法一旦某个字段拼错，运行时才暴露。 - **禁止循环依赖**：约定单向依赖链 `server → controller → { config, views }`，`config` 与 `views` 之间不得互相 import，`controller` 不能被 `config` / `views` 反向 import。一旦出现循环，部分 named export 在求值期会是 `undefined`，症状和「没导出」一模一样但排查起来更隐蔽。 - **模块顶部列 export 清单**：每个 `.mjs` 第一屏注释里写出自己对外暴露的名字（如 `// exports: DEFAULT_SHORTCUTS, loadShortcutsConfig, loadCardPositionConfig`）。review 时一眼可核，也方便别的 AI / 开发者在不读全文的情况下正确 import。 - **改完用 grep 反查残留**：删除或改名后执行 ```powershell rg "<旧名字>" site/addons/<addonId> ``` 必须返回 0 条结果，才能视为重构完成。 #### 15.4.2 模块缓存与热加载陷阱宿主的插件 loader 对 `dist/server.mjs` 及其 import 链有进程内缓存。编辑完 `.mjs` 文件后，**光刷新浏览器不够**。按以下优先级处理： 1. 改动仅限 `assets/*.js`（浏览器侧）→ 硬刷新浏览器即可； 2. 改动涉及 `dist/*.mjs`（服务端侧）→ 重启 dev server，或在后台 `/admin/addons` 点一次「同步 / 清缓存」； 3. 改动涉及 `addon.json` 的 `entry` / `provides` / `permissions` → 必须「同步」，否则宿主看到的仍是旧清单； 4. 诊断「我明明加了 export 却还是报没有」时，在 `dist/server.mjs` 里临时 `console.log(Object.keys(await import('./config.mjs')))`，看到的才是宿主真正用到的那一份。 #### 15.4.3 配置项增量约定为后续新增配置时不破坏既有安装，约束如下： - 每个配置 key 固定在 `config.mjs` 中以**三件套**出现： - `CONFIG_KEY_XXX` 常量（避免字符串散落） - `DEFAULT_XXX` 默认值（Object 默认值务必 `Object.freeze`） - `loadXxxConfig(ctx)` 读取 + 校验 + 合法兜底函数，返回值**一定合法** - `ctx.readConfig(key, default)` 的第二参数不是「装饰」，是在 host 里根本没写过这个 key 时唯一的兜底来源；**新增 key 一定要传 default**，否则旧安装会拿到 `undefined`。 - 合法性校验内聚：如 `cardPosition` 只允许 `"top" | "bottom"`，白名单写在 loader 内部；controller / view 拿到的只能是「已经合法的值」，不要再次判断。 - **不要在 `setup(api)` 阶段预读配置做缓存**。配置每次 render 都要 `await` 一次，否则后台改值后必须重启插件才生效，违反文档「即时生效」的期望。 - 向后兼容：新增 key 后，旧安装（host 里没这个 key）拿到的默认值必须能让 UI 原样工作。 - `addon.json` 的 `permissions` 必须同步声明 `config:read`（只读取）或 `config:read` + `config:write`（后台也能写）。漏声明时 `setup(api)` 会直接以权限错误终止，所有注册项全部不生效。 #### 15.4.4 Slot 声明与多点位切换当一个功能可能落在多个 slot 点位（本插件的「卡片放顶部 / 底部」是典型案例）： - `addon.json` 的 `provides.slots` **必须列出所有候选点位**。例如同时支持 `home.right.top` 和 `home.right.bottom`，两个都要写；漏写的那个即使 `registerSlot` 成功，后台也看不到、审计也不过。 - 运行期策略：**两个点位都 `registerSlot`**，在各自 `render(ctx)` 里读最新配置，不匹配当前位置就 `return null`。不要试图「根据配置在 setup 时动态决定注册哪一个」——那样后台改配置必须重启才生效。 - `render()` 返回 `null` = 跳过渲染，**没有任何 DOM 产出**；返回 `{ html: "" }` = 渲染一个空壳节点，可能破坏父容器的 gap / 间距。按意图选其一，不要混用。 - Slot `key` 在单插件内唯一；多点位同功能建议用 `home-shortcut-card-${position}` 这类后缀区分，方便排查日志。 #### 15.4.5 SSR HTML 输出 - 所有进入 HTML 字符串的「配置值 / 用户输入 / 外部数据」必须先过 `escapeHtml`；只有你自己写死的静态片段（如 SVG 图标）可以直出。 - 不要在 SSR HTML 里引用 `window` / `document` / `localStorage`；这些只能放进 `assets/*.js` 里，通过 `clientModule` 由浏览器加载。 - View 层（`views/*.mjs`）保持纯函数：输入 → HTML 字符串，无副作用、不读配置、不发请求。读配置、组装数据在 controller 完成。 #### 15.4.6 增量改动自检闭环每次完成增量功能后，按顺序跑一遍，不要省略： 1. `node --check site/addons/<id>/dist/server.mjs`，以及每个被它 import 的 `.mjs`——先把语法 / 显式 parse error 捞掉。 2. `rg "<你新增或改名的符号>" site/addons/<id>`，确认 import 方和 export 方字符完全一致、没有残留旧名字。 3. 重启 dev server 或在 `/admin/addons` 执行「同步 / 清缓存」，消除模块缓存。 4. 打开后台 `/admin/addons/<id>`，确认 `loadError` 为空、`warnings` 为空。`loadError` 非空时，插件**所有注册项都不会生效**，不要以为只是「那一项坏了」。 5. 打开前台目标页，切换相关后台配置（如本插件的 `cardPosition`），**不重启**刷新页面确认立即生效；如果必须重启才生效，说明违反了 §15.4.3 最后两条。 6. 涉及 slot 的改动，顺便在 DOM 里搜一次你的 slot key，确认只在期望位置出现、没在别的点位重复。 --- ### 15.5 Client / Server 边界与 `server-only` 陷阱从实际踩坑记录整理出的硬性边界规则。**违反任何一条都会让 `next build` 直接失败**（不是运行时报错，是编译期静态分析阶段报错）。 **规则 1：出现在 client bundle 里的文件不允许 import 服务端资源** Next.js 的静态分析会沿着 import 图递归扫描。只要一个"工具文件"被某个 client component 间接引到，它内部的**所有 import** 都会被强制按浏览器可执行校验。禁止在这种文件里 import： - `"server-only"` - `fs` / `path` / `crypto`（node 内置） - 任何 DB / ORM 客户端（`@/lib/db`、`drizzle-orm/*`） - 宿主侧 `src/addons-host/**`（含 SDK 的 server 端、provider runtime） - `next/headers`、`next/server`（部分 API 在 RSC client 边界仍受限）即使该文件里的"服务端函数"**从来没被 client 调用过**也不行——打包器只认静态 import 图，不认运行时是否可达。 **规则 2：同源文件要按"谁调用"拆分** 正确的做法是把同一个逻辑域按调用方拆成两个文件： ``` src/lib/avatar.ts ← 纯函数 / 仅类型工具, RSC + client 都能 import src/lib/avatar-server.ts ← 顶部 import "server-only"; DB / fs / 宿主 SDK 放这里 ``` 然后在 server.ts / route handler / RSC 里 import `avatar-server`，在 `"use client"` 组件里只 import `avatar`。 **规则 3：判断一个文件属于哪一侧** 最靠谱的判断不是看文件名，而是**追溯它被哪条 import 链导入**： - 被任意 `"use client"` 文件（或被它的 transitive import）引到 → **必须 client-safe** - 只被 RSC / route handler / server.ts 引到 → 可以引 server-only 可以 `rg '"use client"' src -l` 找到所有 client 根；然后检查目标文件是否出现在这些根的 import 图上（IDE 的 "Find Usages" 也可以）。 **规则 4：插件侧同样适用** 插件 `dist/server.mjs` 和 `assets/*.js` 是**完全隔离的两套 bundle**： - `dist/server.mjs` 在 Node 里跑，可以用 fs / DB / 宿主 SDK - `assets/*.js` 通过 `/_addons/<id>/assets/xxx.js` 被浏览器加载，绝不能打进任何 Node-only 代码常见错误模式： - ❌ 在插件的 `assets/xxx.js` 顶部 import 了 `./shared/db.js`，而后者引了 `fs` - ❌ 把 `addon.json` 里的 `clientModule` 指向 `dist/server.mjs`（运行时会 500） - ❌ 在 server.ts 的 `render()` 里返回了引用 `window` 的字符串，SSR 时直接报 ReferenceError **规则 5：发现污染后的排查命令** ```powershell # 1. 先看 next build 的第一条 error，它通常指向 bundle 根和触发文件 pnpm next build 2>&1 | Select-String -Pattern 'error|Module not found' -Context 0,3 # 2. 拿到"触发文件"后，反查它的被引用者 rg -l "from ['\"].*avatar['\"]" src # 3. 任何一个被引用者是 "use client" 或被 "use client" 链引到，就说明污染成立 ``` 修复方式永远是**把 server-only 依赖挪到独立文件**，而不是在原文件里 `if (typeof window === ...)` 做运行时判断——静态分析阶段拦截比运行时分支早得多。 ## 16. 最小开发流程建议推荐按下面的顺序开发一个新插件： 1. 在 `addons/<addonId>/` 下创建目录 2. 写好 `addon.json`，并先把首批 `permissions` 声明出来 3. 先只做一个最小 `dist/server.mjs` 4. 只注册一个 public page，确认路由打通 5. 再注册 slot 或 API 6. 如果需要交互，再补 `assets/<client>.js` 7. 到 `/admin/addons` 看后台状态、warning、loadError 8. 最后再补文档和 provider 元数据，并回头收紧到最小权限集 ## 17. 建议的插件交付清单一个可交付插件，至少应包含： - `addon.json` - 可运行的 `dist/server.mjs` - 如有前端交互，包含 `assets/*.js` - 如有样式，包含 `assets/*.css` - 自己的 `README.md` - 版本号变更记录如果要发 zip 包，发布前至少自检： - 是否只有一个 `addon.json` - `id` 是否合法 - 目录名是否与 `id` 一致 - `entry.server` 是否存在 - `permissions` 是否覆盖 `setup(api)` 和运行期真实用到的能力 - `clientModule` 引用的资源是否真的在 `assets/` - `stylesheets` 引用的 CSS 是否真的在 `assets/` - 后装到已构建好的线上环境时，页面是否不依赖宿主 Tailwind 新生成 class - 前台页、后台页、API 路径是否都能打开 ## 18. 一句话总结这套插件系统当前是一个“文件目录 + 清单 + 服务端注册 + 宿主路由转发”的 addon 运行时。开发新插件时，最重要的不是把清单写得多复杂，而是保证这五件事成立： - `addons/<addonId>/addon.json` 存在 - `permissions` 与 `setup(api)` / `context` 实际使用的能力一致 - `dist/server.mjs` 能被直接加载 - `setup(api)` 里完成真实注册 - 需要浏览器访问的文件都放进 `assets/`</article></body></html>

# 插件系统开发文档（addons-host） ## 1. 文档目的这份文档面向后续插件开发者，描述当前仓库里已经落地的插件系统实现方式、目录约定、运行机制和开发流程。先统一一个概念和约束： - 产品和后台文案里叫“插件” - 代码实现里实际使用的是 `addon` / `addons-host` - 核心层只允许做“扩展点 / SDK 暴露”，不写这项业务逻辑本身；业务逻辑与渲染放到 addon 内部完成 - 后文里“插件”和“addon”表示同一套系统。 ### 1.1 强制开发约束以下约束同时适用于插件前台 UI 和后台 UI，默认视为强制规范，不是“建议即可”： - 插件 UI 必须优先复用宿主系统 UI；浏览器侧优先使用 `sdk.ui` 和 `sdk.custom` - 可动态安装 / 覆盖安装的插件，页面级样式必须随插件交付到 `assets/*.css`，并通过 `stylesheets: [context.asset("...css")]` 显式注入；不要依赖宿主生产构建后的 Tailwind CSS 重新扫描插件源码 - 插件自带 CSS 必须使用插件 ID 前缀或命名空间根类（例如 `.ai-chat`、`.points-scratch`），并优先复用宿主 CSS 变量 / 语义 token，例如 `hsl(var(--card))`、`hsl(var(--background))`、`hsl(var(--border))`、`hsl(var(--foreground))`、`hsl(var(--muted-foreground))` - 宿主已经有对应 UI / 交互模式时，插件不要自己重写一套视觉和交互 - 宿主已有组件但还没暴露给插件时，优先补宿主 SDK 暴露，再让插件复用；不要在插件里复制宿主组件源码 - 跟宿主一起进入镜像 / 源码并在 `next build` 前已存在的内置插件，可以复用宿主 `src/app/globals.css` 中的 Tailwind `@source` 扫描；通过后台 ZIP 后装的插件不能依赖这条链路 - 插件禁止在浏览器里引入 `https://cdn.tailwindcss.com`。如果插件选择使用 Tailwind 写样式，必须在插件发布前预编译成 `assets/*.css`，线上只加载静态 CSS 产物 - 插件前后台页面的布局、卡片、按钮、输入框、选择器、弹层等，默认按宿主当前 `shadcn/ui` 体系组织 - 插件采用组件模式时，优先通过 `sdk.ui` / `sdk.custom` 复用宿主 `shadcn/ui` 体系；不要直接 import 宿主内部组件源码 - 如果宿主页面外层已经提供了带边框的 Card / Panel 壳，插件第一层不要再额外包一层同级带边框 Card；插件第一层应优先直接输出布局容器、标题区和内容区，只在内部子分区再按需使用 Card 插件代码结构也要遵守分层约束： - 插件前端交互模块默认采用类似 MVC 的分层设计，至少拆成 `model`、`controller`、`view` - `model` 只负责纯数据逻辑，例如配置归一化、API 请求体 / 响应快照转换、标签 / 节点选项整理 - `controller` 负责状态管理、异步动作编排、事件入口，不直接堆大段渲染结构 - `view` 负责 UI 组合和展示，不把请求构造、数据清洗、复杂副作用混在渲染函数里 - 不要把“页面结构 + 请求提交 + 数据转换 + 样式拼装”混在同一个大文件或同一个大函数里 - 宿主侧如果要为插件新增前端能力，也应优先遵守相同思路：先抽象能力，再暴露给插件消费 ## 2. 当前实现边界当前代码里，插件系统已经稳定支持以下能力： - `slot`：向宿主预留插槽注入内容 - `surface`：接管宿主现有区块的默认渲染，未命中时回退宿主实现 - `action hook`：在宿主生命周期点执行副作用逻辑 - `waterfall`：同步串行改写宿主数据 - `asyncWaterfall`：异步串行改写宿主数据 - `public page`：注册前台页面 - `admin page`：注册后台页面 - `public api`：注册前台 API - `admin api`：注册后台 API - `provider`：统一 provider registry / capability runtime；`payment`、`auth`、`captcha`、`external-auth`、`editor`、`navigation`、`emoji`、`upload`、`home-feed` 已有宿主接线 - `config`：插件级配置读写 - `secret`：插件敏感配置读写 - `background job`：插件自定义后台任务注册、入队与删除 - `data`：结构化插件数据读写 - `data migration`：按 schema version 执行插件数据迁移 - `lifecycle hook`：安装、升级、卸载前的插件自定义生命周期逻辑 - `permissions`：注册期与执行期权限校验 - `external fetch guard`：插件执行期外网访问守卫 - `install / upgrade / uninstall / sync / clear-cache / enable / disable / remove`：安装与管理动作当前**还没有**通用运行时支持的能力： - 插件自带 Prisma schema 自动并表 - 插件 SQL migration 自动发现与自动执行器 - 动态参数路由匹配 - `install.requiresRestart` 自动执行逻辑 ### 2.1 典型业务场景支持矩阵这几个场景很容易被误以为“插件已经支持”，这里单独说明当前真实状态。这里的重点不是“能不能归类成 hook”，而是“当前宿主实际通过哪种机制开放”： | 场景 | 当前状态 | 主要机制 | 说明 | | --- | --- | --- | --- | | 支付网关 / 支付通道接入 | **部分支持** | `payment provider` | 已有专门的 `payment` provider 接线，可接入下单、查单、回调处理；支付成功后的派生副作用可再配合 `payment.paid.*` action hook | | 登录表单增加字段 / 校验 | **部分支持** | `slot` + `auth provider` | 已支持通过 auth form slot 注入额外字段，并通过 `auth` provider 做服务端校验； | | 注册表单增加字段 / 校验 | **部分支持** | `slot` + `auth provider` | 已支持通过 auth form slot 注入额外字段，并通过 `auth` provider 做服务端校验； | | 新增验证码类型 | **部分支持** | `slot` + `captcha provider` | 已支持登录 / 注册 / 发帖页插件验证码 UI 注入，以及 `captcha` provider 服务端校验；登录 / 注册场景下可与系统验证码共存 | | 追加第三方 / 聚合登录入口 | **部分支持** | `slot` + external auth bridge | 已支持插件通过 auth slot 追加登录入口，并通过宿主 external auth bridge 复用现有账号创建 / 绑定 / 登录流程；登录后的副作用可配合 `auth.login.*` 与 `auth.identity.*` hook | | 应用导航 / 页脚导航增加链接 | **部分支持** | `navigation provider` | 当前主要是 provider 注入；如果只是改写主导航数组，也可以使用 `navigation.primary.items` asyncWaterfall | | 首页 tabs 增加插件栏目 / 插件内容成为首页第一屏 | **部分支持** | `home-feed provider` | 已支持插件注册首页 feed 栏目；provider 可返回动态 tab 信息、渲染结果与 metadata。若排序排在 `latest` 之前，根路径 `/` 会把该插件栏目作为首页内容，原最新流仍保留在 `/latest` | | Markdown / 选择器表情扩展 | **部分支持** | `emoji provider` | 已支持 `emoji` provider 注入 Markdown 短码表情，站点渲染和编辑器 / 私信表情面板会复用 | | 替换发帖编辑器 / 评论编辑器 | **部分支持** | `editor provider` | 宿主已接入 `editor` provider，可按场景替换 `post` / `comment` 等编辑器，默认编辑器仍作为 fallback | | 给现有编辑器工具栏追加按钮 | **部分支持** | `editor provider.toolbarItems` | 默认 `RefinedRichPostEditor` 已支持通过 `toolbarItems` 追加按钮；整块替换后的自定义编辑器是否复用这套按钮，由对应 provider 自行决定 | | 替换系统图片上传接口 | **部分支持** | `upload provider` | 已支持插件接管 `/api/upload` 和站点图标上传；插件未处理当前文件时，宿主继续回退到内置 local / s3 上传 | | 插件主动保存文件到系统存储 | **已支持** | `context.files.save()` | 插件可把生成图、导出文件等交给宿主上传存储，复用后台配置的本地 / S3 / OSS / COS，不需要插件单独配置存储 | | 替换系统短信发送接口 | **部分支持** | `sms provider` | 已支持插件注册 `kind: "sms"` 的 provider 接管手机验证码、短信登录、手机找回密码等短信投递；未命中插件 provider 时回退到宿主内置阿里云短信发送器 | | 替换宿主已有页面区块 | **已支持** | `surface` | 宿主继续负责数据加载和页面骨架，插件只决定该区块渲染宿主默认 UI，还是渲染插件实现 | 换句话说： - `hook` 更适合表达生命周期副作用和数据串改，不适合替代需要 UI 注入、能力注册、协议桥接的场景 - `provider` 更适合表达“我提供一种可被宿主消费的能力”，例如支付、验证码、导航、首页 feed 栏目、表情、编辑器、上传 - `slot` 更适合表达“我需要把一块 UI 插到宿主现有页面里” - `surface` 更适合表达“我想保留宿主数据流，但替换它原本那块 UI” - 部分业务场景会同时使用多种机制，例如第三方登录入口通常是 `slot + bridge + action hook` - 这张矩阵描述的是“场景如何接入”，不是“所有场景都应该迁移到 hook” ### 2.2 短信 provider 宿主内置阿里云短信发送器在后台“登录注册 / 短信配置”中配置。插件可以注册 `sms` provider 替换默认发送器；宿主会按 provider `order` 依次尝试，命中插件后不再调用内置阿里云。 ```js api.registerProvider({ kind: "sms", code: "acme-sms", label: "Acme SMS", order: -10, data: { runtime: { async isRunnable(input) { return input.scene?.startsWith("verification") }, async send(input) { await thirdPartySdk.send({ phone: input.phone, templateCode: input.templateCode, params: input.templateParam ?? { code: input.code }, }) return { provider: "acme-sms", sent: true, messageId: "third-party-message-id", } }, }, }, }) ``` 插件主动发短信时使用执行上下文里的 `sms` facade，并在 `addon.json` 里声明 `sms:send` 权限： ```js await context.sms.send({ recipientUsername: "alice", scene: "addon.notice", templateParam: { name: "Alice" }, }) ``` ## 3. 关键目录与文件 ### 3.1 宿主侧 | 路径 | 作用 | | --- | --- | | `src/addons-host/types.ts` | 插件清单、注册项、上下文、渲染结果等核心类型定义 | | `src/addons-host/runtime/loader.ts` | 扫描 `addons/`、读取清单、加载服务端入口、收集注册结果 | | `src/addons-host/runtime/execute.ts` | 执行 slot / surface / page / api | | `src/addons-host/runtime/routes.ts` | 路由查找与挂载路径匹配 | | `src/addons-host/runtime/render.tsx` | 将插件返回的渲染结果输出到页面或区块 | | `src/addons-host/runtime/http.ts` | 插件 API 的统一 HTTP 入口 | | `src/addons-host/runtime/data.ts` | 结构化插件数据存储与 schema version | | `src/addons-host/runtime/config.ts` | 插件配置读写 | | `src/addons-host/runtime/secrets.ts` | 插件敏感配置读写 | | `src/addons-host/runtime/background-jobs.ts` | 插件后台任务注册、分发与队列桥接 | | `src/addons-host/runtime/lifecycle.ts` | 插件 install / upgrade / uninstall 生命周期执行与数据库包装 | | `src/addons-host/runtime/state.ts` | 插件注册表状态映射读写；当前主要用于启用/禁用和最近错误，`uninstalledAt` 仅保留旧数据兼容 | | `src/addons-host/runtime/permissions.ts` | 权限标准化、敏感权限映射与 enforcement | | `src/addons-host/runtime/execution-scope.ts` | 插件执行作用域与外网 fetch 守卫 | | `src/addons-host/hook-catalog.ts` | slot / surface / hook 扩展点目录与合法 hook 名校验 | | `src/addons-host/surface-catalog.ts` | 宿主内建 surface 目录、分类、说明和 server / client / hybrid 模式元数据 | | `src/addons-host/surface-modes.ts` | surface 执行模式查询；当前以 `surface-catalog` 为单一事实源 | | `src/addons-host/installer.ts` | 从 zip 安装、覆盖安装、物理卸载 | | `src/addons-host/management.ts` | 同步注册表、后台管理动作、生命周期日志 | | `src/addons-host/sdk/server.ts` | `defineAddon()` 和服务端类型导出 | | `src/addons-host/sdk/client.tsx` | 浏览器侧 client module 可用的 SDK | ### 3.2 路由侧 | 路径 | 作用 | | --- | --- | | `src/app/addons/[addonId]/[[...slug]]/page.tsx` | 前台插件页面入口 | | `src/app/admin/addons/[addonId]/[[...slug]]/page.tsx` | 后台插件页面入口 | | `src/app/api/addons/[addonId]/[[...slug]]/route.ts` | 前台插件 API 入口 | | `src/app/api/admin/addons/[addonId]/[[...slug]]/route.ts` | 后台插件 API 入口 | | `src/app/%5Faddons/[addonId]/[[...path]]/route.ts` | 插件静态资源入口，对应 `/_addons/...` | | `src/app/api/admin/addons/install/route.ts` | 后台 zip 安装入口 | | `src/app/api/admin/addons/route.ts` | 后台同步/清缓存/启停/物理卸载入口 | ### 3.3 数据持久化 | 路径 | 作用 | | --- | --- | | `prisma/schema.prisma` | 定义 `AddonRegistry`、`AddonLifecycleLog`、`AddonConfig` | | `src/db/addon-registry-queries.ts` | 插件注册表与生命周期日志访问 | | `src/db/addon-config-queries.ts` | 插件配置访问 | ## 4. 插件目录结构宿主只扫描项目根目录下的 `addons/`： ```txt addons/ hello-widget/ addon.json dist/ server.mjs assets/ hello-client.js hello.css .runtime/ addons-secrets.json data/ hello-widget/ __meta.json orders.json .staging/ .trash/ ``` 说明： - 每个插件必须是 `addons/` 下的独立目录 - 目录里必须有 `addon.json` - 服务端入口默认是 `dist/server.mjs` - 浏览器侧脚本、样式、图片、音频等静态资源必须放在 `assets/` - `.runtime`、`.staging`、`.trash` 由宿主维护，不是插件源码目录当前实现里： - `addons/.runtime/addons-secrets.json` 是敏感配置的文件态兜底 - `addons/.runtime/data//` 存放结构化插件数据和 `schemaVersion` - 普通插件配置当前走数据库 `addon_config` - 插件状态当前走数据库 `addon_registry` - zip 安装时先解压到 `addons/.staging` - 物理卸载或覆盖安装旧版本时，旧目录会被移动到 `addons/.trash` ## 5. `addon.json` 清单规范 ### 5.1 最小可运行清单 ```json { "id": "hello-widget", "name": "Hello Widget", "version": "1.0.0", "permissions": ["page:public"] } ``` 如果插件还需要在安装、升级、卸载时处理自己的表结构或初始化数据，可以继续在同一个 server entry 里加 `lifecycle`： ```js export default { async setup(api) { // ... }, lifecycle: { async install(context) { await context.database.executeRaw( `CREATE TABLE IF NOT EXISTS addon_demo_orders ( id TEXT PRIMARY KEY, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() )` ) }, async upgrade(context) { await context.database.executeRaw( `ALTER TABLE addon_demo_orders ADD COLUMN IF NOT EXISTS status TEXT` ) const rows = await context.database.queryRaw( `SELECT COUNT(*)::int AS count FROM addon_demo_orders` ) console.log("existing rows", rows[0]?.count ?? 0) }, async uninstall(context) { await context.database.executeRaw( `DROP TABLE IF EXISTS addon_demo_orders` ) } } } ``` 说明： - `context.database.executeRaw()` / `queryRaw()` 适合处理插件自己的表 - `context.database.transaction()` 可把多步升级包进一个事务 - `context.database.prisma` 可以复用宿主 Prisma Client 访问宿主已有模型，但它**不能**自动识别插件新建表；插件自定义表仍应优先走 raw SQL 说明： - 从 `AddonManifest` 类型上看，`permissions` 仍然是可选字段 - 但对任何会在 `setup(api)` 里调用 `register*()`，或在执行期调用 `context.readConfig()` / `context.data.*()` 这类受保护能力的插件，`permissions` 都应视为**事实上的必填** - 如果缺少所需权限，插件通常不是“部分失效”，而是在加载阶段直接抛错并进入 `loadError` ### 5.2 推荐清单 ```json { "id": "hello-widget", "name": "Hello Widget", "version": "1.0.0", "description": "一个示例插件", "author": "team", "homepage": "https://example.com", "enabled": true, "engines": { "core": "^1.0.0" }, "entry": { "server": "dist/server.mjs" }, "permissions": [ "slot:register", "surface:register", "page:public", "api:public", "config:read", "config:write", "database:sql", "background-job:register", "background-job:enqueue", "background-job:delete", "provider:register" ], "provides": { "slots": ["home.right.top"], "surfaces": ["search.hero"], "pages": [""], "adminPages": ["settings"], "publicApis": ["ping"], "adminApis": ["toggle"], "backgroundJobs": ["sync-remote"], "providers": ["demo"] }, "dependencies": { "addons": [], "conflicts": [] }, "install": { "requiresRestart": false } } ``` ### 5.3 字段说明 | 字段 | 是否必须 | 当前行为 | | --- | --- | --- | | `id` | 是 | 必填；安装时会校验格式是否合法 | | `name` | 是 | 必填 | | `version` | 是 | 必填 | | `description` / `author` / `homepage` | 否 | 展示用途 | | `enabled` | 否 | 作为默认启用状态参与计算 | | `entry.server` | 否 | 服务端入口；默认 `dist/server.mjs` | | `engines.core` | 否 | 仅元数据，当前不会自动校验版本 | | `permissions` | 建议视为是 | manifest 类型层允许省略，但运行时会对注册动作、`context` 敏感能力和外网访问做真实校验；缺失通常会导致插件 `loadError` | | `provides` | 否 | 仅元数据，真正生效的是 `setup(api)` 里的注册 | | `dependencies.addons` / `conflicts` | 否 | 已在安装预检、启用动作和运行时加载阶段校验；缺依赖、依赖未启用、依赖加载失败或命中冲突时会阻止启用或进入 `loadError` | | `install.requiresRestart` | 否 | 当前不会自动执行重启逻辑 | 权限字段的额外说明： - 推荐新插件只使用标准化权限名，例如 `slot:register`、`page:public`、`api:admin`、`background-job:enqueue` - 运行时仍兼容一部分历史写法：`route:public` 会归一化成 `page:public`，`route:admin` 会归一化成 `page:admin` - 历史上写成 `slot:<具体插槽名>` 的权限也会被归一化为 `slot:register`；新文档不再推荐这种写法 ### 5.4 `id` 约束安装器会要求 `id` 满足： - 允许字母、数字、点、短横线 - 不能包含 `..` - 首尾必须是字母或数字 - 总长度 1 到 64 个字符建议： - 插件目录名与 `id` 保持完全一致 - 全部使用小写，例如 `hello-widget`、`acme.editor` 注意： - 运行时扫描阶段如果目录名与 `manifest.id` 不一致，不会阻止加载，但会在后台显示 warning - zip 安装阶段如果 `id` 非法，会直接拒绝安装 ## 6. 加载流程宿主每次加载插件时，大致执行以下步骤： 1. 扫描 `addons/` 下所有非隐藏目录 2. 只处理包含 `addon.json` 的目录 3. 读取并标准化清单 4. 读取数据库 `addon_registry` 里的插件状态；如果注册表不存在，则回退到清单默认值和空状态 5. 计算插件基础 URL： - `/_addons/` - `/addons/` - `/admin/addons/` - `/api/addons/` - `/api/admin/addons/` 6. 如果插件处于禁用状态，或命中旧数据里的 `uninstalledAt` 兼容标记，则不继续执行入口 7. 定位服务端入口，默认 `dist/server.mjs` 8. 使用动态 `import()` 加载入口模块 9. 调用默认导出对象上的 `setup(api)` 10. 在 `setup(api)` 的注册过程中执行权限检查、注册项归一化与重复注册保护，并在需要时运行数据迁移 11. 收集 slot / surface / page / api / provider / hook / migration 注册结果几个关键事实： - 运行时真正要求的入口格式只有一个：`default export` 是一个带 `setup(api)` 的对象 - `defineAddon()` 只是语义化封装，不是强制要求 - 服务端入口加载失败时，插件会保留在列表里，但 `loadError` 不为空，页面、API、插槽都不会生效 - 缺少所需 `permissions` 时，安装通常仍会成功，但插件会在 `setup(api)` 或执行期第一次触发受保护能力时进入 `loadError` - 开发环境下服务端入口会附带基于文件修改时间的版本参数重新导入，避免 Node `import()` 缓存过旧 ### 6.1 注册项归一化与重复处理 `setup(api)` 里的所有注册函数现在都会在进入运行时索引前做一层统一保护： - `key` 会自动 `trim()`；空 key 会直接抛错并让插件进入 `loadError`，避免后台出现不可定位的匿名注册项 - `path` 会通过 `normalizeMountedAddonPath()` 归一化，例如 `/dashboard/` 与 `dashboard` 视为同一路由 - `methods` 会转成大写并去重；同一个 `path + method` 被重复注册时，只保留第一次注册 - `surface` 名称会自动 `trim()`；空 surface 会直接抛错并让插件进入 `loadError` - 未出现在宿主内建 `ADDON_SURFACE_CATALOG` 里的 surface 不会被拒绝，但会写入插件 `warnings`；这用于兼容历史或实验点位，也提醒开发者该 key 当前没有宿主内建声明 - `slot`、`surface`、`provider`、`hook`、`background job`、`data migration` 都会按各自稳定身份去重 - 重复项不会覆盖第一次注册，也不会让整个插件加载失败；宿主会把重复项忽略，并把原因写入插件 `warnings` 重复判定身份如下： | 类型 | 重复判定身份 | | --- | --- | | `slot` | `slot + key` | | `surface` | `surface + key` | | public / admin page | 归一化后的 `path` | | public / admin API | 归一化后的 `path + method` | | `provider` | `kind + code` | | action / waterfall / asyncWaterfall hook | `hook + key` | | background job | `key` | | data migration | `version` | 建议插件开发时仍把注册身份保持唯一；重复保护只用于防止增量开发或动态注册时意外覆盖宿主索引。 ## 7. 服务端入口怎么写最小可运行示例： ```js export default { async setup(api) { api.registerPublicPage({ key: "index", title: "Hello Widget", render() { return { html: "

Hello from addon

" } } }) } } ``` 推荐的完整示例： ```js export default { async setup(api) { api.registerSlot({ key: "home-banner", slot: "home.right.top", order: 10, async render(context) { const enabled = await context.readConfig("enabled", true) if (!enabled) { return null } return { html: `

Hello Widget

当前插件标识：${context.manifest.id}

` } } }) api.registerPublicPage({ key: "index", path: "", title: "Hello Widget", description: "示例前台页面", render(context) { return { html: `

插件主页

API: ${context.publicApi("ping")}

` } } }) api.registerAdminApi({ key: "toggle", path: "toggle", methods: ["POST"], async handle(context) { const job = await context.backgroundJobs.enqueue("sync-remote", { source: "admin" }, { delayMs: 5_000 }) return { json: { ok: true, jobId: job.id } } } }) api.registerBackgroundJob({ key: "sync-remote", async handle(context) { const enabled = await context.readConfig("enabled", true) if (!enabled) { return } await context.writeConfig("lastSyncSource", context.payload?.source ?? "unknown") } }) api.registerProvider({ kind: "demo", code: "hello-widget", label: "Hello Widget Provider" }) } } ``` ## 8. 宿主支持的注册能力 ### 8.1 Slot 用于把内容挂到宿主预留位置： ```js api.registerSlot({ key: "my-block", slot: "post.sidebar.top", order: 100, render(context) { return { text: "这是一个插件区块" } } }) ``` 特点： - 同一个插槽允许多个插件同时输出 - 排序规则是 `order` 升序，再按 `addonId:key` 排序 - `render()` 返回 `null` / `undefined` 时表示本次不输出 - 宿主通过 `` 调用时，插件可从 `context.props` 读取当前点位的上下文数据 - 如果你要的是“替换宿主本来那块 UI”，不要硬塞到 slot 里，改用下面的 `surface` 插件前台页 `/addons//...` 额外开放了一组通用页面插槽： | Slot | 位置 | `context.props` | | --- | --- | --- | | `addon.page.before` | 插件页 `

` 内，标题区和内容区之前 | `{ scope, addonId, addonName, pageKey, routePath, routeSegments }` | | `addon.page.after` | 插件页 `

` 内，内容区之后 | 同上 | | `addon.page.header.before` | 插件页默认标题区开头 | 同上 | | `addon.page.header.after` | 插件页默认标题区末尾 | 同上 | | `addon.page.content.before` | 插件页面渲染块之前 | 同上 | | `addon.page.content.after` | 插件页面渲染块之后 | 同上 | 注意：`addon.page.header.*` 只会在插件页启用默认 heading（`chrome.pageHeading !== false`）时渲染；如果插件完全自绘标题，请使用 `addon.page.before` / `addon.page.content.before`。其他常用页面插槽也会把业务上下文放进 `context.props`： | Slot | `context.props` | | --- | --- | | `board.right.top` / `board.right.middle` / `board.right.bottom` | `{ boardSlug, boardName }` | | `tasks.page.*` / `tasks.header.*` / `tasks.content.*` | `{ userId, pointName, todayCompleted, challengeCompleted, totalCompleted, totalTasks }` | | `leaderboard.page.*` / `leaderboard.hero.*` / `leaderboard.content.*` / `leaderboard.sidebar.*` | `{ title, totalUsers, entryCount, currentUserRank, activeTabHref }` | | `zone.page.*` / `zone.hero.*` / `zone.content.*` / `zone.sidebar.*` | `{ zoneId, zoneSlug, zoneName, boardCount, postCount, currentSort, currentPage, totalPages, totalPosts, canView }` | | `custom-page.page.*` / `custom-page.content.*` / `custom-page.sidebar.*` | `{ pageId, title, routePath, includeHeader, includeLeftSidebar, includeRightSidebar }` | | `funs.app.page.*` / `funs.app.content.*` | `{ appId, appName }`，具体功能页可能额外提供 `isAuthenticated`、广告位或积分字段 | | `feed.page.*` / `feed.main.*` / `feed.latest.*` / `feed.new.*` / `feed.hot.*` / `feed.following.*` / `feed.universe.*` | `{ currentPage, sort, addonTabSlug, settings }` | | `auth.login.page.*` / `auth.login.panel.*` / `auth.login.form.*` | `{ authError, externalAuthEntries, settings }` | | `auth.register.page.*` / `auth.register.panel.*` / `auth.register.form.*` | `{ registrationEnabled, authError?, inviteCode?, inviterUsername?, externalAuthEntries, settings }` | 当前宿主已经开放了大量 slot，完整清单请以这两处为准： - `src/addons-host/types.ts` 里的 `ADDON_SLOT_KEYS` - `docs/插件 Hook 清单.md` 常见示例包括： - `auth.login.form.after` - `auth.register.form.after` - `auth.login.form.before` - `auth.register.form.before` - `auth.login.page.before` / `auth.login.page.after` - `auth.register.page.before` / `auth.register.page.after` - `auth.login.panel.before` / `auth.login.panel.after` - `auth.register.panel.before` / `auth.register.panel.after` - `auth.login.captcha` - `auth.register.captcha` - `post.create.captcha` - `addon.page.before` / `addon.page.after` - `addon.page.header.before` / `addon.page.header.after` - `addon.page.content.before` / `addon.page.content.after` - `post.header.before` - `post.author.name.after` - `home.right.top` - `board.right.top` - `zone.content.before` - `custom-page.content.after` - `funs.app.content.before` - `tasks.content.before` - `leaderboard.sidebar.after` - `layout.head.before` - `layout.header.before` - `layout.header.after` - `layout.body.end` - `settings.content.before` - `messages.page.after` 注意： - 运行时不会在 JS 层强制校验 slot 名称是否合法 - 但宿主只会执行它自己调用过的 slot - 写了未知 slot 名称不会报错，只是永远不会被渲染 #### Surface 用于接管宿主现有区块的默认渲染，但仍复用宿主自己的数据来源和页面结构。最小示例： ```js api.registerSurface({ key: "search-hero", surface: "search.hero", render(context) { return { html: `

插件版搜索头部

` } } }) ``` 对客户端交互区块，优先使用 `clientModule`： ```js api.registerSurface({ key: "post-tools", surface: "post.create.tools", clientModule: "write-tools.js" }) ``` 特点： - 同一个 `surface` 同时只会命中一个插件 - 选择规则是 `priority` 降序，再按 `addonId:key` 稳定排序 - 插件没有命中、`render()` 返回 `null` / `undefined`、插件报错或客户端模块加载失败时，宿主会回退到默认 UI - 宿主内建 surface 目录在 `src/addons-host/surface-catalog.ts`；它会同时进入 `ADDON_EXTENSION_POINT_CATALOG`，供后台、文档生成或插件开发工具枚举 - 注册未知 surface 会保留兼容行为，但插件会收到 warning；新插件应优先从 `ADDON_SURFACE_CATALOG` / `docs/插件 Hook 清单.md` 里选择已声明点位 - 服务端区块可使用 `render(context)` 返回 `AddonRenderResult` - 客户端交互区块更适合使用 `clientModule`，宿主会把当前区块 props 直接传给插件组件 - `messages.page`、`settings.page` 属于 hybrid surface：宿主会先尝试服务端 `render(context)`，未命中时再继续走 `clientModule` 或默认 UI - `messages.header`、`messages.sidebar`、`messages.thread`、`collection.hero`、`collection.pending`、`collection.content`、`history.panel`、`settings.content`、`tasks.header`、`tasks.content`、`post.weibo.feed`、`post.create.form`、`post.create.tools`、`post.create.editor`、`post.create.enhancements`、`post.create.submit`、`comment.author.row`、`comment.author.meta`、`comment.author.verification`、`comment.author.name`、`comment.author.badges` 属于 client-only surface：必须使用 `clientModule`，单独注册 `render()` 会在加载阶段被拒绝 - 微博模式列表开放了 `post.weibo.feed` client-only surface。`context.props` 会包含 `items`、`source`（`feed` / `post-stream`）、`showBoard`、`showPinBadge`、`postLinkDisplayMode`；节点 / 分区帖子流还会包含 `sortLinks`。如果只是调整摘要、预览媒体、统计或排序，优先用 `post-list.display.items`；只有要整块替换微博模式 UI 时再接管这个 surface。 - 帖子详情头部额外开放了 `post.header`、`post.author.row`、`post.author.meta`、`post.author.verification`、`post.author.name`、`post.author.badges`，适合做用户名、认证位、勋章位的深度定制 - 上述帖子详情 surface / slot 的 `context.props` 会包含 `post`、`authorHref`、`authorNameClassName`、`boardHref`、`isFollowingPost`、`isRestrictedAuthor`、`zone`、`zoneBoards`；其中 `post.author.verification` 额外包含 `verification`，`post.author.badges` 额外包含 `badges` - 帖子正文区开放了 `post.body`，覆盖正文块、投票和附件的默认渲染；`post.body.before` / `post.body.after` 仍保留为前后插入位。 - 插件前台页、全站页头、登录 / 注册、首页内容流、任务中心、榜单、用户主页、分区页、自定义页、友情链接页和功能应用页均已按成对 slot 补齐对应 surface，例如 `addon.page/header/content`、`layout.header`、`auth.login.page/panel/form`、`auth.register.page/panel/form`、`feed.page/main/latest/new/hot/following/universe`、`tasks.page/header/content`、`leaderboard.page/hero/content/sidebar`、`user.page/profile/activity/sidebar`、`zone.*`、`custom-page.*`、`friend-links.page`、`funs.app.page/content`。 - 评论区还开放了 `comment.author.row`、`comment.author.meta`、`comment.author.verification`、`comment.author.name`、`comment.author.badges` 这组 client-only surface，宿主会把 `entryType`、`entry`、`authorHref`、`authorNameClassName`、`isRestrictedAuthor`、`shouldDimRestrictedAuthor`、`showVerification` 等上下文传入 `context.props` 命名约定： - 大多数成对开放的 `*.before` / `*.after` slot，都对应同名 `surface` - 例如 `search.hero.before` / `search.hero.after` 对应 `search.hero` - 例如 `topup.payment.before` / `topup.payment.after` 对应 `topup.payment` - 例如 `messages.thread.before` / `messages.thread.after` 对应 `messages.thread` - 例如 `post.create.tools.before` / `post.create.tools.after` 对应 `post.create.tools` - 例如 `post.author.name.before` / `post.author.name.after` 对应 `post.author.name` - 例如 `post.author.badges.before` / `post.author.badges.after` 对应 `post.author.badges` - 例如 `addon.page.content.before` / `addon.page.content.after` 对应 `addon.page.content` - 例如 `auth.login.panel.before` / `auth.login.panel.after` 对应 `auth.login.panel` - 例如 `feed.main.before` / `feed.main.after` 对应 `feed.main` ### 8.2 Public Page / Admin Page 注册页面的方式： ```js api.registerPublicPage({ key: "index", path: "", title: "插件首页", chrome: { header: true, pageHeading: false, rightSidebar: true, contentLayout: "wide", }, render() { return { html: "

hello

" } } }) api.registerAdminPage({ key: "settings", path: "settings", title: "插件设置", render() { return { text: "admin page" } } }) ``` 路由映射： - 前台页面：`/addons//` - 后台页面：`/admin/addons//` 注意： - `path` 是相对路径，前后 `/` 会被自动去掉 - `path: ""` 或省略 `path` 时，对应插件根路径 - 当前匹配规则是**精确匹配** - 暂不支持 `:id`、`[slug]`、通配符之类的动态路由 - public page 还可以通过 `chrome` 控制宿主页外壳是否显示： - `header` - `footer` - `leftSidebar` - `rightSidebar` - `pageHeading` - `contentLayout` - 这些外壳选项默认全部关闭；也就是说插件前台页默认只渲染插件自己的主体，不自动带站点头部、底部和全局左右侧栏 - `pageHeading` 默认显示；设置为 `false` 时，宿主插件页壳顶部那块「addonId + 标题 + 描述」会被隐藏 - `contentLayout` 用于无左右侧栏的插件页主体宽度；默认值为 `"default"`，宿主会使用阅读型内容宽度；设置为 `"wide"` 时，主体会撑满插件页外层容器，适合画布、工作台、仪表盘类插件 - 如果插件声明 `chrome.footer: true`，宿主会在插件页内部主动渲染全局页脚；根布局对 `/addons/*` 路径默认不再自动附带 footer，避免重复后台页额外说明： - 后台页面会先经过宿主的管理员鉴权 - 未登录或非管理员用户不能访问后台插件页 ### 8.3 Public API / Admin API 注册 API： ```js api.registerPublicApi({ key: "ping", path: "ping", methods: ["GET"], handle() { return { json: { ok: true } } } }) ``` 路由映射： - 前台 API：`/api/addons//` - 后台 API：`/api/admin/addons//` 返回值支持两种写法： - 直接返回 `Response` - 返回宿主可归一化的对象： - `{ json, status, headers }` - `{ text, status, headers }` - `{ html, status, headers }` 注意： - `methods` 默认是 `["GET"]` - 当前 API 路由同样是**精确匹配** - 后台 API 由宿主统一做管理员鉴权 - 前台 API 不做额外鉴权，插件自己决定要不要校验登录态或权限插件 API 请求还会触发一组接口级 action hook： | Hook | 触发时机 | Payload | | --- | --- | --- | | `addon.api.request.before` | 插件 API 路由命中后、插件 `handle()` 执行前 | `{ scope, addonId, routePath, routeSegments, method, pathname }` | | `addon.api.request.after` | 插件 API 请求结束后；404 / 403 / 500 也会尽量触发 | `{ scope, addonId, routePath, routeSegments, method, pathname, status, matched, errorMessage? }` | `addon.api.request.before` 在宿主侧以 `throwOnError: true` 执行，插件可以抛错阻断当前 API 请求；`addon.api.request.after` 适合做审计、指标、访问日志和失败告警。 ### 8.4 Provider 注册 provider： ```js api.registerProvider({ kind: "payment", code: "hello-pay", label: "Hello Pay", description: "示例 Provider" }) ``` 当前 provider 的实际状态： - 会被加载、统计，并显示在后台详情里 - 宿主会按 `kind` 把 provider 统一收集到 registry / capability 层 - 当前已经接线的 `kind` 包括：`payment`、`auth`、`captcha`、`external-auth`、`editor`、`navigation`、`emoji`、`upload` - 这些接线既支持读取静态 `provider.data`，也支持调用 `provider.data.runtime` 上的 runtime hooks - provider runtime 的执行同样会进入 addon execution scope，继承权限检查与外网访问守卫 - 还没有宿主消费端接线的 `kind` 仍然可以注册并展示在后台，但不会自动产生业务效果 ### 8.5 支付网关 Provider 怎么接如果插件要接入支付网关，当前可行方式不是注册 page / api 自己绕开，而是注册一个： ```js api.registerProvider({ kind: "payment", code: "hello-pay", label: "Hello Pay", description: "示例支付提供方", data: { settingsHref: "/admin/addons/hello-pay/settings", settingsLabel: "打开插件配置", runtime: { listChannels() { return [ { channelCode: "hello-pay.web", label: "Hello Pay 网页支付", description: "示例网页收银台", clientTypes: ["WEB_DESKTOP", "WEB_MOBILE"], presentationType: "HTML_FORM", }, ] }, async isRunnable({ context }) { const appId = await context.readSecret("appId", "") return Boolean(appId) }, getDefaultNotifyPath() { return "/api/payments/notify/hello-pay" }, getDefaultReturnPath() { return "/topup/result" }, async createCheckout(input) { return { presentation: { type: "HTML_FORM", html: "", }, providerTradeNo: "demo-trade-no", requestPayload: null, responsePayload: null, redirectUrl: null, providerTraceId: null, } }, async queryOrder(input) { return { ok: true, orderStatus: "PAID", tradeStatus: "SUCCESS", paidAt: new Date().toISOString(), } }, async handleNotification({ request }) { return { verified: true, merchantOrderNo: "pay_xxx", providerTradeNo: "trade_xxx", tradeStatus: "SUCCESS", orderStatus: "PAID", payload: Object.fromEntries(new URL(request.url).searchParams.entries()), } }, }, }, }) ``` 当前支付 provider runtime 已接入的能力包括： - `listChannels()`：声明插件提供的支付通道 - `isRunnable()`：告知宿主当前 provider 是否可运行 - `getDefaultNotifyPath()`：返回默认异步回调地址 - `getDefaultReturnPath()`：返回默认前台返回地址 - `createCheckout()`：创建下单结果 - `queryOrder()`：主动查单 - `handleNotification()`：处理第三方回调几个关键事实： - 宿主会把 `kind === "payment"` 的 provider 自动并入支付网关注册表 - 后台支付网关页会显示插件 provider - 插件回调入口统一走 `/api/payments/notify/` - 这套能力目前只对支付场景生效，不代表其他 `provider.kind` 也会自动被宿主解析 ### 8.6 登录 / 注册表单扩展怎么接当前第一版 auth 扩展，支持两件事： 1. 在登录 / 注册表单末尾插入插件自定义字段 2. 在服务端对这些额外字段执行插件校验 #### 8.6.1 表单注入位置当前宿主开放了四个 auth 表单插槽： - `auth.login.form.before` - `auth.login.form.after` - `auth.register.form.before` - `auth.register.form.after` `*.form.before` 会被渲染在宿主内置字段之前；`*.form.after` 会被渲染在宿主内置字段和验证码区块之后、提交按钮之前。登录 / 注册页还开放了 `auth.login.page.*`、`auth.login.panel.*`、`auth.register.page.*`、`auth.register.panel.*`，用于在页面主体和认证面板前后追加 UI。如果插件想让自己的字段跟随表单一起提交，约定如下： - 额外字段必须放在 `auth.*.form.before`、`auth.*.form.after` 或验证码 slot 里渲染 - 额外字段的表单名必须以 `addon:` 开头 - 例如：`addon:otpCode`、`addon:inviteToken` 示例： ```js api.registerSlot({ key: "login-otp-field", slot: "auth.login.form.before", render(context) { return { html: `

二次验证码

`, } }, }) ``` #### 8.6.2 服务端校验方式如果插件要对登录 / 注册做额外校验，需要注册一个 `kind: "auth"` 的 provider： ```js api.registerProvider({ kind: "auth", code: "hello-auth", label: "Hello Auth", data: { runtime: { validateLogin({ addonFields, user }) { const otpCode = addonFields.otpCode if (typeof otpCode !== "string" || otpCode !== "123456") { return { ok: false, message: "二次验证码错误", } } }, validateRegister({ addonFields, payload }) { const inviteToken = addonFields.inviteToken if (typeof inviteToken !== "string" || !inviteToken.trim()) { return "请填写扩展邀请码" } if (payload.email && !payload.email.endsWith("@example.com")) { return { ok: false, message: "仅允许 example.com 邮箱注册扩展入口", } } }, }, }, }) ``` 当前 auth provider runtime 已接入的能力包括： - `validateLogin(input)`：登录基础凭证校验通过后执行扩展校验 - `validateRegister(input)`：注册内置字段、验证码、邮箱/手机验证码校验通过后执行扩展校验校验输入里当前可用的重点字段： - `addonFields`：来自表单里所有 `name="addon:*"` 的字段 - `request`：当前原始请求 - `context`：插件执行上下文，可读写 config / secret - 登录场景额外提供：`username`、`user` - 注册场景额外提供：`payload`、`registerIp` #### 8.6.3 当前 auth 扩展的边界当前第一版只支持“加字段 + 阻断式校验”，还**不支持**： - 改写宿主内置用户名 / 密码 / 邮箱 / 手机等核心字段语义 - 自动把插件自定义字段持久化到用户主表 #### 8.6.4 追加第三方 / 聚合登录入口怎么接如果插件不是想“加字段”，而是想在登录 / 注册表单里追加一个第三方登录按钮组，也可以继续使用： - `auth.login.form.after` - `auth.register.form.after` 这类插件通常不需要提交 `addon:*` 字段，而是直接渲染一组跳转链接或按钮。推荐模式： 1. 插件在 auth slot 里追加一个“第三方登录入口” 2. 用户点击后，进入插件自己的 public API，例如 `/api/addons//start` 3. 插件在这个 API 里完成第三方授权初始化 4. 第三方回调插件自己的 public API，例如 `/api/addons//callback` 5. 插件把标准化后的身份信息转交给宿主 external auth bridge 6. 宿主继续复用现有 external auth 流程，完成： - 自动登录 - 自动注册 - 补充用户名 - 绑定已有账户 - `mode=connect` 时绑定到当前登录账户宿主新增了两个桥接 API： - `POST /api/auth/addon-external/start` - `POST /api/auth/addon-external/finish` 它们不是插件页面直接给最终用户访问的入口，而是插件 server API 在服务端中转时调用的内部桥接接口。如果插件还想把“绑定某个第三方渠道”的入口显示到用户设置页，除了桥接 API 以外，还应再注册一个： - `kind: "external-auth"` provider ##### `POST /api/auth/addon-external/start` 作用： - 让宿主写入 external auth flow state - 复用现有 cookie / 签名流程 - 让插件后续可以安全回到宿主的 external auth 链路请求体： ```json { "addonId": "zn29o-login", "provider": "zn29o_qq", "mode": "login" } ``` 可选 `mode`： - `login` - `register` - `connect` 插件调用时必须附带请求头： - `x-addon-auth-secret` 这个 secret 由插件自己保存在： - `readSecret("external-auth-bridge-secret")` - `writeSecret("external-auth-bridge-secret", value)` ##### `POST /api/auth/addon-external/finish` 作用： - 把插件自己拿到的第三方身份信息转交给宿主 - 宿主继续执行现有 external auth 逻辑请求体： ```json { "addonId": "zn29o-login", "mode": "login", "identity": { "method": "oauth", "provider": "zn29o_qq", "providerLabel": "智南聚合登录 · QQ", "providerAccountId": "social_uid_xxx", "providerUsername": "nickname", "providerEmail": null, "emailVerified": false, "displayName": "昵称", "avatarUrl": "https://example.com/avatar.jpg" } } ``` 这里的 `identity` 结构，本质上就是宿主现有的 `ExternalAuthIdentity`。桥接完成后： - 如果第三方账户已绑定站内账户，宿主直接登录 - 如果还没绑定，但可自动注册，宿主直接创建用户并登录 - 如果需要补用户名或绑定已有账户，宿主会跳转到现有 `/auth/complete` - 如果 `mode=connect`，宿主会把这个第三方账户绑定到当前登录用户重要约束： - 插件自己负责和第三方平台交互 - 宿主不会替插件完成 OAuth / code 换 token / 查询用户信息 - 插件只是在“拿到标准化身份信息之后”把结果交给宿主 - `provider` 建议使用稳定的小写编码，例如 `zn29o_qq`、`acme_wechat` - 同一个插件里的不同第三方渠道，建议使用不同 `provider` 账户设置页当前也已经支持显示和解绑这类动态 provider。 ##### `kind: "external-auth"` provider 这个 provider 的用途不是做登录校验，而是告诉宿主： - 当前插件有哪些外部登录渠道 - 这些渠道在账户设置页里该怎么展示 - 用户点击“绑定”后应该跳到哪个插件入口推荐写法： ```js api.registerProvider({ kind: "external-auth", code: "acme-external-auth", label: "Acme Login", data: { runtime: { async listEntries({ context }) { return [ { provider: "acme_wechat", label: "Acme · 微信", loginUrl: context.publicApi("start") + "?mode=login&type=wechat", registerUrl: context.publicApi("start") + "?mode=register&type=wechat", connectUrl: context.publicApi("start") + "?mode=connect&type=wechat", description: "通过 Acme 登录绑定微信账号", order: 50, }, ] }, }, }, }) ``` 每个 entry 当前支持： - `provider`：最终写入 `authAccount.provider` 的 provider code - `label`：账户设置页展示名称 - `loginUrl`：登录页“其它登录方式”使用的入口 - `registerUrl`：注册页“快捷注册方式”使用的入口 - `connectUrl`：用户在账户设置页点击“绑定”后跳转的地址 - `description` - `order` 宿主当前行为： - 如果 entry 提供 `loginUrl`，它会并入登录页“其它登录方式” - 如果 entry 提供 `registerUrl`，它会并入注册页“快捷注册方式” - 如果该 provider 已经绑定，会显示“已绑定”并允许解绑 - 如果该 provider 还没绑定，但 provider entry 提供了 `connectUrl`，会显示“绑定”按钮 - 如果 provider 只存在绑定记录、但当前插件没有再声明 `connectUrl`，账户设置页仍会显示这条记录，但只允许解绑 ### 8.7 插件验证码怎么和系统验证码共存当前第一版 captcha 扩展，支持两件事： 1. 在登录 / 注册 / 发帖页注入插件自己的验证码 UI 2. 在服务端追加执行插件验证码校验 #### 8.7.1 验证码注入位置当前宿主开放了三个验证码插槽： - `auth.login.captcha` - `auth.register.captcha` - `post.create.captcha` 其中： - `auth.login.captcha`、`auth.register.captcha` 会和宿主内置验证码区块放在同一个安全校验区域里 - `post.create.captcha` 会渲染在 `/write` 新建帖子与 `/write?mode=edit` 编辑帖子表单内部、提交按钮区域之前这意味着： - 如果系统验证码开启，插件验证码会叠加显示和叠加校验 - 如果系统验证码关闭，但插件在这些 slot 里渲染了内容，页面仍然会显示插件验证码区块 - 如果只想使用插件验证码，把后台登录 / 注册验证码模式设为 `OFF` 即可这些 slot 里的插件字段，如果要跟随宿主表单一起提交，仍然使用同一套约定： - 字段名必须以 `addon:` 开头 - 例如：`addon:captchaCode`、`addon:geetest-captcha.lot_number` - 登录 / 注册场景会直接从表单提取这些字段 - 发帖场景会在前端提交 `/api/posts/create` 与 `/api/posts/update` 时把这些字段收集进 JSON `addonFields` 示例： ```js api.registerSlot({ key: "login-addon-captcha", slot: "auth.login.captcha", render() { return { html: `

插件验证码

`, } }, }) ``` #### 8.7.2 服务端校验方式如果插件要追加验证码校验，需要注册一个 `kind: "captcha"` 的 provider： ```js api.registerProvider({ kind: "captcha", code: "hello-captcha", label: "Hello Captcha", data: { runtime: { verifyLoginCaptcha({ addonFields }) { if (addonFields.captchaCode !== "654321") { return { ok: false, message: "插件验证码错误", } } }, verifyRegisterCaptcha({ addonFields, payload }) { if (typeof addonFields.captchaCode !== "string" || addonFields.captchaCode.length < 4) { return "请填写插件验证码" } if (payload.username.startsWith("bot_")) { return { ok: false, message: "该用户名不允许通过插件验证码校验", } } }, verifyCreatePostCaptcha({ addonFields, payload }) { if (typeof addonFields.captchaCode !== "string" || addonFields.captchaCode.length < 4) { return "请先完成发帖插件验证码" } if (payload.postType === "LOTTERY" && payload.boardSlug === "sandbox") { return { ok: false, message: "当前节点的抽奖帖不允许通过这个验证码入口提交", } } }, }, }, }) ``` 当前 captcha provider runtime 已接入的能力包括： - `verifyLoginCaptcha(input)`：在宿主内置登录验证码之后追加执行 - `verifyRegisterCaptcha(input)`：在宿主内置注册验证码之后追加执行 - `verifyCreatePostCaptcha(input)`：在 `/api/posts/create` 与普通编辑模式下的 `/api/posts/update` 基础参数校验通过后执行校验输入里当前可用的重点字段： - `addonFields`：来自表单里所有 `name="addon:*"` 的字段 - `request`：当前原始请求 - `context`：插件执行上下文，可读写 config / secret - 登录场景额外提供：`username` - 注册场景额外提供：`payload`、`registerIp` - 发帖场景额外提供：`payload` 目前包含 `title`、`content`、`boardSlug`、`postType`、`isAnonymous` 等已通过宿主基础校验的发帖字段 #### 8.7.3 当前 captcha 扩展的边界当前第一版 captcha 扩展是“附加层”，不是“替换层”： - 宿主内置验证码和插件验证码可以同时开启 - 宿主会先执行内置验证码，再执行插件验证码 - 如果只想用插件验证码，就把后台登录 / 注册验证码模式改成 `OFF` - 发帖页当前没有宿主内置验证码，是否启用完全由插件自己决定当前还**不支持**： - 在后台选择“某一个插件 captcha provider”为唯一验证码实现 - 对多个 captcha provider 做优先级、互斥、路由规则管理 - 让宿主自动生成插件验证码 UI；当前仍需插件自己在 slot 里渲染字段 ### 8.8 导航、表情、编辑器与首页 Feed 扩展当前宿主新增了四类 provider 接线： - `navigation` provider：向 `header-app`、`footer` 注入链接 - `emoji` provider：注入 Markdown 短码表情，前台 Markdown 渲染、编辑器表情面板和私信表情面板都会复用 - `editor` provider：替换 `post`、`comment`、`profile`、`admin`、`generic` 场景的编辑器 - `home-feed` provider：向首页 feed tabs 注入插件栏目，并由宿主负责 `/feed/` 路由和“第一位即首页”的默认入口切换 `navigation` provider 支持两种写法： - 静态：`provider.data.links` - 动态：`provider.data.runtime.listLinks(input)` 其中每个 link 至少要提供： - `placement`：`header-app` 或 `footer` - `href` - `name` / `label` - `icon`：仅 `header-app` 建议提供，未提供时宿主回退到 `⭐` `emoji` provider 同样支持两种写法： - 静态：`provider.data.items` - 动态：`provider.data.runtime.listItems(input)` 返回值使用宿主现有的 `MarkdownEmojiItem[]` 结构： - `shortcode` - `label` - `icon` `editor` provider 现在支持两类能力： - 整块替换编辑器 - 给默认 `RefinedRichPostEditor` 追加 toolbar button 宿主会先按场景挑选 provider，命中 `clientModule` 时整块加载其客户端模块；未命中时仍回退到默认 `RefinedRichPostEditor`。`toolbarItems` 只作用在默认编辑器，不会自动注入到“整块替换”的自定义编辑器里。 `editor` provider 当前支持： - `provider.data.clientModule`：客户端模块路径，可写插件 assets 下的相对路径 - `provider.data.supports` / `provider.data.contexts`：支持的编辑器场景 - `provider.data.runtime.getClientModule(input)`：动态返回客户端模块路径 - `provider.data.runtime.getSupports(input)`：动态返回支持场景 - `provider.data.toolbarItems`：为默认编辑器追加 toolbar item - `provider.data.runtime.getToolbarItems(input)`：动态返回 toolbar item 列表 `home-feed` provider 当前推荐使用动态写法： - `provider.data.runtime.getTab(input)`：返回当前插件栏目配置；返回 `null` / `undefined` 时表示隐藏入口 - `provider.data.runtime.render(input)`：返回 `AddonRenderResult`，由宿主在首页 feed 主区域渲染 - `provider.data.runtime.getMetadata(input)`：可选；返回 `{ title, description }` 用于当前栏目页面的 metadata `getTab(input)` 建议至少返回： - `slug`：栏目路由 slug，例如 `micro-feed` - `label`：tabs 上显示的文案 - `order`：排序值；宿主内置 tabs 的默认顺序是 `latest=100`、`new=200`、`hot=300`、`following=400`、`universe=500` - `description`：可选；用于 metadata fallback 或后台说明行为约定： - 当插件栏目 `order < 100` 且它是当前最靠前的可见 tab 时，根路径 `/` 会直接显示该插件栏目内容 - 插件即使占据首页第一位，原最新流也不会消失，仍然固定可通过 `/latest` 访问 - `home-feed` provider 不需要注册独立 public page；推荐直接把内容渲染到宿主首页 feed 壳内 - 如果你的入口位置来自后台配置，不要在 `setup()` 时动态决定是否 `registerProvider()`；应始终注册 provider，并在 `getTab()` 里读取最新配置后返回 tab 或 `null` 编辑器客户端模块应导出以下任一接口： - `Component` - `createComponent(sdk)` 宿主会向插件组件传入： - `value` - `onChange` - `placeholder` - `minHeight` - `disabled` - `uploadFolder` - `markdownEmojiMap` - `markdownImageUploadEnabled` - `context` - `providerCode` - `providerLabel` toolbar item 当前支持的字段： - `key` - `clientModule` - `supports` / `contexts` - `order` - `label` - `title` - `description` toolbar item 客户端模块会额外收到： - `item` - `disabled` - `value` - `selection` - `editor` 其中 `editor` 当前提供： - `focus()` - `preserveSelection()` - `getSelection()` - `getValue()` - `setValue(value)` - `insertTemplate(template)` - `replaceSelection(value)` - `wrapSelection(before, after?)` - `setHeadingLevel(level)` - `toggleBold()` - `toggleUnderline()` - `toggleStrike()` - `toggleHighlight()` - `formatCode(type)` - `toggleQuote()` - `formatList(type)` - `insertDivider()` - `align(value)` 最小示例： ```js api.registerProvider({ kind: "editor", code: "callout-tools", label: "Callout 工具条扩展", data: { toolbarItems: [ { key: "insert-callout", clientModule: "client/insert-callout.js", contexts: ["post", "comment"], order: 120, label: "Callout", title: "插入提示块", }, ], }, }) ``` 对应的 `client/insert-callout.js` 可以导出： ```js export function Component({ item, disabled, editor, sdk }) { const { AlertCircle } = sdk.icons return ( ) } ``` 仍未支持的部分只有： - toolbar button 分组、插入到某个内置按钮之前/之后 - 对“整块替换”的自定义编辑器强制复用宿主默认 toolbar item ### 8.9 上传 Provider 如果插件要接管系统图片上传链路，当前推荐注册一个 `kind: "upload"` 的 provider： ```js api.registerProvider({ kind: "upload", code: "ceoimg", label: "CEOIMG", description: "将系统图片上传转发到 CEOIMG 图床。", data: { runtime: { async uploadFile({ context, file, preparedFile, folder }) { const settings = await context.readConfig("settings", {}) if (!settings.enabled || folder === "attachments") { return null } const formData = new FormData() formData.append("strategy_id", "1") formData.append( "file", new Blob([preparedFile.buffer], { type: preparedFile.detectedMime }), file.name, ) const response = await fetch("https://example.com/upload", { method: "POST", body: formData, }) const result = await response.json() return { urlPath: result.data.links.url, } }, }, }, }) ``` 当前 upload provider runtime 已接入的能力包括： - `uploadFile(input)`：尝试处理当前上传请求上传 runtime 输入里当前可用的重点字段： - `request`：当前原始请求；可选 - `actor`：当前操作者摘要；用户上传和后台管理员上传都会传入 - `file`：原始 `File` - `preparedFile.buffer`：宿主完成校验、必要时加水印后的最终二进制内容；图片上传场景下通常存在，二进制附件场景可能为 `null` - `preparedFile.fileHash` - `preparedFile.detectedMime` - `preparedFile.fileSize` - `folder`：当前上传 bucket，例如 `posts`、`avatars`、`icon` - `context`：插件运行时上下文，可读写 config / secret 当前宿主行为： - `/api/upload` 与站点图标上传都会先尝试 `upload provider` - provider 返回 `null` / `undefined` 时，宿主继续回退到内置 local / s3 上传 - provider 返回上传结果时，宿主继续复用现有去重、入库、日志流程 - 帖子附件上传也会经过同一调度层，但插件可以按 `folder` 或 MIME 类型选择跳过，让宿主继续使用本地 / s3 - upload provider 不需要新增专门权限名；注册期仍使用 `provider:register`，访问外网仍需要 `network:external` ### 8.9.1 插件主动调用系统文件存储如果插件自己产生了文件，例如 AI 生图、报表导出、海报生成，不要把文件写进插件 `assets/` 目录，也不要在插件后台重复配置 OSS / COS / 本地存储。插件运行时可以调用 `context.files.save()`，把文件交给宿主系统上传能力处理： ```js const saved = await context.files.save({ fileName: `result-${Date.now()}.png`, content: imageBuffer, mimeType: "image/png", folder: "my-addon", bucketType: "my-addon", userId: currentUser?.id, username: currentUser?.username, }) return { url: saved.urlPath, uploadId: saved.uploadId, } ``` `addon.json` 需要声明： ```json { "permissions": ["file:write"] } ``` `context.files.save(input)` 支持的重点字段： - `fileName`：必填，原始文件名；宿主会清理不安全字符 - `content` / `buffer`：`Buffer`、`Uint8Array`、`ArrayBuffer` 或 `Blob` - `base64`：可直接传纯 base64 内容 - `dataUrl`：可直接传 `data:image/png;base64,...` - `mimeType`：建议显式传入，例如 `image/png` - `folder`：存储目录 / bucket 前缀，默认使用当前插件 ID；只能包含字母、数字、点、下划线和短横线 - `bucketType`：写入 `Upload.bucketType` 的分类，默认等于 `folder` - `userId` / `username`：如果传入用户 ID，宿主会写入 `Upload` 记录并按同用户、同 bucket、同 hash 去重；未传用户 ID 时只保存文件，不写用户上传记录返回值： - `uploadId`：写入 `Upload` 记录时返回 ID；未绑定用户时为 `null` - `urlPath`：可直接给前台展示的访问地址 - `fileName` - `fileExt` - `mimeType` - `fileSize` - `fileHash` - `storagePath` 宿主行为： - 复用后台“上传设置”里的本地 / S3 / OSS / COS 配置 - 仍会先尝试已注册的 `upload provider`；provider 不处理时回退到宿主内置存储 - 复用宿主图片类型白名单、大小限制、MIME 头校验和图片水印逻辑 - 这是服务端上下文能力，只能在 page / api / background job / hook / lifecycle 等服务端插件代码里调用；浏览器侧 `assets/*.js` 不能直接调用 - 如果插件需要访问外部接口下载文件再保存，外部 HTTP(S) 请求本身仍需要 `network:external` ### 8.10 通用 Action Hook 宿主统一通过 `api.registerActionHook()` 暴露生命周期副作用点。注册方式： ```js api.registerActionHook({ key: "after-login-sync", hook: "auth.login.after", async handle(context) { const { payload, data } = context await data.put("login-events", { id: `${payload.userId}:${payload.username}`, value: payload, }) }, }) ``` 当前宿主已开放的 action hook 包括： - `auth.login.before` - `auth.login.after` - `auth.register.before` - `auth.register.after` - `auth.identity.bind.before` - `auth.identity.bind.after` - `auth.identity.unbind.before` - `auth.identity.unbind.after` - `auth.password.change.before` - `auth.password.change.after` - `auth.password.reset.before` - `auth.password.reset.after` - `post.create.before` - `post.create.after` - `comment.create.before` - `comment.create.after` - `message.send.before` - `message.send.after` - `report.create.before` - `report.create.after` - `task.complete.after` - `check-in.submit.before` - `check-in.submit.after` - `payment.paid.before` - `payment.paid.after` - `invite-code.purchase.before` - `invite-code.purchase.after` - `redeem-code.redeem.before` - `redeem-code.redeem.after` - `user.update.before` - `user.update.after` - `user.notification-settings.update.before` - `user.notification-settings.update.after` - `addon.config.changed.before` - `addon.config.changed.after` - `auth.logout.before` / `auth.logout.after` - `post.update.before` / `post.update.after` - `post.delete.before` / `post.delete.after` - `post.status.changed.after`（上架 / 下架 / 精华 / 置顶等状态变更） - `post.like.before` / `post.like.after` - `post.favorite.toggle.before` / `post.favorite.toggle.after` - `comment.update.before` / `comment.update.after` - `comment.delete.before` / `comment.delete.after` - `comment.like.before` / `comment.like.after` - `user.follow.toggle.before` / `user.follow.toggle.after`（关注 / 取消关注） - `notification.create.before` / `notification.create.after` - `points.change.after`（积分变更 payload 含 delta / reason / balanceAfter） - `upload.file.before` / `upload.file.after`（payload 含 fileId / url / mime / size） - `addon.installed.after` / `addon.uninstalled.after` - `addon.enabled.after` / `addon.disabled.after` - `addon.api.request.before` / `addon.api.request.after` - `search.query.after`（payload 含 query / scope / resultCount） action hook 上下文当前包含： - `hook` - `payload` - 完整插件执行上下文能力包括 `readConfig`、`writeConfig`、`readSecret`、`writeSecret`、`data.*` 当前宿主行为： - action hook 按 `order` 升序执行 - 插件 action hook 执行失败时，不会回滚主业务动作 - 宿主会记录 lifecycle log，并继续执行后续插件 - `before` action hook 在宿主显式传入 `throwOnError: true` 的流程里可阻断主动作 - 当前登录、注册、第三方身份绑定/解绑、密码修改/重置、发帖、评论、私信发送、签到/补签、邀请码购买、兑换码兑换、资料更新、通知设置写入、插件配置写入等流程已接入 `before` action hook ### 8.11 通用 Waterfall Hook 除了副作用型 action hook，宿主现在也开放了数据改写型 hook： - `api.registerWaterfallHook()`：同步串行改写 - `api.registerAsyncWaterfallHook()`：异步串行改写当前已落地的宿主 hook 包括：同步 waterfall（`registerWaterfallHook`）： - `post.slug.value`：串行改写帖子最终 slug - `post.title.value`：串行改写帖子标题（落库前；可做敏感词替换、自动加前缀） - `post.content.value`：串行改写帖子正文（创建 / 编辑 / 追加写入前；公开正文会进入后续敏感词、摘要与 @ 解析主链） - `comment.content.value`：串行改写评论内容（写入前；可做签名补全、文本规范化） - `message.body.value`：串行改写私信内容（发送前；可做模板展开、文本规范化） - `report.reasonDetail.value`：串行改写举报补充说明（写入前；可做模板展开、文本规范化） - `user.profile.nickname.value`：串行改写用户昵称（资料写入前；后续仍会做敏感词与重名校验） - `user.profile.bio.value`：串行改写用户简介（资料写入前；可返回空串清空） - `user.profile.introduction.value`：串行改写用户个人介绍（资料写入前；可返回空串清空） - `user.displayName.value`：串行改写用户展示名（列表 / 详情渲染前） - `user.avatar.url.value`：串行改写用户头像 URL（加 CDN 前缀 / 默认占位） - `search.query.normalize`：串行规范化搜索关键词（大小写、同义词、繁简） - `seo.meta.title`：串行改写 SEO `` - `seo.meta.description`：串行改写 SEO meta description - `breadcrumb.items`：串行改写面包屑条目数组异步 waterfall（`registerAsyncWaterfallHook`）： - `navigation.primary.items`：主导航项数组 - `home.sidebar.hot-topics.items`：首页热点帖子列表 - `settings.post-management.tabs`：设置页“帖子管理”插件 tab 列表 - `feed.posts.items`：原始帖子流（首页 / 分类 / 列表页，`payload.displayMode` 表示当前列表模式） - `post-list.display.items`：映射后的帖子列表展示项；微博模式会包含 `previewMedia`、`contentPreviewMarkdown`、`contentPreviewHtml`、点赞 / 收藏 / 打赏等统计字段 - `search.results.rerank`：搜索结果重排（`payload` 含 `{ query, scope }`） - `notification.dispatch.targets`：通知分发目标（`payload` 含当前通知 `draft`） - `sitemap.entries`：sitemap.xml 条目列表 - `post.related.items`：详情页相关推荐 - `post.content.render`：帖子正文渲染后 HTML（代码高亮 / LaTeX / Mermaid）示例： ```js api.registerAsyncWaterfallHook({ key: "prepend-navigation", hook: "navigation.primary.items", async transform(context) { return [ { label: "活动", href: "/events", activePrefix: "/events" }, ...context.value, ] }, }) ``` 补充约定： - `feed.posts.items` 发生在原始记录阶段，适合插入广告位、置顶、重排或过滤；`post-list.display.items` 发生在宿主完成展示映射之后，适合微调卡片字段。插件应返回新的数组或新的 item 对象，避免直接原地修改 `context.value`。 - 微博模式的正文预览会在服务端去重首个媒体并预渲染 Markdown HTML，宿主会做轻量内存 LRU 缓存；插件如果改写 `contentPreviewMarkdown`，应同步更新或清空 `contentPreviewHtml`，否则客户端会优先使用旧 HTML。 - `post.content.value` 当前在帖子创建、普通编辑和超时后的追加内容链路里执行；它只改写公开正文 / 追加正文，不会自动改写 `loginUnlockContent`、`replyUnlockContent`、`purchaseUnlockContent` 这些附加文本。 - `message.body.value` 在宿主敏感词处理以及 `message.send.before` action hook 之前执行；`payload` 当前包含 `recipientId?`、`conversationId?` 和 `conversationKind`（`DIRECT` / `SITE_CHAT`）。 - `message.send.before` / `message.send.after` 的 payload 现在也会携带 `conversationKind`，其中 `after` 里的 `contentAdjusted` 会同时反映插件文本改写和宿主敏感词替换。 - `report.reasonDetail.value` 在举报补充说明为空时也会执行；插件可按 `reasonType`、`targetType` 自动补全模板文本。 - `report.create.after` 会拿到结构化 `report` 快照；其 `contentAdjusted` 同时反映插件对补充说明的改写和宿主敏感词替换。 - `user.profile.bio.value` / `user.profile.introduction.value` 允许返回空串，宿主会按显式清空处理；`user.profile.nickname.value` 仍带非空保护，空串会回退到原始昵称。 - `user.update.after` 会拿到结构化 `profile` 快照；其 `contentAdjusted` 同时反映昵称 / 简介 / 个人介绍的插件改写和宿主敏感词替换。 - `task.complete.after` 只会在任务首次完成并成功结算奖励后触发；payload 当前包含 `triggerType`、`eventKey`、`pointName`、`rewardPoints` 以及结构化 `task` / `progress` 快照。 - `check-in.submit.before` 在普通签到或补签写入前触发，并以 `throwOnError: true` 执行；payload 包含 `userId`、`username`、`action`、`date`、`reward`、`pointName`，补签时额外包含 `makeUpCost`。 - `check-in.submit.after` 在签到或补签成功后触发；payload 包含 `finalReward`、`points`、`currentStreak`、`maxStreak`、`alreadyCheckedIn`，补签时额外包含 `makeUpCost`。 `settings.post-management.tabs` 的返回值约定为 tab 描述数组，单项通常至少包含： - `key`：tab 唯一标识 - `label`：tab 文案 - `order`：排序，数值越小越靠前 - `panel`：一个与 `AddonRenderResult` 同构的对象；当前推荐使用 `clientModule + clientProps` 示例： ```js api.registerAsyncWaterfallHook({ key: "purchased-attachments-tab", hook: "settings.post-management.tabs", async transform(context) { return [ ...context.value, { key: "purchased-attachments", label: "购买的附件", order: 200, addonId: context.manifest.id, panel: { clientModule: context.asset("post-management-purchased-attachments.js"), clientProps: { endpoint: context.publicApi("purchased-attachments-posts"), }, }, }, ] }, }) ``` 运行规则： - 按 `order` 升序串行执行 - `context` 至少包含 `hook`、`value`，宿主在有额外语义时还会传 `payload` - 某个 hook 返回 `undefined` 时，保留上一个值继续向后传递 - 某个 hook 报错时，宿主会记录 lifecycle log，并默认继续后续 hook - `throwOnError` 只在宿主显式要求时才中断主流程完整点位请看 [`docs/插件 Hook 清单.md`](/D:/dev/bbs/site/docs/插件%20Hook%20清单.md)。 #### 8.11.1 Waterfall 实战示例下面 4 个例子覆盖最常见的"批量数据改写"场景，每个例子都给出了**注册代码 + 注意事项 + 常见反模式**。 **例 1：给所有用户头像套一层 CDN / 占位兜底** ```js // server.js api.registerWaterfallHook({ key: "avatar-cdn-wrap", hook: "user.avatar.url.value", order: 50, transform(context) { const { value, payload } = context // payload: { userId, size? } if (!value) { return `https://cdn.example.com/avatar/default-${(payload.userId ?? 0) % 8}.png` } if (value.startsWith("/")) { return `https://cdn.example.com${value}` } return value }, }) ``` 注意： - 该 hook 在宿主的 `ensureUserDisplay()` 管道里执行，同一次 SSR 渲染会命中一批用户，**保持 transform 轻量**（纯字符串拼接即可，不要在里面发请求） - 如果需要异步查询 CDN 签名，请改用 `registerAsyncWaterfallHook` - 返回 `undefined` 会让宿主保留上一个值继续传给下一个 hook **例 2：串行改写用户展示名（加 VIP 前缀 / 敏感词遮蔽）** ```js api.registerWaterfallHook({ key: "vip-badge-prefix", hook: "user.displayName.value", order: 100, transform(context) { const { value, payload } = context // payload: { userId, role?, badges? } if (payload.badges?.includes("vip")) { return `⭐ ${value}` } return value }, }) ``` 注意： - `displayName` 会出现在帖子列表、详情、评论、@ 提示等几乎所有 UI 上，改写要幂等（多次 transform 不会叠加前缀） - 需要辨识"已经加过前缀"时，优先用 `payload.badges` 判断，不要对 `value` 做 `startsWith("⭐")` 这种脆弱匹配 **例 3：SEO title / description 串改** ```js api.registerWaterfallHook({ key: "seo-site-suffix", hook: "seo.meta.title", order: 900, // 放在最后追加站点名 transform(context) { const { value } = context if (!value) return "我的论坛" if (value.endsWith(" - 我的论坛")) return value return `${value} - 我的论坛` }, }) api.registerWaterfallHook({ key: "seo-desc-fallback", hook: "seo.meta.description", transform(context) { return context.value || "一个由论坛驱动的社区站点。" }, }) ``` 注意： - `seo.meta.*` 是**同步** waterfall，不能 `await` - 同一页面上多个插件都注册时按 `order` 串行，**越晚执行的越靠外包装** - 默认站点后缀类逻辑建议放到 `order: 900+`，避免挤占前序 transform 语义空间 **例 4：扩展 sitemap.xml（异步）** ```js api.registerAsyncWaterfallHook({ key: "sitemap-extra-pages", hook: "sitemap.entries", order: 200, async transform(context) { const { value } = context const staticEntries = [ { loc: "/about", lastmod: "2026-01-01", changefreq: "monthly", priority: 0.5 }, { loc: "/help", lastmod: "2026-01-01", changefreq: "monthly", priority: 0.4 }, ] // 也可以 await context.data.list(...) 动态生成 return [...value, ...staticEntries] }, }) ``` 注意： - `sitemap.entries` 是**异步** waterfall，可以 `await` 数据查询 - 宿主只要求返回的每项至少包含 `loc`；`lastmod` / `changefreq` / `priority` 缺省时宿主会保留原样 - `loc` 可以是绝对 URL 也可以是 `/xxx` 形式；相对路径宿主会拼接站点域名 **通用反模式（所有 waterfall 都要避免）** - ❌ 在 transform 里 `throw`：会被宿主吞并写 lifecycle log，但后续 hook 拿到的仍是改写前的 value，业务上往往不是你想要的 - ❌ 在 transform 里直接 mutate `context.value`（数组 / 对象）：虽然当前能跑，但破坏了 waterfall 的"串行值传递"语义，换个执行顺序就会出 bug。**始终返回新值** - ❌ 在同步 waterfall 里调用 Promise / `fetch`：返回值会被当作普通对象处理，不会被 await - ❌ 让 transform 依赖 `window` / `document`：waterfall 大多在服务端 SSR 管道里执行，碰 DOM 就会 500 ### 8.12 Provider Registry 宿主内部现在已经把 provider 消费层统一到一个 registry/capability 层，而不是每种 provider 都各自重新扫描插件目录。对插件作者来说，接口没有变化： - 仍然通过 `api.registerProvider()` 注册 provider - 仍然在 `provider.data.runtime` 里暴露 runtime 方法但宿主侧会统一完成这些事情： - 按 `kind` 收集 provider - 构造 provider context - 进入统一 addon execution scope - 执行权限检查 - 执行外网访问守卫这意味着： - 新增 provider kind 时，宿主只需要补 capability 消费逻辑 - 不再需要每个 consumer 自己手写一套 addon 扫描 / context 构造 / runtime 调用包装 ### 8.13 宿主内容与互动 API 除了 `config / secret / backgroundJobs / data`，运行时上下文现在还开放了宿主内容与互动接口，适合“后台巡检型插件”： - `context.database.queryRaw(sql, values?)`：直接查询插件自定义 SQL 表 - `context.database.executeRaw(sql, values?)`：直接执行插件自定义 SQL - `context.database.transaction(task)`：把多步 SQL 包进一个事务 - `context.database.prisma`：在声明 `database:orm` 时复用宿主 Prisma Client - `context.posts.create(input)`：以指定账号创建帖子 - `context.posts.query(options?)`：按节点、分区、作者、时间、回复数、浏览数、点赞数等条件查询帖子 - `context.posts.like(input)`：以指定账号确保帖子已点赞 - `context.comments.create(input)`：以指定账号创建评论 / 回帖 - `context.comments.query(options?)`：按帖子、作者、状态、时间、点赞数等条件查询评论 - `context.comments.like(input)`：以指定账号确保评论已点赞 - `context.messages.send(input)`：以指定账号发送站内私信 - `context.notifications.create(input)`：创建一条系统通知 - `context.notifications.createMany(inputs)`：批量创建系统通知 - `context.emails.send(input)`：给指定用户的已验证邮箱发送邮件 - `context.follows.followUser(input)`：以指定账号确保已关注某个用户 - `context.points.adjust(input)`：增减指定用户积分 - `context.badges.list(options?)`：读取当前站点可供插件使用的勋章列表 - `context.badges.getGrantedIds(input)`：读取指定用户已经持有的勋章 ID 列表 - `context.badges.grant(input)`：向指定用户发放一个站点勋章 - `context.posts.tip(input)`：以指定账号执行帖子打赏典型用法就是自动顶贴 / 自动回帖机器人；如果你的插件本身还维护自定义订单、奖池、库存、报名表，也可以把 `database.*` 和这些宿主互动 API 组合起来： 1. 用 `scheduler.ensure()` 自我续期后台任务 2. 在任务里通过 `posts.query()` 找候选帖子 3. 通过 `comments.query({ postId, authorUsernames })` 判断某贴已经被哪些马甲账号参与过 4. 选出“当前帖子还没用过的账号”和一条回复文案 5. 调用 `comments.create()` 发出回复 6. 如果还需要造热度，再调用 `posts.like()` 或 `comments.like()` 7. 如果还需要联动运营动作，再调用 `messages.send()`、`notifications.create()`、`emails.send()`、`follows.followUser()`、`points.adjust()` 或 `posts.tip()` #### 8.13.1 `posts.query()` 适合解决的问题 - 只扫描指定分区 / 节点 - 只扫描最近 N 天的帖子 - 跳过回复数过多的帖子 - 优先处理回复少 / 浏览少 / 长时间没人回复的帖子常用筛选字段包括： - `boardIds` / `boardSlugs` - `zoneIds` / `zoneSlugs` - `authorIds` / `authorUsernames` - `statuses` - `createdAfter` / `createdBefore` - `publishedAfter` / `publishedBefore` - `lastCommentedAfter` / `lastCommentedBefore` - `activityAfter` / `activityBefore` - `minCommentCount` / `maxCommentCount` - `minViewCount` / `maxViewCount` - `minLikeCount` / `maxLikeCount` - `sort` - `limit` / `offset` - `includeTotal` 返回结果会包含帖子基础信息、原始内容、节点 / 分区信息、作者信息和互动统计。 #### 8.13.2 `comments.query()` 适合解决的问题 - 某个帖子已经有哪些账号参与过 - 某个马甲账号是否已经在目标帖子下回复 - 最近一段时间哪些评论被点过赞常用筛选字段包括： - `postId` / `postIds` - `authorIds` / `authorUsernames` - `statuses` - `parentId` - `createdAfter` / `createdBefore` - `updatedAfter` / `updatedBefore` - `minLikeCount` / `maxLikeCount` - `sort` - `limit` / `offset` - `includeTotal` #### 8.13.3 `comments.create()` 与 `posts.like()` / `comments.like()` 的行为约定 - `comments.create()` 不是直接裸写数据库，而是复用宿主服务链 - 节点回复权限、禁言状态、回复间隔、积分门槛、审核规则仍然会生效 - `posts.like()` / `comments.like()` 采用 ensure-liked 语义，不会执行取消点赞 - 如果目标已经点赞，返回值里的 `liked` 仍然是 `true`，但 `changed` 会是 `false` 这套设计是为了让后台插件更容易实现幂等逻辑，避免任务重试时把原本点过的赞又取消掉。 #### 8.13.4 私信、系统通知、邮件与用户关注 - `messages.send()` 适合后台客服机器人、自动欢迎私信、任务完成通知 - `notifications.create()` / `createMany()` 适合给用户发系统通知，而不是伪造点赞 / 回复类通知 - `emails.send()` 适合需要明确触达用户邮箱的运营、活动或后台任务通知 - `follows.followUser()` 适合运营号、机器人号自动建立关注关系 - `points.adjust()` 适合插件自己的积分奖惩、活动结算、签到补偿 - `badges.list()` / `getGrantedIds()` / `grant()` 适合活动插件、成就插件、勋章联动奖励 - `posts.tip()` 适合运营号 / 机器人号给帖子造支持度，复用宿主原有打赏结算行为约定： - `messages.send()` 复用宿主私信主链，会继续执行黑名单校验、敏感词替换、消息实时事件和 `message.send.before/after` - `notifications.create()` / `createMany()` 当前创建的是 `SYSTEM` 通知，并会继续触发未读数刷新与站外 webhook 派发 - `emails.send()` 只允许按 `recipientId` / `recipientUsername` 投递到用户已验证邮箱；如果用户不存在、邮箱未验证或 SMTP 未配置，会直接抛错 - `follows.followUser()` 采用 ensure-followed 语义；如果目标已经关注，会返回 `changed: false` - `points.adjust()` 默认按你传入的 `delta` 直接结算；如果额外提供合法的 `scopeKey`，则会先走 point-effect 规则再入账 - `badges.list()` 默认只返回“启用且非隐藏”的勋章；传入 `includeHidden` / `includeDisabled` 后可放宽筛选 - `badges.getGrantedIds()` 适合在活动开奖前排除“用户已持有勋章”的奖品，避免重复发放 - `badges.grant()` 采用 ensure-granted 语义；如果目标用户已经拥有该勋章，返回值会标记 `alreadyGranted: true` - `posts.tip()` 会继续执行余额校验、次数限制、积分日志、分账和系统通知 ## 9. 渲染结果格式 slot 和 page 的 `render()` 返回的是 `AddonRenderResult` 或重定向对象。 ### 9.1 可用字段 ```ts { html?: string text?: string clientModule?: string clientProps?: Record<string, unknown> containerTag?: "div" | "section" | "aside" containerClassName?: string stylesheets?: Array<string | { href: string; media?: string }> scripts?: Array<string | { src: string; strategy?: "beforeInteractive" | "afterInteractive" | "lazyOnload"; type?: "module" | "text/javascript" }> inlineScripts?: string[] } ``` ### 9.2 使用建议 - 纯静态内容优先用 `html` 或 `text` - 需要交互时再使用 `clientModule` - 样式、脚本、图片等都应该通过 `context.asset("...")` 指向 `assets/` 目录 - 可独立安装的插件如有页面级样式，必须返回 `stylesheets: [context.asset("xxx.css")]`；宿主不会在插件安装后重新运行 `next build` 或 Tailwind 扫描 ### 9.3 页面重定向页面也可以返回： ```js return { redirectTo: "/login" } ``` 宿主会把它当成重定向页面结果处理。 ## 10. 浏览器侧 `clientModule` 如果你要渲染交互式前端，可以在服务端返回： ```js return { stylesheets: [context.asset("hello-client.css")], clientModule: context.asset("hello-client.js"), clientProps: { title: "Hello" } } ``` ### 10.1 `clientModule` 的放置位置重要： - `clientModule` 必须是浏览器能访问到的 URL - 最常见的做法是把编译后的浏览器脚本放进 `assets/` - 然后通过 `context.asset("xxx.js")` 生成 `/_addons/<addonId>/xxx.js` ### 10.2 浏览器模块支持的导出形式宿主支持三种形式： 1. 导出 `createComponent(sdk)` 2. 导出 `Component` 3. 导出 `mount(container, props, sdk)`，可选配对 `unmount` 最简单的 `mount` 版本示例： ```js export function mount(container, props) { container.innerHTML = `<button type="button">Hello ${props.title ?? "Addon"}</button>` const button = container.querySelector("button") const onClick = () => { button.textContent = "clicked" } button?.addEventListener("click", onClick) return () => { button?.removeEventListener("click", onClick) container.innerHTML = "" } } ``` ### 10.3 `sdk` 能力浏览器模块会拿到一个 `sdk`，目前包含： - `React` - `createRoot` - `toast` - `cn` - 一批宿主 UI 组件（基于 `shadcn/ui`） - 一批宿主自定义展示组件 - 一批宿主工具函数 - 一批常用 `lucide-react` 图标 - 一个公开到 `window._rhex` 的宿主前端全局对象如果你的浏览器模块要长期维护，建议把它当成“宿主注入能力”，不要假设宿主之外的内部路径长期稳定。当前已注入的 `sdk.ui` 常用稳定组件包括： - 反馈与弹层：`AlertDialog*`、`Dialog*`、`DropdownMenu*`、`HoverCard*`、`Popover*`、`Sheet*`、`Tooltip*` - 导航与布局：`Breadcrumb*`、`Collapsible*`、`NavigationMenu*`、`Pagination*`、`ScrollArea`、`Separator`、`Tabs*` - 表单与选择：`Button`、`Checkbox`、`IconPicker`、`Input`、`InputGroup*`、`Textarea`、`Select*`、`Combobox*`、`Slider`、`Switch`、`Toggle`、`ToggleGroup*` - 数据与展示：`Avatar*`、`Badge`、`Card*`、`Command*`、`Skeleton`、`Spinner`、`Table*` - 宿主扩展 UI：`Modal`、`FormModal`、`Sidebar*`、`useSidebar` 当前已注入的 `sdk.custom` 宿主自定义组件包括： - 内容流：`ForumPostStreamView` - 节点选择：`BoardSelectField` - 等级与图标：`LevelIcon`、`LevelBadge` - 用户身份：`UserAvatar`、`UserStatusBadge`、`UserVerificationBadge`、`UserDisplayedBadges` - VIP 展示：`AvatarVipBadge`、`VipLevelIcon`、`VipNameTooltip`、`VipDisplayName` - 当前已注入的 `sdk.utils` 宿主工具包括：`escapeHtml`、`isRecord`、`normalizeOptionalString`、`loadScriptOnce` 当前已注入的 `sdk.icons` 常用图标包括： - 导航与方向：`ArrowRight`、`ArrowUpRight`、`ChevronDown`、`ChevronLeft`、`ChevronRight`、`ChevronUp` - 状态与提示：`AlertCircle`、`CheckCircle2`、`CircleHelp`、`Info`、`ShieldCheck`、`Sparkles` - 通用动作：`Check`、`Download`、`ExternalLink`、`Eye`、`EyeOff`、`Filter`、`Loader2`、`MoreHorizontal`、`Pencil`、`Plus`、`Save`、`Search`、`Trash2`、`Upload`、`X` - 内容与社交：`FileText`、`Heart`、`ImageIcon`、`Link2`、`MessageCircle`、`MessageSquareMore`、`Pin`、`Star` - 用户与站点：`Clock3`、`Lock`、`Palette`、`Settings2`、`User`、`UserRound`、`Users` - 音频播放：`ListMusic`、`Music4`、`Pause`、`Play`、`SkipBack`、`SkipForward`、`Volume2`、`VolumeX` 注意： - 这里是宿主**显式公开**给插件的稳定集合 - 它不等于 `src/components/ui/` 目录下的所有文件都会自动成为插件 API - `sdk.custom` 里的组件属于宿主站点语义组件，不是通用 `shadcn/ui` - `sdk.utils` 适合放插件资产脚本里经常重复的小工具 - 后续如果宿主继续扩充公开集合，应以 `src/addons-host/sdk/client.tsx` 为准 ### 10.3.1 `window._rhex` 全局对象除了 `clientModule` 里收到的 `sdk` 参数，宿主还会在浏览器里暴露一个全局对象： ```js window._rhex ``` 它的作用： - 让插件的普通浏览器脚本也能拿到宿主公共 SDK，而不必每个文件自己重复实现工具函数 - 让不走 React `createComponent(sdk)` 的脚本，也能读取宿主公开的前端上下文当前 `window._rhex` 里主要包括： - `sdkVersion` - `getSdk()` - `ui` - `custom` - `icons` - `utils` - `toast` - `cn` - `React` - `createRoot` - `session` - `site` 其中： - `window._rhex.session.isAuthenticated`：当前用户是否已登录 - `window._rhex.session.user`：当前登录用户的公开摘要；未登录时为 `null` - `window._rhex.site`：当前站点的公开设置快照；字段集合与宿主 `getSiteSettings()` 返回值保持一致当前 `window._rhex.session.user` 公开字段包括： - `id` - `username` - `nickname` - `avatarPath` - `role` - `status` - `level` - `points` - `vipLevel` - `vipExpiresAt` 当前 `window._rhex.site` 不再只暴露少量摘要字段，而是直接暴露宿主的公开站点设置快照。这意味着插件前端脚本可以直接读取大部分“前台本来就能看到、且宿主认为可公开”的站点设置，例如： - 站点品牌与展示：`siteName`、`siteSlogan`、`siteDescription`、`siteLogoPath`、`siteIconPath` - 交互与显示模式：`pointName`、`postLinkDisplayMode`、`leftSidebarDisplayMode`、`homeFeedPostListDisplayMode` - 页面与分页参数：`homeFeedPostPageSize`、`zonePostPageSize`、`boardPostPageSize`、`commentPageSize` - 公开功能开关：`friendLinksEnabled`、`checkInEnabled`、`inviteCodePurchaseEnabled`、`tippingEnabled` - 上传与附件能力：`markdownImageUploadEnabled`、`attachmentUploadEnabled`、`attachmentDownloadEnabled`、`attachmentAllowedExtensions` - 可公开导航与文案：`footerLinks`、`headerAppLinks`、`redeemCodeHelpEnabled`、`redeemCodeHelpTitle`、`redeemCodeHelpUrl` 完整字段范围请以宿主源码中的 `SiteSettingsData` 为准： - `src/lib/site-settings.types.ts` - `src/lib/site-settings.ts` 里的 `getSiteSettings()` 使用示例： ```js const rhex = window._rhex const isLoggedIn = Boolean(rhex?.session?.isAuthenticated) const username = rhex?.session?.user?.username ?? "" const pointName = rhex?.site?.pointName ?? "积分" const html = rhex?.utils?.escapeHtml(username) ?? username ``` 约束： - `window._rhex` 只应读取宿主明确公开的字段，不要假设还有未文档化的内部结构 - 这里公开的是“前端可安全暴露摘要”，不是完整用户对象 - `window._rhex.site` 虽然字段明显变多，但仍然只包含公开站点设置，不包含后台敏感配置 - 不会通过 `window._rhex` 暴露任何 secret、session token、后台敏感配置 ### 10.4 UI 约束与 `shadcn/ui` 可以。当前宿主前端就是基于 `shadcn/ui`，插件的浏览器侧模块也允许使用宿主注入的 `shadcn/ui` 组件。推荐做法： - 不走组件模式时，静态 HTML 也应配套插件自带命名空间 CSS；不要把 ZIP 后装插件的页面级布局建立在宿主 Tailwind utility 是否已生成之上 - 在 `clientModule` 里优先通过 `sdk.ui` 使用宿主提供的通用 UI 组件 - 需要宿主站点语义时，通过 `sdk.custom` 使用头像、等级、VIP、徽章、节点选择器等自定义组件 - 通过 `sdk.toast`、`sdk.cn`、`sdk.icons` 复用宿主现成能力 - 前台和后台页面都优先复用宿主已提供的组件组合，保证视觉和交互风格一致 - 如果插件发现宿主其实已经有某个组件，但 SDK 还没公开，优先补 SDK 暴露，不要在插件里复制一份 - 插件自带 CSS 应尽量只负责插件独有布局、密度、响应式和复杂交互状态；颜色、边框、背景、文字等应通过宿主 CSS 变量取值，保持主题一致 - 如果宿主页面已经给插件内容包了一层 Card / Section 壳，插件第一层不要再套一层同级 Card，避免双层边框和重复内边距 - 插件交互页建议按 `model/controller/view` 分层组织代码，避免把数据转换、网络请求和渲染混在一起示例： ```js export function createComponent(sdk) { const { React, ui, icons, toast } = sdk const { Button, Card, CardContent, CardHeader, CardTitle } = ui const { Play } = icons return function DemoCard() { return React.createElement( Card, null, React.createElement( CardHeader, null, React.createElement(CardTitle, null, "Hello Widget") ), React.createElement( CardContent, null, React.createElement( Button, { onClick: () => toast.success("clicked") }, React.createElement(Play, { "data-icon": "inline-start" }), "Run" ) ) ) } } ``` 不要这样做： - 不要在插件源码里直接 import 宿主内部别名，例如 `@/components/ui/button`、`@/lib/utils` - 不要在插件源码里直接 import 宿主自定义组件路径，例如 `@/components/user/user-avatar`、`@/components/level-icon` - 不要把宿主仓库里的 `shadcn/ui` 源码路径当成插件公共 API - 不要假设宿主未来一定会继续暴露完全相同的组件集合原因： - 插件是独立产物，最终通过 `addons/<addonId>/dist` 和 `assets/` 被加载 - zip 安装后的插件运行环境里，并不存在宿主源码别名解析 - 当前真正稳定的浏览器侧 UI 接口，是宿主传给你的 `sdk.ui` 和 `sdk.custom` 额外约束： - 如果插件只需要现有那批组件，优先使用 `sdk.ui` - 如果插件需要头像、等级、VIP、徽章等站点语义组件，优先使用 `sdk.custom` - 如果插件需要宿主当前未暴露的 `shadcn/ui` 组件，不要直接引用宿主源码；应把所需实现打包进你自己的前端产物 - 如果插件需要宿主当前未暴露的站点自定义组件，也不要直接引用宿主源码；应先扩充宿主公开 SDK，或把自己的实现打包进插件产物 - 动态安装插件不能要求宿主重新构建 CSS。新增或修改插件 UI 时，同步更新插件自己的 `assets/*.css` 和 `stylesheets` 注入声明 - 内置插件如果复用宿主 Tailwind utility class，必须确认这些源码会在部署镜像 `next build` 前进入仓库 / 镜像；否则按动态插件处理，自带 CSS ## 11. 插件上下文能力宿主在执行 slot / surface / page / api 时会传入运行时上下文对象；在安装、升级、卸载 lifecycle hook 里会传入一套扩展上下文。所有上下文都包含： - `manifest` - `state` - `enabled` - `rootDir` - `assetRootDir` - `assetBaseUrl` - `publicBaseUrl` - `adminBaseUrl` - `publicApiBaseUrl` - `adminApiBaseUrl` - `permissions` - `hasPermission(permission)` - `assertPermission(permission, message?)` - `getCurrentUser()` - `getSiteSettings()` - `getBoardSelectOptions()` - `asset(path)` - `publicPage(path)` - `adminPage(path)` - `publicApi(path)` - `adminApi(path)` - `readAssetText(path)` - `readAssetJson(path)` - `readConfig(configKey, fallback)` - `writeConfig(configKey, value)` - `readSecret(secretKey, fallback)` - `writeSecret(secretKey, value)` - `backgroundJobs.enqueue(jobKey, payload, options?)` - `backgroundJobs.remove(jobId)` - `scheduler.inspect({ enabled, configured, state })` - `scheduler.ensure(currentState, { enabled, configured, jobKey, delayMs, ... })` - `scheduler.cancel(currentState)` - `database.queryRaw(sql, values?)` - `database.executeRaw(sql, values?)` - `database.transaction(task)` - `database.prisma` - `posts.create(input)` - `posts.query(options?)` - `posts.like(input)` - `comments.create(input)` - `comments.query(options?)` - `comments.like(input)` - `messages.send(input)` - `notifications.create(input)` - `notifications.createMany(inputs)` - `emails.send(input)` - `follows.followUser(input)` - `points.adjust(input)` - `badges.list(options?)` - `badges.getGrantedIds(input)` - `badges.grant(input)` - `posts.tip(input)` - `files.save(input)` - `data.*` 补充说明： - `getCurrentUser()` 会基于当前请求的 cookie / headers 解析宿主登录态；没有请求上下文时返回 `null` - `getSiteSettings()` 返回宿主的公开站点设置快照，字段集合与前端 `window._rhex.site` 保持一致 - `getBoardSelectOptions()` 返回按分区分组的节点选项，可直接喂给浏览器侧 `sdk.custom.BoardSelectField` - `backgroundJobs.enqueue()` 会返回包含 `jobId`、`attempt`、`maxAttempts`、`availableAt` 的任务句柄；`remove()` 会返回实际删除位置 - `scheduler.*` 适合“每天/每小时/固定延迟后执行一次”的插件级定时任务；宿主会统一复用 `backgroundJobs` 做调度与取消 - `database.queryRaw()` / `executeRaw()` / `transaction()` 现在在插件运行态和 lifecycle 阶段都可用；自定义业务表推荐优先通过它们维护 - `database.queryRaw()` / `executeRaw()` 使用 PostgreSQL 风格的 `$1`、`$2` 参数占位符；所有动态值都应通过第二个 `values` 数组传入，不要把用户输入直接拼进 SQL 字符串 - `database.prisma` 仍然只适合访问宿主已有 Prisma 模型；插件自定义表不应依赖 Prisma schema 自动发现 - `posts.create()` 复用宿主发帖主链，仍会触发状态校验、敏感词、审核、通知、等级与 action hook - `comments.create()` 复用宿主评论主链，仍会触发状态校验、回帖权限、积分门槛、审核、通知、等级、AI 提及回复与 action hook - `posts.like()` / `comments.like()` 是幂等的 ensure-liked 语义：如果目标已点赞，会返回 `changed: false`，不会像前台 UI 那样执行 toggle 取消点赞 - `messages.send()` 复用宿主私信主链，仍会触发状态校验、黑名单校验、敏感词、消息事件总线与 `message.send.*` action hook - `notifications.create()` / `createMany()` 当前创建的是宿主 `SYSTEM` 类型通知，并会复用未读数刷新和站外 webhook 分发 - `emails.send()` 复用宿主 SMTP 配置，按用户 ID / 用户名投递到该用户已验证邮箱，不会向插件暴露邮箱地址 - `follows.followUser()` 是幂等的 ensure-followed 语义：如果目标已关注，会返回 `changed: false`，不会触发取消关注 - `points.adjust()` 复用宿主积分结算能力，可按需应用 point-effect 规则，并继续写入积分日志 / 审计 - `badges.list()` / `getGrantedIds()` / `grant()` 复用宿主勋章体系，适合活动奖励、成就联动和后台批处理插件 - `badges.grant()` 当前是 ensure-granted 语义：重复发放不会新增第二条用户勋章记录，返回值会带 `alreadyGranted` - `posts.tip()` 复用宿主帖子打赏结算能力，会继续执行余额校验、税率分账、积分日志和系统通知 - `files.save()` 复用宿主上传存储配置保存插件生成文件，适合 AI 生图、海报、导出文件等场景；详见 §8.9.1 - `posts.query()` / `comments.query()` 是插件运行时的宿主数据读取接口，适合后台巡检、定时机器人、批处理插件；它们读取的是宿主原始业务数据，不会自动继承当前访客页面的可见性视角 - `data.*` 包括 `ensureCollection`、`get`、`put`、`delete`、`query`、`cleanup`、`getSchemaVersion` lifecycle 上下文在上面这套基础能力之外，还额外包含： - `action`：`install` / `upgrade` / `uninstall` - `readFileText(path)` / `readFileJson(path)`：读取插件根目录内任意文件，可直接读取 `migrations/*.sql` - `database.queryRaw(sql, values?)` - `database.executeRaw(sql, values?)` - `database.transaction(task)` - `database.prisma` 补充说明： - `database.*` 只建议在 lifecycle hook 里处理安装表、升级表和清理表 - `database.prisma` 复用的是宿主 Prisma Client，更适合访问宿主已有模型；插件自建表不会自动进入宿主 Prisma schema 页面上下文额外包含： - `scope` - `routePath` - `routeSegments` API 上下文额外包含： - `scope` - `routePath` - `routeSegments` - `method` - `request` - `pathname` - `searchParams` slot 上下文额外包含： - `slot` surface 上下文额外包含： - `surface` - `props` ## 12. 配置与状态存储 ### 12.1 状态插件状态当前主要包括： - 是否启用 - 安装时间 - 禁用时间 - 最近错误时间 - 最近错误信息另外，注册表模型里仍保留 `uninstalledAt` 字段用于兼容旧数据；运行时会把这类记录视为不可用，但当前后台和 CLI 已不再提供“逻辑卸载 / 恢复”动作。状态读取规则当前是： 1. 读取数据库 `addon_registry` 2. 如果表不存在，则返回空状态，运行时回退到 manifest 默认值和本次扫描结果说明： - 当前没有 `addons/.runtime/addons-state.json` 这套状态文件读写链路 - 管理页面向管理员展示的稳定状态只有 `enabled` / `disabled` ### 12.2 配置普通插件配置由 `readConfig` / `writeConfig` 访问。当前实现只走数据库 `addon_config`： - `readConfig()`：查 `addon_config`，没查到则返回调用方传入的 `fallback` - `writeConfig()`：upsert `addon_config` 注意： - 当前没有 `addons/.runtime/addons-config.json` 文件兜底 - 如果 `addon_config` 表不存在，`readConfig()` 会退回 `fallback`，`writeConfig()` 不会形成持久化 ### 12.3 敏感配置敏感配置由 `readSecret` / `writeSecret` 访问。读取规则： 1. 先尝试读取站点敏感状态 `site_settings.sensitiveStateJson` 里的 addon secret 命名空间 2. 数据库不可用，或没有对应值时，再回退到 `addons/.runtime/addons-secrets.json` 写入规则： - 总是先写文件态 secret - 再尽力同步到站点敏感状态；数据库不可用时保留文件态作为兜底建议： - API 私钥、平台公钥、第三方密钥、Token 一律放 secret - 可公开展示或可导出的业务参数仍放普通 config ### 12.4 结构化插件数据除了 `config / secret`，宿主现在还提供结构化插件数据存储： - `context.data.ensureCollection()` - `context.data.get()` - `context.data.put()` - `context.data.delete()` - `context.data.query()` - `context.data.cleanup()` - `context.data.clear()` - `context.data.getSchemaVersion()` 这套数据层当前是文件态文档仓库，根目录在： - `addons/.runtime/data/<addonId>/` 每个 collection 是独立文件，宿主会维护： - collection 定义 - 文档记录 - 简单索引映射 - schema version 推荐写法： ```js await context.data.ensureCollection({ name: "orders", indexes: [ { name: "by-user", fields: ["userId"] }, { name: "by-status-user", fields: ["status", "userId"] }, ], }) await context.data.put("orders", { id: "order_001", value: { userId: 1, status: "paid", amount: 99, }, }) const result = await context.data.query("orders", { where: { userId: 1, }, sort: [ { field: "status", direction: "asc" }, ], limit: 20, includeTotal: true, }) ``` 当前特点： - 支持按 `where` 做等值过滤 - 支持 `sort` - 支持 `limit / offset / cursor` - 支持 TTL 清理 - 支持 collection 级索引声明 #### 12.4.1 数据迁移插件现在还可以注册数据迁移： ```js api.registerDataMigration({ version: 1, async migrate(context) { await context.data.ensureCollection({ name: "orders", }) }, }) ``` 当前迁移规则： - 迁移按 `version` 升序执行 - 宿主记录每个 addon 当前 `schemaVersion` - 只执行尚未跑过的迁移 - 迁移失败会让 addon load 失败，并记录 lifecycle log ### 12.5 权限执行与审计 `addon.json` 里的 `permissions` 现在不再只是展示字段，宿主已经开始做真实 enforcement。可以把它理解成两层： - 注册期权限：插件在 `setup(api)` 里调用 `registerSlot()`、`registerProvider()`、`registerActionHook()` 等注册函数时检查 - 执行期权限：插件在运行过程中调用 `context.readConfig()`、`context.writeSecret()`、`context.data.*()`，或 provider runtime 访问外网时检查当前会被宿主检查的能力包括： - `config:read` - `config:write` - `secret:read` - `secret:write` - `background-job:register` - `background-job:enqueue` - `background-job:delete` - `database:sql` - `database:orm` - `data:read` - `data:write` - `data:delete` - `data:migrate` - `file:write` - `slot:register` - `surface:register` - `page:public` - `page:admin` - `api:public` - `api:admin` - `provider:register` - `hook:register` - `post:create` - `post:query` - `post:like` - `comment:create` - `comment:query` - `comment:like` - `message:send` - `notification:create` - `email:send` - `follow:user` - `points:adjust` - `badge:query` - `badge:grant` - `post:tip` - `network:external` - `auth:integrate` - `captcha:integrate` - `payment:integrate` 敏感能力额外约束： - 登录 / 注册相关 slot 和 `auth` / `external-auth` provider 需要 `auth:integrate` - `captcha` provider 和验证码 slot 需要 `captcha:integrate` - `payment` provider 需要 `payment:integrate` - `context.backgroundJobs.enqueue()` 需要 `background-job:enqueue` - `context.backgroundJobs.remove()` 需要 `background-job:delete` - `context.database.queryRaw()` / `executeRaw()` 需要 `database:sql` - `context.database.prisma` 需要 `database:orm` - `context.posts.create()` 需要 `post:create` - `context.posts.query()` 需要 `post:query` - `context.posts.like()` 需要 `post:like` - `context.comments.create()` 需要 `comment:create` - `context.comments.query()` 需要 `comment:query` - `context.comments.like()` 需要 `comment:like` - `context.messages.send()` 需要 `message:send` - `context.notifications.create()` / `createMany()` 需要 `notification:create` - `context.emails.send()` 需要 `email:send` - `context.follows.followUser()` 需要 `follow:user` - `context.points.adjust()` 需要 `points:adjust` - `context.badges.list()` / `getGrantedIds()` 需要 `badge:query` - `context.badges.grant()` 需要 `badge:grant` - `context.posts.tip()` 需要 `post:tip` - `context.files.save()` 需要 `file:write` - 插件执行期访问外部 HTTP(S) 资源需要 `network:external` - 相对地址、同源地址以及 `localhost` / `127.0.0.1` / `::1` 默认不受 `network:external` 限制兼容与迁移说明： - `route:public` / `route:admin` 仍会被归一化为 `page:public` / `page:admin` - 历史上的 `slot:<slotName>` 仍会被归一化为 `slot:register` - 新插件应直接声明标准化权限名，不要继续依赖旧写法当前审计行为： - 权限拒绝会写 lifecycle log - 外网访问被拒绝会写 lifecycle log - 事件执行失败会写 lifecycle log ## 13. 安装、启停与卸载 ### 13.1 zip 安装要求安装器支持两种压缩包结构： 1. zip 根目录直接放 `addon.json` 2. zip 里包一层目录，目录下放 `addon.json` 安装时会做这些事情： 1. 解压到 `addons/.staging` 2. 查找唯一的 `addon.json` 3. 解析清单 4. 校验 `id` 5. 校验服务端入口存在，并从 staging 预加载 server entry 6. 首次安装时，先执行新插件的 `lifecycle.install` 7. 覆盖安装时，先在 staging 执行新插件的 `lifecycle.upgrade` 8. 上一步成功后，覆盖安装才会把旧版本移动到 `.trash` 9. 把新插件移动到 `addons/<addonId>` 10. 写入状态和注册表 11. 重新同步宿主注意： - 安装器当前会校验 zip 结构、`id` 和服务端入口是否存在 - 安装 / 升级 lifecycle hook 失败时，当前目录替换不会发生 - 但不会预先校验 `permissions` 是否覆盖了 `setup(api)` 里真实用到的能力 - 所以“安装成功”不等于“插件一定能成功加载”；权限缺失通常会在同步 / 加载阶段暴露为 `loadError` - 后台安装表单当前额外支持 `replaceExisting`（升级）和 `enableAfterInstall` 两个开关 ### 13.2 生命周期动作当前公开的管理动作： - `enable`：启用插件 - `disable`：禁用插件 - `remove`：物理卸载；会先尝试执行 `lifecycle.uninstall`，成功后再把目录移到 `.trash` - `sync`：重新扫描并同步注册表 - `clear-cache`：清理运行时缓存，并清掉已恢复正常插件的残留最近错误状态说明： - 当前后台和 CLI 都不再暴露 `uninstall` / `reinstall` - 旧注册表里的 `uninstalledAt` 只作为兼容字段保留，运行时会把它视为不可用状态 ### 13.3 后台管理入口后台可直接使用： - 页面：`/admin/addons` - 接口：`/api/admin/addons` - 安装接口：`/api/admin/addons/install` 当前后台管理页支持的操作包括： - 上传 zip 安装插件 - 覆盖已有插件目录 - 安装后立即启用 - 同步扫描插件目录 - 清除插件宿主缓存 - 对单个插件执行启用、禁用、物理卸载 ## 14. 静态资源规则静态资源通过 `/_addons/<addonId>/...` 暴露。已内置的内容类型包括： - `.css` - `.js` - `.mjs` - `.json` - `.mp3` - `.wav` - `.ogg` - `.jpg` - `.jpeg` - `.png` - `.gif` - `.webp` - `.svg` - `.ico` - `.woff` - `.woff2` - `.ttf` 缓存策略： - `.js` / `.mjs` / `.css` / `.json`：`no-cache, must-revalidate` - 其他资源：默认 `max-age=3600` 安全规则： - 所有资源路径都会做目录逃逸校验 - 不能通过 `../` 访问插件目录外的文件 ## 15. 当前开发约束与建议 ### 15.1 强约束 - 服务端入口必须是已编译完成、可直接被 Node `import()` 的文件 - 浏览器模块必须是已编译完成、可直接被浏览器 `import()` 的文件 - 不要依赖宿主会帮你编译插件源码 - 需要浏览器访问的文件必须放在 `assets/` - 可动态安装插件的 CSS 必须随插件发布；页面级 class 应使用插件命名空间，避免污染宿主或其他插件 - 插件样式必须优先使用宿主 `shadcn/ui` 语义 CSS 变量，例如 `hsl(var(--card))`、`hsl(var(--background))`、`hsl(var(--border))`、`hsl(var(--foreground))`、`hsl(var(--muted-foreground))` - 插件前端如果要用宿主 UI 或宿主自定义展示组件，稳定入口是 `sdk.ui` / `sdk.custom`，不是宿主内部源码 import - 插件不要在运行时引入 `https://cdn.tailwindcss.com`；如需 Tailwind，必须由插件自己的发布流程预编译为 `assets/*.css` - 宿主 Tailwind 扫描只对随宿主一起构建的内置插件可靠；后台 ZIP 安装、覆盖安装、热更新的插件都要按“自带 CSS”处理 ### 15.2 建议 - 保持插件目录名与 `id` 一致 - `path` 一律写相对路径，不要加前导 `/` - `key` 在单插件内保持唯一 - 所有管理面操作都优先通过后台或 CLI 走，不要手动改 `.runtime` - `permissions` 尽量在开发早期就按最小权限集写全，不要等到功能做完再补 - `provides`、`dependencies` 仍然建议写全；其中 `dependencies/conflicts` 现在会参与安装预检和运行时校验 ### 15.3 现在最容易踩的坑 - `render()` 返回了内容，但挂错 slot，页面上永远不显示 - 页面 `path` 以为支持动态参数，结果始终 404 - `clientModule` 指向了 `dist/` 文件，浏览器无法访问 - 服务端入口里用了宿主源码别名，但最终安装产物里没有正确打包 - 插件 zip 能安装，但 `permissions` 没写全，导致 `setup(api)` 直接报权限错误 - 插件已启用，但 `loadError` 不为空，导致所有注册项都不生效 - 覆盖安装后忘了检查 `.trash`，以为旧版本已经彻底删除 ### 15.4 跨模块契约与增量修改约定（ESM / 配置 / Slot / 自检）本节给出一组硬性约定，专门用于**在已有插件上做增量功能**的场景。本仓库的插件 server 入口全是 ESM（`.mjs`），一旦跨文件契约错位，宿主启动时会直接抛： ``` SyntaxError: The requested module './xxx.mjs' does not provide an export named 'yyy' ``` 这类错误的根因永远是「导入方和导出方对同一个名字没对齐」或「宿主仍在使用旧的模块缓存」。以下约定按出错概率排序，请按顺序遵守。 #### 15.4.1 ESM 跨模块契约（强约束） - **一次改动两边原子化**：新增 / 重命名 / 删除一个 `export` 时，必须在同一次编辑里把**所有 import 方**一起改到位；严禁只改一侧提交一次、再改另一侧提交一次的串行推进。 - **命名完全一致**：ES Module 的 named import 是**大小写敏感、无容错**的。`loadCardPositionConfig` 和 `loadCardPositionconfig` 是两个不同的东西，宿主不会帮你纠正。 - **相对路径写全**：`import ... from './config.mjs'`，必须有前导 `./` 和显式 `.mjs` 后缀。不要依赖扩展名省略，Node 的 ESM loader 默认不解析。 - **单一事实源**：同一个配置 key、同一个默认值、同一个校验器只能在**一个文件**里声明（本仓库里是 `config.mjs`）。其它文件一律 `import` 这些常量与函数，不要就地再写一份字面量。 - **默认导出只用于插件入口**：`dist/server.mjs` 用 `export default { setup }`；所有业务模块（model / controller / view）一律用 named export，禁止「默认导出一个大对象再解构」的反模式——这种写法一旦某个字段拼错，运行时才暴露。 - **禁止循环依赖**：约定单向依赖链 `server → controller → { config, views }`，`config` 与 `views` 之间不得互相 import，`controller` 不能被 `config` / `views` 反向 import。一旦出现循环，部分 named export 在求值期会是 `undefined`，症状和「没导出」一模一样但排查起来更隐蔽。 - **模块顶部列 export 清单**：每个 `.mjs` 第一屏注释里写出自己对外暴露的名字（如 `// exports: DEFAULT_SHORTCUTS, loadShortcutsConfig, loadCardPositionConfig`）。review 时一眼可核，也方便别的 AI / 开发者在不读全文的情况下正确 import。 - **改完用 grep 反查残留**：删除或改名后执行 ```powershell rg "<旧名字>" site/addons/<addonId> ``` 必须返回 0 条结果，才能视为重构完成。 #### 15.4.2 模块缓存与热加载陷阱宿主的插件 loader 对 `dist/server.mjs` 及其 import 链有进程内缓存。编辑完 `.mjs` 文件后，**光刷新浏览器不够**。按以下优先级处理： 1. 改动仅限 `assets/*.js`（浏览器侧）→ 硬刷新浏览器即可； 2. 改动涉及 `dist/*.mjs`（服务端侧）→ 重启 dev server，或在后台 `/admin/addons` 点一次「同步 / 清缓存」； 3. 改动涉及 `addon.json` 的 `entry` / `provides` / `permissions` → 必须「同步」，否则宿主看到的仍是旧清单； 4. 诊断「我明明加了 export 却还是报没有」时，在 `dist/server.mjs` 里临时 `console.log(Object.keys(await import('./config.mjs')))`，看到的才是宿主真正用到的那一份。 #### 15.4.3 配置项增量约定为后续新增配置时不破坏既有安装，约束如下： - 每个配置 key 固定在 `config.mjs` 中以**三件套**出现： - `CONFIG_KEY_XXX` 常量（避免字符串散落） - `DEFAULT_XXX` 默认值（Object 默认值务必 `Object.freeze`） - `loadXxxConfig(ctx)` 读取 + 校验 + 合法兜底函数，返回值**一定合法** - `ctx.readConfig(key, default)` 的第二参数不是「装饰」，是在 host 里根本没写过这个 key 时唯一的兜底来源；**新增 key 一定要传 default**，否则旧安装会拿到 `undefined`。 - 合法性校验内聚：如 `cardPosition` 只允许 `"top" | "bottom"`，白名单写在 loader 内部；controller / view 拿到的只能是「已经合法的值」，不要再次判断。 - **不要在 `setup(api)` 阶段预读配置做缓存**。配置每次 render 都要 `await` 一次，否则后台改值后必须重启插件才生效，违反文档「即时生效」的期望。 - 向后兼容：新增 key 后，旧安装（host 里没这个 key）拿到的默认值必须能让 UI 原样工作。 - `addon.json` 的 `permissions` 必须同步声明 `config:read`（只读取）或 `config:read` + `config:write`（后台也能写）。漏声明时 `setup(api)` 会直接以权限错误终止，所有注册项全部不生效。 #### 15.4.4 Slot 声明与多点位切换当一个功能可能落在多个 slot 点位（本插件的「卡片放顶部 / 底部」是典型案例）： - `addon.json` 的 `provides.slots` **必须列出所有候选点位**。例如同时支持 `home.right.top` 和 `home.right.bottom`，两个都要写；漏写的那个即使 `registerSlot` 成功，后台也看不到、审计也不过。 - 运行期策略：**两个点位都 `registerSlot`**，在各自 `render(ctx)` 里读最新配置，不匹配当前位置就 `return null`。不要试图「根据配置在 setup 时动态决定注册哪一个」——那样后台改配置必须重启才生效。 - `render()` 返回 `null` = 跳过渲染，**没有任何 DOM 产出**；返回 `{ html: "" }` = 渲染一个空壳节点，可能破坏父容器的 gap / 间距。按意图选其一，不要混用。 - Slot `key` 在单插件内唯一；多点位同功能建议用 `home-shortcut-card-${position}` 这类后缀区分，方便排查日志。 #### 15.4.5 SSR HTML 输出 - 所有进入 HTML 字符串的「配置值 / 用户输入 / 外部数据」必须先过 `escapeHtml`；只有你自己写死的静态片段（如 SVG 图标）可以直出。 - 不要在 SSR HTML 里引用 `window` / `document` / `localStorage`；这些只能放进 `assets/*.js` 里，通过 `clientModule` 由浏览器加载。 - View 层（`views/*.mjs`）保持纯函数：输入 → HTML 字符串，无副作用、不读配置、不发请求。读配置、组装数据在 controller 完成。 #### 15.4.6 增量改动自检闭环每次完成增量功能后，按顺序跑一遍，不要省略： 1. `node --check site/addons/<id>/dist/server.mjs`，以及每个被它 import 的 `.mjs`——先把语法 / 显式 parse error 捞掉。 2. `rg "<你新增或改名的符号>" site/addons/<id>`，确认 import 方和 export 方字符完全一致、没有残留旧名字。 3. 重启 dev server 或在 `/admin/addons` 执行「同步 / 清缓存」，消除模块缓存。 4. 打开后台 `/admin/addons/<id>`，确认 `loadError` 为空、`warnings` 为空。`loadError` 非空时，插件**所有注册项都不会生效**，不要以为只是「那一项坏了」。 5. 打开前台目标页，切换相关后台配置（如本插件的 `cardPosition`），**不重启**刷新页面确认立即生效；如果必须重启才生效，说明违反了 §15.4.3 最后两条。 6. 涉及 slot 的改动，顺便在 DOM 里搜一次你的 slot key，确认只在期望位置出现、没在别的点位重复。 --- ### 15.5 Client / Server 边界与 `server-only` 陷阱从实际踩坑记录整理出的硬性边界规则。**违反任何一条都会让 `next build` 直接失败**（不是运行时报错，是编译期静态分析阶段报错）。 **规则 1：出现在 client bundle 里的文件不允许 import 服务端资源** Next.js 的静态分析会沿着 import 图递归扫描。只要一个"工具文件"被某个 client component 间接引到，它内部的**所有 import** 都会被强制按浏览器可执行校验。禁止在这种文件里 import： - `"server-only"` - `fs` / `path` / `crypto`（node 内置） - 任何 DB / ORM 客户端（`@/lib/db`、`drizzle-orm/*`） - 宿主侧 `src/addons-host/**`（含 SDK 的 server 端、provider runtime） - `next/headers`、`next/server`（部分 API 在 RSC client 边界仍受限）即使该文件里的"服务端函数"**从来没被 client 调用过**也不行——打包器只认静态 import 图，不认运行时是否可达。 **规则 2：同源文件要按"谁调用"拆分** 正确的做法是把同一个逻辑域按调用方拆成两个文件： ``` src/lib/avatar.ts ← 纯函数 / 仅类型工具, RSC + client 都能 import src/lib/avatar-server.ts ← 顶部 import "server-only"; DB / fs / 宿主 SDK 放这里 ``` 然后在 server.ts / route handler / RSC 里 import `avatar-server`，在 `"use client"` 组件里只 import `avatar`。 **规则 3：判断一个文件属于哪一侧** 最靠谱的判断不是看文件名，而是**追溯它被哪条 import 链导入**： - 被任意 `"use client"` 文件（或被它的 transitive import）引到 → **必须 client-safe** - 只被 RSC / route handler / server.ts 引到 → 可以引 server-only 可以 `rg '"use client"' src -l` 找到所有 client 根；然后检查目标文件是否出现在这些根的 import 图上（IDE 的 "Find Usages" 也可以）。 **规则 4：插件侧同样适用** 插件 `dist/server.mjs` 和 `assets/*.js` 是**完全隔离的两套 bundle**： - `dist/server.mjs` 在 Node 里跑，可以用 fs / DB / 宿主 SDK - `assets/*.js` 通过 `/_addons/<id>/assets/xxx.js` 被浏览器加载，绝不能打进任何 Node-only 代码常见错误模式： - ❌ 在插件的 `assets/xxx.js` 顶部 import 了 `./shared/db.js`，而后者引了 `fs` - ❌ 把 `addon.json` 里的 `clientModule` 指向 `dist/server.mjs`（运行时会 500） - ❌ 在 server.ts 的 `render()` 里返回了引用 `window` 的字符串，SSR 时直接报 ReferenceError **规则 5：发现污染后的排查命令** ```powershell # 1. 先看 next build 的第一条 error，它通常指向 bundle 根和触发文件 pnpm next build 2>&1 | Select-String -Pattern 'error|Module not found' -Context 0,3 # 2. 拿到"触发文件"后，反查它的被引用者 rg -l "from ['\"].*avatar['\"]" src # 3. 任何一个被引用者是 "use client" 或被 "use client" 链引到，就说明污染成立 ``` 修复方式永远是**把 server-only 依赖挪到独立文件**，而不是在原文件里 `if (typeof window === ...)` 做运行时判断——静态分析阶段拦截比运行时分支早得多。 ## 16. 最小开发流程建议推荐按下面的顺序开发一个新插件： 1. 在 `addons/<addonId>/` 下创建目录 2. 写好 `addon.json`，并先把首批 `permissions` 声明出来 3. 先只做一个最小 `dist/server.mjs` 4. 只注册一个 public page，确认路由打通 5. 再注册 slot 或 API 6. 如果需要交互，再补 `assets/<client>.js` 7. 到 `/admin/addons` 看后台状态、warning、loadError 8. 最后再补文档和 provider 元数据，并回头收紧到最小权限集 ## 17. 建议的插件交付清单一个可交付插件，至少应包含： - `addon.json` - 可运行的 `dist/server.mjs` - 如有前端交互，包含 `assets/*.js` - 如有样式，包含 `assets/*.css` - 自己的 `README.md` - 版本号变更记录如果要发 zip 包，发布前至少自检： - 是否只有一个 `addon.json` - `id` 是否合法 - 目录名是否与 `id` 一致 - `entry.server` 是否存在 - `permissions` 是否覆盖 `setup(api)` 和运行期真实用到的能力 - `clientModule` 引用的资源是否真的在 `assets/` - `stylesheets` 引用的 CSS 是否真的在 `assets/` - 后装到已构建好的线上环境时，页面是否不依赖宿主 Tailwind 新生成 class - 前台页、后台页、API 路径是否都能打开 ## 18. 一句话总结这套插件系统当前是一个“文件目录 + 清单 + 服务端注册 + 宿主路由转发”的 addon 运行时。开发新插件时，最重要的不是把清单写得多复杂，而是保证这五件事成立： - `addons/<addonId>/addon.json` 存在 - `permissions` 与 `setup(api)` / `context` 实际使用的能力一致 - `dist/server.mjs` 能被直接加载 - `setup(api)` 里完成真实注册 - 需要浏览器访问的文件都放进 `assets/`</article></body></html>