playcanvas-agent-bridge-cli 0.5.3 → 0.6.1

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
@@ -20,7 +20,7 @@ npm install -g github:Q-My99/playcanvas-agent-bridge-cli
20
20
  pcbridge install-skill --agent all
21
21
  ```
22
22
 
23
- The commands documented below track repository version `0.5.3`. npm installs the latest stable
23
+ The commands documented below track repository version `0.6.1`. npm installs the latest stable
24
24
  release; use the GitHub install when testing changes that have not been released yet.
25
25
 
26
26
  One-shot with npx:
@@ -30,6 +30,67 @@ npx playcanvas-agent-bridge-cli doctor
30
30
  npx playcanvas-agent-bridge-cli install-skill --agent all
31
31
  ```
32
32
 
33
+ ## Update pcbridge components
34
+
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.
37
+
38
+ ### Update the CLI, daemon, and agent skills
39
+
40
+ ```bash
41
+ npm install -g playcanvas-agent-bridge-cli@latest
42
+ pcbridge version
43
+ pcbridge install-skill --agent all
44
+ pcbridge daemon restart --workspace /the/workspace/root
45
+ ```
46
+
47
+ Installing the npm package replaces the CLI files, but an already-running daemon remains the old
48
+ in-memory version until it is restarted. `daemon restart` authenticates the existing pcbridge
49
+ listener, shuts it down gracefully, waits for the port to be released, and starts the new daemon in
50
+ the current terminal. It never kills an unverified process merely because that process occupies the
51
+ configured port. When upgrading from a version that predates authenticated shutdown, stop that old
52
+ daemon once with **Ctrl+C**, then use `daemon restart` for later switches and upgrades.
53
+
54
+ Installed Codex, Claude, Cursor, and Windsurf skills are also copies, so rerun `install-skill`;
55
+ start a new agent task/session if the client has already loaded the old skill.
56
+
57
+ ### Update the Chrome extension
58
+
59
+ After updating the CLI, regenerate the unpacked extension directory:
60
+
61
+ ```bash
62
+ pcbridge install-extension --no-open
63
+ ```
64
+
65
+ Then complete these **manual Chrome steps**:
66
+
67
+ 1. Open `chrome://extensions`.
68
+ 2. Find **PlayCanvas Agent Bridge** and click **Reload**. Loading it again is unnecessary when the
69
+ existing entry already points to `~/.pcbridge/extension`.
70
+ 3. If the extension is not installed, enable Developer Mode, click **Load unpacked**, and select the
71
+ directory printed by `pcbridge install-extension`.
72
+ 4. Refresh every open PlayCanvas Editor and Launch tab.
73
+ 5. After restarting the daemon, run `pcbridge doctor` and confirm the generated and connected
74
+ extension versions match the CLI.
75
+
76
+ Updating npm alone does not refresh `~/.pcbridge/extension`, and rewriting that directory does not
77
+ make Chrome reload an unpacked extension automatically.
78
+
79
+ ### Update the custom PlayCanvas Editor frontend
80
+
81
+ The custom frontend has its own release lifecycle and is not bundled with the CLI or extension:
82
+
83
+ ```bash
84
+ pcbridge frontend update
85
+ pcbridge frontend status
86
+ ```
87
+
88
+ `frontend update` downloads, verifies, and activates the latest published frontend by default. A
89
+ running daemon resolves the active release for each request, so a frontend-only update does not
90
+ require a daemon restart. The **manual step is to refresh the PlayCanvas Editor tab**. If the project
91
+ is currently using the official frontend, open the extension popup and choose **Use custom
92
+ frontend**. Previously downloaded frontend releases remain installed until explicitly removed.
93
+
33
94
  ## Install the Chrome extension
34
95
 
35
96
  Run:
@@ -93,21 +154,35 @@ until another installed release is selected.
93
154
 
94
155
  ## Start the bridge
95
156
 
96
- Change into the directory that should become the local workspace root before starting the daemon:
157
+ Use the current directory as the workspace root, or pass it explicitly:
97
158
 
