插件 Hook 清单

当前宿主把扩展点分成 5 类：

• slot：插入 UI 块
• surface：覆盖宿主默认 UI 区块
• action hook：在生命周期点执行副作用逻辑
• waterfall：同步串行改写数据
• asyncWaterfall：异步串行改写数据

说明：

• provider 类能力不在这份 hook 清单里单独枚举；例如 payment、navigation、editor、upload、home-feed 都属于“由宿主按 kind 消费的 provider 扩展”
• 新增首页 tabs / 首页主内容切换时，应优先看主文档里的 home-feed provider，而不是把它误解成 slot 或 surface
• 内建 surface 现在有独立目录：src/addons-host/surface-catalog.ts。它会并入 ADDON_EXTENSION_POINT_CATALOG，可被后台、文档生成器或插件开发工具统一枚举。

通用规则

• 所有扩展点都按 order 升序执行
• 同 order 下按 addonId:key 稳定排序
• slot 返回 AddonRenderResult | null
• surface 返回 AddonRenderResult | null
• surface 支持 server / client / hybrid 三种执行模式；模式元数据以 ADDON_SURFACE_CATALOG 为准
• action hook 返回 void
• waterfall / asyncWaterfall 返回下一个值；返回 undefined 时保留上一个值
• hook 执行失败时，宿主默认记录 lifecycle log 并继续后续插件
• before action hook 在宿主显式传入 throwOnError: true 时可中断主流程
• surface 只会选择一个插件生效；命中失败时自动回退宿主默认 UI
• 注册未知 surface 不会被阻断，但会进入插件 warnings；新插件应优先选择本清单中已声明的内建点位
• 宿主通过 <AddonSlotRenderer slot="..." props={{ ... }} /> 或 <AddonSurfaceRenderer surface="..." props={{ ... }} /> 调用时，当前点位上下文会进入 context.props
• 同一插件重复注册同一个 hook + key 时，只保留第一次注册；重复项会进入插件 warnings，不会覆盖已注册处理器

Action Hook

补充说明：

• message.send.before / message.send.after 的 payload 当前都会携带 conversationKind（DIRECT / SITE_CHAT）；其中 after 的 contentAdjusted 会同时反映插件文本改写和宿主敏感词替换。
• report.create.after 的 payload 当前会携带结构化 report 快照；contentAdjusted 会同时反映 report.reasonDetail.value 改写和宿主敏感词替换。
• user.update.after 的 payload 当前会携带结构化 profile 快照；contentAdjusted 会同时反映资料字段的插件改写和宿主敏感词替换。
• task.complete.after 只会在本轮任务首次完成并完成奖励结算后触发；重复事件、重复点赞、已完成任务不会再次派发。
• check-in.submit.before 会以 throwOnError: true 执行，可阻断普通签到或补签；payload 含 userId/username/action/date/reward/pointName，补签额外含 makeUpCost。
• check-in.submit.after 只在签到动作成功返回前触发；payload 含 finalReward/points/currentStreak/maxStreak/alreadyCheckedIn，其中 alreadyCheckedIn 可用于识别普通签到重复提交。

Waterfall

补充说明：

• post.content.value 当前会在帖子创建、普通编辑和超时后追加内容三条链路执行；它只改写公开正文 / 追加正文，不会自动改写登录解锁、回复解锁、购买解锁等附加文本。
• message.body.value 会在宿主敏感词处理和 message.send.before action hook 之前执行；其 payload 当前包含 recipientId?、conversationId? 与 conversationKind（DIRECT / SITE_CHAT）。
• report.reasonDetail.value 即使初始补充说明为空也会执行；插件可以基于 reasonType、targetType 自动补全模板化说明。
• user.profile.bio.value 与 user.profile.introduction.value 允许返回空串，宿主会按“显式清空”处理，不会自动回退到旧值。
• user.profile.nickname.value 仍沿用非空保护；插件若返回空串，宿主会保留原始昵称继续后续校验。

AsyncWaterfall

Surface

命名规则：

• 如果宿主同时开放了 xxx.before 和 xxx.after 两个 slot，中间那块默认 UI 通常会同步开放一个 xxx 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

