playcanvas-agent-bridge-cli 0.3.0 → 0.5.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.zh-CN.md CHANGED
@@ -13,6 +13,9 @@ npm install -g playcanvas-agent-bridge-cli
13
13
  pcbridge install-skill --agent all
14
14
  ```
15
15
 
16
+ 下文命令包含仓库版 `0.5.0` 的尚未发布改动。在该版本发布前,npm 的 `latest`(截至
17
+ 2026-08-04 为 `0.3.0`)不包含这里列出的全部命令;测试本轮新能力时请使用 GitHub 安装。
18
+
16
19
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
17
20
 
18
21
  ```bash
@@ -70,6 +73,12 @@ daemon 会在 `http://localhost:3487` 提供当前激活的构建。打开
70
73
  点击 **Use official frontend** 会删除 `use_local_frontend` 参数,并用官方前端重新加载同一个
71
74
  Editor URL。
72
75
 
76
+ 插件会按 PlayCanvas project ID 记住最后一次在 popup 中选择的模式。之后进入
77
+ `/editor/project/<projectId>` 场景选择页或 `/editor/scene/<sceneId>` 场景编辑页时,会自动
78
+ 添加或删除 `use_local_frontend`,并保留 URL 中其他查询参数和 hash。该偏好只会在用户再次
79
+ 点击 **Use custom frontend** 或 **Use official frontend** 时改变;popup 的 **Project
80
+ preference** 会显示当前项目的记忆值。
81
+
73
82
  需要时可以显式管理本地版本:
74
83
 
75
84
  ```bash
@@ -84,26 +93,102 @@ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
84
93
 
85
94
  ## 启动桥接
86
95
 
96
+ 请先进入希望作为本地工作区根目录的位置,再启动 daemon:
97
+
87
98
  ```bash
99
+ cd /path/to/my-playcanvas-workspace
88
100
  pcbridge daemon start