98
159
  ```bash
99
160
  cd /path/to/my-playcanvas-workspace
100
161
  pcbridge daemon start
162
+
163
+ # Equivalent from any directory
164
+ pcbridge daemon start --workspace /path/to/my-playcanvas-workspace
165
+
166
+ # Stop the current daemon and switch workspace roots
167
+ pcbridge daemon restart --workspace /path/to/another-workspace
168
+
169
+ # Gracefully stop the authenticated pcbridge daemon
170
+ pcbridge daemon stop
101
171
  ```
102
172
 
173
+ `daemon restart` and `daemon stop` first verify the token-protected `/health` response. A token
174
+ mismatch or a non-pcbridge listener fails without terminating the process on that port. Both
175
+ `start` and `restart` run the daemon in the foreground so logs remain visible and **Ctrl+C** still
176
+ works.
177
+
103
178
  When a ready Editor connects, pcbridge creates `<projectId>-<projectName>/` automatically:
104
179
 
105
180
  ```text
106
181
  1552681-pcbridge-test/
107
182
  ├── pcbridge.project.json # project metadata plus the agent-readable asset catalog
108
- ├── assets/ # PlayCanvas folder mirror; scripts eager, binary assets lazy
183
+ ├── assets/ # collision-safe projection of the PlayCanvas folder tree
109
184
  ├── tmp/ # builds, cache, conflicts, captures, and quarantined remote deletions
110
- └── .pcbridge/ # internal sync state; do not edit
185
+ └── .pcbridge/ # internal sync state and content-addressed object cache; do not edit
111
186
  ```
112
187
 
113
188
  Inspect or refresh the workspace with:
@@ -129,10 +204,21 @@ imported type; local folders are created remotely. Renames and moves preserve th
129
204
  a local file only clears the local cache and never deletes the remote Asset. The `tmp/` tree is
130
205
  agent-owned and excluded from workspace synchronization.
131
206
 
132
- `pcbridge.project.json` schema v2 stores every asset id, type, PlayCanvas folder, project-relative
133
- `assets/...` file path, download presence, and the remote/local/base MD5 values. Agents may read
134
- this catalog directly; the `assets` object is managed by pcbridge. An existing schema-v1 hidden
135
- asset index is migrated automatically and retained as `.pcbridge/asset-index.v1.json` for rollback.
207
+ PlayCanvas may create source and generated Assets with the same display name, for example a source
208
+ GLB plus Container/Model outputs or a font plus generated atlas files. The manifest keeps the remote
209
+ 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.
214
+
215
+ `pcbridge.project.json` schema v3 records `origin` (`source`, `derived`, or `standalone`), advertised
216
+ and observed remote file metadata, the effective MD5, and local presence/writability/current/base
217
+ hashes. Texture variants, additional font maps, and similar build-only files are listed under
218
+ `local.resources`; they are read-only managed files beside the primary Asset projection. Agents may
219
+ read this catalog directly; the `assets` object is managed by pcbridge. Existing
220
+ schema-v1 and schema-v2 state is migrated automatically; the v1 hidden index is retained as
221
+ `.pcbridge/asset-index.v1.json` for rollback.
136
222
  An empty snapshot received while indexed assets exist is ignored, and a non-empty shrinking
137
223
  snapshot must repeat before files are moved to `tmp/trash/remote/`.
138
224
 
@@ -140,10 +226,14 @@ snapshot must repeat before files are moved to `tmp/trash/remote/`.
140
226
 
141
227
  Selecting a PlayCanvas Template Asset adds a **pcbridge Tiny Builder** section to the Attributes
142
228
  panel. **Build and upload to S3** collects recursive Asset references, attached scripts, and child
