playcanvas-agent-bridge-cli 0.6.0 → 0.6.2

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,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.0`. npm installs the latest stable
29
+ The commands documented below track repository version `0.6.2`. 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:
@@ -37,22 +43,22 @@ frontend are separate local components. Updating one does not update the others
37
43
 
38
44
  ### Update the CLI, daemon, and agent skills
39
45
 
40
- First stop the running daemon with **Ctrl+C in the terminal where it was started**. There is no
41
- `pcbridge daemon stop` command. Remember that terminal's working directory because it is the
42
- workspace root and must be reused when the daemon starts again.
43
-
44
46
  ```bash
45
- npm install -g playcanvas-agent-bridge-cli@latest
47
+ bun add --global playcanvas-agent-bridge-cli@latest
46
48
  pcbridge version
47
49
  pcbridge install-skill --agent all
48
- cd /the/same/workspace/root
49
- pcbridge daemon start
50
+ pcbridge daemon restart --workspace /the/workspace/root
50
51
  ```
51
52
 
52
53
  Installing the npm package replaces the CLI files, but an already-running daemon remains the old
53
- in-memory version until it is restarted. Installed Codex, Claude, Cursor, and Windsurf skills are
54
- also copies, so rerun `install-skill`; start a new agent task/session if the client has already
55
- loaded the old skill.
54
+ in-memory version until it is restarted. `daemon restart` authenticates the existing pcbridge
55
+ listener, shuts it down gracefully, waits for the port to be released, and starts the new daemon in
56
+ the current terminal. It never kills an unverified process merely because that process occupies the
57
+ configured port. When upgrading from a version that predates authenticated shutdown, stop that old
58
+ daemon once with **Ctrl+C**, then use `daemon restart` for later switches and upgrades.
59
+
60
+ Installed Codex, Claude, Cursor, and Windsurf skills are also copies, so rerun `install-skill`;
61
+ start a new agent task/session if the client has already loaded the old skill.
56
62
 
57
63
  ### Update the Chrome extension
58
64
 
@@ -140,6 +146,12 @@ add or remove `use_local_frontend` while preserving other query parameters and t
140
146
  preference changes only when the user clicks **Use custom frontend** or **Use official frontend**
141
147
  again, and the popup shows the remembered value under **Project preference**.
142
148
 
149
+ A remembered custom preference is applied even when the daemon or frontend listener is unavailable,
150
+ so the Editor fails visibly instead of silently falling back to the official frontend. The popup
151
+ reports whether the daemon is offline, the frontend server is stopped, or no release is installed.
152
+ The pcbridge daemon and its frontend listener are started together from the terminal; the extension
153
+ does not attempt to start local processes.
154
+
143
155
  Manage installed releases explicitly when needed:
144
156
 
145
157
  ```bash
@@ -154,21 +166,36 @@ until another installed release is selected.
154
166
 
155
167
  ## Start the bridge
156
168
 
157
- Change into the directory that should become the local workspace root before starting the daemon:
169
+ Use the current directory as the workspace root, or pass it explicitly:
158
170
 
159
171
  ```bash
160
172
  cd /path/to/my-playcanvas-workspace
161
173
  pcbridge daemon start
174
+
175
+ # Equivalent from any directory
176
+ pcbridge daemon start --workspace /path/to/my-playcanvas-workspace
177
+
178
+ # Stop the current daemon and switch workspace roots
179
+ pcbridge daemon restart --workspace /path/to/another-workspace
180
+
181
+ # Gracefully stop the authenticated pcbridge daemon
182
+ pcbridge daemon stop
162
183
  ```
163
184
 
185
+ `daemon restart` and `daemon stop` first verify the token-protected `/health` response. A token
186
+ mismatch or a non-pcbridge listener fails without terminating the process on that port. Both
187
+ `start` and `restart` run the daemon in the foreground so logs remain visible and **Ctrl+C** still
188
+ works.
189
+
164
190
  When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` automatically:
165
191
 
166
192
  ```text
167
193
  1552681-pcbridge-test/
