unity-behavior

**调用本模块中的任何技能前：**如果你打算根据技能名称或描述猜测参数后调用该技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已经从 recommend/schema 获取了参数定义，则可以直接进行 dryRun。

触发条件

• 配置 NPC/AI 决策逻辑
• 使用行为树/行为图
• 读写黑板变量
• 搭建 NPC/AI 决策逻辑、使用行为树/行为图、读写黑板变量

Behavior 技能

Unity Behavior（com.unity.behavior，已针对 1.0.16 验证）图资产发现、Agent 配置和黑板变量访问。

此包为可选项，不是 UnitySkills 的已声明依赖项。本模块中的每项技能都通过反射访问该包；如果缺少该包，每项技能都会返回相同的结构化 PACKAGE_NOT_INSTALLED 响应，并指向 package_install。

运行模式

• 查询技能（behavior_status、behavior_graph_list、behavior_graph_info、behavior_agent_get、behavior_agent_list、behavior_blackboard_list）采用 SkillMode.SemiAuto——无需授权即可在所有三种模式下运行。
• 修改技能（behavior_graph_create、behavior_agent_add、behavior_agent_set_graph、behavior_blackboard_set）采用 SkillMode.FullAuto——在 Approval 模式下需要用户授权；在 Auto / Bypass 模式下直接执行。
• 本模块中的所有技能都不带有 SkillOperation.Delete，因此在 Approval / Auto 模式下不会被自动禁止。

前提条件

如果 behavior_status 报告 installed: false，请先安装此包：

package_install  packageName="com.unity.behavior"

安装会触发 Domain Reload；请等待其完成，然后再次调用 behavior_status，再使用本模块中的其他技能。

两种资产类型（绑定图前请先阅读）

一个“Behavior Graph” .asset 文件包含两个对象，混淆它们是最常见的错误：

对象	作用	所在位置
BehaviorAuthoringGraph	编辑表示形式——节点、黑板、故事。主资产。	.asset 文件本身
BehaviorGraph	烘焙后的运行时图。BehaviorGraphAgent.Graph 实际需要的对象。	同一文件中嵌套的子资产

本模块中的技能始终接收文件路径（graphAssetPath / assetPath），并在内部解析正确的对象——你无需直接访问子资产。behavior_agent_set_graph 会为你查找嵌套的 BehaviorGraph，如果图从未编译过，则会以 RUNTIME_GRAPH_MISSING 拒绝绑定。

注意事项

路由：

• Behavior 图 / 黑板 / BehaviorGraphAgent：使用本模块
• Animator 状态机：使用 animator_*
• 在 GameObject 上附加通用组件：component_add 可以实现，但 behavior_agent_add 还会绑定图并对其进行验证

运行时优先规则：

• 调用 behavior_blackboard_set 前，务必先调用 behavior_blackboard_list——变量名称区分大小写，声明的 CLR 类型决定了可接受的值形态。
• 切勿凭记忆编造 graphAssetPath；请从 behavior_graph_list 获取。
• 如果技能返回 errorCode: "API_MISMATCH"，说明已安装的软件包版本与此集成所预期的成员布局不同。不要尝试使用不同参数重试——请报告版本不匹配，并改用 Behavior 编辑器窗口或直接编辑 .asset 文本。
• behavior_graph_create 创建的图除自动插入的 Start 根节点外为空。添加实际行为节点需要使用 Behavior 编辑器窗口（参见限制）。

技能

behavior_status

报告软件包可用性：installed、version、已解析的核心类型、项目图资产数量以及场景 Agent 数量。即使缺少软件包也可以安全调用——这是唯一会提供响应而不是报错的技能。

behavior_graph_list

列出行为图资源，包括 path、guid、nodeCount、variableCount 和 hasRuntimeGraph。可选参数：filter（对路径进行子字符串匹配）、folder、limit。

behavior_graph_info

单个图资源的结构摘要：节点数量及按类型细分的数量、各节点（id / type / position，数量上限由 maxNodes 指定）、根节点数量、包含类型和默认值的完整黑板变量列表、子图依赖项以及运行时图状态。

behavior_graph_create

在 savePath 创建空的 BehaviorAuthoringGraph，并强制重新导入，让 Unity 烘焙黑板、运行时 BehaviorGraph 子资源、调试信息子资源以及必需的 Start 根节点。返回 hasRuntimeGraph；如果未执行烘焙，则返回 warning，并且必须在编辑器窗口中打开一次该图。

behavior_agent_add

向 GameObject（name / instanceId / path）添加 BehaviorGraphAgent，并可选择在同一调用中绑定 graphAssetPath。组件添加前会解析并验证图，因此错误路径不会留下配置不完整的 Agent。此操作具有幂等性——如果 Agent 已存在，则会复用并通过 componentAdded: false 报告。

behavior_agent_get

读取单个 Agent：已绑定的图名称和资源路径、isInitialised / isStarted / isRunning、图的黑板变量以及 Agent 级别的覆盖值。

behavior_agent_set_graph

将 graphAssetPath 绑定到现有 Agent。此操作会解析嵌套的运行时图，并拒绝未编译的图。

behavior_agent_list

列出已加载场景中的所有 BehaviorGraphAgent，包括层级路径、已绑定的图、激活/启用标记和运行状态。可选参数：graphFilter、includeInactive、limit。

behavior_blackboard_list

列出黑板变量。传入 graphAssetPath 可读取资源的创作默认值（source: "asset"）；传入 GameObject 定位参数可读取 Agent 的图变量及其覆盖值（source: "agent"）。两者必须提供其一。