89
101
  ```
90
102
 
103
+ 连接 ready 的 Editor 后,pcbridge 会自动创建 `<projectId>-<projectName>/` 工程目录:
104
+
105
+ ```text
106
+ 1552681-pcbridge-test/
107
+ ├── pcbridge.project.json # 项目信息和供 agent 读取的资源目录
108
+ ├── assets/ # 与 PlayCanvas 文件夹结构对应,所有文件内容自动双向同步
109
+ ├── tmp/ # 构建产物、缓存、冲突、截图和远端删除隔离副本
110
+ └── .pcbridge/ # 内部同步状态,请勿手动修改
111
+ ```
112
+
113
+ 查看或手动刷新工作区:
114
+
115
+ ```bash
116
+ pcbridge workspace status --target editor:<sceneId>
117
+ pcbridge workspace path --target editor:<sceneId>
118
+ pcbridge workspace sync --target editor:<sceneId>
119
+ pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
120
+ ```
121
+
122
+ 脚本、图片、模型、音频等文件内容都保持双向同步。首次建立镜像会下载项目文件;之后每轮
123
+ 刷新只读取完整 Asset 元数据,并用 PlayCanvas MD5 与本地缓存的 size/mtime/MD5 判断变化,
124
+ 不会重复全量传输文件内容。本地单边修改会上传,远端单边修改会下载;同时修改时不会覆盖
125
+ 任一版本,文本和二进制冲突副本都写入 `tmp/conflicts/`。资源的新建、移动、重命名和删除
126
+ 仍应使用 pcbridge 结构化命令;`workspace pull` 可用于显式重新拉取单个文件。
127
+
128
+ schema v2 的 `pcbridge.project.json` 会记录每个 asset 的 id、类型、PlayCanvas 文件夹、相对
129
+ 项目根目录的 `assets/...` 文件路径、是否已下载,以及远端、本地和同步基线 MD5。agent 可以
130
+ 直接读取这些信息,但其中的 `assets` 对象由 pcbridge 管理。已有 schema v1 隐藏索引会自动
131
+ 迁移,并保留为 `.pcbridge/asset-index.v1.json` 以便回退。已有资源时收到的空快照会被忽略;
132
+ 非空但缩小的快照必须连续出现两次,文件才会被移动到 `tmp/trash/remote/`。
133
+
134
+ ## Template 构建与 S3 上传
135
+
136
+ 选中 PlayCanvas Template Asset 后,Attributes 面板会出现 **pcbridge Tiny Builder**。点击
137
+ **构建并上传到 S3** 后,网页只负责收集 Template、递归 Asset 引用、挂载脚本和子 Template;
138
+ daemon 会核对工作区 MD5,缺失或远端更新的文件才会下载到工作区,然后直接并发上传对象,
139
+ 不再生成 ZIP。生成的 `tinyapp.json` 和 `gamescript.js` 保存在 `tmp/builds/`,变体和字体附加
140
+ 贴图缓存于 `tmp/cache/assets/`。
141
+
142
+ 在 daemon 启动目录创建 `.env` 作为工作区默认配置,也可以在单个项目目录创建 `.env`;
143
+ 项目配置按字段覆盖工作区配置。不要提交含密钥的 `.env`:
144
+
145
+ ```dotenv
146
+ PCBRIDGE_S3_ENDPOINT=https://s3.example.com
147
+ PCBRIDGE_S3_REGION=us-east-1
148
+ PCBRIDGE_S3_BUCKET=my-bucket
149
+ PCBRIDGE_S3_ACCESS_KEY_ID=your-access-key
150
+ PCBRIDGE_S3_SECRET_ACCESS_KEY=your-secret-key
151
+ # PCBRIDGE_S3_SESSION_TOKEN=
152
+ PCBRIDGE_S3_PUBLIC_BASE_URL=https://cdn.example.com
153
+ PCBRIDGE_S3_PREFIX=assets
154
+ PCBRIDGE_S3_FORCE_PATH_STYLE=false
155
+ ```
156
+
157
+ 以上配置使用 AWS S3 标准客户端,适用于 Amazon S3、阿里云 OSS、腾讯云 COS、Cloudflare
158
+ R2 等兼容服务;自定义服务是否需要 path-style URL 由
159
+ `PCBRIDGE_S3_FORCE_PATH_STYLE` 决定。也可以从 CLI 发起和查看任务:
160
+
161
+ ```bash
162
+ pcbridge builder start --target editor:<sceneId> --asset <templateAssetId> --suffix '-${time}'
163
+ pcbridge builder status --job <jobId>
164
+ ```
165
+
166
+ CLI 的脚本、JSON、上传文件和截图路径默认必须位于对应项目工作区内。只有明确需要使用
167
+ 外部文件时才使用 `--allow-external-path`。
168
+
91
169
  另开一个终端检查:
92
170
 
93
171
  ```bash
94
172
  pcbridge doctor
95
173
  pcbridge targets
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 }"
174
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor }"
175
+ pcbridge launch diagnose --target launch:<sceneId>
98
176
  ```
99
177
 
178
+ `doctor` 会区分 daemon 未监听(`DAEMON_NOT_LISTENING`)和受限环境禁止 localhost
179
+ (`LOOPBACK_ACCESS_DENIED`);只有前一种情况才应该再启动 daemon。
180
+
100
181
  ## 渐进式 help
101
182
 
102
183
  CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
103
184
 
104
185
  ```bash
105
186
  pcbridge help
187
+ pcbridge help core
188
+ pcbridge help workspace
189
+ pcbridge help builder
106
190
  pcbridge help frontend
191
+ pcbridge help target
107
192
  pcbridge help entity
108
193
  pcbridge help asset
109
194
  pcbridge help material
@@ -123,54 +208,70 @@ Editor/Engine 工作流、Launch 调试、大量多步骤场景修改,则优
123
208
  ## 常用命令
124
209
 