168
194
  ├── pcbridge.project.json # project metadata plus the agent-readable asset catalog
195
+ ├── scenes/ # active writable .scene.json plus read-only mirrors of inactive scenes
169
196
  ├── assets/ # collision-safe projection of the PlayCanvas folder tree
170
- ├── tmp/ # builds, cache, conflicts, captures, and quarantined remote deletions
171
- └── .pcbridge/ # internal sync state and content-addressed object cache; do not edit
197
+ ├── tmp/ # builds, cache, conflicts, captures, and local/remote deletion trash
198
+ └── .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
172
199
  ```
173
200
 
174
201
  Inspect or refresh the workspace with:
@@ -176,27 +203,43 @@ Inspect or refresh the workspace with:
176
203
  ```bash
177
204
  pcbridge workspace status --target editor:<sceneId>
178
205
  pcbridge workspace path --target editor:<sceneId>
206
+ pcbridge workspace settings [--eager-max-mb <1..10>]
179
207
  pcbridge workspace sync --target editor:<sceneId>
180
208
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
181
209
  ```
182
210
 
183
- Scripts are eagerly mirrored and kept close to real time. Images, models, audio, fonts, and other
184
- binary assets are lazy: refresh records the Asset metadata and PlayCanvas MD5 without downloading
185
- file contents. Use `workspace pull`, or let Tiny Builder fetch the dependencies needed for a build.
186
- Existing binary files under `assets/` are retained and remain bidirectional. Local edits upload,
187
- remote edits download according to the sync baseline, and concurrent edits preserve both copies under
188
- `tmp/conflicts/`. New local files are uploaded into their matching folder and PlayCanvas decides the
189
- imported type; local folders are created remotely. Renames and moves preserve the Asset ID. Deleting
190
- a local file only clears the local cache and never deletes the remote Asset. The `tmp/` tree is
191
- agent-owned and excluded from workspace synchronization.
211
+ Synchronization is event-driven over WebSocket deltas (`workspace:delta`) and targeted local
212
+ `fs.watch` dirty paths without idle polling. Text assets (`script`, `text`, `json`, `html`, `css`,
213
+ `shader`) and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`,
214
+ `animstategraph`, `bundle`, projected as `<name>.<type>.json`) up to the direct-sync size limit are
215
+ eagerly mirrored and kept bidirectional. Adjust the direct-sync limit from **1 MB to 10 MB**
216
+ (default **2 MB**) with the slider in the browser extension popup or `pcbridge workspace settings
217
+ --eager-max-mb <1..10>`. The active Editor scene is mirrored bidirectionally at
218
+ `scenes/<name>.<sceneId>.scene.json` with DFS-ordered entities, while inactive project scenes are
219
+ mirrored as read-only (`0o444`, `$pcbridge.readonly: true`) files for cross-scene inspection
220
+ (`pcbridge scene open` activates a scene before editing it).
221
+
222
+ Structured JSON assets and active scenes use canonical formatting and property-path 3-way merge
223
+ against `.pcbridge/baselines/`: non-overlapping local and Editor edits merge automatically, while
224
+ conflicting edits to the same leaf property preserve `.local`, `.remote`, and `.conflict.json` under
225
+ `tmp/conflicts/`. Images, models, audio, fonts, and files above the direct-sync limit remain lazy:
226
+ metadata, dimensions, and MD5 hashes are recorded in `pcbridge.project.json`, and bytes are fetched
227
+ on demand via `workspace pull` or Tiny Builder. New local files (including new `*.<type>.json`
228
+ structured assets) create matching remote Assets and folders; renames and moves preserve the Asset
229
+ ID via embedded `$pcbridge.id`, file inode, or content hash. Deleting an eagerly synced Tier 1 file
230
+ locally backs up the file under `tmp/trash/local/` and deletes the remote Asset to keep both sides
231
+ consistent, whereas deleting a pulled lazy binary file only evicts the local cache. The `tmp/` tree
232
+ is agent-owned and excluded from workspace synchronization.
192
233
 
193
234
  PlayCanvas may create source and generated Assets with the same display name, for example a source
