@hupu-tech/shaper 0.2.2 → 0.2.3
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/CHANGELOG.md +5 -0
- package/README.md +32 -216
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,131 +1,61 @@
|
|
|
1
1
|
# Shaper
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
Shaper 将项目初始化、本地预览、平台上传和审核流程连接起来。一个 npm 包提供命令行工具(CLI)、标准 stdio MCP 服务和开发技能(Skills),支持通过 AI 对话或终端完成开发。
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install -g @hupu-tech/shaper
|
|
9
|
-
shaper install --ide cursor
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
[安装](#安装) · [快速开始](#快速开始) · [接入-ai-工具](#接入-ai-工具) · [项目结构](#项目结构) · [常用命令](#常用命令) · [常见问题](#常见问题)
|
|
13
|
-
|
|
14
|
-
## 功能
|
|
15
|
-
|
|
16
|
-
- **AI 工具接入**:为 Codex、Cursor、Claude Code 安装 MCP 和用户级技能。
|
|
17
|
-
- **项目初始化**:提供 HTML、React、Phaser 模板;已有工程保留原代码和构建方式。
|
|
18
|
-
- **本地开发**:启动预览、查看日志、检查配置和构建产物。
|
|
19
|
-
- **平台交付**:上传生成预览,在浏览器核对资料后提交审核。
|
|
20
|
-
- **后台开发**:按需接入应用云服务、部署后台源码和执行版本化数据库迁移。
|
|
21
|
-
- **统一应用归属**:网页、CLI、MCP 复用同一个 App ID,避免重复创建和错误关联。
|
|
22
|
-
|
|
23
|
-
## 环境要求
|
|
24
|
-
|
|
25
|
-
- Node.js **22.14 或以上**,建议使用 Node.js 24。
|
|
26
|
-
- npm,以及一个拥有对应 Shaper 平台访问权限的账号。
|
|
27
|
-
- 通过 AI 开发时,需要支持 Skills 或 stdio MCP 的客户端。
|
|
28
|
-
|
|
29
|
-
已在 macOS 验证构建和安装流程。Windows 已适配 npm 命令入口、技能 junction 和凭据目录权限,完整实机验收仍在进行;Linux 完整链路也尚未验收。登录、上传和云能力需要目标 Shaper 服务启用对应接口。
|
|
3
|
+
在你熟悉的 AI 工具中开发网页、游戏和互动体验。提供项目初始化、本地预览、上传提审,以及配套的 Skills 和 MCP。
|
|
30
4
|
|
|
31
5
|
## 安装
|
|
32
6
|
|
|
33
|
-
|
|
7
|
+
需要 Node.js 22.14+,建议使用 Node.js 24。
|
|
34
8
|
|
|
35
9
|
```bash
|
|
36
10
|
npm install -g @hupu-tech/shaper
|
|
37
|
-
shaper --version
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
也可以不全局安装,使用 npx 执行命令:
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
npx -y @hupu-tech/shaper --help
|
|
44
|
-
npx -y @hupu-tech/shaper install --ide cursor
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
安装开发工具不会创建平台应用,也不会自动提交审核。
|
|
48
|
-
|
|
49
|
-
## 快速开始
|
|
50
|
-
|
|
51
|
-
### 1. 连接你的 AI 工具
|
|
52
|
-
|
|
53
|
-
按实际使用的客户端选择一条:
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
11
|
shaper install --ide cursor
|
|
57
|
-
shaper install --ide codex
|
|
58
|
-
shaper install --ide claude
|
|
59
12
|
```
|
|
60
13
|
|
|
61
|
-
|
|
14
|
+
将 `cursor` 换成 `codex` 或 `claude`,即可接入对应客户端。安装后按提示重启客户端。技能安装一次,多个项目共用。
|
|
62
15
|
|
|
63
|
-
|
|
64
|
-
shaper install --ide codex,cursor,claude
|
|
65
|
-
```
|
|
16
|
+
## 开始开发
|
|
66
17
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
从 Shaper 网页开始创作时,复制网页生成的命令,在**业务项目目录**运行。将示例中的 `AppID` 替换为网页提供的真实值:
|
|
18
|
+
在项目目录执行网页提供的初始化命令,将 `AppID` 替换为实际应用 ID:
|
|
70
19
|
|
|
71
20
|
```bash
|
|
72
21
|
shaper init --app AppID
|
|
73
22
|
```
|
|
74
23
|
|
|
75
|
-
|
|
24
|
+
新建应用必须在浏览器确认“创建并连接”,确认前不会创建应用或完成项目绑定。已有项目保留原代码和构建方式;应用 ID 冲突时,先核对归属,不要覆盖绑定。
|
|
76
25
|
|
|
77
|
-
|
|
26
|
+
也可以从模板新建项目:
|
|
78
27
|
|
|
79
28
|
```bash
|
|
80
29
|
shaper init my-project --template react
|
|
81
30
|
cd my-project
|
|
82
31
|
```
|
|
83
32
|
|
|
84
|
-
模板支持 `h5`、`react`、`phaser
|
|
85
|
-
|
|
86
|
-
**已有项目先核对原 App ID。** 已绑定或已识别的旧 ID 与命令目标冲突时,初始化会停止;已有源码但无法确定归属时,需要明确指定应用。不要使用新建应用来绕过权限或绑定错误。
|
|
33
|
+
模板支持 `h5`、`react`、`phaser`,默认使用 `h5`。
|
|
87
34
|
|
|
88
|
-
|
|
35
|
+
接下来直接向 AI 描述需求:
|
|
89
36
|
|
|
90
|
-
|
|
37
|
+
> 请检查当前项目配置,帮我实现需求,并启动本地预览。
|
|
91
38
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
也可以在终端操作:
|
|
39
|
+
或使用命令行:
|
|
95
40
|
|
|
96
41
|
```bash
|
|
97
|
-
shaper dev
|
|
98
|
-
shaper
|
|
99
|
-
shaper
|
|
100
|
-
shaper build
|
|
42
|
+
shaper dev # 本地预览
|
|
43
|
+
shaper check # 检查工程配置
|
|
44
|
+
shaper build # 构建
|
|
101
45
|
```
|
|
102
46
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
### 4. 上传和提审
|
|
47
|
+
## 上传与提审
|
|
106
48
|
|
|
107
49
|
```bash
|
|
108
50
|
shaper deploy
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
命令构建并上传当前应用,返回版本 ID 和预览信息。确认页面效果后,将下面的 `VersionID` 替换为上传返回的版本 ID:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
51
|
shaper publish --version VersionID --description "本次更新说明"
|
|
115
52
|
```
|
|
116
53
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
## 接入 AI 工具
|
|
54
|
+
`deploy` 构建并上传,返回版本 ID 和预览信息。预览确认后,将 `VersionID` 替换为实际版本 ID;在打开的浏览器页面核对资料,确认提交后进入审核。
|
|
120
55
|
|
|
121
|
-
|
|
122
|
-
| --- | --- |
|
|
123
|
-
| Codex | `shaper install --ide codex` |
|
|
124
|
-
| Cursor | `shaper install --ide cursor` |
|
|
125
|
-
| Claude Code | `shaper install --ide claude` |
|
|
126
|
-
| WorkBuddy、TRAE 等其他客户端 | 按客户端支持的方式手动配置 Skills 和 stdio MCP,目前没有自动安装参数 |
|
|
56
|
+
## 其他 AI 工具
|
|
127
57
|
|
|
128
|
-
|
|
58
|
+
WorkBuddy、TRAE 等客户端需手动接入,配置方式以客户端支持为准。stdio MCP 配置示例:
|
|
129
59
|
|
|
130
60
|
```json
|
|
131
61
|
{
|
|
@@ -138,146 +68,32 @@ shaper publish --version VersionID --description "本次更新说明"
|
|
|
138
68
|
}
|
|
139
69
|
```
|
|
140
70
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
手动安装技能时,读取包内 `skills/manifest.json`,按客户端规范接入对应技能目录。不要给未支持的客户端套用 `--ide cursor` 等参数。
|
|
144
|
-
|
|
145
|
-
默认提供七个核心技能:
|
|
146
|
-
|
|
147
|
-
| 技能 | 职责 |
|
|
148
|
-
| --- | --- |
|
|
149
|
-
| `shaper-product` | 明确目标、用户流程和完成条件 |
|
|
150
|
-
| `shaper-design` | 视觉、交互及体验设计 |
|
|
151
|
-
| `shaper-development` | 项目归属、工程接入和前端开发 |
|
|
152
|
-
| `shaper-game-development` | 玩法实现与游戏开发流程 |
|
|
153
|
-
| `shaper-backend` | 应用云服务、后台部署和数据库迁移 |
|
|
154
|
-
| `hupu-business` | 虎扑用户、分享及容器能力接入 |
|
|
155
|
-
| `shaper-release` | 构建、预览、提审确认和结果检查 |
|
|
156
|
-
|
|
157
|
-
可选安装离线养成玩法技能:
|
|
158
|
-
|
|
159
|
-
```bash
|
|
160
|
-
shaper install --ide cursor --skills shaper-idle-game
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
技能按用户级安装,后续项目复用;`init` 不把整套技能复制到每个项目。
|
|
164
|
-
|
|
165
|
-
## 项目结构
|
|
166
|
-
|
|
167
|
-
新模板采用统一结构,React 和 Phaser 的差异放在业务源码中:
|
|
168
|
-
|
|
169
|
-
```text
|
|
170
|
-
my-project/
|
|
171
|
-
├─ package.json
|
|
172
|
-
├─ package-lock.json
|
|
173
|
-
├─ shaper.config.json # 开发命令、构建命令、产物目录
|
|
174
|
-
├─ index.html
|
|
175
|
-
├─ src/ # 业务源码
|
|
176
|
-
├─ public/ # 保留路径的静态资源
|
|
177
|
-
├─ docs/
|
|
178
|
-
│ ├─ product.md
|
|
179
|
-
│ ├─ design.md
|
|
180
|
-
│ └─ validation.md
|
|
181
|
-
├─ AGENTS.md # AI 项目入口
|
|
182
|
-
├─ dist/ # 构建生成
|
|
183
|
-
└─ .shaper/ # 本地绑定与工具状态,不提交 Git
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
已有 HTML 或其他打包工程无需为了接入而整体搬迁。缺失的启动、构建配置需要结合原工程调整,并验证实际产物;不保证任意旧项目都能机械转换。
|
|
187
|
-
|
|
188
|
-
## 常用命令
|
|
189
|
-
|
|
190
|
-
在业务项目目录执行;完整参数以 `shaper <命令> --help` 为准。
|
|
191
|
-
|
|
192
|
-
| 命令 | 用途 |
|
|
193
|
-
| --- | --- |
|
|
194
|
-
| `shaper config` | 查看有效服务地址 |
|
|
195
|
-
| `shaper doctor` | 查看安装与登录状态 |
|
|
196
|
-
| `shaper status` | 查看当前项目绑定、版本和预览状态 |
|
|
197
|
-
| `shaper login` / `shaper logout` | 登录或退出当前服务的共用账号 |
|
|
198
|
-
| `shaper projects` | 列出已获授权的应用 |
|
|
199
|
-
| `shaper init` | 初始化或接入项目 |
|
|
200
|
-
| `shaper dev` / `shaper stop` | 启动或停止本地预览 |
|
|
201
|
-
| `shaper logs` | 查看本地运行日志 |
|
|
202
|
-
| `shaper check` / `shaper build` | 检查配置或构建网页 |
|
|
203
|
-
| `shaper deploy` | 上传当前应用的构建产物 |
|
|
204
|
-
| `shaper publish` | 打开指定版本的提审确认页 |
|
|
205
|
-
|
|
206
|
-
`shaper link --app AppID` 用于明确更换目录关联,应先确认目标应用和影响;它不迁移源码或云资源。
|
|
207
|
-
|
|
208
|
-
## 服务地址与登录
|
|
209
|
-
|
|
210
|
-
CLI 和 MCP 共用全局配置,设置服务地址无需先登录:
|
|
211
|
-
|
|
212
|
-
```bash
|
|
213
|
-
shaper config --server https://shaper.example.com
|
|
214
|
-
shaper config
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
上例是占位地址,请替换为平台提供的服务地址。未配置时默认使用 `https://shaper.hupu.com`。服务地址必须是 HTTPS origin,本机回环 HTTP 地址仅用于本地调试。
|
|
71
|
+
技能目录见安装包内的 `skills/manifest.json`。客户端找不到命令时,可使用 Node 和包内 `dist/cli.js` 的绝对路径启动 MCP。
|
|
218
72
|
|
|
219
|
-
|
|
220
|
-
- `SHAPER_CONFIG_HOME` 可指定独立配置目录;`SHAPER_SERVER` 可覆盖当前进程的默认服务。
|
|
221
|
-
- 修改地址后重启已运行的 MCP;环境变量需要由相应客户端进程继承。
|
|
222
|
-
- 登录凭据按服务保存,项目只保存 App ID 和服务地址。切换服务不会迁移应用。
|
|
223
|
-
- 同一服务的多个项目和 Agent 共用登录;补充授权保留已有权限,退出会影响该服务的全部本地项目。
|
|
73
|
+
## 项目与后端
|
|
224
74
|
|
|
225
|
-
|
|
75
|
+
- `shaper.config.json`:开发、构建命令及产物目录。
|
|
76
|
+
- `src/`、`public/`:业务源码与静态资源。
|
|
77
|
+
- `docs/`、`AGENTS.md`:项目文档与 AI 开发入口。
|
|
78
|
+
- `.shaper/`:本地绑定和工具状态,不提交 Git。
|
|
226
79
|
|
|
227
|
-
|
|
80
|
+
已有 HTML 或其他框架项目可以接入,无需统一改成 React。需要后端时,让 AI 使用后台开发技能处理云服务、数据库和网关;命令入口为 `shaper cloud --help`。
|
|
228
81
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
```bash
|
|
232
|
-
shaper login --cloud
|
|
233
|
-
shaper cloud init cloud/functions/api
|
|
234
|
-
shaper cloud enable
|
|
235
|
-
shaper cloud status
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
资源就绪后维护后台代码和数据库迁移,再使用 `shaper cloud deploy --directory cloud/functions/api` 部署。云资源可能产生费用,以平台提供的套餐和权限为准。
|
|
239
|
-
|
|
240
|
-
后台结构按职责分开:
|
|
241
|
-
|
|
242
|
-
```text
|
|
243
|
-
cloud/
|
|
244
|
-
├─ functions/api/ # 服务源码和运行配置
|
|
245
|
-
├─ database/migrations/ # 版本化 SQL 迁移
|
|
246
|
-
└─ gateway/routes.json # 路由声明
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
返回 `queued` / `running` 只代表已受理或执行中。使用 `shaper cloud operation OperationID` 查询最终结果;依赖迁移的代码须等迁移成功后再部署。网页上传与后台部署分别执行;一期每个应用只有一份活动后台服务。
|
|
250
|
-
|
|
251
|
-
## 升级与卸载
|
|
252
|
-
|
|
253
|
-
升级全局 CLI 后,重新安装客户端集成,使 MCP 和技能使用新版快照:
|
|
82
|
+
## 升级与排查
|
|
254
83
|
|
|
255
84
|
```bash
|
|
256
85
|
npm install -g @hupu-tech/shaper@latest
|
|
257
86
|
shaper install --ide cursor
|
|
258
87
|
```
|
|
259
88
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
```bash
|
|
263
|
-
shaper uninstall
|
|
264
|
-
npm uninstall -g @hupu-tech/shaper
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
`shaper uninstall` 只移除本工具管理的客户端配置与技能链接,保留登录和运行时缓存。若需撤销登录,在卸载 CLI 前执行 `shaper logout`。
|
|
268
|
-
|
|
269
|
-
## 常见问题
|
|
270
|
-
|
|
271
|
-
**安装成功,AI 仍找不到工具?** 重新加载 MCP 或重启客户端,并运行 `shaper doctor`。手动接入时检查客户端是否能找到 command;优先使用绝对路径。
|
|
272
|
-
|
|
273
|
-
**初始化提示应用 ID 冲突?** 当前目录可能属于另一个应用。核对原绑定和网页入口,回到原应用继续或使用新的空目录;不要删除绑定来绕过冲突。
|
|
274
|
-
|
|
275
|
-
**登录页面无法打开或服务未启用?** 用 `shaper config` 核对服务公开地址。CLI 配置地址不会自动启用后端 OAuth,需要服务端完成授权配置。
|
|
89
|
+
升级后重新安装客户端集成,使技能与 MCP 使用新版。
|
|
276
90
|
|
|
277
|
-
|
|
91
|
+
- `shaper doctor`:检查安装和登录状态。
|
|
92
|
+
- `shaper status`:查看当前项目状态。
|
|
93
|
+
- `shaper --help`:查看命令;`shaper <命令> --help` 查看参数。
|
|
278
94
|
|
|
279
|
-
|
|
95
|
+
已验证 macOS;Windows 和 Linux 完整流程尚待实机验证。
|
|
280
96
|
|
|
281
97
|
## 许可证
|
|
282
98
|
|
|
283
|
-
Copyright © 2026 Hupu
|
|
99
|
+
Copyright © 2026 Hupu。`UNLICENSED`,保留所有权利,详见 LICENSE。
|