143
- Templates in the page. The daemon validates the workspace MD5 cache, downloads only missing or
144
- remote-updated files, and uploads objects concurrently without creating a ZIP. Generated
145
- `tinyapp.json` and `gamescript.js` files live under `tmp/builds/`; variants and additional font maps
146
- are cached under `tmp/cache/assets/`.
229
+ Templates in the page. The daemon materializes every dependency under `assets/`: an existing local
230
+ file is reused when it matches the effective remote MD5, while a missing or remote-updated file is
231
+ synchronized from PlayCanvas first. Texture variants and additional font maps are stored beside the
232
+ primary Asset as managed read-only resources, not under `tmp/cache/assets/`. The internal
233
+ `.pcbridge/objects/` cache avoids repeat downloads, and uploads run concurrently without creating a
234
+ ZIP. Attached non-`sds*` scripts are merged, transpiled to ES5 with Babel, and conservatively
235
+ compressed with Terser while preserving function and class names. Only generated `tinyapp.json`
236
+ and `gamescript.js` files live under `tmp/builds/`.
147
237
 
148
238
  Create `.env` in the directory where the daemon starts for workspace defaults, or in a project
149
239
  directory for per-project values. Project values override workspace values field by field. Do not
@@ -163,7 +253,10 @@ PCBRIDGE_S3_FORCE_PATH_STYLE=false
163
253
 
164
254
  The implementation uses the standard AWS S3 client and supports Amazon S3, Alibaba OSS, Tencent
165
255
  COS, Cloudflare R2, and other compatible providers. Set `PCBRIDGE_S3_FORCE_PATH_STYLE` when the
166
- provider requires path-style addressing. Builds can also be started and inspected from the CLI:
256
+ provider requires path-style addressing. Bucket-prefixed OSS endpoints such as
257
+ `https://my-bucket.oss-cn-shanghai.aliyuncs.com` are normalized before the SDK applies the bucket,
258
+ and uploads use a fixed `Content-MD5` instead of streaming checksum trailers. Builds can also be
259
+ started and inspected from the CLI:
167
260
 
168
261
  ```bash
169
262
  pcbridge builder start --target editor:<sceneId> --asset <templateAssetId> --suffix '-${time}'
@@ -360,6 +453,20 @@ pcbridge install-skill --agent windsurf
360
453
  pcbridge install-skill --agent all
361
454
  ```
362
455
 
456
+ Use `--path` to install one agent's skill or rule under a custom parent directory. Relative paths
457
+ are resolved from the current working directory, and pcbridge appends the standard directory or
458
+ filename so the parent itself is never cleared:
459
+
460
+ ```bash
461
+ pcbridge install-skill --agent codex --path "D:\AgentConfig\skills"
462
+ pcbridge install-skill --agent cursor --path ./.cursor/rules
463
+ ```
464
+
465
+ These create `D:\AgentConfig\skills\playcanvas-agent-bridge-cli\` and
466
+ `.cursor/rules/playcanvas-agent-bridge-cli.mdc`. Quote Windows paths that contain spaces.
467
+ `--agent all --path ...` is rejected because the supported agents use different artifact layouts;
468
+ run one command per agent for custom locations.
469
+
363
470
  Installed locations:
364
471
 
365
472
  - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
package/README.zh-CN.md CHANGED
@@ -13,7 +13,7 @@ npm install -g playcanvas-agent-bridge-cli
13
13
  pcbridge install-skill --agent all
14
14
  ```
15
15
 
16
- 下文命令跟随仓库版 `0.5.3`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
16
+ 下文命令跟随仓库版 `0.6.1`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
17
17
  GitHub 安装。
18
18
 
19
19
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
@@ -30,6 +30,64 @@ npx playcanvas-agent-bridge-cli doctor
30
30
  npx playcanvas-agent-bridge-cli install-skill --agent all
