playcanvas-agent-bridge-cli 0.6.1 → 0.7.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.
Files changed (42) hide show
  1. package/README.md +148 -31
  2. package/README.zh-CN.md +137 -33
  3. package/dist/cli.js +514 -95
  4. package/dist/config.js +23 -1
  5. package/dist/daemon/server.js +336 -28
  6. package/dist/daemon/target-registry.js +3 -0
  7. package/dist/plugins/host.js +260 -0
  8. package/dist/plugins/store.js +567 -0
  9. package/dist/processing/manager.js +265 -0
  10. package/dist/processing/tools.js +97 -0
  11. package/dist/snippets.js +27 -0
  12. package/dist/updates.js +475 -0
  13. package/dist/workspace/json-sync.js +821 -0
  14. package/dist/workspace/manager.js +1973 -326
  15. package/extension/icons/icon-128.png +0 -0
  16. package/extension/icons/icon-16.png +0 -0
  17. package/extension/icons/icon-256.png +0 -0
  18. package/extension/icons/icon-32.png +0 -0
  19. package/extension/icons/icon-48.png +0 -0
  20. package/extension/isolated.js +59 -2
  21. package/extension/main.js +770 -275
  22. package/extension/manifest.json +60 -10
  23. package/extension/popup.html +115 -3
  24. package/extension/popup.js +398 -14
  25. package/extension/service-worker.js +221 -4
  26. package/package.json +18 -18
  27. package/plugins/index.json +14 -0
  28. package/plugins/tinyapp-builder/node/builder.js +589 -0
  29. package/plugins/tinyapp-builder/node/index.js +30 -0
  30. package/plugins/tinyapp-builder/package.json +13 -0
  31. package/plugins/tinyapp-builder/page/editor.js +249 -0
  32. package/plugins/tinyapp-builder/pcbridge-plugin.json +28 -0
  33. package/skills/claude/pcbridge-plugin-authoring/SKILL.md +220 -0
  34. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +99 -43
  35. package/skills/codex/pcbridge-plugin-authoring/SKILL.md +220 -0
  36. package/skills/codex/pcbridge-plugin-authoring/agents/openai.yaml +4 -0
  37. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +89 -62
  38. package/skills/cursor/pcbridge-plugin-authoring.mdc +221 -0
  39. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +69 -33
  40. package/skills/windsurf/pcbridge-plugin-authoring.md +215 -0
  41. package/skills/windsurf/playcanvas-agent-bridge-cli.md +68 -33
  42. package/dist/builder/manager.js +0 -564
package/README.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
+ Scene management: `scene list`, `scene create --name <name>`, and `scene open --id <id>` use the selected Editor project; opening waits for the matching scene load. `asset upload` infers GLB/FBX/OBJ files as model sources (`scene`).
4
+
5
+ In the parent PlayCanvas workspace, `bun run pcbridge <command>` defaults to the root `pcbridge-workspace/` directory (created automatically and ignored by Git). `bun run dev` starts the daemon from the current source and stops it on exit. If the daemon port is occupied, run `bun run pcbridge daemon stop` first. The extension popup shows its own version separately from the daemon version, including while offline.
6
+
7
+ > Requires Bun 1.4.0 or newer. In the parent monorepo, run `bun install --frozen-lockfile` at the workspace root.
8
+
3
9
  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
10
 
5
11
  The core interface is the `pcbridge` command plus a local daemon and a Chrome Manifest V3 extension. MCP is intentionally not required.
@@ -9,18 +15,18 @@ The core interface is the `pcbridge` command plus a local daemon and a Chrome Ma
9
15
  From npm:
10
16
 
11
17
  ```bash
12
- npm install -g playcanvas-agent-bridge-cli
18
+ bun add --global playcanvas-agent-bridge-cli
13
19
  pcbridge install-skill --agent all
14
20
  ```
15
21
 
16
22
  From this GitHub repository for unreleased changes:
17
23
 
18
24
  ```bash
19
- npm install -g github:Q-My99/playcanvas-agent-bridge-cli
25
+ bun add --global github:Q-My99/playcanvas-agent-bridge-cli
20
26
  pcbridge install-skill --agent all
21
27
  ```
22
28
 
23
- The commands documented below track repository version `0.6.1`. npm installs the latest stable
29
+ The commands documented below track repository version `0.7.0`. bun installs the latest stable
24
30
  release; use the GitHub install when testing changes that have not been released yet.
25
31
 
26
32
  One-shot with npx:
@@ -32,15 +38,38 @@ npx playcanvas-agent-bridge-cli install-skill --agent all
32
38
 
33
39
  ## Update pcbridge components
34
40
 
35
- The CLI/daemon, installed agent skills, generated Chrome extension, and optional custom Editor
36
- frontend are separate local components. Updating one does not update the others automatically.
41
+ `pcbridge` automatically checks npm for newer CLI/extension releases and checks GitHub
42
+ (`plugins/index.json`) for independent official plugin updates. When an update is available:
43
+
44
+ - **Extension badge & popup**: The Chrome toolbar icon displays an `↑` badge. Open the popup to
45
+ click **Update & Reload** (for `pcbridge` core) or **Update** / **Update all** under the
46
+ **Plugins** tab.
47
+ - **CLI & AI agents**: Commands attach structured `meta.updates` to JSON responses and print a
48
+ single-line notice to `stderr` in interactive terminals.
37
49
 
