Files

T

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

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-01 17:44:37 +08:00

4.5 KiB

Raw Blame History

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 只做薄包装，不重写业务逻辑。

目标

一键到可测状态 — 场景预设，而非暴露底层细节
状态可查询 — JSON / Log，便于 Agent 自动验证
Editor / Dev 专用 — #if UNITY_EDITOR || DEVELOPMENT_BUILD，不进 Release
菜单路径稳定 — 供 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 状态结构

{
  "overlayActive": true,
  "canvasLayer": 5,
  "sortingOrder": 0,
  "sortingLayer": "StartUI",
  "worldCamera": "UI Camera",
  "layerVisibleToCamera": true
}

设计原则

只包装，不重写 — 调用现有 public API
场景预设 > 原子命令 — 优先「一键到眼动模块」
状态可查询 — 每个常 debug 模块至少一个 GetState() / Dump*()
不进入 Release — 编译条件守卫 + 不进 Addressables
菜单路径稳定 — 变更需同步更新本文档

待讨论问题

代码放哪：Framework/AgentBridge 还是 Editor/Agent？
测试存档：是否需要固定 PlayMode 存档 slot，还是每次冷启动场景？
第一批优先级：眼动 / 插线 / 对话 / 记忆 — 哪个最常需要 Agent 介入？
是否写入 .cursor/rules：固定 MenuItem 清单，让 Agent 默认走 Bridge 流程？
与现有 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 自动化计划

4.5 KiB Raw Blame History Unescape Escape