194
235
  GLB plus Container/Model outputs or a font plus generated atlas files. The manifest keeps the remote
195
236
  display `folder` separate from the unique local `projectionPath`. The real `file.filename` is used
196
- when possible; only collisions receive `.__pc_<type>_<assetId>` before the extension. Source and
197
- standalone projections are writable. Generated derivatives are lazy and read-only: pulling or
198
- building them stores immutable bytes under `.pcbridge/objects/<assetId>/<md5>/`, and a local edit or
199
- move is quarantined under `tmp/conflicts/` before the projection is restored.
237
+ for derived files while source/standalone names track `asset.name`; only collisions receive
238
+ `.__pc_<type>_<assetId>` before the extension. Source and standalone projections are writable.
239
+ Generated binary derivatives are lazy and read-only (`0o444`), while structured JSON assets
240
+ linked to a source model (such as FBX/GLB-imported materials) remain writable and bidirectional,
241
+ recording `$pcbridge.sourceAssetId` for provenance; local edits or moves on read-only binary
242
+ derivatives are quarantined under `tmp/conflicts/` before restoration.
200
243
 
201
244
  `pcbridge.project.json` schema v3 records `origin` (`source`, `derived`, or `standalone`), advertised
202
245
  and observed remote file metadata, the effective MD5, and local presence/writability/current/base
@@ -272,6 +315,8 @@ The CLI exposes layered help so agents can load only the command surface they ne
272
315
  pcbridge help
273
316
  pcbridge help core
274
317
  pcbridge help workspace
318
+ pcbridge help processing
319
+ pcbridge help import
275
320
  pcbridge help builder
276
321
  pcbridge help frontend
277
322
  pcbridge help target
@@ -439,6 +484,20 @@ pcbridge install-skill --agent windsurf
439
484
  pcbridge install-skill --agent all
440
485
  ```
441
486
 
487
+ Use `--path` to install one agent's skill or rule under a custom parent directory. Relative paths
488
+ are resolved from the current working directory, and pcbridge appends the standard directory or
489
+ filename so the parent itself is never cleared:
490
+
491
+ ```bash
492
+ pcbridge install-skill --agent codex --path "D:\AgentConfig\skills"
493
+ pcbridge install-skill --agent cursor --path ./.cursor/rules
494
+ ```
495
+
496
+ These create `D:\AgentConfig\skills\playcanvas-agent-bridge-cli\` and
497
+ `.cursor/rules/playcanvas-agent-bridge-cli.mdc`. Quote Windows paths that contain spaces.
498
+ `--agent all --path ...` is rejected because the supported agents use different artifact layouts;
499
+ run one command per agent for custom locations.
500
+
442
501
  Installed locations:
443
502
 
444
503
  - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
@@ -467,9 +526,9 @@ Safeguards:
467
526
  ## Development
468
527
 
469
528
  ```bash
470
- pnpm install
471
- pnpm build
472
- node dist/cli.js doctor
529
+ bun install
530
+ bun run build
531
+ bun dist/cli.js doctor
473
532
  ```
474
533
 
475
534
  Use `bun` for one-off TypeScript scripts if you add them.
@@ -481,7 +540,7 @@ repository does not need an `NPM_TOKEN` secret.
481
540
 
482
541
  1. Update the same stable version in `package.json`, `src/config.ts`, and
483
542
  `extension/manifest.json`.
484
- 2. Run `pnpm test`, commit the release to `main`, and push `main`.
543
+ 2. Run `bun run test`, commit the release to `main`, and push `main`.
485
544
  3. Create and push the matching tag, for example:
486
545
 
487
546
  ```bash
@@ -492,3 +551,28 @@ git push origin v<version>
492
551
  The workflow rejects tags that do not match the package version or whose commit is not on `main`.
493
552
  Configure the npm package's Trusted Publisher with GitHub user `Q-My99`, repository
494
553
  `playcanvas-agent-bridge-cli`, and workflow filename `npm-publish.yml` before pushing the tag.
