# 🎮 Game Agent｜Cocos Creator 游戏开发智能体 > 🚀 **不只是写代码，直接把游戏做出来。** Game Agent 直接运行在 Cocos Creator 中。告诉它你的想法，它可以读项目、写脚本、搭场景、改组件、运行预览、操作游戏并检查结果。 **从一句需求出发，持续开发、预览和验证，直到得到可玩的游戏。** ![不只是写代码，直接把游戏做出来](https://download.cocos.com/CocosStore/resource/29f3863788674824bf0678db5f0ddf14/29f3863788674824bf0678db5f0ddf14.png) --- ## ✨ 核心优势 ### 🧠 实时压缩，节省 Token 游戏开发往往需要几十次工具调用。如果每一步都重复发送完整节点树、日志和历史消息，Token 会快速上涨。 Game Agent 通过“按需加载工具 + 三层实时压缩”控制上下文： | 当前实测 | 数据 | | ---------------- | ------------------: | | 常规工具全部常驻 | 41,584 token / step | | 默认按需激活 | 15,249 token / step | | 单 step 减少 | 26,335 token | | 降幅 | **63.3%** | 当会话继续变长时，L0/L1/L2 会分层压缩旧工具结果、生成结构化上下文包，并在接近上限时建立任务交接文档。 ### 👁️ 强感知：同时理解代码、编辑器与游戏在常见的代码仓库工作流中，通用代码智能体首先看到的是文件和终端；而 Game Agent 能直接感知 Cocos 编辑器与游戏运行状态。 - **编辑器感知**：当前 Scene/Prefab、节点树、组件、属性、资源 UUID、控制台。 - **脚本感知**：TypeScript 诊断、定义、引用和 Cocos 组件关系。 - **运行时感知**：游戏场景树、节点、组件、文字、测试状态和检查点。 - **问题感知**：浏览器日志、网络失败、性能摘要和失败截图。它不只判断“代码写正确没有”，还可以继续确认“场景树是否正确、角色能否移动、关卡能否通过、控制台是否报错”。 ### 🛡️ 大模型护栏：用确定性规则约束不确定性大模型擅长理解开放需求、规划步骤和生成内容，但输出天然具有不确定性。Game Agent 将大模型的灵活性与确定性的工程规则结合，在会话、消息、输出和工具执行等关键边界持续检查，防止任务跑偏。 - **防止提前结束**：任务清单尚未完成时，要求智能体继续推进，而不是直接宣布完成。 - **防止未经验证**：修改 Scene 或 Prefab 后，要求通过只读查询、控制台、预览或截图复验关键结果。 - **防止遗漏结论**：工具执行完成但没有面向用户的最终答复时，触发纠偏并补全结果说明。确定性规则负责守住底线，大模型负责处理开放问题。二者结合，可以减少漏步骤、误完成和未验证交付，提高任务准确性与完成质量。 ### 🔁 游戏开发闭环：从需求到验证持续迭代脚本、场景和测试在同一个任务里连续完成：

Game Agent 从需求到验证的游戏开发闭环

### 🧰 开箱即用：工具、智能体与知识一体化 - 提供 **71 个工具**，覆盖项目读取、脚本开发、编辑器操作、游戏测试与问题诊断。 - 内置 **4 个专项子智能体**，分别负责调研、代码分析、任务执行和测试验证。 - 内置 Cocos Creator 3.8 文档技能，包含 **219 份 Markdown 知识文件**，补足大模型的引擎知识盲区。

Game Agent 工具、智能体与知识能力

--- ## ⚖️ 产品对比 Codex、Claude Code 等产品是优秀的通用代码智能体，擅长读取代码库、修改文件和运行命令。Game Agent 的区别，是把 Cocos 游戏开发需要的引擎操作和测试闭环直接做进插件。 | 对比项 | Game Agent | 通用代码智能体的默认方式 | | ---------- | ------------------------------------------ | ------------------------------------ | | 使用入口 | Cocos Creator 内置面板 | 终端、IDE、桌面端或网页 | | Cocos 场景 | 直接操作 Scene、Prefab、节点、组件和属性 | 通常从文件理解，深度操作需要额外接入 | | 脚本开发 | 结合场景结构与 Cocos TypeScript 语义 | 通用代码编辑与命令执行 | | 游戏测试 | 连接本地预览，按节点点击、输入、等待和断言 | 通常需要另配测试脚本或浏览器工具 | | 问题诊断 | 串联编辑器、浏览器、网络、性能和截图 | 依赖项目已有日志与用户提供现场 | | Cocos 知识 | 内置 Creator 3.8 文档技能 | 依赖通用知识、联网资料或自建技能 | | 开发闭环 | 场景、脚本、测试已打通；素材生成规划中 | 以代码和命令任务为主，可自行扩展 | Game Agent 不是要替代所有代码智能体，而是让 Cocos 开发者少做上下文搬运，少在多个工具之间来回切换。 --- ## 💻 兼容性与模型支持 | 项目 | 要求 | | ------------- | --------------------------------------- | | Cocos Creator | 3.8.x（最低 3.8.0） | | MCP | 部分服务需要 Node.js 18+ 或对应运行环境 | | 游戏预览测试 | 需要 Node.js 20 与 Chromium | 当前模型目录覆盖 **9 家提供商、29 个模型条目**：OpenAI、Anthropic、Google、DeepSeek、xAI、Mistral、Alibaba、Moonshot AI 和智谱。实际可用模型以插件内目录、API Key 和服务状态为准。模型费用由对应服务商收取。重要项目建议使用 Git，并保留人工验收。

