故障排查与反馈

Turboism 未启动

• 确认使用的是预期的 Preview 目录和 Turboism home。
• 检查 Preview 所有或 home 所有日志目录中的 Java Agent 和 Runtime 日志。
• 确认当前 Cubism 安装符合受支持的 Preview 范围。
• 不要替换 Cubism JAR、DLL、BAT 文件或许可组件来绕过身份验证失败。

插件未出现

检查以下各项：

• 托管 JAR 安装已在重启后完成，或者手动安装的 JAR 直接位于 <turboism.home>/plugins/ 根下（不在子目录中）；
• 两次启动使用同一个 Turboism home；
• 没有同 plugin ID 的旧 JAR 残留（重复 ID 会以 DUPLICATE_PLUGIN_ID 失败）；
• JAR 中恰好有一个 META-INF/turboism/plugin.json；
• manifest 使用 schema version 2；
• entrypoint class 存在、是 public、实现 TurboismPlugin，并且有 public 无参构造函数；
• Turboism API 范围和必需依赖可以解析；
• plugin ID 未被禁用且没有重复；
• environment.requiresCubism 与当前环境匹配。

JAR 被拒绝

受管理的 JAR 可能因符号链接或非常规源、大小超过 16 MiB 上限、路径格式错误、重复条目、特殊文件、META-INF/turboism/plugin.json 缺失或重复、描述符 ID/版本/API 不一致、复制的 SDK/Runtime/Live2D 类、native 或 installer payload、嵌套 JAR、缺少 entrypoint 或存在未声明资源而被拒绝。

请从当前插件源码重新构建 JAR。不要手动编辑归档，也不要禁用检查。上述原因描述的是托管 preflight；手动复制会跳过它，只有启动验证强制执行的违规才会出现在 Runtime 启动诊断中。

操作一直处于 pending

插件安装、替换、启用、禁用和卸载操作会在 Cubism 重启后生效。

• 确认 Cubism 已完全退出并重新启动。
• 确认两次启动使用的是同一个 turboism.home。
• 检查 Runtime 状态和日志。
• Turboism 运行时不要编辑 plugin、config 和 pending-state 文件。

宿主 capability 不可用

这通常是有意的 fail-closed 结果，原因可能包括宿主版本、Cubism 文件身份、mapping 验证、Provider 可用性、安全模式或过时的对象 generation。

记录确切的 Cubism 版本、Cubism 文件身份、操作和 diagnostic code。不要通过反射或直接宿主访问绕过失败。

反馈

请通过反馈与功能需求，使用 Discord、GitHub 或电子邮件报告 Bug，或提出框架与插件功能需求。