554
+
555
+ ## Self-hosted sites and local asset processing
556
+
557
+ 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.
558
+
559
+ 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):
560
+
561
+ ```sh
562
+ pcbridge processing install /path/to/release.json
563
+ pcbridge processing enable --memory-mb 1024 --timeout-ms 600000
564
+ pcbridge processing status --target editor:<sceneId>
565
+ pcbridge import submit --asset <id> --kind model --json options.json --target editor:<sceneId>
566
+ pcbridge import list --target editor:<sceneId>
567
+ pcbridge import wait --job <id> --sync-workspace --target editor:<sceneId>
568
+ pcbridge import status --job <id> --target editor:<sceneId>
569
+ pcbridge import cancel --job <id> --target editor:<sceneId>
570
+ pcbridge import retry --job <id> --target editor:<sceneId>
571
+ pcbridge processing disable
572
+ ```
573
+
574
+ 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.
575
+
576
+ 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.
577
+
578
+ 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.0`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
22
+ 下文命令跟随仓库版 `0.6.2`。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
 
@@ -37,18 +43,18 @@ CLI/daemon、已安装的 Agent 技能、生成的 Chrome 插件和可选的本
37
43
 
38
44
  ### 更新 CLI、daemon 和 Agent 技能
39
45
 
40
- 先在启动 daemon 的终端中按 **Ctrl+C 手动停止 daemon**。目前没有 `pcbridge daemon stop`
41
- 命令。请记住该终端的工作目录,它就是 workspace 根目录,升级后必须回到同一目录启动。
42
-
43
46
  ```bash
44
- npm install -g playcanvas-agent-bridge-cli@latest
47
+ bun add --global playcanvas-agent-bridge-cli@latest
45
48
  pcbridge version
46
49
  pcbridge install-skill --agent all
47
- cd /原来的/workspace/根目录
48
- pcbridge daemon start
50
+ pcbridge daemon restart --workspace /原来的/workspace/根目录
49
51
  ```
50
52
 
51
53
  npm 全局安装会替换 CLI 文件,但已经运行的 daemon 仍然是内存中的旧版本,必须重启才会生效。
54
+ `daemon restart` 会先认证当前 pcbridge 服务,优雅关闭并等待端口释放,再在当前终端启动新
55
+ daemon。它不会因为某个进程占用了配置端口就直接杀掉该进程。从不支持认证关闭的旧版本升级
56
+ 时,第一次仍需在旧 daemon 终端按 **Ctrl+C**;完成这次迁移后即可使用 restart 切换和升级。
57
+
52
58
  Codex、Claude、Cursor 和 Windsurf 的技能文件也是安装时复制出去的,因此需要重新执行
53
59
  `install-skill`;如果当前 Agent 任务已经加载了旧技能,请新建一个任务或会话再使用新技能。
54
60
 
@@ -137,6 +143,10 @@ Editor URL。
137
143
  点击 **Use custom frontend** 或 **Use official frontend** 时改变;popup 的 **Project
138
144
  preference** 会显示当前项目的记忆值。
139
145
 
146
+ 已记住的 Custom 偏好会始终应用;即使 daemon 或前端监听不可用,Editor 也会明确加载失败,
147
+ 不会静默回退到官方前端。popup 会区分显示 daemon 离线、前端监听停止或未安装前端版本。
148
+ pcbridge daemon 与前端监听仍由同一个终端命令一起启动;插件不会尝试启动本地进程。
149
+
140
150
  需要时可以显式管理本地版本:
141
151
 
142
152
  ```bash
@@ -151,21 +161,35 @@ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
151
161
 
152
162
  ## 启动桥接
153
163
 
154
- 请先进入希望作为本地工作区根目录的位置,再启动 daemon:
164
+ 可以使用当前目录作为 workspace 根目录,也可以显式指定目录:
155
165
 
156
166
  ```bash
157
167
  cd /path/to/my-playcanvas-workspace
158
168
  pcbridge daemon start
169
+
170
+ # 在任意目录执行,效果相同
171
+ pcbridge daemon start --workspace /path/to/my-playcanvas-workspace
172
+
173
+ # 停止当前 daemon 并切换 workspace
174
+ pcbridge daemon restart --workspace /path/to/another-workspace
175
+
176
+ # 优雅停止经过认证的 pcbridge daemon
177
+ pcbridge daemon stop
159
178
  ```