125
210
  ```bash
126
- pcbridge entity list --target current --limit 50
127
- pcbridge entity list --target current --tag enemy --component render
128
- pcbridge entity create --target current --json ./entity.json
129
- pcbridge entity create-many --target current --json ./entities.json
130
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
131
- pcbridge entity patch-many --target current --json ./edits.json
132
- pcbridge entity duplicate --target current --id <resource_id>
133
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
134
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
135
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
136
- pcbridge entity delete --target current --id <resource_id>
137
-
138
- pcbridge asset list --target current --type script
139
- pcbridge asset list --target current --tag generated
140
- pcbridge asset get --target current --id <asset_id>
141
- pcbridge asset create --target current --json ./assets.json
142
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
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
145
- pcbridge asset instantiate --target current --id <template_asset_id>
146
- pcbridge asset delete --target current --id <asset_id>
147
-
148
- pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
149
- pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
150
-
151
- pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
152
- pcbridge template instantiate --target current --id <template_asset_id>
153
-
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
156
- pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
157
- pcbridge script parse --target current --asset-id <asset_id>
158
-
159
- pcbridge scene settings get --target current
160
- pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
161
-
162
- pcbridge store search --target current --search vehicle --limit 20
163
- pcbridge store get --target current --id <store_asset_id>
164
- pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
165
-
166
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
167
- pcbridge viewport focus --target current --id <resource_id> --view perspective
168
-
169
- pcbridge logs get --target current --limit 100
211
+ pcbridge entity list --target editor:<sceneId> --limit 50
212
+ pcbridge entity list --target editor:<sceneId> --tag enemy --component render
213
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
214
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
215
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
216
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
217
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
218
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
219
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
220
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
221
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
222
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
223
+
224
+ pcbridge asset list --target editor:<sceneId> --type script
225
+ pcbridge asset list --target editor:<sceneId> --tag generated
226
+ pcbridge asset get --target editor:<sceneId> --id <asset_id>
227
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
228
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Demo/Textures"
229
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
230
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
231
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
232
+ pcbridge asset delete --target editor:<sceneId> --id <asset_id>
233
+
234
+ pcbridge material create --target editor:<sceneId> --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
235
+ pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --set diffuse='[1,0,0]'
236
+
237
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
238
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
239
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
240
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
241
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
242
+
243
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
244
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse --wait
245
+ pcbridge script set-text --target editor:<sceneId> --asset-id <asset_id> --file ./controller.js --parse --wait
246
+ pcbridge script parse --target editor:<sceneId> --asset-id <asset_id>
247
+
248
+ pcbridge scene settings get --target editor:<sceneId>
249
+ pcbridge scene settings patch --target editor:<sceneId> --set physics.gravity='[0,-9.8,0]'
250
+
251
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
252
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
253
+ pcbridge store download --target editor:<sceneId> --id <store_asset_id> --name Vehicle --license-json ./license.json
254
+
255
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
256
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
257
+
258
+ pcbridge logs get --target editor:<sceneId> --limit 100
170
259
  pcbridge logs get --target launch:<sceneId> --level error
171
- pcbridge logs clear --target current
260
+ pcbridge logs clear --target editor:<sceneId>
172
261
  ```
173
262
 
263
+ 通过 bundle 或 runtime asset 注册、没有独立 script asset id 的 ScriptType,请使用
264
+ `--script-name`。脚本更新配合 `--parse --wait` 时,会在返回前校验远端文本、稳定的文件元数据
265
+ 以及最新的解析属性。这个完成检查覆盖远端 asset 和当前 Editor observer,不等待之后一次
266
+ workspace mirror sync。
267
+
268
+ Template apply 命令会调用 Editor 现有的 `templates:apply` action。存在 overrides 时,完成条件
269
+ 是 pipeline callback 已到达,且连续两次观察到 overrides 为 0。返回的 `verified` 只确认当前
270
+ Editor observer 状态,不代表刷新 Editor 后仍然持久。
271
+ Editor entity patch 是持久修改;apply 前必须先恢复只用于预览的 enabled/visibility 状态。
272
+ `apply-many` 会先校验清单,再串行处理每个 root。清单可以写成
273
+ `{"entityIds":["root-a","root-b"]}`,也可直接使用 entity id 或 `{ "entityId": "..." }` 条目数组。
274
+
174
275
  大型任务可以把上传清单放在生成文件旁边。`file` 的相对路径会按清单文件所在目录解析:
175
276
 