behavior_blackboard_set

设置单个变量的值。

参数	含义
variable	变量名称，区分大小写。必填。
value	新值。接受的格式取决于声明的类型（见下文）。
name / instanceId / path	GameObject 定位参数——写入 Agent 级别的覆盖值。
graphAssetPath	写入图资源默认值并重新烘焙运行时黑板；如果重新烘焙步骤失败，响应中会包含 warning。

请提供 GameObject 定位参数或 graphAssetPath；如果两者都提供，则以 GameObject 为准。

返回值：target（"agent" 或 "asset"）、variable、type、规范化后的 value，以及说明写入位置的 note。

支持的值类型和接受的输入格式：

声明的类型	接受的 value
int / float / double / bool / string	JSON 标量，或可解析的字符串
enum	成员名称（不区分大小写）
Vector2 / Vector3 / Vector4 / Quaternion	[1,2,3]、{"x":1,"y":2,"z":3} 或 "1,2,3"
Color	{"r":1,"g":0,"b":0,"a":1}、[1,0,0,1] 或 "#FF0000"
Vector2Int / Vector3Int	与浮点向量相同，数值会截断
GameObject / Component	Assets/... 预制体路径、场景层级路径或场景对象名称
其他 UnityEngine.Object	Assets/... 或 Packages/... 资源路径

设置未知变量时，会在 availableVariables 中返回可用名称。

编辑模式与播放模式

BehaviorGraphAgent 会在 Init() 时实例化其图的私有副本，而这只会在播放模式下发生。这会改变读写的含义：

• 编辑模式 — 使用 GameObject 调用 behavior_blackboard_set 时，会写入一个 Agent 级覆盖值（与 Inspector 中显示的内容完全一致）。读取图变量时，返回的是共享资源默认值，而不是每个 Agent 的值；每个 Agent 的值位于 overrides 数组中。
• 播放模式 — 写入会进入正在运行的图实例，因此会立即生效，且仅影响该 Agent。

这就是 behavior_blackboard_list 会同时报告 Agent 的 variables 和 overrides 的原因。

工作流

1. behavior_status — 确认已安装该包。
2. behavior_graph_list — 查找图，或使用 behavior_graph_create 新建一个图。
3. 在 Behavior 编辑器窗口中编写节点图（节点编辑不可通过脚本完成 — 参见限制）。
4. behavior_graph_info — 确认节点拓扑并读取黑板约定。
5. 使用 graphAssetPath 调用 behavior_agent_add — 一次调用即可附加并绑定。
6. behavior_blackboard_list — 读取准确的变量名称和声明类型。
7. behavior_blackboard_set — 设置每个 Agent 的覆盖值，或通过 graphAssetPath 设置整个图的默认值。
8. behavior_agent_list — 验证整个场景中 Agent 的连接情况。

限制

不支持节点级图编辑。 没有可用于在行为图中添加、删除、连接或重新配置节点的技能。这是有意排除的功能，并非疏忽：

• 编写用的节点图以 [SerializeReference] 多态 List<NodeModel> 的形式存储，其中包含 PortModel 交叉引用、内嵌的 SerializableCommandBuffer，以及带版本戳的 NodeModelInfo 缓存。要正确写入，就必须复现该包的命令/分发器流水线，而不只是设置字段。
• 每次编辑后都必须对三个子资源（运行时图、运行时黑板、调试信息）进行一致的重新烘焙，并同步 VersionTimestamp，否则资源会与烘焙后的运行时图静默失配。
• 序列化架构有明确的版本控制（kLatestSerializationVersion，当前为 3），且在 1.0.x 系列中曾发生变化。由反射驱动的拓扑写入会在补丁版本发布时失效。

需要进行节点级更改时的替代方案：

1. 首选 — 在 Behavior 编辑器窗口中编写图（Window > AI > Behavior，或双击资源），然后使用此模块检查并连接图。
2. 使用 asset_duplicate 复制一个已知正常的图并重新绑定，而不是从零构建拓扑。
3. 对现有图进行机械性、重复性编辑时，直接编辑 .asset YAML — 先加载 yaml 编辑提示，了解托管引用和 fileID 规则，然后使用 behavior_graph_info 再次验证。

其他限制：

• behavior_graph_create 会生成一个空图。编写节点仍需使用编辑器窗口。
• 无法创建、重命名、更改类型或删除黑板变量 — 只能为现有变量赋值。请在 Behavior 编辑器的 Blackboard 面板中添加变量。
• 不支持事件通道、子图动态链接和运行时序列化（Serialize / Deserialize）。
• 对 graphAssetPath 使用 behavior_blackboard_set 会更改所有未为该变量设置覆盖值的 Agent 共用的默认值。
• 不支持 Agent 生命周期控制（Init / Start / End / Restart）；这些属于播放模式下的运行时事项，最好由游戏代码处理。

版本敏感性

类型和成员名称取自 com.unity.behavior 1.0.16 源码，并与已发布的 Scripting API 交叉核对。公共接口（BehaviorGraphAgent、BehaviorGraph、BlackboardReference、Blackboard、BlackboardVariable、VariableModel）均有文档说明且保持稳定。创作接口（BehaviorAuthoringGraph、GraphAsset、BlackboardAsset、BehaviorBlackboardAuthoringAsset）在包中为 internal，并通过名称访问——升级包时这些接口可能会变动。所有此类查找都经过空值检查，并会报告 API_MISMATCH，而不会抛出异常；behavior_status 会准确显示哪些类型已解析。

---

精确签名

准确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文档。