在 MSW 项目中生成或编辑 .behaviourtree…

适用于 MSW 项目中需要创建、更新或校验 .behaviourtree 行为树的场景。

适用场景

解决思路

1. Step 0：在以下情况重新构建项目 spec（bt-spec.md）：首次在项目处理 BT（没有 .behaviourDocs/bt-spec.md 时）；任何影响 BT 节点表面区域的变更（新增/重命名/删除 .codeblock 且配对 .mlua extends ActionNode/DecoratorNode/CompositeNode；在此类 .mlua 中添加/删除/重命名 property 行；Environment/config 的 CoreVersion 提升）；用户说最近添加/修改了 BT codeblock 或 .mlua 属性；下游验证 Step 7 标记 definitionId、propertyKey 或版本不匹配。
2. Step 0：运行 `node "scripts/build-spec.cjs" --projectRoot "<MSW project root>"`；如果当前工作目录已经是 MSW 项目根，可省略 --projectRoot。
3. Step 0：确保 Node.js 在 PATH 上（脚本仅用 stdlib fs/path，无其他依赖）。
4. Step 0：可选覆盖（长标志，大小写不敏感）：--projectRoot 默认当前工作目录；--outputPath 默认 `<ProjectRoot>/.behaviourDocs/bt-spec.md`，文件夹缺失时创建；--coreVersion 默认从 `<ProjectRoot>/Environment/config` 的 CoreVersion 字段读取，config 缺失时必需。
5. Step 0：示例：`node "scripts/build-spec.cjs" --projectRoot "C:/path/to/project" --coreVersion 26.7.0.0`。
6. Step 0：如果 Environment/config 不存在且未传 --coreVersion，脚本会抛出错误，没有默认回退。
7. Step 0：生成的 spec 包含：1) 项目元数据（项目根、CoreVersion、生成时间、发现的节点数）；2) 复合节点（内置名称与固定 definitionId/btNodeType，加上发现的自定义复合节点）；3) 自定义动作节点（Name、definitionId、btNodeType、可见属性名）；4) 自定义装饰器节点（与动作节点同形）；5) 类型映射（mlua 类型到序列化 MODNativeType.type 加上 Blackboard ObjectValue 形状）。
8. Step 0：UUID 来自项目中真实 .codeblock 文件，spec 从不虚构；@HideFromInspector 属性自动过滤；固定编写规则、文件骨架、验证清单在 references/ 而不是生成的 spec。
9. Step 0：重建后，读取新写入的 `<ProjectRoot>/.behaviourDocs/bt-spec.md` 并继续。
10. Step 0：构建 nodeProperties 时，从配对 .mlua 解析每个属性的 mlua 类型/默认值，然后使用 bt-spec.md §4 的类型映射给 propertyType.type。
11. Step 0：同时读取 references/skeleton-minimal.json（最小有效树）、references/skeleton-full.json（Composite+Decorator+Action+Blackboard 示例，所有可选字段填充）、references/node-catalog.md（固定图规则），以及任何现有 .behaviourtree（`**/*.behaviourtree`）以镜像约定。
12. Step 0：用 bt-spec.md 中的 CoreVersion 替换骨架中的 {CORE_VERSION}，包括顶层和每个 MOD.Core.* 类型字符串（Blackboard 变量和 nodeProperties 中）。
13. Step 1：通过上下文确认或使用 AskUserQuestion 询问：name（树显示名）；保存路径（相对项目根的 .behaviourtree 位置）；树形状（目标节点图，如 `Sequence → [Chase, MoveTo]`）；自定义节点（树引用的 action/decorator/composite codeblocks）；Blackboard 变量（变量名 + 类型 + 初始值，如 `TargetEntity: Entity`、`MoveSpeed: number = 10.0`）；节点属性（每个自定义节点哪个属性映射到哪个 Blackboard 变量，如 `Chase.TargetEntityKey = "TargetEntity"`）。
14. Step 1：强制自定义节点存在检查：用户提到的每个自定义 action/decorator/composite 名称必须出现在 bt-spec.md §1/§2/§3。如果引用的节点不在 spec 中，停止并询问用户——不要发明 UUID，不要假设节点按名称存在，不要跳过重跑 Step 0。
15. Step 2：为文件生成一个 UUID → 放入 EntryKey 和 ContentProto.Json.id（两者相同，均前缀 `behaviourtree://`）。
16. Step 2：为 Nodes 中每个节点生成一个 UUID → nodeId。
17. Step 2：使用命令 `node -e "console.log(require('node:crypto').randomUUID())"` 生成 UUID。
18. Step 2：提前生成，写入草稿表，然后组装；不要复用文件 UUID 作为 nodeId。
19. Step 3：解析每个 definitionId：内置复合（SequenceNode、SelectorNode、ParallelNode）definitionId 与 nodeName 相同，btNodeType 1；自定义复合节点（extends CompositeNode）definitionId 来自 bt-spec.md §1，btNodeType 1；自定义动作节点来自 §2，btNodeType 0；自定义装饰器节点来自 §3，btNodeType 2。
20. Step 3：自定义节点 UUID 来自 bt-spec.md（其从真实 .codeblock 文件读取），绝不使用其他来源。
21. Step 4：构建 Blackboard：每个变量从 bt-spec.md §4 逐字复制 Type.type 字符串和 ObjectValue 形状；版本标记子串（Version=<CoreVersion>）必须完全匹配，拼写错误会静默破坏反序列化。
22. Step 4：Variables 是有序数组；每个条目：{ Name, Type: { "$type": "MODNativeType", type: "<from spec>" }, ObjectValue: <from spec> }。ObjectValue 不包含 $type 鉴别器（不同于 .model 文件中的 Value）。
23. Step 4：对于 Component/ComponentRef，ComponentId 是 `<entity-uuid>:<ComponentName>`（引擎组件）或 `<entity-uuid>:<scriptCodeblockUuid>:<ScriptComponentName>`（脚本组件）；镜像项目中现有序列化示例。
24. Step 4：数值 ObjectValue 使用浮点字面量形式（3.0，不是 3）。
25. Step 4：运行时警告：Blackboard 位于入口的树。如果任何脚本稍后调用 AIComponent:SetRootNode(...)，入口树和此 Blackboard 被丢弃，BlackBoard 读 nil 且 *Key 属性停止解析；不要混用运行时根替换与依赖 Blackboard 的树。
26. Step 4.5：对每个需要 nodeProperties 的自定义节点：确认 propertyKey 存在于 bt-spec.md §1/§2/§3 中该节点。
27. Step 4.5：通过搜索 `script <NodeName> extends ActionNode`、`extends DecoratorNode` 或 `extends CompositeNode` 在项目下找到配对 .mlua；如果多个匹配，优先选择兄弟 .codeblock 具有 bt-spec.md 中精确 definitionId UUID 的那个；如果仍模糊，询问用户。
28. Step 4.5：读取该 .mlua 中可见的 property 声明，忽略 @HideFromInspector 属性；得到 mlua 类型和默认值。
29. Step 4.5：仅当用户提供值、行为需要非默认值、或 *Key 属性必须指向 Blackboard 变量时，才包含 nodeProperties 条目；省略可安全使用 .mlua 默认值的可选属性。
30. Step 4.5：对于 *Key 字符串属性，将 propertyValue 设为 Blackboard 变量名；根据名称和 getter 用法推断变量（MoveSpeedKey -> MoveSpeed，TargetEntityKey -> TargetEntity）；如果多个 Blackboard 变量可能匹配，询问。
31. Step 4.5：对于字面量属性，使用用户提供的值；如果未提供值且 .mlua 默认值有意义，省略属性而不是序列化猜测值。
32. Step 4.5：如果 OnBehave 检查属性为 nil、空字符串或无效枚举且无法推断值，写入树前询问用户。
33. Step 4.5：nodeProperties 条目形状：{ propertyKey: "<property name>", propertyType: { "$type": "MODNativeType", type: "<type from bt-spec.md §4>" }, propertyValue: <value> }
34. Step 5：硬图约束（写入前验证）：RootNode 不是父节点，不得有 childNodes；只存 startNodeId，startNodeId 指向 Nodes 中恰好一个节点。
35. Step 5：如果树需要多个顶层行为，使用一个 Composite 作为单个 startNodeId，或一个 Decorator 作为单个 startNodeId，其 decoChildNodes 包裹一个 Composite 或另一 Decorator 链，最终包裹一个 Composite；将多个行为放在该 Composite 的 childNodes 下。
36. Step 5：Nodes 中恰好一个节点可以有 nodeParentId: ""：即 RootNode.startNodeId 引用的节点；不要创建多个根级 Action/Composite/Decorator 节点。
37. Step 5：Composite（btNodeType: 1）是唯一可通过 childNodes 拥有多个子节点的节点类别。
38. Step 5：Decorator（btNodeType: 2）只是恰好一个 Action、Composite 或 Decorator 节点的包装/父节点；它也可以是另一 Decorator 的子节点，因此 Decorator-to-Decorator 链有效；必须使用单数 decoChildNodes（单个 nodeId 字符串）表示那一个子节点，而不是 childNodes；被包裹的子节点也必须在 nodeParentId 中记录 Decorator 的 id。
39. Step 5：装饰器应用于同一 Action 必须链式，绝不能扁平化为兄弟；每个装饰器拥有恰好一个下游子树；如果两个或多个装饰器意图门控/修改同一 Action，构建单链 `Composite → ADeco → BDeco → CDeco → Action`，每个装饰器的 decoChildNodes 指向下一个装饰器（最后指向 Action）；具体：在通向单个 Action 的一个链内，没有两个装饰器可以共享同一 nodeParentId——每个装饰器的父节点是前一个装饰器，只有最顶层装饰器的父节点是 Composite；一个 Composite 下的兄弟装饰器各自包裹不同下游子树时仍然有效。
40. Step 5：装饰器链式示例：✅ `Composite → ADeco → BDeco → CDeco → Action`（链——链内每个装饰器有唯一父节点）；❌ `Composite → [ADeco→Action, BDeco→Action, CDeco→Action]`（Action 重复以绕过链式）；❌ `Composite → [ADeco, BDeco, CDeco, Action]`（装饰器扁平化——它们不包裹 Action 且实际孤立）。
41. Step 5：Action（btNodeType: 0）是叶子——永远没有子节点。
42. Step 5：节点写入不变量：每个 nodeId 在文件内唯一。
43. Step 5：每个非根节点的 nodeParentId 指向一个真实 nodeId，该 nodeId 是 Composite 或 Decorator；它绝不能指向 RootNode，因为 RootNode 不在 Nodes 中表示。
44. Step 5：如果节点父节点是 Composite，该 Composite 必须在其 childNodes 中包含节点 id。
45. Step 5：如果节点父节点是 Decorator，该 Decorator 的 decoChildNodes 必须等于该节点的 nodeId；即使父和子都是 Decorator 也有效。
46. Step 5：Composite childNodes ↔ 子节点 nodeParentId 必须双向一致。
47. Step 5：Action 节点省略 childNodes；Decorator 节点省略 childNodes，并使用恰好一个 decoChildNodes（单个字符串 nodeId）。
48. Step 5：绝不写 probability；编辑器在往返时剥离此字段，支持的复合（SequenceNode、SelectorNode、ParallelNode）不消耗每子权重；旧生成的树可能每个节点仍带 "probability": 1.0，读取时视为遗留，但新节点不写。
49. Step 5：装饰器节点（btNodeType: 2）省略 nodePosition；编辑器自动相对于包裹的子节点定位装饰器，保存时不为其写 nodePosition 字段；只有 Composite 和 Action 携带 nodePosition；RootNode 块也有自己的 nodePosition（与 start node 分开）。
50. Step 5：空集合字段省略，不序列化为 []；尚无子节点的 Composite 应完全省略 childNodes；无覆盖的节点应完全省略 nodeProperties；空数组是编辑器草稿产物——不要编写。
51. Step 5：装饰器子字段是 decoChildNodes（规范——编辑器保存时保留；ChildNodeId 在往返时被静默剥离）；它是单个字符串，保存被包裹子节点的 nodeId（不是数组）；读取遗留文件时可能仍在手工编写的装饰器上遇到 ChildNodeId，将其视为相同字段；写入时始终发出 decoChildNodes。
52. Step 5：RootNode.startNodeId 引用其中一个 nodeId——Action、Composite 或 Decorator——并且该节点是唯一具有 nodeParentId: "" 的节点。
53. Step 5：*Key 后缀 String 属性携带 Blackboard 变量的名称（运行时通过 BlackBoard:GetXxx 解析）；非 Key 属性携带字面量值。
54. Step 6：nodePosition 是带数值 x/y 的 JSON 对象：`"nodePosition": { "x": 0.0, "y": 0.0 }`。
55. Step 6：使用浮点字面量（0.0，不是 0）；遗留字符串形式 `"(0.000, 0.000)"` 可能出现在旧手工树中——读取时视为等效，但始终写入对象形式（BT 编辑器保存时规范化为该形状，字符串形式首次打开时会重新序列化为噪声差异）。
56. Step 6：编辑器轴：BT 编辑器使用数学约定画布——+x 向右，+y 向上（右上象限为正）；因此子节点放在比父节点更高的 y 会在屏幕上出现在父节点上方。
57. Step 6：布局规则——向下绘制树：深度沿 −y 增长（子节点在父节点下方），兄弟姐妹沿父节点 x 的 ±x 展开；典型间距：深度级别之间 200 单位，兄弟姐妹之间 200 单位。
58. Step 6：RootNode 块与 start node——不要堆叠在同一位置；RootNode.nodePosition 是画布锚点，保持 { "x": 0.0, "y": 0.0 }；start node（startNodeId 引用的节点）必须位于该锚点下一层——将其放在 (0, 0) 会使其在编辑器画布上与 RootNode 标记视觉重叠；将 RootNode 锚点视为深度 0，start node 视为深度 1。
59. Step 6：具体坐标：RootNode.nodePosition: { "x": 0.0, "y": 0.0 }（固定锚点——永不移动）；Start node（深度 1）：{ "x": 0.0, "y": -200.0 }；start node 的单个子节点（深度 2）：{ "x": 0.0, "y": -400.0 }；start node 的两个子节点（深度 2）：{ "x": -100.0, "y": -400.0 } 和 { "x": 100.0, "y": -400.0 }；每增加一级：parent.y − 200。
60. Step 6：绝不要把子节点放在 y 大于或等于父节点 y 的位置——那会向上绘制并与父节点视觉重叠；同一规则适用于 RootNode 和 start node：start node 必须在 y ≤ -200（严格低于锚点）。
61. Step 6：装饰器节点不携带 nodePosition；编辑器自动相对于包裹的子节点布局它们；在每个 btNodeType: 2 节点上省略该字段；它只出现在 RootNode、Composites（btNodeType: 1）和 Actions（btNodeType: 0）上。
62. Step 7：写入 JSON 文件，然后运行验证清单。
63. Step 7 检查：EntryKey 是 `behaviourtree://{uuid}` 并与 ContentProto.Json.id 完全匹配。
64. Step 7 检查：顶层 Id、GameId、Content 是 ""；Usage、UseService、DynamicLoading 是 0；UsePublish 是 1；CoreVersion 匹配项目（Environment/config）；StudioVersion 是 0.1.0.0；ContentType 是 x-mod/behaviourtree；ContentProto.Use 是 Json。
65. Step 7 检查：RootNode 没有 childNodes；RootNode.startNodeId 匹配 Nodes 中恰好一个 nodeId；该 start node 有 nodeParentId: ""；没有其他节点有 nodeParentId: ""。
66. Step 7 检查：每个 nodeParentId 是 "" 或现有 nodeId。
67. Step 7 检查：所有 nodeId 值唯一。
68. Step 7 检查：对于每个 Composite，childNodes ID 集合等于 nodeParentId 为此 Composite 的节点集合。
69. Step 7 检查：每个 Action 没有 childNodes；每个 Decorator 没有 childNodes，恰好一个 decoChildNodes（单个 nodeId 字符串——ChildNodeId 是遗留变体，编辑器在往返时剥离它），该 id 指向恰好一个 Action、Composite 或 Decorator 子节点，其 nodeParentId 指回 Decorator；Decorator-to-Decorator 父子链有效，必须用相同 decoChildNodes ↔ nodeParentId 规则检查。
70. Step 7 检查：装饰器链规则——当多个装饰器应用于同一 Action 时，它们形成单链（Composite → ADeco → BDeco → … → Action）；通过将每个 Action 向上走到其封闭 Composite 来验证：沿该路径遇到的装饰器必须都具有唯一的 nodeParentId 值（即每个装饰器的父节点是前一个装饰器，绝不是已出现在链中的另一个装饰器）；同一链中两个装饰器共享 nodeParentId 无效；（一个 Composite 下的兄弟装饰器包裹不同下游子树是好的——唯一性是每链，不是全局）。
71. Step 7 检查：没有节点序列化 "probability"（读取时可能出现过时 1.0 值，但绝不编写）。
72. Step 7 检查：每个 Composite 和 Action 以对象形式 { "x": <num>, "y": <num> } 携带 nodePosition，使用浮点字面量——写入时没有遗留 "(x.xxx, y.yyy)" 字符串；装饰器节点完全不携带 nodePosition。
73. Step 7 检查：Start node 不堆叠在 RootNode 锚点上；RootNode.nodePosition 是 { "x": 0.0, "y": 0.0 }，startNodeId 引用的节点有 y ≤ -200.0（通常 { "x": 0.0, "y": -200.0 }）；如果 start node 是 Decorator（无 nodePosition），则链中第一个被包裹的 Composite/Action 必须满足此偏移。
74. Step 7 检查：没有节点序列化空数组——无子节点的 Composite 省略 childNodes；无覆盖的节点省略 nodeProperties；不要写 "childNodes": [] 或 "nodeProperties": []。
75. Step 7 检查：每个自定义节点的 definitionId 从 bt-spec.md 复制（绝不发明）。
76. Step 7 检查：每个 nodeProperties[].propertyKey 匹配 bt-spec.md 中该节点的属性。
77. Step 7 检查：每个 *Key 属性的 propertyValue 匹配正确类型的 Blackboard.Variables[].Name。
78. Step 7 检查：每个类型字符串从 bt-spec.md §4 逐字复制——版本标记，易错。
79. Step 7 检查：版本交叉检查——每个 MOD.Core.* 类型字符串的 Version=X.Y.Z.Z 子串（在 Blackboard.Variables[].Type.type 和 Nodes[].nodeProperties[].propertyType.type 中）等于文件顶层 CoreVersion；不匹配会静默破坏反序列化——常见于 bt-spec.md 相对于项目当前 CoreVersion 过时；如果不同，写入前重新运行 Step 0；（System.* 类型使用不可变 Version=4.0.0.0，豁免）。
80. Step 7 检查：JSON 可解析：`node -e "JSON.parse(require('node:fs').readFileSync(process.argv[1],'utf8'))" "<path>"`。
81. Step 7：如果任何检查失败，在报告完成前修复。
82. 编辑现有文件：读取整个文件——绝不要盲编辑；UUID 和父/子图必须保持一致。
83. 编辑现有文件：绝不更改文件包装 UUID（EntryKey / ContentProto.Json.id）——外部引用会断裂。
84. 编辑现有文件：添加节点时，生成新 nodeId，追加到 Nodes，更新父 Composite 的 childNodes，设置新节点的 nodeParentId。
85. 编辑现有文件：删除节点时，从 Nodes 移除，从任何 Composite 的 childNodes 移除其 ID；如果它是 Composite，决定重新挂载还是移除其子节点——绝不留悬空 nodeParentId 引用。
86. 编辑现有文件：如果编辑涉及自定义节点名称、属性或类型，且这些可能自 spec 上次构建以来已更改，先重新运行 Step 0。
87. 编辑现有文件：每次编辑后重新运行 Step 7 验证清单。
88. 使用 `scripts/build-spec.cjs`：Node.js 脚本，扫描项目并输出 `<ProjectRoot>/.behaviourDocs/bt-spec.md`，在 Step 0 调用。
89. 使用 `<ProjectRoot>/.behaviourDocs/bt-spec.md`：紧凑生成的目录，是节点名称、definitionId、btNodeType、属性名和类型字符串的 source of truth；由上述脚本写入，由 Steps 1–7 消费。
90. 使用 `references/skeleton-minimal.json`：最小有效树（空 Blackboard，单个 Composite 根无子节点）。
91. 使用 `references/skeleton-full.json`：Composite → Decorator → Action，带 nodeProperties（字面量 + Key 后缀）和填充的 Blackboard；非平凡树时用作形状参考。
92. 使用 `references/node-catalog.md`：btNodeType 值、有效图形状、Key 后缀约定、spec builder 如何发现节点的叙述说明（保留参考；运行时目录在 bt-spec.md 中）。

适用边界 · 注意事项

• 非 MSW 项目，或项目中不存在 .behaviourtree/.codeblock/.mlua 体系时。
• 无法运行 Node.js 脚本，或缺少 Environment/config 且未提供 --coreVersion 时。
• 计划在运行时调用 AIComponent:SetRootNode(...) 并依赖 Blackboard 的场景；该操作会丢弃入口树和 Blackboard，导致 *Key 属性解析失败。