playcanvas-agent-bridge-cli 0.2.2 → 0.4.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.
Files changed (34) hide show
  1. package/README.md +218 -52
  2. package/README.zh-CN.md +210 -51
  3. package/dist/cli.js +723 -92
  4. package/dist/config.js +6 -2
  5. package/dist/daemon/server.js +181 -19
  6. package/dist/daemon/target-registry.js +61 -3
  7. package/dist/frontend/server.js +191 -0
  8. package/dist/frontend/store.js +369 -0
  9. package/dist/shared/protocol.js +3 -1
  10. package/dist/snippets.js +764 -30
  11. package/dist/workspace/manager.js +536 -0
  12. package/extension/icons/concepts/pcbridge-bridge.png +0 -0
  13. package/extension/icons/concepts/pcbridge-cube.png +0 -0
  14. package/extension/icons/concepts/pcbridge-p-active.png +0 -0
  15. package/extension/icons/concepts/pcbridge-p-arch.png +0 -0
  16. package/extension/icons/concepts/pcbridge-p-bridge.png +0 -0
  17. package/extension/icons/concepts/pcbridge-p-emblem.png +0 -0
  18. package/extension/icons/concepts/pcbridge-signal.png +0 -0
  19. package/extension/icons/icon-128.png +0 -0
  20. package/extension/icons/icon-16.png +0 -0
  21. package/extension/icons/icon-32.png +0 -0
  22. package/extension/icons/icon-48.png +0 -0
  23. package/extension/isolated.js +214 -43
  24. package/extension/main.js +619 -32
  25. package/extension/manifest.json +29 -7
  26. package/extension/popup.html +188 -24
  27. package/extension/popup.js +199 -10
  28. package/extension/service-worker.js +268 -17
  29. package/package.json +4 -1
  30. package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +97 -24
  31. package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +167 -52
  32. package/skills/codex/playcanvas-agent-bridge-cli/agents/openai.yaml +2 -2
  33. package/skills/cursor/playcanvas-agent-bridge-cli.mdc +63 -23
  34. package/skills/windsurf/playcanvas-agent-bridge-cli.md +61 -23
package/README.zh-CN.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # playcanvas-agent-bridge-cli
2
2
 
3
- 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景。
3
+ 这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景和 PlayCanvas Launch 页面。
4
4
 
5
5
  核心接口是 `pcbridge` 命令、本地 daemon 和 Chrome Manifest V3 插件。MCP 不是核心依赖,之后可以作为薄适配层再加。
6
6
 
@@ -13,6 +13,9 @@ npm install -g playcanvas-agent-bridge-cli
13
13
  pcbridge install-skill --agent all
14
14
  ```
15
15
 
16
+ 下文命令包含仓库版 `0.4.2` 的尚未发布改动。在该版本发布前,npm 的 `latest`(截至
17
+ 2026-08-04 为 `0.3.0`)不包含这里列出的全部命令;测试本轮新能力时请使用 GitHub 安装。
18
+
16
19
  如果要测试尚未发布的改动,也可以直接从这个 GitHub 仓库安装:
17
20
 
18
21
  ```bash
@@ -50,30 +53,101 @@ pcbridge install-extension
50
53
  2. 开启 Developer Mode。
51
54
  3. 点击 Load unpacked。
52
55
  4. 选择 `pcbridge install-extension` 打印出来的那个目录。
53
- 5. 打开或刷新 PlayCanvas Editor 页面。
56
+ 5. 打开或刷新 PlayCanvas Editor 页面或 PlayCanvas Launch 页面。
54
57
 
55
58
  注意:生成目录里的 `config.json` 包含本地 session token。请加载 `~/.pcbridge/extension`,不要直接加载仓库里的原始 `extension/` 目录。
56
59
 
