gizmo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gizmo

Use this skill when creating, editing, inspecting, or validating Gizmo worlds with the

gizmo

CLI or MCP.

当使用

gizmo

CLI或MCP创建、编辑、检查或验证Gizmo世界时，使用本技能。

Safety

安全须知

Only run Gizmo against trusted workspaces and world files. JavaScript/MJS worlds and persisted runtime module factories can execute code. Live sessions bind to

127.0.0.1

by default and use a per-session token; treat printed browser URLs, tokens, and portable MCP configs as local secrets.

仅在可信工作区和世界文件上运行Gizmo。JavaScript/MJS世界和持久化运行时模块工厂可执行代码。实时会话默认绑定到

127.0.0.1

并使用会话专属令牌；请将打印的浏览器URL、令牌和可移植MCP配置视为本地机密。

First Run

首次运行

Assume the

gizmo

CLI is installed globally. Verify when needed:

bash

gizmo --version

gizmo

is missing, ask the user before installing it:

bash

npm install -g @gizmo3d/cli@latest

In an empty folder, start the recommended live workflow:

bash

gizmo start --no-open

start

auto-creates

world.json

when needed, writes

.gizmo/session.json

, starts a browser-backed live session, creates

.gizmo/runs/<run-id>/

, and prints browser plus MCP connection details.

Launch mode:

In agent environments, use
```
gizmo start --no-open
```
by default.
Immediately tell the user the printed
```
codex.openInAppBrowserUrl
```
or
```
browserUrl
```
so they can watch the live world if they want.
Do not stop and wait for the user to open the link. Keep working with CLI/MCP commands after surfacing the URL.
If your environment exposes an in-app/local browser navigation tool, open the printed URL there as well. If it does not, clearly report the URL and continue.
In a normal user terminal where the user expects the browser to open, use
```
gizmo start
```
without
```
--no-open
```
.
For file-only/headless edits, use
```
gizmo init
```
,
```
gizmo use
```
, or explicit
```
--world
```
; do not use screenshots or viewport camera validation unless a live browser is attached.

For headless file work:

bash

gizmo init ./my-world
cd ./my-world
gizmo use ./world.json

假设

gizmo

CLI已全局安装。必要时进行验证：

bash

gizmo --version

如果缺少

gizmo

，请先询问用户再安装：

bash

npm install -g @gizmo3d/cli@latest

在空文件夹中，启动推荐的实时工作流：

bash

gizmo start --no-open

start

命令会在需要时自动创建

world.json

，写入

.gizmo/session.json

，启动由浏览器支持的实时会话，创建

.gizmo/runs/<run-id>/

目录，并打印浏览器和MCP连接详情。

启动模式：

在Agent环境中，默认使用
```
gizmo start --no-open
```
。
立即告知用户打印的
```
codex.openInAppBrowserUrl
```
或
```
browserUrl
```
，以便他们可以查看实时世界（如果需要）。
不要停止并等待用户打开链接。在展示URL后继续使用CLI/MCP命令进行操作。
如果你的环境提供应用内/本地浏览器导航工具，也在其中打开打印的URL。如果没有，请明确告知URL并继续操作。
在用户期望浏览器自动打开的普通终端中，使用不带
```
--no-open
```
的
```
gizmo start
```
。
对于仅文件/无头编辑，使用
```
gizmo init
```
、
```
gizmo use
```
或显式指定
```
--world
```
；除非已连接实时浏览器，否则不要使用截图或视口相机验证功能。

无头文件操作：

bash

gizmo init ./my-world
cd ./my-world
gizmo use ./world.json

Agent Loop

Agent循环

When visual work is requested, start or attach a live session and surface the live URL to the user before making edits. If no browser is attached, continue with structured edits, but wait to use camera/screenshot validation until a browser client is available.

Inspect before mutating:

```
gizmo resource session-info
```
```
gizmo resource world-state-summary
```
```
gizmo resource entity-list
```
```
gizmo resource component-catalog
```
```
gizmo resource module-type-catalog
```

Make one focused change:
- ```
gizmo call <command> --params '<json>'
```
- ```
gizmo batch '<json-array>'
```
  only when changes are one logical operation.
Re-read relevant resources.

For visual work:

```
gizmo camera frame-entity <stableId>
```

gizmo camera set --position '<json>' --look-at '<json>'

```
gizmo snapshot
```

Use

stableId

as the durable public entity identity. Do not expose runtime entity IDs as public handles.