31
31
  ```
32
32
 
33
+ ## 更新 pcbridge 各组件
34
+
35
+ CLI/daemon、已安装的 Agent 技能、生成的 Chrome 插件和可选的本地 Editor 前端是四个独立的
36
+ 本地组件,更新其中一个不会自动更新其他组件。
37
+
38
+ ### 更新 CLI、daemon 和 Agent 技能
39
+
40
+ ```bash
41
+ npm install -g playcanvas-agent-bridge-cli@latest
42
+ pcbridge version
43
+ pcbridge install-skill --agent all
44
+ pcbridge daemon restart --workspace /原来的/workspace/根目录
45
+ ```
46
+
47
+ npm 全局安装会替换 CLI 文件,但已经运行的 daemon 仍然是内存中的旧版本,必须重启才会生效。
48
+ `daemon restart` 会先认证当前 pcbridge 服务,优雅关闭并等待端口释放,再在当前终端启动新
49
+ daemon。它不会因为某个进程占用了配置端口就直接杀掉该进程。从不支持认证关闭的旧版本升级
50
+ 时,第一次仍需在旧 daemon 终端按 **Ctrl+C**;完成这次迁移后即可使用 restart 切换和升级。
51
+
52
+ Codex、Claude、Cursor 和 Windsurf 的技能文件也是安装时复制出去的,因此需要重新执行
53
+ `install-skill`;如果当前 Agent 任务已经加载了旧技能,请新建一个任务或会话再使用新技能。
54
+
55
+ ### 更新 Chrome 插件
56
+
57
+ CLI 更新完成后,重新生成 unpacked 插件目录:
58
+
59
+ ```bash
60
+ pcbridge install-extension --no-open
61
+ ```
62
+
63
+ 然后完成以下 **Chrome 手动操作**:
64
+
65
+ 1. 打开 `chrome://extensions`。
66
+ 2. 找到 **PlayCanvas Agent Bridge**,点击 **Reload**。如果现有条目已经指向
67
+ `~/.pcbridge/extension`,不需要再次 Load unpacked。
68
+ 3. 如果插件尚未安装,开启 Developer Mode,点击 **Load unpacked**,选择
69
+ `pcbridge install-extension` 打印的目录。
70
+ 4. 刷新所有已经打开的 PlayCanvas Editor 和 Launch 页面。
71
+ 5. daemon 重启后运行 `pcbridge doctor`,确认生成目录中的插件版本、浏览器已连接插件版本和
72
+ CLI 版本一致。
73
+
74
+ 只更新 npm 包不会更新 `~/.pcbridge/extension`;重新写入插件目录后,Chrome 也不会自动 reload
75
+ unpacked 插件。
76
+
77
+ ### 更新 PlayCanvas 本地前端
78
+
79
+ 本地前端使用独立的 Release,不会随 CLI 或插件一起更新:
80
+
81
+ ```bash
82
+ pcbridge frontend update
83
+ pcbridge frontend status
84
+ ```
85
+
86
+ `frontend update` 默认会下载、校验并激活最新发布版。如果 daemon 已经运行,它会在每次请求时
87
+ 读取当前激活版本,因此只更新前端不需要重启 daemon;**用户仍然必须刷新 PlayCanvas Editor
88
+ 页面**。如果当前项目正在使用官方前端,请打开插件 popup,点击 **Use custom frontend**。
89
+ 旧的本地前端版本会继续保留,除非显式执行 `frontend remove`。
90
+
33
91
  ## 安装 Chrome 插件
34
92
 
35
93
  运行:
@@ -93,21 +151,34 @@ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
93
151
 
94
152
  ## 启动桥接
95
153
 
96
- 请先进入希望作为本地工作区根目录的位置,再启动 daemon:
154
+ 可以使用当前目录作为 workspace 根目录,也可以显式指定目录:
97
155
 
98
156
  ```bash
99
157
  cd /path/to/my-playcanvas-workspace
100
158
  pcbridge daemon start
159
+
160
+ # 在任意目录执行,效果相同
161
+ pcbridge daemon start --workspace /path/to/my-playcanvas-workspace
162
+
163
+ # 停止当前 daemon 并切换 workspace
164
+ pcbridge daemon restart --workspace /path/to/another-workspace
165
+
166
+ # 优雅停止经过认证的 pcbridge daemon
167
+ pcbridge daemon stop
101
168
  ```
