本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：内部文档归档。
FlintHub 插件开发规范 · 最终版导读与版本演化
本篇由 7 份文档整理而成。最新完整规范原文（最终版，内部版本号 1.6，2026-10-16 变更、2026-10-18 定稿，约 8.8 万字符）保留在
WWW/docs/插件开发规范.md，本篇给出章节地图、核心规则与四个版本的演化脉络。完整的历史变更摘要（1.3 / 1.4 / 1.5 / 1.6）见
WWW/docs/插件开发规范-CHANGELOG.md。
一、规范定位与适用对象
- 适用范围：FlintHub 社区系统
plugins/目录下所有插件。 - 配套代码：
app/Helpers/Plugin.php、app/Core/Autoloader.php、app/Core/TemplateCompiler.php、app/Helpers/I18n.php、app/init.php。 - 参考实现：
plugins/points_mall（完整范例）、plugins/medal、plugins/qa、plugins/task_center、plugins/adslot。 - 自检入口：钩子表核对用
php .workbuddy-ai/tools/plugin_hook_audit.php（输出钩子数 / 调用点数 / 与规范 §9.1 表的双向差集）。 - 文档性质：由对现有插件目录、核心插件机制、全部钩子触发点及历史审计报告的综合分析生成——它不是"设计草案"，而是从
app/实际代码逐行核实 + 历史事故复盘沉淀出来的落地规范。 - 读者对象：插件作者，以及替人写插件的 AI Agent（最终版第十三章就是专门给 Agent 的指令模板，可直接整段附在指令里）。
规范的组织方式：开头用「三条硬性安全规则 + 8 条一票否决红线」把最狠的规则顶到最前（给 Agent 下指令直接抄这两段即可），中间十章讲结构与机制，第十一章是 36 个小节的"常见坑与红线清单"（全部来自历史审计与事故复盘），最后两章讲开发流程与 Agent 指令模板。
二、章节地图
下表按最终版（1.6）的实际标题结构整理，共 14 个二级章节（正文章节 13 章 + 插入章「一五」）。第三列只列最关键的约束，细则以原文为准。
| 章节 | 讲什么 | 关键约束 |
|---|---|---|
| 一、总则：三条硬性安全规则 | 文件操作、SQL、输出转义三条铁律 | 文件名一律过 basename()；SQL 一律 prepare()+绑定或 (int) 强转；输出不绕过 $this->e()/htmlspecialchars() |
| 一五、最高级别红线（8 条） | 一票否决清单 | 禁反序列化/动态执行、禁 DOCUMENT_ROOT、渲染钩子禁 die/exit/header、上传白名单+强随机名、库存/积分原子扣减、IN 强转+占位符、PDO 不覆盖核心属性、AJAX 必带 CSRF |
| 二、插件目录结构 | 一目录一插件的标准骨架 | 目录名即插件名（小写下划线）；禁放 .bak/.tmp 等残留；禁改核心文件；样式/JS 收敛到插件自己的 assets/ |
| 三、plugin.json 配置规范 | 字段表与坑 | hooks 路径用 /；改 hooks 后必须重建 plugins_cache.json（或 Plugin::refresh()）；icon 必须在 TemplateCompiler::$map 真实存在；category 取核心 10 类；permissions 强制声明（system:settings / route:admin / net:fetch） |
| 四、插件主类 Plugin.php | db()/ddl()/activate()/deactivate()/uninstall() 约定 | db() 必须 public static；activate 建表失败不得返回 true；§4.1 生命周期调用链显式约定 |
| 五、控制器与命名空间 | 命名空间与自动加载 | namespace 首段必须与目录名逐字节一致（Windows 假通过、Linux 直接 500）；前/后台控制器分工 |
| 六、视图与模板 | section 区块、模板方法、视图数据注入、§6.4 前台 UI 一致性 | 图标用 $this->icon() 且名字受 $map 约束；字号分钩子有权威表（14/15/16/12px）；前台页统一 .mn-section 容器 |
| 七、资源文件 assets/ | 引用方式与按页加载、§7.3 零内联细则 | 零内联（<style>/<script>/onclick= 一律进 assets/）；资源 URL 带 ?v=filemtime；禁改核心 admin.css |
| 八、语言包 lang/ | 自动合并机制与键名约定 | 键名统一 plugin.{插件名}.{语义}；至少提供 zh.php；前台交互提示用 _act 后缀，err_ 是后台校验文案 |
| 九、钩子系统全览 | §9.0 触发机制、§9.1 全表、§9.2 废弃钩子、§9.3/9.4 双触发陷阱、§9.5 文件模板 | 钩子数以 §9.1 表为准（44 个核心触发 / 51 个调用点）；触发点口径是「文件+锚点」，行号会漂移；钩子内异常被吞不影响页面；双触发钩子文件禁声明顶层函数/类 |
| 十、独立数据库与事务 | 独立 SQLite、事务、DDL | 每插件一个 data/{插件名}.sqlite；读核心帖子/博客必须经 Model（threads/posts 是退役表）；批量补用户名走 User::batchGetNames()；事务用 beginTransaction() 且回滚前判 inTransaction()；建表必须是 SQLite 语法 |
| 十一、常见坑与红线清单 | §11.1~11.36 共 36+ 小节 | 含安全红线、二级目录 BASE_PATH、性能（单插件每请求查询 ≤5 次）、核心库访问边界（禁直写 users/积分表）、插件间禁直耦、$this 在渲染钩子不可用、命名空间大小写、htmx 属性污染、投稿包结构等 |
| 十二、开发流程与验证 | 8 步流程 + §12.1 验证手法 6 条 + §12.2 投稿包自检 | 命名空间大小写必跑 plugin_case_lint.py；双触发钩子必做双 include 回归；投稿包一次通过 /plughub/submit 预检 |
| 十三、给 Agent 的指令模板 | 三段硬性规则 + 一长串附加约定 | 可直接整段附在给 Agent 的指令里；含性能红线、登录回跳 Auth::loginUrl()、卸载自检、投稿包结构等 |
三、必须遵守的核心规则（精选 16 条）
从最终版中挑出最能"一条定生死"的规则。每条先给规则要点，再给定这条规则的原因。
1. 三条安全铁律（一切插件代码）
文件操作先过 basename() 再落盘；SQL 必须 prepare() + 绑定或 (int) 强转；输出文字不绕过 $this->e() / htmlspecialchars()。
为什么：历史审计扫出的路径穿越、IDOR、XSS 全部源于这三处的侥幸心理，所以单列成铁律放在规范最前面。
2. 8 条一票否决红线
禁 unserialize()/eval()/assert()/preg_replace('/e')；禁 $_SERVER['DOCUMENT_ROOT']；渲染钩子禁 die()/exit()/header()；上传必须扩展名白名单 + bin2hex(random_bytes(16)) 随机名；库存/积分扣减必须 UPDATE ... WHERE id=:id AND stock>0 + rowCount() 检查；IN 查询 array_map('intval') + 占位符；不覆盖 PDO 的 ERRMODE_EXCEPTION/EMULATE_PREPARES=false/busy_timeout；AJAX 必带 CSRF。
为什么：违反任一即整插件判不合格——反序列化是 RCE 入口、渲染钩子中断会毁掉整页、先 SELECT 再 UPDATE 会并发超卖，每条背后都有真实事故。
3. 一目录一插件，命名空间首段逐字节等于目录名
plugins/adslot 的命名空间就必须是 Plugin\Adslot。自检：python .workbuddy-ai/tools/plugin_case_lint.py。
为什么：写成 Plugin\AdSlot 时 camelToSnake('AdSlot')=ad_slot ≠ adslot，自动加载器三条候选路径全落空；Windows 大小写不敏感本机全绿，Linux/宝塔生产环境「点设置」直接 500——这是 2026-09-30 记录的生产事故。
4. 零内联：样式/JS 一律进插件自己的 assets/
禁 <style>/<script> 块、禁 onclick= 等内联属性、禁改核心 admin.css。出包前三道门禁命令之一就是 grep 零命中。
为什么：08-26 审计发现 2 个插件内联 script；更重要的是内联样式无法按页加载、无法版本化管理，还会把插件样式漏进核心。
5. 钩子以 §9.1 全表为准，触发点用「文件+锚点」定位
全表 44 个钩子（51 个调用点），含触发文件、注入参数、通信全局变量。一键核对：php .workbuddy-ai/tools/plugin_hook_audit.php。
为什么：1.2 版的钩子表只有 32 行、无触发点、参数不全，且列了死钩子；1.3 起重写为逐行核实的全表，1.6 又把行号口径改为锚点（2026-10-16 实测全篇漂移 24 处——行号会随核心改动漂，锚点不会）。
6. 双触发钩子：钩子文件顶部禁声明函数/类
nav_plugin_links（PC 左栏 + 顶栏下拉）、route_before_dispatch（index.php 带 $router + Router.php:93 不带）、nav_user_menu_items、sidebar_above_friend_links、home_sidebar_bottom、announcements_display 都会在一次请求里触发多次。核心按钩子文件是否声明顶层符号决定 include 还是 include_once。
为什么：一旦声明函数/类，第二次触发被降级为 include_once，第二处入口静默消失（无报错、无日志，只是前端少个链接），且单次 CLI 测试完全测不出来。
7. 渲染钩子里 $this 不可用
钩子运行在独立 closure 作用域，$this->e() 会抛 "Using $this when not in object context" 并被 try/catch 吞掉——表现为 HTML 渲染一半断掉、HTTP 仍 200。
为什么：钩子机制把 $params extract() 进闭包再 include，插件之间不共享局部变量；需要视图能力时改用核心注入的 $GLOBALS['__view']。
8. 插件数据归插件：独立 SQLite，读核心必须经 Model
自有表放 data/{插件名}.sqlite（Plugin::db() 自动创建并写 .htaccess/web.config 防 Web 下载）；禁止直查核心库 threads/posts/blogs/users——SplitDB 迁移后 threads 表和 posts 表已是 0 行退役表。
为什么：content_review 直查退役表做审核软删，功能实际失效（帖子该看的看不到）；seo 直查导致 SEO 描述长期为空——都是审计记录在案的功能性缺陷。
9. 核心库访问边界（2026-09 双模型交叉裁决）
禁直写核心 users/积分表：用户组变更走 User::updateGroupId()、积分增减走 Points::deduct()/award()；删核心表记录走 Model 封装；批量补用户名走 User::batchGetNames()/batchGetUsers()；Model 的 update() 受 $fillable 白名单约束，请求数组不能原样传入。
为什么：mod_system 直写 group_id、red_packet 直写 points 均被审计标记；直写绕过积分等级联动与缓存刷新，会产生数据不一致。
10. 插件间禁止直耦
跨插件联动只能经核心钩子事件（如 points_award_after）或核心服务（Points/Settings），禁止调其他插件的 Plugin::db() 或写其数据表。
为什么：points_mall 曾直接 \Plugin\Medal\Plugin::grant()，被二轮审计判红线级漏报，后改为 Plugin::hook('points_mall_medal_redeem') 事件解耦。
11. 性能红线：单插件每请求查询 ≤5 次
核心没有 Plugin::budget()——预算是插件自实现的进程内计数器；重逻辑走 Queue::push() 异步或独立页面，禁止在 layout_head_end/controller_view_before 做重查询；曝光/浏览类统计禁止每请求写库（渲染期内存计数，响应后一条批量 UPDATE）。
为什么：渲染钩子在每个页面都会触发，一处重查询会被放大成全站性能问题；预算条款来自性能审计的量化结论。
12. permissions 强制声明（2026-09 起默认强制）
写全局设置要 "system:settings"、注册后台路由要 "route:admin"、外部 HTTP 要 "net:fetch"；未声明在强制模式下直接 DENY（不执行 + error_log），不再"警告放行"。
为什么：seo 插件 activate() 写全局设置却缺声明，在强制模式下被拒——权限模型从软约束改硬约束后，老插件必须补声明。
13. i18n：语言包键名规范 + 缺键不白屏
键名统一 plugin.{插件名}.{语义}，至少提供 zh.php，en.php/zh_tw.php 建议同步；读取用 $this->t()，缺 key 回退 key 本身。
为什么：语言包自动合并（I18n::mergePluginLangs()，核心键优先）无需钩子；曾因缺 please_select 键，下拉框直接显示键名原文。
14. 改 hooks 后必须重建插件缓存
删 plugins/plugins_cache.json 让系统重建，或调 \app\Helpers\Plugin::refresh()。
为什么：mod_system 的 plugin.json 里 11 处 hooks 路径用了反斜杠，且 plugins_cache.json 同步缓存了错误格式——Linux 上钩子文件全部找不到、插件静默失效，这是 08-26 审计的 P0 案例。
15. 事务：原生 PDO 方法 + 回滚前判 inTransaction() + AJAX 异常必须消化成 JSON
事务用 beginTransaction()/commit()/rollBack()（没有 begin()）；catch 里无条件 rollBack() 会二次抛异常逃逸成 HTML 500 页，前端 res.json() 解析失败用户看到 network_err。
为什么：这条是 medal 插件实测踩过的坑——错误链是「异常逃逸 → 500 HTML → AJAX 解析失败 → 文案错乱」，排查成本极高，所以规范给了标准 try/catch 模板。
16. 编码与提交卫生
UTF-8 无 BOM + LF；消息串里全角标点紧跟 $var 会被 PHP 当成变量名一部分导致静默空值，一律写 {$var}；投稿包每个文件路径必须以 plugins/<name>/ 开头、排除 data/、不带根级文件。
为什么：全角标点事故在探针里表现为"成片假 FAIL"把真因埋掉；投稿包结构错误会被 /plughub/submit 预检打回（bad_struct/missing_file/bad_name/too_big 等错误码）。
四、版本演化
字符量为原始文档的实际字符数。日期以文档版本头 / 归档时间为准；两轮审计（08-26~08-27）本身不是规范版本，但它们是 v1.0 的验收依据，且直接催生了后续整改，故列为第一行。
| 版本 | 日期 | 字符量 | 关键变化 |
|---|---|---|---|
| 08-26~08-27 | 两份审计报告（验收与整改） | 14087 / 30372 | 对 23 个插件做规范符合性审计：7 个不合格、约 90 条问题（真问题约 62 条、误报 10 条、二轮补漏 16 项）。P0（5 项）/P1（11 项）/P2（12 项）问题于 08-27 全部整改清零（icon_generator 按用户决定跳过）。审计同时暴露了规范本身的若干缺陷（见第五节） |
| 08-30 | v1.0 初版（文件头 2026-08-26，归档时已含 08-29 落点） | 30217 | 规范成文：三条安全铁律 + 8 条一票否决红线 + 目录结构 / plugin.json / Plugin.php / 控制器 / 视图 / assets / lang / 钩子 / 独立库 / 常见坑 / 开发流程共 13 章。此时钩子清单为 32 行、无触发点、参数不全；§7.3 已含"2026-08-29 内联审计落地"内容 |
| 09-12 | v1.2 第二版 | 36578 | 新增：§6.4 前台 UI 一致性（图标/间距/容器/导航）、§11.8 核心库访问边界（2026-09 双模型交叉裁决）、§11.9 htmx 继承属性污染、§11.10 后台 Tab 标准、§11.11 配置合并禁 array_merge。钩子表扩表中但仍有错（死钩子 nav_pc_user_links 在列、"图标统一 14px"错误约定、强制引用不存在的 cli/_verify_plugin_hook_reinclude.php） |
| 09-20 | v1.3（无独立留档，摘要并入后续版本文件头） | — | §9 完全重写：按 app/ 实际代码逐行核实，扩为 40 个钩子全表（触发文件:行号 + 完整参数 + 通信全局变量表），脚本双向比对代码 vs 文档零差集；新增 §9.3 nav_plugin_links 双触发、§9.2 死钩子标注；订正 14px 错误约定、CACHE_VERSION 改站点版本派生、替换不存在的验证脚本 |
| 10-02 | v1.4 第三版（文件头 2026-09-30） | 73980 | 因 adslot 广告位插件落地集中暴露新坑而大增：§11.12~11.28 共 17 个新小节（生命周期类名推导、budget 进程内计数器、fullKey() 幂等、建表兜底两路、两套等级体系混淆、admin_route_register 禁写 /admin 前缀、无 $_SESSION['user_points']、渲染钩子 $this 不可用、核心没有 Plugin::budget()、右栏用户栏钩子容器契约、htmx 回包禁带 <link>/<script>、登录态失效回跳用 Auth::loginUrl()、Upload::file() 返回裸相对路径、外链中转页契约、曝光统计禁每请求写库、设置保存字段缺失被静默写成最小值、CSP img-src 不含 blob:、命名空间首段逐字节等于目录名）；新增 §12.1 验证手法 5 条；§9.1 扩为 43 钩子（layout_body_end 编号 #43）；参考实现补 adslot |
| 10-03 | v1.5（无独立留档，仅存 CHANGELOG 摘要） | — | 新增 §11.35「前台投稿包打包规范」：包结构硬约束（plugins/<name>/ 单根、必备两文件、禁根级文件、排除 data/）+ 表单字段约束表 + 三条发布路径边界 + 出包/自检两条命令；§6.4 补第 4 条「图标一致性」（icon 必须在 TemplateCompiler::$map，否则商店显示问号）；§12 拆分「打投稿包」子步骤并接入 skill 脚本 |
| 10-18 | v1.6 最终版（变更摘要 2026-10-16，10-18 定稿归档） | 88243 | 口径校正 + 内容补齐 + 去重：category 白名单校正为核心/商店共 10 类（system/security/admin 等值不存在）；§三 补 min_core（缺省兜底 1.1.2）/sort_order（支持负数）/changelog 三个实用字段；§9.1 补 3 个 upload_* 钩子（新增 I 组，upload_url 每页几十次必须零 DB 查询），钩子数统一口径为 44 个核心触发 / 51 个调用点；触发点口径改「文件+锚点」并校正全篇 24 处行号漂移；新增 §11.36（自建上传落盘两个静默失败）；§11.29 补 upload_after 的 filename 键；§12.1 增至 6 条、§12.2 增至 7 项；去重（§11.3 第 22 条抽为 §11.3b、§6.4 字号表成为唯一权威表） |
演化脉络一句话总结：v1.0 立骨（安全红线 + 基本结构）→ v1.2 长肉（UI 一致性 + 核心库边界）→ v1.3/1.4 由一次 adslot 落地把钩子体系核实到零差集、把常见坑从十几条扩到三十多条 → v1.5/1.6 补上发布链路（投稿包、图标、分类口径）并做全书口径校正与去重。增长的 5.8 万字符里，绝大部分是"用事故换来的坑位"。
五、规范审计发现的问题与整改
两份审计报告的对象虽是插件，但复核过程中也暴露了规范本身的问题。下表只收录"规范自身的问题 → 整改 → 现状"，插件代码问题不在此表。
| # | 规范的问题 | 发现依据 | 整改 | 现状 |
|---|---|---|---|---|
| 1 | §9.4/§12 强制要求的验证脚本 cli/_verify_plugin_hook_reinclude.php 在仓库中不存在，规范引用了空气 | 二轮报告 §3.8/§十二 | v1.3 替换为可执行手法：grep 静态普查 + php -r 'include $f; include $f;' 独立进程双 include（PHP 8 下 Cannot redeclare 是 E_COMPILE_ERROR，try/catch 拦不住，必须独立进程） | 已修正，最终版 §9.4 ③ / §12 均为可执行命令 |
| 2 | v1.2 版"导航图标统一 14px"是错误约定（nav_plugin_links 实测 16px，14px 只属 nav_user_menu_items） | 二轮报告 §3.8 | v1.3 订正并分钩子给出字号；v1.6 把 §6.4 字号表补全为唯一权威表（另含 nav_main_links 16px、nav_drawer_links 15px、右栏用户栏钩子 12px） | 已修正，附"拿不准先 grep 同钩子现有实现"的兜底指引 |
| 3 | v1.2 钩子表信息量不足：32 行、无触发点、参数不全，还列入死钩子 nav_pc_user_links（核心从不触发） | 一轮报告 §十 / CHANGELOG 1.3 | v1.3 按 app/ 代码逐行核实重写为 40 钩子全表（文件:行号 + 参数 + 全局变量），双向比对零差集；§9.2 标注废弃钩子；v1.6 补 upload_* 后统一为 44/51 口径 | 已修正，并新增自检工具 plugin_hook_audit.php 防再次腐化 |
| 4 | 规范表述含糊把"建议"当"硬性要求"，引发误报：如"字面量写法"建议被用于判定 ai_assistant 用 self::NAME 常量违规；"资源文件缺失"误判 quiz_duel | 二轮报告 §5.4 / F6 / F8 | 二轮报告逐条标注 ❌ 误报并说明规范无此要求；规范后续措辞区分"必须/建议/禁止" | 已澄清（常量写法规范未禁止，仅为风格差异） |
| 5 | §10.1 独立库条款对只读型 / 仓库型插件缺例外：seo 经 Settings 读写核心 settings、code_repo 数据在文件系统，被机械判"违规" | 二轮报告 §5.2 / P2-8/9 | 规范补坑注"核心库只读访问保留给 seo 等只读插件"；两插件在类声明加规范豁免注释（code_repo 未删 data/repos 内用户数据，待用户决定） | 例外已入规范；code_repo data/repos 冗余副本清理仍挂起 |
| 6 | §八"至少提供 zh.php"对纯钩子型插件边界不清（edit_info 无自有页面/文案，被判违规） | 二轮报告 §8.2 / L6 | edit_info 补 lang/zh.php+en.php+zh_tw.php（纯钩子插件无自有文案，展示复用核心键并附说明注释） | 已整改；规范对"钩子型插件豁免"的表述仍靠注释兜底 |
| 7 | 行号口径不可维护：规范引用具体行号，核心一改就漂移（2026-10-16 实测全篇漂移 24 处，index.php 一度漂了约 120 行） | 一轮/二轮报告复核 + v1.6 自测 | v1.6 触发点口径统一改为「文件 + 锚点」（行号仅参考），并给出 grep -n "Plugin::hook('<钩子名>'" <文件> 定位法 | 已修正，明确"行号会漂移、锚点不漂" |
| 8 | 规范缺卸载自检与验证手法的成文要求，问题靠审计兜底 | 一轮报告 §十一 / adslot 落地复盘 | 最终版 §十三 补"卸载自检"清单（独立库表已删、核心 settings 无残留、Plugin::getPlugin() 返回 null）；§12.1 沉淀 6 条验证手法（零内联切片、CLI 探针连接复用、curl 数组编码、全角标点贴 $var、settings_cache 不可 require、漏 use 的静态扫描） | 已成文，并各配工具（php_var_cjk_check.php、php_missing_use_check.php 等） |
六、使用建议
新插件从哪抄样例
- 首选
plugins/points_mall：规范点名的完整范例（db/ddl/ensureSchema + Model 调用 + 资源加载全流程合规）。 - 分场景参考：
plugins/medal（导航/统计钩子）、plugins/qa（标准钩子与视图转义）、plugins/task_center（多钩子协调 + 完整语言包）、plugins/adslot（前台嵌入区块 + 中长踩坑记录）。 - 审计验证过"完全合规、可直接抄"的还有
code_audit（自带审计引擎，本身就是规范活样本）。 - 反面教材同样有价值：审计报告里的
content_review（直查退役表）、mod_system（反斜杠 hooks 路径）。
去哪查钩子目录
- 权威来源：规范 §9.1 全表（44 个核心触发 / 51 个调用点，按生命周期 A~I 分组，含触发文件 + 锚点 + 注入参数 + 通信全局变量）。
- 一键核对：
php .workbuddy-ai/tools/plugin_hook_audit.php（钩子数 / 调用点数 / 与 §9.1 表双向差集）。 - 手工兜底：
grep -rn "Plugin::hook(" app/ index.php plugins/ --include=*.php。 - 注册前必读 §9.3（
nav_plugin_links双触发）与 §9.4（route_before_dispatch双触发），以及 §9.2 的废弃/陷阱钩子清单（nav_pc_user_links是死钩子，别注册）。
校验工具清单（写插件时主动跑，别等审计）
| 工具 | 查什么 | 时机 |
|---|---|---|
.workbuddy-ai/tools/plugin_hook_audit.php | 钩子表与代码双向差集 | 改钩子相关代码后 |
.workbuddy-ai/tools/plugin_case_lint.py | 命名空间与目录名逐字节匹配（Linux 500 病根） | 新增/改名插件后必跑 |
.workbuddy-ai/tools/fh_i18n_check.php | 语言键全量比对（zh/en/zh_tw 零缺失） | 涉及文案时 |
.workbuddy-ai/tools/php_var_cjk_check.php | 全角标点紧跟 $var 静默空值 | 交付前 |
.workbuddy-ai/tools/php_missing_use_check.php | 漏 use 的运行期 500（php -l 查不出） | 交付前 |
cli/release_build.php --type=plugin | 后台发布 9 项门禁（先 --dry-run） | 走后台发布时 |
build_submit_zip.py + verify_submit_zip.php | 投稿包结构预检 | 走前台投稿时 |
违反规范会有什么后果
- 现行机制是"事后审计 + 分级整改"：历史一轮审计 23 个插件查出 7 个不合格、约 90 条问题，按 P0（红线/功能失效，一周内）/P1（安全/并发/规范，两周内）/P2（规范/体验，建议）分级限期整改，08-27 全部清零；审计报告会在项目内留档（
暂存20260913/两份即在册）。 - 投稿路径有硬门禁：zip 结构不合规会被
/plughub/submit预检直接打回（bad_struct/missing_file/bad_name/too_big/closed），且投稿表单不回填，失败即丢已填内容——所以规范要求"先把verify_submit_zip.php跑绿再上传"。 - 没有覆盖"提交即拦截"的强制门禁（除上述投稿预检）：常见违规（private db()、直查退役表、硬编码 URL）不报错、只静默出错，最疼的几次都是生产事故——Linux 500（命名空间大小写）、退役表直查导致审核/seo 功能失效、缓存不同步导致钩子静默消失。
- 结论：这份规范没有"违规即失败"的自动执行机制，靠的是审计留档 + 事故复盘 + 工具自检三件套；按第六节清单主动跑工具，是成本最低的合规路径。
本篇为纯文档整理产出，未改动任何代码。规范原文与全部历史文档路径见文首 merged_from。
