@hupu-tech/shaper 0.2.11 → 0.2.13

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 (189) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +6 -0
  3. package/dist/cli.js +2 -2
  4. package/dist/cloud/client.d.ts +1 -2
  5. package/dist/cloud/service-build.d.ts +5 -7
  6. package/dist/index.js +1 -1
  7. package/dist/project/create.d.ts +9 -3
  8. package/dist/project/delivery.d.ts +5 -5
  9. package/dist/runtime.d.ts +2 -1
  10. package/dist/runtime.js +1 -1
  11. package/dist/shared-2WDEQ3AQ.js +19 -0
  12. package/package.json +1 -3
  13. package/skills/business/SKILL.md +158 -0
  14. package/skills/business/activity/README.md +14 -0
  15. package/skills/business/activity/hupu-leaderboard-template/SKILL.md +52 -0
  16. package/skills/business/activity/hupu-leaderboard-template/example/README.md +20 -0
  17. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/.cloudignore +3 -0
  18. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/index.js +218 -0
  19. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/package.json +15 -0
  20. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
  21. package/skills/business/activity/hupu-leaderboard-template/example/index.html +291 -0
  22. package/skills/business/activity/hupu-leaderboard-template/example/migrations/20260828210000_create_leaderboard.sql +54 -0
  23. package/skills/business/activity/hupu-lottery-draw/SKILL.md +50 -0
  24. package/skills/business/activity/hupu-lottery-draw/example/README.md +21 -0
  25. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/.cloudignore +3 -0
  26. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/index.js +142 -0
  27. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/package.json +9 -0
  28. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
  29. package/skills/business/activity/hupu-lottery-draw/example/index.html +178 -0
  30. package/skills/business/activity/hupu-lottery-draw/example/migrations/20260828220000_create_draw.sql +193 -0
  31. package/skills/business/activity/hupu-pk-voting/SKILL.md +54 -0
  32. package/skills/business/activity/hupu-pk-voting/example/README.md +44 -0
  33. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/.cloudignore +3 -0
  34. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/index.js +370 -0
  35. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/package.json +15 -0
  36. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/scf_bootstrap +2 -0
  37. package/skills/business/activity/hupu-pk-voting/example/index.html +729 -0
  38. package/skills/business/activity/hupu-pk-voting/example/migrations/20260828220000_create_pk_vote.sql +168 -0
  39. package/skills/business/activity/hupu-request-activity-execute-vote-task/SKILL.md +77 -0
  40. package/skills/business/activity/hupu-request-activity-get-vote-detail/SKILL.md +84 -0
  41. package/skills/business/activity/hupu-request-activity-get-vote-task-list/SKILL.md +86 -0
  42. package/skills/business/activity/hupu-request-activity-list-by-biz-keys/SKILL.md +153 -0
  43. package/skills/business/activity/hupu-request-activity-report-vote-task/SKILL.md +58 -0
  44. package/skills/business/activity/hupu-request-activity-submit-vote/SKILL.md +58 -0
  45. package/skills/business/activity/hupu-vote-task/SKILL.md +47 -0
  46. package/skills/business/community/README.md +13 -0
  47. package/skills/business/community/hupu-request-bbs-detail/SKILL.md +197 -0
  48. package/skills/business/community/hupu-request-bbs-get-tag-thread-list/SKILL.md +257 -0
  49. package/skills/business/community/hupu-request-bbs-get-topic-threads/SKILL.md +159 -0
  50. package/skills/business/community/hupu-request-bbs-gets-thread-post-list/SKILL.md +124 -0
  51. package/skills/business/community/hupu-request-bbs-open-post-editor/SKILL.md +75 -0
  52. package/skills/business/community/hupu-request-bbs-reply-post/SKILL.md +59 -0
  53. package/skills/business/community/hupu-score-add-score/SKILL.md +57 -0
  54. package/skills/business/community/hupu-score-get-item-detail/SKILL.md +173 -0
  55. package/skills/business/community/hupu-score-get-score/SKILL.md +263 -0
  56. package/skills/business/quality/README.md +7 -0
  57. package/skills/business/quality/hupu-security-check-audit/SKILL.md +39 -0
  58. package/skills/business/quality/hupu-wasm-compression/SKILL.md +69 -0
  59. package/skills/business/quality/hupu-wasm-compression/agents/openai.yaml +4 -0
  60. package/skills/business/quality/hupu-wasm-compression/tool/checks.mjs +90 -0
  61. package/skills/business/quality/hupu-wasm-compression/tool/compress-worker.mjs +40 -0
  62. package/skills/business/quality/hupu-wasm-compression/tool/public/app.js +84 -0
  63. package/skills/business/quality/hupu-wasm-compression/tool/public/index.html +80 -0
  64. package/skills/business/quality/hupu-wasm-compression/tool/public/style.css +3 -0
  65. package/skills/business/quality/hupu-wasm-compression/tool/server.mjs +126 -0
  66. package/skills/business/quality/hupu-web-security-audit/SKILL.md +45 -0
  67. package/skills/business/quality/hupu-web-security-audit/agents/openai.yaml +4 -0
  68. package/skills/business/rewards/README.md +13 -0
  69. package/skills/business/rewards/hupu-vacoin/SKILL.md +70 -0
  70. package/skills/business/rewards/hupu-vacoin-consume-coins/SKILL.md +47 -0
  71. package/skills/business/rewards/hupu-vacoin-get-coin-overview/SKILL.md +52 -0
  72. package/skills/business/rewards/hupu-vacoin-get-session-coins/SKILL.md +44 -0
  73. package/skills/business/rewards/hupu-vacoin-reset-session-id/SKILL.md +39 -0
  74. package/skills/business/rewards/hupu-vatask/SKILL.md +63 -0
  75. package/skills/business/rewards/hupu-vatask-complete-reward-video/SKILL.md +43 -0
  76. package/skills/business/rewards/hupu-vatask-consume-activity-chance/SKILL.md +48 -0
  77. package/skills/business/rewards/hupu-vatask-get-activity-task-state/SKILL.md +49 -0
  78. package/skills/business/runtime/README.md +13 -0
  79. package/skills/business/runtime/hupu-add-to-desktop/SKILL.md +51 -0
  80. package/skills/business/runtime/hupu-close-webview/SKILL.md +48 -0
  81. package/skills/business/runtime/hupu-cloud-auth/SKILL.md +43 -0
  82. package/skills/business/runtime/hupu-cloud-request/SKILL.md +56 -0
  83. package/skills/business/runtime/hupu-fullscreen-safe-top/SKILL.md +33 -0
  84. package/skills/business/runtime/hupu-navigate-to/SKILL.md +45 -0
  85. package/skills/business/runtime/hupu-request/SKILL.md +67 -0
  86. package/skills/business/runtime/hupu-seer-chat/SKILL.md +183 -0
  87. package/skills/business/runtime/hupu-track-report/SKILL.md +71 -0
  88. package/skills/business/sharing/README.md +7 -0
  89. package/skills/business/sharing/hupu-oss-upload-file/SKILL.md +40 -0
  90. package/skills/business/sharing/hupu-result-poster-posting/SKILL.md +37 -0
  91. package/skills/business/sharing/hupu-result-poster-posting/example/README.md +14 -0
  92. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/.cloudignore +3 -0
  93. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/index.js +187 -0
  94. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/package.json +15 -0
  95. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
  96. package/skills/business/sharing/hupu-result-poster-posting/example/index.html +256 -0
  97. package/skills/business/sharing/hupu-result-poster-posting/example/migrations/20260828213000_create_result_poster_results.sql +60 -0
  98. package/skills/business/sharing/hupu-result-poster-posting/references/api-contract.md +46 -0
  99. package/skills/business/sharing/hupu-social-share/SKILL.md +27 -0
  100. package/skills/business/sports/README.md +27 -0
  101. package/skills/business/sports/hupu-request-basketball-player-info/SKILL.md +131 -0
  102. package/skills/business/sports/hupu-request-basketball-single-match/SKILL.md +158 -0
  103. package/skills/business/sports/hupu-request-basketball-team-info/SKILL.md +96 -0
  104. package/skills/business/sports/hupu-request-basketball-team-player-list/SKILL.md +108 -0
  105. package/skills/business/sports/hupu-request-basketball-team-salary-info/SKILL.md +85 -0
  106. package/skills/business/sports/hupu-request-football-coach-info/SKILL.md +76 -0
  107. package/skills/business/sports/hupu-request-football-live-room-news-list/SKILL.md +85 -0
  108. package/skills/business/sports/hupu-request-football-match-info/SKILL.md +126 -0
  109. package/skills/business/sports/hupu-request-football-player-info/SKILL.md +82 -0
  110. package/skills/business/sports/hupu-request-football-team-info/SKILL.md +83 -0
  111. package/skills/business/sports/hupu-request-football-team-player-season-stats/SKILL.md +73 -0
  112. package/skills/business/sports/hupu-request-football-team-season-year/SKILL.md +68 -0
  113. package/skills/business/sports/hupu-request-kog-playbyplay/SKILL.md +77 -0
  114. package/skills/business/sports/hupu-request-live-tab-info-list/SKILL.md +85 -0
  115. package/skills/business/sports/hupu-request-live-tab-list/SKILL.md +66 -0
  116. package/skills/business/sports/hupu-request-lol-playbyplay/SKILL.md +77 -0
  117. package/skills/business/sports/hupu-request-match-get-tab-detail-schedule-list/SKILL.md +113 -0
  118. package/skills/business/sports/hupu-request-match-query-all-diagram-info-by-id/SKILL.md +79 -0
  119. package/skills/business/sports/hupu-request-match-query-match-stats-by-match-info/SKILL.md +85 -0
  120. package/skills/business/sports/hupu-request-news-news-common-list/SKILL.md +90 -0
  121. package/skills/business/sports/hupu-request-news-player-news-list/SKILL.md +79 -0
  122. package/skills/business/sports/hupu-request-news-subject-news/SKILL.md +89 -0
  123. package/skills/business/sports/hupu-request-news-team-news-list/SKILL.md +76 -0
  124. package/skills/business/storage/README.md +9 -0
  125. package/skills/business/storage/hupu-cloud-save/SKILL.md +129 -0
  126. package/skills/business/storage/hupu-cloud-save/references/legacy-migration.md +111 -0
  127. package/skills/business/storage/hupu-cloud-save-load/SKILL.md +41 -0
  128. package/skills/business/storage/hupu-cloud-save-save/SKILL.md +45 -0
  129. package/skills/business/storage/hupu-storage-get-value/SKILL.md +26 -0
  130. package/skills/business/storage/hupu-storage-set-value/SKILL.md +42 -0
  131. package/skills/business/user/README.md +6 -0
  132. package/skills/business/user/hupu-auth-get-user-info/SKILL.md +47 -0
  133. package/skills/business/user/hupu-game-auth/SKILL.md +46 -0
  134. package/skills/core/hupu-business/SKILL.md +1 -1
  135. package/skills/core/hupu-business/references/runtime.md +17 -11
  136. package/skills/core/shaper-backend/SKILL.md +1 -1
  137. package/skills/core/shaper-backend/references/database.md +2 -2
  138. package/skills/core/shaper-backend/references/legacy.md +1 -1
  139. package/skills/core/shaper-backend/references/node-server.md +29 -20
  140. package/skills/core/shaper-development/SKILL.md +5 -1
  141. package/skills/core/shaper-development/references/project-setup.md +1 -1
  142. package/skills/core/shaper-game-development/SKILL.md +1 -1
  143. package/skills/core/shaper-release/SKILL.md +1 -1
  144. package/templates/cloud-service/README.md +4 -30
  145. package/templates/cloud-service/cloud.json +6 -9
  146. package/templates/cloud-service/package-lock.json +1090 -0
  147. package/templates/cloud-service/release.json +11 -0
  148. package/templates/cloud-service/server.cjs +37 -0
  149. package/templates/h5/package-lock.json +40 -40
  150. package/templates/leaderboard/README.md +3 -0
  151. package/templates/leaderboard/cloud/database/migrations/202611130001_leaderboard.sql +6 -0
  152. package/templates/leaderboard/cloud/functions/api/cloud.json +10 -0
  153. package/templates/leaderboard/cloud/functions/api/leaderboard.cjs +49 -0
  154. package/templates/leaderboard/cloud/functions/api/package-lock.json +1093 -0
  155. package/templates/leaderboard/cloud/functions/api/package.json +19 -0
  156. package/templates/leaderboard/cloud/functions/api/server.cjs +25 -0
  157. package/templates/leaderboard/cloud/gateway/routes.json +15 -0
  158. package/templates/leaderboard/docs/design.md +1 -0
  159. package/templates/leaderboard/docs/integration.md +12 -0
  160. package/templates/leaderboard/docs/product.md +1 -0
  161. package/templates/leaderboard/docs/validation.md +1 -0
  162. package/templates/leaderboard/index.html +12 -0
  163. package/templates/leaderboard/package-lock.json +828 -0
  164. package/templates/leaderboard/package.json +17 -0
  165. package/templates/leaderboard/public/.gitkeep +1 -0
  166. package/templates/leaderboard/shaper.config.json +7 -0
  167. package/templates/leaderboard/src/main.js +67 -0
  168. package/templates/leaderboard/src/style.css +69 -0
  169. package/templates/leaderboard/test/leaderboard.test.cjs +93 -0
  170. package/templates/offline-game/README.md +3 -0
  171. package/templates/offline-game/docs/design.md +1 -0
  172. package/templates/offline-game/docs/integration.md +10 -0
  173. package/templates/offline-game/docs/product.md +1 -0
  174. package/templates/offline-game/docs/validation.md +1 -0
  175. package/templates/offline-game/index.html +1 -0
  176. package/templates/offline-game/package-lock.json +828 -0
  177. package/templates/offline-game/package.json +16 -0
  178. package/templates/offline-game/public/.gitkeep +1 -0
  179. package/templates/offline-game/shaper.config.json +7 -0
  180. package/templates/offline-game/src/game.js +11 -0
  181. package/templates/offline-game/src/main.js +12 -0
  182. package/templates/offline-game/src/style.css +1 -0
  183. package/templates/offline-game/test/game.test.js +7 -0
  184. package/templates/phaser/package-lock.json +70 -70
  185. package/templates/react/package-lock.json +74 -74
  186. package/dist/shared-F5CQJEWB.js +0 -19
  187. package/templates/cloud-service/handlers.cjs +0 -46
  188. package/vendor/cloud-server/hupu-cloud-server-0.1.0.tgz +0 -0
  189. package/vendor/cloud-server/release.json +0 -12
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: hupu-cloud-save-save
3
+ description: 将用户进度、草稿、选择或个人设置保存到指定云存档位;编号为 1–5,同编号完整覆盖。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.cloudSave.save(params)`
9
+
10
+ # Constraints
11
+
12
+ - 新接入首选 save/load;已有 getValue/setValue 应用可继续使用原接口,不强制迁移。决定切换时不能只替换方法名,应先处理旧 key 数据;用法与迁移见 hupu-cloud-save/SKILL.md
13
+ - 结合游戏或应用实际功能选择保存时机,接入云存档不代表需要自动保存;无恢复需求不保存,点击保存、确认步骤、完成关卡或检查点已足够时只按这些节点保存;仅长篇草稿、持续创作或需保护中途进度等功能按需启用持续自动保存,不扩展到其他功能,用户未确认的编辑不自动覆盖约定手动保存的正式存档
14
+ - 固定存档编号用途,读写使用相同编号;建议最多使用三个存档位,一起保存和恢复的小字段放同一对象,仅保存时机或加载需求独立时才拆分;同编号完整替换,不合并对象字段,共用对象提交完整有效快照,多个存档位保存不保证一起成功
15
+ - 按白名单只存无法可靠重建的用户内容、进度、选择和设置;已有数据优先存稳定 ID 及必要关系或顺序,详情恢复时重新获取,名称不能替代稳定 ID;必要正文完整保留。数据取舍与场景示例见 hupu-cloud-save/SKILL.md
16
+ - 不存整个 state/store、接口响应、派生值、静态配置、临时 UI 状态、日志、资源二进制或 Base64;资源成功上传后只存可恢复引用,历史限定范围,不保存 token、密码、Cookie
17
+ - 只在必需字段变化时保存,提交前序列化一次并复用;同一用户/应用/活动/存档位可跳过与上次成功值相同的内容,失败不更新成功记录,成功后更新或失效读取缓存;不在输入、渲染或逐帧回调中反复序列化和深拷贝
18
+ - 仅在启用持续自动保存时合并连续变化,同一存档位至少间隔 3 秒并按可接受的进度损失设最长等待;不是每 3 秒定时保存,无变化不写,仅按节点保存无需这套调度。手动保存防重复,手动或明确业务节点不必等待该间隔;同一存档位不重叠写,旧请求成功不能清掉新变化,不只依赖关闭时保存
19
+ - 已启用自动保存且需要恢复时,成功读取、解析和校验前暂停自动写回;普通手动保存不要求先读。卸载或切换用户/应用/活动/存档位时清理定时器、监听、缓存及待写任务,忽略旧结果
20
+ - 只有 code === 200 才提示已保存;失败提示并保留内容,暂停该失败操作的自动提交,不由定时器或队列立即重发、不无限重试。413 先去冗余,仍超限不能截断必要内容;2MiB 是 UTF-8 字节上限而非目标,验证体积、请求次数和序列化耗时
21
+ - 超时或网络中断不代表云端未写入,底层请求可能仍在执行;暂停自动写并保留提交快照及新编辑,不立即发起可能被旧请求覆盖的新写入。没有删除接口,清空需按业务约定保存空状态,空字符串不等于无存档;重置及提交后清理须处理旧待写和在途请求,不能清掉新编辑。细则见 hupu-cloud-save/SKILL.md
22
+
23
+ # Parameters
24
+
25
+ | 参数名 | 类型 | 是否必填 | 说明 |
26
+ | --- | --- | --- | --- |
27
+ | slot | integer | 是 | 存档编号,只接受 1–5 的整数;固定用途,建议每个应用最多使用三个存档位 |
28
+ | value | string | 是 | 恢复必需的数据字符串;对象按需 JSON.stringify,最多 2MiB UTF-8 bytes |
29
+
30
+ # Returns
31
+
32
+ - Type: `Promise<Response>`
33
+
34
+ ### Response Properties
35
+
36
+ | 属性名 | 类型 | 是否必填 | 说明 |
37
+ | --- | --- | --- | --- |
38
+ | code | number | 是 | 成功为 200,失败时为错误码 |
39
+ | message | string | 是 | 结果说明 |
40
+
41
+ # Examples
42
+
43
+ ```javascript
44
+ window.ShaperAI.cloudSave.save({ slot: 1, value: JSON.stringify({ levelId: 3 }) }).then(res => { if (res.code !== 200) throw new Error(res.message || "保存失败"); console.log("保存成功"); }).catch(error => console.warn(error.message));
45
+ ```
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: hupu-storage-get-value
3
+ description: 读取当前活动页在本地或 App 容器内已经存储的状态数据。支持项目隔离及读取合并。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.storage.getValue(params)`
9
+
10
+ # Constraints
11
+
12
+ - 本地存档、草稿、单机进度允许直接通过 window.localStorage.getItem 读取,不要当成违规或强行改写
13
+ - 需要按项目隔离读取时使用 ShaperAI.storage.getValue
14
+ - 当读取的键尚未存储时,接口返回 null,前台页面需要做好对应的空值兜底
15
+
16
+ # Parameters
17
+
18
+ | 参数名 | 类型 | 是否必填 | 说明 |
19
+ | --- | --- | --- | --- |
20
+ | key | string | 否 | 待读取的数据键名称,如果不传则返回当前项目下存储的所有键值对 |
21
+
22
+ # Examples
23
+
24
+ ```javascript
25
+ window.ShaperAI.storage.getValue("userLevel").then(val => { console.log(val); })
26
+ ```
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: hupu-storage-set-value
3
+ description: 为当前活动页在本地或 App 容器内安全存储指定的键值数据。支持项目隔离及多端自动同步。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.storage.setValue(params)`
9
+
10
+ # Constraints
11
+
12
+ - 本地存档、草稿、单机进度允许直接使用 window.localStorage 或 window.sessionStorage,不要当成违规或强行改写
13
+ - 需要 App 容器同步或按项目隔离时使用 ShaperAI.storage.setValue
14
+ - 使用 ShaperAI.storage 时,单次写入的数据大小不得超过 200KB
15
+ - 使用 ShaperAI.storage 时,数据必须传入普通对象键值对格式
16
+ - 禁止用本地存储冒充多人后端,禁止明文存储令牌或身份凭证
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | data | object | 是 | 需要存储的键值对对象数据,如 { score: 10 } |
23
+
24
+ # Returns
25
+
26
+ - Type: `Promise<Response>`
27
+
28
+ ### Response Properties
29
+
30
+ | 属性名 | 类型 | 是否必填 | 说明 |
31
+ | --- | --- | --- | --- |
32
+ | ok | boolean | 是 | 是否成功发起写入 |
33
+ | key | string | 否 | 写入的主键标识 |
34
+ | keys | array | 否 | 所有写入的键标识列表 |
35
+ | keys[] | string | 否 | 数组元素 |
36
+ | size | number | 否 | 本次写入数据的大小,单位字节 |
37
+
38
+ # Examples
39
+
40
+ ```javascript
41
+ window.ShaperAI.storage.setValue({ userLevel: 5 })
42
+ ```
@@ -0,0 +1,6 @@
1
+ # 用户登录
2
+
3
+ 识别玩家、获取用户资料。本目录仅分类,技能内容暂不重构。
4
+
5
+ - [hupu-auth-get-user-info](hupu-auth-get-user-info/SKILL.md)
6
+ - [hupu-game-auth](hupu-game-auth/SKILL.md)
@@ -0,0 +1,47 @@
1
+ ---
2
+ name: hupu-auth-get-user-info
3
+ description: 获取当前登录用户的基本资料(包含用户唯一标识 PUID、头像、昵称及客户端布局信息)。可用于登录态校验、页面个性化定制与特权判定。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.auth.getUserInfo()`
9
+
10
+ # Constraints
11
+
12
+ - 必须使用 window.ShaperAI.auth.getUserInfo() 接口进行异步调取
13
+ - 若当前用户未登录,接口返回的 data 可能为 null,业务端需做好未登录状态的引导(如去登录)
14
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
15
+
16
+ # Parameters
17
+
18
+ | 参数名 | 类型 | 是否必填 | 说明 |
19
+ | --- | --- | --- | --- |
20
+
21
+ # Returns
22
+
23
+ - Type: `Promise<Response>`
24
+
25
+ ### Response Properties
26
+
27
+ | 属性名 | 类型 | 是否必填 | 说明 |
28
+ | --- | --- | --- | --- |
29
+ | code | number | 是 | 状态码,成功为 200 |
30
+ | message | string | 是 | 提示信息 |
31
+ | data | object | 否 | |
32
+ | data.islogin | number | 否 | 是否登录:1 为已登录,0 为未登录/游客 |
33
+ | data.puid | string | 否 | 用户唯一 ID(未登录为 null) |
34
+ | data.nickname | string | 否 | 用户昵称(未登录为 null) |
35
+ | data.avatar | string | 否 | 用户头像 URL 链接地址 |
36
+ | data.userHeadUrl | string | 否 | 用户头像 URL 链接地址(同 avatar) |
37
+ | data.platform | string | 否 | 当前客户端平台:iOS / Android |
38
+ | data.night | number | 否 | 是否为夜间模式:1 为是,0 为否 |
39
+ | data.statusbar_hight | number | 否 | 状态栏高度(单位 px),用于顶部自定义标题栏避让刘海 |
40
+ | data.titlebar_hight | number | 否 | 标题栏高度(单位 px) |
41
+ | data.bottomSafeHeight | number | 否 | 底部安全区高度(单位 px,如 iPhone 全面屏通常为 34px) |
42
+
43
+ # Examples
44
+
45
+ ```javascript
46
+ window.ShaperAI.auth.getUserInfo().then(res => { if (res.code === 200 && res.data) { console.log("当前登录用户:", res.data.nickname); } else { console.log("当前未登录"); } });
47
+ ```
@@ -0,0 +1,46 @@
1
+ ---
2
+ name: hupu-game-auth
3
+ description: 使用当前登录态获取目标应用的短期游戏令牌。默认使用当前页面所属应用,也可显式传入其他 appId。游戏地址由游戏自身配置。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.game.auth(params)`
9
+
10
+ # Constraints
11
+
12
+ - 页面通过 window.ShaperAI.game.auth 获取连接凭证;无需接触签发地址、CloudBase 环境或验签密钥
13
+ - appId 指向目标游戏所属应用,格式为 app_xxxxx;不能从 CloudBase envId 推导
14
+ - 令牌交给 Colyseus 客户端的 client.auth.token,不放入 URL、消息或 join options
15
+ - 每次准备入房时获取新凭证;重连使用 Colyseus reconnectionToken
16
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | appId | string | 否 | 目标游戏所属应用 ID;省略时使用当前页面的 appId |
23
+
24
+ # Returns
25
+
26
+ - Type: `Promise<Response>`
27
+
28
+ ### Response Properties
29
+
30
+ | 属性名 | 类型 | 是否必填 | 说明 |
31
+ | --- | --- | --- | --- |
32
+ | code | number | 是 | 状态码,成功为 200 |
33
+ | message | string | 是 | 提示信息 |
34
+ | data | object | 否 | |
35
+ | data.token | string | 否 | 短期 Game Token |
36
+ | data.expiresAt | number | 否 | 令牌过期时间,毫秒时间戳 |
37
+
38
+ # Examples
39
+
40
+ ```javascript
41
+ const res = await window.ShaperAI.game.auth(); if (res.code === 200) console.log(res.data.token);
42
+ ```
43
+
44
+ ```javascript
45
+ const res = await window.ShaperAI.game.auth({ appId: "app_1234567890" });
46
+ ```
@@ -5,7 +5,7 @@ description: 在 Shaper 网页中接入虎扑用户资料、分享和 cloud.requ
5
5
 
6
6
  # 虎扑业务接入
7
7
 
8
- 页面使用 Shaper 容器提供的 `window.ColorboxAI`。开发者 CLI 的 OAuth 只管理项目,不是应用用户登录。新工具保持既有虎扑桥接协议;不要套用 Maker 的 SDK 名称或注入方式。
8
+ 页面使用 Shaper 容器提供的 `window.ShaperAI`。开发者 CLI 的 OAuth 只管理项目,不是应用用户登录。新工具保持既有虎扑桥接协议;不要套用 Maker 的 SDK 名称或注入方式。
9
9
 
10
10
  用户资料、分享和云业务请求的具体调用见 [references/runtime.md](references/runtime.md)。需要这些能力时读取该文档;玩家认证复用已有 SDK 的 cloud.request 内部逻辑。
11
11
 
@@ -1,11 +1,11 @@
1
1
  # 既有虎扑桥接
2
2
 
3
- Shaper 发布壳提供 `window.ColorboxAI`。不额外从第三方 CDN 装一份替代 SDK。
3
+ Shaper 发布壳提供 `window.ShaperAI`。不额外从第三方 CDN 装一份替代 SDK。
4
4
 
5
5
  读取当前用户:
6
6
 
7
7
  ```js