160
179
 
180
+ `daemon restart` 和 `daemon stop` 都会先校验带 token 的 `/health` 响应。token 不匹配或端口上
181
+ 不是 pcbridge 服务时,命令会报错且不会终止占用端口的进程。`start` 和 `restart` 都以前台
182
+ 方式运行,日志仍然直接显示在终端中,也仍然可以使用 **Ctrl+C** 停止。
183
+
161
184
  连接 ready 的 Editor 后,pcbridge 会自动创建 `<projectId>-<projectName>/` 工程目录:
162
185
 
163
186
  ```text
164
187
  1552681-pcbridge-test/
165
188
  ├── pcbridge.project.json # 项目信息和供 agent 读取的资源目录
189
+ ├── scenes/ # 当前激活场景的可写 .scene.json 与未激活场景的只读镜像
166
190
  ├── assets/ # PlayCanvas 文件树的碰撞安全本地投影
167
- ├── tmp/ # 构建产物、缓存、冲突、截图和远端删除隔离副本
168
- └── .pcbridge/ # 内部同步状态和内容寻址对象缓存,请勿手动修改
191
+ ├── tmp/ # 构建产物、缓存、冲突、截图以及本地/远端删除回收站
192
+ └── .pcbridge/ # 内部同步状态、JSON 三方合并基线和内容寻址对象缓存,请勿手动修改
169
193
  ```
170
194
 
171
195
  查看或手动刷新工作区:
@@ -173,28 +197,36 @@ pcbridge daemon start
173
197
  ```bash
174
198
  pcbridge workspace status --target editor:<sceneId>
175
199
  pcbridge workspace path --target editor:<sceneId>
200
+ pcbridge workspace settings [--eager-max-mb <1..10>]
176
201
  pcbridge workspace sync --target editor:<sceneId>
177
202
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
178
203
  ```
179
204
 
180
- 脚本默认实时同步到本地;图片、模型、音频、字体等二进制资源默认只同步 Asset 元数据,
181
- 不会在首次建立镜像时下载文件内容。需要本地文件时使用 `workspace pull`,或由 Tiny Builder
182
- 在构建实际依赖时按需拉取。已经存在于 `assets/` 的本地二进制文件会保留并参与双向同步。
183
- 刷新只读取完整 Asset 元数据,并用 PlayCanvas MD5 与本地缓存的 size/mtime/MD5 判断变化。
184
- 本地修改会自动上传,远端修改会按基线判断并下载;同时修改时不会覆盖任一版本,文本和二进制
185
- 冲突副本都写入 `tmp/conflicts/`。
186
-
187
- daemon 会监控项目 `assets/` 目录:本地新增文件会上传到对应目录,由 PlayCanvas 自行判断资源
188
- 类型并完成导入,然后重新读取远端 Asset 列表;本地目录会自动映射为 PlayCanvas Folder。
189
- 本地重命名和移动会保持同一个 Asset ID,并同步远端名称和目录。删除本地文件只视为清理本地
190
- 缓存,不会删除 PlayCanvas 远端 Asset;远端删除仍会隔离到 `tmp/trash/remote/`。`tmp/` 下的
191
- 构建、缓存和 agent 临时文件完全不参与 workspace 同步。
205
+ 同步采用 WebSocket 增量事件流(`workspace:delta`)与本地脏路径精确监控,空闲时零轮询。
206
+ 未超过直接同步体积上限的文本类资源(`script`、`text`、`json`、`html`、`css`、`shader`)和结构化
207
+ JSON 资源(`material`、`template`、`cubemap`、`sprite`、`animstategraph`、`bundle`,投影为
208
+ `<name>.<type>.json`)默认直接落盘并双向实时同步。可在浏览器插件弹窗中使用 **Direct sync limit**
209
+ 滑动条或执行 `pcbridge workspace settings --eager-max-mb <1..10>` 在 **1 MB–10 MB**(默认 **2 MB**)
210
+ 范围内调整直接同步上限。当前打开的激活场景同步到 `scenes/<name>.<sceneId>.scene.json`(按场景树
211
+ DFS 排序,支持双向增量同步);未打开的其他场景落盘为只读(`0o444`,且 `$pcbridge.readonly: true`)`.scene.json` 供跨场景检索,
212
+ 编辑前先通过 `pcbridge scene open` 切换为激活场景。
213
+
214
+ 结构化 JSON 资源与激活场景基于 `.pcbridge/baselines/` 做规范化与属性路径级三方合并:两端修改不同
215
+ 实体或不同属性时自动无冲突合并并结构化 Patch 回写 Editor;仅当同一叶子属性被同时改成不同值时,
216
+ 才将 `.local`、`.remote` 与 `.conflict.json` 隔离到 `tmp/conflicts/`。图片、模型、音频、字体及超过
217
+ 直接同步上限的大文件保持懒同步:在 `pcbridge.project.json` 中记录元数据、尺寸规格与 MD5,按需通过
218
+ `workspace pull` 或 Tiny Builder 拉取。本地新增文件(包括新建 `*.<type>.json` 结构化资源)会在对应
219
+ 目录自动创建远端 Asset;本地重命名和移动通过内嵌 `$pcbridge.id`、文件 inode 或内容哈希保持原 Asset ID。
220
+ 删除本地直接同步(Tier 1)文件会先备份到 `tmp/trash/local/` 并同步删除远端 Asset 以避免状态歧义;
221
+ 删除已拉取的懒同步(Tier 2)二进制文件则仅清理本地缓存,远端删除仍隔离到 `tmp/trash/remote/`。
222
+ `tmp/` 下的构建、缓存和 agent 临时文件完全不参与 workspace 同步。
192
223
 
