156 个钩子全景：插件能挂载的所有位置

结论：Clara BBS 一共暴露 156 个运行时钩子，插件不改一行核心代码，就能挂进从注册登录、发帖回帖、记账打赏到后台菜单与定时任务的几乎所有关键环节。但这 156 个点官方并没有一份"写死的清单"——最靠谱的全景图，是拿官方插件当索引、在源码里反向检索出来的。

先搞清楚"运行时钩子"是什么

钩子（hook）指的是核心代码在关键节点主动"喊一嗓子"，插件事先登记过名字，就能在那一刻插入自己的逻辑。Clara BBS 的插件目录是 `content/plugins`，由运行时钩子体系加载，保存即生效，不需要 Composer、不需要编译、不需要清缓存。这一点和"改核心文件"有本质区别：升级覆盖文件时，核心被覆盖了插件就没了；走钩子的插件不受影响。

结论：判断一个位置值不值得挂插件，只看一件事——核心代码在那里有没有触发钩子。有触发点，插件就能介入；没有，就只能改核心。

三步摸清这 156 个点到底在哪

第一步，看官方插件监听什么。官方插件（AI 智能回复、GEO 问答工厂、AI 写作、API 工具箱、答题考试、抽奖、会员墙、广告位、快捷回复、站点排行、访客统计、品牌落地页、复制尾注、哀悼模式）每一个都在注册若干钩子，把它们注册过的钩子名汇总去重，就是一份真实可用的钩子地图——这比任何文档都可信。

第二步，写一个探针插件。把自己掌握的钩子名逐个注册，回调里只做一件事：把钩子名 + 时间 + 当前 URL 写进日志。然后前台把首页、版块页、帖子页、用户页点一遍，后台把帖子管理、用户管理、系统设置点一遍，看日志里蹦出哪些名字。没被触发的说明触发条件还没满足（比如只在"采纳最佳答案"那一刻才触发），不是不存在。

第三步，按功能域反推漏网之鱼。想清楚"这个功能在运行时会经过哪几个节点"，再去对应代码位置搜钩子调用。这是找冷门钩子最有效的方式。

这 156 个点大致分布在八个环节

下面按功能域归纳，具体钩子名请以你手上版本的源码为准：

• 账号与登录：注册、登录成功、登录失败、连续错误锁定、后台手动解锁——想接第三方登录或登录风控，挂这里。
• 内容发布与编辑：发帖前校验、发帖后、回帖、编辑、审核流转、进回收站与恢复。注意先审后发是按版块开关的，钩子回调里要自己判断当前版块状态。
• 页面渲染：首页、版块页、帖子页、用户页、导航与广告位。这是插件最容易"看得见"的位置。
• 互动：点赞、@提及、关注、私信、举报、礼物打赏。
• 交易与记账：悬赏托管与采纳发放、附件购买、转账、卡密、签到奖励。涉及钱的钩子务必走系统的统一货币记账 API，别自己直接 UPDATE 余额字段，否则账目对不上。
• 通知与邮件：发通知、发邮件，一般配合 `notify` 用。
• 后台与管理：后台菜单、各管理页保存前后、用户/帖子/版块操作。
• 计划任务与缓存：配 `Cron::register` 注册定时任务（懒触发，零配置），配 `Cache::remember` 做缓存。

结论：Clara BBS 插件开发优先复用的四个公共设施是 Cache::remember、Cron::register、notify 和货币记账 API，自己造轮子只会把站点拖慢。

挂钩子前必须知道的三个坑

第一，运行时加载意味着插件出错会牵连页面。回调里该 try/catch 就 try/catch，尤其是挂在渲染钩子上的插件。

第二，页面输出类插件要守住隐私口径。系统所有面向 AI 引擎的输出（llms.txt、llms-full.txt、answers.html）只包含游客可见版块的内容，隐藏版块和权限版块绝不外泄——你的插件如果自己往页面吐数据，同样得按这个标准过滤。

第三，钩子数量多不等于随便挂。同一个功能挂三四个钩子，用户点一次帖子要跑三遍查询，这是最常见的性能事故。能用缓存挡一层就先挡一层。

156 个钩子听起来很多，但真正决定一个插件好不好写的，是你能不能准确判断"这个功能该挂在哪个节点"。方法是死的：官方插件找索引、探针插件做验证、功能域反推补漏，三步走完，这 156 个位置对你就不是黑盒了。