Skip to content

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.

docs(agent): the tiers say what the checkpoint now covers

esengined7f0f246747b
diff --git a/desktop/electron/agent/prompt.ts b/desktop/electron/agent/prompt.ts
index e60ac1ab0..2c848ab89 100644
--- a/desktop/electron/agent/prompt.ts
+++ b/desktop/electron/agent/prompt.ts
@@ -23,8 +23,9 @@ export const SYSTEM_PROMPT = `You are the agent built into Estella, a 2D game ed
How work lands here:
- Edits go through the tools. There is no file-level path to the scene: a scene is a live World, and writing its file behind the editor's back would be overwritten by the next save.
-- Anything that only mutates the scene is undoable, and the whole turn is bracketed by one undo checkpoint, so you do not need permission for it. Make the edit rather than describing the edit you would make.
-- A few tools reach past what Undo can take back — writing a file, rewriting project settings, running code you wrote. Those stop and ask the user. If they decline, do not retry: work around it, or say what you need and why.
+- Your turn is bracketed by a checkpoint over BOTH halves of what you can change: the scene, and the project's files. Scene edits are undo steps; every file you write is captured beforehand, so the user takes the whole turn back — script, prefab, scene and all — with one gesture. You therefore do not need permission to edit or to write, and should make the change rather than describing the change you would make.
+- What still stops to ask is what the checkpoint does not reach: making a project somewhere else, building an export, running code you wrote (run_editor_command, play_probe). If the user declines, do not retry: work around it, or say what you need and why.
+- Do not treat that safety net as licence to be careless. It puts the project back, not the user's attention — a turn they have to take back has cost them the time they spent reading it.
- After you change the scene you will be shown any problems the editor now flags. Silence means it is clean. Fix what you broke before reporting the work as done.
Working style:
diff --git a/desktop/src/i18n/messages/agent.ts b/desktop/src/i18n/messages/agent.ts
index 2be1d5b18..2e1556e84 100644
--- a/desktop/src/i18n/messages/agent.ts
+++ b/desktop/src/i18n/messages/agent.ts
@@ -78,8 +78,8 @@ export const agentMessages = defineMessages({
// — Empty states —
'agent.empty.title': { en: 'Ask the agent to do something', zh: '让 Agent 帮你做点什么' },
'agent.empty.body': {
- en: 'It can read the scene, change entities, and look at what it rendered. Its edits are bracketed by a checkpoint, so one Undo takes the whole turn back.',
- zh: '它能读场景、改实体、看渲染结果。改动会记一个检查点,一次撤销全退。',
+ en: 'It can read the scene, change entities, write scripts and assets, and look at what it rendered. A checkpoint brackets the whole turn — the scene edits and the files — so one gesture takes all of it back.',
+ zh: '它能读场景、改实体、写脚本和资产,还能看渲染结果。整轮会记一个检查点 —— 场景改动和文件都在内 —— 一个动作全部退回。',
},
'agent.empty.sug1': { en: 'Add a pause menu for the player', zh: '给玩家加一个暂停菜单' },
'agent.empty.sug1.h': { en: 'creates UI entities', zh: '会新建 UI 实体' },
diff --git a/desktop/src/plugins/types.ts b/desktop/src/plugins/types.ts
index e361291ac..c6283e1fc 100644
--- a/desktop/src/plugins/types.ts
+++ b/desktop/src/plugins/types.ts
@@ -379,15 +379,15 @@ export interface AgentToolContribution {
*/
schema?: unknown;
/**
- * What calling it costs, which is what decides whether the person is asked
- * first: `read` and `undoable` run unasked (the turn's checkpoint is the
- * approval), `irreversible` stops and asks. Defaults to `read`.
+ * What calling it costs, which decides whether the person is asked first.
+ * The turn's checkpoint covers `read`, `undoable` and `journaled`, so all
+ * three run unasked; `journaled` is for writes through `ctx.fs.writeProject`,
+ * which are captured before they land. `irreversible` stops to ask.
*
- * Declare it honestly. Nothing verifies it — a plugin already runs with the
- * whole editor surface in reach — but an `irreversible` tool declared
- * `read` is one that will run without anyone being asked.
+ * Declare it honestly — nothing verifies it. A tool calling itself
+ * `journaled` while writing outside `ctx.fs` claims a net not holding it.
*/
- effect?: 'read' | 'undoable' | 'irreversible';
+ effect?: 'read' | 'undoable' | 'journaled' | 'irreversible';
/** Do the work. Whatever it returns is JSON-encoded for the model; throwing
* reports the message as a failed call, which the model can act on. */
run(input: unknown): unknown | Promise<unknown>;
diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdx
index 0f489a190..243be9740 100644
--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx
@@ -286,12 +286,20 @@ ctx.agentTools.register({
deciding whether this is the right tool. Say what it does and when to reach for
it.
-`effect` decides whether the person is asked first: `read` and `undoable` run
-unasked (the turn's checkpoint is the approval), `irreversible` stops and asks.
-Nothing verifies it, and that is not a gap — your plugin already runs with the
-whole editor surface in reach, so it could do the same work through a command.
-The boundary is the trust prompt at install. What the field buys is the confirm
-gate behaving correctly for an honest plugin, so declare it honestly.
+`effect` decides whether the person is asked first, and the tiers are drawn
+where going back stops working. `read` and `undoable` run unasked — the turn's
+checkpoint is the approval. So does `journaled`, which is what to declare when
+your tool writes project files through `ctx.fs.writeProject`: those are captured
+before they land, so the turn's Revert takes them back with the scene. Reserve
+`irreversible` for what no checkpoint reaches — work outside the open project,
+or code whose effects nobody enumerated; it stops and asks.
+
+Nothing verifies the field, and that is not a gap — your plugin already runs
+with the whole editor surface in reach, so it could do the same work through a
+command. The boundary is the trust prompt at install. What the field buys is
+the confirm gate behaving correctly for an honest plugin, so declare it
+honestly: a tool that calls itself `journaled` while writing outside `ctx.fs`
+claims a safety net that is not holding it.
The name must be namespaced with your plugin id. An un-namespaced tool could
shadow a built-in, and a model calling `delete_entity` believes it knows what
diff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
index 32809bc29..8133f5025 100644
--- a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
@@ -262,7 +262,9 @@ ctx.agentTools.register({
`description` **不是文档**——它是模型判断「该不该调这个」时唯一会读的东西。写清楚它做什么、什么时候该用。
-`effect` 决定要不要先问人:`read` 和 `undoable` 直接跑(这一轮的检查点就是许可),`irreversible` 会停下来问。**没有任何东西会去核实它**,而这不是漏洞——你的插件本来就握着整个编辑器接口,同样的事它用一个命令也能做。边界在安装时的信任提示,不在这个字段。这个字段换来的是:对一个诚实的插件,确认门能正确工作。所以请如实声明。
+`effect` 决定要不要先问人,分档的界线画在**「还退得回去」到此为止**的地方。`read` 和 `undoable` 直接跑(这一轮的检查点就是许可)。`journaled` 也直接跑——当你的工具通过 `ctx.fs.writeProject` 写项目文件时就声明这一档:这些写入会在落盘前被留底,所以这一轮的「撤回」会把它们连同场景一起收回来。`irreversible` 留给检查点够不着的:动到已打开项目之外,或者跑没人枚举得清后果的代码;它会停下来问。
+
+**没有任何东西会去核实这个字段**,而这不是漏洞——你的插件本来就握着整个编辑器接口,同样的事它用一个命令也能做。边界在安装时的信任提示,不在这个字段。这个字段换来的是:对一个诚实的插件,确认门能正确工作。所以请如实声明——一个自称 `journaled` 却绕开 `ctx.fs` 去写盘的工具,是在宣称一张并没有接住它的安全网。
名字必须以你的插件 id 开头。不带命名空间的工具可能**盖住内置工具**,而模型在调 `delete_entity` 时是相信自己知道会发生什么的。违反上述任一条的工具会被**拒绝并在输出日志里说明原因**,不会被静默丢掉。