playcanvas-agent-bridge-cli 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
- CLI-first local automation for controlling an already-open PlayCanvas Editor scene from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
3
+ CLI-first local automation for controlling already-open PlayCanvas Editor scenes and PlayCanvas Launch pages from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
4
4
 
5
5
  The core interface is the `pcbridge` command plus a local daemon and a Chrome Manifest V3 extension. MCP is intentionally not required.
6
6
 
@@ -50,10 +50,38 @@ Then in Chrome:
50
50
  2. Enable Developer Mode.
51
51
  3. Click Load unpacked.
52
52
  4. Select the exact directory printed by `pcbridge install-extension`.
53
- 5. Open or refresh a PlayCanvas Editor page.
53
+ 5. Open or refresh a PlayCanvas Editor page or a PlayCanvas Launch page.
54
54
 
55
55
  The generated extension directory contains a local session token in `config.json`, so load that generated directory rather than the raw `extension/` folder from the repo.
56
56
 
57
+ ## Use the custom Editor frontend
58
+
59
+ The Editor build is not bundled in the npm package. Download the latest published build from
60
+ `Q-My99/playcanvas-editor`, verify its release metadata and SHA-256, then activate it locally:
61
+
62
+ ```bash
63
+ pcbridge frontend install latest
64
+ pcbridge frontend status
65
+ pcbridge daemon start
66
+ ```
67
+
68
+ The daemon serves the active build from `http://localhost:3487`. On a
69
+ `https://playcanvas.com/editor/...` tab, open the extension popup and choose **Use custom
70
+ frontend**. Choose **Use official frontend** to remove `use_local_frontend` and reload the same
71
+ Editor URL with the official frontend.
72
+
73
+ Manage installed releases explicitly when needed:
74
+
75
+ ```bash
76
+ pcbridge frontend list
77
+ pcbridge frontend update
78
+ pcbridge frontend use playcanvas-editor-v2.28.1-r1
79
+ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
80
+ ```
81
+
82
+ Downloaded builds live under `~/.pcbridge/frontends/`. Removing the active release is refused
83
+ until another installed release is selected.
84
+
57
85
  ## Start the bridge
58
86
 
59
87
  ```bash
@@ -66,6 +94,7 @@ In another terminal:
66
94
  pcbridge doctor
67
95
  pcbridge targets
68
96
  pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
97
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc }"
69
98
  ```
70
99
 
71
100
  ## Progressive help
@@ -74,6 +103,7 @@ The CLI exposes layered help so agents can load only the command surface they ne
74
103
 
75
104
  ```bash
76
105
  pcbridge help
106
+ pcbridge help frontend
77
107
  pcbridge help entity
78
108
  pcbridge help asset
79
109
  pcbridge help material
@@ -82,12 +112,14 @@ pcbridge help script
82
112
  pcbridge help scene
83
113
  pcbridge help store
84
114
  pcbridge help viewport
115
+ pcbridge help launch
116
+ pcbridge help logs
85
117
  pcbridge help eval
86
118
  ```
87
119
 
88
120
  Use structured commands for small, known operations that map cleanly to one Editor action. Use
89
- `pcbridge eval` for exploratory work, custom Editor/Engine API workflows, and large multi-step
90
- scene edits where one script is clearer and faster than many CLI calls.
121
+ `pcbridge eval` for exploratory work, custom Editor/Engine API workflows, Launch debugging, and
122
+ large multi-step scene edits where one script is clearer and faster than many CLI calls.
91
123
 
92
124
  ## Common commands
93
125
 
@@ -110,6 +142,7 @@ pcbridge asset get --target current --id <asset_id>
110
142
  pcbridge asset create --target current --json ./assets.json
111
143
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
112
144
  pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
145
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
113
146
  pcbridge asset instantiate --target current --id <template_asset_id>
114
147
  pcbridge asset delete --target current --id <asset_id>
115
148
 
@@ -120,6 +153,7 @@ pcbridge template create --target current --entity-id <resource_id> --name DemoT
120
153
  pcbridge template instantiate --target current --id <template_asset_id>
121
154
 
122
155
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
156
+ pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse
123
157
  pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
124
158
  pcbridge script parse --target current --asset-id <asset_id>
