Xiuno BBS X 插件开发

解决的问题

为 Xiuno BBS X 写插件，很多坑不在 PHP 语法，而在框架的隐性约束：

• plugin/xxx/hook/ 里的文件文件名（含扩展名）必须和源码标记完全一致，少个 .php 或 .htm，hook 就静默失效。
• 用了 jQuery 或 Alpine.js 会被安全扫描器直接拦成 fatal，白屏；裸 htmlspecialchars()、不带 CSRF 的 POST、裸 include 同样触发拦截。
• hook 里写了 return;，或 .htm 模板里把 JS 写成 //，可能导致页面崩掉。
• display_name、status 这类字段在 SQL 里直接 SELECT 会报 Unknown column，因为它们是 user_format() 等装饰层派生的虚拟字段。
• 前台判断插件是否启用时误用 global $plugins，结果前台根本没初始化这个变量，功能时有时无。

技能如何工作

这个技能是一个精简入口 + 分层文档的组合：用 SKILL.md 集中讲硬规则和工作流，细节交给 references/（速查）和 ../plugindev/（完整手册）。核心能力分五块：

1. 硬规则清单
用两张表给出“禁止项”和“必须项”。禁止 jQuery、Alpine.js、idiomorph；禁止裸转义、裸 include、window.__xxxData 全局状态；必须用 esc_html()/esc_attr()/esc_js() 转义，必须用 CsrfService::input() + CsrfService::check() 校验 CSRF，必须用 _include() 加载模板。后台（admin/）里不能用 htmx，要用原生 JS + Bootstrap。

2. 前端 UI 偏好
轻提示用 XN.toast()，确认删除用 XN.confirm()，重要错误用 XN.alert()。前台必须用三栏骨架 layout_three_column.inc.htm，不能自己写 container/row/col-lg-*。卡片组件必须 x-card + card 组合，右侧栏卡片标题格式固定，不能用 card-header 或 h5。视频要内联播放，不出现在附件列表里。

3. 开发工作流
分四步：需求评估（确认目录名至少两段 作者_功能标识，主题类第二段为 theme）→ 架构设计（选 hook 注入点、设计数据表前缀和 Service 类）→ 实现（按顺序创建 conf.json → install.php → uninstall.php → upgrade.php → model/XxxService.php → hook 文件）→ 测试（清 tmp/ 编译缓存、递增 static_version、验证 PC 和移动端双模板）。

4. 失败策略
针对十几种常见故障给出排查顺序。例如 hook 不生效，依次检查：文件名是否和标记一致、conf.json.hooks_rank 键名是否含扩展名、tmp/ 缓存是否清理、插件是否在 bbs_plugin 表里启用。函数重声明 fatal，先查 model/ 目录有没有 *.func.php，应改为 XxxService.php 静态类。

5. 交付检查表
开发完成后按清单逐项确认：conf.json 不含已废弃的 id/installed/enable，数据库变更走 upgrade.php 幂等迁移，静态资源引用带版本号，UI 组件符合规范。

适用边界与注意点

这个技能只用于插件扩展，不处理：

• 修改 model/、lib/、route/、xiunophp/ 等核心源码（应通过插件 hook 或 _register.php 自注册实现）。
• 通用 PHP 编码问题或与 Xiuno 插件架构无关的 Web 开发。
• 后台操作指导、发帖流程说明等纯使用问题。
• nginx 配置、数据库备份、PHP 环境搭建等部署运维。

另外需要注意：插件目录名不能是单段，至少 作者_功能标识 两段；前缀不能以 xn_ 或 xnx_ 开头；hook 里的局部变量必须加插件前缀（如 $_myplugin_settings），避免污染宿主作用域；static/*.js 或 static/*.css 修改后要递增 conf/conf.php 的 static_version，否则浏览器可能读到旧缓存。