38
- ### Update the CLI, daemon, and agent skills
50
+ ### One-click update (CLI, daemon, skills, Chrome extension, and plugins)
39
51
 
40
52
  ```bash
41
- npm install -g playcanvas-agent-bridge-cli@latest
53
+ pcbridge update status --refresh # check core and plugin update availability
54
+ pcbridge update # one-click update CLI, daemon, skills, extension, and open tabs
55
+ pcbridge update --plugins # also update all outdated installed plugins
56
+ pcbridge plugin update <id> # hot-update a single plugin without restarting daemon
57
+ pcbridge plugin update --all # hot-update all outdated installed plugins
58
+ ```
59
+
60
+ `pcbridge update` upgrades the global npm package, rewrites `~/.pcbridge/extension` and installed
61
+ agent skills using the newly installed version, reloads the unpacked Chrome extension via
62
+ `chrome.runtime.reload()`, refreshes open PlayCanvas Editor/Launch tabs (pass `--no-reload-tabs` to
63
+ skip tab refresh), and restarts the running daemon in-place in its original terminal while
64
+ preserving its `--workspace` root.
65
+
66
+ ### Manual component update commands
67
+
68
+ ```bash
69
+ bun add --global playcanvas-agent-bridge-cli@latest
42
70
  pcbridge version
43
71
  pcbridge install-skill --agent all
72
+ pcbridge install-extension --no-open
44
73
  pcbridge daemon restart --workspace /the/workspace/root
45
74
  ```
46
75
 
@@ -140,6 +169,12 @@ add or remove `use_local_frontend` while preserving other query parameters and t
140
169
  preference changes only when the user clicks **Use custom frontend** or **Use official frontend**
141
170
  again, and the popup shows the remembered value under **Project preference**.
142
171
 
172
+ A remembered custom preference is applied even when the daemon or frontend listener is unavailable,
173
+ so the Editor fails visibly instead of silently falling back to the official frontend. The popup
174
+ reports whether the daemon is offline, the frontend server is stopped, or no release is installed.
175
+ The pcbridge daemon and its frontend listener are started together from the terminal; the extension
176
+ does not attempt to start local processes.
177
+
143
178
  Manage installed releases explicitly when needed:
144
179
 
145
180
  ```bash
@@ -180,9 +215,10 @@ When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` auto
180
215
  ```text
181
216
  1552681-pcbridge-test/
182
217
  ├── pcbridge.project.json # project metadata plus the agent-readable asset catalog
218
+ ├── scenes/ # active writable .scene.json plus read-only mirrors of inactive scenes
183
219
  ├── assets/ # collision-safe projection of the PlayCanvas folder tree
184
- ├── tmp/ # builds, cache, conflicts, captures, and quarantined remote deletions
185
- └── .pcbridge/ # internal sync state and content-addressed object cache; do not edit
220
+ ├── tmp/ # builds, cache, conflicts, captures, and local/remote deletion trash
221
+ └── .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
186
222
  ```
187
223
 
188
224
  Inspect or refresh the workspace with:
@@ -190,27 +226,43 @@ Inspect or refresh the workspace with:
190
226
  ```bash
191
227
  pcbridge workspace status --target editor:<sceneId>
192
228
  pcbridge workspace path --target editor:<sceneId>
229
+ pcbridge workspace settings [--eager-max-mb <1..10>]
193
230
  pcbridge workspace sync --target editor:<sceneId>
194
231
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
195
232
  ```
196
233
 