125
159
 
@@ -132,6 +166,31 @@ pcbridge store download --target current --id <store_asset_id> --name Vehicle --
132
166
 
133
167
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
134
168
  pcbridge viewport focus --target current --id <resource_id> --view perspective
169
+
170
+ pcbridge logs get --target current --limit 100
171
+ pcbridge logs get --target launch:<sceneId> --level error
172
+ pcbridge logs clear --target current
173
+ ```
174
+
175
+ For task-sized installs, keep upload manifests next to the generated files. Relative `file` paths are resolved from the manifest location:
176
+
177
+ ```json
178
+ {
179
+ "assets": [
180
+ {
181
+ "key": "player",
182
+ "file": "final/player.png",
183
+ "name": "DemoPlayer",
184
+ "folder": "AI Agent Bridge/Demo/Textures"
185
+ }
186
+ ]
187
+ }
188
+ ```
189
+
190
+ Use `eval --args-json` when a large Editor script needs local configuration without embedding JSON into source:
191
+
192
+ ```bash
193
+ pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
135
194
  ```
136
195
 
137
196
  ## Texture + material + script workflow
@@ -157,9 +216,15 @@ pcbridge eval --target current --code "return location.href"
157
216
  pcbridge eval --target tab:123 --code "return location.href"
158
217
  pcbridge eval --target scene:987654 --code "return location.href"
159
218
  pcbridge eval --target project:123456 --code "return location.href"
219
+ pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
220
+ pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
221
+ pcbridge logs get --target launch:987654 --limit 100
160
222
  ```
161
223
 
162
- `current` means the most recently seen ready PlayCanvas Editor target.
224
+ `current` means the most recently seen ready PlayCanvas target. If both the Editor and Launch page
225
+ are open for the same scene, use `tab:<id>`, `editor:<sceneId>`, or `launch:<sceneId>` to avoid
226
+ ambiguity. Editor-only structured commands require an Editor target; `eval`, `viewport capture`,
227
+ and `logs` also work on Launch targets.
163
228
 
164
229
  ## Agent skills
165
230
 
@@ -182,13 +247,15 @@ Installed locations:
182
247
 
183
248
  ## Security model
184
249
 
185
- This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor pages that you already have open.
250
+ This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor and Launch pages that you already have open.
186
251
 
187
252
  Safeguards:
188
253
 
189
254
  - daemon binds only to `127.0.0.1`;
255
+ - the frontend server binds only to `127.0.0.1`, validates the Host header, and serves only files
256
+ under the active verified release;
190
257
  - CLI, daemon, and extension share a local session token;
191
- - extension matches only PlayCanvas Editor URLs;
258
+ - extension matches only PlayCanvas Editor and Launch URLs;
192
259
  - CLI output uses compact JSON envelopes;
193
260
  - structured write commands require explicit IDs or JSON files.
194
261
 
