Genarrative/plugins/agc-cocos-editor

agc-cocos-editor

Cocos Creator 编辑器桥接插件。用户侧看到的是一个普通 AGC 插件：插件生命周期、UI、 RPC、权限和能力注册全部由通用宿主负责，只有“如何连接 Cocos Creator”属于本插件。

它同时是 AGC 的内置插件：随客户端分发、不能卸载。只有当前受控目录被识别为 Cocos Creator 项目时才会暴露插件、面板和工具；切换到其它项目会立即停止插件实例并隐藏对应能力。 用户在运行时设置里只能切换“是否可用”，禁用后插件不能启动，agc_cocos_execute 与全部 cocos_* Agent 工具也会从 Agent 工具列表、工具策略快照和上下文里消失；重新启用后仍需 满足当前项目是 Cocos 的门禁。

Cocos Creator 项目目录中的 extensions/、package.json 插件声明或第三方 MCP 包不属于 AGC Cocos 桥接来源。Agent 处理 Cocos 请求时只使用客户端登记的 agc-cocos-editor 内置插件；内置工具不可用时报告客户端插件状态，不扫描或要求用户启动项目内 MCP 扩展。

plugin.json                      Agent Plugins 清单 + AGC Runtime 扩展
src/entry.mjs                    运行时入口（注册命令 / 能力 / 面板，转发 host.rpc）
src/cocos-editor-adapter.mjs     通用请求 → Cocos 适配器请求的翻译与入参校验
src/operations/                  36 个操作的 schema、主进程/场景/预览实现
src/cocos-editor-operations.mjs  插件侧构造器，与 native 编译内置代码一致
panels/cocos-editor.html         自包含面板
native/cocos-editor-bridge/      插件自带 native 模块（进程发现、pipe 协议、注入）

Runtime 契约

项	值
协议	agc.plugin.v1（stdio 行分隔 JSON-RPC 2.0）
适配器 id	cocos-editor
命令	cocos.editor.execute（{ code }）
操作命令	cocos.editor.operation（{ operation: "cocos_*", args: {...} }）
Agent MCP	agc_cocos_execute + catalog.json 的全部 36 个 cocos_* 工具
能力	cocos.editor.connection（{ operation, processId?, projectPath?, timeoutMs? }）
面板	cocos-editor（panels/cocos-editor.html，sidebar）

operation 取值为 detect、connect、disconnect、prepare、ping、status、 execute、inject，与 native 适配器的 COCOS_EDITOR_RPC_METHODS 一一对应； src/entry.test.mjs 会校验两边不会漂移。

Agent 能力与 JavaScript 用法

Agent 通过 agc_cocos_execute 注入 JavaScript 函数体；插件只负责把代码安全地送进 已校验的 Creator 主进程，不在项目目录写入扩展。常用的 Creator 3.8.8 操作如下：

客户端还注册了 cocos.editor.operation 操作命令。它把第三方 MCP 的 36 个稳定操作名 暴露给宿主；DirectProject 的 agc_tools 同时从该目录注册 36 个独立工具。两者使用相同 schema 和内置 JS，并在执行时走同一个受控 editor.execute 通道：

cocos_ping / cocos_get_capabilities / cocos_get_project_info
cocos_get_current_scene_meta / cocos_get_log_tail / cocos_diagnose
cocos_get_build_diagnostics / cocos_list_assets / cocos_get_prefab_info
cocos_get_hierarchy / cocos_search_nodes / cocos_inspect_node
cocos_set_node_active / cocos_set_node_transform / cocos_set_node_name
cocos_create_node / cocos_delete_node / cocos_reparent_node
cocos_set_node_sibling_index / cocos_duplicate_node / cocos_instantiate_prefab
cocos_set_component_property / cocos_add_component / cocos_remove_component
cocos_create_ui_shape / cocos_create_ui_label / cocos_create_ui_sprite
cocos_create_ui_button / cocos_apply_ui_spec
cocos_preview_debug_start / cocos_preview_debug_read / cocos_preview_debug_capture
cocos_preview_debug_stop / cocos_save_scene / cocos_editor_undo / cocos_mcp_undo_last

场景操作由主进程定位唯一 Scene WebView，将随包 JS 加载到该运行时，调用 Creator 场景管理器 与 require('cc') 的引擎 API；保存和资源导入使用官方 Editor.Message。不安装项目扩展。

