1. conf.json 必填字段（fatal 阻止安装，?force=1 不可跳过）
字段 | 类型 | 合法值 | 校验位置 |
|---|---|---|---|
| string | 非空字符串 |
|
| string | 两位制 X.Y（如 “1.1”），必须与当前 |
|
| string |
|
|
新增插件：以上 3 字段 + version（三位制 X.Y.Z）+ brief 必须齐全，缺失即拒绝安装。
判定标准：扫描器扫描时只检查 conf.json 字段存在性/格式/兼容性，db 异常时不回退 conf.json 的 installed/enable（这两个字段已彻底废弃）。
2. conf.json 废弃字段（禁止写入）
字段 | 原因 | 替代方案 |
|---|---|---|
| 插件唯一标识是目录名（dir）， | 用目录名作为唯一标识 |
| 运行时状态，唯一权威源是 db | db |
| 同上 | db |
存量插件 conf.json 中的这三个字段：代码层彻底不读，但新插件不应写入，存量插件清理时一并删除。
3. bbs_version 兼容性语义
核心主次版本计算：XIUNOX_VERSION 取前两段（如 1.1.0 → 1.1），通过 preg_replace('/^(\d+\.\d+)\..*/', '$1', XIUNOX_VERSION) 提取。
校验规则：插件声明的 bbs_version 必须完全等于核心主次版本（不是 ≤）。
旧规则：
version_compare($bv, $coreMajorMinor, '>')→ 只阻止"插件要求高于核心"新规则：
version_compare($bv, $coreMajorMinor, '!=')→ 必须与核心同分支绑定
理由：避免跨分支兼容性陷阱。同分支的小版本升级（1.1.0 → 1.1.9）插件无需改 bbs_version；跨分支升级（1.1 → 1.2）插件必须显式声明新兼容性。
4. type 字段决定 plugin_is_theme()
model/plugin.func.php:737 的 plugin_is_theme($dir, $conf) 判定顺序：
conf.json
type字段（最权威）：值为theme/template/skin→ 主题目录名关键词：含
theme/template/skin/风格/模板→ 主题插件
name字段关键词：含上述关键词 → 主题
db bbs_plugin.type 字段：0=插件，1=主题，由 plugin_db_init() 调用 plugin_is_theme() 写入。
新规则影响：type 必填后，判定不再依赖目录名启发式，全部以 conf.json 显式声明为准。
5. 批量修复存量插件 conf.json 的标准流程
当 conf.json 规范变更需要批量修复存量插件时：
写一次性 PHP 脚本（不要手改 40 个文件），放在工作目录根（不是
/tmp，Edit 工具无法访问/tmp）修复顺序：
先
preg_replace('/,\s*,/', ',', $raw)修复双逗号语法错误（存量插件删除installed/enable时易留,,残留）再
preg_replace('/,(\s*[\}\]])/', '$1', $cleaned)修复 trailing commajson_decode后在数组层unset($j['id'], $j['installed'], $j['enable'])（regex 因双逗号语法错误可能漏匹配行级删除，数组层最可靠）补全
bbs_version/type/authorjson_encode($j, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)写回
验证：跑
for d in plugin/*/; do php -r 'json_decode(file_get_contents($argv[1]),true) or print("INVALID\n");' $d/conf.json; done全部通过删除一次性脚本（避免污染工作目录）
已违反 1 次：regex '/^\s*"(?:installed|enable)"\s*:\s*[^,\n]+,?\s*\r?\n/m' 因 [^,\n]+ 排除逗号，遇到 "installed": 0,, 时 ,? 只匹配一个逗号，第二个逗号挡住 \s*\r?\n 导致整行不匹配，installed/enable 残留在 JSON 中。改用数组层 unset 后修复。
6. 文档同步清单
修改 conf.json 校验规则后必须同步：
docs/plugindev/02-plugin-structure.md：字段表 + 全字段示例 + 最小示例 + 故障排查表docs/plugindev/06-ai-collaboration.md：Fatal/Error 分类表docs/xiunox-plugin-dev/SKILL.md：字段类型陷阱表 + 必需/可选/废弃字段清单 + 交付检查表
PluginScanner.php 通过裸 include 加载（非 _include()），修改后立即生效，无需清 tmp 编译缓存。