102
169
 
170
+ `daemon restart` 和 `daemon stop` 都会先校验带 token 的 `/health` 响应。token 不匹配或端口上
171
+ 不是 pcbridge 服务时,命令会报错且不会终止占用端口的进程。`start` 和 `restart` 都以前台
172
+ 方式运行,日志仍然直接显示在终端中,也仍然可以使用 **Ctrl+C** 停止。
173
+
103
174
  连接 ready 的 Editor 后,pcbridge 会自动创建 `<projectId>-<projectName>/` 工程目录:
104
175
 
105
176
  ```text
106
177
  1552681-pcbridge-test/
107
178
  ├── pcbridge.project.json # 项目信息和供 agent 读取的资源目录
108
- ├── assets/ # 与 PlayCanvas 文件夹结构对应,所有文件内容自动双向同步
179
+ ├── assets/ # PlayCanvas 文件树的碰撞安全本地投影
109
180
  ├── tmp/ # 构建产物、缓存、冲突、截图和远端删除隔离副本
110
- └── .pcbridge/ # 内部同步状态,请勿手动修改
181
+ └── .pcbridge/ # 内部同步状态和内容寻址对象缓存,请勿手动修改
111
182
  ```
112
183
 
113
184
  查看或手动刷新工作区:
@@ -132,19 +203,32 @@ daemon 会监控项目 `assets/` 目录:本地新增文件会上传到对应
132
203
  缓存,不会删除 PlayCanvas 远端 Asset;远端删除仍会隔离到 `tmp/trash/remote/`。`tmp/` 下的
133
204
  构建、缓存和 agent 临时文件完全不参与 workspace 同步。
134
205
 
135
- schema v2 的 `pcbridge.project.json` 会记录每个 asset 的 id、类型、PlayCanvas 文件夹、相对
136
- 项目根目录的 `assets/...` 文件路径、是否已下载,以及远端、本地和同步基线 MD5。agent 可以
137
- 直接读取这些信息,但其中的 `assets` 对象由 pcbridge 管理。已有 schema v1 隐藏索引会自动
138
- 迁移,并保留为 `.pcbridge/asset-index.v1.json` 以便回退。已有资源时收到的空快照会被忽略;
206
+ PlayCanvas 可能生成同名的源 Asset 和派生 Asset,例如源 GLB 与 Container/Model,或字体源文件
207
+ 与字体图集。manifest 会把网页端显示路径 `folder` 和本地唯一路径 `projectionPath` 分开记录。
208
+ 本地优先使用真实的 `file.filename`;只有名称碰撞时,才会在扩展名前加入
209
+ `.__pc_<type>_<assetId>`。source 和 standalone 投影可写;derived 投影按需下载且只读,内容会
210
+ 缓存到 `.pcbridge/objects/<assetId>/<md5>/`。修改或移动 derived 投影时,本地副本会隔离到
211
+ `tmp/conflicts/`,随后从对象缓存恢复正确内容,不会反向上传到 PlayCanvas。
212
+
213
+ schema v3 的 `pcbridge.project.json` 会记录 `origin`(`source`、`derived` 或 `standalone`)、
214
+ PlayCanvas 声明和实际观察到的文件元数据、最终采用的 MD5,以及本地是否存在、是否可写、当前
215
+ 和同步基线 MD5。贴图 variant、字体附加图集等仅在构建中使用的文件记录在 `local.resources`
216
+ 中,并作为主 Asset 同目录下的只读受管文件。agent 可以直接读取这些信息,但 `assets` 对象由
217
+ pcbridge 管理。schema v1
218
+ 和 v2 会自动迁移;v1 隐藏索引仍保留为 `.pcbridge/asset-index.v1.json` 以便回退。已有资源时
219
+ 收到的空快照会被忽略;
139
220
  非空但缩小的快照必须连续出现两次,文件才会被移动到 `tmp/trash/remote/`。