60
+ ## 使用自构建 Editor 前端
61
+
62
+ Editor 构建产物不会打进 npm 包。下面的命令会从 `Q-My99/playcanvas-editor` 下载最新
63
+ Release,校验发布清单、文件大小和 SHA-256,然后在本地激活:
64
+
65
+ ```bash
66
+ pcbridge frontend install latest
67
+ pcbridge frontend status
68
+ pcbridge daemon start
69
+ ```
70
+
71
+ daemon 会在 `http://localhost:3487` 提供当前激活的构建。打开
72
+ `https://playcanvas.com/editor/...` 页面后,在插件 popup 中点击 **Use custom frontend**。
73
+ 点击 **Use official frontend** 会删除 `use_local_frontend` 参数,并用官方前端重新加载同一个
74
+ Editor URL。
75
+
76
+ 插件会按 PlayCanvas project ID 记住最后一次在 popup 中选择的模式。之后进入
77
+ `/editor/project/<projectId>` 场景选择页或 `/editor/scene/<sceneId>` 场景编辑页时,会自动
78
+ 添加或删除 `use_local_frontend`,并保留 URL 中其他查询参数和 hash。该偏好只会在用户再次
79
+ 点击 **Use custom frontend** 或 **Use official frontend** 时改变;popup 的 **Project
80
+ preference** 会显示当前项目的记忆值。
81
+
82
+ 需要时可以显式管理本地版本:
83
+
84
+ ```bash
85
+ pcbridge frontend list
86
+ pcbridge frontend update
87
+ pcbridge frontend use playcanvas-editor-v2.28.1-r1
88
+ pcbridge frontend remove playcanvas-editor-v2.28.1-r1
89
+ ```
90
+
91
+ 下载的构建保存在 `~/.pcbridge/frontends/`。当前激活的版本不能直接删除,需要先切换到
92
+ 另一个已安装版本。
93
+
57
94
  ## 启动桥接
58
95
 
96
+ 请先进入希望作为本地工作区根目录的位置,再启动 daemon:
97
+
59
98
  ```bash
99
+ cd /path/to/my-playcanvas-workspace
60
100
  pcbridge daemon start
61
101
  ```
62
102
 
103
+ 连接 ready 的 Editor 后,pcbridge 会自动创建 `<projectId>-<projectName>/` 工程目录:
104
+
105
+ ```text
106
+ 1552681-pcbridge-test/
107
+ ├── pcbridge.project.json
108
+ ├── assets/ # 与 PlayCanvas 文件夹结构对应,脚本自动双向同步
109
+ ├── tmp/ # 临时脚本、清单、截图和冲突副本
110
+ └── .pcbridge/ # 内部资源索引,请勿手动修改
111
+ ```
112
+
113
+ 查看或手动刷新工作区:
114
+
115
+ ```bash
116
+ pcbridge workspace status --target editor:<sceneId>
117
+ pcbridge workspace path --target editor:<sceneId>
118
+ pcbridge workspace sync --target editor:<sceneId>
119
+ pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
120
+ ```
121
+
122
+ 脚本内容保持双向同步。资源的新建、移动、重命名和删除仍应使用 pcbridge 结构化命令;
123
+ 图片、模型和音频等文件只建立索引,需要时用 `workspace pull` 懒下载。检测到本地与远端
124
+ 同时修改时不会覆盖任一版本,冲突副本写入 `tmp/conflicts/`。
125
+
126
+ CLI 的脚本、JSON、上传文件和截图路径默认必须位于对应项目工作区内。只有明确需要使用
127
+ 外部文件时才使用 `--allow-external-path`。
128
+
63
129
  另开一个终端检查:
64
130
 
65
131
  ```bash
66
132
  pcbridge doctor
67
133
  pcbridge targets
68
- pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
134
+ pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor }"
135
+ pcbridge launch diagnose --target launch:<sceneId>
69
136
  ```
70
137
 
138
+ `doctor` 会区分 daemon 未监听(`DAEMON_NOT_LISTENING`)和受限环境禁止 localhost
139
+ (`LOOPBACK_ACCESS_DENIED`);只有前一种情况才应该再启动 daemon。
140
+
71
141
  ## 渐进式 help
72
142
 
73
143
  CLI 提供分层 help,方便 agent 只加载当前需要的命令面:
74
144
 
75
145
  ```bash
76
146
  pcbridge help
147
+ pcbridge help core
148
+ pcbridge help workspace
149
+ pcbridge help frontend
150
+ pcbridge help target
77
151
  pcbridge help entity
78
152
  pcbridge help asset
79
153
  pcbridge help material
@@ -82,70 +156,115 @@ pcbridge help script
82
156
  pcbridge help scene
83
157
  pcbridge help store
84
158
  pcbridge help viewport
159
+ pcbridge help launch
160
+ pcbridge help logs
85
161
  pcbridge help eval
86
162
  ```
