﻿# 交给 AI 的任务说明

把这份文档包与你自己的脚本或功能需求一起发送给 AI，使用下面的任务说明。

> 请按照随附的 DAYU 公共作者合同 1.0.0 / 1.1.0，把我的脚本转换为工具箱扩展，或按需求制作扩展。先阅读《普通接入》；仅在功能需要时查《复杂接入》和参考资料。保留原算法、默认值、单位、事件、列表和预览行为。列出原 UI、参数、动作、场景修改、资源及生命周期，再映射成公共字段、命令和标准控件。交付完整的 plugin.json、placement.json、main.ms；额外资源或 DLL 必须明确声明。用户只填写分类和排序，不运行官方验证或构建流程。不得索要 DAYU 工程、官方插件源码或内部工具，不得调用未公开的 UI/Workspace/Core 类、窗口句柄或私有 JSON。无法支持的功能逐项说明，不生成假按钮或把场景修改伪装成只读命令。最后给出文件清单、安装位置、实际验证步骤、未验证项目和与原脚本的差异。

## 需要我提供的信息

- 原脚本或明确的功能需求；已有 UI 可附截图。
- 目标 Max 版本，以及依赖的渲染器、第三方插件和素材。
- 分类名与排序；不了解时先生成 `{"category":"自定","order":10}`，稍后修改。
- 需要保留的默认值、单位、热键、预览和双击/右击等行为。

## AI 的交付检查

1. 文件夹可以整体放入用户扩展目录，不需要完整工程。
2. 每个按钮指向已声明且已实现的命令；清单与代码中的导出名一致。
3. 字段 ID、控件 ID、命令 ID 分开；共享输入通过字段绑定实现。
4. 场景修改与撤销如实声明。选面、选点、材质、文件操作等不以占位代码冒充完成。
5. 原列表仍是列表，预览仍是预览；单击、双击、选择、右击目标分别核对。
6. 字体、字重、圆角、颜色和 DPI 跟随框架，子插件不硬编码第二套皮肤。
7. 没有长期资源时不添加空的初始化/停止逻辑。使用计时器、订阅、异步或拾取时明确释放责任。
8. 未运行 Max 时写明“未执行宿主验证”；语法或格式检查通过不等于业务通过。

最小示例在[普通接入](basic.md)。[公共接口参考](reference/public-api.md)只有公开签名和约束，不含框架实现。

## 转换顺序与最小验收

1. **先盘点，再改造。** 列出原参数的类型、单位、默认值、持久范围；每个事件的输入、输出、副作用、取消和释放责任。已有功能不因接入困难而静默删除。
2. **先完成一个可运行闭环。** 选一个真实动作，把字段、控件、命令、模块导出接通；再接入其余动作。保留原算法，不在文件加载或初始化阶段执行原先的按钮动作。
3. **同时检查结构和引用。** 按完整 Schema（含 allOf/oneOf/条件分支）检查，核对每个 bind、command、args/args_ref、source 和布局引用。模块 runtime 与宿主 runtimes 不是一回事；无参命令仍需 args={}。
4. **按实际目标版本验收。** 导入成功只说明包结构被接受。至少验证空选区、合法输入、越界输入、取消、一次撤销和后续有效操作；涉及单位、对象引用或资源时增加相应场景，不反复重跑无关功能。
5. **更新保持身份。** 保留 plugin_id、已用字段/命令/面板 ID，明确新版本与数据兼容。脚本或 DLL 更新后重启 Max 验证；不通过清空用户配置掩盖迁移问题。
6. **交付真实记录。** 分开记录静态检查、实际 Max 业务、鼠标交互和目标版本。直接调用命令通过不等于按钮、右键、拖动等事件链已通过；未测项必须保留。

## 请 AI 如何处理错误

先读取完整错误、字段路径和错误码，定位当前阶段（导入、发现、初始化、执行、联动、更新或停止），再修正对应文件。一次只修有证据的问题；保留失败记录和已通过结果，不为消除提示而放宽校验、添加未公开接口或自动重放失败的场景命令。参考[发布与排错](troubleshooting.md)。
