docs(agent): 添加 AgentBridge 自动化计划草案

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-01 17:44:37 +08:00
parent 660f8e24ee
commit 8f6616920c
1 changed files with 120 additions and 0 deletions
@@ -0,0 +1,120 @@
+# AgentBridge 计划草案
+
+> 状态：草案，待讨论后实施。  
+> 目的：让 Cursor Agent / Unity MCP 能自动到达可测状态、读取结构化运行时状态、做回归验证，减少手动 Play + 复现。
+
+## 背景
+
+当前 Agent 已可通过 **Unity MCP** 做：
+
+- Play / Stop、加载场景、查 GameObject / 组件
+- 读 Console、截图
+- 触发 Editor MenuItem（`execute_menu_item`）
+
+难以自动完成的部分：
+
+- 完整叙事流程（Persistence → 维修场景 → Yarn → 进模块）
+- UI 交互（Esc 开设置、点 log 面板等）
+- 缺乏结构化状态输出，debug 依赖临时埋点
+
+本项目已有大量可复用入口：`FixSystemCenter`、`EyeSystem`、`DialogController`、`UIManager`、各 `*YarnCommand`、`PeipeiFixCues`（如 `EyeCue.EnterImmediate`）等。AgentBridge 只做薄包装，不重写业务逻辑。
+
+## 目标
+
+1. **一键到可测状态** — 场景预设，而非暴露底层细节  
+2. **状态可查询** — JSON / Log，便于 Agent 自动验证  
+3. **Editor / Dev 专用** — `#if UNITY_EDITOR || DEVELOPMENT_BUILD`，不进 Release  
+4. **菜单路径稳定** — 供 MCP `execute_menu_item` 与文档引用
+
+## 阶段 1：最小可用（建议优先）
+
+| 项 | 内容 | 调用方式 |
+|---|---|---|
+| `AgentBridge.cs` | 静态薄包装 | — |
+| 场景预设 | `EnterPeipeiEyeModule()` → `EyeCue.EnterImmediate` | `Tools/Agent/Enter Peipei Eye Module` |
+| UI 操作 | `ToggleSettingPanel()`、`ToggleMainPanel()` | `Tools/Agent/Toggle Setting Panel` 等 |
+| 状态查询 | `DumpEyeOverlayState()` → 输出 layer / sortingOrder / active | `Tools/Agent/Dump Eye Overlay State` |
+| 文档 | 本文件 + 菜单清单维护 | Agent / `.cursor/rules` 引用 |
+
+### 建议 Editor 菜单（第一批）
+
+```
+Tools/Agent/Enter Peipei Eye Module
+Tools/Agent/Toggle Setting Panel
+Tools/Agent/Toggle Main Panel
+Tools/Agent/Dump Eye Overlay State
+```
+
+### 代码位置（待拍板）
+
+- 方案 A：`Assets/Scripts/Framework/AgentBridge/`（Runtime + `#if` 守卫）  
+- 方案 B：`Assets/Editor/Agent/`（仅 Editor，MenuItem 与 Bridge 同目录）
+
+## 阶段 2：常用模块覆盖（按需扩展）
+
+按实际 debug 频率扩展场景预设：
+
+| 模块 | 预设示例 | 复用 API |
+|---|---|---|
+| FixSystem | `TransitionTo(Eye / UF / Memory)`、`ResetCablePanel` | `FixSystemCenter` |
+| Eye | `EyeOverlayOn/Off`、`SetEyeTarget(name)` | `EyeSystem` |
+| Dialog | `StartDialogNode(nodeName)` | `DialogController` |
+| Save | `LoadTestSave("peipei_eye")` | `SaveSystem` / 固定测试档 |
+| Camera | `SwitchCamera(EyeDeep)` 等 | `CameraKit` |
+
+每个预设 = 一个 MenuItem + 一个 `AgentBridge` 方法 +（可选）一个 `GetXxxState()`。
+
+## 阶段 3：可验证 + 防回归
+
+| 项 | 用途 |
+|---|---|
+| `GetXxxState()` 返回 JSON | Agent 读 Console / 文件验证，少依赖截图 |
+| PlayMode Tests | 如 overlay UI 层、sortingOrder、Dialog 不被挡 |
+| MCP `run_tests` | UI / 渲染相关改动后自动跑 |
+
+### 示例：Eye Overlay 状态结构
+
+```json
+{
+  "overlayActive": true,
+  "canvasLayer": 5,
+  "sortingOrder": 0,
+  "sortingLayer": "StartUI",
+  "worldCamera": "UI Camera",
+  "layerVisibleToCamera": true
+}
+```
+
+## 设计原则
+
+1. **只包装，不重写** — 调用现有 public API  
+2. **场景预设 > 原子命令** — 优先「一键到眼动模块」  
+3. **状态可查询** — 每个常 debug 模块至少一个 `GetState()` / `Dump*()`  
+4. **不进入 Release** — 编译条件守卫 + 不进 Addressables  
+5. **菜单路径稳定** — 变更需同步更新本文档
+
+## 待讨论问题
+
+1. **代码放哪**：`Framework/AgentBridge` 还是 `Editor/Agent`？  
+2. **测试存档**：是否需要固定 PlayMode 存档 slot，还是每次冷启动场景？  
+3. **第一批优先级**：眼动 / 插线 / 对话 / 记忆 — 哪个最常需要 Agent 介入？  
+4. **是否写入 `.cursor/rules`**：固定 MenuItem 清单，让 Agent 默认走 Bridge 流程？  
+5. **与现有 Editor 工具关系**：如 `EyeSystemEditor` 预览 — 合并还是并存？
+
+## 参考：Persistence UI 层级
+
+Eye 视口遮罩修复后的约定（`EyeViewportOverlay`）：
+
+| Canvas | sortingOrder | 说明 |
+|---|---|---|
+| EyeViewportOverlay | 0 | 遮罩，不挡系统 UI |
+| UI Canvas | 1 | 设置、MainPanel、PlayTool 等 |
+| Dialog Canvas | 3 | 对话 |
+
+Overlay 使用 `ScreenSpaceCamera` + UI Camera，Canvas 须在 **UI 层 (5)** 以匹配 UI Camera culling mask。
+
+## 变更记录
+
+| 日期 | 说明 |
+|---|---|
+| 2026-07-01 | 初稿：overlay debug 后整理 Agent 自动化计划 |