Xiuno BBS X 插件开发 Skill

> 本 Skill 是精简入口，深入细节查 references/（速查）和 references/manual/（完整手册）。写代码时对照本文件的硬规则与工作流。

目录

• When to Use
• 输入 / 输出
• 核心架构要点
• 硬规则
• 开发工作流
• 速查参考
• Hook 选择速查
• 失败策略
• 交付检查表
• 输出要求

When to Use

✅ 使用本 Skill

• 用户要求为 Xiuno BBS X（XIUNOX）写新插件、改插件、调试插件、加 hook/路由/后台设置页
• 用户要求加签到/标签/勋章/举报/收藏/投票/抽奖/悬赏等新功能插件
• 用户要求创建 Service 类、写 install/uninstall/upgrade 脚本、配置 conf.json
• 用户报告插件不生效、hook 不触发、修改后无变化、白屏、扫描器拦截 fatal/warning
• 用户要求将旧插件从 jQuery / Alpine.js 迁移到 htmx 4 + 原生 JS
• 用户要求做插件架构设计、查 hook 注入点、查 API 签名、查前端模式
• 用户要求排查插件冲突、互斥规则、目录命名规范问题
• 用户要求接入 DiscoverService / NavService / EditorService / UserBanService 等系统级服务
• 用户要求做主题插件 / 改前台版式 / 换肤样式（仿某 App 风格的主题模板，type:"theme"）

❌ 不要使用本 Skill

• 普通 PHP 编码问题、与 Xiuno BBS 插件架构无关的 Web 开发任务
• 修改 Xiuno BBS 核心源码（model/、lib/、route/、xiunophp/）本身而非通过插件扩展
• 仅查询 Xiuno BBS 使用方法（如后台操作、发帖流程），不涉及代码开发
• 部署运维（nginx 配置、数据库备份、PHP 环境搭建）问题

输入 / 输出

• 输入：功能需求或问题描述；目标插件目录名（未给出则按 作者_功能标识 新建并说明）；现有插件代码 / 报错信息 / 截图描述。
• 输出：变更文件清单 + 关键架构决策 + 使用说明 + 测试结果 + 遗留风险 + Grep 审计结果，格式见文末 输出要求。

核心架构要点

1. 编译期合并 hook，无运行时事件分发。 把文件放到 plugin/<dir>/hook/<hook名> 即注册 hook，没有 add_hook() 函数。_include() 编译时把 hook 内容物理拼进源文件，缓存到 tmp/。改 hook 后必须清 tmp/。
2. hook 文件名（含扩展名）必须与源标记完全一致。 PHP 源码标记 // hook thread_create_thread_end.php；模板标记 <!--{hook thread_subject_after.htm}-->。
3. 模型三层命名： __ 原始层（纯 DB）→ 单 _ 业务层（缓存/计数/通知/hook）→ _format 装饰层。插件永远调单下划线业务层。
4. db 是插件状态的唯一权威源。 bbs_plugin 表存 installed/enable/version；conf.json 的 installed/enable/id 已彻底废弃，代码层任何情况下都不读。前台判断启用用 plugin_paths_enabled()，禁止 global $plugins（前台未初始化）。
5. 双模板系统： PC 端 + 移动端通过成对 hook（如 post_ref_thread_after.htm + *_mobile.htm）各渲染一份，CSS 控制显隐。移动端 id 必须加 -mobile 后缀。

> 完整架构说明见 references/manual/01-architecture.md

硬规则

❌ 禁止项（违反 = 扫描器拦截或运行异常）

✅ 必须项

> 完整规则清单见 references/ai-rules.md

前端 UI 偏好规范

开发工作流

Step 1: 需求评估

1. 确认功能目标、用户角色、触发场景（前台/后台/API）
2. 检索项目中是否已有同类组件可复用（Grep 搜 TablerIconPicker、bootstrap.Modal、lightbox 等）
3. 确认插件目录名符合 作者_功能标识 两段格式；主题类第二段为 theme；前缀不与 xn_/xnx_ 冲突
4. 确认是否依赖其他插件（写入 conf.json.dependencies）

