﻿# 复杂接入：仍使用同一个公共合同

复杂功能不需要框架项目或官方插件源码，也不使用另一套插件格式。在基础三文件上增加声明的资源、模块或公共服务；只引入实际需要的能力。

精确字段结构见[插件声明结构](reference/plugin-schema.json)，类型、参数和返回值见[公共接口](reference/public-api.md)，可请求的服务见[公共能力](reference/capabilities.json)。不得通过猜测方法名调用私有实现。

| 功能 | 接入方式 | 必须保留的语义 |
| --- | --- | --- |
| 参数改变后自动联动 | 字段 `change_command`，返回 typed 字段更新 | 一次结果统一验证，多处控件共享同一字段 |
| 拖动数值、曲线、颜色并实时预览 | 字段 `edit_command`，与 change_command 二选一 | 预览/提交/取消；绝对值设置，不能每帧累加；场景编辑只有一次撤销 |
| 展开卷展时刷新内容 | 面板 `prepare_command` | 同步只读准备；不要在展开查询中修改场景 |
| 列表、表格、树和预览图库 | 声明数据来源；用 `SetSource` 发布带稳定 ID 的快照 | 选择与右击目标分开；排序、过滤、分页后仍按 ID 对应 |
| 多个动态参数组 | 模板和实例状态 | 有界实例数量，字段身份稳定，删除时清理所属状态 |
| 操作选择和场景对象 | 请求已实现的宿主服务，声明实际场景效果与撤销方式 | 对象存活、场景代次、取消与失败，不能以 query 隐瞒修改 |
| 选点、选对象、材质或贴图 | 公共宿主交互服务 | 使用当前会话的引用；完成、取消、关闭均释放资源 |
| 后台任务与进度 | 公共异步命令服务 | 后台不访问 Max/UI；回到拥有者线程提交，过期结果不能覆盖新状态 |
| 持久参数与配置升级 | 声明持久范围及状态版本，按需增加迁移 | 用户配置不清空；临时对象句柄/材质引用不能当作重启后身份 |
| 计时器与订阅 | 公共 timer、事件及生命周期服务 | 所有者关闭时释放；失败停止须保留可重试状态 |
| 图片和外部文件 | 声明资源，使用受约束资源/文件服务 | 不写入安装目录；不把任意绝对文件地址伪装成资源 URI |

## 初始化与停止

需要服务时，在模块 `Initializing` 事件获取 `args.Environment.Services`，按公共能力名称和版本获取已声明服务。`Stopping` 负责释放作者持有的资源。基础模块无需为了形式完整而添加空回调。

服务不存在时明确报错或使用文档允许的可选回退，不使用反射去找框架私有实现。场景修改只发生在拥有者线程。Stop 不等于在当前 Max 进程中卸载 CLR DLL；更新 DLL 后重启 Max。

MS 事件处理中捕获错误后，用 `args.Fail "script_error" (getCurrentException())` 返回失败；不要用 `Message` 或 `Success` 代替失败。失败会丢弃本次尚未提交的字段/数据源输出，并保留具体错误供界面和侦听器查看。初始化失败也使用对应事件参数的 `Fail`。

## 数据与 UI

字段定义业务值，控件只是该值的视图。每次结果只能选择简化 `args.Set*` 方式或完整 `AuthorResultBuilder` / `args.Result` 方式之一。动态数据源及选择应在同一次结果中保持一致。

`number` 的规范单位和显示单位分开；`color` 是界面 RGB，不等于场景线性色。`color4` 保留 HDR/透明度。持久值范围为 view/user/scene/transient；会话资源 token 和宿主引用不得跨重启保存。

命令的 `async: true` 只支持实现 `IAuthorAsyncModule` 的 `dotnet` 模块，不能直接给 MAXScript 命令加 async。`PrepareCommand` 与 `CompleteCommand` 在拥有者 GUI 线程执行，worker 只处理纯数据，不访问 Max、MAXScript 或 Qt 对象。同步命令只能使用 `concurrency: "reject"`；`replace` 仅用于异步 query；`queue` 必须声明 1–32 的 `queue_limit`。场景撤销不跨 worker 阶段。

`change_command` 必须指向已声明的同步命令，其 `args` 或 `args_ref` 必须包含本字段映射。回调按映射后的参数名读取候选值，不会自动收到全部字段；结果验证通过后统一提交。`edit_command` 同样须接收本字段，仅支持 number/curve/color4 的同步 query/scene 命令，与 `change_command` 互斥。

