入门与设置 / DAYU TOOLBOX 5.0
发布与排错
检查文件放置、插件识别、更新、依赖和执行错误。
导入与目录
在“设置 → 自定义插件”中导入完整插件文件夹或 ZIP、RAR、7z。导入的是按合同准备好的扩展包,不会自动把任意 .ms 转换成插件。开发中版本的新增入口,以实际安装版本为准。
手动放置时使用 Windows 实际“文档”下 DAYUCG/大鱼工具箱/自定义插件/插件包/<插件目录>/,该目录直接包含 plugin.json、placement.json 及其声明的模块。不要再嵌套解压目录;不要写到工具箱安装目录。新包放好后重启 Max。
导入支持 ZIP、RAR、7z 和完整文件夹。压缩包可以包含一层唯一外包装目录;手动放置时,插件目录应直接包含 plugin.json 与 placement.json。加密或分卷包请先完整解压并检查,再按文件夹导入。压缩包及解压后总量各不超过256 MiB,单文件不超过64 MiB,导入文件与目录最多4096项。
导入成功只说明该阶段的声明、路径、依赖和完整性检查通过,没有执行业务代码。首次加载、实际计算、单位、取消和撤销仍需在独立场景中检查。扩展在Max进程内运行,不是沙箱;只运行来源可信的脚本和DLL。
第三方扩展不需要官方包签名或内部构建工具;这不等于免除工具箱自身的授权要求,也不代表文件来自可信作者。
先定位错误发生阶段
出现错误时,先记下是在导入、重启后发现、第一次展开/点击、列表联动、更新还是删除时发生。保留错误中的位置、原因和代码:例如 $.commands[0].args 指向声明中第一条命令的参数,方括号中的代码用于区分错误类别;文件路径则提示需要核对的文件。只提供一个代码通常不足以定位问题。
优先复制完整消息;界面可能截断长文本,必要时同时提供诊断记录及自己相关文件。并非每种异常都有固定代码或 JSON 路径。$.commands[0] 表示第一条命令;下表反引号中的名称是已存在的错误码,带引号的中文是界面提示摘要,不能当作错误码。
导入阶段
| 错误码或提示 | 原因 | 处理方法 |
|---|---|---|
| “请选择自定义插件目录之外的来源。”;“请选择含 plugin.json 的插件包;压缩包可以包含一层外包装文件夹。” | 选择了用户扩展目录自身、其父/子目录;文件夹或归档根没有plugin.json,且不满足单一外包装目录。 | 从用户扩展根之外选择完整来源。手动放置时plugin.json直接位于插件目录;管理器导入允许归档/来源外多一层唯一文件夹。 |
| “请选择 ZIP、RAR 或 7z 压缩包。”;“无法读取压缩包:请确认文件完整、未加密,分卷包请先解压后按文件夹导入。” | 不支持的扩展名,打开/读取失败,加密、分卷或特殊条目。 | 使用完整的ZIP、RAR或7z。加密/分卷包先用自己的解压工具完整解压,检查后按文件夹导入;损坏包重新向作者获取。不要仅改后缀。 |
| “压缩包存在重复路径。”;“压缩包文件与文件夹路径冲突。” | 归档含重复大小写路径、文件目录冲突、链接、非法/保留名称或越界路径。 | 让作者用普通文件重打包,移除链接、..、绝对路径、Windows保留名称、重复路径和文件夹同名冲突。保留原失败包用于定位。 |
| “压缩包超过 256 MiB。”;“压缩包应包含 1–4096 个文件和目录。” | 包太大、条目过多、声明大小不完整、解压校验失败/超时或未完整解压。 | 移除缓存、备份和无关资源,拆分确实独立的资源交付;压缩输入与解压总量均不超过256 MiB,单文件不超过64 MiB,导入条目1–4096。损坏数据重新获取。 |
| “压缩组件缺少解压接口。” | 压缩组件不完整、无法加载或接口缺失。 | 优先尝试自己完整解压后按文件夹导入;若普通包都失败,使用完整工具箱安装包修复组件并提供实际错误。 |
| “此插件已存在,请选择它并使用“导入更新”;删除待重启的插件需先重启。”;“目标名称或旧更新记录已存在,未覆盖已有文件;请先检查恢复目录。” | 相同plugin_id已存在、目标目录/旧更新记录存在、超过128个自定义插件。 | 已有同一插件时选中它并使用导入更新。标记删除后先重启;目标或恢复记录冲突时先备份并核对原插件和更新历史,再处理明确归属。 |
发现阶段
| 错误码或提示 | 原因 | 处理方法 |
|---|---|---|
metadata_missing、metadata_capacity、module_file_missing、legacy_format_ignored |
手动放入后看不到插件;缺plugin.json/placement.json,缺声明模块,文件过大,只有旧extension.json。 | 先核对Windows实际文档位置与一层插件目录。补齐声明所需文件,main.ms路径和大小写保持一致。plugin.json上限1 MiB,placement.json上限8 KiB。新放入后重启Max。 |
invalid_utf8、invalid_json、duplicate_key、nonfinite、capacity |
非法UTF-8、JSON语法错误/尾逗号、重复键、非有限数、超过1 MiB或深度32。 | 使用UTF-8;按消息位置修复括号、引号、重复键和深度/容量。plugin.json可用JSONC注释但不允许尾逗号,placement等其他JSON不能推断同样支持注释。 |
required、unknown_property、type、unsupported_value、identifier、duplicate_id、version |
缺字段、拼错属性、类型或枚举错误、非法/重复稳定ID、版本不是三段数字。 | 严格按公开结构改自己的声明,普通接入可用1.0.0;共享argument_sets/args_ref使用1.1.0。保持身份/绑定ID稳定,版本使用如1.2.3。 |
official_identity_reserved、duplicate_plugin_id、category_identity_conflict |
使用官方保留身份,同一plugin_id被多个目录声明,类别身份冲突。 | 为新插件设置独有ID;同一插件更新保持原ID。移走重复副本后重启。官方插件通过完整安装包更新;分类冲突先调整自己的分类名。 |
path、path_escape、reparse_path、metadata_changed、module_path_changed、module_changed、library_changed、update_source_changed |
包内路径不合法、经过链接/重解析点,或发现后文件被修改。 | 模块用包内正斜杠相对路径;普通文件夹交付。完成编辑后保存所有文件并重启Max,再读取新版本;不要在扫描/加载时写文件。 |
dependency_missing、dependency_cycle、library_missing、library_cycle、library_runtime、module_extension、library_extension、library_hash、library_file_missing |
依赖未声明/循环、运行时或后缀不一致、库文件缺失或SHA256与交付字节不符。 | 把实际使用的普通库与依赖完整声明并交付;去除循环,确认.ms/.dll与runtime一致。自己库确已更新后由作者重新计算并声明其SHA256。 |
host_target_unavailable、host_target_mismatch、unsupported_capability、capability_name、duplicate_capability |
目标Max/CLR/架构不匹配,请求未知或宿主未提供的能力,能力名或重复声明不合法。 | 提供Max版本与完整工具箱版本;核对host_targets和name@major。只声明需要的公共能力;可选能力不可用时实行声明的回退。DLL按目标CLR编译;不要改声明掩盖二进制不匹配。 |
| control_property | 属性不适用于当前控件,例如给 number 设置 read_only。 | 按控件类型核对属性;只读结果用 text 字段+只读 text 控件,不能仅修改类型名称而保留不兼容绑定。 |
首次执行阶段
| 错误码或提示 | 原因 | 处理方法 |
|---|---|---|
module_result、module_factory、initialization_failed、library_load_failed |
首次展开/点击时main.ms没有返回AuthorScriptModule,DLL工厂不满足公共接口,初始化失败,或加载器先前执行失败。 | 确保main.ms最后返回公共模块实例;检查导出/事件订阅及Initializing中依赖获取。管理DLL声明正确公开无参工厂。修复后重启Max;业务不得在加载阶段运行。 |
unknown_command、command_module、argument_source、argument_ref、argument_field、export、execution_failed、invalid_result |
命令/module/export映射错误,args与args_ref用法错误或参数字段不存在,命令不提供结果。 | 对应区分命令ID、模块ID、导出名、参数名和字段ID。每命令恰有args或args_ref;无参数写args:{}。同步Executing分支结束前提供字段/数据源/消息结果或Success,失败用公开Fail合同。 |
unsupported_capability、unsupported_service |
声明服务不存在、类型错误,或场景等副作用需要宿主协调器。 | 在Initializing用Environment.Services按公开名称取服务,先Supports或按可选能力分支回退;不要保留另一模块/上次会话的服务。对场景/文件/视口如实声明effect和undo。 |
effect_undo、module_undo、unsafe_replace、async_runtime |
scene命令未用single/module撤销,MAXScript标为async,或replace用于有副作用命令。 | 按真实业务声明effect和撤销。普通MAXScript留在宿主线程;需要异步时采用公开托管异步接口,worker只处理纯数据。replace只用于query。 |
联动阶段
| 错误码或提示 | 原因 | 处理方法 |
|---|---|---|
invalid_update、read_only、field_type、field_range、field_integer、field_choice、field_selection、source_owner |
返回未知/只读字段,值类型/范围/整数不符,动态选项ID失效,其他模块更新了不属于自己的源。 | 让AI核对返回字段与声明类型/规范单位;整数返回精确整数。列表用稳定ID而非序号/显示文字;源和选中值同次有效发布,由声明拥有者更新。 |
wrong_thread、closing、generation_expired、stale_generation、stale_scene、stale_object、stale_revision |
后台触碰Max/UI;模块已关闭;场景/对象/字段/请求代次过期;旧任务结果晚到。 | 关闭/场景变化时取消旧任务并停止观察,显示后重取当前对象和字段;后台仅计算纯数据,在拥有者线程提交。重新选取有效对象再发起新的用户操作。 |
initialization_failed、capacity |
面板隐藏仍有计时器、反复重复订阅、停止清理抛错或未释放资源。 | 声明lifecycle.visibility@1并在Initializing绑定WatchPanel;Shown补齐并启动,Hidden/Closed停止被动观察,Stopping释放作者资源。多面板共用资源需统计可见面板。 |
busy、queue_full、worker_capacity、job_capacity、source_capacity、choice_capacity、list_capacity |
重复点击占用同一模块,队列/工作者/历史条目或数据源超出预算。 | 等待已有操作结束或明确取消;作者减少重复请求,释放订阅并按需分页。动态选择至多128项,continuous列表至多4096项;按错误所指数据源/队列处理。 |
resync_required、projection_failed |
状态提交/界面投影失败,或副作用/回滚结果不确定。 | 先核对场景和文件的实际变化并保留错误;按当前恢复入口关闭重开作者视图以同步界面,若提示停止清理失败则先处理保留资源。没有确认前不要再次执行同一业务。 |
更新阶段
| 错误码或提示 | 原因 | 处理方法 |
|---|---|---|
update_version、update_plugin_identity、update_source_overlap |
候选版本不高于当前、plugin_id变化或来源与安装/更新存储重叠。 | 在扩展根之外准备完整新版本目录,同一plugin_id,三段数字version递增,再对当前插件导入更新。 |
update_pending、update_process_stale、update_busy、update_revision_conflict |
已有更新/回滚等待重启,其他Max进程已激活新版本,事务占用/并发写入。 | 先查看列表状态与待重启版本;保存工作后关闭使用该扩展的Max进程并重新启动,再刷新状态。事务忙时等待拥有者结束,冲突时保留记录重新核对。 |
update_source_changed、update_copy_changed、update_snapshot_changed、update_snapshot、update_journal、update_recovery_required |
暂存中来源改变、复制后哈希不符、不可变快照或更新日志被修改/损坏、发布结果不确定。 | 停止编辑/同步候选,保留原始包、快照、日志与错误;确定来源完整后用新候选重新暂存。出现日志/恢复必需错误时先备份明确所属恢复目录并交给维护者定位。 |
update_not_managed、update_rollback_unavailable、update_revision_conflict |
没有受管更新历史、没有previous快照或旧进程试图回滚新活动版。 | 先核对管理器显示的当前/上一版本。只有存在可用上一版本时安排回滚,并重启Max生效;没有历史时向作者取得兼容完整包和恢复说明。 |
删除阶段
| 错误码或提示 | 原因 | 处理方法 |
|---|---|---|
| “此插件已标记删除,请重启 Max。”;“已标记删除。重启后移入自定义目录的 .dayu-updates 回收区;当前会话不卸载,配置与资源保留。” | 删除后仍可执行或目录仍存在;文件被当前进程锁定。 | 查看“删除待重启”,保存工作后重启Max;删除先标记,后续发现时将包及更新记录移到用户扩展根内回收区。 |
| “官方插件不能在这里删除。”;“只能删除统一目录中的自定义插件。” | 试图从设置删除官方插件或不在统一用户目录中的自定义包。 | 官方功能通过完整工具箱安装包管理;自定义包使用统一用户扩展目录并先核对身份。 |
执行和联动的边界
modules[].runtime只写maxscript/dotnet;host_targets[].runtimes使用net48/net8/net10,不是脚本语言。- 1.0.0 每条命令必须有
args,无参数也写{};1.1.0 恰选args或args_ref,共享参数才需要argument_sets。完整 Schema 的条件约束也必须检查。 Service unavailable、Service type mismatch或 Executing 未提供结果等原始异常,不一定有专属错误码。保留原文,不要编造新的代码。- 场景、对象和会话资源失效后要重新获取;不要把旧句柄保存为跨重启身份。隐藏时停止被动观察,不因此取消用户主动发起的长任务。
- 恢复界面不等于回滚场景,也不会自动重放失败业务。未知失败后先确认场景与文件实际变化,再决定后续操作。
FailBeforeEffects只用于确实未产生副作用;FailAfterRollback只用于确实完成自有回滚。普通异常用Fail,不能统一伪报为安全失败。
更新、回滚与删除
更新同一插件时保留plugin_id,提高三段数字version,从安装目录之外选择完整新版本目录。暂存后当前会话继续用原版本,重启Max后生效;原分类和排序保留。已有待重启更新或其他进程更新时,先重启再处理。快照或更新记录损坏时保留恢复文件,不要删除记录或清空个人配置。
已选中或已加载的 MAXScript 和 DLL 修改后都应重启 Max;关闭再显示工具箱不是代码热更新。“刷新状态”也不等于激活新版本。回滚仅在有可用上一版本时安排,重启生效;不会自动把用户状态文件降级到旧格式。
删除先标记待重启,当前会话不卸载;后续启动将包移入自定义目录的 .dayu-updates 回收区,配置与资源保留。遇到锁定或恢复记录异常时保留记录,不要手改更新日志或清空个人配置。官方插件不在自定义插件管理中删除。
打包与验收
只包含声明的模块、资源和所需第三方许可,移除开发缓存、备份、PDB、凭据及无关文件。不携带框架/Qt DLL 或内部安装工具。保持 plugin_id、字段与命令身份稳定;数据结构变化使用迁移,不删用户配置来“修复”。
先检查结构与引用,再在目标 Max 的独立场景验证首次加载、正常结果、非法选择、取消、撤销、失败后有效操作以及关闭资源释放。涉及更新时验证重启激活与原配置保留;涉及鼠标菜单、拾取或对话框时明确实测交互。分别记录通过、未执行和适用版本,不能用导入成功代替全部业务验收。
这份文档包只含公开接入资料与最小示例,不包含工具箱安装器、官方业务模块或运行测试工具。官方功能缺失应检查完整安装,不要求用户重建官方插件。
交给 AI 的错误回传模板
请按公开接入合同诊断我自己的用户扩展。
触发阶段:导入/重启后发现/第一次展开或点击/联动/更新/删除
Max版本与工具箱版本:
插件plugin_id、version、schema_version:
复现步骤、预期与实际结果:
完整错误文字(保留位置、原因、代码):
是否有待重启更新、其他Max进程、外部依赖:
以下是我自己的相关声明和脚本(已移除口令、Token和私人配置):
请说明错误原因、需要修改的自己的文件、验证方法和仍未执行的宿主检查;不要要求工具箱工程或内部工具。
让 AI 一次修复有证据的原因,保留版本与验证结论;不要盲目重放失败命令、降低路径检查、改成 query 隐瞒副作用,或要求用户提供授权密钥和框架内部工程。