121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# 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 自动化计划 |
|