8
- const result = await window.ColorboxAI.auth.getUserInfo();
8
+ const result = await window.ShaperAI.auth.getUserInfo();
9
9
  const signedIn = result.code === 200 && (
10
10
  result.data?.islogin === 1 ||
11
11
  result.data?.islogin === '1' ||
@@ -18,7 +18,7 @@ const signedIn = result.code === 200 && (
18
18
  用户点击分享按钮时:
19
19
 
20
20
  ```js
21
- const result = await window.ColorboxAI.social.share({
21
+ const result = await window.ShaperAI.social.share({
22
22
  title: '我的作品',
23
23
  link: publishedHttpsUrl,
24
24
  text: '一起来玩',
@@ -38,18 +38,24 @@ const user = await hupu.user();
38
38
 
39
39
  `available()` 读取桥接可用性,`user()` 返回 `signedIn` 和展示资料,`share()` 保留宿主结果。它不保存用户凭证,不自动引入云管理 SDK。包未发布阶段,应使用交付的本地 npm 包;不要假设公共 registry 中已存在此版本。
40
40
 
41
- 调用应用自己的云业务接口时,直接复用已有 SDK:
41
+ ## 新版应用云请求
42
+
43
+ 使用壳提供的当前应用,不填写环境 ID、网关地址或 Token:
42
44
 
43
45
  ```js
44
- const response = await window.ColorboxAI.cloud.request({
45
- url: `${apiBase}/votes`,
46
+ const response = await window.ShaperAI.cloud.request({
47
+ path: '/api/progress',
46
48
  method: 'POST',
47
- data: { matchId, teamId },
48
- envId,
49
- auth: true
49
+ data: { score: 100, submissionId }
50
50
  });
51
51
  ```
52
52
 
53
- `apiBase` 是已经部署并验证的 HTTPS 业务接口地址,`envId` 是对应环境的公开运行配置;两者都不是平台密钥。SDK 内部处理玩家登录和认证。根据实际接口契约检查 HTTP `statusCode` 与业务 `code/message/data`,业务函数仍负责数据权限。
53
+ 只传 path、method、data;支持 GET/POST/PUT/PATCH/DELETE/HEAD。路由的 public/user 决定是否登录。SDK 验证真实虎扑玩家、换取当前应用会话并请求网关;后端从 user.puid 判断归属,不信任 body.puid。预览访问凭证由壳管理,业务不读取或复制。
54
+
55
+ 先确认 cloud status 就绪、数据库迁移成功、后端和网关部署成功,再在实际虎扑容器验证保存与回读。普通浏览器没有玩家登录态时给出登录提示,不使用开发者 Token 或调试账号冒充真实玩家。检查 statusCode 和业务 code/message/data;失败的写请求先确认结果,不自动重发。日志不记录 Token。
56
+
57
+ 若返回 CLOUD_NOT_CONFIGURED,说明平台壳尚未接入新版能力,应升级平台 SDK/运行配置;不能自行拼接服务地址或回退旧鉴权。此次测试7已在开发环境验证,正式环境上线状态仍需核对。
58
+
59
+ ## 已有旧云调用
54
60
 
55
- 先确认 HTTP 函数、路由及环境认证配置已由平台就绪,再验证用户请求。当前新 MCP 的事件函数部署/管理调用不会自动产生 HTTP 业务地址;需要 HTTP 服务时沿用现有部署入口。管理操作成功不能替代真实容器内的业务请求验收。
61
+ 旧项目继续使用已有 url/envId/auth 参数,不与 path 混用。新旧会话独立;不要为了兼容新后台而将旧云 Token 附加到新地址。旧项目升级遵循 shaper-development,不在业务调用中自动迁移。
@@ -7,7 +7,7 @@ description: 设计和实现 Shaper 后端接口、数据模型、身份权限
7
7
 
8
8
  先读项目 docs/product.md、docs/design.md 和已有后端,确定本次需要接口、数据变更还是部署。没有共享状态或权威判定需求时,先评估是否需要后台。
9
9
 
10
- 旧版下载包(activity.json.activityId、COLORBOX 指导块或 act-cloudbase 技能)继续原项目流程,本技能停止新版接入;LEGACY_PROJECT_UPGRADE_REQUIRED 不能通过删除标识、link 或旧脚本绕过。升级策略见 shaper-development。
10
+ 旧版下载包(activity.json.activityId、旧版生成指导块或 act-cloudbase 技能)继续原项目流程,本技能停止新版接入;LEGACY_PROJECT_UPGRADE_REQUIRED 不能通过删除标识、link 或旧脚本绕过。升级策略见 shaper-development。
11
11
 
12
12
  ## 执行顺序
13
13
 
@@ -3,8 +3,8 @@
3
3
  ## 设计与读写
4
4
 
5
5
  - 明确数据所有者、唯一约束、索引和生命周期。次数、余额、奖励等约束由数据库事务和约束共同保证。
6
- - 使用 `db.query(sql, values)` 参数化查询;按可信 user 限定数据归属,SDK 不自动实现行级授权。
7
- - 多次写入使用 `await db.transaction(async tx => { ... })`,在回调内 await 所有操作。业务事务出错整体回滚,不支持嵌套事务或回调结束后继续使用 tx。
6
+ - 使用 `cloud.db.query(sql, values)` 参数化查询;按可信 user 限定数据归属,SDK 不自动实现行级授权。
7
+ - 多次写入使用 `await cloud.db.transaction(async tx => { ... })`,回调内用 tx.query 并 await 所有操作。业务事务出错整体回滚,不支持嵌套事务或回调结束后继续使用 tx。
8
8
  - 按业务定义幂等键,区分未提交、已提交和结果未知,重试不能重复扣减或发奖。
9
9
 
10
10
  ## 结构变更
@@ -22,7 +22,7 @@ exports.main = async (event) => ({ ok: true, message: event.message ?? 'Hello Hu
22
22
 
23
23
  部署返回 `deploying` 后,用 `hupu_legacy_cloud_functions` 检查函数状态,直到 `ready`,再执行 `hupu_legacy_cloud_function_invoke` 验证真实返回,并查询 `hupu_legacy_cloud_function_logs` 排查错误。函数部署、调用、日志三项分别记录结果。
24
24
 
25
- 函数运行环境和日志由虎扑云部署流程自动配置。当前事件函数管理接口不等于浏览器运行时 API;网页访问已有 HTTP 业务接口时,使用 `hupu-business` 中的 `ColorboxAI.cloud.request`,由 SDK 内部处理玩家认证。HTTP 函数与路由配置目前沿用旧部署入口;管理凭证始终留在开发工具和服务端。
25
+ 函数运行环境和日志由虎扑云部署流程自动配置。当前事件函数管理接口不等于浏览器运行时 API;网页访问已有 HTTP 业务接口时,使用 `hupu-business` 中的 `ShaperAI.cloud.request`,由 SDK 内部处理玩家认证。HTTP 函数与路由配置目前沿用旧部署入口;管理凭证始终留在开发工具和服务端。
26
26
 
27
27
  ## 数据库
28
28
 
@@ -1,35 +1,44 @@
1
1
  # 后端实现与路由
2
2
 
3
- 先按用户操作定义请求、响应、身份前提和失败行为,前后端共用同一接口契约。后台校验输入、数据归属和业务权限;UI 传来的用户标识与状态不作为可信依据。
4
-
5
- 源码由开发者工程管理:
3
+ 先按用户操作定义请求、响应、身份前提和失败行为。业务使用普通 Node HTTP 服务;Express 等框架由项目选择,SDK 只负责玩家鉴权与 PostgreSQL 访问。
6
4
 
7
5
  ```text
8
6
  cloud/functions/api/
9
- handlers.cjs # 可继续拆分为业务 modules,再从此入口导出 handlers
10
- cloud.json # 精确 SDK 版本与运行参数
11
- package.json # 精确依赖和 hupuCloud 构建设置
12
- vendor/ # Toolkit 分发的 SDK 包,应随源码提交
13
- README.md # 当前模板的操作步骤
7
+ server.cjs # HTTP 启动入口,可拆分路由和业务模块
8
+ cloud.json # manifest v2、SDK 精确版本、运行参数
9
+ package.json # 依赖与 hupuCloud.entry
10
+ package-lock.json
11
+ cloud/gateway/routes.json # 暴露路径、方法、登录要求
12
+ cloud/database/migrations/ # 独立 SQL 迁移
14
13
  ```
15
14
 
16
- 网关在 `cloud/gateway/routes.json`,迁移在 `cloud/database/migrations/`;路由只维护一份。旧 `functions/api` 的合并 manifest 与 migrations 继续支持,不自动搬迁。
17
-
18
15
  ```js
19
- const { defineHandlers } = require('@hupu/cloud-server');
20
- exports.handlers = defineHandlers({
21
- me: async ({ user, db }) => ({
22
- rows: (await db.query('SELECT score FROM progress WHERE puid=$1', [user.puid])).rows,
23
- }),
16
+ const express = require('express');
17
+ const { createClient, ShaperCloudError } = require('@hupu-tech/shaper-cloud');
18
+ const app = express();
19
+ const cloud = createClient();
20
+ app.use(express.json({ limit: '64kb' }));
21
+ app.get('/api/me', async (req, res, next) => {
22
+ try {
23
+ const user = await cloud.auth.requireUser({ authorization: req.headers.authorization });
24
+ const result = await cloud.db.query('SELECT score FROM progress WHERE puid=$1', [user.puid]);
25
+ res.json({ rows: result.rows });
26
+ } catch (error) { next(error); }
27
+ });
28
+ app.use((error, req, res, next) => {
29
+ if (error instanceof ShaperCloudError) return res.status(error.status).json({ code: error.code, message: error.publicMessage });
30
+ res.status(500).json({ code: 'INTERNAL_ERROR' });
24
31
  });
32
+ const server = app.listen(Number(process.env.PORT || 9000), '0.0.0.0');
33
+ process.once('SIGTERM', () => server.close(() => cloud.close()));
25
34
  ```
26
35
 
27
- `me` 声明为 user 路由后,网关先认证,SDK 提供可信 user。数据归属仍在 SQL/业务规则中明确限制。将客户端的 body.puid 当作当前用户会绕过业务授权。
36
+ 每个进程复用一个 client,每次请求单独取得 user;私有接口必须调用 requireUser。按可信 user.puid 限制数据归属,不能采用 body.puid。可匿名接口用 getUser;无凭据返回 null,无效凭据仍报错。运行绑定由平台注入,源码不包含厂商密钥或数据库密码。
28
37
 
29
- 业务使用平台 SDK 提供的 db,不自行创建数据库连接池,不处理厂商 Token 或环境密钥。
38
+ 业务路由在 HTTP 服务中;网关声明只描述暴露范围,不映射 JS 函数。新增接口同步声明路径和方法,服务端仍须鉴权。腾讯托管网关负责 CORS 响应,避免重复添加跨域头。
30
39
 
31
- 按工具包 `templates/cloud-service` 准备源码和 SDK 依赖,并按上述目录分离运行配置、网关和迁移,不覆盖已有工程。包中 `initCloudService(workspace)` 是本地模板辅助函数,不是云资源创建动作。
40
+ 按工具包 templates/cloud-service 初始化本地源码;已有工程保留代码。函数目录执行 npm ci,新增依赖后提交锁文件。部署将 SDK 和业务依赖打包,产物在 .shaper/cloud-build/<digest>。旧 handler 项目需显式升级为 HTTP 服务,不能直接换 SDK 版本。
32
41
 
33
- 之后修改 cloud/functions/api 中的源码和声明,再执行 deploy。构建目录位于 `.shaper/cloud-build/<digest>`,不是源码目录。Toolkit 内置 SDK 包可支持未发布 registry 的开发流程;安装业务第三方依赖时使用函数目录的 package.json,提交锁文件。
42
+ 前端使用 ShaperAI.cloud.request({ path, method, data }),完整玩家接入见 hupu-business。迁移、后端部署和网页预览分别验证;真实登录和云端读写通过才算链路完成。当前已完成腾讯云新版真机验证,阿里云仍待验证。
34
43
 
35
- 默认模板的进度和排行榜是教学业务;正式应用需替换展示资料和计分逻辑。SDK 统一的是 Node HTTP、用户上下文和 PostgreSQL 协议访问;当前只有 CloudBase 适配器完成,支持情况由工具内部检查,开发者无需选择厂商或规格。
44
+ 需要排行榜时,调用 shaper_templates 找到 leaderboard 项目,先读 docs/integration.md,再参考其前后端与迁移。已有项目复用原身份、积分和服务入口,按业务融合;模板的自报成绩示例不作为可信奖励计分。
@@ -17,7 +17,7 @@ description: 检查新旧 Shaper 项目的归属,初始化或关联应用,
17
17
 
18
18
  ## 开始创作与继续开发
19
19
 
20
- 接入完成且需求尚未明确时,引导用户描述想法,暂不选模板。需求已明确且尚无工程时,由 AI 根据交互特点选择 h5、react 或 phaser,调用 `shaper_create(workspace, template)`(CLI:`shaper create --template react`),再实现需求;不要让用户选择技术栈。已有源码沿用原工程,不调用 create 覆盖。`project.engineering.status: not_created` 是正常待创作状态;configuration_required 才需要检查已有工程并补配置。
20
+ 接入完成且需求尚未明确时,引导用户描述想法,暂不选模板。需求已明确且尚无工程时,由 AI 根据交互特点选择工程模板,调用 `shaper_create(workspace, template)`(CLI:`shaper create --template react`),再实现需求;不要让用户选择技术栈。已有源码沿用原工程,不调用 create 覆盖。`project.engineering.status: not_created` 是正常待创作状态;configuration_required 才需要检查已有工程并补配置。
21
21
 
22
22
  用 Agent 自带的文件工具编写项目。`shaper_dev_start` 返回就绪 URL 后,在浏览器检查用户实际会用的交互、控制台错误和窄屏布局。开发日志用 `shaper_dev_logs`。停止服务用 `shaper_dev_stop`;状态查询不会重启服务。
23
23
 
@@ -27,6 +27,10 @@ description: 检查新旧 Shaper 项目的归属,初始化或关联应用,
27
27
 
28
28
  新官方模板统一维护 docs/product.md、docs/design.md 和 docs/validation.md;已接入新版的工程只补缺失文档,不搬迁或覆盖源码。React 按业务组织组件,状态靠近使用者;异步操作具有失败反馈与重复提交保护。不默认添加路由、全局状态或大型 UI 库。
29
29
 
30
+ ## 复用完整项目模板
31
+
32
+ 需要排行榜或离线养成时,调用 `shaper_templates`(CLI:`shaper templates`),读取对应目录的 `docs/integration.md`。每个模板包含自己的前端、所需后端、数据库与说明。新空工程可用 `leaderboard` 或 `offline-game` 创建;已有工程先检查现有身份、积分、存档与路由,再按说明增量融合并验证原业务,模板目录只读。后端迁移与部署交由 shaper-backend。
33
+
30
34
  ## 用户引导
31
35
 
32
36
  - 接入完成先说明可以开始创作,引导用户直接描述想法;仅确需重启客户端时给出重启步骤。版本、App ID、配置和检查明细用于排查,不作为默认完成报告。
@@ -47,7 +47,7 @@
47
47
 
48
48
  ## 旧版下载项目
49
49
 
50
- 发现 activity.json 的 activityId、AGENTS.md 的 COLORBOX 标记或 skills/act-cloudbase 时,保留原下载技能及原开发方式,停止新版初始化、开发和交付流程。目录名不是判定依据;已写入 .shaper 绑定不代表升级完成。
50
+ 发现 activity.json 的 activityId、AGENTS.md 的旧版生成标记或 skills/act-cloudbase 时,保留原下载技能及原开发方式,停止新版初始化、开发和交付流程。目录名不是判定依据;已写入 .shaper 绑定不代表升级完成。
51
51
 
52
52
  工具返回 LEGACY_PROJECT_UPGRADE_REQUIRED 时说明:这是旧版项目,仍可按原方式开发。不要删除标识、改用 link、覆盖指导或运行旧脚本来绕过新版限制。
53
53
 
@@ -13,6 +13,6 @@ description: 细化并实现游戏玩法、最小可玩原型、场景与资源
13
13
  4. 试玩检查输入响应、边界、失败与重玩、不同屏幕、持续运行;按实际设备记录帧率或卡顿依据。根据观察调整节奏和反馈,不凭截图宣称好玩。
14
14
  5. 更新 docs/design.md 的玩法实现与取舍、docs/validation.md 的实际试玩结论及未验证项。
15
15
 
16
- 离线成长、自动产出或离线结算可使用独立的 shaper-idle-game 技能(未安装时按需求补充,不阻断普通游戏)。奖励、排行榜等可信状态需要 shaper-backend;壳身份和分享由 hupu-business 接入。工程和预览复用 shaper-development,网页交付由 shaper-release 处理。
16
+ 离线存档、升级和离线收益的代码参考:调用 shaper_templates,读取 offline-game/docs/integration.md,按现有游戏状态融合;空工程才用 create。离线成长、自动产出或离线结算可使用独立的 shaper-idle-game 技能(未安装时按需求补充,不阻断普通游戏)。奖励、排行榜等可信状态需要 shaper-backend;壳身份和分享由 hupu-business 接入。工程和预览复用 shaper-development,网页交付由 shaper-release 处理。
17
17
 
18
18
  交付首个可玩版本时,按 shaper-development 的用户引导给出试玩入口,邀请反馈操作、节奏或难度;用户希望分享时再转入 shaper-release,不以代码或构建报告结束试玩交付。
@@ -7,7 +7,7 @@ description: 将 Shaper 网页工程构建、上传预览并提交发布审核
7
7
 
8
8
  调用 `shaper_status(workspace)` 确认当前账号、服务和应用绑定。已有用户明确要求部署或提交审核时直接完成已授权流程。
9
9
 
10
- 旧版下载包(activity.json.activityId、COLORBOX 指导块或 act-cloudbase 技能)继续原项目流程,本技能停止新版接入;LEGACY_PROJECT_UPGRADE_REQUIRED 不能通过删除标识、link 或旧脚本绕过。升级策略见 shaper-development。
10
+ 旧版下载包(activity.json.activityId、旧版生成指导块或 act-cloudbase 技能)继续原项目流程,本技能停止新版接入;LEGACY_PROJECT_UPGRADE_REQUIRED 不能通过删除标识、link 或旧脚本绕过。升级策略见 shaper-development。
11
11
 
12
12
  1. 用 `shaper_web_deploy` 构建并上传网页代码。它复用 Shaper 版本、内容校验和预览服务。检查操作 `status`、校验结果、`versionId` 与预览信息;上传成功并不代表应用已发布。
13
13
  2. 展示 `result.preview.previewUrl`、`expiresAt` 和二维码;MCP 同时返回二维码图片,CLI 返回 `qrCodePath`。打开云端预览地址验证页面,手机扫描该二维码;本机回环链接不用于手机分享。链接过期、预览生成失败或仅需查看已有版本时,用 `shaper_web_preview(workspace, versionId)` 获取或刷新;省略版本只复用该工程最近一次已确认交付,不选择其他应用或新建版本。若已安装工具缺少此能力,明确提示升级 Toolkit/插件,不用重新上传代替刷新。需要虎扑登录或分享时,在实际 Shaper/虎扑容器中检查对应能力;本地浏览器检查作为独立证据。
@@ -1,33 +1,7 @@
1
- # Node 后台服务
1
+ # 应用后端
2
2
 
3
- 此目录是该应用一个 HTTP 后台服务的源码,可包含多个路由。持续修改这里,再重新构建发布;无需重复开通云资源。当前一个应用管理一份活动 HTTP 发布,新目录不会自动变成第二个独立服务。
3
+ `server.cjs` 是普通 Express 服务;从 `@hupu-tech/shaper-cloud` 导入 `createClient`,使用 `cloud.auth.requireUser` 校验玩家、`cloud.db` 访问 PostgreSQL。按 `PORT` 启动服务。
4
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。
5
+ 业务路由在服务代码中;网关声明只限制公开路径、方法和登录要求,不映射处理函数。私有接口必须在服务代码中校验身份并按 `user.puid` 限制数据归属。
9
6
 
10
- 从开发者工程根目录操作(目录不是 functions/api 时替换路径):
11
-
12
- ```sh
13
- # 获得用户对当前应用开通的明确同意后:
14
- shaper cloud create
15
- shaper cloud status # 确认 ready 后继续
16
- shaper cloud db migrate --version 202610250001_init --file functions/api/migrations/202610250001_init.sql
17
- # 确认上一迁移已生效后继续
18
- shaper cloud db migrate --version 202610250002_events --file functions/api/migrations/202610250002_events.sql
19
- # 确认迁移已生效后部署
20
- shaper cloud deploy --directory functions/api
21
- ```
22
-
23
- 以后修改 handlers/cloud.json,直接再次 deploy;新增表字段先迁移。deploy 自动构建 CommonJS、打包第三方纯 JS 依赖,并外置平台 SDK。它不执行任意 npm build 脚本,也不自动运行数据库迁移。增加第三方依赖后在本目录安装,提交锁文件;动态依赖、原生二进制及额外资源文件不属于这版单 bundle 部署契约。
24
-
25
- 鉴权在云厂商网关执行。user 路由中的 `user.puid` 可信;public 路由没有 user。业务不读取身份头、Token、PG 环境变量,不创建连接池。Node 控制面绑定应用资源,Hupu 不代理业务 HTTP 或 SQL。
26
-
27
- `db.query(sql, values)` 使用参数化 SQL。`db.transaction(async tx => {...})` 内必须 await 全部操作;真实 PG 事务固定一个连接,失败回滚,不自动重试、不支持嵌套。数据归属、业务角色、分数校验仍由业务实现;SDK 不会自动加用户过滤或 RLS。
28
-
29
- 初始示例包含排行榜和个人进度,仅用于演示:公开榜单返回测试 PUID,正式业务应改成展示资料;自报分数不具备防作弊能力。重复 submissionId 返回 409 且整笔回滚;未提供时使用请求 ID,因此网络重试不保证去重。
30
-
31
- cloud.json 是路由声明的源文件,修改后通过 cloud deploy 随服务发布。构建由 deploy 自动完成。
32
-
33
- 异步返回 queued/running 仅表示受理或执行中。开通以 cloud status 的 ready 为准;发布以当前 release.digest 和接口验证为准。写操作自动等待结果;仍在处理中时通过 cloud status 查看未完成和最近操作,迁移 succeeded 后才执行依赖变更。结果未知时不重复提交。
7
+ 在函数目录执行 npm ci。新增依赖后提交锁文件;部署会打包 SDK 和业务依赖。数据库结构变更先迁移成功,再部署服务。运行绑定由平台注入,凭据不写入源码。
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": 1,
2
+ "version": 2,
3
3
  "runtime": "nodejs20",
4
4
  "memoryMB": 256,
5
5
  "timeoutSeconds": 15,
@@ -7,24 +7,21 @@
7
7
  {
8
8
  "method": "GET",
9
9
  "path": "/api/leaderboard",
10
- "access": "public",
11
- "handler": "leaderboard"
10
+ "access": "public"
12
11
  },
13
12
  {
14
13
  "method": "GET",
15
14
  "path": "/api/me",
16
- "access": "user",
17
- "handler": "me"
15
+ "access": "user"
18
16
  },
19
17
  {
20
18
  "method": "POST",
21
19
  "path": "/api/progress",
22
- "access": "user",
23
- "handler": "progress"
20
+ "access": "user"
24
21
  }
25
22
  ],
26
23
  "serverSdk": {
27
- "name": "@hupu/cloud-server",
28
- "version": "0.1.0"
24
+ "name": "@hupu-tech/shaper-cloud",
25
+ "version": "0.3.0"
29
26
  }
30
27
  }