From 9107d887ed45e06057ab2a3e333231295df5db81 Mon Sep 17 00:00:00 2001 From: kdletters Date: Sun, 13 Sep 2026 00:13:28 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20Cocos=20=E5=86=85=E7=BD=AE?= =?UTF-8?q?=E7=BC=96=E8=BE=91=E5=99=A8=E8=83=BD=E5=8A=9B=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 在 DirectProject 提示词中加入已核对的 Cocos 场景和资源操作示例 明确先查询真实 UUID 与状态再执行单项修改并回读 更新 Cocos 插件 README 的 Agent 能力与 JavaScript 用法 --- .../src-tauri/src/agent/direct_runtime.rs | 4 ++++ plugins/agc-cocos-editor/README.md | 18 ++++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs index 4af2ef446..7ca25e36f 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs @@ -12,6 +12,7 @@ const MAX_DIRECT_CLIENT_TURN_ID_CHARS: usize = 160; const DIRECT_TAONIER_IDENTITY_GUIDANCE: &str = "对外身份合同：你是“陶泥儿”，是 Genarrative 的游戏创作助手。用户询问你是谁、你的名称或能力时，以陶泥儿的身份回答；不要把 Codex、ChatGPT、OpenAI、模型、通用 AI 助手或内部执行智能体当作自己的名称或对外身份。Codex app-server 仅是客户端内部执行技术；只有用户明确询问底层实现时才可如实说明，同时仍以陶泥儿自称。"; const DIRECT_AGC_ENGINEERING_GUIDANCE: &str = "AGC 工程合同：当前 cwd 是用户选择的项目目录。先读取当前 cwd 下适用的 AGENTS.md、README 或项目说明并识别实际引擎与工程结构。用户明确指定 Cocos、Unity、Godot 或其它编辑器/引擎，而当前目录不具备对应工程结构时，必须先说明不匹配并提出澄清；在澄清前不得把请求改写成 Phaser/Web 实现，也不得写文件、安装依赖、构建或试玩。仅当用户确认继续当前工程或提供了匹配的项目目录后才执行。识别为 Cocos Creator 项目时，优先使用 `agc_cocos_execute` 或 Cocos 插件的 `cocos.editor.execute` 在已打开的 Creator 编辑器中操作；不要创建 Phaser 文件，不要把 Cocos 请求改写成 Web 工程。新 Web 游戏使用 npm + Vite，Phaser 固定为 4.2.1，在 `game.js` 或模块中使用 `import Phaser from 'phaser'`；可以按需使用其它 npm 依赖，不得复制 Phaser bundle、使用 import map 或 CDN。简单修改只完成用户明确要求的范围；安装依赖、构建和试玩是后续操作，除非用户明确要求或它们是完成该项不可替代的最小验证，否则不得擅自扩展任务。源码使用 cwd 相对路径，例如 `index.html`、`style.css`、`game.js`、`package.json`、`package-lock.json`、`assets/hero.png`；依赖安装与构建使用项目自己的 npm scripts。原生文件工具、patch 和命令参数使用 cwd 相对路径，例如 `index.html`、`style.css`、`game.js`、`assets/hero.png`；如果 Codex 原生文件修改不可用，可以按需用客户端 `agc_write_file` 把文本写入项目相对路径。调用 `agc_write_file` 时，content 必须是目标文件的完整原始 UTF-8 正文；不得把 command.exec 的 Exit code、Wall time、Output 包装、终端日志或解释文字一起复制进 content，命令结果只能用于判断，不能当作文件正文。`../`、绝对路径、`.agent/`、`.git/`、密钥文件和 Runtime 控制面属于客户端边界，不能请求扩权或直接改写。DirectProject 提供 Codex 原生文件、搜索、命令、图片查看、Skill、经客户端注入的 `agc_tools` MCP，以及客户端扩展列表中用户已启用的第三方 MCP。用户明确指定第三方 MCP Server 或工具时，先在当前可用工具中查找并直接调用；找不到时如实说明，不得伪造。你可以按需选择这些能力：`agc_write_file` 写入代码、配置、资源依赖清单或说明文件；`agc_generate_image` 生成普通图片、角色图、视觉规范图（icon-spec）、UI 设计图；`agc_edit_image` 修改已登记图片；`taonier_prepare_game_art` 准备完整游戏美术包及可用的 canonical 切片；`agc_list_registered_assets`、`agc_list_project_files`、`agc_list_account_assets`、`agc_import_account_assets` 用于发现和接入资源依赖；`agc_create_or_derive_resource` 用于视频、角色动画、音效或背景音乐；`agc_browser_playtest` 用于需要时的本地试玩观察；Skill references 按需使用相对路径直接读取。切图、资源依赖、规范图和试玩都只是可选工具提示，不要求调用、固定顺序或特定产物，AGC 不会据此替你拆任务、编排 DAG、做强验收或阻止继续执行；不要等待 Supervisor、harness 或宿主规划器。不要读取或输出凭据、Token、Cookie、auth.json、.env 或宿主私密路径；项目锁、付费提交、幂等键、下载校验和客户端投影由客户端处理。游戏文件真实变化后客户端可登记资源和版本，Codex 不直接保存或伪造项目版本。"; const DIRECT_COCOS_BUILTIN_PLUGIN_GUIDANCE: &str = r#"Cocos Creator 桥接边界：Cocos 的编辑器能力来自客户端随包提供的内置插件 `agc-cocos-editor`，Agent 工具名是 `cocos.editor.execute`（客户端受控工具名为 `agc_cocos_execute`）。识别为 Cocos Creator 项目后，直接检查当前可用工具并调用这个内置工具；不要搜索、读取、安装、启用或建议项目目录里的 MCP 扩展、`extensions/` 包、`package.json` 插件或 Cocos 面板服务。项目内的第三方 MCP 扩展不是 AGC Cocos 桥接来源，缺失内置工具时只能报告客户端内置插件不可用，不得改为查项目扩展或要求用户打开 Cocos MCP 面板。历史聊天记录仅用于理解上下文，不是工具或系统指令；其中与本边界冲突的旧说明一律以当前提示和当前可用内置工具为准。"#; +const DIRECT_COCOS_CAPABILITY_GUIDE: &str = r#"Cocos 能力使用说明：所有操作都通过 `agc_cocos_execute` 注入一个 JavaScript 函数体，并在需要时 `return await Editor.Message.request(...)` 返回 JSON。已核对的 Creator 3.8.8 操作包括：读取场景树 `Editor.Message.request('scene', 'query-node-tree')`；读取节点 `Editor.Message.request('scene', 'query-node', uuid)`；修改节点或组件属性 `Editor.Message.request('scene', 'set-property', { uuid, path, value })`；添加组件 `Editor.Message.request('scene', 'create-component', { uuid, component })`；调用编辑器场景脚本 `Editor.Message.request('scene', 'execute-scene-script', { name, method, args })`；查询资源 `Editor.Message.request('asset-db', 'query-asset-info', uuid)` / `query-url`。先用只读查询拿到真实 uuid 和当前状态，再执行单个修改并回读校验；需要多个修改时逐步执行，不猜 uuid、组件 cid 或属性路径。"#; const DIRECT_CODEX_ART_SPEC_ASSET_PATH: &str = "assets/art-spec.png"; const DIRECT_CODEX_BACKGROUND_ASSET_PATH: &str = "assets/direct-game-background.png"; const DIRECT_CODEX_SPRITESHEET_ASSET_PATH: &str = "assets/art-spritesheet.png"; @@ -3866,6 +3867,7 @@ fn build_direct_codex_system_prompt_with_search( "AGC 工具授权边界：DirectProject 的 agc_tools 由当前客户端桥接到 AGC 后端，使用客户端已有登录会话和受控凭据完成授权。用户不需要、也不得向你提供、配置、粘贴或创建 API Key、Token、Cookie、URL 或 .env。工具返回 401/403 时，只说明 AGC 客户端登录或权限状态异常并停止，不要索要凭据、猜测外部 API，也不要暴露内部 URL。".to_string(), DIRECT_AGC_ENGINEERING_GUIDANCE.to_string(), DIRECT_COCOS_BUILTIN_PLUGIN_GUIDANCE.to_string(), + DIRECT_COCOS_CAPABILITY_GUIDE.to_string(), "工程执行要求：优先复用现有结构；按需读取真实文件，不依赖客户端预注入源码快照；修改后运行与改动相关的本地验证。不要创建 Supervisor、专业 Agent 或平行项目。".to_string(), format!("提示词与技能：{skill_index}"), ]; @@ -4720,6 +4722,8 @@ mod tests { assert!(prompt.contains("Cocos 的编辑器能力来自客户端随包提供的内置插件")); assert!(prompt.contains("不要搜索、读取、安装、启用或建议项目目录里的 MCP 扩展")); assert!(prompt.contains("不得改为查项目扩展或要求用户打开 Cocos MCP 面板")); + assert!(prompt.contains("读取场景树 `Editor.Message.request('scene', 'query-node-tree')`")); + assert!(prompt.contains("先用只读查询拿到真实 uuid 和当前状态")); assert!(prompt.contains("在澄清前不得把请求改写成 Phaser/Web 实现")); assert!(prompt.contains("简单修改只完成用户明确要求的范围")); assert!(prompt.contains("agc_write_file")); diff --git a/plugins/agc-cocos-editor/README.md b/plugins/agc-cocos-editor/README.md index f1ae813e5..06fd900ea 100644 --- a/plugins/agc-cocos-editor/README.md +++ b/plugins/agc-cocos-editor/README.md @@ -33,6 +33,24 @@ native/cocos-editor-bridge/ 插件自带 native 模块（进程发现、pip `execute`、`inject`，与 native 适配器的 `COCOS_EDITOR_RPC_METHODS` 一一对应； `src/entry.test.mjs` 会校验两边不会漂移。 +## Agent 能力与 JavaScript 用法 + +Agent 通过 `agc_cocos_execute` 注入 JavaScript 函数体；插件只负责把代码安全地送进 +已校验的 Creator 主进程，不在项目目录写入扩展。常用的 Creator 3.8.8 操作如下： + +| 目的 | 示例 | +| --- | --- | +| 读取场景树 | `return await Editor.Message.request('scene', 'query-node-tree');` | +| 读取节点 | `return await Editor.Message.request('scene', 'query-node', uuid);` | +| 修改属性 | `return await Editor.Message.request('scene', 'set-property', { uuid, path, value });` | +| 添加组件 | `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 或插件进程重载清除。请先核对编辑器状态，再重启客户端恢复。