playcanvas-agent-bridge-cli 0.6.2 → 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.
- package/README.md +71 -10
- package/README.zh-CN.md +68 -10
- package/dist/cli.js +384 -89
- package/dist/config.js +23 -1
- package/dist/daemon/server.js +259 -29
- package/dist/plugins/host.js +260 -0
- package/dist/plugins/store.js +567 -0
- package/dist/updates.js +475 -0
- package/extension/isolated.js +12 -3
- package/extension/main.js +72 -246
- package/extension/manifest.json +1 -1
- package/extension/popup.html +82 -1
- package/extension/popup.js +257 -4
- package/extension/service-worker.js +99 -5
- package/package.json +7 -8
- package/plugins/index.json +14 -0
- package/plugins/tinyapp-builder/node/builder.js +589 -0
- package/plugins/tinyapp-builder/node/index.js +30 -0
- package/plugins/tinyapp-builder/package.json +13 -0
- package/plugins/tinyapp-builder/page/editor.js +249 -0
- package/plugins/tinyapp-builder/pcbridge-plugin.json +28 -0
- package/skills/claude/pcbridge-plugin-authoring/SKILL.md +220 -0
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +24 -18
- package/skills/codex/pcbridge-plugin-authoring/SKILL.md +220 -0
- package/skills/codex/pcbridge-plugin-authoring/agents/openai.yaml +4 -0
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +32 -20
- package/skills/cursor/pcbridge-plugin-authoring.mdc +221 -0
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +14 -13
- package/skills/windsurf/pcbridge-plugin-authoring.md +215 -0
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +14 -13
- package/dist/builder/manager.js +0 -564
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ bun add --global github:Q-My99/playcanvas-agent-bridge-cli
|
|
|
26
26
|
pcbridge install-skill --agent all
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
The commands documented below track repository version `0.
|
|
29
|
+
The commands documented below track repository version `0.7.0`. bun installs the latest stable
|
|
30
30
|
release; use the GitHub install when testing changes that have not been released yet.
|
|
31
31
|
|
|
32
32
|
One-shot with npx:
|
|
@@ -38,15 +38,38 @@ npx playcanvas-agent-bridge-cli install-skill --agent all
|
|
|
38
38
|
|
|
39
39
|
## Update pcbridge components
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
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
43
|
|
|
44
|
-
|
|
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.
|
|
49
|
+
|
|
50
|
+
### One-click update (CLI, daemon, skills, Chrome extension, and plugins)
|
|
51
|
+
|
|
52
|
+
```bash
|
|
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
|
|
45
67
|
|
|
46
68
|
```bash
|
|
47
69
|
bun add --global playcanvas-agent-bridge-cli@latest
|
|
48
70
|
pcbridge version
|
|
49
71
|
pcbridge install-skill --agent all
|
|
72
|
+
pcbridge install-extension --no-open
|
|
50
73
|
pcbridge daemon restart --workspace /the/workspace/root
|
|
51
74
|
```
|
|
52
75
|
|
|
@@ -224,7 +247,7 @@ against `.pcbridge/baselines/`: non-overlapping local and Editor edits merge aut
|
|
|
224
247
|
conflicting edits to the same leaf property preserve `.local`, `.remote`, and `.conflict.json` under
|
|
225
248
|
`tmp/conflicts/`. Images, models, audio, fonts, and files above the direct-sync limit remain lazy:
|
|
226
249
|
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`
|
|
250
|
+
on demand via `workspace pull` or the Tiny Builder plugin. New local files (including new `*.<type>.json`
|
|
228
251
|
structured assets) create matching remote Assets and folders; renames and moves preserve the Asset
|
|
229
252
|
ID via embedded `$pcbridge.id`, file inode, or content hash. Deleting an eagerly synced Tier 1 file
|
|
230
253
|
locally backs up the file under `tmp/trash/local/` and deletes the remote Asset to keep both sides
|
|
@@ -251,9 +274,47 @@ schema-v1 and schema-v2 state is migrated automatically; the v1 hidden index is
|
|
|
251
274
|
An empty snapshot received while indexed assets exist is ignored, and a non-empty shrinking
|
|
252
275
|
snapshot must repeat before files are moved to `tmp/trash/remote/`.
|
|
253
276
|
|
|
254
|
-
##
|
|
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:
|
|
282
|
+
|
|
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.
|
|
255
316
|
|
|
256
|
-
|
|
317
|
+
With the plugin enabled, selecting a PlayCanvas Template Asset adds a **pcbridge Tiny Builder** section to the Attributes
|
|
257
318
|
panel. **Build and upload to S3** collects recursive Asset references, attached scripts, and child
|
|
258
319
|
Templates in the page. The daemon materializes every dependency under `assets/`: an existing local
|
|
259
320
|
file is reused when it matches the effective remote MD5, while a missing or remote-updated file is
|
|
@@ -288,8 +349,8 @@ and uploads use a fixed `Content-MD5` instead of streaming checksum trailers. Bu
|
|
|
288
349
|
started and inspected from the CLI:
|
|
289
350
|
|
|
290
351
|
```bash
|
|
291
|
-
pcbridge builder start --target editor:<sceneId> --
|
|
292
|
-
pcbridge builder status --
|
|
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>"}'
|
|
293
354
|
```
|
|
294
355
|
|
|
295
356
|
Script, JSON, upload, and capture paths are restricted to the selected project workspace by default.
|
|
@@ -317,7 +378,7 @@ pcbridge help core
|
|
|
317
378
|
pcbridge help workspace
|
|
318
379
|
pcbridge help processing
|
|
319
380
|
pcbridge help import
|
|
320
|
-
pcbridge help
|
|
381
|
+
pcbridge help plugin
|
|
321
382
|
pcbridge help frontend
|
|
322
383
|
pcbridge help target
|
|
323
384
|
pcbridge help entity
|
package/README.zh-CN.md
CHANGED
|
@@ -19,7 +19,7 @@ bun add --global playcanvas-agent-bridge-cli
|
|
|
19
19
|
pcbridge install-skill --agent all
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
下文命令跟随仓库版 `0.
|
|
22
|
+
下文命令跟随仓库版 `0.7.0`。npm 安装的是最新稳定版本;测试尚未发布的改动时请使用
|
|
23
23
|
GitHub 安装。
|
|
24
24
|
|
|
25
25
|
如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
|
|
@@ -38,15 +38,37 @@ npx playcanvas-agent-bridge-cli install-skill --agent all
|
|
|
38
38
|
|
|
39
39
|
## 更新 pcbridge 各组件
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
`pcbridge` 会后台定期检查 npm 上的最新 CLI/浏览器扩展版本,以及 GitHub 仓库(`plugins/index.json`)
|
|
42
|
+
中独立演进的官方插件版本。检测到可用更新时:
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
- **浏览器插件徽标与弹窗**:Chrome 工具栏图标会显示 `↑` 角标;打开弹窗即可在顶部点击
|
|
45
|
+
**Update & Reload** 一键更新 `pcbridge` 本体,或在 **Plugins** 标签页点击 **Update** /
|
|
46
|
+
**Update all** 一键热更新官方插件。
|
|
47
|
+
- **CLI 与 AI Agent**:命令返回的 JSON 信封会自动挂载结构化 `meta.updates` 字段,交互式终端会在
|
|
48
|
+
`stderr` 打印单行更新提示。
|
|
49
|
+
|
|
50
|
+
### 一键更新(CLI、daemon、Agent 技能、Chrome 插件与官方插件)
|
|
51
|
+
|
|
52
|
+
```bash
|
|
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
|
+
### 手动分步更新命令
|
|
45
66
|
|
|
46
67
|
```bash
|
|
47
68
|
bun add --global playcanvas-agent-bridge-cli@latest
|
|
48
69
|
pcbridge version
|
|
49
70
|
pcbridge install-skill --agent all
|
|
71
|
+
pcbridge install-extension --no-open
|
|
50
72
|
pcbridge daemon restart --workspace /原来的/workspace/根目录
|
|
51
73
|
```
|
|
52
74
|
|
|
@@ -215,7 +237,7 @@ DFS 排序,支持双向增量同步);未打开的其他场景落盘为只
|
|
|
215
237
|
实体或不同属性时自动无冲突合并并结构化 Patch 回写 Editor;仅当同一叶子属性被同时改成不同值时,
|
|
216
238
|
才将 `.local`、`.remote` 与 `.conflict.json` 隔离到 `tmp/conflicts/`。图片、模型、音频、字体及超过
|
|
217
239
|
直接同步上限的大文件保持懒同步:在 `pcbridge.project.json` 中记录元数据、尺寸规格与 MD5,按需通过
|
|
218
|
-
`workspace pull` 或 Tiny Builder
|
|
240
|
+
`workspace pull` 或 Tiny Builder 插件拉取。本地新增文件(包括新建 `*.<type>.json` 结构化资源)会在对应
|
|
219
241
|
目录自动创建远端 Asset;本地重命名和移动通过内嵌 `$pcbridge.id`、文件 inode 或内容哈希保持原 Asset ID。
|
|
220
242
|
删除本地直接同步(Tier 1)文件会先备份到 `tmp/trash/local/` 并同步删除远端 Asset 以避免状态歧义;
|
|
221
243
|
删除已拉取的懒同步(Tier 2)二进制文件则仅清理本地缓存,远端删除仍隔离到 `tmp/trash/remote/`。
|
|
@@ -238,9 +260,45 @@ pcbridge 管理。schema v1
|
|
|
238
260
|
收到的空快照会被忽略;
|
|
239
261
|
非空但缩小的快照必须连续出现两次,文件才会被移动到 `tmp/trash/remote/`。
|
|
240
262
|
|
|
241
|
-
##
|
|
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 管理插件:
|
|
276
|
+
|
|
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** 即可添加。
|
|
242
300
|
|
|
243
|
-
|
|
301
|
+
插件开启后,选中 PlayCanvas Template Asset,Attributes 面板会出现 **pcbridge Tiny Builder**。点击
|
|
244
302
|
**构建并上传到 S3** 后,网页只负责收集 Template、递归 Asset 引用、挂载脚本和子 Template;
|
|
245
303
|
daemon 会把全部依赖物化到 `assets/`:本地文件与有效远端 MD5 一致时直接复用,不存在或远端
|
|
246
304
|
已更新时先从 PlayCanvas 同步。贴图 variant 和字体附加图集会作为主 Asset 同目录下的只读
|
|
@@ -272,8 +330,8 @@ R2 等兼容服务;自定义服务是否需要 path-style URL 由
|
|
|
272
330
|
发起和查看任务:
|
|
273
331
|
|
|
274
332
|
```bash
|
|
275
|
-
pcbridge builder start --target editor:<sceneId> --
|
|
276
|
-
pcbridge builder status --
|
|
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>"}'
|
|
277
335
|
```
|
|
278
336
|
|
|
279
337
|
CLI 的脚本、JSON、上传文件和截图路径默认必须位于对应项目工作区内。只有明确需要使用
|
|
@@ -301,7 +359,7 @@ pcbridge help core
|
|
|
301
359
|
pcbridge help workspace
|
|
302
360
|
pcbridge help processing
|
|
303
361
|
pcbridge help import
|
|
304
|
-
pcbridge help
|
|
362
|
+
pcbridge help plugin
|
|
305
363
|
pcbridge help frontend
|
|
306
364
|
pcbridge help target
|
|
307
365
|
pcbridge help entity
|