@hupu-tech/shaper 0.0.0-stage → 0.2.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.
- package/CHANGELOG.md +19 -0
- package/LICENSE +3 -0
- package/README.md +282 -2
- package/dist/api.d.ts +29 -0
- package/dist/auth.d.ts +80 -0
- package/dist/cli.js +14 -0
- package/dist/cloud-service.d.ts +55 -0
- package/dist/cloud.d.ts +71 -0
- package/dist/config.d.ts +21 -0
- package/dist/core.d.ts +17 -0
- package/dist/credentials.d.ts +23 -0
- package/dist/dev-runner.js +1 -0
- package/dist/dev.d.ts +66 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.js +1 -0
- package/dist/legacy-cloud.d.ts +25 -0
- package/dist/runtime.d.ts +54 -0
- package/dist/runtime.js +1 -0
- package/dist/shared-2ZNSJXPO.js +15 -0
- package/dist/shared-BTZI42QW.js +17 -0
- package/dist/workspace.d.ts +84 -0
- package/package.json +73 -4
- package/skills/compat/hupu-cloud/SKILL.md +8 -0
- package/skills/core/hupu-business/SKILL.md +14 -0
- package/skills/core/hupu-business/references/runtime.md +55 -0
- package/skills/core/shaper-backend/SKILL.md +35 -0
- package/skills/core/shaper-backend/references/legacy.md +41 -0
- package/skills/core/shaper-backend/references/node-server.md +44 -0
- package/skills/core/shaper-design/SKILL.md +16 -0
- package/skills/core/shaper-development/SKILL.md +54 -0
- package/skills/core/shaper-game-development/SKILL.md +16 -0
- package/skills/core/shaper-product/SKILL.md +17 -0
- package/skills/core/shaper-product/references/ecosystem.md +10 -0
- package/skills/core/shaper-release/SKILL.md +17 -0
- package/skills/game/shaper-idle-game/SKILL.md +16 -0
- package/skills/manifest.json +18 -0
- package/templates/cloud-service/README.md +32 -0
- package/templates/cloud-service/cloud.json +30 -0
- package/templates/cloud-service/handlers.cjs +46 -0
- package/templates/cloud-service/migrations/202610250001_init.sql +5 -0
- package/templates/cloud-service/migrations/202610250002_events.sql +8 -0
- package/templates/h5/docs/design.md +3 -0
- package/templates/h5/docs/product.md +3 -0
- package/templates/h5/docs/validation.md +3 -0
- package/templates/h5/index.html +24 -0
- package/templates/h5/package-lock.json +828 -0
- package/templates/h5/package.json +15 -0
- package/templates/h5/public/.gitkeep +0 -0
- package/templates/h5/shaper.config.json +7 -0
- package/templates/h5/src/main.js +7 -0
- package/templates/h5/src/style.css +21 -0
- package/templates/h5/vite.config.js +4 -0
- package/templates/phaser/docs/design.md +3 -0
- package/templates/phaser/docs/product.md +3 -0
- package/templates/phaser/docs/validation.md +3 -0
- package/templates/phaser/index.html +2 -0
- package/templates/phaser/package-lock.json +1287 -0
- package/templates/phaser/package.json +19 -0
- package/templates/phaser/public/.gitkeep +0 -0
- package/templates/phaser/shaper.config.json +7 -0
- package/templates/phaser/src/game/create-game.ts +5 -0
- package/templates/phaser/src/game/rules/scoring.ts +2 -0
- package/templates/phaser/src/game/scenes/PlayScene.ts +15 -0
- package/templates/phaser/src/main.ts +4 -0
- package/templates/phaser/src/styles.css +1 -0
- package/templates/phaser/tsconfig.json +21 -0
- package/templates/phaser/vite.config.ts +4 -0
- package/templates/react/docs/design.md +3 -0
- package/templates/react/docs/product.md +3 -0
- package/templates/react/docs/validation.md +3 -0
- package/templates/react/index.html +2 -0
- package/templates/react/package-lock.json +1329 -0
- package/templates/react/package.json +22 -0
- package/templates/react/public/.gitkeep +0 -0
- package/templates/react/shaper.config.json +7 -0
- package/templates/react/src/app/App.tsx +5 -0
- package/templates/react/src/app/styles.css +1 -0
- package/templates/react/src/main.tsx +6 -0
- package/templates/react/tsconfig.json +21 -0
- package/templates/react/vite.config.ts +4 -0
- package/vendor/cloud-server/hupu-cloud-server-0.1.0.tgz +0 -0
- package/vendor/cloud-server/release.json +12 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-backend
|
|
3
|
+
description: 设计和实现 Shaper 后端接口、数据模型、身份权限与事务;维护云函数、数据库、网关并确认迁移部署结果。网页交付使用 shaper-release。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 后端开发
|
|
7
|
+
|
|
8
|
+
先读 docs/product.md 的规则、docs/design.md 的接口与数据约定,以及当前后端实现。没有保存共享状态或权威判定需求时,不为了完整性引入后台。
|
|
9
|
+
|
|
10
|
+
- 按用户操作定义请求、响应、身份前提和失败行为;前后端共用同一契约,不从 UI 字段直接推导可信输入。
|
|
11
|
+
- 数据模型说明所有者、唯一约束、索引和生命周期;次数、余额或奖励等不变量由数据库事务与约束保证,不能只靠前端禁用按钮。
|
|
12
|
+
- 写请求按业务要求设计幂等;区分未提交、已提交与结果未知。重试不得重复发奖或扣减。
|
|
13
|
+
- 迁移优先增量兼容当前线上代码;破坏性修改说明影响与恢复方案。源码、网关与迁移分别维护,验证记录写 docs/validation.md,技术取舍写 docs/design.md。
|
|
14
|
+
|
|
15
|
+
需要实际云操作时,先用 `shaper_status(workspace)` 确认应用绑定与账号。缺少云权限时用 `shaper_auth_start(cloud: true)`;缺少已有应用权限时同时传 appId。授权 complete 后继续,pending 才等待网页确认。
|
|
16
|
+
|
|
17
|
+
## 后台服务
|
|
18
|
+
|
|
19
|
+
1. 用 `hupu_cloud_status` 查看工程所绑定应用的云状态和当前发布。一个应用拥有一套云资源,不提供测试/生产环境或规格选择。未开通时用 `hupu_cloud_enable`;通过 hupu_cloud_status 确认资源 ready 再继续。已就绪时直接复用。历史资源绑定冲突由平台修复,不能通过换应用或新建资源绕过。
|
|
20
|
+
2. 用 `hupu_cloud_init` 生成本地 `cloud/functions/api`。目录已存在就继续编辑。业务使用 `defineHandlers`,接收 `{request,user,db,requestId}`;数据归属和业务权限由 handler 校验。
|
|
21
|
+
3. 有数据库变更时,用 `hupu_cloud_database_migrate` 提交版本化 SQL;提交返回 operationId 后用 hupu_cloud_operation 查询;只有返回 succeeded,才能发布依赖这些结构的代码;queued/running 仅表示受理或执行中,查询原 operationId,不能换幂等键重复提交。已应用版本不修改 SQL。
|
|
22
|
+
4. 用 `hupu_cloud_deploy` 发布源码目录;默认自动构建。只有需要检查或复用制品才单独用 `hupu_cloud_build`。CI 可向同一个 deploy 工具传 manifestFile 和 bundleFile,两者成对且与 directory 互斥。
|
|
23
|
+
5. 用 `hupu_cloud_status` 核对当前 release.digest 与部署 operation 的 result.digest 一致,并用 `hupu_cloud_routes` 检查生效路由,再验证公开接口和登录接口的真实行为。queued/running 不表示发布完成;失败或结果不明时报告实际状态,用 hupu_cloud_operation 查询原结果;明确失败才分析原因,不自动换键绕过。
|
|
24
|
+
|
|
25
|
+
一个应用只有一份活动后台服务;更换源码目录部署会替换整个服务。新工程的运行配置在 cloud/functions/api/cloud.json,路由和 public/user 策略在 cloud/gateway/routes.json,迁移在 cloud/database/migrations。构建组合唯一部署 manifest;旧工程保留原 cloud.json 合并布局。`hupu_cloud_routes` 只检查已生效的配置。
|
|
26
|
+
|
|
27
|
+
HTTP 业务请求由浏览器 SDK 直接访问厂商网关。开发者 OAuth 只用于管理;正式玩家身份由平台接入,不能用自报 PUID 代替。SDK 不自动提供行级数据授权。
|
|
28
|
+
|
|
29
|
+
目录、事务及命令示例见 [标准 Node 后台服务](references/node-server.md)。SDK 不兼容或 Cloud 未开放时报告实际错误;网页发布联动、FC、新版日志和对象存储尚未接入。
|
|
30
|
+
|
|
31
|
+
## 存量应用
|
|
32
|
+
|
|
33
|
+
明确维护旧事件函数、旧数据库查询或私有存储时,读取 [存量维护流程](references/legacy.md)。需要显式启用 legacy MCP 工具;旧功能不能用于操作新版应用云资源。
|
|
34
|
+
|
|
35
|
+
已有线上应用更新后台前说明影响并取得用户确认,新接口与迁移须兼容当前线上页面。云开通前说明实际用途、已知费用和配额,未知费用不能承诺免费。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# 存量事件函数维护
|
|
2
|
+
|
|
3
|
+
只在明确维护旧执行器环境时使用本流程。启动 MCP 时添加 `--legacy-cloud`;CLI 对应 `shaper legacy cloud`。这些环境、函数和任务与新版 Cloud 独立。新环境使用主技能中的标准服务流程。
|
|
4
|
+
|
|
5
|
+
先用 `shaper_status(workspace)` 确认应用和账号,再读 `hupu_legacy_cloud_capabilities`。授权缺少云权限时使用 `shaper_auth_start(cloud: true)`,只追加权限并保留已有应用访问;若同时缺少目标应用权限,传该应用的 `appId`。返回 `complete` 可继续,返回 `pending` 才等待网页确认。环境属于当前授权的 Shaper 应用,操作前确认项目绑定,所有云操作通过 Shaper MCP 完成。
|
|
6
|
+
|
|
7
|
+
## 环境
|
|
8
|
+
|
|
9
|
+
`hupu_legacy_cloud_environments` 列出现有环境。需要开通时用 `hupu_legacy_cloud_create`;要求 PostgreSQL 时同时传 `postgres: true`。开通由虎扑云统一处理,使用 Shaper 网页授权和当前应用绑定。按用户已经授权的资源范围执行,不重复确认同一开通请求;需要扩大资源或费用范围时再说明。
|
|
10
|
+
|
|
11
|
+
创建返回 `creating` 仅表示已受理。调用 `hupu_legacy_cloud_status`,直到真实状态为 `ready` 才部署依赖它的资源。创建结果不确定时查询状态,不另起名字再次创建。
|
|
12
|
+
|
|
13
|
+
## 云函数
|
|
14
|
+
|
|
15
|
+
读取 capabilities 的 runtime、type 和 handler。当前实现支持事件函数,入口是 `index.js` 导出的 `main`:
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
exports.main = async (event) => ({ ok: true, message: event.message ?? 'Hello Hupu Cloud' });
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
使用 `hupu_legacy_cloud_function_deploy` 指定项目内函数目录。目录应是可直接运行的打包产物;外部依赖先打包,工具不会上传 `node_modules` 或在云端自动安装依赖。不要将平台管理 token 放入函数。
|
|
22
|
+
|
|
23
|
+
部署返回 `deploying` 后,用 `hupu_legacy_cloud_functions` 检查函数状态,直到 `ready`,再执行 `hupu_legacy_cloud_function_invoke` 验证真实返回,并查询 `hupu_legacy_cloud_function_logs` 排查错误。函数部署、调用、日志三项分别记录结果。
|
|
24
|
+
|
|
25
|
+
函数运行环境和日志由虎扑云部署流程自动配置。当前事件函数管理接口不等于浏览器运行时 API;网页访问已有 HTTP 业务接口时,使用 `hupu-business` 中的 `ColorboxAI.cloud.request`,由 SDK 内部处理玩家认证。HTTP 函数与路由配置目前沿用旧部署入口;管理凭证始终留在开发工具和服务端。
|
|
26
|
+
|
|
27
|
+
## 数据库
|
|
28
|
+
|
|
29
|
+
以 capabilities 返回的数据库引擎和方言编写 SQL,当前为 PostgreSQL;根据虎扑云支持的能力编写代码。使用 `hupu_legacy_cloud_database_query` 完成明确授权的建表、查询或变更。写操作支持幂等键;未知结果先核对,不盲目重跑。
|
|
30
|
+
|
|
31
|
+
验收需在同一环境执行建表、写入和查询,核对实际数据。只得到 API 受理或本地模拟响应不能报告云数据库可用。
|
|
32
|
+
|
|
33
|
+
## 对象存储
|
|
34
|
+
|
|
35
|
+
先检查 capabilities.storage.available;未启用时说明平台尚未开放此能力,不尝试自行改变套餐或借用其他应用的存储。
|
|
36
|
+
|
|
37
|
+
使用 `hupu_legacy_cloud_storage_list` 查询,返回 `nextCursor` 时继续分页。`hupu_legacy_cloud_storage_upload` 将工程内文件写入私有存储,同一个对象键会替换内容;`hupu_legacy_cloud_storage_download` 下载到工程内尚不存在的文件。单对象上限由 capabilities 给出。验收比较上传与下载文件的哈希。
|
|
38
|
+
|
|
39
|
+
`hupu_legacy_cloud_storage_delete` 只删除用户明确指定的对象。网页公开素材仍使用 Shaper 网页交付或已有虎扑上传能力;私有存储对象不自动变成公网 URL。
|
|
40
|
+
|
|
41
|
+
已有线上应用更新后台前说明影响并取得用户确认,新接口与迁移须兼容当前线上页面。云开通前说明实际用途、已知费用和配额,未知费用不能承诺免费。
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# 标准 Node 后台服务
|
|
2
|
+
|
|
3
|
+
源码由开发者工程管理:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
cloud/functions/api/
|
|
7
|
+
handlers.cjs # 可继续拆分为业务 modules,再从此入口导出 handlers
|
|
8
|
+
cloud.json # 精确 SDK 版本与运行参数
|
|
9
|
+
package.json # 精确依赖和 hupuCloud 构建设置
|
|
10
|
+
vendor/ # Toolkit 分发的 SDK 包,应随源码提交
|
|
11
|
+
README.md # 当前模板的操作步骤
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
网关在 `cloud/gateway/routes.json`,迁移在 `cloud/database/migrations/`;路由只维护一份。旧 `functions/api` 的合并 manifest 与 migrations 继续支持,不自动搬迁。
|
|
15
|
+
|
|
16
|
+
```js
|
|
17
|
+
const { defineHandlers } = require('@hupu/cloud-server');
|
|
18
|
+
exports.handlers = defineHandlers({
|
|
19
|
+
me: async ({ user, db }) => ({
|
|
20
|
+
rows: (await db.query('SELECT score FROM progress WHERE puid=$1', [user.puid])).rows,
|
|
21
|
+
}),
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`me` 声明为 user 路由后,网关先认证,SDK 提供可信 user。数据归属仍在 SQL/业务规则中明确限制。将客户端的 body.puid 当作当前用户会绕过业务授权。
|
|
26
|
+
|
|
27
|
+
事务使用 `await db.transaction(async tx => { await tx.query(...); ... })`,在 callback 内 await 所有操作;出错整笔回滚,不支持嵌套事务或事务外继续使用 tx。业务不自行创建池,不处理厂商 Token 或环境密钥。
|
|
28
|
+
|
|
29
|
+
本地命令与 MCP 对应:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
shaper cloud init cloud/functions/api
|
|
33
|
+
shaper cloud build cloud/functions/api
|
|
34
|
+
# 按生成的 README 完成云服务开通和迁移后:
|
|
35
|
+
shaper cloud deploy --directory cloud/functions/api
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
之后修改 cloud/functions/api 中的源码和声明,再执行 deploy。构建目录位于 `.shaper/cloud-build/<digest>`,不是源码目录。Toolkit 内置 SDK 包可支持未发布 registry 的开发流程;安装业务第三方依赖时使用函数目录的 package.json,提交锁文件。
|
|
39
|
+
|
|
40
|
+
默认模板的进度和排行榜是教学业务;正式应用需替换展示资料和计分逻辑。SDK 统一的是 Node HTTP、用户上下文和 PostgreSQL 协议访问;当前只有 CloudBase 适配器完成,支持情况由工具内部检查,开发者无需选择厂商或规格。
|
|
41
|
+
|
|
42
|
+
异步返回 queued/running 仅表示受理或执行中。开通以 cloud status 的 ready 为准;发布以当前 release.digest 和接口验证为准。使用 `shaper cloud operation <operationId>` 或 `hupu_cloud_operation` 查询原任务,迁移 succeeded 后才执行依赖变更。未知结果不换键重发。
|
|
43
|
+
|
|
44
|
+
已有线上应用更新后台前说明影响并取得用户确认,新接口与迁移须兼容当前线上页面。云开通前说明实际用途、已知费用和配额,未知费用不能承诺免费。
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-design
|
|
3
|
+
description: 设计 Shaper 页面与游戏界面的信息层级、交互反馈、视觉和移动适配;输出实现依据,业务规则以项目产品文档为准。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 体验设计
|
|
7
|
+
|
|
8
|
+
读取 docs/product.md 和现有 docs/design.md;已有产品设计系统、页面和素材优先作为约束。先确定用户在每个页面最重要的动作,再安排信息与操作。
|
|
9
|
+
|
|
10
|
+
- 描述进入、主要操作、完成后的去向;只为实际存在的异步行为设计加载、空、错误、成功和恢复状态。
|
|
11
|
+
- 先确定信息层级、布局和视觉方向,再细化字体、颜色、间距、按钮、焦点与窄屏布局。简约不能删除必要反馈,也不靠增加卡片和说明填满页面。
|
|
12
|
+
- 游戏的 HUD、暂停和结算服务于玩法;玩法数值与胜负规则由产品及游戏实现共同维护,不在视觉稿中暗改。
|
|
13
|
+
- 列出需要的真实素材、用途、尺寸和来源约束;没有素材时明确占位,不把文字块当成完成稿。新增运行素材的来源记录在 docs/assets.md。
|
|
14
|
+
- 将交互与视觉依据写入 docs/design.md 的体验部分;发现业务缺口回到 docs/product.md 同步,不维护另一套规则。
|
|
15
|
+
|
|
16
|
+
完成结果应能让实现者知道主要布局、状态变化和适配方式;说明已展示的设计与尚未验证的交互。仅设计请求不擅自部署或重做工程。
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-development
|
|
3
|
+
description: 检查新旧 Shaper 项目的归属,初始化或关联应用,继续开发及排查本地预览。用于 Shaper 工程开发;网页交付使用 shaper-release,云资源使用 shaper-backend。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Shaper 本地开发
|
|
7
|
+
|
|
8
|
+
工具全局安装,代码属于普通本地项目。初始化前先检查归属;网页提示词里的 App ID 只是期望接入的目标,不是覆盖本地绑定的授权。
|
|
9
|
+
|
|
10
|
+
## 初始化前检查
|
|
11
|
+
|
|
12
|
+
1. 确定用户要操作的绝对目录,调用 `shaper_status`。MCP 启动目录不能代替项目目录。目录不存在时先确认路径与新建意图;不要为执行状态查询提前创建工程。
|
|
13
|
+
2. 用文件工具读取 `.shaper/project.json`(若存在)、项目说明和明确的旧应用配置,核对原 App ID 与服务地址。不要把 SDK 示例、依赖或测试数据中的 ID 当作项目身份;避免读取或输出凭据。
|
|
14
|
+
3. 检查是否有源码,以及 `package.json`、锁文件、原构建配置和 `shaper.config.json`。记录真实启动命令、构建命令、产物目录。没有新规范配置不代表空项目;构建方式不明时先调查或询问。
|
|
15
|
+
4. 按下表确定目标。目标和权限明确前,保持工程文件与绑定不变。
|
|
16
|
+
|
|
17
|
+
| 检查结果 | 下一步 |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| 已有绑定,无指定目标或目标相同 | 验证原应用权限,直接继续开发;仅确需补缺时再调用 init |
|
|
20
|
+
| 本地绑定或明确旧 App ID 与网页目标不同 | 展示两个应用的名称和 ID,停止初始化;引导进入原应用,不自动更换绑定 |
|
|
21
|
+
| 找到明确旧 App ID,目标一致或未指定 | 验证原应用后显式传 `appId` 接入,不创建应用 |
|
|
22
|
+
| 空目录,已指定目标 | 使用 `appId` 初始化;若尚未创建,浏览器确认创建并授权 |
|
|
23
|
+
| 空目录,明确要求新作品 | init 保存预分配 ID,经浏览器确认创建并授权后初始化 |
|
|
24
|
+
| 已有源码,归属无法确定或多个候选 | 询问“继续哪个已有应用,还是将这份代码作为新应用”;网页参数本身不能代替确认 |
|
|
25
|
+
|
|
26
|
+
空目录且明确新建作品时可省略 `appId`,工具会持久化预分配 ID。已有源码必须先确定目标;无法确定时请用户选择原应用或从网页开始新的作品,再携带网页 ID。普通初始化不执行 `shaper_link`;用户明确要求更换关联时,先核对原应用、目标和影响。
|
|
27
|
+
## 授权与接入
|
|
28
|
+
|
|
29
|
+
- 登录由同一台电脑、同一服务下的所有项目和 Agent 共用,不按聊天重新登录。调用 `shaper_auth_start` 后,`status: complete` 表示已复用登录;仅在 `pending` 时展示网页链接并使用 `flowId` 查询 `shaper_auth_status`。
|
|
30
|
+
- 已有应用缺少授权:调用 `shaper_auth_start(appId: 应用ID)`;需要手动补充其他范围时传 `reauthorize: true`。网页确认会追加权限,已有应用权限保留。拒绝或超时不清除原登录。
|
|
31
|
+
- 项目始终按传入绝对目录的 `.shaper/project.json` 定位,不能使用最近操作的应用或 MCP 启动目录兜底。`binding.authorized: false` 时先处理对应权限错误,不重新创建应用。
|
|
32
|
+
- 网页账号与本机账号不一致时,切回原账号。只有用户明确要求切换全局账号时才执行 `shaper_logout` 再登录;退出会影响当前服务的全部本地项目。
|
|
33
|
+
|
|
34
|
+
目标确定后直接调用 init,由工具检查授权和应用存在性。预分配 ID 尚不是应用,不单独对它执行 `shaper_auth_start`:
|
|
35
|
+
|
|
36
|
+
- 返回 `awaiting_confirmation`:展示 `authorizationUrl`,用 `flowId` 查询 `shaper_auth_status`。登录和创建/关联确认在同一浏览器流程完成;完成后用原目录、原参数再次 init。拒绝、失败或超时保持原状态,不改 ID 重试。CLI init 会等待浏览器回调后继续。
|
|
37
|
+
- `AUTH_IN_PROGRESS`:先完成返回的 flowId 对应授权,再重试,不发起并行登录。
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
- 新目录:调用 `shaper_init(workspace, name, template, appId?)`。根据需求选择 h5、react 或 phaser;指定已有应用时必须传 `appId`。
|
|
41
|
+
- 旧工程:使用已确定的应用 ID 初始化;新作品使用网页预分配 ID。保留原目录、包管理器和构建方式,不强制搬入 src 或换成 Vite。核对并补齐缺失配置,不覆盖已有文档或用户配置。当前工具可能生成默认构建命令,接入后必须与预先识别的原工程命令核对并调整。
|
|
42
|
+
- 中断或失败:检查已有绑定和原请求状态后继续;保留已创建应用的 ID,不删除状态、换名字或改目录来重新创建。不确定原创建结果时先核实。
|
|
43
|
+
- 完成条件:`shaper_status` 确认绑定目标及权限,`shaper_check` 检查配置,再构建验证。需要运行验证时启动本地预览;分别说明已验证和未验证项。失败则报告“已关联,但构建/预览待修复”,不宣称完整接入成功。
|
|
44
|
+
- 返回应用名称、关联结果和可验证的应用入口。后续上传使用同一应用,不能再引导用户从网页新建另一个应用。
|
|
45
|
+
|
|
46
|
+
## 继续开发
|
|
47
|
+
|
|
48
|
+
用 Agent 自带的文件工具编写项目。`shaper_dev_start` 返回就绪 URL 后,在浏览器检查用户实际会用的交互、控制台错误和窄屏布局。开发日志用 `shaper_dev_logs`。停止服务用 `shaper_dev_stop`;状态查询不会重启服务。
|
|
49
|
+
|
|
50
|
+
项目绑定位于 `.shaper/project.json`,仅包含服务 origin 和应用 ID,默认忽略提交。可提交 `shaper.config.json` 和依赖锁文件。授权存放在用户配置目录的 credentials 文件中,由工具管理;不要读取、展示、复制这些凭证到对话或工程。技能和工程中不放 token、云密钥或复制来的登录态。
|
|
51
|
+
|
|
52
|
+
`shaper_check` 只检查配置。交付前执行 `shaper_build`,同时完成浏览器行为检查。报告构建、页面行为和真实虎扑容器能力分别验证到了哪一步。普通浏览器没有虎扑桥接时,界面应解释不可用,不能伪造已登录。
|
|
53
|
+
|
|
54
|
+
新官方模板统一维护 docs/product.md、docs/design.md 和 docs/validation.md;旧工程只补缺失文档,不搬迁或覆盖源码。React 按业务组织组件,状态靠近使用者;异步操作具有失败反馈与重复提交保护。不默认添加路由、全局状态或大型 UI 库。
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-game-development
|
|
3
|
+
description: 细化并实现游戏玩法、最小可玩原型、场景与资源,进行试玩和调优;适用于独立游戏或活动中的游戏环节。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 游戏制作
|
|
7
|
+
|
|
8
|
+
读 docs/product.md 的目标与规则、docs/design.md 的体验及现有游戏代码。已有引擎沿用;需要创建或接入工程时先按 shaper-development 完成归属与授权检查;新 2D 游戏可用 shaper_init 的 phaser 模板,页面式玩法可用 React,不默认混用引擎。
|
|
9
|
+
|
|
10
|
+
1. 明确核心循环、输入、反馈、胜负和重玩条件,先做一条可玩的完整循环;不先建设通用游戏框架。
|
|
11
|
+
2. 场景负责生命周期和编排;计分、胜负、成长规则与引擎对象分离。资源 key/路径集中管理,加载失败能解释和恢复。
|
|
12
|
+
3. 清理离开场景时的事件与计时器;重玩和热更新不重复创建实例。明确切后台是否计时,手动暂停不得被自动恢复覆盖;声音由用户手势开启。
|
|
13
|
+
4. 试玩检查输入响应、边界、失败与重玩、不同屏幕、持续运行;按实际设备记录帧率或卡顿依据。根据观察调整节奏和反馈,不凭截图宣称好玩。
|
|
14
|
+
5. 更新 docs/design.md 的玩法实现与取舍、docs/validation.md 的实际试玩结论及未验证项。
|
|
15
|
+
|
|
16
|
+
离线成长、自动产出或离线结算可使用独立的 shaper-idle-game 技能(未安装时按需求补充,不阻断普通游戏)。奖励、排行榜等可信状态需要 shaper-backend;壳身份和分享由 hupu-business 接入。工程和预览复用 shaper-development,网页交付由 shaper-release 处理。
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-product
|
|
3
|
+
description: 规划 Shaper 产品的目标、用户流程、业务规则和一期范围,定义可检查的验收条件;不代替体验设计或代码实现。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 产品规划
|
|
7
|
+
|
|
8
|
+
先读现有 docs/product.md;从用户当前目标补充信息,不从模板推导业务。小修改只更新受影响规则。
|
|
9
|
+
|
|
10
|
+
1. 明确为谁解决什么问题、用户从哪里进入、如何完成主要目标。活动与游戏可组合,不按类型强迫二选一。
|
|
11
|
+
2. 写清主流程、必要分支、数据归属与完成条件。参与资格、奖励、次数、排行榜只有需求需要时才设计;缺失且影响实现的规则才询问用户。
|
|
12
|
+
3. 区分本期、后续与不做;每项本期能力给出可观察的验收条件。记录假设,不把假设标为已确认。
|
|
13
|
+
4. 将结果维护在 docs/product.md。已有约定优先复用;不另外生成重复 PRD 或任务系统。
|
|
14
|
+
|
|
15
|
+
涉及虎扑生态时读取 [能力用途](references/ecosystem.md)。承诺能力前查询当前应用实际支持情况;无法核实时写明限制。体验实现交给 shaper-design,网页/游戏/后端按实际任务组合对应技能,不自动启动完整流程。
|
|
16
|
+
|
|
17
|
+
完成时说明目标、主流程、范围和未确定的关键规则;纯产品请求以方案结束,不自行创建应用或部署。
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# 生态能力用途
|
|
2
|
+
|
|
3
|
+
| 能力 | 产品用途 | 前提与实现职责 |
|
|
4
|
+
| --- | --- | --- |
|
|
5
|
+
| 玩家身份 | 保存个人进度、区分用户数据 | hupu-business 接入真实玩家会话;shaper-backend 校验数据归属。普通浏览器不保证壳能力可用 |
|
|
6
|
+
| 分享 | 用户主动传播当前内容 | hupu-business 核对当前 SDK 和容器支持;分享成功不等于被其他人打开 |
|
|
7
|
+
| 后台与数据库 | 多人共享状态、跨设备保存、可信规则 | shaper-backend 核对云权限、资源及费用;客户端结果不能直接成为奖励依据 |
|
|
8
|
+
| 预览与提审 | 试用并交付版本 | shaper-release;上传、提审、上线是不同状态 |
|
|
9
|
+
|
|
10
|
+
社区发帖、消息、分发推荐和奖励发放不在已确认接入范围。需要时先核实接口与权限,不按生态归属臆造能力。
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-release
|
|
3
|
+
description: 将 Shaper 网页工程构建、上传预览并提交发布审核,检查交付结果。云函数部署由 shaper-backend 处理。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Shaper 网页交付
|
|
7
|
+
|
|
8
|
+
调用 `shaper_status(workspace)` 确认当前账号、服务和应用绑定。已有用户明确要求部署或提交审核时直接完成已授权流程。
|
|
9
|
+
|
|
10
|
+
1. 用 `shaper_web_deploy` 构建并上传网页代码。它复用 Shaper 版本、内容校验和预览服务。检查操作 `status`、校验结果、`versionId` 与预览信息;上传成功并不代表应用已发布。
|
|
11
|
+
2. 打开返回的预览地址验证页面。需要虎扑登录或分享时,在实际 Shaper/虎扑容器中检查对应能力;本地浏览器检查作为独立证据。
|
|
12
|
+
3. 用户要求发布时,调用 `shaper_web_publish`,提供 `versionId` 和说明;可选工程内的 `coverPath`(PNG/JPEG/WebP,最大 2 MiB)。工具保存资料并打开浏览器确认页。用户可在那里补封面、修改应用资料并点击提交审核。
|
|
13
|
+
4. 返回的 operation succeeded 只表示确认页已准备好;`result.status: awaiting_confirmation` 和 `submitted: false` 表示尚未提审。展示确认链接,等待用户在浏览器操作;再调用 `shaper_status(workspace)` 查询 `project.binding.versions` 中同一版本的状态,只有 submitted/in_review/security_review 才报告“已提交审核”,published 才报告“已发布”。取消或关闭页面不会提交,也不需要新建应用或上传另一个版本。
|
|
14
|
+
|
|
15
|
+
网络超时、`running` 或 `uncertain` 时,由平台核对原请求记录。不要为了绕过未确认结果重复创建应用或提交。`uncertain` 需要根据服务端记录核对,不能把它当作失败后自动重发。
|
|
16
|
+
|
|
17
|
+
云函数、数据库和存储属于虎扑云;网页仍走本技能的 Shaper 交付流程。交付包包含构建产物,排除凭证、`.env` 和本地绑定。构建配置决定包内文件,不通过上传整个源仓库绕过构建。
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: shaper-idle-game
|
|
3
|
+
description: 设计与实现离线养成、自动产出和离线收益结算;处理时钟、存档兼容和数值增长,不负责通用工程初始化。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 离线养成
|
|
7
|
+
|
|
8
|
+
这是可独立安装的专业技能,不要求所有游戏加载。读取项目已有玩法规则、存档结构与验证记录。
|
|
9
|
+
|
|
10
|
+
- 明确资源产出、消耗、上限与成长节奏;先写可解释的小规模数值模型,不擅自增加付费、签到或排行榜。
|
|
11
|
+
- 将在线累计和离线结算统一为可重复计算的规则。结算以已提交的时间点为基准,成功保存后推进时间点;处理时钟倒退、超长离线和重复恢复,不允许重复领取。
|
|
12
|
+
- 本地时间与存档不可信。纯离线单机可接受可修改存档;涉及奖品或共享经济时由后端权威时间和事务结算,不能靠前端限制防作弊。
|
|
13
|
+
- 存档包含版本,迁移保留原数据直至新版本保存成功;损坏或不可识别版本提供明确恢复方式,不静默清空。
|
|
14
|
+
- 检查零收益、上限、时间回拨、长时间离线、刷新与重复恢复;将实际结果写入 docs/validation.md。未验证的平台存储和后台生命周期明确列出。
|
|
15
|
+
|
|
16
|
+
完成时给出规则、可运行结算、存档兼容策略及边界验证结果。
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"default": [
|
|
4
|
+
"core/hupu-business",
|
|
5
|
+
"core/shaper-backend",
|
|
6
|
+
"core/shaper-design",
|
|
7
|
+
"core/shaper-development",
|
|
8
|
+
"core/shaper-game-development",
|
|
9
|
+
"core/shaper-product",
|
|
10
|
+
"core/shaper-release"
|
|
11
|
+
],
|
|
12
|
+
"optional": [
|
|
13
|
+
"game/shaper-idle-game"
|
|
14
|
+
],
|
|
15
|
+
"compatibility": [
|
|
16
|
+
"compat/hupu-cloud"
|
|
17
|
+
]
|
|
18
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Node 后台服务
|
|
2
|
+
|
|
3
|
+
此目录是该应用一个 HTTP 后台服务的源码,可包含多个路由。持续修改这里,再重新构建发布;无需重复开通云资源。当前一个应用管理一份活动 HTTP 发布,新目录不会自动变成第二个独立服务。
|
|
4
|
+
|
|
5
|
+
- `handlers.cjs`:业务代码,使用 `defineHandlers({ handler: async ({request,user,db}) => ... })`。
|
|
6
|
+
- `cloud.json`:SDK 精确版本、Node 运行参数、路由和 public/user 访问规则。
|
|
7
|
+
- `migrations/`:版本化 PostgreSQL 迁移;已应用文件不能修改,变更另加新版本。
|
|
8
|
+
- `vendor/`:随 Toolkit 分发的官方 SDK 包;跟随源码提交,不含凭证。`npm install --ignore-scripts` 可获得编辑器补全;默认示例构建不需要先安装 SDK。
|
|
9
|
+
|
|
10
|
+
从开发者工程根目录操作(目录不是 functions/api 时替换路径):
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
shaper cloud enable
|
|
14
|
+
shaper cloud status # 确认 ready 后继续
|
|
15
|
+
shaper cloud db migrate --version 202610250001_init --file functions/api/migrations/202610250001_init.sql
|
|
16
|
+
# 确认上一迁移已生效后继续
|
|
17
|
+
shaper cloud db migrate --version 202610250002_events --file functions/api/migrations/202610250002_events.sql
|
|
18
|
+
# 确认迁移已生效后部署
|
|
19
|
+
shaper cloud deploy --directory functions/api
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
以后修改 handlers/cloud.json,直接再次 deploy;新增表字段先迁移。build 和 deploy 自动构建 CommonJS、打包第三方纯 JS 依赖,并外置平台 SDK。它们不执行任意 npm build 脚本,也不自动运行数据库迁移。增加第三方依赖后在本目录安装,提交锁文件;动态依赖、原生二进制及额外资源文件不属于这版单 bundle 部署契约。
|
|
23
|
+
|
|
24
|
+
鉴权在云厂商网关执行。user 路由中的 `user.puid` 可信;public 路由没有 user。业务不读取身份头、Token、PG 环境变量,不创建连接池。Java 控制面绑定应用资源,Hupu 不代理业务 HTTP 或 SQL。
|
|
25
|
+
|
|
26
|
+
`db.query(sql, values)` 使用参数化 SQL。`db.transaction(async tx => {...})` 内必须 await 全部操作;真实 PG 事务固定一个连接,失败回滚,不自动重试、不支持嵌套。数据归属、业务角色、分数校验仍由业务实现;SDK 不会自动加用户过滤或 RLS。
|
|
27
|
+
|
|
28
|
+
初始示例包含排行榜和个人进度,仅用于演示:公开榜单返回测试 PUID,正式业务应改成展示资料;自报分数不具备防作弊能力。重复 submissionId 返回 409 且整笔回滚;未提供时使用请求 ID,因此网络重试不保证去重。
|
|
29
|
+
|
|
30
|
+
cloud.json 是路由声明的源文件,修改后通过 cloud deploy 随服务发布。需要检查或复用制品时,可单独执行 cloud build functions/api。
|
|
31
|
+
|
|
32
|
+
异步返回 queued/running 仅表示受理或执行中。开通以 cloud status 的 ready 为准;发布以当前 release.digest 和接口验证为准。迁移暂未提供独立完成查询,未收到 succeeded 时需由平台确认已生效后再执行依赖变更。失败恢复本轮不提供。
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"runtime": "nodejs20",
|
|
4
|
+
"memoryMB": 256,
|
|
5
|
+
"timeoutSeconds": 15,
|
|
6
|
+
"routes": [
|
|
7
|
+
{
|
|
8
|
+
"method": "GET",
|
|
9
|
+
"path": "/api/leaderboard",
|
|
10
|
+
"access": "public",
|
|
11
|
+
"handler": "leaderboard"
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
"method": "GET",
|
|
15
|
+
"path": "/api/me",
|
|
16
|
+
"access": "user",
|
|
17
|
+
"handler": "me"
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"method": "POST",
|
|
21
|
+
"path": "/api/progress",
|
|
22
|
+
"access": "user",
|
|
23
|
+
"handler": "progress"
|
|
24
|
+
}
|
|
25
|
+
],
|
|
26
|
+
"serverSdk": {
|
|
27
|
+
"name": "@hupu/cloud-server",
|
|
28
|
+
"version": "0.1.0"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const { defineHandlers } = require("@hupu/cloud-server");
|
|
4
|
+
|
|
5
|
+
exports.handlers = defineHandlers({
|
|
6
|
+
// public 路由没有 user。示例仅使用测试账号,正式榜单应返回展示名而非 PUID。
|
|
7
|
+
leaderboard: async ({ db }) => ({
|
|
8
|
+
rows: (await db.query("SELECT puid,score FROM progress ORDER BY score DESC,puid LIMIT 10")).rows,
|
|
9
|
+
}),
|
|
10
|
+
|
|
11
|
+
me: async ({ user, db }) => ({
|
|
12
|
+
puid: user.puid,
|
|
13
|
+
rows: (await db.query("SELECT score FROM progress WHERE puid=$1", [user.puid])).rows,
|
|
14
|
+
}),
|
|
15
|
+
|
|
16
|
+
progress: async ({ request, requestId, user, db }) => {
|
|
17
|
+
let input;
|
|
18
|
+
try { input = await request.json(); } catch {
|
|
19
|
+
return Response.json({ code: "INVALID_JSON" }, { status: 400 });
|
|
20
|
+
}
|
|
21
|
+
if (!input || !Number.isSafeInteger(input.score) || input.score < 0 || input.score > 1000000) {
|
|
22
|
+
return Response.json({ code: "INVALID_SCORE" }, { status: 400 });
|
|
23
|
+
}
|
|
24
|
+
const submissionId = input.submissionId ?? requestId;
|
|
25
|
+
if (typeof submissionId !== "string" || !/^[a-zA-Z0-9_-]{1,64}$/.test(submissionId)) {
|
|
26
|
+
return Response.json({ code: "INVALID_SUBMISSION_ID" }, { status: 400 });
|
|
27
|
+
}
|
|
28
|
+
try {
|
|
29
|
+
// 两次写入在同一 PG 事务;业务归属始终来自网关身份,不读取 body.puid。
|
|
30
|
+
return await db.transaction(async tx => {
|
|
31
|
+
const result = await tx.query(
|
|
32
|
+
"INSERT INTO progress(puid,score) VALUES($1,$2) ON CONFLICT(puid) DO UPDATE SET score=excluded.score RETURNING puid,score",
|
|
33
|
+
[user.puid, input.score],
|
|
34
|
+
);
|
|
35
|
+
await tx.query(
|
|
36
|
+
"INSERT INTO progress_events(puid,submission_id,score) VALUES($1,$2,$3)",
|
|
37
|
+
[user.puid, submissionId, input.score],
|
|
38
|
+
);
|
|
39
|
+
return { progress: result.rows[0] };
|
|
40
|
+
});
|
|
41
|
+
} catch (error) {
|
|
42
|
+
if (error.code === "23505") return Response.json({ code: "DUPLICATE_SUBMISSION" }, { status: 409 });
|
|
43
|
+
throw error; // SDK 统一脱敏,不能将数据库异常正文返回客户端。
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
});
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
-- 单独的增量迁移,不能修改已经发布的 init.sql 校验和。
|
|
2
|
+
CREATE TABLE progress_events (
|
|
3
|
+
puid text NOT NULL,
|
|
4
|
+
submission_id text NOT NULL,
|
|
5
|
+
score integer NOT NULL CHECK (score >= 0 AND score <= 1000000),
|
|
6
|
+
created_at timestamptz NOT NULL DEFAULT now(),
|
|
7
|
+
PRIMARY KEY (puid, submission_id)
|
|
8
|
+
);
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="zh-CN">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
6
|
+
<meta name="theme-color" content="#173b35" />
|
|
7
|
+
<title>我的 Shaper 应用</title>
|
|
8
|
+
</head>
|
|
9
|
+
<body>
|
|
10
|
+
<main>
|
|
11
|
+
<header><span class="brand">SHAPER</span><span class="tag">你的下一个想法,从这里开始</span></header>
|
|
12
|
+
<section>
|
|
13
|
+
<p class="eyebrow">HELLO, CREATOR</p>
|
|
14
|
+
<h1>把想法<br />变成可以玩的作品。</h1>
|
|
15
|
+
<p class="intro">这是你的应用起点。修改本地代码,立即预览,再通过 Shaper 交付给用户。</p>
|
|
16
|
+
<button id="play" type="button">点亮灵感 <span aria-hidden="true">↗</span></button>
|
|
17
|
+
<p id="status" role="status" aria-live="polite">已经准备好了。</p>
|
|
18
|
+
</section>
|
|
19
|
+
<aside aria-hidden="true"><div class="orb"><span>MAKE<br />SOMETHING<br /><em>YOURS.</em></span></div></aside>
|
|
20
|
+
<footer>本地开发 · Shaper 发布 · 按需接入虎扑服务</footer>
|
|
21
|
+
</main>
|
|
22
|
+
<script type="module" src="/src/main.js"></script>
|
|
23
|
+
</body>
|
|
24
|
+
</html>
|