197
- Scripts are eagerly mirrored and kept close to real time. Images, models, audio, fonts, and other
198
- binary assets are lazy: refresh records the Asset metadata and PlayCanvas MD5 without downloading
199
- file contents. Use `workspace pull`, or let Tiny Builder fetch the dependencies needed for a build.
200
- Existing binary files under `assets/` are retained and remain bidirectional. Local edits upload,
201
- remote edits download according to the sync baseline, and concurrent edits preserve both copies under
202
- `tmp/conflicts/`. New local files are uploaded into their matching folder and PlayCanvas decides the
203
- imported type; local folders are created remotely. Renames and moves preserve the Asset ID. Deleting
204
- a local file only clears the local cache and never deletes the remote Asset. The `tmp/` tree is
205
- agent-owned and excluded from workspace synchronization.
234
+ Synchronization is event-driven over WebSocket deltas (`workspace:delta`) and targeted local
235
+ `fs.watch` dirty paths without idle polling. Text assets (`script`, `text`, `json`, `html`, `css`,
236
+ `shader`) and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`,
237
+ `animstategraph`, `bundle`, projected as `<name>.<type>.json`) up to the direct-sync size limit are
238
+ eagerly mirrored and kept bidirectional. Adjust the direct-sync limit from **1 MB to 10 MB**
239
+ (default **2 MB**) with the slider in the browser extension popup or `pcbridge workspace settings
240
+ --eager-max-mb <1..10>`. The active Editor scene is mirrored bidirectionally at
241
+ `scenes/<name>.<sceneId>.scene.json` with DFS-ordered entities, while inactive project scenes are
242
+ mirrored as read-only (`0o444`, `$pcbridge.readonly: true`) files for cross-scene inspection
243
+ (`pcbridge scene open` activates a scene before editing it).
244
+
245
+ Structured JSON assets and active scenes use canonical formatting and property-path 3-way merge
246
+ against `.pcbridge/baselines/`: non-overlapping local and Editor edits merge automatically, while
247
+ conflicting edits to the same leaf property preserve `.local`, `.remote`, and `.conflict.json` under
248
+ `tmp/conflicts/`. Images, models, audio, fonts, and files above the direct-sync limit remain lazy:
249
+ metadata, dimensions, and MD5 hashes are recorded in `pcbridge.project.json`, and bytes are fetched
250
+ on demand via `workspace pull` or the Tiny Builder plugin. New local files (including new `*.<type>.json`
251
+ structured assets) create matching remote Assets and folders; renames and moves preserve the Asset
252
+ ID via embedded `$pcbridge.id`, file inode, or content hash. Deleting an eagerly synced Tier 1 file
253
+ locally backs up the file under `tmp/trash/local/` and deletes the remote Asset to keep both sides
254
+ consistent, whereas deleting a pulled lazy binary file only evicts the local cache. The `tmp/` tree
255
+ is agent-owned and excluded from workspace synchronization.
206
256
 
207
257
  PlayCanvas may create source and generated Assets with the same display name, for example a source
208
258
  GLB plus Container/Model outputs or a font plus generated atlas files. The manifest keeps the remote
209
259
  display `folder` separate from the unique local `projectionPath`. The real `file.filename` is used
210
- when possible; only collisions receive `.__pc_<type>_<assetId>` before the extension. Source and
211
- standalone projections are writable. Generated derivatives are lazy and read-only: pulling or
212
- building them stores immutable bytes under `.pcbridge/objects/<assetId>/<md5>/`, and a local edit or
213
- move is quarantined under `tmp/conflicts/` before the projection is restored.
260
+ for derived files while source/standalone names track `asset.name`; only collisions receive
261
+ `.__pc_<type>_<assetId>` before the extension. Source and standalone projections are writable.
262
+ Generated binary derivatives are lazy and read-only (`0o444`), while structured JSON assets
263
+ linked to a source model (such as FBX/GLB-imported materials) remain writable and bidirectional,
264
+ recording `$pcbridge.sourceAssetId` for provenance; local edits or moves on read-only binary
265
+ derivatives are quarantined under `tmp/conflicts/` before restoration.
214
266
 
215
267
  `pcbridge.project.json` schema v3 records `origin` (`source`, `derived`, or `standalone`), advertised
216
268
  and observed remote file metadata, the effective MD5, and local presence/writability/current/base
@@ -222,9 +274,47 @@ schema-v1 and schema-v2 state is migrated automatically; the v1 hidden index is
222
274
  An empty snapshot received while indexed assets exist is ignored, and a non-empty shrinking
223
275
  snapshot must repeat before files are moved to `tmp/trash/remote/`.
224
276
 
225
- ## Template builds and S3 uploads
277
+ ## Plugins
278
+
279
+ Optional features are pcbridge plugins. A pcbridge plugin is not the Chrome extension: the
280
+ extension is a fixed part of pcbridge, while plugins are packages that each user adds, enables,
281
+ disables, and removes. A plugin can contribute two kinds of code:
226
282
 
227
- Selecting a PlayCanvas Template Asset adds a **pcbridge Tiny Builder** section to the Attributes
283
+ | Runtime | Runs in | Typical use |
284
+ | --- | --- | --- |
285
+ | `node` | The local daemon | Files, network, credentials, local applications such as Blender |
286
+ | `page.editor` / `page.launch` | The PlayCanvas Editor or Launch page | Editor UI, Editor API access, runtime inspection |
287
+
288
+ The extension itself is not extensible by plugins; it relays messages between the two sides and
289
+ hosts the management panel. Manage plugins from the extension popup **Plugins** tab or the CLI:
290
+
291
+ ```bash
292
+ pcbridge plugin list # installed plugins, their actions, and available official plugins
293
+ pcbridge plugin add tinyapp-builder # an official plugin shipped with pcbridge
294
+ pcbridge plugin add github:<owner>/<repo>[/<subdir>][#<ref>]
295
+ pcbridge plugin add ./my-plugin [--link] # --link uses the directory in place for development
296
+ pcbridge plugin enable|disable|remove|update <id>
297
+ pcbridge plugin reload <id> # re-read a plugin's files after editing them
298
+ pcbridge plugin call <id> <action> --target editor:<sceneId> --params '<json>'
299
+ ```
300
+
301
+ Plugins are stored under `~/.pcbridge/plugins/`. A plugin with npm dependencies gets them from
302
+ `bun install --production` when it is added or updated. Enabling, disabling, and reloading take
303
+ effect in the daemon and in open Editor and Launch tabs without a page refresh. `plugin update`
304
+ re-fetches the plugin from the source it was added from. Plugins run with full local and page
305
+ access, so add only plugins you trust.
306
+
307
+ To write a plugin, install the agent skills (`pcbridge install-skill --agent all`) and use the
308
+ `pcbridge-plugin-authoring` skill, which defines the manifest (`pcbridge-plugin.json`), both
309
+ runtime APIs, and the rules. `plugins/tinyapp-builder/` in this repository is the reference
310
+ implementation.
311
+
312
+ ## Tiny Builder plugin: Template builds and S3 uploads
313
+
314
+ Tiny Builder is the official `tinyapp-builder` plugin. Add it once with
315
+ `pcbridge plugin add tinyapp-builder` or **Install** in the popup **Plugins** tab.
316
+
317
+ With the plugin enabled, selecting a PlayCanvas Template Asset adds a **pcbridge Tiny Builder** section to the Attributes
228
318
  panel. **Build and upload to S3** collects recursive Asset references, attached scripts, and child
229
319
  Templates in the page. The daemon materializes every dependency under `assets/`: an existing local
230
320
  file is reused when it matches the effective remote MD5, while a missing or remote-updated file is
@@ -259,8 +349,8 @@ and uploads use a fixed `Content-MD5` instead of streaming checksum trailers. Bu
259
349
  started and inspected from the CLI:
260
350
 
261
351
  ```bash
262
- pcbridge builder start --target editor:<sceneId> --asset <templateAssetId> --suffix '-${time}'
263
- pcbridge builder status --job <jobId>
352
+ pcbridge plugin call tinyapp-builder start --target editor:<sceneId> --params '{"templateAssetId":"<templateAssetId>","suffix":"-${time}"}'
353
+ pcbridge plugin call tinyapp-builder status --params '{"jobId":"<jobId>"}'
264
354
  ```
265
355
 
266
356
  Script, JSON, upload, and capture paths are restricted to the selected project workspace by default.
@@ -286,7 +376,9 @@ The CLI exposes layered help so agents can load only the command surface they ne
286
376
  pcbridge help
287
377
  pcbridge help core
288
378
  pcbridge help workspace
289
- pcbridge help builder
379
+ pcbridge help processing
380
+ pcbridge help import
381
+ pcbridge help plugin
290
382
  pcbridge help frontend
291
383
  pcbridge help target
292
384
  pcbridge help entity
@@ -495,9 +587,9 @@ Safeguards:
495
587
  ## Development
496
588
 
497
589
  ```bash
498
- pnpm install
499
- pnpm build
500
- node dist/cli.js doctor
590
+ bun install
591
+ bun run build
592
+ bun dist/cli.js doctor
501
593
  ```
502
594
 
503
595
  Use `bun` for one-off TypeScript scripts if you add them.
@@ -509,7 +601,7 @@ repository does not need an `NPM_TOKEN` secret.
509
601
 
510
602
  1. Update the same stable version in `package.json`, `src/config.ts`, and
511
603
  `extension/manifest.json`.
512
- 2. Run `pnpm test`, commit the release to `main`, and push `main`.
604
+ 2. Run `bun run test`, commit the release to `main`, and push `main`.
513
605
  3. Create and push the matching tag, for example:
514
606
 
515
607
  ```bash
@@ -520,3 +612,28 @@ git push origin v<version>
520
612
  The workflow rejects tags that do not match the package version or whose commit is not on `main`.
521
613
  Configure the npm package's Trusted Publisher with GitHub user `Q-My99`, repository
522
614
  `playcanvas-agent-bridge-cli`, and workflow filename `npm-publish.yml` before pushing the tag.
615
+
616
+ ## Self-hosted sites and local asset processing
617
+
618
+ The extension automatically recognizes official PlayCanvas, `pc-editor.sightp.com`, `pc-launch.sightp.com`, `localhost` and `127.0.0.1` Editor/Launch pages on any port. For another hostname, use **Enable on this site** in the popup, grant Chrome permission, then refresh. Editor and Launch hosts need separate grants. Disabling or revoking a site closes existing connections. Self-hosted pages never inherit the official frontend-switch preference.
619
+
620
+ Local conversion is opt-in and self-hosted only. Install a **trusted** versioned asset-tools manifest and its precompiled archive (macOS arm64 validated; no public release published yet):
621
+
622
+ ```sh
623
+ pcbridge processing install /path/to/release.json
624
+ pcbridge processing enable --memory-mb 1024 --timeout-ms 600000
625
+ pcbridge processing status --target editor:<sceneId>
626
+ pcbridge import submit --asset <id> --kind model --json options.json --target editor:<sceneId>
627
+ pcbridge import list --target editor:<sceneId>
628
+ pcbridge import wait --job <id> --sync-workspace --target editor:<sceneId>
629
+ pcbridge import status --job <id> --target editor:<sceneId>
630
+ pcbridge import cancel --job <id> --target editor:<sceneId>
631
+ pcbridge import retry --job <id> --target editor:<sceneId>
632
+ pcbridge processing disable
633
+ ```
634
+
635
+ For textures use `--kind texture` with options such as `{"formats":["dxt","etc2"],"mipmaps":true}`. Existing asset uploads and Editor UI use the same server jobs. Browser-owned authentication, leases and object-store URLs never reach the CLI. `complete` means server publication; `--sync-workspace` separately waits for metadata synchronization, retaining lazy binary downloads. Missing/disabled/busy tools fall back to the server worker.
636
+
637
+ Processing uses one fixed subprocess, a 1 GiB conversion budget, 256 KiB sequential chunks and project `tmp/processing/` scratch files. A ten-minute conversion timeout and ninety-second abandoned-transfer timeout bound execution. This is not an OS memory sandbox. Tool/recipe/platform checks are independent of bridge connectivity. Server caches remain trusted; client output does not populate the server converter cache. Persistent local result caching is not implemented.
638
+
639
+ After upgrading extension sources, regenerate with `pcbridge install-extension --no-open`, reload the unpacked extension in Chrome, refresh Editor/Launch and restart an older daemon while retaining its workspace path. Official and self-hosted projects must use separate workspaces and explicit targets; project IDs are not namespaced across sites. Fresh self-hosted resource datasets use MD5; no legacy SHA-256 resource migration is provided.
package/README.zh-CN.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
+ 场景管理:`scene list`、`scene create --name <名称>`、`scene open --id <ID>` 使用所选 Editor 的项目;打开操作会等待目标场景加载。`asset upload` 自动将 GLB/FBX/OBJ 识别为模型源资源(`scene`)。
4
+
5
+ 在父级 PlayCanvas 工作区中,`bun run pcbridge <命令>` 默认使用根目录 `pcbridge-workspace/`(自动创建,Git 忽略)。`bun run dev` 会自动启动当前源码的 daemon,退出时一起关闭;若 daemon 端口已被占用,先运行 `bun run pcbridge daemon stop`。插件弹窗显示插件自身版本和 daemon 版本,离线时也能确认插件版本。
6
+
7
+ > 需要 Bun 1.4.0 或更新版本。在父级 monorepo 中,请于根目录执行 `bun install --frozen-lockfile`。
8
+
3
9
  这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景和 PlayCanvas Launch 页面。
4
10
 
5
11
  核心接口是 `pcbridge` 命令、本地 daemon 和 Chrome Manifest V3 插件。MCP 不是核心依赖,之后可以作为薄适配层再加。
@@ -9,17 +15,17 @@
9
15
  从 npm 安装:
10
16
 
11
17
  ```bash
12
- npm install -g playcanvas-agent-bridge-cli
18
+ bun add --global playcanvas-agent-bridge-cli
13
19
  pcbridge install-skill --agent all
14
20
  ```
15
21
 
16
- 下文命令跟随仓库版 `0.6.1`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
22
+ 下文命令跟随仓库版 `0.7.0`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
17
23
  GitHub 安装。
18
24
 
19
25
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
20
26
 
21
27
  ```bash
22
- npm install -g github:Q-My99/playcanvas-agent-bridge-cli
28
+ bun add --global github:Q-My99/playcanvas-agent-bridge-cli
23
29
  pcbridge install-skill --agent all
24
30
  ```
25
31
 
@@ -32,15 +38,37 @@ npx playcanvas-agent-bridge-cli install-skill --agent all
32
38
 
33
39
  ## 更新 pcbridge 各组件
34
40
 
35
- CLI/daemon、已安装的 Agent 技能、生成的 Chrome 插件和可选的本地 Editor 前端是四个独立的
36
- 本地组件,更新其中一个不会自动更新其他组件。
41
+ `pcbridge` 会后台定期检查 npm 上的最新 CLI/浏览器扩展版本,以及 GitHub 仓库(`plugins/index.json`)
42
+ 中独立演进的官方插件版本。检测到可用更新时:
43
+
44
+ - **浏览器插件徽标与弹窗**:Chrome 工具栏图标会显示 `↑` 角标;打开弹窗即可在顶部点击
45
+ **Update & Reload** 一键更新 `pcbridge` 本体,或在 **Plugins** 标签页点击 **Update** /
46
+ **Update all** 一键热更新官方插件。
47
+ - **CLI 与 AI Agent**:命令返回的 JSON 信封会自动挂载结构化 `meta.updates` 字段,交互式终端会在
48
+ `stderr` 打印单行更新提示。
37
49
 
38
- ### 更新 CLI、daemon 和 Agent 技能
50
+ ### 一键更新(CLI、daemon、Agent 技能、Chrome 插件与官方插件)
39
51
 
40
52
  ```bash
41
- npm install -g playcanvas-agent-bridge-cli@latest
53
+ pcbridge update status --refresh # 检查 pcbridge 本体与已安装插件的更新状态
54
+ pcbridge update # 一键升级 CLI、daemon、已安装技能、Chrome 扩展并刷新标签页
55
+ pcbridge update --plugins # 同时一键更新所有有新版本的已安装插件
56
+ pcbridge plugin update <id> # 独立热更新单个插件(无需重启 daemon 或刷新页面)
57
+ pcbridge plugin update --all # 独立热更新全部有新版本的已安装插件
58
+ ```
59
+
60
+ `pcbridge update` 会自动升级全局 npm 包,调用新版二进制重写 `~/.pcbridge/extension` 并刷新已安装的
61
+ Agent 技能,通知 Chrome 扩展执行 `chrome.runtime.reload()` 自动重载并刷新已打开的 PlayCanvas
62
+ Editor / Launch 标签页(可通过 `--no-reload-tabs` 跳过标签页刷新),同时让正在运行的 daemon 在原终端
63
+ 内原地重启并继承原有的 `--workspace` 目录。
64
+
65
+ ### 手动分步更新命令
66
+
67
+ ```bash
68
+ bun add --global playcanvas-agent-bridge-cli@latest
42
69
  pcbridge version
43
70
  pcbridge install-skill --agent all
71
+ pcbridge install-extension --no-open
44
72
  pcbridge daemon restart --workspace /原来的/workspace/根目录
45
73
  ```
46
74
 
@@ -137,6 +165,10 @@ Editor URL。
137
165
  点击 **Use custom frontend** 或 **Use official frontend** 时改变;popup 的 **Project
138
166
  preference** 会显示当前项目的记忆值。
139
167
 
168
+ 已记住的 Custom 偏好会始终应用;即使 daemon 或前端监听不可用,Editor 也会明确加载失败,
169
+ 不会静默回退到官方前端。popup 会区分显示 daemon 离线、前端监听停止或未安装前端版本。
170
+ pcbridge daemon 与前端监听仍由同一个终端命令一起启动;插件不会尝试启动本地进程。
171
+
140
172
  需要时可以显式管理本地版本:
141
173
 
142
174
  ```bash
@@ -176,9 +208,10 @@ pcbridge daemon stop
176
208
  ```text
177
209
  1552681-pcbridge-test/
178
210
  ├── pcbridge.project.json # 项目信息和供 agent 读取的资源目录
211
+ ├── scenes/ # 当前激活场景的可写 .scene.json 与未激活场景的只读镜像
179
212
  ├── assets/ # PlayCanvas 文件树的碰撞安全本地投影
180
- ├── tmp/ # 构建产物、缓存、冲突、截图和远端删除隔离副本
181
- └── .pcbridge/ # 内部同步状态和内容寻址对象缓存,请勿手动修改
213
+ ├── tmp/ # 构建产物、缓存、冲突、截图以及本地/远端删除回收站
214
+ └── .pcbridge/ # 内部同步状态、JSON 三方合并基线和内容寻址对象缓存,请勿手动修改
182
215
  ```
183
216
 
184
217
  查看或手动刷新工作区:
@@ -186,28 +219,36 @@ pcbridge daemon stop
186
219
  ```bash
187
220
  pcbridge workspace status --target editor:<sceneId>
188
221
  pcbridge workspace path --target editor:<sceneId>
222
+ pcbridge workspace settings [--eager-max-mb <1..10>]
189
223
  pcbridge workspace sync --target editor:<sceneId>
190
224
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
191
225
  ```
192
226
 
193
- 脚本默认实时同步到本地;图片、模型、音频、字体等二进制资源默认只同步 Asset 元数据,
194
- 不会在首次建立镜像时下载文件内容。需要本地文件时使用 `workspace pull`,或由 Tiny Builder
195
- 在构建实际依赖时按需拉取。已经存在于 `assets/` 的本地二进制文件会保留并参与双向同步。
196
- 刷新只读取完整 Asset 元数据,并用 PlayCanvas MD5 与本地缓存的 size/mtime/MD5 判断变化。
197
- 本地修改会自动上传,远端修改会按基线判断并下载;同时修改时不会覆盖任一版本,文本和二进制
198
- 冲突副本都写入 `tmp/conflicts/`。
199
-
200
- daemon 会监控项目 `assets/` 目录:本地新增文件会上传到对应目录,由 PlayCanvas 自行判断资源
201
- 类型并完成导入,然后重新读取远端 Asset 列表;本地目录会自动映射为 PlayCanvas Folder。
202
- 本地重命名和移动会保持同一个 Asset ID,并同步远端名称和目录。删除本地文件只视为清理本地
203
- 缓存,不会删除 PlayCanvas 远端 Asset;远端删除仍会隔离到 `tmp/trash/remote/`。`tmp/` 下的
204
- 构建、缓存和 agent 临时文件完全不参与 workspace 同步。
227
+ 同步采用 WebSocket 增量事件流(`workspace:delta`)与本地脏路径精确监控,空闲时零轮询。
228
+ 未超过直接同步体积上限的文本类资源(`script`、`text`、`json`、`html`、`css`、`shader`)和结构化
229
+ JSON 资源(`material`、`template`、`cubemap`、`sprite`、`animstategraph`、`bundle`,投影为
230
+ `<name>.<type>.json`)默认直接落盘并双向实时同步。可在浏览器插件弹窗中使用 **Direct sync limit**
231
+ 滑动条或执行 `pcbridge workspace settings --eager-max-mb <1..10>` 在 **1 MB–10 MB**(默认 **2 MB**)
232
+ 范围内调整直接同步上限。当前打开的激活场景同步到 `scenes/<name>.<sceneId>.scene.json`(按场景树
233
+ DFS 排序,支持双向增量同步);未打开的其他场景落盘为只读(`0o444`,且 `$pcbridge.readonly: true`)`.scene.json` 供跨场景检索,
234
+ 编辑前先通过 `pcbridge scene open` 切换为激活场景。
235
+
236
+ 结构化 JSON 资源与激活场景基于 `.pcbridge/baselines/` 做规范化与属性路径级三方合并:两端修改不同
237
+ 实体或不同属性时自动无冲突合并并结构化 Patch 回写 Editor;仅当同一叶子属性被同时改成不同值时,
238
+ 才将 `.local`、`.remote` 与 `.conflict.json` 隔离到 `tmp/conflicts/`。图片、模型、音频、字体及超过
239
+ 直接同步上限的大文件保持懒同步:在 `pcbridge.project.json` 中记录元数据、尺寸规格与 MD5,按需通过
240
+ `workspace pull` 或 Tiny Builder 插件拉取。本地新增文件(包括新建 `*.<type>.json` 结构化资源)会在对应
241
+ 目录自动创建远端 Asset;本地重命名和移动通过内嵌 `$pcbridge.id`、文件 inode 或内容哈希保持原 Asset ID。
242
+ 删除本地直接同步(Tier 1)文件会先备份到 `tmp/trash/local/` 并同步删除远端 Asset 以避免状态歧义;
243
+ 删除已拉取的懒同步(Tier 2)二进制文件则仅清理本地缓存,远端删除仍隔离到 `tmp/trash/remote/`。
244
+ `tmp/` 下的构建、缓存和 agent 临时文件完全不参与 workspace 同步。
205
245
 
206
246
  PlayCanvas 可能生成同名的源 Asset 和派生 Asset,例如源 GLB 与 Container/Model,或字体源文件
207
247
  与字体图集。manifest 会把网页端显示路径 `folder` 和本地唯一路径 `projectionPath` 分开记录。
208
- 本地优先使用真实的 `file.filename`;只有名称碰撞时,才会在扩展名前加入
209
- `.__pc_<type>_<assetId>`。source 和 standalone 投影可写;derived 投影按需下载且只读,内容会
210
- 缓存到 `.pcbridge/objects/<assetId>/<md5>/`。修改或移动 derived 投影时,本地副本会隔离到
248
+ 派生二进制使用 `file.filename`,源资源和独立资源跟随 `asset.name`;只有名称碰撞时,才会在扩展名前加入
249
+ `.__pc_<type>_<assetId>`。派生二进制按需下载且只读(`0o444`),而关联源模型的结构化 JSON 资源
250
+ (如 FBX/GLB 导入生成的材质)保持可写并参与双向同步,仅在 `$pcbridge.sourceAssetId` 保留来源标记;
251
+ 修改或移动只读派生二进制投影时,本地副本会隔离到
211
252
  `tmp/conflicts/`,随后从对象缓存恢复正确内容,不会反向上传到 PlayCanvas。
212
253
 
213
254
  schema v3 的 `pcbridge.project.json` 会记录 `origin`(`source`、`derived` 或 `standalone`)、
@@ -219,9 +260,45 @@ pcbridge 管理。schema v1
219
260
  收到的空快照会被忽略;
220
261
  非空但缩小的快照必须连续出现两次,文件才会被移动到 `tmp/trash/remote/`。
221
262
 
222
- ## Template 构建与 S3 上传
263
+ ## 插件
264
+
265
+ 可选功能以 pcbridge 插件的形式提供。pcbridge 插件不等于 Chrome 浏览器插件:浏览器插件是
266
+ pcbridge 固定的组成部分,而 pcbridge 插件是每个用户按需添加、开启、关闭和删除的功能包。
267
+ 一个插件可以包含两类代码:
268
+
269
+ | 运行环境 | 运行位置 | 典型用途 |
270
+ | --- | --- | --- |
271
+ | `node` | 本地 daemon | 文件、网络、密钥、连接 Blender 等本地程序 |
272
+ | `page.editor` / `page.launch` | PlayCanvas Editor 或 Launch 页面 | 编辑器 UI、Editor API 读写、运行时检查 |
273
+
274
+ 浏览器插件本身不能被 pcbridge 插件扩展,它只负责在两端之间转发消息并提供管理面板。可以在
275
+ 浏览器插件弹窗的 **Plugins** 标签页或通过 CLI 管理插件:
223
276
 
224
- 选中 PlayCanvas Template Asset 后,Attributes 面板会出现 **pcbridge Tiny Builder**。点击
277
+ ```bash
278
+ pcbridge plugin list # 已安装插件、各自的 action,以及可添加的官方插件
279
+ pcbridge plugin add tinyapp-builder # 随 pcbridge 发布的官方插件
280
+ pcbridge plugin add github:<owner>/<repo>[/<subdir>][#<ref>]
281
+ pcbridge plugin add ./my-plugin [--link] # --link 直接使用该目录,便于开发调试
282
+ pcbridge plugin enable|disable|remove|update <id>
283
+ pcbridge plugin reload <id> # 修改插件文件后重新加载
284
+ pcbridge plugin call <id> <action> --target editor:<sceneId> --params '<json>'
285
+ ```
286
+
287
+ 插件保存在 `~/.pcbridge/plugins/`。带 npm 依赖的插件会在添加或更新时通过
288
+ `bun install --production` 安装依赖。开启、关闭和重新加载会立即作用于 daemon 以及已打开的
289
+ Editor / Launch 页面,无需刷新页面。`plugin update` 会从添加时记录的来源重新拉取。插件拥有
290
+ 完整的本地和页面权限,请只添加可信来源的插件。
291
+
292
+ 开发插件时,先安装 Agent 技能(`pcbridge install-skill --agent all`),再使用
293
+ `pcbridge-plugin-authoring` 技能;它定义了清单文件(`pcbridge-plugin.json`)、两端运行时 API
294
+ 和编写规则。本仓库的 `plugins/tinyapp-builder/` 是参考实现。
295
+
296
+ ## Tiny Builder 插件:Template 构建与 S3 上传
297
+
298
+ Tiny Builder 是官方插件 `tinyapp-builder`,执行一次 `pcbridge plugin add tinyapp-builder`
299
+ 或在弹窗 **Plugins** 标签页点击 **Install** 即可添加。
300
+
301
+ 插件开启后,选中 PlayCanvas Template Asset,Attributes 面板会出现 **pcbridge Tiny Builder**。点击
225
302
  **构建并上传到 S3** 后,网页只负责收集 Template、递归 Asset 引用、挂载脚本和子 Template;
226
303
  daemon 会把全部依赖物化到 `assets/`:本地文件与有效远端 MD5 一致时直接复用,不存在或远端
227
304
  已更新时先从 PlayCanvas 同步。贴图 variant 和字体附加图集会作为主 Asset 同目录下的只读
@@ -253,8 +330,8 @@ R2 等兼容服务;自定义服务是否需要 path-style URL 由
253
330
  发起和查看任务:
254
331
 
255
332
  ```bash
256
- pcbridge builder start --target editor:<sceneId> --asset <templateAssetId> --suffix '-${time}'
257
- pcbridge builder status --job <jobId>
333
+ pcbridge plugin call tinyapp-builder start --target editor:<sceneId> --params '{"templateAssetId":"<templateAssetId>","suffix":"-${time}"}'
334
+ pcbridge plugin call tinyapp-builder status --params '{"jobId":"<jobId>"}'
258
335
  ```
259
336
 
260
337
  CLI 的脚本、JSON、上传文件和截图路径默认必须位于对应项目工作区内。只有明确需要使用
@@ -280,7 +357,9 @@ CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
280
357
  pcbridge help
281
358
  pcbridge help core
282
359
  pcbridge help workspace
283
- pcbridge help builder
360
+ pcbridge help processing
361
+ pcbridge help import
362
+ pcbridge help plugin
284
363
  pcbridge help frontend
285
364
  pcbridge help target
286
365
  pcbridge help entity
@@ -482,9 +561,9 @@ pcbridge install-skill --agent cursor --path ./.cursor/rules
482
561
  ## 开发
483
562
 
484
563
  ```bash
485
- pnpm install
486
- pnpm build
487
- node dist/cli.js doctor
564
+ bun install
565
+ bun run build
566
+ bun dist/cli.js doctor
488
567
  ```
489
568
 
490
569
  如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
@@ -495,7 +574,7 @@ node dist/cli.js doctor
495
574
  仓库不需要保存 `NPM_TOKEN`。
496
575
 
497
576
  1. 在 `package.json`、`src/config.ts` 和 `extension/manifest.json` 中同步更新同一个稳定版本号。
498
- 2. 运行 `pnpm test`,把发布提交合并并推送到 `main`。
577
+ 2. 运行 `bun run test`,把发布提交合并并推送到 `main`。
499
578
  3. 创建并推送匹配的 tag,例如:
500
579
 
501
580
  ```bash
@@ -506,3 +585,28 @@ git push origin v<version>
506
585
  如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。
507
586
  推送 tag 前,需要在 npm 包设置中把 GitHub 用户设为 `Q-My99`、仓库设为
508
587
  `playcanvas-agent-bridge-cli`、workflow 文件名设为 `npm-publish.yml`。
588
+
589
+ ## 自托管站点与本地资源处理
590
+
591
+ 插件自动识别官方站点、`pc-editor.sightp.com`、`pc-launch.sightp.com` 及任意端口的 localhost / 127.0.0.1 Editor、Launch 页面。其他域名在 popup 点击 **Enable on this site**,经 Chrome 授权后刷新;Editor 与 Launch 域名分别授权。禁用或撤回权限会关闭现有连接。自托管页面不套用官方 frontend 切换偏好。
592
+
593
+ 本地计算仅限自托管,默认关闭。安装可信发布者提供的版本化工具 manifest 和预编译包(当前实测 macOS arm64,尚未发布公开工具 release):
594
+
595
+ ```sh
596
+ pcbridge processing install /path/to/release.json
597
+ pcbridge processing enable --memory-mb 1024 --timeout-ms 600000
598
+ pcbridge processing status --target editor:<sceneId>
599
+ pcbridge import submit --asset <id> --kind model --json options.json --target editor:<sceneId>
600
+ pcbridge import list --target editor:<sceneId>
601
+ pcbridge import wait --job <id> --sync-workspace --target editor:<sceneId>
602
+ pcbridge import status --job <id> --target editor:<sceneId>
603
+ pcbridge import cancel --job <id> --target editor:<sceneId>
604
+ pcbridge import retry --job <id> --target editor:<sceneId>
605
+ pcbridge processing disable
606
+ ```
607
+
608
+ 贴图改用 `--kind texture`,options 如 `{"formats":["dxt","etc2"],"mipmaps":true}`。已有上传命令和 Editor UI 使用同一种服务器任务。身份、租约和对象存储 URL 仅由浏览器持有,不传给 CLI。`complete` 表示服务器正式发布;`--sync-workspace` 额外等待工作区元数据同步,二进制继续按需下载。工具缺失、关闭或繁忙时回退服务器 worker。
609
+
610
+ 固定转换子进程单并发,转换预算 1 GiB,顺序分块 256 KiB,临时文件在项目 `tmp/processing/`。转换超时 10 分钟,失联传输 90 秒回收;这不是 OS 级硬内存沙箱。工具/配方/平台兼容性独立于桥接连接报告。可复用可信服务端缓存,但客户端结果不写入服务端转换缓存;首版不提供本地持久结果缓存。
611
+
612
+ 更新后执行 `pcbridge install-extension --no-open`,在 Chrome 重新加载 unpacked 扩展,再刷新 Editor/Launch;旧 daemon 需使用原工作区路径重启。官方与自托管需分开工作区并明确选择目标,不提供跨站点 projectId 命名空间。自托管新数据集使用资源 MD5,不提供旧 SHA-256 资源迁移。