playcanvas-agent-bridge-cli 0.6.1 → 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 +79 -23
- package/README.zh-CN.md +71 -25
- package/dist/cli.js +132 -8
- package/dist/config.js +1 -1
- package/dist/daemon/server.js +79 -1
- package/dist/daemon/target-registry.js +3 -0
- package/dist/processing/manager.js +265 -0
- package/dist/processing/tools.js +97 -0
- package/dist/snippets.js +27 -0
- package/dist/workspace/json-sync.js +821 -0
- package/dist/workspace/manager.js +1973 -326
- package/extension/icons/icon-128.png +0 -0
- package/extension/icons/icon-16.png +0 -0
- package/extension/icons/icon-256.png +0 -0
- package/extension/icons/icon-32.png +0 -0
- package/extension/icons/icon-48.png +0 -0
- package/extension/isolated.js +48 -0
- package/extension/main.js +708 -39
- package/extension/manifest.json +60 -10
- package/extension/popup.html +33 -2
- package/extension/popup.js +142 -11
- package/extension/service-worker.js +124 -1
- package/package.json +19 -18
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +76 -26
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +59 -44
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +57 -22
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +56 -22
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
|
-
|
|
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
|
-
|
|
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.
|
|
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:
|
|
@@ -38,7 +44,7 @@ frontend are separate local components. Updating one does not update the others
|
|
|
38
44
|
### Update the CLI, daemon, and agent skills
|
|
39
45
|
|
|
40
46
|
```bash
|
|
41
|
-
|
|
47
|
+
bun add --global playcanvas-agent-bridge-cli@latest
|
|
42
48
|
pcbridge version
|
|
43
49
|
pcbridge install-skill --agent all
|
|
44
50
|
pcbridge daemon restart --workspace /the/workspace/root
|
|
@@ -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
|
|
@@ -180,9 +192,10 @@ When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` auto
|
|
|
180
192
|
```text
|
|
181
193
|
1552681-pcbridge-test/
|
|
182
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
|
|
183
196
|
├── assets/ # collision-safe projection of the PlayCanvas folder tree
|
|
184
|
-
├── tmp/ # builds, cache, conflicts, captures, and
|
|
185
|
-
└── .pcbridge/ # internal sync state and
|
|
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
|
|
186
199
|
```
|
|
187
200
|
|
|
188
201
|
Inspect or refresh the workspace with:
|
|
@@ -190,27 +203,43 @@ Inspect or refresh the workspace with:
|
|
|
190
203
|
```bash
|
|
191
204
|
pcbridge workspace status --target editor:<sceneId>
|
|
192
205
|
pcbridge workspace path --target editor:<sceneId>
|
|
206
|
+
pcbridge workspace settings [--eager-max-mb <1..10>]
|
|
193
207
|
pcbridge workspace sync --target editor:<sceneId>
|
|
194
208
|
pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
|
|
195
209
|
```
|
|
196
210
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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.
|
|
206
233
|
|
|
207
234
|
PlayCanvas may create source and generated Assets with the same display name, for example a source
|
|
208
235
|
GLB plus Container/Model outputs or a font plus generated atlas files. The manifest keeps the remote
|
|
209
236
|
display `folder` separate from the unique local `projectionPath`. The real `file.filename` is used
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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.
|
|
214
243
|
|
|
215
244
|
`pcbridge.project.json` schema v3 records `origin` (`source`, `derived`, or `standalone`), advertised
|
|
216
245
|
and observed remote file metadata, the effective MD5, and local presence/writability/current/base
|
|
@@ -286,6 +315,8 @@ The CLI exposes layered help so agents can load only the command surface they ne
|
|
|
286
315
|
pcbridge help
|
|
287
316
|
pcbridge help core
|
|
288
317
|
pcbridge help workspace
|
|
318
|
+
pcbridge help processing
|
|
319
|
+
pcbridge help import
|
|
289
320
|
pcbridge help builder
|
|
290
321
|
pcbridge help frontend
|
|
291
322
|
pcbridge help target
|
|
@@ -495,9 +526,9 @@ Safeguards:
|
|
|
495
526
|
## Development
|
|
496
527
|
|
|
497
528
|
```bash
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
529
|
+
bun install
|
|
530
|
+
bun run build
|
|
531
|
+
bun dist/cli.js doctor
|
|
501
532
|
```
|
|
502
533
|
|
|
503
534
|
Use `bun` for one-off TypeScript scripts if you add them.
|
|
@@ -509,7 +540,7 @@ repository does not need an `NPM_TOKEN` secret.
|
|
|
509
540
|
|
|
510
541
|
1. Update the same stable version in `package.json`, `src/config.ts`, and
|
|
511
542
|
`extension/manifest.json`.
|
|
512
|
-
2. Run `
|
|
543
|
+
2. Run `bun run test`, commit the release to `main`, and push `main`.
|
|
513
544
|
3. Create and push the matching tag, for example:
|
|
514
545
|
|
|
515
546
|
```bash
|
|
@@ -520,3 +551,28 @@ git push origin v<version>
|
|
|
520
551
|
The workflow rejects tags that do not match the package version or whose commit is not on `main`.
|
|
521
552
|
Configure the npm package's Trusted Publisher with GitHub user `Q-My99`, repository
|
|
522
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
|
-
|
|
18
|
+
bun add --global playcanvas-agent-bridge-cli
|
|
13
19
|
pcbridge install-skill --agent all
|
|
14
20
|
```
|
|
15
21
|
|
|
16
|
-
下文命令跟随仓库版 `0.6.
|
|
22
|
+
下文命令跟随仓库版 `0.6.2`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
|
|
17
23
|
GitHub 安装。
|
|
18
24
|
|
|
19
25
|
如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
|
|
20
26
|
|
|
21
27
|
```bash
|
|
22
|
-
|
|
28
|
+
bun add --global github:Q-My99/playcanvas-agent-bridge-cli
|
|
23
29
|
pcbridge install-skill --agent all
|
|
24
30
|
```
|
|
25
31
|
|
|
@@ -38,7 +44,7 @@ CLI/daemon、已安装的 Agent 技能、生成的 Chrome 插件和可选的本
|
|
|
38
44
|
### 更新 CLI、daemon 和 Agent 技能
|
|
39
45
|
|
|
40
46
|
```bash
|
|
41
|
-
|
|
47
|
+
bun add --global playcanvas-agent-bridge-cli@latest
|
|
42
48
|
pcbridge version
|
|
43
49
|
pcbridge install-skill --agent all
|
|
44
50
|
pcbridge daemon restart --workspace /原来的/workspace/根目录
|
|
@@ -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
|
|
@@ -176,9 +186,10 @@ pcbridge daemon stop
|
|
|
176
186
|
```text
|
|
177
187
|
1552681-pcbridge-test/
|
|
178
188
|
├── pcbridge.project.json # 项目信息和供 agent 读取的资源目录
|
|
189
|
+
├── scenes/ # 当前激活场景的可写 .scene.json 与未激活场景的只读镜像
|
|
179
190
|
├── assets/ # PlayCanvas 文件树的碰撞安全本地投影
|
|
180
|
-
├── tmp/ #
|
|
181
|
-
└── .pcbridge/ #
|
|
191
|
+
├── tmp/ # 构建产物、缓存、冲突、截图以及本地/远端删除回收站
|
|
192
|
+
└── .pcbridge/ # 内部同步状态、JSON 三方合并基线和内容寻址对象缓存,请勿手动修改
|
|
182
193
|
```
|
|
183
194
|
|
|
184
195
|
查看或手动刷新工作区:
|
|
@@ -186,28 +197,36 @@ pcbridge daemon stop
|
|
|
186
197
|
```bash
|
|
187
198
|
pcbridge workspace status --target editor:<sceneId>
|
|
188
199
|
pcbridge workspace path --target editor:<sceneId>
|
|
200
|
+
pcbridge workspace settings [--eager-max-mb <1..10>]
|
|
189
201
|
pcbridge workspace sync --target editor:<sceneId>
|
|
190
202
|
pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
|
|
191
203
|
```
|
|
192
204
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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 同步。
|
|
205
223
|
|
|
206
224
|
PlayCanvas 可能生成同名的源 Asset 和派生 Asset,例如源 GLB 与 Container/Model,或字体源文件
|
|
207
225
|
与字体图集。manifest 会把网页端显示路径 `folder` 和本地唯一路径 `projectionPath` 分开记录。
|
|
208
|
-
|
|
209
|
-
`.__pc_<type>_<assetId
|
|
210
|
-
|
|
226
|
+
派生二进制使用 `file.filename`,源资源和独立资源跟随 `asset.name`;只有名称碰撞时,才会在扩展名前加入
|
|
227
|
+
`.__pc_<type>_<assetId>`。派生二进制按需下载且只读(`0o444`),而关联源模型的结构化 JSON 资源
|
|
228
|
+
(如 FBX/GLB 导入生成的材质)保持可写并参与双向同步,仅在 `$pcbridge.sourceAssetId` 保留来源标记;
|
|
229
|
+
修改或移动只读派生二进制投影时,本地副本会隔离到
|
|
211
230
|
`tmp/conflicts/`,随后从对象缓存恢复正确内容,不会反向上传到 PlayCanvas。
|
|
212
231
|
|
|
213
232
|
schema v3 的 `pcbridge.project.json` 会记录 `origin`(`source`、`derived` 或 `standalone`)、
|
|
@@ -280,6 +299,8 @@ CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
|
|
|
280
299
|
pcbridge help
|
|
281
300
|
pcbridge help core
|
|
282
301
|
pcbridge help workspace
|
|
302
|
+
pcbridge help processing
|
|
303
|
+
pcbridge help import
|
|
283
304
|
pcbridge help builder
|
|
284
305
|
pcbridge help frontend
|
|
285
306
|
pcbridge help target
|
|
@@ -482,9 +503,9 @@ pcbridge install-skill --agent cursor --path ./.cursor/rules
|
|
|
482
503
|
## 开发
|
|
483
504
|
|
|
484
505
|
```bash
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
506
|
+
bun install
|
|
507
|
+
bun run build
|
|
508
|
+
bun dist/cli.js doctor
|
|
488
509
|
```
|
|
489
510
|
|
|
490
511
|
如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
|
|
@@ -495,7 +516,7 @@ node dist/cli.js doctor
|
|
|
495
516
|
仓库不需要保存 `NPM_TOKEN`。
|
|
496
517
|
|
|
497
518
|
1. 在 `package.json`、`src/config.ts` 和 `extension/manifest.json` 中同步更新同一个稳定版本号。
|
|
498
|
-
2. 运行 `
|
|
519
|
+
2. 运行 `bun run test`,把发布提交合并并推送到 `main`。
|
|
499
520
|
3. 创建并推送匹配的 tag,例如:
|
|
500
521
|
|
|
501
522
|
```bash
|
|
@@ -506,3 +527,28 @@ git push origin v<version>
|
|
|
506
527
|
如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。
|
|
507
528
|
推送 tag 前,需要在 npm 包设置中把 GitHub 用户设为 `Q-My99`、仓库设为
|
|
508
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 资源迁移。
|
package/dist/cli.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
#!/usr/bin/env
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
import { activeTools, installTools, TOOLS_ROOT } from "./processing/tools.js";
|
|
2
3
|
import { spawn } from "node:child_process";
|
|
3
4
|
import { realpathSync } from "node:fs";
|
|
4
5
|
import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
|
|
@@ -9,7 +10,7 @@ import { fileURLToPath } from "node:url";
|
|
|
9
10
|
import { CONFIG_DIR, DEFAULT_FRONTEND_PORT, DEFAULT_HOST, DEFAULT_PORT, EXTENSION_INSTALL_DIR, VERSION, copyDir, findPackageRoot, readOrCreateSession, readSessionIfExists, } from "./config.js";
|
|
10
11
|
import { createDaemonServer } from "./daemon/server.js";
|
|
11
12
|
import { FrontendError, getFrontendStatus, installFrontend, listFrontends, removeFrontend, useFrontend, } from "./frontend/store.js";
|
|
12
|
-
import { assetDeleteSnippet, assetFolderEnsureSnippet, assetCreateManySnippet, assetGetSnippet, assetInstantiateTemplateSnippet, assetListSnippet, entityAddComponentsSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateManySnippet, entityCreateSnippet, entityDeleteSnippet, entityDuplicateSnippet, entityGetSnippet, entityListSnippet, entityPatchManySnippet, entityPatchSnippet, entityReparentSnippet, entityRemoveComponentsSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, materialPatchSnippet, sceneSettingsGetSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, scriptUpsertSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateApplySnippet, templateCreateSnippet, templateOverridesSnippet, } from "./snippets.js";
|
|
13
|
+
import { assetDeleteSnippet, assetFolderEnsureSnippet, assetCreateManySnippet, assetGetSnippet, assetInstantiateTemplateSnippet, assetListSnippet, entityAddComponentsSnippet, entityAddComponentSnippet, entityAddScriptSnippet, entityCreateManySnippet, entityCreateSnippet, entityDeleteSnippet, entityDuplicateSnippet, entityGetSnippet, entityListSnippet, entityPatchManySnippet, entityPatchSnippet, entityReparentSnippet, entityRemoveComponentsSnippet, entityRemoveComponentSnippet, entitySetMaterialSnippet, materialCreateSnippet, materialPatchSnippet, sceneSettingsGetSnippet, sceneManageSnippet, sceneSettingsPatchSnippet, scriptCreateSnippet, scriptParseSnippet, scriptSetTextSnippet, scriptUpsertSnippet, storeDownloadSnippet, storeGetSnippet, storeSearchSnippet, templateApplySnippet, templateCreateSnippet, templateOverridesSnippet, } from "./snippets.js";
|
|
13
14
|
import { fail, ok } from "./shared/protocol.js";
|
|
14
15
|
function parseArgs(argv) {
|
|
15
16
|
const parsed = { _: [], flags: {} };
|
|
@@ -285,6 +286,8 @@ function listEnvelope(raw) {
|
|
|
285
286
|
}
|
|
286
287
|
function inferAssetType(path) {
|
|
287
288
|
const ext = extname(path).toLowerCase();
|
|
289
|
+
if ([".glb", ".fbx", ".obj"].includes(ext))
|
|
290
|
+
return "scene";
|
|
288
291
|
if ([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tga"].includes(ext))
|
|
289
292
|
return "texture";
|
|
290
293
|
if ([".mp3", ".wav", ".ogg", ".m4a"].includes(ext))
|
|
@@ -381,18 +384,22 @@ async function uploadAsset(args, spec) {
|
|
|
381
384
|
preload: spec.preload !== false,
|
|
382
385
|
}, 120000);
|
|
383
386
|
}
|
|
387
|
+
function bunVersionSupported(version) {
|
|
388
|
+
const [major, minor] = version.split(".").map(Number);
|
|
389
|
+
return major > 1 || (major === 1 && minor >= 4);
|
|
390
|
+
}
|
|
384
391
|
async function doctor() {
|
|
385
392
|
const session = await readSessionIfExists();
|
|
386
393
|
const checks = [];
|
|
387
394
|
const nextActions = [];
|
|
388
|
-
const
|
|
395
|
+
const bunVersion = process.versions.bun;
|
|
389
396
|
let daemonOk = false;
|
|
390
397
|
let connectedExtensionVersionsOk = true;
|
|
391
398
|
checks.push({
|
|
392
|
-
name: "
|
|
393
|
-
ok:
|
|
394
|
-
version: process.version,
|
|
395
|
-
message:
|
|
399
|
+
name: "bun",
|
|
400
|
+
ok: !!bunVersion && bunVersionSupported(bunVersion),
|
|
401
|
+
version: bunVersion || process.version,
|
|
402
|
+
message: bunVersion && bunVersionSupported(bunVersion) ? "Bun version is supported." : "Bun 1.4.0 or newer is required.",
|
|
396
403
|
});
|
|
397
404
|
if (!session) {
|
|
398
405
|
nextActions.push("Run pcbridge install-extension to create a local session token.");
|
|
@@ -505,7 +512,7 @@ async function doctor() {
|
|
|
505
512
|
}
|
|
506
513
|
return ok({
|
|
507
514
|
version: VERSION,
|
|
508
|
-
healthy:
|
|
515
|
+
healthy: !!bunVersion && bunVersionSupported(bunVersion) &&
|
|
509
516
|
daemonOk &&
|
|
510
517
|
extensionExists &&
|
|
511
518
|
generatedExtensionVersion === VERSION &&
|
|
@@ -1341,6 +1348,15 @@ async function handleScript(args) {
|
|
|
1341
1348
|
}
|
|
1342
1349
|
async function handleScene(args) {
|
|
1343
1350
|
const subcommand = args._[1];
|
|
1351
|
+
if (["list", "create", "open"].includes(subcommand)) {
|
|
1352
|
+
const name = flagString(args, "name");
|
|
1353
|
+
const id = flagString(args, "id");
|
|
1354
|
+
if (subcommand === "create" && !name)
|
|
1355
|
+
return fail("INVALID_REQUEST", "scene create requires --name.");
|
|
1356
|
+
if (subcommand === "open" && !id)
|
|
1357
|
+
return fail("INVALID_REQUEST", "scene open requires --id.");
|
|
1358
|
+
return rpcEval(args, sceneManageSnippet(), { action: subcommand, name: name || null, id: id || null }, 60000);
|
|
1359
|
+
}
|
|
1344
1360
|
if (subcommand === "settings" && (args._[2] || "get") === "get") {
|
|
1345
1361
|
return rpcEval(args, sceneSettingsGetSnippet());
|
|
1346
1362
|
}
|
|
@@ -1551,9 +1567,24 @@ async function handleWorkspace(args) {
|
|
|
1551
1567
|
rootDirectory: data.rootDirectory || null,
|
|
1552
1568
|
projectDirectory: data.projectDirectory || null,
|
|
1553
1569
|
assetsDirectory: data.assetsDirectory || null,
|
|
1570
|
+
scenesDirectory: data.scenesDirectory || null,
|
|
1554
1571
|
tmpDirectory: data.tmpDirectory || null,
|
|
1555
1572
|
});
|
|
1556
1573
|
}
|
|
1574
|
+
if (subcommand === "settings") {
|
|
1575
|
+
const rawLimit = flagString(args, "eager-max-mb") || flagString(args, "limit-mb");
|
|
1576
|
+
if (!rawLimit) {
|
|
1577
|
+
return fetchDaemon("/workspace/settings");
|
|
1578
|
+
}
|
|
1579
|
+
const mb = Number(rawLimit);
|
|
1580
|
+
if (!Number.isFinite(mb) || mb < 1 || mb > 10) {
|
|
1581
|
+
return fail("INVALID_REQUEST", "workspace settings --eager-max-mb must be between 1 and 10.");
|
|
1582
|
+
}
|
|
1583
|
+
return fetchDaemon("/workspace/settings", {
|
|
1584
|
+
method: "POST",
|
|
1585
|
+
body: JSON.stringify({ eagerMaxMb: Math.round(mb) }),
|
|
1586
|
+
});
|
|
1587
|
+
}
|
|
1557
1588
|
if (subcommand === "sync") {
|
|
1558
1589
|
return fetchDaemon("/workspace/sync", {
|
|
1559
1590
|
method: "POST",
|
|
@@ -1598,12 +1629,80 @@ async function handleBuilder(args) {
|
|
|
1598
1629
|
}
|
|
1599
1630
|
return fail("UNKNOWN_COMMAND", `Unknown builder command: ${subcommand}`);
|
|
1600
1631
|
}
|
|
1632
|
+
async function handleProcessing(args) {
|
|
1633
|
+
const action = args._[1] || "status";
|
|
1634
|
+
if (action === "install") {
|
|
1635
|
+
const source = args._[2];
|
|
1636
|
+
if (!source)
|
|
1637
|
+
return fail("INVALID_REQUEST", "processing install requires a trusted release manifest path or HTTPS URL.");
|
|
1638
|
+
return ok(await installTools(source));
|
|
1639
|
+
}
|
|
1640
|
+
if (action === "enable" || action === "disable") {
|
|
1641
|
+
await mkdir(TOOLS_ROOT, { recursive: true });
|
|
1642
|
+
if (action === "enable")
|
|
1643
|
+
await activeTools();
|
|
1644
|
+
const memoryMb = Number(flagString(args, "memory-mb", "1024"));
|
|
1645
|
+
const timeoutMs = Number(flagString(args, "timeout-ms", "600000"));
|
|
1646
|
+
if (!Number.isInteger(memoryMb) || memoryMb < 64 || memoryMb > 1024 || !Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000)
|
|
1647
|
+
return fail("INVALID_REQUEST", "memory-mb must be 64..1024; timeout-ms must be 1000..600000.");
|
|
1648
|
+
const settings = { enabled: action === "enable", memoryBytes: memoryMb * 1024 * 1024, timeoutMs };
|
|
1649
|
+
await writeFile(join(TOOLS_ROOT, "settings.json"), JSON.stringify(settings));
|
|
1650
|
+
return ok(settings);
|
|
1651
|
+
}
|
|
1652
|
+
if (action === "status")
|
|
1653
|
+
return fetchDaemon("/processing/capabilities", { method: "POST", body: JSON.stringify({ target: flagString(args, "target", "current") }) });
|
|
1654
|
+
return fail("UNKNOWN_COMMAND", `Unknown processing command: ${action}`);
|
|
1655
|
+
}
|
|
1656
|
+
async function handleImportJob(args) {
|
|
1657
|
+
const action = args._[1] || "list";
|
|
1658
|
+
const id = flagString(args, "job");
|
|
1659
|
+
if (["status", "cancel", "retry", "wait"].includes(action) && !id)
|
|
1660
|
+
return fail("INVALID_REQUEST", "--job is required.");
|
|
1661
|
+
const params = { action, jobId: id || null };
|
|
1662
|
+
if (action === "submit") {
|
|
1663
|
+
const assetId = flagString(args, "asset");
|
|
1664
|
+
const kind = flagString(args, "kind", "model");
|
|
1665
|
+
if (!assetId || !["model", "texture"].includes(kind || ""))
|
|
1666
|
+
return fail("INVALID_REQUEST", "submit requires --asset and --kind model|texture.");
|
|
1667
|
+
params.assetId = assetId;
|
|
1668
|
+
params.kind = kind || "model";
|
|
1669
|
+
params.options = objectJson(await readJsonFlag(args, "json"), "import options");
|
|
1670
|
+
}
|
|
1671
|
+
if (action !== "wait")
|
|
1672
|
+
return rpcCall(args, "bridge:importJob", params);
|
|
1673
|
+
const timeout = readTimeoutMs(args, 120000);
|
|
1674
|
+
if (timeout === null)
|
|
1675
|
+
return invalidTimeoutEnvelope();
|
|
1676
|
+
const deadline = Date.now() + timeout;
|
|
1677
|
+
while (Date.now() < deadline) {
|
|
1678
|
+
const result = await rpcCall(args, "bridge:importJob", { action: "status", jobId: id }, 15000, false);
|
|
1679
|
+
if (!result.ok)
|
|
1680
|
+
return result;
|
|
1681
|
+
const job = result.data;
|
|
1682
|
+
if (["failed", "cancelled"].includes(String(job.status)))
|
|
1683
|
+
return fail("IMPORT_" + String(job.status).toUpperCase(), String(job.error || job.status), undefined, job);
|
|
1684
|
+
if (job.status === "complete") {
|
|
1685
|
+
let workspace = { state: "not-requested" };
|
|
1686
|
+
if (flagBool(args, "sync-workspace")) {
|
|
1687
|
+
const synced = await fetchDaemon("/workspace/sync", { method: "POST", body: JSON.stringify({ target: flagString(args, "target", "current") }) });
|
|
1688
|
+
if (!synced.ok)
|
|
1689
|
+
return synced;
|
|
1690
|
+
workspace = synced.data;
|
|
1691
|
+
}
|
|
1692
|
+
return ok({ job, published: true, workspace });
|
|
1693
|
+
}
|
|
1694
|
+
await new Promise(resolve => setTimeout(resolve, 500));
|
|
1695
|
+
}
|
|
1696
|
+
return fail("IMPORT_WAIT_TIMEOUT", "Task is still pending; query the same job before submitting another.");
|
|
1697
|
+
}
|
|
1601
1698
|
function help(group = "overview") {
|
|
1602
1699
|
const groups = {
|
|
1603
1700
|
overview: [
|
|
1604
1701
|
"pcbridge help core",
|
|
1605
1702
|
"pcbridge help workspace",
|
|
1606
1703
|
"pcbridge help builder",
|
|
1704
|
+
"pcbridge help processing",
|
|
1705
|
+
"pcbridge help import",
|
|
1607
1706
|
"pcbridge help frontend",
|
|
1608
1707
|
"pcbridge help target",
|
|
1609
1708
|
"pcbridge help entity",
|
|
@@ -1639,10 +1738,26 @@ function help(group = "overview") {
|
|
|
1639
1738
|
workspace: [
|
|
1640
1739
|
"pcbridge workspace status --target editor:<sceneId>",
|
|
1641
1740
|
"pcbridge workspace path --target editor:<sceneId>",
|
|
1741
|
+
"pcbridge workspace settings [--eager-max-mb <1..10>]",
|
|
1642
1742
|
"pcbridge workspace sync --target editor:<sceneId>",
|
|
1643
1743
|
"pcbridge workspace pull --target editor:<sceneId> --asset <assetId>",
|
|
1644
1744
|
"daemon start/restart uses --workspace when provided, otherwise the current directory.",
|
|
1645
1745
|
],
|
|
1746
|
+
processing: [
|
|
1747
|
+
"pcbridge processing install <trusted-release.json-path-or-https-url>",
|
|
1748
|
+
"pcbridge processing enable [--memory-mb 1024] [--timeout-ms 600000]",
|
|
1749
|
+
"pcbridge processing disable",
|
|
1750
|
+
"pcbridge processing status --target editor:<sceneId>",
|
|
1751
|
+
"Selfhost only. Tools are opt-in; unavailable local compute falls back to server.",
|
|
1752
|
+
],
|
|
1753
|
+
import: [
|
|
1754
|
+
"pcbridge import submit --asset <source_asset_id> --kind model|texture [--json options.json] --target editor:<sceneId>",
|
|
1755
|
+
"pcbridge import list --target editor:<sceneId>",
|
|
1756
|
+
"pcbridge import status|cancel|retry --job <id> --target editor:<sceneId>",
|
|
1757
|
+
"pcbridge import wait --job <id> [--timeout-ms 120000] [--sync-workspace] --target editor:<sceneId>",
|
|
1758
|
+
"Complete means server publication. --sync-workspace separately waits for local metadata synchronization.",
|
|
1759
|
+
"New files use the existing asset upload command; model uploads create the same import jobs.",
|
|
1760
|
+
],
|
|
1646
1761
|
builder: [
|
|
1647
1762
|
"pcbridge builder start --target editor:<sceneId> --asset <template_asset_id> [--suffix '-${time}'] [--prefix assets]",
|
|
1648
1763
|
"pcbridge builder status --job <build_job_id>",
|
|
@@ -1709,6 +1824,9 @@ function help(group = "overview") {
|
|
|
1709
1824
|
],
|
|
1710
1825
|
scene: [
|
|
1711
1826
|
"pcbridge scene settings get --target editor:<sceneId>",
|
|
1827
|
+
"pcbridge scene list --target editor:<sceneId>",
|
|
1828
|
+
"pcbridge scene create --name <name> --target editor:<sceneId>",
|
|
1829
|
+
"pcbridge scene open --id <sceneId> --target editor:<sceneId>",
|
|
1712
1830
|
"pcbridge scene settings patch --target editor:<sceneId> --json ./scene-settings.json",
|
|
1713
1831
|
"pcbridge scene settings patch --target editor:<sceneId> --set render.fog='\"linear\"' --set physics.gravity='[0,-9.8,0]'",
|
|
1714
1832
|
],
|
|
@@ -1793,6 +1911,12 @@ async function main() {
|
|
|
1793
1911
|
else if (command === "install-skill") {
|
|
1794
1912
|
print(await installSkill(args));
|
|
1795
1913
|
}
|
|
1914
|
+
else if (command === "processing") {
|
|
1915
|
+
print(await handleProcessing(args));
|
|
1916
|
+
}
|
|
1917
|
+
else if (command === "import") {
|
|
1918
|
+
print(await handleImportJob(args));
|
|
1919
|
+
}
|
|
1796
1920
|
else if (command === "frontend") {
|
|
1797
1921
|
print(await handleFrontend(args));
|
|
1798
1922
|
}
|
package/dist/config.js
CHANGED
|
@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
|
|
|
4
4
|
import { homedir } from "node:os";
|
|
5
5
|
import { dirname, join, resolve } from "node:path";
|
|
6
6
|
import { fileURLToPath } from "node:url";
|
|
7
|
-
export const VERSION = "0.6.
|
|
7
|
+
export const VERSION = "0.6.2";
|
|
8
8
|
export const DEFAULT_HOST = "127.0.0.1";
|
|
9
9
|
export const DEFAULT_PORT = 17329;
|
|
10
10
|
export const DEFAULT_FRONTEND_PORT = 3487;
|