XIUNOX 插件 conf.json 规范规则 [Copy Link]

1. conf.json 必填字段（fatal 阻止安装，?force=1 不可跳过）

字段	类型	合法值	校验位置
name	string	非空字符串	PluginScanner 分类 conf_required_fields
bbs_version	string	两位制 X.Y（如 “1.1”），必须与当前 XIUNOX_VERSION 前两段完全一致（version_compare($bv, $coreMajorMinor, '!=')）	PluginScanner 分类 conf_version
type	string	"plugin" 或 "theme"（template/skin 视为 theme 别名）	PluginScanner 分类 conf_required_fields

新增插件：以上 3 字段 + version（三位制 X.Y.Z）+ brief 必须齐全，缺失即拒绝安装。

判定标准：扫描器扫描时只检查 conf.json 字段存在性/格式/兼容性，db 异常时不回退 conf.json 的 installed/enable（这两个字段已彻底废弃）。

---

2. conf.json 废弃字段（禁止写入）

字段	原因	替代方案
id	插件唯一标识是目录名（dir），bbs_plugin 表主键是 dir，所有 plugin_* 函数以 $dir 为参数。引入 id 会带来"dir 与 id 谁是权威"的歧义	用目录名作为唯一标识
installed	运行时状态，唯一权威源是 db bbs_plugin 表。代码层 plugin_init() 在 xn_json_decode(conf.json) 后立即 unset 丢弃	db bbs_plugin.installed 字段
enable	同上	db bbs_plugin.enable 字段

存量插件 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) 判定顺序：

1. conf.json type 字段（最权威）：值为 theme/template/skin → 主题

2. 目录名关键词：含 theme/template/skin/风格/模板 → 主题

3. 插件 name 字段关键词：含上述关键词 → 主题

db bbs_plugin.type 字段：0=插件，1=主题，由 plugin_db_init() 调用 plugin_is_theme() 写入。

新规则影响：type 必填后，判定不再依赖目录名启发式，全部以 conf.json 显式声明为准。

---

5. 批量修复存量插件 conf.json 的标准流程

当 conf.json 规范变更需要批量修复存量插件时：

1. 写一次性 PHP 脚本（不要手改 40 个文件），放在工作目录根（不是 /tmp，Edit 工具无法访问 /tmp）

2. 修复顺序：

   • 先 preg_replace('/,\s*,/', ',', $raw) 修复双逗号语法错误（存量插件删除 installed/enable 时易留 ,, 残留）

   • 再 preg_replace('/,(\s*[\}\]])/', '$1', $cleaned) 修复 trailing comma

   • json_decode 后在数组层 unset($j['id'], $j['installed'], $j['enable'])（regex 因双逗号语法错误可能漏匹配行级删除，数组层最可靠）

   • 补全 bbs_version/type/author

   • json_encode($j, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) 写回

3. 验证：跑 for d in plugin/*/; do php -r 'json_decode(file_get_contents($argv[1]),true) or print("INVALID\n");' $d/conf.json; done 全部通过

4. 删除一次性脚本（避免污染工作目录）

已违反 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 编译缓存。