当需要进行可视化操作时，先启动或连接实时会话，并在进行编辑前向用户展示实时URL。如果未连接浏览器，继续进行结构化编辑，但需等到浏览器客户端可用后再使用相机/截图验证功能。

在修改前先检查状态：

```
gizmo resource session-info
```
```
gizmo resource world-state-summary
```
```
gizmo resource entity-list
```
```
gizmo resource component-catalog
```
```
gizmo resource module-type-catalog
```

进行一个针对性的修改：
- ```
gizmo call <command> --params '<json>'
```
- 仅当变更属于同一逻辑操作时，使用
```
gizmo batch '<json-array>'
```
  。
重新读取相关资源。

对于可视化操作：

```
gizmo camera frame-entity <stableId>
```

gizmo camera set --position '<json>' --look-at '<json>'

```
gizmo snapshot
```

使用

stableId

作为持久化的公共实体标识。不要将运行时实体ID作为公共句柄暴露。

CLI Reference

CLI参考

Use the installed CLI as the source of truth:

bash

gizmo --help
gizmo docs
gizmo docs workflow
gizmo docs command add-entity
gizmo docs resource entity-bundle
gizmo docs component Transform
gizmo docs module material
gizmo commands
gizmo resources

Core commands:

```
gizmo start --no-open
```
: recommended live workflow; auto-inits in empty folders.
```
gizmo mcp
```
: start stdio MCP for the active workspace or explicit world.
```
gizmo mcp-config
```
: print MCP configuration.
```
gizmo resource <name>
```
: read world/session state.
```
gizmo call <name> --params '<json>'
```
: mutate the world.
```
gizmo camera get|set|frame-entity
```
: inspect/control the viewport camera.
```
gizmo snapshot
```
: capture the live viewport into
```
.gizmo/runs/.../artifacts
```
.
```
gizmo docs ...
```
: read installed-version docs for finer syntax.

Live editor persistence:

Manual editor saves write the visible browser world back to
```
world.json
```
. Prefer the toolbar Save button or
```
Ctrl+S
```
/
```
Cmd+S
```
after user-driven edits.
Live editor exports are written to
```
.gizmo/runs/<run-id>/artifacts/
```
instead of relying on browser downloads. Use this path when an embedded browser, such as Codex's in-app browser, blocks downloads.

Common resources:

session-info

world-state-summary

entity-list

```
entity-bundle --stable-id <id>
```
```
component-catalog
```

module-type-catalog

module-instance-catalog

```
viewport-camera
```

render-screenshot

entity-render-screenshot --stable-id <id>

Common mutating commands:

```
add-entity(archetypeOrDef, overrides?)
```
```
delete-entity(stableId)
```
```
duplicate-entity(stableId, offset?)
```
```
set-transform(stableId, transform)
```

add-component(stableId, componentName, componentData)

modify-component(stableId, componentName, componentData)

```
modify-body(stableId, body)
```

insert-body-part(stableId, parentPath, part)

upsert-module-type(moduleName, typeName, factorySource, description?, parameterSchema?)

upsert-module-instance(moduleName, instanceName, definition)

set-viewport-camera(position?, lookAt?, rotation?, fov?)

frame-viewport-entity(stableId, padding?, fov?)

以已安装的CLI作为权威来源：

bash

gizmo --help
gizmo docs
gizmo docs workflow
gizmo docs command add-entity
gizmo docs resource entity-bundle
gizmo docs component Transform
gizmo docs module material
gizmo commands
gizmo resources

核心命令：

```
gizmo start --no-open
```
：推荐的实时工作流；在空文件夹中会自动初始化。
```
gizmo mcp
```
：为当前工作区或指定世界启动标准输入输出MCP。
```
gizmo mcp-config
```
：打印MCP配置。
```
gizmo resource <name>
```
：读取世界/会话状态。
```
gizmo call <name> --params '<json>'
```
：修改世界状态。
```
gizmo camera get|set|frame-entity
```
：检查/控制视口相机。
```
gizmo snapshot
```
：将实时视口捕获到
```
.gizmo/runs/.../artifacts
```
目录。
```
gizmo docs ...
```
：查看对应安装版本的文档以获取更详细的语法说明。

实时编辑器持久化：

