# 大鱼工具箱：给 Agent 的脚本转换入口

此文档是公开接入合同的入口。目标：把用户提供的普通 MAXScript 或明确需求，转换成大鱼工具箱用户扩展。无需工具箱源码、官方插件工程或内部构建工具。

按你正在读取的本文件实际 URL 解析下方相对链接；本地预览与正式站使用相同文件结构。

## 先读这些资料

1. [接入概览](reference/readme.md)
2. [AI 任务说明](reference/agent-task.md)
3. [普通接入：完整三个文件示例](reference/basic.md)
4. 涉及动态列表、拾取、连续编辑、后台任务或场景事务时，再读[复杂接入](reference/advanced.md)。
5. 按需查[控件与布局](reference/controls.md)、[编辑配置与安全](reference/editing.md)、[发布与排错](reference/troubleshooting.md)。
6. 精确结构和方法签名：[插件声明结构](reference/reference/plugin-schema.json)、[公开接口](reference/reference/public-api.md)、[能力清单](reference/reference/capabilities.json)。不得凭记忆编造 API。

公共声明版本为 1.0.0 / 1.1.0，目标 profile 为 author-services-v1。普通插件优先使用 1.0.0；确需共享参数等 1.1.0 特性才使用对应版本。实际能力以用户安装的框架为准。

## 转换步骤

1. 先盘点原脚本的参数、单位、默认值、按钮、列表、选择、单击/双击/右击、场景修改、文件操作、资源和生命周期。
2. 保留原算法与输出，把界面映射为公开字段、命令和标准控件；说明无法原样支持的差异。不使用占位代码、假按钮或静默丢失的交互。
3. 交付一个完整文件夹，至少含 plugin.json、placement.json、main.ms。模块与依赖用相对路径声明，列出额外文件和目标版本。
4. plugin_id 全局唯一并在更新时保持稳定，不使用官方保留前缀 dayu.* / cn.dayu.*。字段、控件、命令和导出名称是不同的稳定标识。
5. main.ms 的最后返回值为公开 AuthorScriptModule；加载阶段不执行场景命令、不 createDialog、不绕过框架自建宿主。
6. 对场景、文件的副作用如实声明。场景命令通常由框架单次撤销管理，不能伪装成 query。普通失败用公开失败合同；仅确实未产生副作用时使用 FailBeforeEffects，实际回滚完成后才能使用 FailAfterRollback。
7. 长度按声明的规范单位保存，调用 Max 几何 API 前转换为系统单位；数量与索引使用 integer 语义，显示精度不能代替整数约束。
8. 使用事件、计时器、异步或拾取时说明释放责任；不要给无资源的普通模块添加空生命周期。

## 用户安装和编辑

完整文件夹直接放入 Windows 实际“文档”/DAYUCG/大鱼工具箱/自定义插件/插件包/<插件文件夹>/。开发版也可在“设置 → 自定义插件”中导入完整文件夹或 ZIP、RAR、7z，具体入口以安装版本为准。压缩包导入不负责把任意 `.ms` 自动转换成扩展。默认 placement.json 为 {"category":"自定","order":10}，用户可改分类和排序。更新已加载脚本或 DLL 后重启 Max；隐藏和再显示工具箱不保证重新加载代码。

设置 → 自定义插件 → 打开布局编辑器（页内按钮）。编辑器调整已有控件顺序、分组、文字与布局，预览后保存；它不能修改字段类型、命令绑定、模块路径或生成算法。完整布局 panel-layouts.json 与区域偏好 layout-preferences.json 分开，不把布局导入当作插件安装。

精简版中，“编辑器说明”按钮与“打开布局编辑器…”同排；底部“AI 接入说明”按钮直接打开转换指南。“自定义插件”分类的 ? 打开整页管理说明。导入按钮的提示解释转换要求，“打开目录”的提示显示实际存放位置。选择导入或更新来源不会更改统一文档目录。

## 出错时的诊断要求

先按[发布与排错](reference/troubleshooting.md)区分导入、发现、首次执行、联动、更新或删除阶段，使用文末错误回传模板。保留实际错误中的位置、原因和代码，不能凭一个通用错误推断根因。核对完整 Schema 的条件约束，不只读 properties；无参数命令也要 `args: {}`。

`modules[].runtime` 使用 `maxscript` / `dotnet`，不是 net8 等宿主运行时；C# 的 factory 必须满足公开接口和构造要求。默认目录相对产品根，不重复拼接 DAYUCG/大鱼工具箱。修复后分别说明静态检查与真实宿主验证；失败业务不自动重放，不通过削弱检查、清空用户配置或猜测私有 API 解决。

## 交付给用户

- 完整文件树及每个文件的内容，或可解压的完整扩展文件夹。
- 安装位置、使用步骤、默认分类与排序、依赖及与原脚本的差异。
- 独立场景的结果、取消、撤销和单位检查方法。
- 实际运行过什么、未运行过什么。未进入 Max 时明确“未执行宿主验证”；元数据检查不等于业务通过。

脚本和 DLL 在 Max 进程中运行，不是沙箱。不要要求用户提供工具箱工程、授权密钥或私人配置。不得调用未公开的 UI/Workspace/Core 类、窗口句柄或内部 JSON。

[完整文档包](dayu-author-guide.zip) · [最小纯数值示例](simple-sum.zip)