@@ -201,3 +268,22 @@ node dist/cli.js doctor
201
268
  ```
202
269
 
203
270
  Use `bun` for one-off TypeScript scripts if you add them.
271
+
272
+ ## Publishing to npm (maintainers)
273
+
274
+ Publishing uses npm Trusted Publishing through `.github/workflows/npm-publish.yml`; the GitHub
275
+ repository does not need an `NPM_TOKEN` secret.
276
+
277
+ 1. Update the same stable version in `package.json`, `src/config.ts`, and
278
+ `extension/manifest.json`.
279
+ 2. Run `pnpm test`, commit the release to `main`, and push `main`.
280
+ 3. Create and push the matching tag, for example:
281
+
282
+ ```bash
283
+ git tag v0.3.0
284
+ git push origin v0.3.0
285
+ ```
286
+
287
+ The workflow rejects tags that do not match the package version or whose commit is not on `main`.
288
+ Configure the npm package's Trusted Publisher with GitHub user `Q-My99`, repository
289
+ `playcanvas-agent-bridge-cli`, and workflow filename `npm-publish.yml` before pushing the tag.
package/README.zh-CN.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
- 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景。
3
+ 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景和 PlayCanvas Launch 页面。
4
4
 
5
5
  核心接口是 `pcbridge` 命令、本地 daemon 和 Chrome Manifest V3 插件。MCP 不是核心依赖,之后可以作为薄适配层再加。
6
6
 
@@ -50,10 +50,38 @@ pcbridge install-extension
50
50
  2. 开启 Developer Mode。
51
51
  3. 点击 Load unpacked。
52
52
  4. 选择 `pcbridge install-extension` 打印出来的那个目录。
53
- 5. 打开或刷新 PlayCanvas Editor 页面。
53
+ 5. 打开或刷新 PlayCanvas Editor 页面或 PlayCanvas Launch 页面。
54
54
 
55
55
  注意:生成目录里的 `config.json` 包含本地 session token。请加载 `~/.pcbridge/extension`,不要直接加载仓库里的原始 `extension/` 目录。
56
56
 
57
+ ## 使用自构建 Editor 前端
58
+
59
+ Editor 构建产物不会打进 npm 包。下面的命令会从 `Q-My99/playcanvas-editor` 下载最新
60
+ Release,校验发布清单、文件大小和 SHA-256,然后在本地激活:
61
+
62
+ ```bash
63
+ pcbridge frontend install latest
64
+ pcbridge frontend status
65
+ pcbridge daemon start
66
+ ```
67
+
68
+ daemon 会在 `http://localhost:3487` 提供当前激活的构建。打开
69
+ `https://playcanvas.com/editor/...` 页面后,在插件 popup 中点击 **Use custom frontend**。
70
+ 点击 **Use official frontend** 会删除 `use_local_frontend` 参数,并用官方前端重新加载同一个
71
+ Editor URL。
72
+
73
+ 需要时可以显式管理本地版本:
74
+
75
+ ```bash
76
+ pcbridge frontend list
77
+ pcbridge frontend update
78
+ pcbridge frontend use playcanvas-editor-v2.28.1-r1
79
+ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
80
+ ```
81
+
82
+ 下载的构建保存在 `~/.pcbridge/frontends/`。当前激活的版本不能直接删除,需要先切换到
83
+ 另一个已安装版本。
84
+
57
85
  ## 启动桥接
58
86
 
59
87
  ```bash
@@ -66,6 +94,7 @@ pcbridge daemon start
66
94
  pcbridge doctor
67
95
  pcbridge targets
68
96
  pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
97
+ pcbridge eval --target launch:<sceneId> --code "return { href: location.href, hasPc: !!pc }"
69
98
  ```
70
99
 
71
100
  ## 渐进式 help
@@ -74,6 +103,7 @@ CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
74
103
 
75
104
  ```bash
76
105
  pcbridge help
106
+ pcbridge help frontend
77
107
  pcbridge help entity
78
108
  pcbridge help asset
79
109
  pcbridge help material
@@ -82,11 +112,13 @@ pcbridge help script
82
112
  pcbridge help scene
83
113
  pcbridge help store
84
114
  pcbridge help viewport
115
+ pcbridge help launch
116
+ pcbridge help logs
85
117
  pcbridge help eval
86
118
  ```
87
119
 
88
120
  小而明确、能对应到单个 Editor 操作的任务优先用结构化命令。探索 API、自定义
89
- Editor/Engine 工作流、大量多步骤场景修改,则优先用 `pcbridge eval`,一段脚本通常更清楚也更快。
121
+ Editor/Engine 工作流、Launch 调试、大量多步骤场景修改,则优先用 `pcbridge eval`,一段脚本通常更清楚也更快。
90
122
 
91
123
  ## 常用命令
92
124
 
@@ -109,6 +141,7 @@ pcbridge asset get --target current --id <asset_id>
109
141
  pcbridge asset create --target current --json ./assets.json
110
142
  pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
111
143
  pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
144
+ pcbridge asset upload-many --target current --json ./upload-manifest.json
112
145
  pcbridge asset instantiate --target current --id <template_asset_id>
113
146
  pcbridge asset delete --target current --id <asset_id>
114
147
 
@@ -119,6 +152,7 @@ pcbridge template create --target current --entity-id <resource_id> --name DemoT
119
152
  pcbridge template instantiate --target current --id <template_asset_id>
120
153
 
121
154
  pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
155
+ pcbridge script upsert --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse
122
156
  pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