Game Agent 模型配置界面

--- ## 🗺️ 产品路线图以下是产品方向，不代表固定发布日期。 ### ✅ 已上线 - 场景、节点、组件与预制体操作。 - TypeScript 编写与语义诊断。 - 本地预览自动化与游戏运行时查询。 - 日志、网络、性能、截图与测试产物。 - `AGENTS.md`、项目记忆与任务记忆。 - 技能、MCP、多智能体与工具权限。 - L0/L1/L2 上下文压缩与用量分析。 ### 🎨 素材生成（规划中） - 角色、场景、UI、图标和贴图生成。 - 自动导入、命名、切图和基础资源设置。 - 保持同一项目的画风、角色和尺寸一致。 - 生成素材直接进入 Scene、Prefab 和脚本引用流程。 ### 🪝 Hooks（规划中） - 任务开始/结束 Hooks。 - 工具调用和文件修改前后 Hooks。 - 构建、测试与发布门禁。 ### 🚀 持续建设 - 更多技能与专项智能体。 - 长任务稳定性与准确度提升。 - 更少的 Token 消耗。 --- ## 🧩 功能一览 | 功能 | 能做什么 | 基本用法 | | ------------ | ------------------------------------------- | -------------------------------- | | 多会话工作台 | 多个任务并行运行，状态互不串线 | 新建会话或切换会话标签 | | 场景与预制体 | 创建、打开、保存、查询和修改 | 直接描述目标节点、组件和验收结果 | | 脚本开发 | 读写文件、诊断 TypeScript、查询定义与引用 | 要求“修改后诊断并验证” | | 游戏测试 | 点击、输入、按键、等待场景/节点/文字/检查点 | 先启动 Cocos 浏览器预览 | | 调试诊断 | 查询日志、网络失败、性能和截图 | 失败时要求先收集证据 | | 资源与项目 | 查询资源、元数据、文件、控制台和项目设置 | 说明资源路径或目标类型 | | 联网与命令 | 搜索最新资料，执行构建、测试和临时脚本 | 在工作模式下按权限执行 | | 项目记忆 | 保存稳定知识与开发经验 | 让智能体记录或检索项目经验 | | 任务记忆 | 维护步骤、进度和验收状态 | 复杂任务开始时创建任务清单 | | 权限与回滚 | 审批危险操作，查询或回滚事务快照 | 在“设置 → 工具”配置权限 | --- ## 🧰 深入能力以下能力可按项目需要独立配置，并在复杂任务中组合使用。 ### 📏 项目规则在 Cocos 项目根目录创建 `AGENTS.md`，用来记录长期有效的开发规则。主智能体和子智能体都会在请求前读取它，修改后下一次请求立即生效。 ```md # 项目规则 - Cocos Creator 版本固定为 3.8.x。 - 运行时脚本统一放在 assets/scripts/。 - 修改 Scene 或 Prefab 后必须保存并重新读取关键属性。 - 完成功能后必须启动浏览器预览验证。 - 不得删除 assets/art/source/ 下的原始素材。 ``` 当前版本只读取**项目根目录**的 `AGENTS.md`。规则文件不能绕过工具权限、审批和安全边界。 ### 🎯 技能技能用于封装可重复的专项流程，可以包含说明、参考资料、脚本和资源。 | 来源 | 位置 | | -------- | ------------------------------------- | | 内置技能 | 随 Game Agent 提供 | | 项目技能 | `.gameagent/skills/<技能名>/SKILL.md` | | 插件技能 | 由其它 Cocos 插件声明 | 技能支持三种模式： - **关闭**：不可见，不占上下文。 - **手动**：在输入框明确选择后加载。 - **自动**：平时只加载名称和简介，需要时再读取完整内容。最小示例： ```md --- name: level-acceptance displayName: 关卡验收 description: 用于关卡完成后的保存、重开、运行与截图验收。 metadata: game-agent: invocation: manual --- # 关卡验收 1. 保存并重新打开场景。 2. 核对关键节点和组件。 3. 启动预览并执行主路径。 4. 查询错误日志并保存截图。 ``` 保存后在 **设置 → 技能** 中选择调用方式。 ### 🔌 MCP MCP 用于连接外部工具和数据。当前支持 command/stdio、Streamable HTTP 和 SSE，可使用服务提供的工具、资源、资源模板和 Prompt。 **使用步骤：** 1. 打开 **设置 → MCP → 设置 MCP**。 2. 填写项目级 JSON 并保存。 3. 检查连接状态和能力数量。 4. 为服务选择关闭、手动审批或自动使用。 ```json { "mcpServers": { "myTool": { "permission": "manual", "command": "/absolute/path/to/mcp-server", "args": ["--project", "."] } } } ``` MCP 在独立 Helper 中运行。Token、Headers、环境变量等敏感字段不会直接暴露给面板或模型。本地 command、`npx`、`uvx` 服务仍需确认来源可信。 ### 🤖 智能体 Game Agent 内置四种分工： | 智能体 | 职责 | | -------- | ---------------------------- | | 深度调研 | 搜索资料和归纳证据 | | 代码分析 | 追踪调用链和影响范围 | | 任务执行 | 修改项目、操作编辑器并验证 | | 测试验证 | 运行测试、复现失败和整理证据 | 在 **设置 → 智能体** 中可以新建自定义智能体，并配置模型、工具白名单、MCP、提示词和超时。也支持其它 Cocos 插件提供智能体。使用时可以在输入框明确选择，也可以让主智能体按任务委派。子任务使用独立上下文，主会话只接收有界结论。示例： > 先让代码分析智能体检查角色控制链路，再让任务执行智能体修改，最后让测试验证智能体跑预览。每一步都返回可核对证据。