## MS 与 C#

托管模块的 `entry` 为包内 DLL 相对路径，`factory` 为实现 `IAuthorModule` 的公开非抽象类型全名，并须有公开无参构造函数。仅实现接口但未声明可实例化的 factory 不足以加载。

普通转换优先保留用户自己的 MS 算法。确实使用 C# 时，实现公开 `IAuthorModule`，并选择安装版本兼容的目标运行时。只引用公开接口，不引用 UI、Workspace 或内部加载器实现；不将框架/Qt DLL 复制进用户插件目录。

Max 2024–2027 的运行时和 Qt 并非完全相同。不能把某一版编译的 DLL 重命名后宣称通用；框架负责宿主适配，作者仍须声明和验证自身业务依赖的 Max 功能范围。

普通 MS 模块使用同一套公共声明，无需为 Qt 单独开发。C# 模块的 `modules[].runtime` 写 `dotnet`，MS 写 `maxscript`。宿主兼容范围使用 `host_targets[].runtimes` 的 `net48`、`net8`、`net10`：分别对应 Max 2024、2025–2026、2027。它只是兼容声明，不会自动切换 DLL；按当前合同提供匹配的程序集/包，不在清单中发明按版本自动选择入口。不要把依赖随意装进 Max 主目录。

### 关键规则编译与升级（2026-10-26）

需要保护或独立维护的任务调度、文件命名、持久化、校验、图像处理等规则，可放入作者自己的 C# 业务程序集；MAXScript 保留 Max API 适配。不要把原脚本文本嵌入 DLL 后再执行，并把它称为算法原生化。只有测量确认的性能热点或 SDK 能力才进一步评估 C++，不因此另建 UI 或使用框架私有类。

编译和混淆只能提高逆向成本，不等于加密或“无法破解”。混淆须保留公共合同、脚本直接调用入口、反射和序列化身份；状态文件字段及稳定命令 ID 不得随内部重命名变化。更新配套 DLL、依赖、脚本桥接和资源清单，明确版本及数据升级办法；已加载程序集须退出宿主后替换，不把重新打开卷展当成 DLL 热更新。

发布只包含明确声明的运行文件与第三方许可，不携带 PDB、测试程序集、缓存、私钥或 Token。凭据使用单独的受保护存储，不写入普通插件配置、任务文件、导出或错误日志。保护构建后的加载、执行、数据重读、失败恢复仍需专项验收；不能只验证未混淆版本。

### 可继续的文件任务（2026-10-26）

长任务先定义可重复执行的最小单位，并分别记录待执行、运行、成功、失败、停用和后处理状态。任务级继续只跳过已核验完整的结果；当前图片中断后整张重新渲染，不用“断点续渲”暗示恢复渲染器采样。恢复或打开卷展不自动重放失败命令。

保存稳定场景身份及源文件版本，重新开始前核验；不要把只在当前会话有效的临时引用写入恢复文件。输出使用暂存、完整性检查和原子替换；普通取消与移除任务不删除已完成成图或用户场景。默认目录通过公共 `directories` 声明，已开始的任务固定输出目录/策略，不能半途把结果分散到新位置。

后台可调度文件和外部进程，不能调用 Max 场景 API。切换场景的任务应隔离于用户当前场景，进程控制必须同时核验自有进程 ID 与启动身份；不能按名字结束所有 Max。保存、发布等临界阶段须有明确取消和恢复边界。操作失败、过期选择、队列进程退出后应有停止/重试入口，不留下永久忙状态；场景与输出恢复未经确认时如实说明。

主动任务可在卷展收起后继续，被动列表同步仍遵守下方可见性规则。列表提供明确的暂停、停止、跳过与重试含义；通知、自动保存与关机等扩展默认关闭，关机仅本次启用且可取消。测试通知必须显式触发，不用真实通知或关机作为普通自动检查。

## 有原生资源或撤销逻辑的迁移

动态生成的预览图片可请求 `resources.publish@1`，将图片字节交给 `IAuthorResourcePublisher.PublishBytes`，保存返回的租约并把 `Uri` 绑定到图片字段。替换图片或停止模块时释放旧租约；需要缩略图时另请求 `thumbnails@1`。不把用户文件的任意绝对路径直接作为界面资源。