123
157
  pcbridge script parse --target current --asset-id <asset_id>
124
158
 
@@ -131,6 +165,31 @@ pcbridge store download --target current --id <store_asset_id> --name Vehicle --
131
165
 
132
166
  pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
133
167
  pcbridge viewport focus --target current --id <resource_id> --view perspective
168
+
169
+ pcbridge logs get --target current --limit 100
170
+ pcbridge logs get --target launch:<sceneId> --level error
171
+ pcbridge logs clear --target current
172
+ ```
173
+
174
+ 大型任务可以把上传清单放在生成文件旁边。`file` 的相对路径会按清单文件所在目录解析:
175
+
176
+ ```json
177
+ {
178
+ "assets": [
179
+ {
180
+ "key": "player",
181
+ "file": "final/player.png",
182
+ "name": "DemoPlayer",
183
+ "folder": "AI Agent Bridge/Demo/Textures"
184
+ }
185
+ ]
186
+ }
187
+ ```
188
+
189
+ 当较大的 Editor 脚本需要本地配置时,用 `eval --args-json`,避免把 JSON 直接拼进代码里:
190
+
191
+ ```bash
192
+ pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
134
193
  ```
135
194
 
136
195
  ## 贴图 + 材质 + 脚本工作流
@@ -156,9 +215,14 @@ pcbridge eval --target current --code "return location.href"
156
215
  pcbridge eval --target tab:123 --code "return location.href"
157
216
  pcbridge eval --target scene:987654 --code "return location.href"
158
217
  pcbridge eval --target project:123456 --code "return location.href"
218
+ pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
219
+ pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
220
+ pcbridge logs get --target launch:987654 --limit 100
159
221
  ```
160
222
 
161
- `current` 表示最近可用的 PlayCanvas Editor 目标页。
223
+ `current` 表示最近可用的 PlayCanvas 目标页。如果同一个 scene 同时打开了 Editor 和 Launch
224
+ 页面,请使用 `tab:<id>`、`editor:<sceneId>` 或 `launch:<sceneId>` 避免歧义。结构化编辑命令需要
225
+ Editor 目标;`eval`、`viewport capture` 和 `logs` 也可以用于 Launch 目标。
162
226
 
163
227
  ## Agent skill / rules
164
228
 
@@ -181,13 +245,14 @@ pcbridge install-skill --agent all
181
245
 
182
246
  ## 安全模型
183
247
 
184
- 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 页面内执行 JavaScript。
248
+ 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 和 Launch 页面内执行 JavaScript。
185
249
 
186
250
  基础防护:
187
251
 
188
252
  - daemon 只绑定 `127.0.0.1`;
253
+ - frontend 服务只绑定 `127.0.0.1`,会校验 Host,并且只提供当前已校验 Release 目录内的文件;
189
254
  - CLI、daemon、插件共享本地 session token;
190
- - 插件只匹配 PlayCanvas Editor URL;
255
+ - 插件只匹配 PlayCanvas Editor 和 Launch URL;
191
256
  - CLI 输出统一使用紧凑 JSON envelope;
192
257
  - 结构化写命令要求明确 ID 或 JSON 文件。
193
258
 
@@ -200,3 +265,21 @@ node dist/cli.js doctor
200
265
  ```
201
266
 
202
267
  如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
268
+
269
+ ## 发布到 npm(维护者)
270
+
271
+ 发布流程通过 `.github/workflows/npm-publish.yml` 使用 npm Trusted Publishing,GitHub
272
+ 仓库不需要保存 `NPM_TOKEN`。
273
+
274
+ 1. 在 `package.json`、`src/config.ts` 和 `extension/manifest.json` 中同步更新同一个稳定版本号。
275
+ 2. 运行 `pnpm test`,把发布提交合并并推送到 `main`。
276
+ 3. 创建并推送匹配的 tag,例如:
277
+
278
+ ```bash
279
+ git tag v0.3.0
280
+ git push origin v0.3.0
281
+ ```
282
+
283
+ 如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。
284
+ 推送 tag 前,需要在 npm 包设置中把 GitHub 用户设为 `Q-My99`、仓库设为
285
+ `playcanvas-agent-bridge-cli`、workflow 文件名设为 `npm-publish.yml`。