193
224
  PlayCanvas 可能生成同名的源 Asset 和派生 Asset,例如源 GLB 与 Container/Model,或字体源文件
194
225
  与字体图集。manifest 会把网页端显示路径 `folder` 和本地唯一路径 `projectionPath` 分开记录。
195
- 本地优先使用真实的 `file.filename`;只有名称碰撞时,才会在扩展名前加入
196
- `.__pc_<type>_<assetId>`。source 和 standalone 投影可写;derived 投影按需下载且只读,内容会
197
- 缓存到 `.pcbridge/objects/<assetId>/<md5>/`。修改或移动 derived 投影时,本地副本会隔离到
226
+ 派生二进制使用 `file.filename`,源资源和独立资源跟随 `asset.name`;只有名称碰撞时,才会在扩展名前加入
227
+ `.__pc_<type>_<assetId>`。派生二进制按需下载且只读(`0o444`),而关联源模型的结构化 JSON 资源
228
+ (如 FBX/GLB 导入生成的材质)保持可写并参与双向同步,仅在 `$pcbridge.sourceAssetId` 保留来源标记;
229
+ 修改或移动只读派生二进制投影时,本地副本会隔离到
198
230
  `tmp/conflicts/`,随后从对象缓存恢复正确内容,不会反向上传到 PlayCanvas。
199
231
 
200
232
  schema v3 的 `pcbridge.project.json` 会记录 `origin`(`source`、`derived` 或 `standalone`)、
@@ -267,6 +299,8 @@ CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
267
299
  pcbridge help
268
300
  pcbridge help core
269
301
  pcbridge help workspace
302
+ pcbridge help processing
303
+ pcbridge help import
270
304
  pcbridge help builder
271
305
  pcbridge help frontend
272
306
  pcbridge help target
@@ -430,6 +464,18 @@ pcbridge install-skill --agent windsurf
430
464
  pcbridge install-skill --agent all