`resources.files@1` 用于按需读取已有文件：通过 `IAuthorFileResourcePublisher.RegisterFile(absolutePath)` 注册经校验的普通文件，持有返回的 `IAuthorFileResourceLease`，用其 `Uri` 绑定界面。注册不等于已读取完整字节，首次资源需求时读取并缓存。当前单文件须为 1 字节至 4 MiB，最多 16384 项注册；在拥有者线程释放租约会撤销 URI，不删除原文件。文件更新后注册新 URI，不跨资源代次或重启复用旧 URI。这个接口允许外部绝对文件路径，与清单中模块 entry 的包内相对路径规则不同。

变换锁通过 `host.transforms@1` 的 `IAuthorTransformLocks.SetLocked` 设置，传入当前场景和有效对象引用，且必须处于声明为 `scene` 的命令中。

默认场景命令继续用 `undo: "single"`，由框架管理一次撤销；业务不要再次 Begin/Accept/Cancel 同一个外层撤销。原算法完整管理原生撤销、启动由 Max 接管的原生创建工具，或执行会重置撤销历史的场景合并时，声明 `undo: "module"` 并请求 `scene.module-undo@1`。命令入口同步返回；原生工具之后的用户交互由 Max 管理，不能把外层框架撤销一直留到用户完成。不要为了通过校验把修改场景的命令标为只读。

2026-10-24 起，执行事件参数提供 `args.FailBeforeEffects "code" "说明"` 和 `args.FailAfterRollback "code" "说明"`。前者仅用于确认尚未改变场景的前置检查；后者仅用于模块确实完成自有回滚后。普通未知异常仍用 `args.Fail`。不能把整个 catch 一律标为安全失败；框架还会检查撤销边界是否干净。

普通拒绝不锁住下一步。真正未知的效果仍如实报告失败，框架先停止本功能的资源，再按当前场景重建会话并保留已提交参数；不会自动重放失败命令，也不会声称现场已回滚。关闭再打开卷展栏会触发恢复重试。其他分类不继承此功能的错误状态；若 Max 仍持有外部原生操作，先结束该操作，框架不能擅自取消它。接入验收须包含“失败后执行有效操作、跨分类继续、关闭重开恢复”，而非只检查成功路径。

## 交给 AI 的复杂功能验收要求

### 可见期间的被动同步（2026-10-25）

选区联动、相机列表和目录自动刷新等被动同步，声明 `lifecycle.visibility@1`。MAXScript 模块在 `Initializing` 中调用 `sender.WatchPanel e.Environment "所属面板ID"`，预先绑定 `PanelChanged` 事件。用 `e.Kind.ToString()` 判断 `Shown` / `Hidden` / `Closed`，不要使用 `as string` 比较 .NET 枚举。只有 `Shown` 启动同步；隐藏、折叠、切换分类或关闭工具条时停止并释放计时器，重新显示时补齐当前状态。停止模块时必须清理资源。多个相关面板共用一个计时器，并统计实际可见面板，不能由其中一个面板关闭就停止另一个仍可见面板所需的同步。

手动发起的渲染或文件处理任务不属于被动同步，不因切换分类被自动取消。更新列表应保留稳定 ID，选区变化不要重复生成全部行。动态下拉框最多128项，安装组件较多时先筛选再发布；显示中文名称，保存和执行使用稳定 Class ID。完整脚本加载、实际事件和后续有效操作均需验证，不能只验证抽取的算法函数。

必须列出选择、单击、双击、右击、拖动、滚轮、取消、场景切换及关闭的实际行为；不以“控件名字相似”代替语义转换。原算法不支持的功能、公共接口缺口和未运行的宿主检查分别列明。没有实现的动作不生成成功提示或空按钮。

数据源若需要保留资源编号或修改器栈的原顺序，可声明 `preserve_order: true` 并省略 `sort_field`。此时筛选、翻页保持发布顺序；显式排序字段优先。快照中的 ID 仍须稳定，不能用行号替代资源身份。

标准图库由框架提供翻页：滚轮或中键拖动逐行浏览；右击编号、空槽或间隙可临时输入页码，回车跳转，Esc取消，每页六项。图片正文的右击仍执行你声明的辅助动作。无需自行添加页码输入或上一页／下一页按键，也无需实现跳页命令。

MS 创建无图片的列表项时，使用 `AuthorSourceItem` 的两个字符串参数构造函数；需要详情和角标时使用公开静态方法 `WithoutResource(id, label, details, badge)`。不要把 `undefined` 作为 .NET 构造函数的资源 URI 参数传入。