手动编辑器保存会将浏览器中可见的世界写回
```
world.json
```
。在用户驱动的编辑后，优先使用工具栏的保存按钮或
```
Ctrl+S
```
/
```
Cmd+S
```
快捷键。
实时编辑器导出的内容会写入
```
.gizmo/runs/<run-id>/artifacts/
```
目录，而非依赖浏览器下载。当嵌入式浏览器（如Codex的应用内浏览器）阻止下载时，使用此路径。

常用资源：

session-info

、

world-state-summary

、

entity-list

```
entity-bundle --stable-id <id>
```
```
component-catalog
```

module-type-catalog

、

module-instance-catalog

```
viewport-camera
```

render-screenshot

、

entity-render-screenshot --stable-id <id>

常用修改命令：

```
add-entity(archetypeOrDef, overrides?)
```
```
delete-entity(stableId)
```
```
duplicate-entity(stableId, offset?)
```
```
set-transform(stableId, transform)
```

add-component(stableId, componentName, componentData)

modify-component(stableId, componentName, componentData)

```
modify-body(stableId, body)
```

insert-body-part(stableId, parentPath, part)

upsert-module-type(moduleName, typeName, factorySource, description?, parameterSchema?)

upsert-module-instance(moduleName, instanceName, definition)

set-viewport-camera(position?, lookAt?, rotation?, fov?)

frame-viewport-entity(stableId, padding?, fov?)

Embedded Engine Reference

嵌入式引擎参考

This block is generated from the installed engine automation catalogs so the skill remains useful when the source repo docs are not on disk. Use it for common shapes, then use

gizmo docs ...

for exact installed-version detail.

此区块由已安装的引擎自动化目录生成，因此即使源仓库文档未在本地磁盘上，本技能仍可正常使用。使用它获取常用格式的信息，然后使用

gizmo docs ...

获取对应安装版本的详细信息。

Automation Commands

自动化命令

```
add-entity(archetypeOrDef, overrides?)
```
: Spawn a new entity from an archetype or bundle. (changes state; persists world)
```
delete-entity(stableId)
```
: Delete an entity by its stable ID. (changes state; persists world)
```
duplicate-entity(stableId, offset?)
```
: Duplicate an entity with an optional offset. (changes state; persists world)
```
set-transform(stableId, transform)
```
: Set an entity transform (position/rotation/scale). (changes state; persists world)
```
add-component(stableId, componentName, componentData)
```
: Add a component to an entity. (changes state; persists world)
```
remove-component(stableId, componentName)
```
: Remove a component from an entity. (changes state; persists world)
```
modify-component(stableId, componentName, componentData)
```
: Modify an existing component on an entity. (changes state; persists world)
```
modify-body(stableId, body)
```
: Modify an entity body definition. (changes state; persists world)
```
insert-body-part(stableId, parentPath, part)
```
: Insert a new body part into a composite body. (changes state; persists world)
```
add-body-part(stableId, archetype, localPosition)
```
: Append a new body part to a composite body. (changes state; persists world)
```
set-body-part-transform(stableId, path, transform)
```
: Set a body part transform. (changes state; persists world)
```
reinitialize-world(definition)
```
: Reinitialize the world (respawn entities). (changes state; persists world)
```
modify-world-settings(settings)
```
: Update world-level settings. (changes state; persists world)
```
upsert-module-type(moduleName, typeName, factorySource, description?, parameterSchema?)
```
: Register or replace a persisted runtime module type backed by factory source. (changes state; persists world)
```
remove-module-type(moduleName, typeName)
```
: Remove a persisted runtime module type. (changes state; persists world)
```
upsert-module-instance(moduleName, instanceName, definition)
```
: Register or replace a named module instance. (changes state; persists world)
```
remove-module-instance(moduleName, instanceName)
```
: Remove a named module instance. (changes state; persists world)

set-viewport-camera(position?, lookAt?, rotation?, fov?)

: Set the current viewport camera pose. (changes state)

```
frame-viewport-entity(stableId, padding?, fov?)
```
: Move the viewport camera to frame one entity by stable ID. (changes state)