87
163
 
88
164
  小而明确、能对应到单个 Editor 操作的任务优先用结构化命令。探索 API、自定义
89
- Editor/Engine 工作流、大量多步骤场景修改,则优先用 `pcbridge eval`,一段脚本通常更清楚也更快。
165
+ Editor/Engine 工作流、Launch 调试、大量多步骤场景修改,则优先用 `pcbridge eval`,一段脚本通常更清楚也更快。
90
166
 
91
167
  ## 常用命令
92
168
 
93
169
  ```bash
94
- pcbridge entity list --target current --limit 50
95
- pcbridge entity list --target current --tag enemy --component render
96
- pcbridge entity create --target current --json ./entity.json
97
- pcbridge entity create-many --target current --json ./entities.json
98
- pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
99
- pcbridge entity patch-many --target current --json ./edits.json
100
- pcbridge entity duplicate --target current --id <resource_id>
101
- pcbridge entity reparent --target current --id <resource_id> --parent <parent_resource_id>
102
- pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
103
- pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
104
- pcbridge entity delete --target current --id <resource_id>
105
-
106
- pcbridge asset list --target current --type script
107
- pcbridge asset list --target current --tag generated
108
- pcbridge asset get --target current --id <asset_id>
109
- pcbridge asset create --target current --json ./assets.json
110
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
111
- pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
112
- pcbridge asset instantiate --target current --id <template_asset_id>
113
- pcbridge asset delete --target current --id <asset_id>
114
-
115
- pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
116
- pcbridge material patch --target current --asset-id <asset_id> --set diffuse='[1,0,0]'
117
-
118
- pcbridge template create --target current --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
119
- pcbridge template instantiate --target current --id <template_asset_id>
120
-
121
- pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
122
- pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
123
- pcbridge script parse --target current --asset-id <asset_id>
170
+ pcbridge entity list --target editor:<sceneId> --limit 50
171
+ pcbridge entity list --target editor:<sceneId> --tag enemy --component render
172
+ pcbridge entity create --target editor:<sceneId> --json ./entity.json
173
+ pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
174
+ pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set position='[0,1,0]'
175
+ pcbridge entity patch-many --target editor:<sceneId> --json ./edits.json
176
+ pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
177
+ pcbridge entity reparent --target editor:<sceneId> --id <resource_id> --parent <parent_resource_id>
178
+ pcbridge entity set-material --target editor:<sceneId> --id <resource_id> --material-id <material_asset_id>
179
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
180
+ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
181
+ pcbridge entity delete --target editor:<sceneId> --id <resource_id>
182
+
183
+ pcbridge asset list --target editor:<sceneId> --type script
184
+ pcbridge asset list --target editor:<sceneId> --tag generated
185
+ pcbridge asset get --target editor:<sceneId> --id <asset_id>
186
+ pcbridge asset create --target editor:<sceneId> --json ./assets.json
187
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Demo/Textures"
188
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
189
+ pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
190
+ pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
191
+ pcbridge asset delete --target editor:<sceneId> --id <asset_id>
192
+
193
+ pcbridge material create --target editor:<sceneId> --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
194
+ pcbridge material patch --target editor:<sceneId> --asset-id <asset_id> --set diffuse='[1,0,0]'
195
+
196
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name DemoTemplate --folder "AI Agent Bridge/Demo/Templates"
197
+ pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
198
+ pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
199
+ pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
200
+ pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
201
+
202
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
203
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts" --parse --wait
204
+ pcbridge script set-text --target editor:<sceneId> --asset-id <asset_id> --file ./controller.js --parse --wait
205
+ pcbridge script parse --target editor:<sceneId> --asset-id <asset_id>
206
+
207
+ pcbridge scene settings get --target editor:<sceneId>
208
+ pcbridge scene settings patch --target editor:<sceneId> --set physics.gravity='[0,-9.8,0]'
209
+
210
+ pcbridge store search --target editor:<sceneId> --search vehicle --limit 20
211
+ pcbridge store get --target editor:<sceneId> --id <store_asset_id>
212
+ pcbridge store download --target editor:<sceneId> --id <store_asset_id> --name Vehicle --license-json ./license.json
213
+
214
+ pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas-viewport.png
215
+ pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
216
+
217
+ pcbridge logs get --target editor:<sceneId> --limit 100
218
+ pcbridge logs get --target launch:<sceneId> --level error
219
+ pcbridge logs clear --target editor:<sceneId>
220
+ ```
124
221
 
