入门与设置 / DAYU TOOLBOX 5.0
编辑配置与安全
了解布局编辑、配置导入导出和脚本执行边界。
编辑器分别做什么
| 入口 | 可以做 | 不应做 |
|---|---|---|
| 框架布局编辑器 | 对已有控件排序、组合行/分组/扩展、修改文字/提示/伸缩权重、保存用户布局 | 修改字段类型、命令绑定、模块路径、执行业务或生成算法 |
| 卷展中的可编辑区域 | 在作者开放的区域内排序、切换允许的列数、隐藏可选项;导入/导出区域偏好 | 隐藏必需项、跨区域执行脚本、冒充完整插件编辑器 |
| 插件工作副本编辑器 | 编辑源码和配置,核对变更,再进行独立测试/发布 | 把保存成功当成业务通过;在查看配置时执行未知脚本 |
完整布局保存为 panel-layouts.json,区域偏好为 layout-preferences.json;均与插件声明 plugin.json 分开。两种偏好格式不能混用。完整布局编辑器支持按卷展名称搜索、导入与导出;文件操作前会保留右侧尚未应用的有效属性到草稿。
导入先显示差异确认:左侧列出修改、相同和跳过的卷展,右侧查看排版、控件属性的当前值与导入后值,以及旧控件的兼容适配。切换明细只读取布局数据,不加载业务。全部相同时不能重复导入;取消确认保留当前草稿。
确认后仅修改内存草稿:按稳定卷展 ID 合并,文件未涉及的当前卷展保持不变;未安装卷展跳过,控件增删按现有版本适配。整次导入可以一步撤销,点击“保存布局”才生效;取消或关闭编辑器放弃未保存修改。导出不会保存到当前运行配置,也不能选中当前的 panel-layouts.json 绕过保存检查。
导入、保存和导出共用结构与容量检查。完整布局最多 1 MiB,区域偏好最多 256 KiB;拒绝重复属性(含转义后同名)、非法 UTF-8、未知版本、命令等非布局属性和超限文件。合并后的总布局也需满足容量限制。布局文件不是插件安装包,不能用它导入脚本或改变命令身份。
控件文字与帮助均按纯文本使用;普通悬浮提示中的 HTML 标记和实体会转义显示,不用于嵌入图片或改变样式。修改显示文字不改变实际命令与字段身份。
类型与参考布局
公共声明已有 24 种控件和 10 种字段,见控件与布局。整数是 number 的 value_kind:"integer",不是新字段类型;像素、角度、数量、长度必须按真实语义声明。资源为受控资源值,不是传入任意 Qt/.NET 对象。多行文本、只读结果、数值滑块联动、颜色+操作和分割按钮是现有控件组合,不需要再造类型。
长度按声明的 canonical_unit 保存,显示跟随框架设置;业务在使用时换算到 Max 系统单位。数字框中只显示数值,当前显示单位和步长交给框架提示。不能为节省布局把百分比、像素或数量标记为长度。
完整可运行起点见普通接入的三个文件示例;更多布局组合见控件与布局。下方共享参数仅为局部片段,不能独立安装。
为什么 UI 文件会超过 100 KB
plugin.json 同时声明字段、控件、命令参数、数据源和布局,不只是界面坐标。重复给每个命令传入整个分类的字段,会比控件本身占用更多空间。缩进和注释也占字节,但保留可读注释有维护价值。文件大小不等于常驻内存,也不能直接推断每次点击耗时。
新配置按以下顺序组织:身份与依赖、目录/数据源、字段、命令、卷展与布局。以功能为单位写注释;解释单位、默认值、联动范围和可编辑项,不重复翻译每个键。plugin.json 可用 JSONC 注释,但不允许尾逗号、重复键、表达式、宏或任意文件 include;其他用户偏好 JSON 仍按各自格式处理,不能推断所有 .json 都支持注释。
每个命令只声明它实际读取的参数。收窄旧命令前必须检查共享适配器是否仍读取其他字段;不要批量删除绑定。现有 panel_templates 适合重复面板实例,不能用来规避展开后的字段/控件限制。schema_version: "1.1.0" 支持下述 argument_sets/args_ref;1.0.0 明确不接受它们。两者均不支持 $include 或外部布局继承。
当前声明读取上限 1 MiB、JSON 深度 32、字段/控件各 512、面板 64、每命令参数 128。模板展开后仍受限制。建议文件超过 80% 或字段/控件超过 90% 时审查结构;这是维护提醒,不是任意提升运行时上限。
共享命令参数(1.1.0)
相同参数映射定义一次,多个命令引用同一组:
{
"schema_version": "1.1.0",
// 仅展示参数部分,不能直接安装;先使用普通接入的完整三文件示例。
"argument_sets": {
"dimensions": {
"width": { "field": "width" },
"height": { "field": "height" }
}
},
"commands": [
{ "id": "inspect", "export": "Inspect", "effect": "query", "args_ref": "dimensions" },
{ "id": "apply", "export": "Apply", "effect": "query", "args_ref": "dimensions" }
]
}
每条命令只能有 args 或 args_ref,不能同时声明,也没有“额外参数覆盖组”规则。少量或不同参数可继续用内联 args。最多 128 组、每组 128 参数;未使用的组也必须引用有效字段。组只共享声明,每次命令读取当前值,因此修改宽高后无需重新加载模块。业务模块收到的仍是原参数名和类型。
panel_templates 可包含同样的本地组,模板命令只引用同模板组。实例组和本地字段随实例前缀隔离,外部字段保持原 ID。模板展开后仍检查容量。不要因“共享后文件变小”就给命令传入所有分类字段;先复用重复声明,再根据业务实际读取精简参数。
以普通接入的完整示例为起点,迁移只改声明版本与重复映射,保留字段、命令、导出、布局、默认值和参数内容;比较解析结果后再替换。文件减少多少用字节统计;加载和执行性能必须实测,不能用压缩率代替性能结果。
安全边界
布局预览处理数据,不应加载业务模块、分发命令或执行表达式。框架会检查类型、引用、容量、路径和资源所有权;用户布局不能注入命令、脚本、QSS 或任意绝对坐标。保存须先校验,检查外部修改并原子写入;失败保持原文件和当前可恢复状态。
MS、C#、原生 DLL 运行在 Max 进程中,不是沙箱。 子插件运行后可能访问同一用户可访问的文件、网络和场景。能力声明是接口协商,不能限制模块绕过 SDK。哈希用于识别文件变化,不等于可信作者认证;有签名也不等于业务安全审计。
因此,不把口令、Pushplus Token 或许可私钥写入 UI 配置、参考包和诊断文本。网络提醒需要独立的用户配置与明确启用;文档链接只接受受控 HTTPS,不能因为打开布局就自动访问网络。路径必须按用途校验,包内引用禁止越界、重解析链接和不允许的扩展名;不能把该规则误用为禁止用户明确选择自己的资产目录。
UI 声明可读是设计目标。加密界面配置无法可靠保护算法,反而妨碍用户修改布局;有价值算法放在独立 C#/原生模块中可以提高分析成本,但不能承诺无法破解。加载未知插件前仍需确认来源。
证据与操作一致性
类型/schema、语义解析、原生预览、Max 实际业务、人工视觉分别记录,不用“解析通过”代替其他验收。列表保持左键选择、Ctrl/Shift 多选、双击明确动作、右键菜单、中键/滚轮滚动;有详情时悬停展示、中键短按固定。仅打开的卷展参与场景双向同步,关闭应释放订阅。
非法选择、过期对象、菜单取消或一次失败不能锁死后续操作。恢复界面不重放失败业务命令;确有部分修改时说明事实和可执行恢复入口,不能用含糊的“状态需同步”阻止下一次操作。
提示与详情的统一规则
侦听器消息同步默认关闭,可由用户在设置中明确开启。关闭侦听器同步不关闭胶囊、消息历史和诊断记录。
胶囊正文第一行写“结果+下一步”,后续行补充对象、数量、原因和路径。框架只将首行作为胶囊摘要;空间不足时显示“点击详情”。悬停查看完整消息,点击查看历史,复制保留原文。不要为排版截断底层错误或丢掉诊断上下文。动态 help_bind 可以引用最多 4096 字符的多行文本;按钮标题仍须保持简短。
列表、图库、复制槽的详情窗负责当前项的说明。详情显示期间,禁止同一来源控件再叠加普通工具提示;短按中键固定后,其他控件的提示仍可使用。普通业务结果使用胶囊,文件选择、输入和确有后果的确认才使用相应对话框;不要为普通成功消息弹模态窗口。
C# 核心负责无宿主对象的计算和可独立验证的状态整理;MS 负责 Max API、场景修改、撤销和视口恢复。不得把 Max 对象直接放到后台线程。对外接口保留稳定名称;内部保护构建与功能正确性分开验收。