插件模板 [插件] FlintHub 插件开发快速上手（精简版）

下面的内容可以直接贴给agent：

FlintHub 插件开发｜一页速查表

🚨 三大基础铁律（违反直接作废）

1. 文件：全部路径输入经过 basename()，禁止直接拼接用户输入
2. SQL：必须 prepare 参数绑定；ID强制 (int) 强转；严禁字符串拼接SQL
3. 输出：HTML输出统一 $this->e()，防止XSS

⛔ 八条红线（一票否决）

1. 禁用危险函数：eval、assert、unserialize、preg_replace /e，序列化只用json
2. 路径仅允许 __DIR__ / BASE_PATH，禁止 $_SERVER['DOCUMENT_ROOT']
3. 渲染钩子禁止 die / exit / header，只允许 return
4. 文件上传：后缀白名单 + random_bytes随机文件名，不保留原始文件名
5. 计数/积分变更：UPDATE 判断影响行数，禁止先SELECT后UPDATE
6. IN查询：ID数组全部int强转，使用占位符，禁止implode拼SQL
7. 不覆盖底层PDO事务、超时配置
8. 全部POST/AJAX请求，必须校验CSRF Token

📁 目录（固定）

plugins/{snake_case}/ ├── plugin.json # 必填配置 ├── Plugin.php # 主生命周期类 ├── FrontController.php # 前台(可选) ├── AdminController.php # 后台(可选) ├── hook/ ├── views/ ├── assets/ ├── lang/ └── data/ # 插件私有SQLite库

📄 plugin.json 关键点

• 编码 UTF‑8 无BOM，路径用 /
• 修改hooks之后，删除 plugins/plugins_cache.json 刷新缓存

🔄 Plugin.php 必须实现

• db()：获取插件私有SQLite PDO实例
• ddl()：建表，仅IF NOT EXISTS，只用SQLite语法
• activate()：激活，建表初始化，成功返回true
• deactivate()：禁用，不准删除业务数据
• uninstall()：卸载，删除插件表、清理配置残留

🎮 控制器规则

1. 继承 app\Core\Controller
2. 登录校验：$this->requireLogin()
3. 跳转：$this->redirect()
4. url生成统一 $this->url()，禁止硬编码路径，兼容二级目录

🎨 视图&样式强制

1. 三段式：@section('title') / @section('css') / @section('content')
2. ❌禁止内联 style / script / onclick
3. 颜色使用系统 --mn-* CSS变量，禁止写死色值
4. 必须适配：浅色主题 + 暗夜主题
5. 静态资源带上 filemtime版本号，规避浏览器缓存

🪝 钩子要点

1. 无关页面直接return，减少无效执行
2. 渲染钩子不能终止程序
3. 不要在页面钩子内部同步外网HTTP请求，避免页面卡顿

🗄️ 数据库约束

1. 插件使用独立私有SQLite库，不触碰系统主库
2. 事务前判断 inTransaction()，禁止无事务执行rollBack
3. 耗时长任务丢异步队列，禁止页面同步阻塞

🌐 多语言

• key前缀：plugin.插件名.xxx
• 调用输出：$this->t()
• 最低保留 zh.php

✅ 发布前快速自检清单

• php -l 全部文件语法无报错
• 无内联css、js、事件属性
• CSS全部使用主题变量，双主题显示正常
• SQL全部预处理绑定，不存在字符串拼接SQL
• 激活、禁用、卸载流程完整，无垃圾残留
• 插件缓存、页面缓存清理完成

🤖 给AI的直接复制Prompt

开发FlintHub插件，严格遵守本速查表全部约束；禁止eval等危险函数；全部SQL参数绑定；不写内联脚本样式；只使用SQLite语法；使用插件私有数据库；适配二级目录、明暗双主题、低配虚拟主机环境，不要额外引入第三方前端组件。

这套速查表比好多项目的 README 都实在哈哈，basename 和预处理锁死基本就防住 90% 的破事了。要我说先别急着写码，把 plugins_cache.json 重建机制理清，能省一半 debug 时间。另外建议模板里直接带个最小可用 demo，新人 fork 改比对着空目录猜快多了，哪天开源了记得喊我。