cocos_get_hierarchy 返回 { sceneUuid, tree, truncated }，节点含 nid/uuid；写工具的 nid/parentNid/childNid 均支持查询得到的 NID 或 UUID。cocos_inspect_node 返回带真实索引的 组件属性。场景切换后旧 NID 不复用，需重新查询。

批量 UI 支持 container/shape/label/sprite/button、Layout、Widget、九宫格，限制为 64 个节点和 12 层（按钮文字计入节点数）。Shape 使用 AssetDB 导入的 assets/agc-ui-shapes/ PNG 模板； 它是可复用资产缓存，撤销节点不会删除模板。save 缺省 true，运行态回读和保存失败都会明确报告。 首次保存缺省创建 assets/Main.scene，也可通过 cocos_save_scene { path } 指定新路径。

编辑事务保留前后序列化快照（单份 2 MiB、最多 32 次、合计 16 MiB）。MCP 撤销只在当前场景仍 等于对应后状态时恢复，已保存事务的撤销同步保存。代码更新、Creator 重启和切换场景不保留撤销历史。 cocos_editor_undo 使用官方 undo；最近操作属于本插件时额外核对恢复结果。

预览在插件自有、无 Node 权限的独立 Chromium 窗口运行，只接收当前 Creator 项目预览端口的 loopback URL。采集 console、JS 异常、网络失败及 HTTP 错误，截图作为 MCP PNG image 返回； stop 只关闭该窗口。日志只读项目 temp/logs/、temp/builder/、build/ 下的日志文件。

所有操作仍受项目身份校验、单执行队列和不确定结果禁止重放约束。实现按 Creator 3.8.8 核验； 其它 3.x 版本中缺少对应运行时 API 时会报告错误，不虚报能力已执行。

目的	示例
读取场景树	return await Editor.Message.request('scene', 'query-node-tree');
读取节点	return await Editor.Message.request('scene', 'query-node', uuid);
修改属性	优先 cocos_set_component_property；原始 scene/set-property 需要从 query-node 克隆并修改属性 dump
添加组件	return await Editor.Message.request('scene', 'create-component', { uuid, component });
执行场景脚本	return await Editor.Message.request('scene', 'execute-scene-script', { name, method, args });
查询资源	return await Editor.Message.request('asset-db', 'query-asset-info', uuid);

先执行只读查询取得真实节点 UUID、组件标识和属性路径，再执行单个修改并回读校验。 不要猜 UUID、组件 CID 或属性路径；需要保存、删除或批量修改时，先确认对应 Creator 消息协议，再通过同一入口逐步执行。

execute 不接受并发积压。结果不确定时返回 needs-reconciliation 与 retryAllowed: false 并阻止后续发送；native 适配器的阻断不会被 disconnect 或插件进程重载清除。请先核对编辑器状态，再重启客户端恢复。

项目上下文

插件从宿主获得当前受控项目路径：

• 注册 host.events.subscribe { type: 'project.changed' } 时，宿主在响应里返回当前 projectPath。
• 之后宿主设置项目时推送 project.changed 事件，payload 带 projectPath。

插件不缓存凭据；资源与日志只在当前受控项目内有界读取。编辑器操作经 host.rpc 交给 native 适配器， 由适配器做 PID / 项目 / 版本校验。

Native 模块

native/cocos-editor-bridge 是从 AGC 服务端源码树移入本插件包的独立 crate，实现 editor-adapter-api::EditorAdapter：

• process-discovery：只把 CocosCreator.exe 主进程的 PID、--project 和 Creator 版本绑定起来，排除 Electron 子进程。
• windows-transport：注入后通过 named pipe 提供 ping/status/execute，执行结果 不确定时返回 ExecutionUncertain 并禁止自动重放。
• windows-injection：随包 DLL 的 Windows 注入实现，默认关闭。
• windows-bootstrap：在首次 connect/execute 前经目标 PID 的 Node Inspector 安装内置 bootstrap，验证 pipe 握手并关闭本次开启的 Inspector；保留已有调试会话。

AGC 客户端当前在编译期链接本 crate（Cargo path 依赖），由通用宿主按 manifest 的 adapter 字段注册；宿主源码里没有 Cocos 进程名、注入或 Editor.Message 逻辑。

本地验证

cargo test --manifest-path plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml
cargo test --manifest-path plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml --features windows-bootstrap -- --include-ignored
npm test --prefix plugins/agc-cocos-editor

真实 Creator 验收（注入、Inspector 引导、非空场景读写）仍按 docs/technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md 单独执行。