#常见问题

按「你遇到的现象」组织，不是按功能模块。用上面的搜索框搜报错原文通常最快。

#插件装了但没反应

#客户端里完全看不到我的插件

先确认插件审核通过了。上传成功只代表包收下了，状态是 pending；只有审核通过的版本才会被指为最新版本，才会出现在市场和客户端里。

在开发者中心看「我的插件」，pending_count 大于 0 说明还在排队。

#游戏里有事件，但设备不动

按这个顺序排查：

GameHub 客户端在跑吗 —— 网关是 127.0.0.1:43002，客户端没开就没有网关。
联动总开关开了吗 —— 客户端「联动」页里，插件卡片外层还有一个总开关。
这个事件启用了吗 —— 每个事件可以单独开关。被禁用的事件，网关下发的 mappings 里就没有它，插件按协议不该发送。
绑了波形吗 —— 需要蓝牙反馈的事件必须选一个波形，否则事件收到了也没动作。
设备在线吗 —— 「蓝牙」页看连接状态。

#日志里一直是「暂时连不上 GameHub 网关」

客户端没启动，或网关端口不是 43002。
开了全局代理或游戏加速器。它们会拦截本机回环连接。插件应该显式绕过系统代理（.NET 里设 req.Proxy = null）；如果还是不通，临时关掉加速器验证一下。

#日志里是「网关暂无 xxx 联动配置」

这是正常的。说明客户端里还没收录你的游戏，插件正在用 manifest 里的默认 commandId 发送，功能可用。等客户端加上条目后会自动切换成用户配置的映射。

#七日杀 / DLL 类 Mod 专属

#F1 控制台里完全没有 `Loaded Mod`

十有八九 EasyAntiCheat 还开着。七日杀在 EAC 开启时会跳过所有带 DLL 的 Mod，不报错，表现就是「什么都没发生」。

用 Steam 的 Play (No EAC) 启动，或在游戏自带启动器里取消勾选 EAC。

#目录结构对不上

ModInfo.xml 和 DLL 必须在 Mods\<模组名>\ 里，不能多套一层文件夹：

✅ 7 Days To Die\Mods\YokonexSevenDays\ModInfo.xml
❌ 7 Days To Die\Mods\YokonexSevenDays\YokonexSevenDays\ModInfo.xml

#游戏更新后 Mod 失效

只用游戏公开 Mod API（不打 Harmony 补丁）的插件，大版本更新后通常还能用。真失效了就对着新版游戏重新编译一次。

如果你的插件打了 Harmony 补丁，那每次游戏更新都可能要改 —— 这也是我们建议 能从状态读出来的就别打补丁的原因。

#上传与发版

#`manifest.not_at_root`

manifest.json 必须在压缩包根目录，不能套一层文件夹。

Windows 上右键「压缩」文件夹得到的就是错的那种。正确做法：进入文件夹， 全选里面的内容再压缩。

#`zip.backslash`

ZIP 规范要求条目路径用正斜杠，但 PowerShell 的 Compress-Archive 写的是反斜杠。

换 7-Zip，或者用 System.IO.Compression.ZipArchive 手动建条目时把路径里的 \ 换成 /。参考 tools/package.ps1 的实现。

#`zip.zip_bomb`

某个文件的压缩比超过了 200:1。通常不是你在搞破坏，而是打包时带进了巨大的空白文件、重复填充的资源，或者未清理的构建中间产物。

#`missing_sha256`

上传必须带 x-content-sha256 请求头。跑一遍 node scripts/check-plugin.mjs 你的包.zip 就能拿到这个值，或者直接用 scripts/publish-plugin.mjs 发版，它会自动算。

#`sha256_mismatch`

你声明的哈希和服务端算出来的不一致 —— 文件在传输中被改了或截断了，重传即可。如果反复出现，检查中间是不是有代理在改写请求体。

#`version_not_newer`

版本号只能往上走。已经发过 1.2.0 就不能再发 1.1.0，哪怕前者被拒审了。

#`duplicate_content`

这个文件（按 SHA-256 算）已经上传过了。内容没变就不需要发新版本。

#`forbidden` / 提示 source 已被占用

source 一旦被某个开发者占用，别人永远无法向它发版。换一个 source。

如果这个 source 本来就是你的、但你换了账号，联系管理员处理 —— 转移所有权需要人工确认，这是防止插件被冒名顶替的必要成本。

#包太大传不上去（`payload_too_large`）

单次直传上限 100MB。更大的包走分片上传，或者直接用 scripts/publish-plugin.mjs，它会自动判断走哪条路。

#账号

#忘记密码

在登录页点「忘记密码」，填注册时用的邮箱，我们会发一封重置邮件过去。重置链接有有效期，用过一次就失效。

收不到就检查垃圾箱，发件域是 security.ycygame.org。

#提示「该账号连续登录失败次数过多」

这是按账号维度的限流：连续输错若干次后该账号会被临时锁定一段时间。等一会儿再试即可。

这道限制是防撞库的 —— 只按 IP 限流拦不住用代理池轮着试的攻击。

如果不是你本人在试，说明有人在拿你的用户名撞库，建议改一个更长的密码。

#事件设计

#设备动得太频繁

优先调大对应事件的冷却，而不是调低设备强度。

尸潮里「玩家受伤」每秒能触发十几次，没有冷却设备会被刷成近乎常通。参考值见网关协议 - 三道闸门。

#事件延迟很大 / 设备为几秒前的事情动作

积压了。插件必须做过期丢弃：入队时记时间戳，出队时超过 3 秒直接扔掉。

另外检查是不是在游戏线程里做了 IO —— HTTP 请求必须在后台线程，超时设短。

#带反作弊的游戏怎么采集事件

不要读内存、不要注入、不要 hook。 无畏契约的 Vanguard、逃离塔科夫的 BattlEye、三角洲行动的 ACE 都是内核级反作弊，这些操作会直接导致封号。

这类游戏只能走画面识别或音频检测：截屏固定区域判断血条/击杀提示，或者检测特征音效。延迟高、准确率一般，但不封号。

审核时会核对 adapter 字段声明的采集方式，读内存类的插件不会通过。

#平台与安全

#为什么密码不用 AES-256 加密

因为 AES 是可逆的 —— 密钥泄露就等于全站密码明文化。密码必须用单向哈希（我们用 PBKDF2-SHA256，21 万次迭代 + 每人独立盐）。

AES-256-GCM 用在真正需要读回明文的地方，比如 IM token。详见安全说明。

#客户端会不会被逆向

会。任何发到用户机器上的代码都能被逆向，这是数学事实，加密解决不了。

所以我们的目标不是「不可逆向」，而是**「逆向了也没用」**：客户端调用的 API 全部只读，没有任何写入端点。逆向者能做的最大伤害是多刷几次下载计数。

#插件包会被扫描恶意代码吗

目前是人工审核 + 可执行文件清单：上传时系统会列出包里所有 .exe/.dll/.bat/.ps1/.jar，交审核员逐个确认。

不自动拦截 —— 游戏 Mod 本来就要带 DLL，一刀切等于禁掉整个生态。审核员会结合你提供的源码和构建脚本判断，所以附上源码能显著加快审核。