﻿# 普通接入：一个文件夹、三个文件

适用于普通按钮、参数编辑和同步计算。已有复杂业务仍需保留原算法，不应替换成下面的演示计算。

```text
Windows 文档/
  DAYUCG/大鱼工具箱/自定义插件/插件包/
    我的插件/
      plugin.json       插件身份、参数、控件和命令
      placement.json    用户选择的分类与排序
      main.ms           作者实现的功能
```

Windows“文档”可能被系统或 OneDrive 重定向，以系统的实际“文档”文件夹为准。插件目录应直接放在 `自定义插件/插件包` 下。

## 接入前先确定这几件事

| 情况 | 使用已有合同 |
| --- | --- |
| 一份脚本提供多个卷展 | 同一个模块 ID，被多个卷展的命令引用；不要为同一文件声明多个独立模块 |
| 共享纯函数或普通 DLL | 声明 `libraries` 和依赖；库没有业务模块的 Initialize/Stop 生命周期 |
| 仅打开分类、搜索或编辑布局 | 读取声明即可，不在扫描配置时 `fileIn`、构造业务对象或执行场景命令 |
| 持久参数、临时选区 | 参数明确声明 user/view/scene 范围；节点引用和场景快照不混入跨场景缓存 |
| 命令改动场景 | 正确声明 effect 与 undo，由确定的一个所有者提交或回滚；不以 query 绕过事务 |
| 普通参数错误、取消、部分修改失败 | 通过公开错误合同返回；仅确实未产生副作用时使用 `FailBeforeEffects`，完成自身回滚后才使用 `FailAfterRollback`；通用 catch 使用 `Fail`，框架恢复界面不会重放命令 |
| 被动列表或场景同步 | 可见时补齐数据，隐藏/关闭/Stop 清理观察器；用户已经启动的任务另按任务生命周期管理 |

配置扫描会校验元数据而不执行代码；首次实际加载前仍复查配置、依赖与代码身份。2026-11-07 的优化只复用同一次扫描中已校验的不可变配置，不建立跨扫描或跨更新的永久缓存。公开 Schema 与 MS 接口版本未因此改变。普通同步插件无需实现任务队列、额外授权会话或第二套 UI 格式；复杂能力见[复杂接入](advanced.md)。

## 脚本类型与宿主运行时不要混用

`modules[].runtime` 表示模块的实现类型，MAXScript 填 `"maxscript"`。可选的 `host_targets[].runtimes` 表示宿主的 .NET 运行时，允许 `"net48"`、`"net8"`、`"net10"`，不能填 `"maxscript"`。例如仅针对 Max 2026：

```json
"host_targets": [{"product":"3dsmax","minimum_release":2026,"maximum_release":2026,"runtimes":["net8"],"architecture":"x64"}]
```

Max 2024 使用 net48，Max 2025–2026 使用 net8，Max 2027 使用 net10。普通 MAXScript 可以直接在命令内调用自身的公开 MaxScript API，例如 `selection.count`；不需要为了读取选区数量编造框架服务。扫描或模块加载阶段不执行这些业务操作。

## 1. 分类与排序：placement.json

```jsonc
{
  // 放到哪个分类：可填已有分类名称，或填写新分类名称。
  "category":"自定",
  // 排第几个：数字越小越靠前，不要求连续编号。
  "order":10
}
```

数字越小越靠前。相同序号仍按稳定身份排序，不依赖文件夹枚举顺序。普通用户通常只修改这个文件。

## 2. 参数和界面：plugin.json

下面是完整的纯数值相加示例。它不修改场景，也不演示长度/面积单位。创建新插件时更换唯一 `plugin_id`；不要占用官方保留的 `dayu.*` 或 `cn.dayu.*`。

