ceshi

2026-02-26 23:45:31 +08:00
parent aa599ea653
commit dd642c8585
79 changed files with 6044 additions and 0 deletions
--- a/Plugins/UnrealAgentLink/Resources/Docs/蓝图开发接口文档.md
+++ b/Plugins/UnrealAgentLink/Resources/Docs/蓝图开发接口文档.md
@@ -0,0 +1,362 @@
+# 蓝图开发接口
+
+## 接口总览
+
+| Method | 名称 | 说明 |
+| --- | --- | --- |
+| **blueprint.describe** | 📋 获取结构 | 查看蓝图的组件、变量列表（修改前必用！） |
+| **blueprint.create** | 创建蓝图 | 创建新的蓝图类，支持指定父类和添加组件 |
+| **blueprint.add_component** | 添加组件 | 为已存在的蓝图添加新组件 |
+| **blueprint.set_property** | 设置属性 | 修改蓝图默认值（CDO）或组件属性（SCS） |
+| **blueprint.add_variable** | 定义变量 | 添加蓝图成员变量（支持数组/对象引用等） |
+| **blueprint.get_graph** | 上帝视角 | 获取图表全貌（节点 GUID + 真实引脚名） |
+| **blueprint.add_node** | 添加节点 | 添加节点并返回 pins 说明书（真实引脚名） |
+| **blueprint.add_timeline** | 添加 Timeline | 添加 Timeline（创建 TimelineTemplate + Timeline 节点；Timeline 不能用 add_variable/add_node 直接创建） |
+| **blueprint.connect_pins** | 逻辑连线 | 基于 node_id + pin.name 连接执行流/数据流 |
+| **blueprint.compile** | 编译蓝图 | 手动触发编译并可选保存（返回 diagnostics 供自修复） |
+
+---
+
+## 获取蓝图结构 `blueprint.describe`
+获取蓝图完整结构信息：父类、组件列表（SCS 添加 + 继承）、变量列表、编译状态。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp0","method":"blueprint.describe","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Hero" // 必填：蓝图名称或路径
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp0","code":200,"result":{
+  "ok":true,
+  "name":"BP_Hero",
+  "path":"/Game/Blueprints/BP_Hero.BP_Hero",
+  "parent_class":"Character",
+  "parent_class_path":"/Script/Engine.Character",
+  "generated_class":"/Game/Blueprints/BP_Hero.BP_Hero_C",
+  "components":[
+    {"name":"DefaultSceneRoot","class":"SceneComponent","class_path":"/Script/Engine.SceneComponent","source":"inherited","editable":true},
+    {"name":"PointLight","class":"PointLightComponent","class_path":"/Script/Engine.PointLightComponent","source":"added","editable":true,"attach_to":"DefaultSceneRoot"}
+  ],
+  "variables":[
+    {"name":"WalkSpeed","type":"float","editable":true,"default_value":"600.000000"}
+  ],
+  "compile_status":"UpToDate"
+}}
+```
+
+### 说明
+- `blueprint_path` 支持短名或完整路径；若传入 `/Game/.../BP_XXX`（不带 `.BP_XXX`），插件会自动补全。
+- `components[].source`：`added` 表示蓝图自身（SCS）添加，`inherited` 表示从父类 CDO 继承。
+- `variables[].default_value` 仅在蓝图变量定义包含默认值时返回。
+- 建议在调用 `blueprint.add_component` / `blueprint.set_property` 之前先 `blueprint.describe`，避免组件名/变量名写错。
+
+---
+
+## 创建蓝图资产 `blueprint.create`
+创建一个新的蓝图资产，支持指定父类、保存路径，以及在创建时直接添加组件。已实现蓝图重名检测，避免覆盖已有资产导致崩溃。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp1","method":"blueprint.create","params":{
+  "name":"BP_MyActor",              // 必填，蓝图名称
+  "parent_class":"Actor",           // 可选，父类（默认 Actor），支持短名或完整路径
+  "path":"/Game/Blueprints/BP_MyActor", // 可选，完整包路径
+  "folder":"/Game/Blueprints",      // 可选，保存目录（与 path 二选一，默认 /Game/UnrealAgent/Blueprints）
+  "components":[                    // 可选，创建时附带的组件列表
+    {
+      "component_type":"StaticMeshComponent",
+      "component_name":"MyMesh",
+      "attach_to":"root",           // 可选，附加到的父组件
+      "location":{"x":0,"y":0,"z":100},
+      "rotation":{"pitch":0,"yaw":0,"roll":0},
+      "scale":{"x":1,"y":1,"z":1},
+      "properties":{                // 可选，组件属性
+        "CastShadow":true
+      }
+    }
+  ]
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp1","code":200,"result":{
+  "ok":true,
+  "name":"BP_MyActor",
+  "path":"/Game/Blueprints/BP_MyActor.BP_MyActor",
+  "parent_class":"Actor",
+  "parent_class_path":"/Script/Engine.Actor",
+  "generated_class":"/Game/Blueprints/BP_MyActor.BP_MyActor_C",
+  "saved":true,
+  "components":[
+    {"name":"MyMesh","class":"StaticMeshComponent","class_path":"/Script/Engine.StaticMeshComponent","source":"added","editable":true,"attach_to":"DefaultSceneRoot"}
+  ],
+  "variables":[],
+  "compile_status":"Dirty",
+  "warnings":[]
+}}
+```
+
+### 说明
+- `parent_class` 支持短名（如 `Actor`、`Pawn`、`Character`）或完整类路径（如 `/Script/Engine.Actor`）。
+- 若蓝图已存在，返回 `code: 409` 冲突错误，需先删除或使用 `blueprint.add_component` 修改。
+- `components` 数组中每个组件会按顺序添加，`attach_to` 可指定父组件名称，留空或 `root` 则附加到根节点。
+- 创建完成后自动保存到磁盘并注册到 AssetRegistry。
+
+---
+
+## 为蓝图添加组件 `blueprint.add_component`
+为已存在的蓝图资产添加新组件，支持设置组件变换和属性。组件会被添加到蓝图的 SimpleConstructionScript 中。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp2","method":"blueprint.add_component","params":{
+  "blueprint_name":"BP_MyActor",    // 必填，蓝图名称或完整路径
+  "component_type":"PointLightComponent", // 必填，组件类型
+  "component_name":"MyLight",       // 必填，组件名称
+  "attach_to":"MyMesh",             // 可选，附加到的父组件名称（默认 root）
+  "location":{"x":0,"y":0,"z":200}, // 可选，相对位置
+  "rotation":{"pitch":0,"yaw":0,"roll":0}, // 可选，相对旋转
+  "scale":{"x":1,"y":1,"z":1},      // 可选，相对缩放
+  "component_properties":{          // 可选，组件属性
+    "Intensity":5000,
+    "LightColor":"(R=1,G=0.8,B=0.6,A=1)"
+  }
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp2","code":200,"result":{
+  "ok":true,
+  "blueprint_name":"BP_MyActor",
+  "blueprint_path":"/Game/Blueprints/BP_MyActor.BP_MyActor",
+  "component_name":"MyLight",
+  "component_class":"PointLightComponent",
+  "attached":true,
+  "saved":true,
+  "message":"Successfully added component 'MyLight' (PointLightComponent) to blueprint 'BP_MyActor'",
+  "all_components":[
+    {"name":"DefaultSceneRoot","class":"SceneComponent","class_path":"/Script/Engine.SceneComponent","source":"inherited","editable":true},
+    {"name":"MyLight","class":"PointLightComponent","class_path":"/Script/Engine.PointLightComponent","source":"added","editable":true,"attach_to":"DefaultSceneRoot"}
+  ]
+}}
+```
+
+### 说明
+- `blueprint_name` 支持短名（如 `BP_MyActor`）或完整路径（如 `/Game/Blueprints/BP_MyActor`）。
+- 若蓝图不存在返回 `code: 404`；若组件名称已存在返回 `code: 409`。
+- 仅 SceneComponent 及其子类支持 `location`、`rotation`、`scale` 设置。
+- `attach_to` 留空或设为 `root`/`DefaultSceneRoot` 则附加到根节点。
+- 添加完成后自动标记蓝图已修改并保存。
+
+---
+
+## 设置蓝图属性 `blueprint.set_property`
+修改蓝图资产的属性，支持两种模式：
+1. **CDO 模式**：`component_name` 为空时，修改蓝图类的默认值（Class Default Object）
+2. **SCS 模式**：`component_name` 有值时，修改蓝图中指定组件的属性
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp3","method":"blueprint.set_property","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Hero", // 必填，蓝图路径
+  "component_name":"PointLight",   // 可选，为空则修改 CDO，有值则修改组件
+  "properties":{                   // 必填，属性键值对
+    "Intensity":5000,
+    "LightColor":{"r":1,"g":0.8,"b":0.6}
+  },
+  "auto_compile":true              // 可选，默认 true
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp3","code":200,"result":{
+  "ok":true,
+  "blueprint_path":"/Game/Blueprints/BP_Hero.BP_Hero",
+  "blueprint_name":"BP_Hero",
+  "target_type":"component",
+  "component_name":"PointLight",
+  "modified_properties":[
+    {"property":"Intensity","type":"FloatProperty"},
+    {"property":"LightColor","type":"StructProperty"}
+  ],
+  "failed_properties":[],
+  "compiled":true,
+  "saved":true,
+  "message":"Successfully set 2 properties on component 'PointLight'"
+}}
+```
+
+### 说明
+- `blueprint_path` 支持短名或完整路径，会自动在 AssetRegistry 中查找。
+- 属性名需与 UE 中的属性名完全匹配（大小写敏感），失败时会返回建议属性名。
+- 支持的数据类型：基础类型（int/float/bool/string）、枚举、结构体（FVector/FRotator/FColor等）、对象引用。
+- 颜色属性：使用 0-1 浮点数格式 `{r,g,b,a}`，会自动转换为 0-255 格式。
+- 返回码：`200` 全部成功，`207` 部分成功，`400` 全部失败，`404` 蓝图或组件未找到。
+
+---
+
+## 编译蓝图 `blueprint.compile`
+手动触发蓝图编译，并可选在编译成功后保存（避免写入坏蓝图）。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp4","method":"blueprint.compile","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Hero", // 必填：蓝图名称或路径
+  "save":true                                 // 可选：默认 true，仅在编译成功时保存
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp4","code":200,"result":{
+  "ok":true,
+  "status":"UpToDate",
+  "saved":true,
+  "path":"/Game/Blueprints/BP_Hero.BP_Hero",
+  "diagnostics":[
+    {"type":"Warning","message":"Some warning message ...","node_id":"GUID-...","pin":"InString"}
+  ]
+}}
+```
+
+### 说明
+- `ok` 仅表示编译结果是否为 `UpToDate`；即使 `ok:false` 也会返回 `code:200`，可通过 `status` 判断（如 `Error`）。
+- `save` 只会在 `ok:true` 时执行保存。
+- `diagnostics` 用于 Agent 自修复：包含 `Error/Warning/Info` 等消息，尽可能附带 `node_id`（best-effort）。
+
+---
+
+## 添加蓝图变量 `blueprint.add_variable`
+添加蓝图成员变量（Blueprint Member Variable）。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp5","method":"blueprint.add_variable","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Hero",
+  "name":"Health",
+  "type":"float",
+  "is_array":false,
+  "default_value":"100.0"
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp5","code":200,"result":{
+  "ok":true,
+  "blueprint_path":"/Game/Blueprints/BP_Hero.BP_Hero",
+  "variable":{
+    "name":"Health",
+    "type":"float",
+    "is_array":false,
+    "default_value":"100.0"
+  }
+}}
+```
+
+### 说明
+- `type` 支持：`bool/int/int64/float/double/string/name/text/vector/rotator/color/linearcolor/object/class/soft_object/soft_class`
+- `object_class`：当 `type` 为 `object/class/soft_object/soft_class` 时可指定（如 `/Script/Engine.Actor`）。
+- 若变量已存在返回 `code:409`。
+
+---
+
+## 获取图表 `blueprint.get_graph`
+获取指定图表的节点与引脚元数据（**真实引脚名**），用于“感知优先”的连线编程。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp6","method":"blueprint.get_graph","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Greeter",
+  "graph_name":"EventGraph"
+}}
+```
+
+### 响应（节选）
+```json
+{"ver":"1.0","type":"res","id":"bp6","code":200,"result":{
+  "ok":true,
+  "blueprint_path":"/Game/Blueprints/BP_Greeter.BP_Greeter",
+  "graph_name":"EventGraph",
+  "nodes":[
+    {
+      "node_id":"GUID-...",
+      "class":"K2Node_Event",
+      "title":"Event BeginPlay",
+      "pos_x":0,"pos_y":0,
+      "pins":[{"name":"Then","dir":"Output","category":"exec","sub_category":"","is_array":false}]
+    }
+  ]
+}}
+```
+
+### 说明
+- `pins[].name` 是 **真实 pin 名**，`blueprint.connect_pins` 必须使用它，不要用 UI 的显示名/label。
+
+---
+
+## 添加节点 `blueprint.add_node`
+在图表中添加节点，并返回 pins 说明书（含真实引脚名）。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp7","method":"blueprint.add_node","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Greeter",
+  "graph_name":"EventGraph",
+  "node_type":"Function",
+  "node_name":"KismetSystemLibrary.PrintString",
+  "node_position":{"x":300,"y":0}
+}}
+```
+
+### 响应（节选）
+```json
+{"ver":"1.0","type":"res","id":"bp7","code":200,"result":{
+  "ok":true,
+  "blueprint_path":"/Game/Blueprints/BP_Greeter.BP_Greeter",
+  "graph_name":"EventGraph",
+  "node_id":"GUID-...",
+  "node_class":"K2Node_CallFunction",
+  "pins":[
+    {"name":"Exec","dir":"Input","category":"exec","sub_category":"","is_array":false},
+    {"name":"Then","dir":"Output","category":"exec","sub_category":"","is_array":false},
+    {"name":"InString","dir":"Input","category":"string","sub_category":"","is_array":false}
+  ]
+}}
+```
+
+### 说明
+- `node_type` 当前支持：`Event / Function / VariableGet / VariableSet`
+- `Event` 支持 `BeginPlay`（会自动映射为 `ReceiveBeginPlay`）。
+
+---
+
+## 连接引脚 `blueprint.connect_pins`
+根据 `node_id` + `pin.name` 连接执行流/数据流。
+
+### 请求（JSON-RPC）
+```json
+{"ver":"1.0","type":"req","id":"bp8","method":"blueprint.connect_pins","params":{
+  "blueprint_path":"/Game/Blueprints/BP_Greeter",
+  "graph_name":"EventGraph",
+  "source_node_id":"GUID-A",
+  "source_pin":"Then",
+  "target_node_id":"GUID-B",
+  "target_pin":"Exec"
+}}
+```
+
+### 响应
+```json
+{"ver":"1.0","type":"res","id":"bp8","code":200,"result":{
+  "ok":true,
+  "message":"Connection created"
+}}
+```
+