Game Agent 智能体配置 Game Agent 智能体执行状态

### 🗜️ 上下文压缩 | 层级 | 触发方式 | 作用 | | ---- | ----------------------------- | ------------------------------------------ | | L0 | 首次达到 60 个 assistant part | 保留前后各 20 个，将中间 20 个本地压缩 | | L1 | 活跃上下文接近模型上限 75% | 生成结构化 Context Pack，保留最近 5 轮原文 | | L2 | L1 已执行 3 次后再次接近阈值 | 生成持久化 Handoff，从清晰任务状态继续 | L0 不调用额外模型。L1/L2 会保留目标、硬性要求、事实、决策、未完成工作、风险和测试状态。原始聊天历史与事实来源不会因压缩被删除。在 **设置 → 上下文** 中可以查看： - 活跃 Token 与模型上限。 - 压缩比例。 - L0/L1/L2 执行次数。 - 会话、工具、项目规则、记忆和 MCP 等上下文分类。

Game Agent 上下文压缩与用量分析

--- ## 🚀 快速开始 1. 从 Cocos 商城安装插件。 2. 打开 **项目 → 项目设置 → 游戏智能体**，配置至少一家 Provider 的 API Key。 3. 通过 **扩展 → 游戏智能体（Game Agent）** 打开面板。 4. 选择模型、推理强度，以及“探讨”或“工作”模式。 5. 输入一个结果可验证的任务。第一次可以这样说： > 先读取当前场景和项目脚本，告诉我项目现在能运行到哪一步。不要修改文件。给出一个最小计划，每一步写明验证方式。确认后进入工作模式： > 完成计划第一步。保存场景，做 TypeScript 诊断，并启动浏览器预览验证。失败时先收集日志和截图。 --- ## 🔐 权限与安全每个工具都可以在 **设置 → 工具** 中配置： - **关闭**：模型不可见，也不占工具上下文。 - **审批**：每次调用前确认。 - **同意**：无需确认，但保留内部安全检查。 - **自动**：根据风险决定，删除、回退等操作需要确认。项目路径限制、参数校验、事务冲突和工具内部规则始终生效。场景和文件操作支持事务记录，必要时可查询或回滚。 --- ## ❓ 常见问题 ### Q1｜会擅自删除文件吗？危险操作受权限和审批控制，文件与编辑器工具还有路径限制和事务保护。正式项目仍建议使用 Git。 ### Q2｜必须使用某一家模型吗？不需要。当前目录覆盖 9 家 Provider，可按成本、速度和任务难度选择。 ### Q3｜能完全替代人工开发吗？不能。它更像一个能读项目、能动手、会测试的 Cocos 开发搭档。玩法、美术和最终验收仍由开发者负责。 --- > 🎮 **把想法留在 Cocos Creator 里，把重复工作交给 Game Agent。** --- ## 📮 联系方式 - QQ交流群：601667348 - 问题反馈：[https://forum.cocos.org/t/topic/176199](https://forum.cocos.org/t/topic/176199)