Step 2: 架构设计

1. 选 hook 注入点：查 references/hooks-catalog.md 找精确位置
2. 设计数据模型：表名带前缀（{$db->tablepre}my_plugin）、字段用 utf8mb4、统计字段直接 db_count 目标条件（禁止 A-B 相减）
3. 设计 Service 类：静态方法模式，放 model/ 目录由 index.php 兜底自动加载（类名=文件名）；hook/model_inc_file.php 可选双保险
4. 设计路由：自定义路由通过 hook/model_route_table_end.php 注册到 $routes
5. 设计前端：发帖辅助功能挂 post_ref_thread_after.htm（PC）+ *_mobile.htm（手机端），卡片样式与"引用帖子"一致
6. 确认 conf.json 字段：name/brief/version（X.Y.Z 三位制）/bbs_version（X.Y 两位制，与当前 XIUNOX_VERSION 前两段一致）/type（"plugin"/"theme"），不含 id/installed/enable

Step 3: 实现

按顺序创建文件（详见 references/manual/02-plugin-structure.md）：

1. conf.json — 必填字段 + hooks_rank（键名与 hook 文件名含扩展名完全一致）+ overwrites_rank（object，非 array）+ dependencies（推荐 object {"dir":"ver"}，兼容 array ["dir"]）
2. install.php — CREATE TABLE IF NOT EXISTS + setting_set() 默认配置 + !defined('DEBUG') AND exit('Access Denied');
3. uninstall.php — 标准拼写（非 unstall.php）+ DROP TABLE + kv_delete()/setting_delete()
4. upgrade.php（如需结构变更）— SHOW COLUMNS + ALTER TABLE 幂等；递增 conf.json.version
5. model/XxxService.php — 静态方法模式；构造函数调 CacheHelper::registerKeys()
6. hook/model_inc_file.php（可选双保险）— 注册 Service：APP_PATH.'plugin/<dir>/model/XxxService.php',（每行逗号结尾）；index.php 兜底逻辑已自动扫描 model/*.php，不写本 hook 也能加载；禁止 model/*.func.php 函数库（xiuno 原版写法，会与自动扫描冲突导致函数重声明 fatal）
7. hook/ 其他 hook 文件 — PHP hook 以 <?php exit; 开头；.htm hook 以 <?php 开头；禁止 return;
8. route/ 路由文件 — param(1, 'list') 取 action；include _include() 加载模板
9. view/htm/ 模板 — 后台模板首尾 include _include(ADMIN_PATH . 'view/htm/header.inc.htm')/footer.inc.htm；前台用 APP_PATH
10. setting.php — 开头权限检查 + POST 走 CsrfService::check()
11. hook/lang_zh_cn_bbs.php（如需多语言）— 同步 zh-tw/en-us；改后清 tmp/lang_*_bbs.php
12. static/js/、static/css/ — 纯静态文件，禁止 <?php；JS ≥50 行独立文件用 <script src> 引用

Step 4: 测试

1. 清 tmp/ 编译缓存：rm -f tmp/route_*.php tmp/model_*.func.php tmp/view_htm_*.htm tmp/plugin_*.php tmp/plugin_*.htm tmp/lang_*_bbs.php（plugin_* 是插件 Service 与模板的编译产物，漏清会导致改动不生效）
2. 若改了 static/*.js/*.css，递增 conf/conf.php 的 static_version，硬刷新浏览器（Ctrl+F5）
3. 启用插件，检查扫描器报告（fatal/error 不可跳过，warning/info 可跳过）
4. 验证核心场景：发帖/回帖/编辑/删除/列表/详情/个人中心/后台设置
5. 验证 PC + 移动端双模板（id 加 -mobile 后缀，JS 同时更新两端）
6. 验证 hook 不含 return;（用 Grep 检查 hook/ 目录）
7. 验证 static/*.js 无 <?php 代码（用 Grep 检查）

Step 5: 交付

1. 跑交付检查表（见下方"失败策略"前的检查清单）
2. 用 Grep 审计常见违规项：
   - Grep "esc_textarea" 全局应无结果
   - Grep "jQuery\|\\$.ajax\|\\$.fn" 应无结果
   - Grep "Alpine\|x-data\|x-show" 应无结果
   - Grep "return;" 在 hook/ 目录下应无结果（闭包内除外）
   - Grep "<\\?php" plugin/*/static/*.js 应无结果
3. 确认 conf.json 不含 id/installed/enable 字段
4. 打包 zip（保留 conf.json 在根目录，详见 references/manual/02-plugin-structure.md）

速查参考

Hook 选择速查

> 完整 Hook 目录见 references/hooks-catalog.md

失败策略

交付检查表

交付前必须确认（核心项，完整清单见 references/ai-rules.md）：

• [ ] conf.json 必填字段完整（name/brief/version/bbs_version/type），不含 id/installed/enable
• [ ] install.php 用 IF NOT EXISTS 幂等；uninstall.php 用标准拼写删表 + 删 KV
• [ ] 数据库结构变更走 upgrade.php 幂等迁移，递增 conf.json.version
• [ ] 所有 PHP hook 以 <?php exit; 开头；.htm hook 以 <?php 开头；hook 文件名与源标记完全匹配
• [ ] hook 文件无 return;（路由层 + model 层 + view 层全适用）
• [ ] 所有 POST 表单含 CsrfService::input()，POST 处理以 CsrfService::check() 开头
• [ ] 所有输出用 esc_html()/esc_attr()/esc_js()，无 esc_textarea()
• [ ] 无 jQuery / Alpine.js / idiomorph；无 htmx:configRequest 等 2.x 旧事件名
• [ ] 命名全带前缀（表/变量/语言键/JS 全局/setting 键/CSS class）
• [ ] JS/CSS 放 static/ 目录（非 view/htm/）；引用用 $conf['view_url']（非 APP_PATH/相对路径）
• [ ] static/*.js 中无 <?php 代码
• [ ] 数据库表用 utf8mb4；db_* 函数传表名不含前缀
• [ ] 用户信息显示用 user_find_by_uids/user_read，模板取 display_name（非 username）
• [ ] URL 用命名快捷函数或 url()，禁止硬编码 .htm/.html 后缀
• [ ] 缓存用 CacheHelper::remember()/pluginKey()/pluginDeletePrefix()
• [ ] Service 调用核心类前 include_once 守卫
• [ ] 改核心文件后清 tmp/；改静态资源后递增 static_version
• [ ] 后台模板 include ADMIN_PATH 的 header/footer；前台用 APP_PATH
• [ ] Card 组件必须 x-card + card 组合，禁止裸 card/border/border-*
• [ ] 前台页面用三栏骨架 layout_three_column.inc.htm，禁止自行写 container/row/col-lg-*
• [ ] 头像用 avatar_component_from_data()，非原生 <img>
• [ ] PC/移动端双模板 id 加 -mobile 后缀
• [ ] 插件目录名符合 作者_功能标识 两段格式；主题类第二段为 theme
• [ ] 静态资源引用带版本号（hook 用 $static_version，视图用 $conf['static_version']）
• [ ] UI 组件符合规范：x-card + card、三栏布局骨架、Toast/Modal 场景区分
• [ ] 视频内联播放、不出现在附件列表中

输出要求

完成插件开发任务后，输出应包含：

1. 变更摘要：列出新增/修改的文件（绝对路径）和每个文件的核心作用
2. 关键决策：说明选择的 hook 点、数据模型设计、路由命名等关键架构决策及原因
3. 使用说明：如何启用插件、配置项说明、前台/后台入口 URL
4. 测试结果：已验证的场景列表（含 PC + 移动端双模板）
5. 遗留风险：未覆盖的边缘场景、潜在冲突、后续优化建议
6. 审计结果：Grep 审计命令的执行结果（esc_textarea/jQuery/Alpine/return;/<?php in static/*.js 等均应无结果）

> 详细 API 见 references/api-cheatsheet.md；详细前端模式见 references/frontend-patterns.md；完整手册见 references/manual/README.md。