playcanvas-agent-bridge-cli 0.2.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/LICENSE +21 -0
- package/README.md +162 -0
- package/README.zh-CN.md +162 -0
- package/dist/cli.js +702 -0
- package/dist/config.js +94 -0
- package/dist/daemon/server.js +204 -0
- package/dist/daemon/target-registry.js +102 -0
- package/dist/shared/protocol.js +21 -0
- package/dist/snippets.js +613 -0
- package/extension/config.example.json +5 -0
- package/extension/isolated.js +224 -0
- package/extension/main.js +288 -0
- package/extension/manifest.json +39 -0
- package/extension/popup.html +47 -0
- package/extension/popup.js +26 -0
- package/extension/service-worker.js +33 -0
- package/package.json +42 -0
- package/skills/claude/playcanvas-agent-bridge-cli/SKILL.md +41 -0
- package/skills/codex/playcanvas-agent-bridge-cli/SKILL.md +150 -0
- package/skills/codex/playcanvas-agent-bridge-cli/agents/openai.yaml +4 -0
- package/skills/cursor/playcanvas-agent-bridge-cli.mdc +37 -0
- package/skills/windsurf/playcanvas-agent-bridge-cli.md +34 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# playcanvas-agent-bridge-cli
|
|
2
|
+
|
|
3
|
+
CLI-first local automation for controlling an already-open PlayCanvas Editor scene from AI coding agents such as Codex, Claude Code, Cursor, and Windsurf.
|
|
4
|
+
|
|
5
|
+
The core interface is the `pcbridge` command plus a local daemon and a Chrome Manifest V3 extension. MCP is intentionally not required.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
When published to npm:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g playcanvas-agent-bridge-cli
|
|
13
|
+
pcbridge install-skill --agent all
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
From this GitHub repository before npm publishing:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g github:Q-My99/playcanvas-agent-bridge-cli
|
|
20
|
+
pcbridge install-skill --agent all
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
One-shot with npx:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx github:Q-My99/playcanvas-agent-bridge-cli doctor
|
|
27
|
+
npx github:Q-My99/playcanvas-agent-bridge-cli install-skill --agent all
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Install the Chrome extension
|
|
31
|
+
|
|
32
|
+
Run:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pcbridge install-extension
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The command generates a local unpacked extension directory at:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
~/.pcbridge/extension
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
On Windows this path is under your user home directory. The path printed by
|
|
45
|
+
`pcbridge install-extension` is the source of truth.
|
|
46
|
+
|
|
47
|
+
Then in Chrome:
|
|
48
|
+
|
|
49
|
+
1. Open `chrome://extensions`.
|
|
50
|
+
2. Enable Developer Mode.
|
|
51
|
+
3. Click Load unpacked.
|
|
52
|
+
4. Select the exact directory printed by `pcbridge install-extension`.
|
|
53
|
+
5. Open or refresh a PlayCanvas Editor page.
|
|
54
|
+
|
|
55
|
+
The generated extension directory contains a local session token in `config.json`, so load that generated directory rather than the raw `extension/` folder from the repo.
|
|
56
|
+
|
|
57
|
+
## Start the bridge
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pcbridge daemon start
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
In another terminal:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pcbridge doctor
|
|
67
|
+
pcbridge targets
|
|
68
|
+
pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Common commands
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pcbridge entity list --target current --limit 50
|
|
75
|
+
pcbridge entity create --target current --json ./entity.json
|
|
76
|
+
pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
|
|
77
|
+
pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
|
|
78
|
+
pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
|
|
79
|
+
pcbridge entity delete --target current --id <resource_id>
|
|
80
|
+
|
|
81
|
+
pcbridge asset list --target current --type script
|
|
82
|
+
pcbridge asset get --target current --id <asset_id>
|
|
83
|
+
pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
|
|
84
|
+
pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
|
|
85
|
+
pcbridge asset delete --target current --id <asset_id>
|
|
86
|
+
|
|
87
|
+
pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
|
|
88
|
+
|
|
89
|
+
pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
|
|
90
|
+
pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
|
|
91
|
+
pcbridge script parse --target current --asset-id <asset_id>
|
|
92
|
+
|
|
93
|
+
pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Texture + material + script workflow
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
|
|
100
|
+
pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
|
|
101
|
+
|
|
102
|
+
pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
|
|
103
|
+
|
|
104
|
+
pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
|
|
105
|
+
|
|
106
|
+
pcbridge entity create --target current --json ./box.json
|
|
107
|
+
pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
|
|
108
|
+
pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Target selection
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pcbridge targets
|
|
115
|
+
pcbridge eval --target current --code "return location.href"
|
|
116
|
+
pcbridge eval --target tab:123 --code "return location.href"
|
|
117
|
+
pcbridge eval --target scene:987654 --code "return location.href"
|
|
118
|
+
pcbridge eval --target project:123456 --code "return location.href"
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`current` means the most recently seen ready PlayCanvas Editor target.
|
|
122
|
+
|
|
123
|
+
## Agent skills
|
|
124
|
+
|
|
125
|
+
Install rules/skills for common agents:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pcbridge install-skill --agent codex
|
|
129
|
+
pcbridge install-skill --agent claude
|
|
130
|
+
pcbridge install-skill --agent cursor
|
|
131
|
+
pcbridge install-skill --agent windsurf
|
|
132
|
+
pcbridge install-skill --agent all
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Installed locations:
|
|
136
|
+
|
|
137
|
+
- Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
|
|
138
|
+
- Claude: `~/.claude/skills/playcanvas-agent-bridge-cli`
|
|
139
|
+
- Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
|
|
140
|
+
- Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
|
|
141
|
+
|
|
142
|
+
## Security model
|
|
143
|
+
|
|
144
|
+
This is a local trusted developer tool. It executes JavaScript inside PlayCanvas Editor pages that you already have open.
|
|
145
|
+
|
|
146
|
+
Safeguards:
|
|
147
|
+
|
|
148
|
+
- daemon binds only to `127.0.0.1`;
|
|
149
|
+
- CLI, daemon, and extension share a local session token;
|
|
150
|
+
- extension matches only PlayCanvas Editor URLs;
|
|
151
|
+
- CLI output uses compact JSON envelopes;
|
|
152
|
+
- structured write commands require explicit IDs or JSON files.
|
|
153
|
+
|
|
154
|
+
## Development
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
pnpm install
|
|
158
|
+
pnpm build
|
|
159
|
+
node dist/cli.js doctor
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Use `bun` for one-off TypeScript scripts if you add them.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# playcanvas-agent-bridge-cli
|
|
2
|
+
|
|
3
|
+
这是一个 CLI 优先的本地自动化桥,用来让 Codex、Claude Code、Cursor、Windsurf 等 AI 编程 agent 控制已经打开的 PlayCanvas Editor 场景。
|
|
4
|
+
|
|
5
|
+
核心接口是 `pcbridge` 命令、本地 daemon 和 Chrome Manifest V3 插件。MCP 不是核心依赖,之后可以作为薄适配层再加。
|
|
6
|
+
|
|
7
|
+
## 安装
|
|
8
|
+
|
|
9
|
+
发布到 npm 后:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g playcanvas-agent-bridge-cli
|
|
13
|
+
pcbridge install-skill --agent all
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
在 npm 发布前,也可以直接从这个 GitHub 仓库安装:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g github:Q-My99/playcanvas-agent-bridge-cli
|
|
20
|
+
pcbridge install-skill --agent all
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
用 npx 一次性运行:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx github:Q-My99/playcanvas-agent-bridge-cli doctor
|
|
27
|
+
npx github:Q-My99/playcanvas-agent-bridge-cli install-skill --agent all
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 安装 Chrome 插件
|
|
31
|
+
|
|
32
|
+
运行:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pcbridge install-extension
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
这个命令会生成一个本地可加载插件目录:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
~/.pcbridge/extension
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
在 Windows 上,这个目录会位于你的用户主目录下。请以
|
|
45
|
+
`pcbridge install-extension` 实际打印出来的路径为准。
|
|
46
|
+
|
|
47
|
+
然后在 Chrome 中操作:
|
|
48
|
+
|
|
49
|
+
1. 打开 `chrome://extensions`。
|
|
50
|
+
2. 开启 Developer Mode。
|
|
51
|
+
3. 点击 Load unpacked。
|
|
52
|
+
4. 选择 `pcbridge install-extension` 打印出来的那个目录。
|
|
53
|
+
5. 打开或刷新 PlayCanvas Editor 页面。
|
|
54
|
+
|
|
55
|
+
注意:生成目录里的 `config.json` 包含本地 session token。请加载 `~/.pcbridge/extension`,不要直接加载仓库里的原始 `extension/` 目录。
|
|
56
|
+
|
|
57
|
+
## 启动桥接
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pcbridge daemon start
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
另开一个终端检查:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pcbridge doctor
|
|
67
|
+
pcbridge targets
|
|
68
|
+
pcbridge eval --target current --code "return { href: location.href, hasEditor: !!editor }"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## 常用命令
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pcbridge entity list --target current --limit 50
|
|
75
|
+
pcbridge entity create --target current --json ./entity.json
|
|
76
|
+
pcbridge entity patch --target current --id <resource_id> --set position='[0,1,0]'
|
|
77
|
+
pcbridge entity set-material --target current --id <resource_id> --material-id <material_asset_id>
|
|
78
|
+
pcbridge entity add-script --target current --id <resource_id> --asset-id <script_asset_id> --attributes '{"speed":2.5}'
|
|
79
|
+
pcbridge entity delete --target current --id <resource_id>
|
|
80
|
+
|
|
81
|
+
pcbridge asset list --target current --type script
|
|
82
|
+
pcbridge asset get --target current --id <asset_id>
|
|
83
|
+
pcbridge asset folder ensure --target current --path "AI Agent Bridge/Demo/Textures"
|
|
84
|
+
pcbridge asset upload --target current --file ./texture.png --name DemoTexture --folder "AI Agent Bridge/Demo/Textures"
|
|
85
|
+
pcbridge asset delete --target current --id <asset_id>
|
|
86
|
+
|
|
87
|
+
pcbridge material create --target current --name DemoMaterial --folder "AI Agent Bridge/Demo/Materials" --diffuse-map <texture_asset_id>
|
|
88
|
+
|
|
89
|
+
pcbridge script create --target current --filename controller.js --file ./controller.js --folder "AI Agent Bridge/Demo/Scripts"
|
|
90
|
+
pcbridge script set-text --target current --asset-id <asset_id> --file ./controller.js
|
|
91
|
+
pcbridge script parse --target current --asset-id <asset_id>
|
|
92
|
+
|
|
93
|
+
pcbridge viewport capture --target current --out ./tmp/playcanvas-viewport.png
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## 贴图 + 材质 + 脚本工作流
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pcbridge asset folder ensure --target current --path "AI Agent Bridge/Texture Box/Textures"
|
|
100
|
+
pcbridge asset upload --target current --file ./cat.png --name CatTexture --folder "AI Agent Bridge/Texture Box/Textures"
|
|
101
|
+
|
|
102
|
+
pcbridge material create --target current --name CatMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
|
|
103
|
+
|
|
104
|
+
pcbridge script create --target current --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
|
|
105
|
+
|
|
106
|
+
pcbridge entity create --target current --json ./box.json
|
|
107
|
+
pcbridge entity set-material --target current --id <box_resource_id> --material-id <material_asset_id>
|
|
108
|
+
pcbridge entity add-script --target current --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## 目标选择
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pcbridge targets
|
|
115
|
+
pcbridge eval --target current --code "return location.href"
|
|
116
|
+
pcbridge eval --target tab:123 --code "return location.href"
|
|
117
|
+
pcbridge eval --target scene:987654 --code "return location.href"
|
|
118
|
+
pcbridge eval --target project:123456 --code "return location.href"
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`current` 表示最近可用的 PlayCanvas Editor 目标页。
|
|
122
|
+
|
|
123
|
+
## Agent skill / rules
|
|
124
|
+
|
|
125
|
+
安装各家 agent 的使用说明:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pcbridge install-skill --agent codex
|
|
129
|
+
pcbridge install-skill --agent claude
|
|
130
|
+
pcbridge install-skill --agent cursor
|
|
131
|
+
pcbridge install-skill --agent windsurf
|
|
132
|
+
pcbridge install-skill --agent all
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
安装位置:
|
|
136
|
+
|
|
137
|
+
- Codex: `~/.codex/skills/playcanvas-agent-bridge-cli`
|
|
138
|
+
- Claude: `~/.claude/skills/playcanvas-agent-bridge-cli`
|
|
139
|
+
- Cursor: `~/.cursor/rules/playcanvas-agent-bridge-cli.mdc`
|
|
140
|
+
- Windsurf: `~/.windsurf/rules/playcanvas-agent-bridge-cli.md`
|
|
141
|
+
|
|
142
|
+
## 安全模型
|
|
143
|
+
|
|
144
|
+
这是一个本地可信开发工具,会在你已经打开的 PlayCanvas Editor 页面内执行 JavaScript。
|
|
145
|
+
|
|
146
|
+
基础防护:
|
|
147
|
+
|
|
148
|
+
- daemon 只绑定 `127.0.0.1`;
|
|
149
|
+
- CLI、daemon、插件共享本地 session token;
|
|
150
|
+
- 插件只匹配 PlayCanvas Editor URL;
|
|
151
|
+
- CLI 输出统一使用紧凑 JSON envelope;
|
|
152
|
+
- 结构化写命令要求明确 ID 或 JSON 文件。
|
|
153
|
+
|
|
154
|
+
## 开发
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
pnpm install
|
|
158
|
+
pnpm build
|
|
159
|
+
node dist/cli.js doctor
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
如果以后添加一次性 TypeScript 脚本,优先用 `bun` 执行。
|