176
277
  ```json
@@ -189,22 +290,22 @@ pcbridge logs clear --target current
189
290
  当较大的 Editor 脚本需要本地配置时,用 `eval --args-json`,避免把 JSON 直接拼进代码里:
190
291
 
191
292
  ```bash
192
- pcbridge eval --target current --file ./install-scene.js --args-json ./install-args.json
293
+ pcbridge eval --target editor:<sceneId> --file ./install-scene.js --args-json ./install-args.json
193
294
  ```
194
295
 
195
296
  ## 贴图 + 材质 + 脚本工作流
196
297
 
197
298
  ```bash
198
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
199
- pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
299
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
300
+ pcbridge asset upload --target editor:<sceneId> --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
200
301
 
201
- pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
302
+ pcbridge material create --target editor:<sceneId> --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
202
303
 
203
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
304
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
204
305
 
205
- pcbridge entity create --target current --json ./box.json
206
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
207
- pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
306
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
307
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
308
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
208
309
  ```
209
310
 
210
311
  ## 目标选择
@@ -215,7 +316,9 @@ pcbridge eval --target current --code "return location.href"
215
316
  pcbridge eval --target tab:123 --code "return location.href"
216
317
  pcbridge eval --target scene:987654 --code "return location.href"
217
318
  pcbridge eval --target project:123456 --code "return location.href"
218
- pcbridge eval --target launch:987654 --code "return { href: location.href, hasPc: !!pc }"
319
+ pcbridge launch diagnose --target launch:987654
320
+ pcbridge launch wait-ready --target launch:987654 --focus --timeout-ms 30000
321
+ pcbridge eval --target launch:987654 --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
219
322
  pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
220
323
  pcbridge logs get --target launch:987654 --limit 100
221
324
  ```
@@ -224,6 +327,16 @@ pcbridge logs get --target launch:987654 --limit 100
224
327
  页面,请使用 `tab:<id>`、`editor:<sceneId>` 或 `launch:<sceneId>` 避免歧义。结构化编辑命令需要
225
328
  Editor 目标;`eval`、`viewport capture` 和 `logs` 也可以用于 Launch 目标。
226
329
 
330
+ Launch ready 是尽力而为的启发式判断,不是 Engine 生命周期事件。`lifecycleReady` 要求找到
331
+ 拥有自身 graphics canvas/context 的 runtime app、scene root 已挂载、至少完成一帧,并且没有
332
+ 识别到启动遮罩;target `ready` 还要求 tab 可见。因此后台 Launch 应使用
333
+ `launch wait-ready --focus`。`scriptTypeCount` 只用于诊断,不能证明所有 ScriptType 已注册。
334
+ eval 提供通过兼容 resolver 选择的 Engine V1/V2 `runtimeApp`。
335
+
336
+ `viewport capture` 只截取当前 canvas,不会调整 Chrome 尺寸或模拟手机 DPR。PNG 可能保留
337
+ 透明通道;默认的 `--max-width 1200` 可能缩放输出。eval 输出有边界;优先返回叶子字段,必要时再使用有
338
+ 上限的 `--max-depth`、`--max-items` 或 `--max-keys`。
339
+
227
340
  ## Agent skill / rules
228
341
 
229
342
  安装各家 agent 的使用说明:
@@ -243,6 +356,10 @@ pcbridge install-skill --agent all
243
356
  - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
244
357
  - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
245
358
 
359
+ 插件 popup 会展示 daemon、当前 tab、项目、scene、branch、工作区路径、同步统计、冲突数
360
+ 以及自定义 Editor frontend 状态。红色表示断联或冲突,黄色表示初始化、同步中或本地待处理
361
+ 状态,绿色表示 ready / synced。
362
+
246
363
  ## 安全模型
247
364
 
248
365
  这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 和 Launch 页面内执行 JavaScript。
@@ -276,8 +393,8 @@ node dist/cli.js doctor
276
393
  3. 创建并推送匹配的 tag,例如:
277
394
 
278
395
  ```bash
279
- git tag v0.3.0
280
- git push origin v0.3.0
396
+ git tag v<version>
397
+ git push origin v<version>
281
398
  ```
282
399
 
283
400
  如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。