﻿# 发布与排错

## 导入与目录

在“设置 → 自定义插件”中导入完整插件文件夹或 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 的错误回传模板

```text
请按公开接入合同诊断我自己的用户扩展。
触发阶段：导入/重启后发现/第一次展开或点击/联动/更新/删除
Max版本与工具箱版本：
插件plugin_id、version、schema_version：
复现步骤、预期与实际结果：
完整错误文字（保留位置、原因、代码）：
是否有待重启更新、其他Max进程、外部依赖：
以下是我自己的相关声明和脚本（已移除口令、Token和私人配置）：
请说明错误原因、需要修改的自己的文件、验证方法和仍未执行的宿主检查；不要要求工具箱工程或内部工具。
```

让 AI 一次修复有证据的原因，保留版本与验证结论；不要盲目重放失败命令、降低路径检查、改成 query 隐瞒副作用，或要求用户提供授权密钥和框架内部工程。