```
add-entity(archetypeOrDef, overrides?)
```
：从原型或包中生成新实体。（更改状态；持久化世界）
```
delete-entity(stableId)
```
：通过stable ID删除实体。（更改状态；持久化世界）
```
duplicate-entity(stableId, offset?)
```
：复制实体，可选择偏移量。（更改状态；持久化世界）
```
set-transform(stableId, transform)
```
：设置实体变换（位置/旋转/缩放）。（更改状态；持久化世界）
```
add-component(stableId, componentName, componentData)
```
：为实体添加组件。（更改状态；持久化世界）
```
remove-component(stableId, componentName)
```
：从实体中移除组件。（更改状态；持久化世界）
```
modify-component(stableId, componentName, componentData)
```
：修改实体上已存在的组件。（更改状态；持久化世界）
```
modify-body(stableId, body)
```
：修改实体主体定义。（更改状态；持久化世界）
```
insert-body-part(stableId, parentPath, part)
```
：将新主体部分插入到复合主体中。（更改状态；持久化世界）
```
add-body-part(stableId, archetype, localPosition)
```
：将新主体部分追加到复合主体中。（更改状态；持久化世界）
```
set-body-part-transform(stableId, path, transform)
```
：设置主体部分的变换。（更改状态；持久化世界）
```
reinitialize-world(definition)
```
：重新初始化世界（重新生成实体）。（更改状态；持久化世界）
```
modify-world-settings(settings)
```
：更新世界级设置。（更改状态；持久化世界）
```
upsert-module-type(moduleName, typeName, factorySource, description?, parameterSchema?)
```
：注册或替换由工厂源码支持的持久化运行时模块类型。（更改状态；持久化世界）
```
remove-module-type(moduleName, typeName)
```
：移除持久化运行时模块类型。（更改状态；持久化世界）
```
upsert-module-instance(moduleName, instanceName, definition)
```
：注册或替换命名模块实例。（更改状态；持久化世界）
```
remove-module-instance(moduleName, instanceName)
```
：移除命名模块实例。（更改状态；持久化世界）

set-viewport-camera(position?, lookAt?, rotation?, fov?)

：设置当前视口相机姿态。（更改状态）

```
frame-viewport-entity(stableId, padding?, fov?)
```
：移动视口相机以框选指定stable ID的实体。（更改状态）

Automation Resources

自动化资源

```
session-info
```
: Information about the active automation session and backing world file. params: none
```
world-state-summary
```
: High-level summary of world entities and metadata. params: none
```
component-catalog
```
: Registered component schemas with structural metadata. params: none
```
module-type-catalog
```
: Registered runtime module types, including persisted custom factories. params: none
```
module-instance-catalog
```
: Named module instances across all modules. params: none
```
entity-list
```
: List of all entities with basic info. params: none
```
selected-entities-full
```
: Selected entities with IDs and full definitions. params: none
```
selected-body-parts-full
```
: Selected body parts with IDs and full entity definitions. params: none
```
metadata
```
: World metadata (title, description, dimensions). params: none
```
achievements
```
: List of all achievements. params: none
```
full-world-state
```
: Complete serialized world state. params: none
```
entity-bundle
```
: Get a full entity bundle by stable ID. params: stableId
```
render-screenshot
```
: Capture a screenshot of the full world viewport. params: none
```
viewport-camera
```
: Current viewport camera pose and framing direction. params: none
```
entity-render-screenshot
```
: Capture a screenshot focused on a single entity by stable ID. params: stableId

```
session-info
```
：关于当前自动化会话和对应的世界文件的信息。参数：无
```
world-state-summary
```
：世界实体和元数据的高级摘要。参数：无
```
component-catalog
```
：已注册的组件schema及结构元数据。参数：无
```
module-type-catalog
```
：已注册的运行时模块类型，包括持久化自定义工厂。参数：无
```
module-instance-catalog
```
：所有模块中的命名模块实例。参数：无
```
entity-list
```
：所有实体的基础信息列表。参数：无
```
selected-entities-full
```
：选中实体的ID和完整定义。参数：无
```
selected-body-parts-full
```
：选中主体部分的ID和完整实体定义。参数：无
```
metadata
```
：世界元数据（标题、描述、尺寸）。参数：无
```
achievements
```
：所有成就列表。参数：无
```
full-world-state
```
：完整的序列化世界状态。参数：无
```
entity-bundle
```
：通过stable ID获取完整的实体包。参数：stableId
```
render-screenshot
```
：捕获整个世界视口的截图。参数：无
```
viewport-camera
```
：当前视口相机的姿态和取景方向。参数：无
```
entity-render-screenshot
```
：捕获指定stable ID实体的聚焦截图。参数：stableId

High-Value Command Examples

高价值命令示例

Add a cube:

bash

gizmo call add-entity --params '{"archetypeOrDef":"cube"}'

Add an inline entity definition:

