@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,90 @@
1
+ ---
2
+ name: hupu-request-news-news-common-list
3
+ description: 获取赛事导航页(如 FIFA、NBA、CBA)的新闻列表,支持分页,用于资讯首页展示。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.request.news.newsCommonList(params)`
9
+
10
+ # Constraints
11
+
12
+ - 请求接口数据必须使用 window.ShaperAI.request 能力及其子能力发起,禁止使用 fetch、axios、XMLHttpRequest、第三方请求库或其它自定义请求方式。
13
+ - 数据能力调用必须避免无条件循环、无限轮询和重复渲染触发;同一参数的返回结果应优先保存在组件状态中复用。
14
+ - 列表/分页类接口连续自动翻页最多 5 页,必须在无下一页、返回空列表或达到页数上限时停止。
15
+ - SDK 前端已启用请求保护:默认不限制单能力并发和分钟调用量,不启用相同请求在途合并或 GET 短缓存;同 URL 在 10000ms 内最多 20 次;同一页面同接口(去掉 query/hash 参数后相同即为同一接口)在 5000ms 内最多 20 次,首次超过限制返回 429,后续同窗口请求静默丢弃,且同一窗口内只上报一次异常日志。不要自行循环重试或重复触发请求,若接口真实返回 408、429 或 503 等错误码,必须停止继续请求并给用户友好提示。
16
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | source | string | 是 | 请求来源标识,默认可传 "nav_category_news" |
23
+ | tagCode | string | 是 | 赛事标识 TagCode,如 "fifa" (足球世界杯) 等 |
24
+ | newsId | string | 否 | 用于分页的分界新闻ID,上一页返回结果中最后一个新闻的 nid,不传则默认为第一页。 |
25
+
26
+ # Returns
27
+
28
+ - Type: `Promise<Response>`
29
+
30
+ ### Response Properties
31
+
32
+ | 属性名 | 类型 | 是否必填 | 说明 |
33
+ | --- | --- | --- | --- |
34
+ | code | number | 是 | 状态码。200 表示成功,401 表示未登录,404 表示内容不存在,500 表示服务器错误 |
35
+ | message | string | 是 | 错误提示信息。当 code 不等于 200 时必须用于向用户友好提示 |
36
+ | data | object | 否 | 成功时返回的数据载荷 |
37
+ | data.newsCommonItems | array | 否 | 首页资讯新闻列表 |
38
+ | data.newsCommonItems[].newsType | string | 否 | 列表项类型,固定为 "news_common" |
39
+ | data.newsCommonItems[].recommendBaseScore | number / null | 否 | 推荐基础分,可能为 null |
40
+ | data.newsCommonItems[].data | object | 否 | 新闻条目详情数据 |
41
+ | data.newsCommonItems[].data.newsType | string | 否 | 新闻类型,固定为 "news_common" |
42
+ | data.newsCommonItems[].data.newsMarkInfos | array | 否 | 新闻角标列表,可能为空数组 |
43
+ | data.newsCommonItems[].data.newsMarkInfos[].text | string | 否 | 标记文案,如 "置顶" |
44
+ | data.newsCommonItems[].data.newsMarkInfos[].url | string | 否 | 日间标记图片 URL |
45
+ | data.newsCommonItems[].data.newsMarkInfos[].nightUrl | string | 否 | 夜间标记图片 URL |
46
+ | data.newsCommonItems[].data.newsMarkInfos[].width | number | 否 | 标记图片宽度 |
47
+ | data.newsCommonItems[].data.newsMarkInfos[].height | number | 否 | 标记图片高度 |
48
+ | data.newsCommonItems[].data.showHotReply | boolean | 否 | 是否展示热门回复标识 |
49
+ | data.newsCommonItems[].data.top | boolean | 否 | 是否置顶 |
50
+ | data.newsCommonItems[].data.newsContentLabel | string | 否 | 新闻内容标签,如 "图文新闻"、"跳转新闻-普通" |
51
+ | data.newsCommonItems[].data.linkUrl | string | 否 | 跳转链接(kanqiu:// 或 huputiyu:// 协议) |
52
+ | data.newsCommonItems[].data.iconInfo | object / null | 否 | 新闻图标信息;无图标时为 null |
53
+ | data.newsCommonItems[].data.iconInfo.iconName | string | 否 | 图标名称,如 "置顶"、"热门" |
54
+ | data.newsCommonItems[].data.iconInfo.iconUrl | string | 否 | 日间图标 URL |
55
+ | data.newsCommonItems[].data.iconInfo.iconNightUrl | string | 否 | 夜间图标 URL |
56
+ | data.newsCommonItems[].data.customLabelInfo | object / null | 否 | 自定义标签信息;无标签时为 null |
57
+ | data.newsCommonItems[].data.customLabelInfo.labelName | string | 否 | 标签名称,如 "虎扑辩论赛"、"闲谈播客" |
58
+ | data.newsCommonItems[].data.newsDescribeInfo | object | 否 | 新闻描述信息(回复数摘要等) |
59
+ | data.newsCommonItems[].data.newsDescribeInfo.describeInfo | string | 否 | 描述文案,如 "6 回复"、"JRs热议中" |
60
+ | data.newsCommonItems[].data.nid | string | 否 | 新闻 ID,可用于分页游标 |
61
+ | data.newsCommonItems[].data.tid | string | 否 | 关联帖子/话题 ID |
62
+ | data.newsCommonItems[].data.newsContentType | string | 否 | 内容类型,如 "IMG_TEXT"(图文)、"LINK"(跳转) |
63
+ | data.newsCommonItems[].data.title | string | 否 | 新闻标题 |
64
+ | data.newsCommonItems[].data.image | string | 否 | 新闻封面图 URL |
65
+ | data.newsCommonItems[].data.showComment | number | 否 | 是否展示评论,1 表示展示,0 表示不展示 |
66
+ | data.newsCommonItems[].data.replyCount | number | 否 | 回复数 |
67
+ | data.newsCommonItems[].data.lightReplyCount | number | 否 | 亮回复数 |
68
+ | data.newsCommonItems[].data.publishTime | string | 否 | 发布时间,ISO 8601 格式,如 "2026-07-21T20:18:28.000+08:00" |
69
+ | data.ad_page_id | string | 否 | 广告页标识,如 "nba.news" |
70
+ | data.reqNo | string | 否 | 本次请求流水号 |
71
+
72
+ # Examples
73
+
74
+ ```javascript
75
+ window.ShaperAI.request.news.newsCommonList({ source: "nav_category_news", tagCode: "fifa" }).then(res => { if (res.code === 200) { console.log(res.data); } })
76
+ ```
77
+
78
+ # Frontend Request Guard
79
+
80
+ | 策略 | 默认值 |
81
+ | --- | --- |
82
+ | 同请求在途合并窗口 | 不启用(0ms) |
83
+ | GET 缓存 TTL | 不启用(0ms) |
84
+ | 请求超时 | 8000ms |
85
+ | 单能力最大并发 | 不限制 |
86
+ | 单能力分钟调用上限 | 不限制 |
87
+ | 同 URL 窗口调用上限 | 20 次 / 10000ms(超过限制排队等待) |
88
+ | 同页面同接口窗口调用上限(去掉 query/hash 参数) | 20 次 / 5000ms(首次超过限制返回 429,后续同窗口请求静默丢弃,异常日志只上报一次) |
89
+ | 连续失败熔断 | 3 次失败后熔断 30000ms |
90
+ | 自动分页建议上限 | 5 页 |
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: hupu-request-news-player-news-list
3
+ description: 获取指定球员的最新资讯,支持翻页加载更多,用于球员资讯流展示。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.request.news.playerNewsList(params)`
9
+
10
+ # Constraints
11
+
12
+ - 请求接口数据必须使用 window.ShaperAI.request 能力及其子能力发起,禁止使用 fetch、axios、XMLHttpRequest、第三方请求库或其它自定义请求方式。
13
+ - 数据能力调用必须避免无条件循环、无限轮询和重复渲染触发;同一参数的返回结果应优先保存在组件状态中复用。
14
+ - 列表/分页类接口连续自动翻页最多 5 页,必须在无下一页、返回空列表或达到页数上限时停止。
15
+ - SDK 前端已启用请求保护:默认不限制单能力并发和分钟调用量,不启用相同请求在途合并或 GET 短缓存;同 URL 在 10000ms 内最多 20 次;同一页面同接口(去掉 query/hash 参数后相同即为同一接口)在 5000ms 内最多 20 次,首次超过限制返回 429,后续同窗口请求静默丢弃,且同一窗口内只上报一次异常日志。不要自行循环重试或重复触发请求,若接口真实返回 408、429 或 503 等错误码,必须停止继续请求并给用户友好提示。
16
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | playerId | string | 是 | 球员ID,例如 "1901000000473842" (篮球) 或 "30389" (足球) |
23
+ | newsId | string | 否 | 用于分页的分界新闻ID,取上一页 data 数组最后一项的 nid,不传则默认为第一页。 |
24
+ | page | number | 否 | 当前页码,仅篮球分类分页时有效,不传则默认为第一页。 |
25
+ | category | string | 是 | 赛事类别:basketball(篮球) 或 football(足球) |
26
+
27
+ # Returns
28
+
29
+ - Type: `Promise<Response>`
30
+
31
+ ### Response Properties
32
+
33
+ | 属性名 | 类型 | 是否必填 | 说明 |
34
+ | --- | --- | --- | --- |
35
+ | code | number | 是 | 状态码。200 表示成功,401 表示未登录,404 表示内容不存在,500 表示服务器错误 |
36
+ | message | string | 是 | 错误提示信息。当 code 不等于 200 时必须用于向用户友好提示 |
37
+ | data | object | 否 | 成功时返回的数据载荷 |
38
+ | data.data | array | 否 | 新闻资讯列表 |
39
+ | data.data[].nid | string | 否 | 新闻唯一 ID,分页游标取列表最后一项的该字段 |
40
+ | data.data[].tid | string | 否 | 关联帖子/话题 ID |
41
+ | data.data[].type | string | 否 | 内容展示类型,如 IMG_TEXT(图文)、VIDEO(视频)、LINK(跳转) |
42
+ | data.data[].title | string | 否 | 新闻标题 |
43
+ | data.data[].img | string | 否 | 封面图 URL |
44
+ | data.data[].replies | number | 否 | 回复数 |
45
+ | data.data[].lights | number | 否 | 亮评数 |
46
+ | data.data[].link | string | 否 | 跳转链接,如 kanqiu://bbs/topic/{tid} |
47
+ | data.data[].linkType | string / null | 否 | 链接类型;type 为 LINK 时可能为 "POST",其余多为 null |
48
+ | data.data[].badge | array | 否 | 角标列表,可能为空数组 |
49
+ | data.data[].badge[] | object | 否 | 数组元素 |
50
+ | data.data[].publishTime | string | 否 | 发布时间,格式如 "2026-07-20 17:40:56" |
51
+ | data.data[].addTime | number | 否 | 发布时间戳(秒) |
52
+ | data.data[].oldNewsId | string / null | 否 | 旧版新闻 ID,可能为 null |
53
+ | data.data[].top | boolean | 否 | 是否置顶 |
54
+ | data.data[].pv | number / null | 否 | 浏览量,可能为 null |
55
+ | data.data[].gifList | array / null | 否 | 动图列表,可能为 null |
56
+ | data.data[].gifList[] | object | 否 | 数组元素 |
57
+ | data.data[].read | string | 否 | 已读标识,通常与 nid 相同 |
58
+ | data.data[].showComment | number | 否 | 是否展示评论,1 表示展示 |
59
+ | data.nextPage | number | 否 | 下一页页码;用于篮球分页的 page 参数 |
60
+
61
+ # Examples
62
+
63
+ ```javascript
64
+ window.ShaperAI.request.news.playerNewsList({ playerId: "1901000000473842", category: "basketball" }).then(res => { if (res.code === 200) { console.log(res.data); } })
65
+ ```
66
+
67
+ # Frontend Request Guard
68
+
69
+ | 策略 | 默认值 |
70
+ | --- | --- |
71
+ | 同请求在途合并窗口 | 不启用(0ms) |
72
+ | GET 缓存 TTL | 不启用(0ms) |
73
+ | 请求超时 | 8000ms |
74
+ | 单能力最大并发 | 不限制 |
75
+ | 单能力分钟调用上限 | 不限制 |
76
+ | 同 URL 窗口调用上限 | 20 次 / 10000ms(超过限制排队等待) |
77
+ | 同页面同接口窗口调用上限(去掉 query/hash 参数) | 20 次 / 5000ms(首次超过限制返回 429,后续同窗口请求静默丢弃,异常日志只上报一次) |
78
+ | 连续失败熔断 | 3 次失败后熔断 30000ms |
79
+ | 自动分页建议上限 | 5 页 |
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: hupu-request-news-subject-news
3
+ description: 获取专题(Subject)下的关联新闻列表,用于专题页资讯展示。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.request.news.subjectNews(params)`
9
+
10
+ # Constraints
11
+
12
+ - 请求接口数据必须使用 window.ShaperAI.request 能力及其子能力发起,禁止使用 fetch、axios、XMLHttpRequest、第三方请求库或其它自定义请求方式。
13
+ - 数据能力调用必须避免无条件循环、无限轮询和重复渲染触发;同一参数的返回结果应优先保存在组件状态中复用。
14
+ - 列表/分页类接口连续自动翻页最多 5 页,必须在无下一页、返回空列表或达到页数上限时停止。
15
+ - SDK 前端已启用请求保护:默认不限制单能力并发和分钟调用量,不启用相同请求在途合并或 GET 短缓存;同 URL 在 10000ms 内最多 20 次;同一页面同接口(去掉 query/hash 参数后相同即为同一接口)在 5000ms 内最多 20 次,首次超过限制返回 429,后续同窗口请求静默丢弃,且同一窗口内只上报一次异常日志。不要自行循环重试或重复触发请求,若接口真实返回 408、429 或 503 等错误码,必须停止继续请求并给用户友好提示。
16
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | newsId | string | 是 | 新闻帖唯一ID,例如 "22224850" |
23
+
24
+ # Returns
25
+
26
+ - Type: `Promise<Response>`
27
+
28
+ ### Response Properties
29
+
30
+ | 属性名 | 类型 | 是否必填 | 说明 |
31
+ | --- | --- | --- | --- |
32
+ | code | number | 是 | 状态码。200 表示成功,401 表示未登录,404 表示内容不存在,500 表示服务器错误 |
33
+ | message | string | 是 | 错误提示信息。当 code 不等于 200 时必须用于向用户友好提示 |
34
+ | data | object | 否 | 成功时返回的数据载荷 |
35
+ | data.nid | string | 否 | 专题 ID |
36
+ | data.signboard | string | 否 | 专题标识文案,如 "专题" |
37
+ | data.title | string | 否 | 专题标题 |
38
+ | data.img | string | 否 | 专题封面图 URL |
39
+ | data.replies | number | 否 | 专题总评论数 |
40
+ | data.lights | number | 否 | 专题总亮评/点赞数 |
41
+ | data.newsCount | number | 否 | 专题关联新闻总数 |
42
+ | data.groups | array | 否 | 按场次/主题划分的新闻分组列表 |
43
+ | data.groups[].orderBy | string | 否 | 分组排序序号,如 "1" |
44
+ | data.groups[].title | string | 否 | 分组标题,如 "奇才92-88爵士" |
45
+ | data.groups[].news | array | 否 | 该分组下的新闻列表 |
46
+ | data.groups[].news[].nid | string | 否 | 新闻 ID |
47
+ | data.groups[].news[].tid | string | 否 | 帖子/话题 ID |
48
+ | data.groups[].news[].type | string | 否 | 新闻类型,如 "IMG_TEXT" |
49
+ | data.groups[].news[].title | string | 否 | 新闻标题 |
50
+ | data.groups[].news[].img | string | 否 | 封面图 URL |
51
+ | data.groups[].news[].replies | number | 否 | 评论数 |
52
+ | data.groups[].news[].lights | number | 否 | 亮评/点赞数 |
53
+ | data.groups[].news[].link | string | 否 | 跳转链接(如 kanqiu://bbs/topic/...) |
54
+ | data.groups[].news[].linkType | string / null | 否 | 链接类型(可能为 null) |
55
+ | data.groups[].news[].badge | array | 否 | 角标列表 |
56
+ | data.groups[].news[].badge[] | object | 否 | 数组元素 |
57
+ | data.groups[].news[].publishTime | string | 否 | 发布时间,如 "2026-07-10 11:08:58" |
58
+ | data.groups[].news[].addTime | number | 否 | 添加时间戳 |
59
+ | data.groups[].news[].oldNewsId | string | 否 | 旧新闻 ID |
60
+ | data.groups[].news[].top | boolean | 否 | 是否置顶 |
61
+ | data.groups[].news[].pv | number / null | 否 | 阅读量(可能为 null) |
62
+ | data.groups[].news[].gifList | array / null | 否 | GIF 列表(可能为 null) |
63
+ | data.groups[].news[].read | string | 否 | 已读标识,通常与 nid 相同 |
64
+ | data.groups[].news[].showComment | number | 否 | 是否展示评论,1 表示展示 |
65
+ | data.share | object | 否 | 分享信息 |
66
+ | data.share.url | string | 否 | 分享落地页 URL |
67
+ | data.share.summary | string | 否 | 分享摘要 |
68
+ | data.share.img | string | 否 | 分享图片 URL |
69
+ | data.share.title | string | 否 | 分享标题 |
70
+
71
+ # Examples
72
+
73
+ ```javascript
74
+ window.ShaperAI.request.news.subjectNews({ newsId: "22224850" }).then(res => { if (res.code === 200) { console.log(res.data); } })
75
+ ```
76
+
77
+ # Frontend Request Guard
78
+
79
+ | 策略 | 默认值 |
80
+ | --- | --- |
81
+ | 同请求在途合并窗口 | 不启用(0ms) |
82
+ | GET 缓存 TTL | 不启用(0ms) |
83
+ | 请求超时 | 8000ms |
84
+ | 单能力最大并发 | 不限制 |
85
+ | 单能力分钟调用上限 | 不限制 |
86
+ | 同 URL 窗口调用上限 | 20 次 / 10000ms(超过限制排队等待) |
87
+ | 同页面同接口窗口调用上限(去掉 query/hash 参数) | 20 次 / 5000ms(首次超过限制返回 429,后续同窗口请求静默丢弃,异常日志只上报一次) |
88
+ | 连续失败熔断 | 3 次失败后熔断 30000ms |
89
+ | 自动分页建议上限 | 5 页 |
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: hupu-request-news-team-news-list
3
+ description: 获取指定球队的最新资讯,支持翻页加载更多,用于球队资讯流展示。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.request.news.teamNewsList(params)`
9
+
10
+ # Constraints
11
+
12
+ - 请求接口数据必须使用 window.ShaperAI.request 能力及其子能力发起,禁止使用 fetch、axios、XMLHttpRequest、第三方请求库或其它自定义请求方式。
13
+ - 数据能力调用必须避免无条件循环、无限轮询和重复渲染触发;同一参数的返回结果应优先保存在组件状态中复用。
14
+ - 列表/分页类接口连续自动翻页最多 5 页,必须在无下一页、返回空列表或达到页数上限时停止。
15
+ - SDK 前端已启用请求保护:默认不限制单能力并发和分钟调用量,不启用相同请求在途合并或 GET 短缓存;同 URL 在 10000ms 内最多 20 次;同一页面同接口(去掉 query/hash 参数后相同即为同一接口)在 5000ms 内最多 20 次,首次超过限制返回 429,后续同窗口请求静默丢弃,且同一窗口内只上报一次异常日志。不要自行循环重试或重复触发请求,若接口真实返回 408、429 或 503 等错误码,必须停止继续请求并给用户友好提示。
16
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | teamId | string | 是 | 球队ID,例如 "1902000003703898" (篮球) 或 "5568" (足球) |
23
+ | newsId | string | 否 | 用于分页的分界新闻ID,取上一页 data 数组最后一项的 nid,不传则默认为第一页。 |
24
+ | category | string | 是 | 赛事类别:basketball(篮球) 或 football(足球) |
25
+
26
+ # Returns
27
+
28
+ - Type: `Promise<Response>`
29
+
30
+ ### Response Properties
31
+
32
+ | 属性名 | 类型 | 是否必填 | 说明 |
33
+ | --- | --- | --- | --- |
34
+ | code | number | 是 | 状态码。200 表示成功,401 表示未登录,404 表示内容不存在,500 表示服务器错误 |
35
+ | message | string | 是 | 错误提示信息。当 code 不等于 200 时必须用于向用户友好提示 |
36
+ | data | array | 否 | 球队资讯新闻列表 |
37
+ | data[].nid | string | 否 | 新闻唯一 ID,分页游标取列表最后一项的该字段 |
38
+ | data[].tid | string | 否 | 关联帖子/话题 ID |
39
+ | data[].type | string | 否 | 内容展示类型,如 IMG_TEXT、IMAGE_TOP_TEXT_BOTTOM |
40
+ | data[].title | string | 否 | 新闻标题 |
41
+ | data[].img | string | 否 | 封面图 URL |
42
+ | data[].replies | number | 否 | 回复数 |
43
+ | data[].lights | number | 否 | 亮评数 |
44
+ | data[].link | string | 否 | 跳转链接,如 kanqiu://bbs/topic/{tid} |
45
+ | data[].linkType | string / null | 否 | 链接类型,可能为 null |
46
+ | data[].badge | array | 否 | 角标列表 |
47
+ | data[].badge[] | object | 否 | 数组元素 |
48
+ | data[].publishTime | string | 否 | 发布时间,格式如 "2026-07-21 21:10:55" |
49
+ | data[].addTime | number | 否 | 发布时间戳(秒) |
50
+ | data[].oldNewsId | string / null | 否 | 旧版新闻 ID,可能为 null |
51
+ | data[].top | boolean | 否 | 是否置顶 |
52
+ | data[].pv | number / null | 否 | 浏览量,可能为 null |
53
+ | data[].gifList | array / null | 否 | 动图列表,可能为 null |
54
+ | data[].gifList[] | object | 否 | 数组元素 |
55
+ | data[].read | string | 否 | 已读标识,通常与 nid 相同 |
56
+ | data[].showComment | number | 否 | 是否展示评论,1 表示展示 |
57
+
58
+ # Examples
59
+
60
+ ```javascript
61
+ window.ShaperAI.request.news.teamNewsList({ teamId: "1902000003703898", category: "basketball" }).then(res => { if (res.code === 200) { console.log(res.data); } })
62
+ ```
63
+
64
+ # Frontend Request Guard
65
+
66
+ | 策略 | 默认值 |
67
+ | --- | --- |
68
+ | 同请求在途合并窗口 | 不启用(0ms) |
69
+ | GET 缓存 TTL | 不启用(0ms) |
70
+ | 请求超时 | 8000ms |
71
+ | 单能力最大并发 | 不限制 |
72
+ | 单能力分钟调用上限 | 不限制 |
73
+ | 同 URL 窗口调用上限 | 20 次 / 10000ms(超过限制排队等待) |
74
+ | 同页面同接口窗口调用上限(去掉 query/hash 参数) | 20 次 / 5000ms(首次超过限制返回 429,后续同窗口请求静默丢弃,异常日志只上报一次) |
75
+ | 连续失败熔断 | 3 次失败后熔断 30000ms |
76
+ | 自动分页建议上限 | 5 页 |
@@ -0,0 +1,9 @@
1
+ # 存档与恢复
2
+
3
+ 云存档、本地数据保存和恢复。本目录仅分类,技能内容暂不重构。
4
+
5
+ - [hupu-cloud-save](hupu-cloud-save/SKILL.md)
6
+ - [hupu-cloud-save-load](hupu-cloud-save-load/SKILL.md)
7
+ - [hupu-cloud-save-save](hupu-cloud-save-save/SKILL.md)
8
+ - [hupu-storage-get-value](hupu-storage-get-value/SKILL.md)
9
+ - [hupu-storage-set-value](hupu-storage-set-value/SKILL.md)
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: hupu-cloud-save
3
+ description: 通过 ShaperAI 云存档保存和恢复用户进度、草稿、选择和个人设置;用于接入存档读写、设计最小存档数据及控制读写成本。
4
+ ---
5
+
6
+ # 云存档
7
+
8
+ 优先使用 `window.ShaperAI.cloudSave.save` / `.load` 保存和恢复用户数据。结合游戏或应用的实际功能选择保存内容和时机,接入云存档不代表需要自动保存。
9
+
10
+ 旧 `cloudSave.getValue/setValue` 保留用法,已有应用可继续使用,维护时见 [旧接口用法与迁移方案](references/legacy-migration.md)。新应用、新接入功能首选本文的 `save/load`;只有决定切换已有存档时才执行迁移,不因升级 SDK 强制迁移。
11
+
12
+ ## 接口与存档位
13
+
14
+ 在 `window.ShaperAI` 可用后调用:
15
+
16
+ | 操作 | 调用 | 成功结果 |
17
+ | --- | --- | --- |
18
+ | 读取 | `window.ShaperAI.cloudSave.load({ slot: 1 })` | `code === 200`,`data` 为字符串或 `null` |
19
+ | 保存 | `window.ShaperAI.cloudSave.save({ slot: 1, value })` | `code === 200` |
20
+
21
+ - **编号**:每个应用最多五个存档位,`slot` 只接受 number 类型的整数 1–5,字符串 `"1"`、小数或越界值返回 400。不同用户、应用和活动的存档相互独立。
22
+ - **分配**:固定编号用途,通常一个就够,建议最多使用三个。一起恢复、一起保存的小字段放同一个对象;保存时机或加载需求独立时再分配其它编号,不按字段拆分或每次编辑轮换。
23
+ - **覆盖**:读写使用相同编号;同编号保存会完整替换旧值,不会合并对象字段。多个功能共用一个对象时,从当前有效数据构造完整快照,不能只提交某个功能的局部字段;需要保持一致的数据放同一存档,多个存档位分别保存不保证一起成功。
24
+ - **内容**:`value` 必须为字符串;普通文本直接保存,对象使用 `JSON.stringify`。每个存档最多 `2 * 1024 * 1024` UTF-8 bytes,超限返回 413;限制按字节计算,不是字符串长度。
25
+ - **结果**:先判断 `code`,只有 200 表示成功。读取成功且 `data === null` 才表示没有存档;`""` 是有效值,不能用 `if (!data)` 判断。
26
+
27
+ ## 使用场景
28
+
29
+ 用户希望刷新页面或退出后重新进入时继续使用,可用云存档恢复必要内容。只在业务需要恢复进度、内容或设置时接入,按下表确定保存内容与时机。
30
+
31
+ | 场景 | 保存的最小数据 | 保存时机 | 恢复方式 |
32
+ | --- | --- | --- | --- |
33
+ | 游戏、剧情或模拟经营续玩 | 当前关卡/章节/回合、必要分支选择、无法由其它字段重建的角色或经营状态 | 完成关卡、回合结算、关键选择或用户点击保存时;不逐帧保存 | 进入时提供继续入口,读取后恢复检查点;关卡资源和静态规则重新加载 |
34
+ | 表单、问卷或文本草稿 | 未提交的用户正文、已填写答案、必要选项 ID、成功上传的附件引用 | 点击存草稿、确认步骤时;需要防止长时间填写因中断丢失时,再合并输入变化自动保存 | 回到编辑入口时恢复未提交内容;选项字典重新获取,校验提示重新计算 |
35
+ | 选择、收藏、排序或自定义组合 | 选中项的稳定 ID,必要的顺序、分组、位置和用户自定义字段 | 用户确认选择、排序结束或点击保存时 | 按 ID 获取详情,恢复用户关系与顺序;失效或已删除条目提示用户处理 |
36
+ | 多步骤配置、创作向导或操作流程 | 当前检查点、已完成步骤、各步必要输入和继续操作所需的用户决定 | 确认步骤、完成阶段或主动暂存时 | 打开相应流程后校验已存输入,再继续未完成步骤;流程定义和进度比例重新获取或计算 |
37
+ | 用户作品或编辑方案 | 用户编写内容、可编辑配置、必要元素 ID/位置/关系、上传后的资源引用 | 点击保存作品/方案;需要持续保护未手动保存的创作内容时,再合并编辑变化自动保存 | 打开作品编辑器时恢复可编辑数据;素材详情和渲染结果按需重建,不存整个画布运行状态或预览 Base64 |
38
+ | 个人设置 | 用户实际修改且需保留的音乐、音效、显示或操作偏好 | 用户确认设置或合并同次设置变更后 | 需要这些设置时读取并与当前默认值合并,只应用已支持的字段 |
39
+ | 有限的个人记录或结果回顾 | 业务确需保留的少量历史选择、个人结果摘要及必要时间信息 | 一次操作完成或结果确定后 | 用户打开记录页时按需读取;限制条数或时间范围,详情可重取时只存 ID |
40
+
41
+ 这些场景可以共用存档:同一次恢复、同一节奏保存的数据放一起;需要独立加载或覆盖的草稿、方案才分配其它存档位。若产品提供多个手动存档,固定编号与界面入口的对应关系,覆盖已有存档前让用户明确选择;最多五个,建议最多使用三个,不自动为每次操作创建新存档。
42
+
43
+ 云存档用于恢复个人内容;流程涉及正式提交、奖励、交易或排名时,完成状态以对应业务接口为准,不能仅因恢复了存档就重新提交、发放奖励或认定操作成功。
44
+
45
+ ## 保存时机选择
46
+
47
+ - **无需恢复就不保存**:一次性小游戏、即时结果页或临时交互若没有续玩、草稿或设置恢复需求,不添加存档或自动保存。
48
+ - **明确节点足够就按节点保存**:游戏在关卡完成、回合结算、检查点保存;应用在用户点击保存、确认步骤或应用设置时保存。节点已经覆盖恢复需求时,不额外增加定时器或监听所有状态变化。若产品约定点击保存才生效,未确认的编辑不自动覆盖正式存档。
49
+ - **确有中途保护需求才持续自动保存**:例如长篇草稿、持续创作,或检查点间隔较长且需要恢复中途进度的游戏;仅对需要保护的内容启用,结合可恢复的有效状态和可接受的进度损失选择触发时机,再合并连续变化。页面其他功能不因此一并启用自动保存。
50
+
51
+ ## 重置、提交与旧存档
52
+
53
+ - **重新开始或清空草稿**:当前只有保存和读取,没有删除接口。业务需要清空时,明确约定并保存可识别的空状态;写入空字符串仍是已有存档,不会让读取返回 null。用户确认重置后,先停旧自动保存并处理在途写入,再保存空状态;只有成功后才提示云端已清空,失败保留原内容和待处理状态。
54
+ - **正式提交后的草稿**:仅在业务接口确认提交成功后,按产品需要更新或清空对应草稿,防止下次恢复出已提交内容;只清理本次提交的快照,不能清掉提交期间新增的编辑。业务提交成功而草稿清理失败时分别反馈,不因清理失败重复提交业务。
55
+ - **应用升级后的兼容**:恢复时兼容已知旧字段,对兼容数据的缺省字段补默认值;不兼容或无法识别的格式保留原存档并提示,不自动用默认值覆盖,也不随意改变已有编号用途。仅在确有多种格式需要区分时增加业务版本字段,不强制所有存档加版本或迁移框架。
56
+
57
+ ## 只存恢复必需的数据
58
+
59
+ 按“下次恢复需要什么”选择字段:只保存无法可靠重建的用户内容、有效进度、必要选择和个人设置。按字段白名单构造对象,不序列化整个页面 state、store 或接口响应。
60
+
61
+ 引用已有数据时优先只存稳定 ID 及必要关系、顺序或自定义字段,不保存完整对象或列表响应。例如:
62
+
63
+ ```javascript
64
+ const value = JSON.stringify({
65
+ selectedIds: selectedItems.map(item => item.id),
66
+ });
67
+ // 恢复时按 ID 获取详情;业务需要保留排序时,按 selectedIds 的顺序展示。
68
+ ```
69
+
70
+ - **必要内容完整保留**:详情无法重新获取且恢复必需时,保存最少必要字段;名称仅在需要保留当时显示内容,或无可靠 ID 且仅用于展示时保存,不能替代稳定 ID。草稿正文等不可重建内容不能静默截断。
71
+ - **资源上传后存引用**:使用项目已有上传能力,上传成功后只存稳定 ID 或可恢复地址,不存资源对象、图片/音视频二进制或 Base64。临时预览地址、会过期且无法重新获取的地址不能作为唯一引用。
72
+ - **排除冗余与临时状态**:不存可计算值、可重取数据、静态配置、loading、弹窗开关、动画/逐帧状态、DOM、组件实例、请求缓存或调试日志。业务确需历史记录时限定保留范围,避免无限追加;不存 token、密码、Cookie 等敏感凭证。
73
+
74
+ ## 最小读写示例
75
+
76
+ 以下示例约定 1 号存档保存草稿文本。实际页面在读取入口和保存事件中捕获异常、展示结果,并保留失败时的用户编辑。
77
+
78
+ ```javascript
79
+ const DRAFT_SLOT = 1;
80
+
81
+ async function loadDraft() {
82
+ const res = await window.ShaperAI.cloudSave.load({ slot: DRAFT_SLOT });
83
+ if (res.code !== 200) throw new Error(res.message || "读取失败");
84
+ return res.data; // string | null,调用方按业务处理无记录的情况
85
+ }
86
+
87
+ async function saveDraft(text) {
88
+ const res = await window.ShaperAI.cloudSave.save({ slot: DRAFT_SLOT, value: text });
89
+ if (res.code !== 200) throw new Error(res.message || "保存失败");
90
+ }
91
+
92
+ // 例如保存按钮的异步事件处理函数:
93
+ async function onSaveDraft(text) {
94
+ try {
95
+ await saveDraft(text);
96
+ console.log("保存成功"); // 实际页面替换为提示
97
+ } catch (error) {
98
+ console.warn(error.message); // 实际页面展示错误,保留未保存内容
99
+ }
100
+ }
101
+ ```
102
+
103
+ 保存对象时先构造白名单数据,再 `JSON.stringify`;读取成功且非 null 后才 `JSON.parse`,捕获解析异常并校验所用字段的类型和范围,只提取白名单字段。普通字符串直接使用。JSON 数据使用能可靠往返还原的类型;大整数 ID 保留字符串,日期或特殊类型按业务显式转换,序列化失败或可能丢失必要字段时不提交残缺数据。
104
+
105
+ ## 读写成本与恢复时序
106
+
107
+ - **按需读**:只读当前需要的存档,不启动时全量读、不轮询、不随渲染或保存成功重复读。同一用户/应用/活动/存档位复用在途请求或页面内结果;明确刷新时重新读取。失败不缓存成无记录,缓存不等于云端最新值;写入成功后更新或失效缓存,写入前的旧读取不能回填旧值。
108
+ - **有变化才写**:只在必需字段变化时标记待保存;无变化不序列化、不请求。可与当前用户/应用/活动/存档位上次成功读取或写入的字符串比较,相同则跳过,失败不更新成功记录。
109
+ - **写入时序**:手动保存防重复点击,同一存档位不重叠写,新变化留待下一次,旧请求成功不能清掉新变化。需要保留的内容在选定的保存节点写入,不只依赖页面关闭时的异步保存。
110
+ - **仅在启用持续自动保存时合并变化**:连续输入或编辑按需防抖或节流,同一存档位至少间隔 3 秒,并按可接受的进度损失设置最长等待,避免持续编辑一直推迟。3 秒是最小间隔,不是要求每 3 秒保存;无变化不写,手动保存或明确业务节点不必等待该间隔。仅按节点保存的功能无需实现这套调度。
111
+ - **先恢复再自动写回**:已启用自动保存且需要恢复的存档,在成功读取、解析和校验前暂停自动写回,避免默认值覆盖已有数据;晚返回的读取不能覆盖新编辑。只有读取成功且无存档时才按新记录处理;普通手动保存不要求先读取。
112
+ - **切换时清理**:组件卸载或切换用户/应用/活动/存档位时,清理定时器、监听、缓存和待写任务,忽略旧请求结果,避免旧用户的待保存内容写到新用户下。忽略结果不能撤销已发出的写入;重置、切换后回到同一存档时,也要避免旧在途写入覆盖新状态。
113
+ - **减少同步工作**:提交前仅序列化最小数据一次并复用;不在输入、渲染或逐帧回调中反复深拷贝、序列化和计算大小。JSON.parse/stringify 是同步操作,放进 async 函数仍占用主线程。
114
+ - **验证实际成本**:2MiB 是上限而非目标,按恢复需求设体积预算,检查完整字符串的 UTF-8 bytes、典型操作的请求次数和序列化/解析耗时,并确认精简后仍能恢复。超预算先删冗余,不默认引入压缩、分片或复杂框架;性能记录只记大小、耗时和结果,不记正文。
115
+
116
+ ## 失败处理
117
+
118
+ Promise 完成不代表业务成功,只有保存返回 200 才提示“已保存”。请求异常或 `code !== 200` 时展示错误、保留未保存内容;读取、解析或字段校验失败不能当成无记录,也不能自动写回默认值。
119
+
120
+ | 结果 | 处理 |
121
+ | --- | --- |
122
+ | `401` | 引导登录 |
123
+ | `400` | 检查参数和配置 |
124
+ | `413` | 去冗余后仍超限时,提示并保留未保存内容;不截断必要内容或提交残缺存档 |
125
+ | `408`、`429`、`503` 或 `204 + dropped:true` | 提示失败,停止当前自动请求 |
126
+
127
+ 保存超时或网络中断时,结果可能尚未确认,不能断言云端没有写入。保留本次提交快照及后续编辑,暂停自动写;当前超时保护不会取消底层请求,不立即发起可能被旧请求覆盖的新写入。后续由用户触发核对或重试时,读取只能确认当时可见值,不能当作旧请求已结束的证明,也不能用读到的值覆盖新编辑。
128
+
129
+ 失败后保留待保存状态,但暂停该失败操作的自动提交;不得由定时器或待写队列立即重发,也不无限重试。
@@ -0,0 +1,111 @@
1
+ # 旧云存档接口用法与迁移方案
2
+
3
+ 维护已有使用 `window.ShaperAI.cloudSave.getValue({ key })` / `.setValue({ key, value })` 的应用,或准备迁移其存档时读取。这里的 get/set 指这两个云存档方法,不包括本地 `storage.*`。新应用、新接入功能首选主 Skill 的 `save/load`;旧接口继续可用,但不作为第一选择。
4
+
5
+ SDK 继续保留旧方法,旧应用可以继续运行,无须为升级 SDK 强制迁移。改用 `save/load` 时,新存档位与旧业务 key 不会自动关联,不能只替换方法名。迁移由应用明确旧 key 与目标 slot 的对应关系,SDK 不会枚举或自动搬运旧数据。
6
+
7
+ ## 继续使用旧接口
8
+
9
+ 在 `window.ShaperAI` 可用后调用:
10
+
11
+ | 操作 | 调用 | 成功结果 |
12
+ | --- | --- | --- |
13
+ | 读取旧存档 | `window.ShaperAI.cloudSave.getValue({ key })` | `code === 200`,`data` 为字符串或 null |
14
+ | 保存旧存档 | `window.ShaperAI.cloudSave.setValue({ key, value })` | `code === 200` |
15
+
16
+ - `key` 是非空业务字符串,沿用原应用的 key 及生成规则;同一用户、活动、key 再次保存会完整覆盖旧值。不要把 key 直接替换成 slot 编号,也不要在维护时任意改名,否则会读不到原存档。
17
+ - 旧接口按用户、活动和 key 定位,不会自动追加应用隔离前缀;维护时保留原 key 的应用前缀或生成规则。同活动下多个应用若共用同一个 key,会访问同一份旧数据,迁移前须确认其归属,不把共享数据误当成当前应用独有数据。
18
+ - `value` 必须为字符串,单个 key 最多 2MiB UTF-8 字节;对象先按白名单构造再 `JSON.stringify`。读取 JSON 存档时捕获解析异常并校验字段,不能以默认值覆盖无法识别的旧格式。
19
+ - 只有读取返回 `200 + null` 表示无记录,空字符串是有效内容;写入空字符串不会删除记录。先检查 code,读取失败不得按无记录处理,保存失败保留用户编辑、不自动循环重试。
20
+ - 继续沿用适合该功能的保存时机,不因保留旧接口额外添加自动保存。主 Skill 的数据精简、恢复时序和失败处理同样适用于旧 key;slot 数量和编号限制仅适用于 `save/load`。
21
+
22
+ 下面演示沿用已有文本草稿 key 的读写;将 `draft` 换成原应用实际 key。由页面读取入口调用读取函数,保存事件调用保存函数,并在调用方捕获错误、提示结果、保留未保存内容。
23
+
24
+ ```javascript
25
+ const EXISTING_DRAFT_KEY = "draft";
26
+
27
+ async function loadExistingDraft() {
28
+ const result = await window.ShaperAI.cloudSave.getValue({ key: EXISTING_DRAFT_KEY });
29
+ if (result.code !== 200) throw new Error(result.message || "读取失败");
30
+ return result.data; // string | null;空字符串仍是有效存档。
31
+ }
32
+
33
+ async function saveExistingDraft(text) {
34
+ const result = await window.ShaperAI.cloudSave.setValue({
35
+ key: EXISTING_DRAFT_KEY,
36
+ value: text,
37
+ });
38
+ if (result.code !== 200) throw new Error(result.message || "保存失败");
39
+ }
40
+ ```
41
+
42
+ 以下内容仅用于已经决定从旧接口切换到 `save/load` 的应用;继续维护旧接口的应用无需执行迁移步骤。
43
+
44
+ ## 先确定映射与切换范围
45
+
46
+ - 确认实际加载的 SDK 提供 `save/load/getValue` 后再启用迁移入口;缺少新方法时继续原接口流程并先升级 SDK,不能停掉旧入口后才发现迁移不可用。
47
+ - 从原应用代码确认实际使用的 key、生成规则、数据格式和保存时机,不猜 key,也不扫描可能存在的 key。迁移沿用原用户、应用和活动;活动或应用标识变化需要另行安排数据迁移,不由此方案跨范围搬运。
48
+ - 为每组要迁移的数据固定目标 slot(1–5,建议最多三个),确认用途未被其他功能占用。独立内容可以分别迁移;多个旧 key 合并到一个 slot 时,先读齐必要数据、校验并构造完整对象,再一次保存,不能逐个 key 覆盖同一 slot。任何必要读取失败都停止;缺失数据是否允许补默认值由业务确定。
49
+ - 分批迁移按每组数据独立判断和切换,某个 slot 成功不代表其他数据已经迁移。合并多个旧 key 的逻辑一旦上线,后续新增来源字段应按格式升级处理,不能因目标非空就把后来加入的旧 key 当成已迁移,也不能覆盖已有新编辑。
50
+ - 旧格式与新格式相同可保留原字符串;格式调整时显式转换并校验,只精简可重建的冗余,保留必要正文。转换后仍受每个 slot 2MiB UTF-8 字节上限约束,不能截断必要数据。
51
+ - 先停旧保存入口、定时器和待写任务,处理已经发出的写入;在初始化恢复阶段完成迁移,再开放编辑和保存。页面退出或切换用户、应用、活动时使本次任务失效,旧结果不得应用到新页面;忽略结果不能撤销已经发出的写入。
52
+
53
+ ## 迁移顺序
54
+
55
+ 1. 调用 `load({ slot })`。失败就停止,不读取旧值覆盖目标;成功且 `data !== null` 时,校验并恢复新存档,**包括空字符串或业务空状态**,不再回退旧 key。新数据不兼容时保留并提示,不以旧值覆盖。
56
+ 2. 仅当新存档明确返回 `code === 200 && data === null`,调用 `getValue({ key: 旧key })`。失败就停止;成功且旧值为 null,按首次使用处理,不为迁移写入默认值。旧值是空字符串时仍属于有效存档。
57
+ 3. 校验旧值并按需转换,使用 `save({ slot, value })` 写入完整的新存档。只有返回 200 才认为迁移完成,并开放使用新接口的正常读写;失败保留旧云存档及本次读取的内容,提示迁移未完成,暂停后续写入,不静默回退到旧写入链路。
58
+ 4. 迁移成功后,这组数据统一使用 `save/load`,尚未迁移的独立数据保持原接口。保留旧 key 的数据,不清空、不删除、不持续双写。以后启动优先读取新 slot,不重复搬运旧数据;业务清空时在新 slot 保存可识别的空状态,避免旧数据被再次恢复。
59
+
60
+ 迁移写入超时也可能已经落库。停止自动重试;后续重新进入或用户主动核对时仍从读取新 slot 开始,不能用旧值无条件重写。读取只能确认当时可见值,不能证明旧超时请求已结束;在结果不确定时保持写入暂停,遵循主 Skill 的超时处理。
61
+
62
+ ## 单个文本草稿的接入示例
63
+
64
+ 下面仅演示已确认的一个旧文本 key 对应一个新 slot,不添加自动保存。`draft` 必须替换为原应用实际 key;目标编号须与应用的存档分配一致。JSON 或多个旧 key 需要按上文补充业务校验与转换,不能直接套用文本校验。
65
+
66
+ ```javascript
67
+ const DRAFT_SLOT = 1;
68
+ const LEGACY_DRAFT_KEY = "draft";
69
+
70
+ function requireSuccess(result, action) {
71
+ if (result.code !== 200) {
72
+ throw new Error(result.message || `${action}失败`);
73
+ }
74
+ }
75
+
76
+ function validateDraft(value) {
77
+ if (typeof value !== "string") throw new Error("草稿格式不兼容");
78
+ return value;
79
+ }
80
+
81
+ // 调用期间禁止编辑/保存;同一初始化任务只运行一次。
82
+ // assertCurrent 由页面生命周期提供:退出或上下文切换后抛错。
83
+ async function restoreOrMigrateDraft(assertCurrent) {
84
+ const cloudSave = window.ShaperAI.cloudSave;
85
+ assertCurrent();
86
+ const current = await cloudSave.load({ slot: DRAFT_SLOT });
87
+ assertCurrent();
88
+ requireSuccess(current, "读取新存档");
89
+ if (current.data !== null) return validateDraft(current.data);
90
+
91
+ const legacy = await cloudSave.getValue({ key: LEGACY_DRAFT_KEY });
92
+ assertCurrent();
93
+ requireSuccess(legacy, "读取旧存档");
94
+ if (legacy.data === null) return null;
95
+
96
+ const value = validateDraft(legacy.data);
97
+ const saved = await cloudSave.save({ slot: DRAFT_SLOT, value });
98
+ assertCurrent();
99
+ requireSuccess(saved, "迁移草稿");
100
+ return value;
101
+ }
102
+ ```
103
+
104
+ 调用方捕获异常、提示错误并保留已有内容;不能在 catch 中把返回值当 null、写默认值或开放尚未完成迁移的保存入口。成功返回 null 才按首次使用处理。页面生命周期检查应覆盖用户、应用、活动和本次初始化任务,不使用永远通过的空函数。
105
+
106
+ ## 上线与回退
107
+
108
+ - 验证新 slot 有数据时不读旧 key、不写入;两边都无记录时不写入;旧空字符串能迁移;读取失败、转换失败、超限、写入失败时不丢原数据;迁移成功后再次进入不重复搬运;切换页面时不应用旧结果。
109
+ - 迁移入口按用户首次使用新版本时执行。不能只因发版一段时间就移除旧读取逻辑,长期未打开应用的用户可能尚未迁移;待确认迁移覆盖情况后再移除。
110
+ - 保留旧 key 是保留迁移前副本,不代表旧应用能看到迁移后的新编辑。回退应用版本时,应保留读取新 slot 的能力;否则先安排受控的数据回迁,再恢复旧写入入口。不要直接回退到只读旧 key 的版本并宣称数据无损。
111
+ - 迁移方案不需要服务端批量修改数据,搬运时仅用旧 `getValue` 读取、新 `save` 写入,不持续双写;这不影响尚未迁移的应用继续使用旧 `setValue` 保存。
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: hupu-cloud-save-load
3
+ description: 从指定云存档位恢复用户进度、草稿、选择或个人设置;编号为 1–5,成功时返回字符串,无存档时返回 null。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.cloudSave.load(params)`
9
+
10
+ # Constraints
11
+
12
+ - 新接入首选 save/load;已有 getValue/setValue 应用可继续使用原接口。新 slot 为 null 不代表旧 key 无数据,切换接口前按 hupu-cloud-save/SKILL.md 的迁移方案处理,不强制迁移
13
+ - 先判断 code;只有 code === 200 且 data === null 才表示没有存档,空字符串是有效值。仅对业务保存的 JSON 做解析,捕获解析异常并校验所用字段的类型和范围,只提取白名单字段
14
+ - 按需读取,不启动时全量读、不轮询、不随渲染或保存成功重复读;同一用户/应用/活动/存档位复用在途请求或页面内结果,显式刷新时重新读取;失败不缓存成无记录,缓存不等于云端最新值
15
+ - 读取存档不要求启用自动保存,保存方式按实际功能选择;已启用自动保存且需要恢复时,成功读取、解析和校验前暂停自动写回。旧读取不能覆盖新编辑,写入成功后更新或失效缓存,写入前的旧读取不能回填。卸载或切换用户/应用/活动/存档位时清理相关缓存和任务,忽略旧结果
16
+ - 读取、解析或校验失败时提示并保留用户编辑,不能按无记录处理或自动写回默认值;暂停该失败操作的自动提交,不由定时器或队列立即重发、不无限重试。存档分配、场景与失败处理见 hupu-cloud-save/SKILL.md
17
+ - 升级后兼容已知旧字段,仅给兼容数据的缺省字段补默认值;不兼容格式保留原存档并提示,不自动覆盖。空字符串不会因业务清空变成 null;保存超时后的读取只确认当时可见值,不代表旧写入已结束,不覆盖新编辑。重置与旧存档处理见 hupu-cloud-save/SKILL.md
18
+
19
+ # Parameters
20
+
21
+ | 参数名 | 类型 | 是否必填 | 说明 |
22
+ | --- | --- | --- | --- |
23
+ | slot | integer | 是 | 存档编号,与保存时保持一致,只接受 1–5 的整数 |
24
+
25
+ # Returns
26
+
27
+ - Type: `Promise<Response>`
28
+
29
+ ### Response Properties
30
+
31
+ | 属性名 | 类型 | 是否必填 | 说明 |
32
+ | --- | --- | --- | --- |
33
+ | code | number | 是 | SDK 状态码,成功为 200;参数或网络失败时为错误码 |
34
+ | message | string | 是 | 结果说明 |
35
+ | data | string / null | 是 | 存档字符串;没有记录时为 null |
36
+
37
+ # Examples
38
+
39
+ ```javascript
40
+ window.ShaperAI.cloudSave.load({ slot: 1 }).then(res => { if (res.code !== 200) throw new Error(res.message || "读取失败"); if (res.data === null) console.log("暂无存档"); else console.log(res.data); }).catch(error => console.warn(error.message));
41
+ ```