431
465
  ```
432
466
 
467
+ 使用 `--path` 可以把单个 Agent 的 skill 或 rule 安装到自定义父目录。相对路径从当前工作目录
468
+ 解析;pcbridge 会自动追加标准目录名或文件名,因此不会清空用户传入的父目录:
469
+
470
+ ```bash
471
+ pcbridge install-skill --agent codex --path "D:\AgentConfig\skills"
472
+ pcbridge install-skill --agent cursor --path ./.cursor/rules
473
+ ```
474
+
475
+ 以上命令分别生成 `D:\AgentConfig\skills\playcanvas-agent-bridge-cli\` 和
476
+ `.cursor/rules/playcanvas-agent-bridge-cli.mdc`。Windows 路径包含空格时必须使用引号。
477
+ 由于不同 Agent 的产物布局不同,`--agent all --path ...` 会被拒绝;自定义位置时请逐个安装。
478
+
433
479
  安装位置:
434
480
 
435
481
  - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
@@ -457,9 +503,9 @@ pcbridge install-skill --agent all
457
503
  ## 开发
458
504
 
459
505
  ```bash
460
- pnpm install
461
- pnpm build
462
- node dist/cli.js doctor
506
+ bun install
507
+ bun run build
508
+ bun dist/cli.js doctor
463
509
  ```
464
510
 
465
511
  如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
@@ -470,7 +516,7 @@ node dist/cli.js doctor
470
516
  仓库不需要保存 `NPM_TOKEN`。
471
517
 
472
518
  1. 在 `package.json`、`src/config.ts` 和 `extension/manifest.json` 中同步更新同一个稳定版本号。
473
- 2. 运行 `pnpm test`,把发布提交合并并推送到 `main`。
519
+ 2. 运行 `bun run test`,把发布提交合并并推送到 `main`。
474
520
  3. 创建并推送匹配的 tag,例如:
475
521
 
476
522
  ```bash
@@ -481,3 +527,28 @@ git push origin v<version>
481
527
  如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。
482
528
  推送 tag 前,需要在 npm 包设置中把 GitHub 用户设为 `Q-My99`、仓库设为
483
529
  `playcanvas-agent-bridge-cli`、workflow 文件名设为 `npm-publish.yml`。
