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

适用：自研 FlintHub 插件快速开发、AI 辅助开发、新人上手

原则：只留实操规范、强制红线、最简模板，无冗余理论

完整版依据：FlintHub 插件开发规范 1.0

一、核心三大铁律（必守，违规直接不合格）

1. 文件操作：无 basename 不落盘

所有文件名、保存路径，必须先过 basename()，杜绝路径穿越，禁止直接拼接用户输入。

2. 数据库：无预处理不执行

所有 SQL 必须 prepare + 参数绑定，ID 强制 (int) 强转，禁止字符串拼接 SQL。

3. 输出内容：无转义不输出

页面输出必须 $this->e() / htmlspecialchars，内容入库可按需 strip_tags，杜绝 XSS。

二、八条顶级红线（一票否决）

1. 禁止危险函数：禁用 unserialize、eval、assert、preg_replace/e，序列化统一用 json_decode

2. 禁止非法路径：仅用 __DIR__ / BASE_PATH，禁用 $_SERVER['DOCUMENT_ROOT']

3. 渲染钩子禁止中断：页面渲染类钩子不准 die/exit/header，只可 return

4. 上传强制校验：后缀白名单 +random_bytes 强随机文件名，禁止保留原文件名

5. 数值扣减原子化：积分/库存 先 UPDATE 判行，禁止先查后改（防并发超扣）

6. IN 查询安全化：ID 数组全 int 强转，占位符拼接，禁止 implode 拼 SQL

7. 禁止覆盖 PDO 配置：沿用核心事务、超时、防预编译模拟配置

8. AJAX 必须 CSRF：所有 POST 异步请求必须携带并校验 CSRF Token

三、标准插件目录结构（固定模板）

一插件一目录，目录名：小写下划线；命名空间：首字母大写驼峰

plugins/插件名/
├── plugin.json        # 插件配置（必填）
├── Plugin.php         # 主类：建表、启停、卸载
├── FrontController.php # 前台控制器（可选）
├── AdminController.php # 后台控制器（可选）
├── hook/              # 钩子文件
├── views/             # 前后台模板
├── assets/            # 样式、JS（零内联）
├── lang/              # 多语言包
└── data/              # 插件独立SQLite库（自动防下载）

四、plugin.json 最简必填模板

编码：UTF-8 无 BOM，路径统一/ 分隔

{
    "name": "插件名称",
    "version": "1.0.0",
    "author": "FlintHub",
    "description": "插件功能描述",
    "activated": false,
    "icon": "cube",
    "admin_url": "/admin/插件路由",
    "hooks": {},
    "permissions": []
}

重要：修改 hooks 后，必须删除plugins/plugins_cache.json 重建缓存。

五、插件主类 Plugin.php 规范

固定四大方法

• db()：返回插件独立 SQLite PDO 实例

• ddl()：SQLite 建表语句（仅 IF NOT EXISTS 幂等）

• activate()：激活建表，成功返回 true，失败回滚

• deactivate()：禁用，禁止删数据

• uninstall()：卸载，清空数据表、清理核心残留

强制：所有建表使用纯 SQLite 语法，禁止 MySQL 语法。

六、控制器规范

1. 统一继承 app\Core\Controller

2. 登录校验只用 $this->requireLogin()

3. 页面跳转只用$this->redirect()

4. 404 统一渲染 errors/404 视图

5. 所有 URL 用 $this->url()，禁止硬编码 /xxx（适配二级目录）

七、视图与样式规范（重点）

1. 页面结构固定三段式

section('title') 页面标题 / section('css') 页面样式 / section('content') 页面主体

2. 样式强制约束

• 零内联：禁止页面内联 style、script、onclick 事件

• 全变量化：只用系统 --mn-* 主题变量，禁止硬编码色值

• 资源引入携带 filemtime 版本号，解决缓存问题

• 双主题兼容：浅色/暗夜星辰 必须全部适配可读

八、钩子开发最简规则

1. 钩子文件顶部先判空、判模板，无关页面直接 return，不无效执行

2. 页面渲染类钩子绝不中断页面

3. 新增钩子必须写入 plugin.json，刷新插件缓存

4. 常驻页面钩子禁止重查询、禁止同步外网请求（防页面卡顿）

九、数据库与事务最简规范

1. 插件数据全部私有 SQLite，不碰核心库、不跨插件读写

2. 事务只用原生 beginTransaction / commit / rollBack

3. 回滚前必须判断 inTransaction()，杜绝无事务回滚报错

4. 耗时、大批量任务全部丢队列异步，禁止页面同步阻塞

十、多语言规范

1. 语言键统一前缀：plugin.插件名.xxx

2. 前台交互文案后缀 _act，后台校验文案无后缀

3. 至少保留 zh.php，建议同步 en、zh_tw

4. 视图统一调用 $this->t()

十一、插件生命周期铁规

• 激活：仅建表、初始化数据，成功才返回 true

• 禁用：仅关闭功能，绝不删除数据

• 卸载：清空私有表 + 清理核心配置残留，无垃圾遗留

十二、AI 开发强制指令（直接复制即用）

开发插件全程遵守：三铁律、八红线、零内联、变量化样式、私有数据库、无 SQL 拼接、无路径穿越、AJAX 必 CSRF。 禁止自作主张使用流行组件、硬编码样式、MySQL 语法、危险函数。 所有代码适配 FlintHub 二级目录、双主题、虚拟主机低配环境。

十三、发布前 6 项快速自检

1. php -l 语法无错误

2. 无任何内联 css / js / 事件属性

3. 所有样式使用 --mn-* 变量，双主题显示正常

4. SQL 全部预处理绑定，无拼接

5. 激活/禁用/卸载流程完整无残留

6. 钩子缓存已刷新、页面缓存已清理

（注：部分内容可能由 AI 生成）