bash

gizmo call add-entity --params '{"archetypeOrDef":{"definition":{"Transform":{"position":{"x":0,"y":1,"z":0},"scale":{"x":2,"y":0.5,"z":2}},"Renderable":{"body":{"type":"box","size":{"x":2,"y":0.5,"z":2}}}},"archetype":"platform"}}'

Move an entity by stable ID:

bash

gizmo call set-transform --params '{"stableId":12,"transform":{"position":{"x":2,"y":1,"z":0}}}'

Modify a component after checking its schema:

bash

gizmo docs component Transform
gizmo call modify-component --params '{"stableId":12,"componentName":"Transform","componentData":{"position":{"x":0,"y":2,"z":0}}}'

Frame and capture visual output:

bash

gizmo camera frame-entity 12
gizmo snapshot --prefix entity-12

Batch one logical operation:

bash

gizmo batch '[{"name":"add-entity","params":{"archetypeOrDef":"cube"}},{"name":"add-entity","params":{"archetypeOrDef":"sphere","overrides":{"Transform":{"position":{"x":2,"y":1,"z":0}}}}}]'

添加立方体：

bash

gizmo call add-entity --params '{"archetypeOrDef":"cube"}'

添加内联实体定义：

bash

gizmo call add-entity --params '{"archetypeOrDef":{"definition":{"Transform":{"position":{"x":0,"y":1,"z":0},"scale":{"x":2,"y":0.5,"z":2}},"Renderable":{"body":{"type":"box","size":{"x":2,"y":0.5,"z":2}}}},"archetype":"platform"}}'

通过stable ID移动实体：

bash

gizmo call set-transform --params '{"stableId":12,"transform":{"position":{"x":2,"y":1,"z":0}}}'

检查schema后修改组件：

bash

gizmo docs component Transform
gizmo call modify-component --params '{"stableId":12,"componentName":"Transform","componentData":{"position":{"x":0,"y":2,"z":0}}}'

框选并捕获可视化输出：

bash

gizmo camera frame-entity 12
gizmo snapshot --prefix entity-12

批量执行同一逻辑操作：

bash

gizmo batch '[{"name":"add-entity","params":{"archetypeOrDef":"cube"}},{"name":"add-entity","params":{"archetypeOrDef":"sphere","overrides":{"Transform":{"position":{"x":2,"y":1,"z":0}}}}}]'

Component And Body Authoring Notes

组件与主体创作注意事项

Components are keyed by component name in entity definitions.

Always inspect

gizmo resource component-catalog

gizmo docs component <name>

before using unfamiliar component fields.

Common transform fields are
```
position
```
,
```
rotation
```
, and
```
scale
```
with
```
{ "x", "y", "z" }
```
numeric objects.
Body definitions are nested objects used by renderable/composite entities. Use
```
modify-body
```
,
```
insert-body-part
```
,
```
add-body-part
```
, and
```
set-body-part-transform
```
for structural body edits.
Prefer small edits followed by
```
entity-bundle --stable-id <id>
```
so mistakes are easy to spot.

在实体定义中，组件以组件名称作为键。

在使用不熟悉的组件字段前，务必查看

gizmo resource component-catalog

或

gizmo docs component <name>

。

常用变换字段为
```
position
```
、
```
rotation
```
和
```
scale
```
，它们的值是包含
```
{ "x", "y", "z" }
```
的数值对象。
主体定义是嵌套对象，用于可渲染/复合实体。使用
```
modify-body
```
、
```
insert-body-part
```
、
```
add-body-part
```
和
```
set-body-part-transform
```
进行结构化主体编辑。
优先进行小幅度修改，然后使用
```
entity-bundle --stable-id <id>
```
查看，这样更容易发现错误。

Visual Iteration Pattern

可视化迭代模式

Open the live browser URL before editing.
Make a small structural change.
Re-read
```
entity-list
```
or the targeted
```
entity-bundle
```
.
Move the camera with
```
frame-entity
```
or
```
camera set
```
.
Capture
```
gizmo snapshot
```
and compare against the user request.
Repeat from another camera angle for spatial work.

在编辑前打开实时浏览器URL。
进行小幅度的结构性修改。
重新读取
```
entity-list
```
或目标
```
entity-bundle
```
。
使用
```
frame-entity
```
或
```
camera set
```
移动相机。
执行
```
gizmo snapshot
```
捕获截图，并与用户需求对比。
对于空间相关操作，从其他相机角度重复上述步骤。