530
+
531
+ ## 自托管站点与本地资源处理
532
+
533
+ 插件自动识别官方站点、`pc-editor.sightp.com`、`pc-launch.sightp.com` 及任意端口的 localhost / 127.0.0.1 Editor、Launch 页面。其他域名在 popup 点击 **Enable on this site**,经 Chrome 授权后刷新;Editor 与 Launch 域名分别授权。禁用或撤回权限会关闭现有连接。自托管页面不套用官方 frontend 切换偏好。
534
+
535
+ 本地计算仅限自托管,默认关闭。安装可信发布者提供的版本化工具 manifest 和预编译包(当前实测 macOS arm64,尚未发布公开工具 release):
536
+
537
+ ```sh
538
+ pcbridge processing install /path/to/release.json
539
+ pcbridge processing enable --memory-mb 1024 --timeout-ms 600000
540
+ pcbridge processing status --target editor:<sceneId>
541
+ pcbridge import submit --asset <id> --kind model --json options.json --target editor:<sceneId>
542
+ pcbridge import list --target editor:<sceneId>
543
+ pcbridge import wait --job <id> --sync-workspace --target editor:<sceneId>
544
+ pcbridge import status --job <id> --target editor:<sceneId>
545
+ pcbridge import cancel --job <id> --target editor:<sceneId>
546
+ pcbridge import retry --job <id> --target editor:<sceneId>
547
+ pcbridge processing disable
548
+ ```
549
+
550
+ 贴图改用 `--kind texture`,options 如 `{"formats":["dxt","etc2"],"mipmaps":true}`。已有上传命令和 Editor UI 使用同一种服务器任务。身份、租约和对象存储 URL 仅由浏览器持有,不传给 CLI。`complete` 表示服务器正式发布;`--sync-workspace` 额外等待工作区元数据同步,二进制继续按需下载。工具缺失、关闭或繁忙时回退服务器 worker。
551
+
552
+ 固定转换子进程单并发,转换预算 1 GiB,顺序分块 256 KiB,临时文件在项目 `tmp/processing/`。转换超时 10 分钟,失联传输 90 秒回收;这不是 OS 级硬内存沙箱。工具/配方/平台兼容性独立于桥接连接报告。可复用可信服务端缓存,但客户端结果不写入服务端转换缓存;首版不提供本地持久结果缓存。
553
+
554
+ 更新后执行 `pcbridge install-extension --no-open`,在 Chrome 重新加载 unpacked 扩展,再刷新 Editor/Launch;旧 daemon 需使用原工作区路径重启。官方与自托管需分开工作区并明确选择目标,不提供跨站点 projectId 命名空间。自托管新数据集使用资源 MD5,不提供旧 SHA-256 资源迁移。
@@ -244,12 +244,17 @@ export class BuilderManager {
244
244
  #requestTarget;
245
245
  #workspace;
246
246
  #jobs = new Map();
247
+ #activeRuns = new Set();
248
+ #activeClients = new Set();
249
+ #closing = false;
247
250
  constructor(options) {
248
251
  this.rootDir = options.rootDir;
249
252
  this.#requestTarget = options.requestTarget;
250
253
  this.#workspace = options.workspace;
251
254
  }
252
255
  start(info, templateAssetId, options = {}) {
256
+ if (this.#closing)
257
+ throw new Error("Tiny Builder is stopping with the daemon.");
253
258
  const now = new Date().toISOString();
254
259
  const job = {
255
260
  id: `build_${randomUUID()}`,
@@ -271,9 +276,17 @@ export class BuilderManager {
271
276
  this.#jobs.set(job.id, job);
272
277
  while (this.#jobs.size > 100)
273
278
  this.#jobs.delete(this.#jobs.keys().next().value);
274
- void this.#run(job);
279
+ const run = this.#run(job);
280
+ this.#activeRuns.add(run);
281
+ void run.finally(() => this.#activeRuns.delete(run));
275
282
  return this.#publicJob(job);
276
283
  }
284
+ async close() {
285
+ this.#closing = true;
286
+ for (const client of this.#activeClients)
287
+ client.destroy();
288
+ await Promise.allSettled(this.#activeRuns);
289
+ }
277
290
  get(jobId) {
278
291
  const job = this.#jobs.get(jobId);
279
292
  return job ? this.#publicJob(job) : null;
@@ -294,6 +307,8 @@ export class BuilderManager {
294
307
  async #run(job) {
295
308
  let activeClient = null;
296
309
  try {
310
+ if (this.#closing)
311
+ throw new Error("Build cancelled because the daemon is stopping.");
297
312
  this.#update(job, { state: "collecting", message: "Collecting Template dependencies" });
298
313
  const descriptors = new Map();
299
314
  const visit = async (assetId, stack) => {
@@ -354,6 +369,9 @@ export class BuilderManager {
354
369
  ]));
355
370
  const settings = await loadS3Settings(this.rootDir, prepared.projectDirectory);
356
371
  activeClient = settings.client;
372
+ this.#activeClients.add(activeClient);
373
+ if (this.#closing)
374
+ throw new Error("Build cancelled because the daemon is stopping.");
357
375
  job.configSource = settings.source;
358
376
  const prefix = normalizePrefix(job.options.prefix || settings.defaultPrefix);
359
377
  const uploads = new Map();
@@ -504,6 +522,8 @@ export class BuilderManager {
504
522
  const uploadFiles = [...uploads.values()];
505
523
  this.#update(job, { state: "uploading", message: `Uploading 0/${uploadFiles.length} files` });
506
524
  await mapWithConcurrency(uploadFiles, 4, async (file) => {
525
+ if (this.#closing)
526
+ throw new Error("Build cancelled because the daemon is stopping.");
507
527
  const info = await stat(file.path);
508
528
  const input = {
509
529
  Bucket: settings.bucket,
@@ -535,7 +555,10 @@ export class BuilderManager {
535
555
  });
536
556
  }
537
557
  finally {
538
- activeClient?.destroy();
558
+ if (activeClient) {
559
+ this.#activeClients.delete(activeClient);
560
+ activeClient.destroy();
561
+ }
539
562
  }
540
563
  }
541
564
  }