125
- pcbridge scene settings get --target current
126
- pcbridge scene settings patch --target current --set physics.gravity='[0,-9.8,0]'
222
+ 通过 bundle 或 runtime asset 注册、没有独立 script asset id 的 ScriptType,请使用
223
+ `--script-name`。脚本更新配合 `--parse --wait` 时,会在返回前校验远端文本、稳定的文件元数据
224
+ 以及最新的解析属性。这个完成检查覆盖远端 asset 和当前 Editor observer,不等待之后一次
225
+ workspace mirror sync。
226
+
227
+ Template apply 命令会调用 Editor 现有的 `templates:apply` action。存在 overrides 时,完成条件
228
+ 是 pipeline callback 已到达,且连续两次观察到 overrides 为 0。返回的 `verified` 只确认当前
229
+ Editor observer 状态,不代表刷新 Editor 后仍然持久。
230
+ Editor entity patch 是持久修改;apply 前必须先恢复只用于预览的 enabled/visibility 状态。
231
+ `apply-many` 会先校验清单,再串行处理每个 root。清单可以写成
232
+ `{"entityIds":["root-a","root-b"]}`,也可直接使用 entity id 或 `{ "entityId": "..." }` 条目数组。
233
+
234
+ 大型任务可以把上传清单放在生成文件旁边。`file` 的相对路径会按清单文件所在目录解析:
235
+
236
+ ```json
237
+ {
238
+ "assets": [
239
+ {
240
+ "key": "player",
241
+ "file": "final/player.png",
242
+ "name": "DemoPlayer",
243
+ "folder": "AI Agent Bridge/Demo/Textures"
244
+ }
245
+ ]
246
+ }
247
+ ```
127
248
 
128
- pcbridge store search --target current --search vehicle --limit 20
129
- pcbridge store get --target current --id <store_asset_id>
130
- pcbridge store download --target current --id <store_asset_id> --name Vehicle --license-json ./license.json
249
+ 当较大的 Editor 脚本需要本地配置时,用 `eval --args-json`,避免把 JSON 直接拼进代码里:
131
250
 
132
- pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
133
- pcbridge viewport focus --target current --id <resource_id> --view perspective
251
+ ```bash
252
+ pcbridge eval --target editor:<sceneId> --file ./install-scene.js --args-json ./install-args.json
134
253
  ```
135
254
 
136
255
  ## 贴图 + 材质 + 脚本工作流
137
256
 
138
257
  ```bash
139
- pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
140
- pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
258
+ pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
259
+ pcbridge asset upload --target editor:<sceneId> --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
141
260
 
142
- pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
261
+ pcbridge material create --target editor:<sceneId> --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
143
262
 
144
- pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
263
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
145
264
 
146
- pcbridge entity create --target current --json ./box.json
147
- pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
148
- pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
265
+ pcbridge entity create --target editor:<sceneId> --json ./box.json
266
+ pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
267
+ pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
149
268
  ```
150
269
 
151
270
  ## 目标选择
@@ -156,9 +275,26 @@ pcbridge eval --target current --code "return location.href"
156
275
  pcbridge eval --target tab:123 --code "return location.href"
157
276
  pcbridge eval --target scene:987654 --code "return location.href"
158
277
  pcbridge eval --target project:123456 --code "return location.href"