MCP

For headless MCP:

json

{
  "mcpServers": {
    "gizmo": {
      "command": "gizmo",
      "args": ["mcp", "--world", "/absolute/path/to/world.json"]
    }
  }
}

For live MCP, run

gizmo start --no-open

and use the printed

mcpConfig

in the same workspace, or

portableMcpConfig

when explicit server/token details are needed.

无头MCP配置：

json

{
  "mcpServers": {
    "gizmo": {
      "command": "gizmo",
      "args": ["mcp", "--world", "/absolute/path/to/world.json"]
    }
  }
}

对于实时MCP，运行

gizmo start --no-open

并使用同一工作区中打印的

mcpConfig

，或在需要明确服务器/令牌详情时使用

portableMcpConfig

。

Module Authoring

模块创作

Inspect first:

bash

gizmo resource module-type-catalog
gizmo resource module-instance-catalog
gizmo docs modules
gizmo docs module material

bash

gizmo call upsert-module-type --params '{"moduleName":"material","typeName":"warmMatte","description":"Solid warm matte material.","parameterSchema":{"type":"object","properties":{"color":{"type":"string"}}},"factorySource":"(params) => ({ type: \"solid\", params: { color: params.color || \"#f2c078\" } })"}'
gizmo call upsert-module-instance --params '{"moduleName":"material","instanceName":"sunlitStucco","definition":{"type":"warmMatte","params":{"color":"#f7e7bf"}}}'

Use

gizmo docs component <name>

for component field syntax and

gizmo docs command <name>

for exact command parameters.

先检查现有模块：

bash

gizmo resource module-type-catalog
gizmo resource module-instance-catalog
gizmo docs modules
gizmo docs module material

仅注册可信的工厂源码：

bash

gizmo call upsert-module-type --params '{"moduleName":"material","typeName":"warmMatte","description":"Solid warm matte material.","parameterSchema":{"type":"object","properties":{"color":{"type":"string"}}},"factorySource":"(params) => ({ type: \"solid\", params: { color: params.color || \"#f2c078\" } })"}'
gizmo call upsert-module-instance --params '{"moduleName":"material","instanceName":"sunlitStucco","definition":{"type":"warmMatte","params":{"color":"#f7e7bf"}}}'

使用

gizmo docs component <name>

获取组件字段语法，使用

gizmo docs command <name>

获取命令的精确参数。

Troubleshooting

故障排除

gizmo

is not found, ask before running

npm install -g @gizmo3d/cli@latest

, then verify with

gizmo --version

If commands cannot find a server, rerun
```
gizmo start --no-open
```
.
If live commands say no browser client is attached, surface the printed
```
browserUrl
```
or
```
codex.openInAppBrowserUrl
```
, open it yourself only if your environment has a browser tool, and retry visual-only operations after a browser attaches.
If a sandbox blocks loopback access, retry with local network permission.
If screenshots fail, confirm the target is a live session, not headless.
If explicit
```
--server
```
auth fails, use the current token from
```
gizmo start
```
.
If a command shape is unclear, prefer
```
gizmo docs command <name>
```
or
```
gizmo commands
```
over guessing.

如果找不到
```
gizmo
```
，询问用户后再运行
```
npm install -g @gizmo3d/cli@latest
```
，然后使用
```
gizmo --version
```
验证。
如果命令无法找到服务器，重新运行
```
gizmo start --no-open
```
。
如果实时命令提示未连接浏览器客户端，展示打印的
```
browserUrl
```
或
```
codex.openInAppBrowserUrl
```
，仅当你的环境有浏览器工具时才自行打开，待浏览器连接后重试仅可视化操作。
如果沙箱阻止环回访问，重试时申请本地网络权限。
如果截图失败，确认目标是实时会话而非无头模式。
如果显式
```
--server
```
认证失败，使用
```
gizmo start
```
输出的当前令牌。
如果命令格式不明确，优先使用
```
gizmo docs command <name>
```
或
```
gizmo commands
```
而非猜测。

Optional Repo Docs

可选仓库文档

If the source repo is available, additional docs may exist under

docs/

. This skill is self-contained so agents can operate when Gizmo was installed from npm without cloning the source repository.

如果源仓库可用，

docs/

目录下可能有额外文档。本技能是自包含的，因此即使Gizmo是从npm安装而非克隆源仓库，Agent仍可正常操作。