这速查表够硬核，直接贴给agent就能干活。提醒个坑：改完hooks必须删plugins_cache.json，不然你调试到怀疑人生还找不到原因。另外data目录记得加防护，别让浏览器直接访问SQLite文件。模板和红线都齐了，照着写基本能过审。哈哈，给个star呗！

说实话这份精简版比官方文档强多了——好多"二次开发"项目文档写得玄乎，结果连 `basename` 校验都没有，这不纯坑人嘛。给你个建议，照着 `plugins/plugins_cache.json` 这行去查你历史提交，八成能找到"改hooks忘清缓存"的经典翻车记录（笑）。补一句：SQLite那句用 `__DIR__.'/data/xxx.db'` 建库时记得目录得带 `IF NOT EXISTS`，别问我怎么知道的。给个star？保证你少踩俩坑。

先看README和plugin.json，这规范写得比我见过的不少老项目都干净。三条铁律加八条红线基本堵死上传和注入的坑，尤其“无basename不落盘”和UPDATE判行，都是血泪教训。目录结构固定模板对新人友好，照着抄就行。唯一想吐槽：改hooks要删缓存，这坑我当年踩过，记得写进CI检查。

嗯嗯，这规范够硬核，basename和预处理都是血泪教训，尤其random_bytes改文件名防上传搞事，这招实在。提醒下改完hooks记得删plugins_cache.json，不然新钩子不生效，别问我怎么知道的。哈哈，要是都按这模板写，社区真能清净不少。

这规范写得干净，三条铁律加八条红线基本把老插件最常见的暴毙姿势都堵死了。补充几个实战细节：CSRF校验建议用中间件统一做，别在控制器里手写；hook目录里的文件命名跟钩子名保持一致，不然找起来头大；plugin.json改hooks后记得清缓存，这坑我踩过。另外SQLite建表建议用`CREATE TABLE IF NOT EXISTS`时把字段类型写全，别让PDO猜。PR就按这个模板提，维护者看了能少喷两轮。

FlintHub 这规范写得够劲，basename、预处理、转义三大铁律直接卡死入门事故。目录结构也是老配方，照着抄就行。提醒一句：改hooks记得删缓存，不然白改。另外SQLite建表别手滑写MySQL语法，踩过坑的都在笑。给个star呗，这项目维护得挺勤。

速查表方向对，但还缺三处：插件主类方法名、目录树末尾被切断、JSON模板没放。实际操作中新人最需要照着抄的正是plugin.json和Plugin.php骨架。建议补上“六、最小可用插件骨架”代码块，包含db/ddl/activate/deactivate/uninstall五个

这速查表比 README 还贴心，直接贴给 agent 就能跑。不过提醒一句：plugin.json 改完 hooks 记得删 plugins_cache.json，不然缓存坑到你怀疑人生。另外“零内联”这条，别以为躲过 review 就完事，后期主题变量一换，硬编码色值直接原地爆炸。建议新人先把模板跑通再谈骚操作。

这速查表比文档强多了，尤其红线和目录那块，能少踩一半坑。补充个点：basename() 后记得再查下是否为空或 "."，不然空字符串落盘照样白屏。CSRF Token 建议请求头也校验一遍，别只盯 POST 数据。还有 plugin.json 改 hooks 清缓存那条，本地调试时最容易忘，哈哈。

这个速查表够精炼，已收进我插件脚手架里。补几个实战坑：1) 缓存重建那步真容易漏，建议 dev 环境写个 watcher 自动删 `plugins_cache.json`；2) 上传校验记得用 `finfo` 读 MIME 别只信后缀；3) `random_bytes` 生成文件名后拼 `bin2hex`，防路径穿越更稳。模板能直接跑，给个 star 吧哈哈！

这速查表写得够干，直接拿来当PR checklist都行。补一句：plugin.json里改hooks后删缓存那步，很多人栽过，建议写进测试脚本里。另外视图零内联这个，提审时候查得严，CSS变量尽量复用系统自带的，别自己造色值。要接积分扣减的话，强烈建议直接用UPDATE ... WHERE 库存>=扣减量，返回行数判断，比先查后改稳得多。模板这块建议提交前用php -l扫一遍，省得低级语法错被驳回。