当前已接入的一批常用 surface 包括：

• 页面主体类：addon.page、about.page、announcements.page、auth.complete.page、auth.forgot-password.page、auth.login.page、auth.passkey.page、auth.register.page、badge.page、board.page、collections.page、custom-page.page、feed.page、friend-links.page、funs.page、funs.app.page、help.page、history.page、leaderboard.page、notifications.page、prison.page、search.page、settings.page、tag.page、tags.page、tasks.page、terms.page、topup.page、topup.result.page、user.page、vip.page、write.page、zone.page
• 头部 / Hero 类：addon.page.header、about.hero、announcement.hero、announcements.hero、auth.complete.panel、auth.forgot-password.panel、auth.login.panel、auth.passkey.panel、auth.register.panel、badge.hero、board.hero、collections.hero、friend-links.hero、leaderboard.hero、search.hero、tasks.header、terms.hero、vip.hero、write.header、zone.hero
• 帖子作者类：post.header、post.author.row、post.author.meta、post.author.verification、post.author.name、post.author.badges
• 评论作者类：comment.author.row、comment.author.meta、comment.author.verification、comment.author.name、comment.author.badges
• 内容 / 列表类：addon.page.content、about.highlights、about.principles、announcement.content、announcements.content、auth.login.form、auth.register.form、board.content、custom-page.content、faq.content、feed.main、friend-links.content、funs.app.content、leaderboard.content、notifications.list、post.body、post.create.form、post.create.tools、post.create.editor、post.create.enhancements、post.create.submit、post.weibo.feed、prison.content、search.results、settings.content、settings.profile、settings.invite、settings.post-management、settings.board-applications、settings.level、settings.badges、settings.verifications、settings.points、settings.follows、tag.content、tasks.content、terms.content、topup.payment、topup.redeem、topup.result.panel、user.activity、user.profile、vip.actions、vip.levels、zone.content
• 侧栏 / 辅助区块类：about.sidebar、badge.sidebar、board.sidebar、collections.sidebar、custom-page.sidebar、funs.sidebar、help.sidebar、leaderboard.sidebar、prison.sidebar、tag.sidebar、tags.sidebar、terms.sidebar、user.sidebar、zone.sidebar
• 交互区块类：layout.header、layout.footer、messages.page、messages.header、messages.sidebar、messages.thread、collection.hero、collection.pending、collection.content、history.panel

完整内建清单以 ADDON_SURFACE_CATALOG 为准。除上面常用分组外，当前还声明了 custom-page.*、zone.*、feed.*、collection.page/sidebar 等页面点位。

说明：

• 服务端静态区块一般通过 render(context) 接管
• messages.page、settings.page 属于 hybrid surface：先尝试服务端 render(context)，未命中再回退到 clientModule
• 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
• post.weibo.feed 的 context.props 包含 items、source（feed / post-stream）、showBoard、showPinBadge、postLinkDisplayMode，在节点 / 分区帖子流里还会包含 sortLinks
• 如果某个只有单边 slot、纯插入位、或宿主没有默认内容的点位，通常不会对应 surface

Slot

认证

插件页

全局布局

首页 / 节点 / 帖子

用户设置

任务 / 榜单

积分 / VIP

帮助 / 关于

发帖页 / 功能区

FAQ / 通知 / 私信 / 搜索

标签 / 用户主页

内容流 / 节点 / 合集

公告 / 足迹 / 友情链接 / 节点目录 / 勋章详情

协议 / 小黑屋 / 认证流程 / 充值结果

js
api.registerActionHook({
  key: "after-login-sync",
  hook: "auth.login.after",
  async handle(context) {
    // ...
  },
})

示例

js
api.registerWaterfallHook({
  key: "slug-prefix",
  hook: "post.slug.value",
  transform(context) {
    return `topic-${context.value}`
  },
})

api.registerAsyncWaterfallHook({
  key: "prepend-navigation",
  hook: "navigation.primary.items",
  async transform(context) {
    return [
      { label: "活动", href: "/events", activePrefix: "/events" },
      ...context.value,
    ]
  },
})