```jsonc
{
  // 1. 插件身份：schema_version 不随意修改；plugin_id 发布后保持稳定。
  "schema_version":"1.0.0",
  "plugin_id":"org.example.simple_sum",
  "version":"1.0.0",
  "title":"数值相加示例",
  // 2. 功能入口：界面与业务分开；main.ms 实现下方命令。
  "modules":[{"id":"main","runtime":"maxscript","entry":"main.ms"}],
  // 3. 参数：默认值、范围、显示精度和保存方式。
  "fields":[
    {"id":"a","type":"number","default":1,"minimum":0,"maximum":100,"step":1,"precision":0,"dimension":"scalar","canonical_unit":"none","display_unit":"none","persistence":"view"},
    {"id":"b","type":"number","default":2,"minimum":0,"maximum":100,"step":1,"precision":0,"dimension":"scalar","canonical_unit":"none","display_unit":"none","persistence":"view"},
    {"id":"total","type":"number","default":3,"minimum":0,"maximum":200,"step":1,"precision":0,"dimension":"scalar","canonical_unit":"none","display_unit":"none","persistence":"view"}
  ],
  // 4. 命令：按钮通过稳定 ID 绑定，不能仅靠显示文字寻找功能。
  "commands":[
    {"id":"sum.calculate","module":"main","export":"Calculate","effect":"query","concurrency":"reject","undo":"none","args":{"a":{"field":"a"},"b":{"field":"b"}}}
  ],
  // 5. 界面：每项是一个卷展；布局顺序和显示文字在这里修改。
  "panels":[{
    "id":"sum","title":"数值相加","activation":"on_command","expanded":true,
    "layout":["a.editor","b.editor","total.editor","calculate"],
    // 6. 教程：有演示视频时改为 {"kind":"url","url":"真实的HTTPS视频地址"}。
    // 每个卷展可填写自己的链接；没有视频时保留文字教程或省略 tutorial。
    "tutorial":{"kind":"inline","text":"输入两个数值后计算。此示例不修改 Max 场景。"},
    "controls":[
      {"id":"a.editor","type":"number","label":"数值 A","bind":"a"},
      {"id":"b.editor","type":"number","label":"数值 B","bind":"b"},
      {"id":"total.editor","type":"number","label":"结果","bind":"total"},
      {"id":"calculate","type":"button","label":"计算","command":"sum.calculate"}
    ]
  }]
}
```

`precision` 只控制显示位数，不把业务值变成整数。数量、索引等真正的整数字段还须声明 `value_kind:"integer"`。

`plugin.json` 和 `placement.json` 支持 `// 单行注释` 与 `/* 多行注释 */`，文件名不变。注释用于说明用途、单位、允许值和修改影响，不作为可执行配置。字符串内的 `https://`、`//` 或 `/* */` 原样保留。仍须使用双引号和正确逗号，不支持尾随逗号、重复字段或未知属性；不要自行增加 `_comment` 字段。编辑器可选择“JSON with Comments”语言模式。已有纯 JSON 文件继续兼容。

统一书写规范：使用 UTF-8、两空格缩进，按“身份 → 模块 → 参数 → 命令 → 卷展/布局/教程”分区。每个参数旁注明用途、单位、默认值和范围；每个命令注明修改场景或文件的影响。中文名称和提示可以修改，已有 `id`、`bind`、`command`、`export` 是关联标识，不能只改其中一个。注释随源配置保存；框架只在内存中去除注释并生成渲染数据，不回写作者文件。配置或脚本改变后重启 Max 再检查；已发布官方包仍按真实文件字节校验完整性。

无参数的按钮也必须声明 `"args": {}`，不能省略。1.0.0 使用内联 `args`；1.1.0 可以使用 `args_ref`，两者只选一个。校验完整 Schema 时要包含 `oneOf`、`allOf` 等条件，不能只检查局部 `required` 列表。

## 3. 功能实现：main.ms

```maxscript
(
    fn executeMyTool sender args =
    (
        case args.Request.Export of
        (
            "Calculate":
            (
                args.SetNumber "total" ((args.Number "a") + (args.Number "b"))
                args.Message "计算完成。"
            )
            default: throw "未知命令。"
        )
    )
    local module = dotNetObject "Dayu.Toolbox.PluginContract.Authoring.AuthorScriptModule"
    dotNet.addEventHandler module "Executing" executeMyTool
    module
)
```

框架先加载公共接口，然后读取 `main.ms` 的最后返回值。不要独立拖入这个文件试图打开窗口，也不要再写 `createDialog`。`fileIn` 阶段只返回模块，实际操作在命令中执行。

`args.Number` 读取清单映射的参数名；`SetNumber` 返回字段更新；`Message` 交给框架统一显示。没有字段或消息结果的成功命令可用 `args.Success()`。使用这些简化方法时，不要在同一次调用另设完整的 `args.Result`。

没有资源的普通模块只接 `Executing` 即可。开始接入场景修改、撤销、拾取或动态列表时转到[复杂接入](advanced.md)，不能继续把所有动作标成 `query`。

## 图库与缓存目录

需要用户选择图库或缓存目录时，在 `plugin.json` 顶层声明 `directories`，不要在每个卷展重复放路径输入框。设置页从声明读取目录，不执行子脚本；用户点击应用后，框架将路径保存到同一个 `user` 字段，并更新当前会话。