278
+ pcbridge launch diagnose --target launch:987654
279
+ pcbridge launch wait-ready --target launch:987654 --focus --timeout-ms 30000
280
+ pcbridge eval --target launch:987654 --code "return { runtimeCreated: !!runtimeApp, rootChildCount: runtimeApp?.root?.children?.length ?? 0 }"
281
+ pcbridge viewport capture --target launch:987654 --out ./tmp/launch.png
282
+ pcbridge logs get --target launch:987654 --limit 100
159
283
  ```
160
284
 
161
- `current` 表示最近可用的 PlayCanvas Editor 目标页。
285
+ `current` 表示最近可用的 PlayCanvas 目标页。如果同一个 scene 同时打开了 Editor 和 Launch
286
+ 页面,请使用 `tab:<id>`、`editor:<sceneId>` 或 `launch:<sceneId>` 避免歧义。结构化编辑命令需要
287
+ Editor 目标;`eval`、`viewport capture` 和 `logs` 也可以用于 Launch 目标。
288
+
289
+ Launch ready 是尽力而为的启发式判断,不是 Engine 生命周期事件。`lifecycleReady` 要求找到
290
+ 拥有自身 graphics canvas/context 的 runtime app、scene root 已挂载、至少完成一帧,并且没有
291
+ 识别到启动遮罩;target `ready` 还要求 tab 可见。因此后台 Launch 应使用
292
+ `launch wait-ready --focus`。`scriptTypeCount` 只用于诊断,不能证明所有 ScriptType 已注册。
293
+ eval 提供通过兼容 resolver 选择的 Engine V1/V2 `runtimeApp`。
294
+
295
+ `viewport capture` 只截取当前 canvas,不会调整 Chrome 尺寸或模拟手机 DPR。PNG 可能保留
296
+ 透明通道;默认的 `--max-width 1200` 可能缩放输出。eval 输出有边界;优先返回叶子字段,必要时再使用有
297
+ 上限的 `--max-depth`、`--max-items` 或 `--max-keys`。
162
298
 
163
299
  ## Agent skill / rules
164
300
 
@@ -179,15 +315,20 @@ pcbridge install-skill --agent all
179
315
  - Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
180
316
  - Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
181
317
 
318
+ 插件 popup 会展示 daemon、当前 tab、项目、scene、branch、工作区路径、同步统计、冲突数
319
+ 以及自定义 Editor frontend 状态。红色表示断联或冲突,黄色表示初始化、同步中或本地待处理
320
+ 状态,绿色表示 ready / synced。
321
+
182
322
  ## 安全模型
183
323
 
184
- 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 页面内执行 JavaScript。
324
+ 这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 和 Launch 页面内执行 JavaScript。
185
325
 
186
326
  基础防护:
187
327
 
188
328
  - daemon 只绑定 `127.0.0.1`;
329
+ - frontend 服务只绑定 `127.0.0.1`,会校验 Host,并且只提供当前已校验 Release 目录内的文件;
189
330
  - CLI、daemon、插件共享本地 session token;
190
- - 插件只匹配 PlayCanvas Editor URL;
331
+ - 插件只匹配 PlayCanvas Editor 和 Launch URL;
191
332
  - CLI 输出统一使用紧凑 JSON envelope;
192
333
  - 结构化写命令要求明确 ID 或 JSON 文件。
193
334
 
@@ -200,3 +341,21 @@ node dist/cli.js doctor
200
341
  ```
201
342
 
202
343
  如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
344
+
345
+ ## 发布到 npm(维护者)
346
+
347
+ 发布流程通过 `.github/workflows/npm-publish.yml` 使用 npm Trusted Publishing,GitHub
348
+ 仓库不需要保存 `NPM_TOKEN`。
349
+
350
+ 1. 在 `package.json`、`src/config.ts` 和 `extension/manifest.json` 中同步更新同一个稳定版本号。
351
+ 2. 运行 `pnpm test`,把发布提交合并并推送到 `main`。
352
+ 3. 创建并推送匹配的 tag,例如:
353
+
354
+ ```bash
355
+ git tag v<version>
356
+ git push origin v<version>
357
+ ```
358
+
359
+ 如果 tag 与包版本不一致,或者 tag 对应的提交不属于 `main`,workflow 会拒绝发布。
360
+ 推送 tag 前,需要在 npm 包设置中把 GitHub 用户设为 `Q-My99`、仓库设为
361
+ `playcanvas-agent-bridge-cli`、workflow 文件名设为 `npm-publish.yml`。