A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: the agent in the editor had no page anywhere
yhh4ef74dfab722
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex d57e3da5e..d40ef47f2 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -139,6 +139,7 @@ export default defineConfig({{ label: 'Mini-Game Platforms', translations: { 'zh-CN': '小游戏平台' }, slug: 'guides/minigame-platforms' },{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },{ label: 'Editor Plugins', translations: { 'zh-CN': '编辑器插件' }, slug: 'guides/editor-plugins' },+ { label: 'The Built-in Agent', translations: { 'zh-CN': '内置 Agent' }, slug: 'guides/agent' },{ label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'guides/mcp' },],},diff --git a/docs/astro/src/assets/guides/en/agent-preview.png b/docs/astro/src/assets/guides/en/agent-preview.pngnew file mode 100644index 000000000..8be44f690Binary files /dev/null and b/docs/astro/src/assets/guides/en/agent-preview.png differdiff --git a/docs/astro/src/assets/guides/en/agent-settings.png b/docs/astro/src/assets/guides/en/agent-settings.pngnew file mode 100644index 000000000..40971793cBinary files /dev/null and b/docs/astro/src/assets/guides/en/agent-settings.png differdiff --git a/docs/astro/src/assets/guides/en/agent-turn.png b/docs/astro/src/assets/guides/en/agent-turn.pngnew file mode 100644index 000000000..804f00047Binary files /dev/null and b/docs/astro/src/assets/guides/en/agent-turn.png differdiff --git a/docs/astro/src/assets/guides/zh/agent-preview.png b/docs/astro/src/assets/guides/zh/agent-preview.pngnew file mode 100644index 000000000..2711a38ffBinary files /dev/null and b/docs/astro/src/assets/guides/zh/agent-preview.png differdiff --git a/docs/astro/src/assets/guides/zh/agent-settings.png b/docs/astro/src/assets/guides/zh/agent-settings.pngnew file mode 100644index 000000000..7adbcb664Binary files /dev/null and b/docs/astro/src/assets/guides/zh/agent-settings.png differdiff --git a/docs/astro/src/assets/guides/zh/agent-turn.png b/docs/astro/src/assets/guides/zh/agent-turn.pngnew file mode 100644index 000000000..649d7f204Binary files /dev/null and b/docs/astro/src/assets/guides/zh/agent-turn.png differdiff --git a/docs/astro/src/content/docs/guides/agent.mdx b/docs/astro/src/content/docs/guides/agent.mdxnew file mode 100644index 000000000..09b97f1ae--- /dev/null+++ b/docs/astro/src/content/docs/guides/agent.mdx@@ -0,0 +1,135 @@+---+title: The Built-in Agent+description: Ask the editor to do something in plain language. The agent reads your scene and edits it through the same tools the editor's own UI uses — with an Undo checkpoint around every turn and a confirmation before anything Undo cannot reach.+---++import { Aside, Steps } from '@astrojs/starlight/components';++The editor ships with an agent of its own. You type a sentence; it reads the scene,+calls the same tools the editor's UI calls, and shows you every one of them as it+goes. Nothing about it is a separate copy of the editor: it drives the exact tool+catalog an [external MCP client](/docs/guides/mcp/) drives, so what it can do and+what the editor can do are one list.++<Aside type="tip">+It is the same window you were already working in. Its edits land in your scene,+your Undo takes them back, and you can take the mouse at any moment.+</Aside>++## Give it a model++The editor ships no key and calls nothing on its own. Open **Settings ▸ AI Agents**+and configure one provider — that is the whole setup.++++<Steps>++1. Paste an **API key** for Anthropic or DeepSeek. Each provider keeps its own, so+ switching back to one you used last week costs nothing.++2. Or fill in the **Custom Provider**: any Anthropic-compatible endpoint, plus the+ model names it offers. Those names become choices in the composer.++3. Close Settings. The model picker sits next to the box you type in — it is a+ per-message choice, not a preference buried in a dialog.++</Steps>++<Aside type="tip" title="Where the key lives">+In the system keychain. It is never written to the project, never written to the+settings file, and never handed back to the editor window — only to the client that+has to send it.+</Aside>++## Ask it something++Open the command palette (`Ctrl/Cmd+Shift+P`) and run **Agent: Open**. Or skip that:+type your question straight into the palette. Anything that reads as a sentence+rather than a command offers **Hand to Agent**, and `Enter` sends it.++++A run reads top to bottom:++- **The question**, with the model that answered it, how long it took, and the+ tokens it cost.+- **A row per tool call** — `get_scene_tree`, `get_event_bindings` — with its+ arguments and how much came back. This is the part worth reading: it is the+ difference between an answer about your scene and an answer about scenes in+ general.+- **The answer.**++In the composer, `@` references an entity by name so you do not have to describe+which one you mean. You can drop or paste an **image** — a mock-up, a screenshot of+the bug — and it is sent along with the question, where the endpoint accepts images.+While it works, the status bar carries a live segment with a **Stop** button, so a+long run is visible and interruptible with the drawer closed.++## What it may do without asking++The tiers are drawn where **Undo stops working**, which is what makes them worth+knowing:++| Tier | Examples | What happens |+| --- | --- | --- |+| Read | `get_scene_tree`, `get_inspector`, `capture_viewport` | Runs. Never asks. |+| Undoable | create, delete, `set_field`, re-parent, paint tiles | Runs. The whole turn is bracketed by one checkpoint, so a single **Undo** takes all of it back. |+| Irreversible | writing a file, exporting a build, saving, `run_editor_command` | **Always asks first.** Undo cannot rescue you afterwards. |++So the approval you give is not per edit — it is the Undo button, and it applies to+the turn as a whole. When a run finishes having changed something, the transcript+leaves a bar behind offering **Undo** or **Keep**, and it tells you if you have+edited since (because then Undo would take your own work back too).++## Before a large edit++One undoable tool still stops to ask, and not for safety: `apply_scene_ops` authors+a whole subtree in a single call, and a hundred-node edit is worth seeing before it+lands rather than reading back afterwards.++++Every line is one change. Click one to **strike it out** — striking a new entity also+strikes whatever refers to it — then **Apply** the rest. **Allow for this run** stops+the asking until the turn ends, which is what keeps a long build from becoming a+hundred prompts; the next run asks again.++Declining is not a dead end: the agent is told it was skipped and works around it.++## The conversation is kept with the project++A finished run is saved alongside the project — the transcript and the model's memory+of it. **Earlier conversations** lists them; pick one and it carries on where it+stopped. The next question in an open conversation still has everything the previous+one established.++Two things are worth knowing about a long one:++- **The context gauge** in the drawer's header says how full the model's window is.+ Past a threshold the earliest runs are *folded out of its memory*: what you asked is+ kept word for word, the tool calls and their results are not. The transcript still+ shows them — the model can no longer read them. When that happens the drawer says+ so, on the line where it happened.+- **A conversation belongs to the model that answered it.** Switching models ends it+ and starts a new one. What it changed in the scene stays.++You can also **ask a run again** in different words: it discards that run and+everything after it, then re-asks. Useful when a turn went the wrong way three+messages ago and you would rather not talk it back.++<Aside type="caution">+It can be confidently wrong, like any model — most often about state it read several+runs ago. When an answer describes your scene rather than reasoning about it, ask it+to re-read rather than trusting the summary. That is also why the tool rows are on+screen: they show what it actually looked at.+</Aside>++## See also++- [AI Agents (MCP)](/docs/guides/mcp/) — the same tool catalog, driven from Claude+ Code, Cursor, or your own agent instead of from inside the editor.+- [Event Binding](/docs/guides/events/) — what the agent reaches for when you ask+ for behaviour without code.+- [Prefabs](/docs/guides/prefab/) — in Prefab Mode the agent edits the prefab, not+ the scene. Check the document it is working on before asking for a big change.diff --git a/docs/astro/src/content/docs/zh-cn/guides/agent.mdx b/docs/astro/src/content/docs/zh-cn/guides/agent.mdxnew file mode 100644index 000000000..ae4810333--- /dev/null+++ b/docs/astro/src/content/docs/zh-cn/guides/agent.mdx@@ -0,0 +1,121 @@+---+title: 内置 Agent+description: 用一句话让编辑器干活。Agent 会读你的场景,并通过编辑器 UI 自己用的那套工具来改动它——每一轮外面都套着一个撤销检查点,撤销够不到的事情则一律先问过你。+---++import { Aside, Steps } from '@astrojs/starlight/components';++编辑器自带一个 Agent。你打一句话,它读场景、调用编辑器 UI 调用的同一批工具,+并把每一次调用都摊在你眼前。它不是编辑器的另一份复制品:它驱动的工具目录,+和[外部 MCP 客户端](/docs/zh-cn/guides/mcp/)驱动的是同一份——它能做什么,+和编辑器能做什么,是一张清单。++<Aside type="tip">+它就在你原本工作的那个窗口里。它的改动落在你的场景上,你的撤销能收回它们,+你随时可以把鼠标拿回来。+</Aside>++## 先给它一个模型++编辑器不附带任何密钥,也不会自己发起任何调用。打开**设置 ▸ AI 代理**,+配好一个提供方,配置就算做完了。++++<Steps>++1. 填入 Anthropic 或 DeepSeek 的 **API 密钥**。每个提供方各存各的,+ 所以切回上周用过的那个不用重新输入。++2. 或者填**自定义提供方**:任何兼容 Anthropic 的接口地址,加上它提供的模型名。+ 这些名字会出现在输入框旁边的模型选择器里。++3. 关掉设置。模型选择器就在你打字的那个框旁边——它是**逐条消息**的选择,+ 而不是埋在对话框里的偏好设置。++</Steps>++<Aside type="tip" title="密钥存在哪">+存在系统钥匙串里。它不写进项目、不写进设置文件,也不会交回给编辑器窗口——+只交给那个必须发送它的客户端。+</Aside>++## 问它点什么++打开命令面板(`Ctrl/Cmd+Shift+P`)执行 **Agent:打开**。或者干脆跳过这一步:+直接把问题打进命令面板。凡是读起来像一句话而不像命令的输入,面板都会给出+**交给 Agent**,按 `Enter` 就发出去了。++++一轮对话从上往下读:++- **问题**,旁边是回答它的模型、耗时,以及花掉的 token。+- **每次工具调用一行**——`get_scene_tree`、`get_event_bindings`——带上参数和+ 返回的条数。这部分才是值得读的:它决定了你拿到的是**关于你这个场景**的回答,+ 还是一段泛泛而谈。+- **回答**。++在输入框里,用 `@` 可以按名字引用实体,省得你去描述指的是哪一个。你也可以+拖入或粘贴**图片**——一张设计稿、一张 bug 截图——在接口支持图片时它会随问题+一起发出去。它干活期间,状态栏上会有一条实时的段落,带**停止**按钮,+所以抽屉关着也看得见进度、也随时能叫停。++## 哪些事它不用问就能做++分级是按**撤销在哪里失效**划的,这也是它值得你知道的原因:++| 层级 | 例子 | 会发生什么 |+| --- | --- | --- |+| 只读 | `get_scene_tree`、`get_inspector`、`capture_viewport` | 直接跑,从不询问。 |+| 可撤销 | 新建、删除、`set_field`、改父子、刷瓦片 | 直接跑。整一轮外面套着一个检查点,一次**撤销**就能全退。 |+| 不可逆 | 写文件、导出构建、保存、`run_editor_command` | **一定先问**。事后撤销救不了你。 |++所以你给出的许可并不是逐条改动的许可——它就是撤销按钮,而且作用于**整一轮**。+一轮跑完且确实改了东西时,记录下面会留一条**撤销 / 保留**的横条;+如果你自己之后又编辑过,它会提示你——因为那时撤销会把你自己的活也一并退回。++## 大批改动落地之前++有一个可撤销的工具仍然会停下来问,而且不是出于安全:`apply_scene_ops`+一次调用就能搭出一整棵子树,上百个节点的改动值得在落地**之前**看一眼,+而不是事后再读回来。++++每一行就是一项改动。点一行可以**划掉**它——划掉一个新建实体时,+引用它的行会一并划掉——然后应用剩下的。**本轮都允许**会让它在这一轮里+不再询问,这正是让一次长时间搭建不至于变成一百次弹窗的东西;下一轮会重新问。++拒绝也不是死路:Agent 会被告知这一步被跳过了,然后绕开它继续。++## 对话跟着项目一起保存++跑完的对话会和项目存在一起——记录,以及模型对它的记忆。**历史对话**里列着它们,+挑一段就能从当时停下的地方接着聊。在一段打开的对话里继续提问,+前面建立起来的东西都还在。++一段长对话里有两件事值得知道:++- 抽屉顶部的**上下文刻度**表示模型的窗口用掉了多少。超过阈值后,+ 最早的几轮会被*折叠出它的记忆*:你问过的话原样保留,工具调用和结果不保留。+ 记录里仍然显示着它们——只是模型读不到了。发生这件事时,抽屉会在发生的那一行说出来。+- **一段对话属于回答它的那个模型。** 切换模型会结束当前这段并重新开始。+ 它对场景做过的改动仍然保留。++你还可以**换个说法重新提问**某一轮:它会丢弃那一轮以及之后的所有内容,然后重问。+当三条消息之前就跑偏了、而你不想再靠聊天把它拉回来时,这个很好用。++<Aside type="caution">+和任何模型一样,它可能非常自信地说错——最常见的是关于它好几轮之前读到的状态。+当一个回答是在**描述**你的场景而不是在推理时,让它重新读一遍,别信那段转述。+这也正是工具调用行摆在明面上的原因:它们显示的是它真正看过的东西。+</Aside>++## 参见++- [AI 代理 (MCP)](/docs/zh-cn/guides/mcp/) —— 同一份工具目录,+ 只不过是从 Claude Code、Cursor 或你自己的代理去驱动,而不是从编辑器内部。+- [事件绑定](/docs/zh-cn/guides/events/) —— 你要求"不写代码的行为"时,Agent 会去用的东西。+- [预制体](/docs/zh-cn/guides/prefab/) —— 在预制体模式下,Agent 编辑的是预制体而不是场景。+ 要它做大改动之前,先确认它正在编辑的是哪个文档。