```jsonc
"directories": [
  {
    "id": "door.library",          // 包内稳定目录标识；改标题时保持此标识
    "title": "门图库",              // 设置页显示名称
    "group": "建模图库",            // 设置页分组
    "field": "door.root",           // fields 中的单行 text，persistence 为 user
    "default_subdirectory": "资源库/门", // 相对于 Windows 实际文档/DAYUCG/大鱼工具箱；禁止绝对路径或 ..
    "kind": "library",              // library 图库，cache 缓存
    "description": "保存门模型及其预览图；更改目录不会搬动旧文件。"
  }
]
```

`door.root` 可以默认空字符串，已有非空自定义路径优先。目录字段不得绑定 `change_command` 或 `edit_command`，目录设置不调用业务来保存配置。业务读取同一字段，空值时使用声明对应的默认目录；在需要切换已打开的文件或后台任务时，业务必须保证这些资源仍归属原任务，必要时在 `description` 说明下次打开生效。框架不会迁移、复制或清理目录中的文件。

卷展需要快捷入口时，使用已有 `shell@1` 服务的 `ShowDirectorySettings("door.library")`。只能定位本包声明的目录；这会打开统一设置页，不会再出现第二套目录选择状态。

### 主操作旁放取消按钮

“检查参数 [×]　保存资产”可用 `split_action` 标准行，三项依次为主操作、取消、另一操作，全部使用已有 `button` 控件和各自命令：

```jsonc
// 放在面板 layout 中；三个 ID 都必须已在该面板 controls 中声明。
{"type":"row","template":"split_action","items":["inspect","cancel_preview","store"]}
```

取消控件配置示例：`{"id":"cancel_preview","type":"button","label":"×","help":"取消预览","command":"cancel_preview"}`。左半行内主按钮与 22 个逻辑像素的取消按钮贴合，右半行放另一按钮。三个按钮分别命中、启用、触发命令；框架不会把取消行为附着到主按钮，也不会推断如何撤销业务预览。作者提供取消命令即可。此模板要求渲染器能力 `layout.split_action`，缺少能力时在加载业务前明确拒绝。

普通显式行也可把数值与其相关开关放一起，例如 `{"type":"row","items":["band","front"]}`。范围输入保留完整数值、正常水平滚动与完整值悬停，不因最大值很长挤出第二行；无需缩短“范围”“反转正面”等标签。

### 数值步长与拖动

毫米尺寸统一使用1 mm基础步长，包括缝隙和切角。字段采用其他单位时，`step`填写换算后对应的值；例如规范单位是米，则1 mm步长写`0.001`。角度、倍率和数量保留各自单位，不把所有数字都当作毫米。`precision`决定显示的小数位数，不会限制数值只能是整数；数量、分段请另写`"value_kind":"integer"`。

框架自动提供右侧箭头单击、长按连调和左键上下拖动。拖远加速、反向恢复细速；Shift精调，Ctrl快调，Esc取消。数字正文仍可选字编辑，中键仍用于滚动。作者无需增加拖动事件或定时器。

普通场景`change_command`在松手时执行一次；纯字段和`effect:"viewport"`的临时预览会限频实时更新，取消时恢复原值。若确实需要实时改变场景并合并为一次撤销，使用复杂接入中的`edit_command`连续编辑合同，不要把场景修改伪装成`viewport`。本能力由框架协商`number.gestures`，旧框架缺少能力时会在业务加载前提示不支持，不会静默忽略。

## 数值输入一致性

数值框只呈现数字；框架悬停提示负责完整值、单位和步长，不要在脚本中拼接 `mm` 后缀。长度声明使用 `dimension: "length"`、`canonical_unit: "mm"`、`display_unit: "mm"`，持久值按毫米，显示由用户的框架单位偏好决定；业务调用 Max 几何 API 时才转换为系统世界单位。角度、百分比、数量、像素以及固定光学毫米焦距应保留各自原有计量方式。标记的固定屏幕尺寸是普通数值，不能声明为长度。

## 模块与共用库

`libraries` 的每项声明 `id`、`runtime`、`entry` 和交付文件的 `sha256`；模块通过 `libraries` 引用它。调用者与所引用库须使用同一 runtime，依赖不得成环。同一个入口文件不能同时作为模块和库。普通库没有模块的 Initialize/Stop 生命周期，不要为库补造业务模块。MAXScript 模块不能把 dotnet 库当作 maxscript 库引用；需要混合实现时先按公开合同划分模块和桥接边界。