140
221
 
141
222
  ## Template 构建与 S3 上传
142
223
 
143
224
  选中 PlayCanvas Template Asset 后,Attributes 面板会出现 **pcbridge Tiny Builder**。点击
144
225
  **构建并上传到 S3** 后,网页只负责收集 Template、递归 Asset 引用、挂载脚本和子 Template;
145
- daemon 会核对工作区 MD5,缺失或远端更新的文件才会下载到工作区,然后直接并发上传对象,
146
- 不再生成 ZIP。生成的 `tinyapp.json` 和 `gamescript.js` 保存在 `tmp/builds/`,变体和字体附加
147
- 贴图缓存于 `tmp/cache/assets/`。
226
+ daemon 会把全部依赖物化到 `assets/`:本地文件与有效远端 MD5 一致时直接复用,不存在或远端
227
+ 已更新时先从 PlayCanvas 同步。贴图 variant 和字体附加图集会作为主 Asset 同目录下的只读
228
+ 受管资源保存,不再写入 `tmp/cache/assets/`;`.pcbridge/objects/` 仅作为避免重复下载的内部
229
+ 对象缓存。随后并发上传对象,不生成 ZIP;只有 `tinyapp.json` 和 `gamescript.js` 保存在
230
+ `tmp/builds/`。挂载的非 `sds*` 脚本会先合并,再由 Babel 转换为 ES5,并由 Terser 做保守
231
+ 压缩;函数名和类名会保留,避免破坏脚本注册和运行时反射。
148
232
 
149
233
  在 daemon 启动目录创建 `.env` 作为工作区默认配置,也可以在单个项目目录创建 `.env`;
150
234
  项目配置按字段覆盖工作区配置。不要提交含密钥的 `.env`:
@@ -163,7 +247,10 @@ PCBRIDGE_S3_FORCE_PATH_STYLE=false
163
247
 
164
248
  以上配置使用 AWS S3 标准客户端,适用于 Amazon S3、阿里云 OSS、腾讯云 COS、Cloudflare
165
249
  R2 等兼容服务;自定义服务是否需要 path-style URL 由
166
- `PCBRIDGE_S3_FORCE_PATH_STYLE` 决定。也可以从 CLI 发起和查看任务:
250
+ `PCBRIDGE_S3_FORCE_PATH_STYLE` 决定。若 OSS endpoint 已包含 bucket 前缀,例如
251
+ `https://my-bucket.oss-cn-shanghai.aliyuncs.com`,pcbridge 会先规范化 endpoint,避免 SDK 再次
252
+ 拼接 bucket;上传使用固定 `Content-MD5`,不会发送流式 checksum trailer。也可以从 CLI
253
+ 发起和查看任务:
167
254
 
168
255
  ```bash
169
256
  pcbridge builder start --target editor:<sceneId> --asset <templateAssetId> --suffix '-${time}'
@@ -356,6 +443,18 @@ pcbridge install-skill --agent windsurf
356
443
  pcbridge install-skill --agent all
357
444
  ```
358
445
 
446
+ 使用 `--path` 可以把单个 Agent 的 skill 或 rule 安装到自定义父目录。相对路径从当前工作目录
447
+ 解析;pcbridge 会自动追加标准目录名或文件名,因此不会清空用户传入的父目录:
448
+
449
+ ```bash
450
+ pcbridge install-skill --agent codex --path "D:\AgentConfig\skills"
451
+ pcbridge install-skill --agent cursor --path ./.cursor/rules
452
+ ```
453
+
454
+ 以上命令分别生成 `D:\AgentConfig\skills\playcanvas-agent-bridge-cli\` 和
455
+ `.cursor/rules/playcanvas-agent-bridge-cli.mdc`。Windows 路径包含空格时必须使用引号。
456
+ 由于不同 Agent 的产物布局不同,`--agent all --path ...` 会被拒绝;自定义位置时请逐个安装。
457
+
359
458
  安装位置:
360
459
 
361
460
  - Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`