@hupu-tech/shaper 0.2.12 → 0.2.14

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 (192) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +6 -0
  3. package/dist/auth/auth.d.ts +1 -0
  4. package/dist/cli.js +2 -2
  5. package/dist/cloud/client.d.ts +0 -1
  6. package/dist/cloud/service-build.d.ts +2 -4
  7. package/dist/index.js +1 -1
  8. package/dist/platform/api.d.ts +2 -0
  9. package/dist/project/create.d.ts +9 -3
  10. package/dist/project/delivery.d.ts +5 -5
  11. package/dist/runtime.d.ts +2 -1
  12. package/dist/runtime.js +1 -1
  13. package/dist/shared-UKIFY6QO.js +19 -0
  14. package/package.json +1 -1
  15. package/skills/business/SKILL.md +158 -0
  16. package/skills/business/activity/README.md +14 -0
  17. package/skills/business/activity/hupu-leaderboard-template/SKILL.md +52 -0
  18. package/skills/business/activity/hupu-leaderboard-template/example/README.md +20 -0
  19. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/.cloudignore +3 -0
  20. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/index.js +218 -0
  21. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/package.json +15 -0
  22. package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
  23. package/skills/business/activity/hupu-leaderboard-template/example/index.html +291 -0
  24. package/skills/business/activity/hupu-leaderboard-template/example/migrations/20260828210000_create_leaderboard.sql +54 -0
  25. package/skills/business/activity/hupu-lottery-draw/SKILL.md +50 -0
  26. package/skills/business/activity/hupu-lottery-draw/example/README.md +21 -0
  27. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/.cloudignore +3 -0
  28. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/index.js +142 -0
  29. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/package.json +9 -0
  30. package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
  31. package/skills/business/activity/hupu-lottery-draw/example/index.html +178 -0
  32. package/skills/business/activity/hupu-lottery-draw/example/migrations/20260828220000_create_draw.sql +193 -0
  33. package/skills/business/activity/hupu-pk-voting/SKILL.md +54 -0
  34. package/skills/business/activity/hupu-pk-voting/example/README.md +44 -0
  35. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/.cloudignore +3 -0
  36. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/index.js +370 -0
  37. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/package.json +15 -0
  38. package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/scf_bootstrap +2 -0
  39. package/skills/business/activity/hupu-pk-voting/example/index.html +729 -0
  40. package/skills/business/activity/hupu-pk-voting/example/migrations/20260828220000_create_pk_vote.sql +168 -0
  41. package/skills/business/activity/hupu-request-activity-execute-vote-task/SKILL.md +77 -0
  42. package/skills/business/activity/hupu-request-activity-get-vote-detail/SKILL.md +84 -0
  43. package/skills/business/activity/hupu-request-activity-get-vote-task-list/SKILL.md +86 -0
  44. package/skills/business/activity/hupu-request-activity-list-by-biz-keys/SKILL.md +153 -0
  45. package/skills/business/activity/hupu-request-activity-report-vote-task/SKILL.md +58 -0
  46. package/skills/business/activity/hupu-request-activity-submit-vote/SKILL.md +58 -0
  47. package/skills/business/activity/hupu-vote-task/SKILL.md +47 -0
  48. package/skills/business/community/README.md +13 -0
  49. package/skills/business/community/hupu-request-bbs-detail/SKILL.md +197 -0
  50. package/skills/business/community/hupu-request-bbs-get-tag-thread-list/SKILL.md +257 -0
  51. package/skills/business/community/hupu-request-bbs-get-topic-threads/SKILL.md +159 -0
  52. package/skills/business/community/hupu-request-bbs-gets-thread-post-list/SKILL.md +124 -0
  53. package/skills/business/community/hupu-request-bbs-open-post-editor/SKILL.md +75 -0
  54. package/skills/business/community/hupu-request-bbs-reply-post/SKILL.md +59 -0
  55. package/skills/business/community/hupu-score-add-score/SKILL.md +57 -0
  56. package/skills/business/community/hupu-score-get-item-detail/SKILL.md +173 -0
  57. package/skills/business/community/hupu-score-get-score/SKILL.md +263 -0
  58. package/skills/business/quality/README.md +7 -0
  59. package/skills/business/quality/hupu-security-check-audit/SKILL.md +39 -0
  60. package/skills/business/quality/hupu-wasm-compression/SKILL.md +69 -0
  61. package/skills/business/quality/hupu-wasm-compression/agents/openai.yaml +4 -0
  62. package/skills/business/quality/hupu-wasm-compression/tool/checks.mjs +90 -0
  63. package/skills/business/quality/hupu-wasm-compression/tool/compress-worker.mjs +40 -0
  64. package/skills/business/quality/hupu-wasm-compression/tool/public/app.js +84 -0
  65. package/skills/business/quality/hupu-wasm-compression/tool/public/index.html +80 -0
  66. package/skills/business/quality/hupu-wasm-compression/tool/public/style.css +3 -0
  67. package/skills/business/quality/hupu-wasm-compression/tool/server.mjs +126 -0
  68. package/skills/business/quality/hupu-web-security-audit/SKILL.md +45 -0
  69. package/skills/business/quality/hupu-web-security-audit/agents/openai.yaml +4 -0
  70. package/skills/business/rewards/README.md +13 -0
  71. package/skills/business/rewards/hupu-vacoin/SKILL.md +70 -0
  72. package/skills/business/rewards/hupu-vacoin-consume-coins/SKILL.md +47 -0
  73. package/skills/business/rewards/hupu-vacoin-get-coin-overview/SKILL.md +52 -0
  74. package/skills/business/rewards/hupu-vacoin-get-session-coins/SKILL.md +44 -0
  75. package/skills/business/rewards/hupu-vacoin-reset-session-id/SKILL.md +39 -0
  76. package/skills/business/rewards/hupu-vatask/SKILL.md +63 -0
  77. package/skills/business/rewards/hupu-vatask-complete-reward-video/SKILL.md +43 -0
  78. package/skills/business/rewards/hupu-vatask-consume-activity-chance/SKILL.md +48 -0
  79. package/skills/business/rewards/hupu-vatask-get-activity-task-state/SKILL.md +49 -0
  80. package/skills/business/runtime/README.md +13 -0
  81. package/skills/business/runtime/hupu-add-to-desktop/SKILL.md +51 -0
  82. package/skills/business/runtime/hupu-close-webview/SKILL.md +48 -0
  83. package/skills/business/runtime/hupu-cloud-auth/SKILL.md +43 -0
  84. package/skills/business/runtime/hupu-cloud-request/SKILL.md +56 -0
  85. package/skills/business/runtime/hupu-fullscreen-safe-top/SKILL.md +33 -0
  86. package/skills/business/runtime/hupu-navigate-to/SKILL.md +45 -0
  87. package/skills/business/runtime/hupu-request/SKILL.md +67 -0
  88. package/skills/business/runtime/hupu-seer-chat/SKILL.md +183 -0
  89. package/skills/business/runtime/hupu-track-report/SKILL.md +71 -0
  90. package/skills/business/sharing/README.md +7 -0
  91. package/skills/business/sharing/hupu-oss-upload-file/SKILL.md +40 -0
  92. package/skills/business/sharing/hupu-result-poster-posting/SKILL.md +37 -0
  93. package/skills/business/sharing/hupu-result-poster-posting/example/README.md +14 -0
  94. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/.cloudignore +3 -0
  95. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/index.js +187 -0
  96. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/package.json +15 -0
  97. package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
  98. package/skills/business/sharing/hupu-result-poster-posting/example/index.html +256 -0
  99. package/skills/business/sharing/hupu-result-poster-posting/example/migrations/20260828213000_create_result_poster_results.sql +60 -0
  100. package/skills/business/sharing/hupu-result-poster-posting/references/api-contract.md +46 -0
  101. package/skills/business/sharing/hupu-social-share/SKILL.md +27 -0
  102. package/skills/business/sports/README.md +27 -0
  103. package/skills/business/sports/hupu-request-basketball-player-info/SKILL.md +131 -0
  104. package/skills/business/sports/hupu-request-basketball-single-match/SKILL.md +158 -0
  105. package/skills/business/sports/hupu-request-basketball-team-info/SKILL.md +96 -0
  106. package/skills/business/sports/hupu-request-basketball-team-player-list/SKILL.md +108 -0
  107. package/skills/business/sports/hupu-request-basketball-team-salary-info/SKILL.md +85 -0
  108. package/skills/business/sports/hupu-request-football-coach-info/SKILL.md +76 -0
  109. package/skills/business/sports/hupu-request-football-live-room-news-list/SKILL.md +85 -0
  110. package/skills/business/sports/hupu-request-football-match-info/SKILL.md +126 -0
  111. package/skills/business/sports/hupu-request-football-player-info/SKILL.md +82 -0
  112. package/skills/business/sports/hupu-request-football-team-info/SKILL.md +83 -0
  113. package/skills/business/sports/hupu-request-football-team-player-season-stats/SKILL.md +73 -0
  114. package/skills/business/sports/hupu-request-football-team-season-year/SKILL.md +68 -0
  115. package/skills/business/sports/hupu-request-kog-playbyplay/SKILL.md +77 -0
  116. package/skills/business/sports/hupu-request-live-tab-info-list/SKILL.md +85 -0
  117. package/skills/business/sports/hupu-request-live-tab-list/SKILL.md +66 -0
  118. package/skills/business/sports/hupu-request-lol-playbyplay/SKILL.md +77 -0
  119. package/skills/business/sports/hupu-request-match-get-tab-detail-schedule-list/SKILL.md +113 -0
  120. package/skills/business/sports/hupu-request-match-query-all-diagram-info-by-id/SKILL.md +79 -0
  121. package/skills/business/sports/hupu-request-match-query-match-stats-by-match-info/SKILL.md +85 -0
  122. package/skills/business/sports/hupu-request-news-news-common-list/SKILL.md +90 -0
  123. package/skills/business/sports/hupu-request-news-player-news-list/SKILL.md +79 -0
  124. package/skills/business/sports/hupu-request-news-subject-news/SKILL.md +89 -0
  125. package/skills/business/sports/hupu-request-news-team-news-list/SKILL.md +76 -0
  126. package/skills/business/storage/README.md +9 -0
  127. package/skills/business/storage/hupu-cloud-save/SKILL.md +129 -0
  128. package/skills/business/storage/hupu-cloud-save/references/legacy-migration.md +111 -0
  129. package/skills/business/storage/hupu-cloud-save-load/SKILL.md +41 -0
  130. package/skills/business/storage/hupu-cloud-save-save/SKILL.md +45 -0
  131. package/skills/business/storage/hupu-storage-get-value/SKILL.md +26 -0
  132. package/skills/business/storage/hupu-storage-set-value/SKILL.md +42 -0
  133. package/skills/business/user/README.md +6 -0
  134. package/skills/business/user/hupu-auth-get-user-info/SKILL.md +47 -0
  135. package/skills/business/user/hupu-game-auth/SKILL.md +46 -0
  136. package/skills/core/hupu-business/SKILL.md +1 -1
  137. package/skills/core/hupu-business/references/runtime.md +17 -11
  138. package/skills/core/shaper-backend/SKILL.md +1 -1
  139. package/skills/core/shaper-backend/references/database.md +2 -2
  140. package/skills/core/shaper-backend/references/legacy.md +1 -1
  141. package/skills/core/shaper-backend/references/node-server.md +29 -20
  142. package/skills/core/shaper-development/SKILL.md +6 -1
  143. package/skills/core/shaper-development/references/materials.md +14 -0
  144. package/skills/core/shaper-development/references/project-setup.md +1 -1
  145. package/skills/core/shaper-game-development/SKILL.md +16 -9
  146. package/skills/core/shaper-game-development/references/implementation.md +13 -0
  147. package/skills/core/shaper-game-development/references/iteration.md +11 -0
  148. package/skills/core/shaper-game-development/references/playable-loop.md +12 -0
  149. package/skills/core/shaper-game-development/references/playtest.md +18 -0
  150. package/skills/core/shaper-game-development/references/sources.md +6 -0
  151. package/skills/core/shaper-release/SKILL.md +1 -1
  152. package/templates/cloud-service/README.md +4 -30
  153. package/templates/cloud-service/cloud.json +5 -8
  154. package/templates/cloud-service/package-lock.json +922 -15
  155. package/templates/cloud-service/release.json +4 -4
  156. package/templates/cloud-service/server.cjs +37 -0
  157. package/templates/leaderboard/README.md +3 -0
  158. package/templates/leaderboard/cloud/database/migrations/202611130001_leaderboard.sql +6 -0
  159. package/templates/leaderboard/cloud/functions/api/cloud.json +10 -0
  160. package/templates/leaderboard/cloud/functions/api/leaderboard.cjs +49 -0
  161. package/templates/leaderboard/cloud/functions/api/package-lock.json +1093 -0
  162. package/templates/leaderboard/cloud/functions/api/package.json +19 -0
  163. package/templates/leaderboard/cloud/functions/api/server.cjs +25 -0
  164. package/templates/leaderboard/cloud/gateway/routes.json +15 -0
  165. package/templates/leaderboard/docs/design.md +1 -0
  166. package/templates/leaderboard/docs/integration.md +12 -0
  167. package/templates/leaderboard/docs/product.md +1 -0
  168. package/templates/leaderboard/docs/validation.md +1 -0
  169. package/templates/leaderboard/index.html +12 -0
  170. package/templates/leaderboard/package-lock.json +828 -0
  171. package/templates/leaderboard/package.json +17 -0
  172. package/templates/leaderboard/public/.gitkeep +1 -0
  173. package/templates/leaderboard/shaper.config.json +7 -0
  174. package/templates/leaderboard/src/main.js +67 -0
  175. package/templates/leaderboard/src/style.css +69 -0
  176. package/templates/leaderboard/test/leaderboard.test.cjs +93 -0
  177. package/templates/offline-game/README.md +3 -0
  178. package/templates/offline-game/docs/design.md +1 -0
  179. package/templates/offline-game/docs/integration.md +10 -0
  180. package/templates/offline-game/docs/product.md +1 -0
  181. package/templates/offline-game/docs/validation.md +1 -0
  182. package/templates/offline-game/index.html +12 -0
  183. package/templates/offline-game/package-lock.json +828 -0
  184. package/templates/offline-game/package.json +16 -0
  185. package/templates/offline-game/public/.gitkeep +1 -0
  186. package/templates/offline-game/shaper.config.json +7 -0
  187. package/templates/offline-game/src/game.js +42 -0
  188. package/templates/offline-game/src/main.js +60 -0
  189. package/templates/offline-game/src/style.css +69 -0
  190. package/templates/offline-game/test/game.test.js +25 -0
  191. package/dist/shared-APGA5MU5.js +0 -19
  192. package/templates/cloud-service/handlers.cjs +0 -46
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: hupu-navigate-to
3
+ description: 为按钮、图片和卡片配置站内、站外或 App 内页面跳转。当用户点击页面元素后前往指定活动页、内容页或外部链接时调用。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.navigate.to(params)`
9
+
10
+ # Constraints
11
+
12
+ - 跳转 URL 必须由显式配置或常量提供,不要从用户输入直接拼接到跳转方法
13
+ - 外链必须使用 https://,相对路径仅用于当前活动页内资源或锚点跳转
14
+ - 必须使用 SDK 统一跳转 API,严禁自行使用 window.location.href 或 window.open 进行跳转以避免损坏路由完整性
15
+ - 如果按钮已有埋点,必须先调用 window.ShaperAI.track 埋点方法,随后再执行跳转
16
+ - 不要在页面加载时自动跳转;跳转必须由用户点击等明确交互触发
17
+ - 必须根据返回的 code 判断是否成功,若 code 不等于 200,必须使用返回的 message 对用户进行友好提示(如 Toast 或弹窗)。
18
+
19
+ # Parameters
20
+
21
+ | 参数名 | 类型 | 是否必填 | 说明 |
22
+ | --- | --- | --- | --- |
23
+ | url | string | 是 | 需要跳转的目标 URL,如 https://... 或 huputiyu://... |
24
+ | target | string | 否 | 跳转目标窗口标识,如 _self 或 _blank,可选 |
25
+
26
+ # Returns
27
+
28
+ - Type: `Promise<Response>`
29
+
30
+ ### Response Properties
31
+
32
+ | 属性名 | 类型 | 是否必填 | 说明 |
33
+ | --- | --- | --- | --- |
34
+ | code | number | 是 | 状态码,200 表示执行成功 |
35
+ | message | string | 是 | 提示信息 |
36
+
37
+ # Examples
38
+
39
+ ```javascript
40
+ window.ShaperAI.navigate.to({ url: "https://m.hupu.com" })
41
+ ```
42
+
43
+ ```javascript
44
+ window.ShaperAI.navigate.to({ url: "huputiyu://bbs/postImg", target: "_self" })
45
+ ```
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: hupu-request
3
+ description: 在活动页中向指定接口发起通用的 HTTP 请求,支持配置自定义方法、请求头与请求体数据。由 SDK 统一进行跨域与转发调度,可选走 Native Bridge 通道。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.request(params)`
9
+
10
+ # Constraints
11
+
12
+ - 严禁自行使用 window.fetch 或 XMLHttpRequest,必须使用统一的 window.ShaperAI.request 接口以避免跨域失败
13
+ - 跨域游戏服务请求设置 credentials: "omit" 和 platformHeaders: false;/admit 的 Game Token 放在 JSON body。omit 不会自动删除自定义请求头,普通业务请求保留默认策略
14
+ - 所有包含机密敏感信息的请求必须在安全风控允许下进行
15
+ - channel 为 bridge 时依赖 App 内 HupuBridge(或 iframe 父容器代理);纯 Web 环境会自动回退 fetch
16
+ - 数据能力调用必须避免无条件循环、无限轮询和重复渲染触发;同一参数的返回结果应优先保存在组件状态中复用。
17
+ - 列表/分页类接口连续自动翻页最多 5 页,必须在无下一页、返回空列表或达到页数上限时停止。
18
+ - SDK 前端已启用请求保护:默认不限制单能力并发和分钟调用量,不启用相同请求在途合并或 GET 短缓存;同 URL 在 10000ms 内最多 20 次;同一页面同接口(去掉 query/hash 参数后相同即为同一接口)在 5000ms 内最多 20 次,首次超过限制返回 429,后续同窗口请求静默丢弃,且同一窗口内只上报一次异常日志。不要自行循环重试或重复触发请求,若接口真实返回 408、429 或 503 等错误码,必须停止继续请求并给用户友好提示。
19
+
20
+ # Parameters
21
+
22
+ | 参数名 | 类型 | 是否必填 | 说明 |
23
+ | --- | --- | --- | --- |
24
+ | url | string | 是 | 需要请求的接口 URL 链接,支持 HTTP/HTTPS 协议 |
25
+ | method | string | 否 | HTTP 请求方法,例如 "GET", "POST", "PUT", "DELETE",默认为 "GET" |
26
+ | headers | object | 否 | 自定义请求头,以键值对表示,可选 |
27
+ | data | object | 否 | 请求体数据对象;GET 时作为 query 参数,POST 时作为请求体,可选 |
28
+ | timeout | number | 否 | 超时时间限制(单位:毫秒),可选 |
29
+ | credentials | string | 否 | 浏览器凭据策略。Game Token 放在 JSON body 的跨域游戏准入请求固定使用 "omit";普通业务请求按原有默认策略。 |
30
+ | platformHeaders | boolean | 否 | 是否自动附加 X-Hupu-Token 和 activityId,默认 true。游戏服务使用 Game Token 鉴权时设为 false;显式传入 headers 的内容仍会保留。 |
31
+ | channel | string | 否 | 请求通道。fetch 为 Web 请求(默认);bridge 为 Native 请求(hupu.common.request),仅 App / Bridge 可用,不可用时自动回退 fetch |
32
+
33
+ # Returns
34
+
35
+ - Type: `Promise<Response>`
36
+
37
+ ### Response Properties
38
+
39
+ | 属性名 | 类型 | 是否必填 | 说明 |
40
+ | --- | --- | --- | --- |
41
+ | statusCode | number | 是 | 响应的 HTTP 状态码,例如 200 |
42
+ | data | object | 是 | 响应的 JSON 数据体,可能为任何 JSON 对象或结构 |
43
+ | headers | object | 是 | 响应头信息 |
44
+
45
+ # Examples
46
+
47
+ ```javascript
48
+ window.ShaperAI.request({ url: "https://activity.hupu.com/api/info", method: "GET" }).then(res => { console.log(res.data); })
49
+ ```
50
+
51
+ ```javascript
52
+ window.ShaperAI.request({ url: "https://bbs.mobileapi.hupu.com/1/8.2.53/threads/getsThreadPostList", method: "GET", channel: "bridge", data: { tid: "640720803" } }).then(res => { console.log(res.data); })
53
+ ```
54
+
55
+ # Frontend Request Guard
56
+
57
+ | 策略 | 默认值 |
58
+ | --- | --- |
59
+ | 同请求在途合并窗口 | 不启用(0ms) |
60
+ | GET 缓存 TTL | 不启用(0ms) |
61
+ | 请求超时 | 8000ms |
62
+ | 单能力最大并发 | 不限制 |
63
+ | 单能力分钟调用上限 | 不限制 |
64
+ | 同 URL 窗口调用上限 | 20 次 / 10000ms(超过限制排队等待) |
65
+ | 同页面同接口窗口调用上限(去掉 query/hash 参数) | 20 次 / 5000ms(首次超过限制返回 429,后续同窗口请求静默丢弃,异常日志只上报一次) |
66
+ | 连续失败熔断 | 3 次失败后熔断 30000ms |
67
+ | 自动分页建议上限 | 5 页 |
@@ -0,0 +1,183 @@
1
+ ---
2
+ name: hupu-seer-chat
3
+ description: 通过 seer.chat 发送流式对话,通过 seer.getHistory 恢复已有 sessionId 的会话;恢复时查询服务端详情和消息、按审核状态展示内容。App 与 Web 的 Relay 请求相同,都带 cookie,不传 puid、不写 identity,用户由 Relay 按 cookie 识别。区别只在调用前:App 须先确认已登录,Web 不在本地判断登录。activityId 由页面 SDK 内部的当前应用标识 自动解析。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.seer.chat(content, templateId, puid, sessionId, params, onEvent)`
9
+
10
+ # Constraints
11
+
12
+ - 发送使用 window.ShaperAI.seer.chat(content, templateId, "", sessionId, params, onEvent),查询已有会话使用 window.ShaperAI.seer.getHistory(sessionId);两者均由本 skill 说明,历史查询不提供独立 skill。第三参必须传空字符串,禁止省略。禁止手写 fetch/EventSource 直连 Relay
13
+ - 【重新显示已有会话必做】页面刷新恢复、从历史列表打开或切换回某个 sessionId 时,必须在会话显示入口调用一次 window.ShaperAI.seer.getHistory(sessionId),等待查询成功后展示内容。只传已有会话 ID。此方法只查询详情和消息,不创建会话、不发送聊天;只恢复 sessionId、本地缓存或发送续聊不能代替这次查询
14
+ - getHistory 成功返回 Promise<{ code: 200, message, session, messages }>,失败返回非 200、session: null、messages: [];sessionId 必须使用 Relay 对外会话 ID,不是 data.id 或 seerSessionId。会话归属由 Relay 按 cookie 校验,不要传 puid,也不要在本地比对 identity。SDK 先获取 token,再 GET /relay/openapi/v1/chat/session/{sessionId},再 GET /relay/openapi/v1/chat/session/{sessionId}/messages 查询内容与审核状态;会话详情接口本身不包含消息,不能只查详情就渲染历史
15
+ - 【历史展示以服务端审核结果为准】code===200 后用顶层 res.messages 按 messageId 重建当前会话列表,保留 requestId/role 对应用户和助手消息,正文使用 displayText。auditStatus=REJECTED 或 ERROR 的对应消息显示“消息内容异常”,PENDING 显示“审核中,请稍候”,PASS 展示正常内容;displayBlocked=true 时不得渲染 content、reasoningContent 或旧缓存中的真实内容。审核结果可能晚于 message.completed 到达,流已完成不代表最终审核通过
16
+ - 【调用时机与失败处理】每次重新显示已有会话查询一次即可;正常流式对话、每帧增量、每次渲染和定时器都不触发恢复查询,不为更新审核状态轮询。查询前清空或隐藏尚未确认审核状态的缓存内容;查询失败显示错误和手动重试入口,不回退展示缓存正文。切换会话时丢弃过期查询结果,仅展示当前 sessionId 的消息
17
+ - App 内必须已登录:调用前先用 window.ShaperAI.auth.getUserInfo() 校验 data.islogin===1;未登录时引导登录,勿调用本能力。不要读取 puid。SDK 在 App 内也会校验,未登录返回 code=401
18
+ - Web 不在本地判断登录态,直接调用。接口返回 401 时引导登录。App 与 Web 的 Relay 请求相同,都使用 credentials=include,都不写 identity
19
+ - activityId 直接取自 SDK 内部的当前应用标识(仅 trim,不去非数字),禁止由调用方传入或手写
20
+ - 不要传 puid,也不要把它写入 session 或 SSE body。第三参固定传空字符串以占位。用户身份只由 cookie 交给 Relay
21
+ - chat 的 content/templateId 必须非空:sessionId 为空则新建会话,有 sessionId 则续聊(token → SSE)。恢复已有会话使用 getHistory(sessionId)。目前没有停止/取消会话的 API
22
+ - 第五参 params 仅为 extraMap:不需要时传 {};需要时运营须在提示词列出全部 key 及每个 value 的获取方式;声明的 key 必须全传,无值则传空字符串 "";禁止增减 key 或臆造值;不要用它传 identity/puid/title/requestId/onEvent 等
23
+ - 第六参 onEvent 可选但优先接入:用增量回调驱动流式对话 UI;未传时只能等流结束后在 Promise 的 data.text 取全文。收到 message.audit_failed 时 event.audit 存在、event.text 为空,必须隐藏已渲染内容并显示“消息内容异常”
24
+ - 流式 UI 体验(聊天页必做):onEvent 只更新 targetText(最新 event.text),用 rAF/定时器把 shownText 逐字追赶后写到气泡;禁止在 onEvent 里把 event.text 一次性直接赋给气泡就当作打字机。建议约 25–40ms/字、每次 1–2 字;短回复整段展示动画不少于约 600–800ms。生成中显示光标与 streaming 状态,结束后移除;列表随 shownText 滚到底。await 后可用 res.data.text 兜底最终全文,但禁止只在 await 后才第一次写入助手内容。限速只做在 UI 层,不要拖延网络请求
25
+ - chat 返回 mode=sse 或 http;getHistory 返回顶层 session/messages,以 res.messages 展示,不读取 res.data.text
26
+ - 根据 code 判断成功与否:发送 code===200 时读 res.data.text 展示回复,并用 res.session.sessionId 续聊;code===422 表示审核失败,按 evt.audit 或 res.data.audit 的 failType 替换本轮对应消息:USER_INPUT_AUDIT 替换用户气泡并清空未生成的助手气泡;MODEL_OUTPUT_AUDIT 替换助手气泡。停止打字机并清空本轮推理,显示“消息内容异常”;code===401 引导登录;其它失败用 message 对用户友好提示
27
+
28
+ # Parameters
29
+
30
+ | 参数名 | 类型 | 是否必填 | 说明 |
31
+ | --- | --- | --- | --- |
32
+ | content | string | 是 | 本轮用户话术,trim 后不能为空,写入 SSE body.content;chat 只负责发送,查询已有会话使用 seer.getHistory(sessionId) |
33
+ | templateId | string | 是 | Seer 模板 ID(运营/后台配置),同一会话应保持一致,按运营提示词中的「指定 templateId=...」取值;getHistory 无需此参数 |
34
+ | puid | string | 否 | 保留的第三参位置。App 与 Web 都传空字符串,不要省略,否则 sessionId 及后续参数会前移。SDK 忽略该值,不写入 identity,也不要为此调用 auth.getUserInfo 取 puid。禁止手写假值、禁止塞进第五参 params |
35
+ | sessionId | string | 否 | 续聊的 Relay 会话 ID。不传则新建会话,res.session.sessionId 用于续聊;重新显示已有会话时先调用 seer.getHistory(sessionId) 恢复消息。chat 不会查询历史或更新历史审核状态。目前没有停止/取消会话的 API |
36
+ | params | object | 否 | 可选。即 Seer extraMap(object<string,string>),有则写入 SSE body.extraMap;不需要业务字段时传 {}。禁止塞 identity/puid/title/requestId/activityId/onEvent。若需要 params:运营须在提示词中列出全部 key 名称,并说明每个 key 的 value 获取方式;声明的 key 必须全部传入,即便暂无值也要传该 key 且 value 设为空字符串 "";禁止增减 key、禁止臆造值。value 来源:(1)提示词写死;(2)页面配置或接口填充 |
37
+ | onEvent | object | 否 | 可选但优先接入。SSE 增量回调函数 (event) => void,位置第六参。每帧(message.delta / message.completed / message.audit_failed / relay.error)调用一次;event.text 为截至当前聚合全文,event.audit 表示审核失败,必须停止打字机并替换异常消息。短回复网络侧可能 <1s 结束,若 onEvent 里直接把 event.text 赋给 DOM,观感会像一次出全——聊天 UI 必须在展示层做平滑打字机(见 constraints/examples),不要只靠裸刷 DOM。成败仍以 Promise code 为准;未传时只能等结束后读 data.text |
38
+
39
+ # Returns
40
+
41
+ - Type: `Promise<Response>`
42
+
43
+ ### Response Properties
44
+
45
+ | 属性名 | 类型 | 是否必填 | 说明 |
46
+ | --- | --- | --- | --- |
47
+ | code | number | 是 | 业务状态码。200 表示成功;401 表示未登录(App 本地校验,或 Web 由接口 cookie 校验失败);403 表示无权访问该会话;422 表示审核失败,显示“消息内容异常”;其它非 200 表示失败(含 mode=http 前置失败与 SSE 内 relay.error) |
48
+ | message | string | 是 | 提示文案;失败时可用于 Toast/页面提示;401 时应引导用户登录 |
49
+ | mode | string | 是 | chat 结果通道。sse=流式发送(含流内错误);http=前置失败。getHistory 不返回 mode |
50
+ | session | object | 是 | 会话信息;无论成败都会返回,便于续聊或排障 |
51
+ | session.sessionId | string | 是 | 当前会话 ID;成功后下一轮必须作为第四参传入 |
52
+ | session.activityId | string | 是 | SDK 从 SDK 内部的当前应用标识 读取的活动 ID(只读,勿回传为入参) |
53
+ | step | string | 否 | 仅 mode=http 时出现。失败步骤为 getToken、createSession 或 chatStream,便于定位前置哪一步挂了 |
54
+ | statusCode | number | 否 | 底层 HTTP 状态码(若有);业务成败仍以 code 为准 |
55
+ | data | object | 否 | chat 发送成功时为 SSE 聚合结果;mode=http 失败时可能含 relay 原始错误字段;getHistory 的消息在顶层 messages 中 |
56
+ | data.text | string | 否 | 助手回复全文(由 SSE delta/completed 聚合);成功展示用这个字段 |
57
+ | data.reasoningText | string | 否 | 可选。模型推理过程文本(若流里有) |
58
+ | data.audit | object | 否 | 审核失败时读取 res.data.audit;status 为 REJECTED 或 ERROR,failType 区分 USER_INPUT_AUDIT 与 MODEL_OUTPUT_AUDIT;此时 code 为 422 |
59
+ | data.completed | boolean | 否 | 流是否收到 completed 事件 |
60
+ | data.events | array | 否 | 原始 SSE 事件列表,调试用;业务页一般只用 text |
61
+
62
+ # Examples
63
+
64
+ ```text
65
+ 【使用说明】
66
+ 调用 ShaperAI.seer.chat(hupu-seer-chat)时须遵守:
67
+ 1. 发送必须设置 templateId:按运营提示词中的「指定 templateId=...」取值;恢复已有会话使用 seer.getHistory(sessionId),无需 content/templateId
68
+ 2. 若需要 params(extraMap):运营提示词必须说明 params 的全部 key 名称,并说明每个 key 对应 value 的获取方式;声明的 key 必须全部传入,即便暂无值也要传该 key,value 设为空字符串 "";禁止增减 key、禁止臆造值
69
+ 3. 若不需要 params,传 {}
70
+ 4. App 须先用 auth.getUserInfo 确认 data.islogin===1,未登录引导登录,不要取 puid。Web 不在本地判断登录。两端第三参都传空字符串
71
+ 5. 优先接入第六参 onEvent;聊天 UI 须做展示层平滑打字机(targetText/shownText 追赶),勿在 onEvent 里一次性裸刷全文
72
+ 6. 禁止在 params 中传入 identity、puid、title、requestId、activityId、onEvent
73
+ 7. 重新显示已有 sessionId 的会话时,必须在显示入口实际调用 seer.getHistory(sessionId) 并以 res.messages 渲染;仅声明恢复函数未接入入口不算完成。显示一次查询一次,不轮询审核状态
74
+ ```
75
+
76
+ ```javascript
77
+ // 【API + 平滑打字机示例】templateId / params 按运营提示词填写;短回复也要有可见逐字过程
78
+ const user = await window.ShaperAI.auth.getUserInfo();
79
+ if (user.code !== 200 || Number(user.data?.islogin) !== 1) {
80
+ // App 引导登录。Web 不要写这段判断,直接调用 seer.chat
81
+ } else {
82
+ const templateId = '按运营提示词指定的 templateId';
83
+ const params = {};
84
+ let targetText = '';
85
+ let shownText = '';
86
+ let timer = 0;
87
+ let auditFailed = false;
88
+ // 本轮消息容器在发送前已创建;引用保留在本次调用内,不选择其他轮的气泡。
89
+ const turn = document.querySelector('.chat-turn[data-current="true"]');
90
+ const userBubble = turn.querySelector('.user-bubble');
91
+ const bubble = turn.querySelector('.assistant-bubble');
92
+ const reasoning = turn.querySelector('.assistant-reasoning');
93
+ let failedAudit;
94
+ const showAuditFailure = (audit) => {
95
+ failedAudit = audit || failedAudit;
96
+ auditFailed = true;
97
+ clearTimeout(timer);
98
+ timer = 0;
99
+ targetText = shownText = '';
100
+ reasoning?.replaceChildren();
101
+ if (failedAudit?.failType === 'USER_INPUT_AUDIT') {
102
+ userBubble.textContent = '消息内容异常';
103
+ bubble.replaceChildren();
104
+ } else {
105
+ bubble.textContent = '消息内容异常';
106
+ }
107
+ };
108
+ const tick = () => {
109
+ if (auditFailed) return;
110
+ if (shownText.length < targetText.length) {
111
+ shownText = targetText.slice(0, shownText.length + 1);
112
+ bubble.textContent = shownText;
113
+ timer = setTimeout(tick, 30);
114
+ return;
115
+ }
116
+ timer = 0;
117
+ };
118
+ const res = await window.ShaperAI.seer.chat(
119
+ '你好',
120
+ templateId,
121
+ '',
122
+ '',
123
+ params,
124
+ (evt) => {
125
+ if (evt.audit) {
126
+ showAuditFailure(evt.audit);
127
+ return;
128
+ }
129
+ if (auditFailed) return;
130
+ if (evt.text !== undefined) {
131
+ targetText = evt.text;
132
+ if (!timer) tick();
133
+ }
134
+ }
135
+ );
136
+ if (res.code === 422) {
137
+ showAuditFailure(res.data?.audit);
138
+ } else if (res.code === 200 && !auditFailed) {
139
+ targetText = res.data?.text || targetText;
140
+ if (!timer) tick();
141
+ // 续聊用 res.session.sessionId
142
+ }
143
+ }
144
+ ```
145
+
146
+ ```javascript
147
+ // 【会话显示入口】页面恢复/打开历史/切换会话时调用 showSession(sessionId),每次显示只查询一次。
148
+ // 将这个函数接入页面初始化和历史列表点击入口,而不是只声明不调用。
149
+ const historyContainer = document.querySelector('.chat-history');
150
+ let historyLoadVersion = 0;
151
+ async function showSession(sessionId) {
152
+ const version = ++historyLoadVersion;
153
+ historyContainer.replaceChildren(); // 查询前隐藏旧缓存,避免审核失败内容闪现。
154
+ historyContainer.textContent = '加载中';
155
+ // App 才做这段登录判断。Web 跳过,直接 getHistory。
156
+ const user = await window.ShaperAI.auth.getUserInfo();
157
+ if (version !== historyLoadVersion) return;
158
+ if (user.code !== 200 || Number(user.data?.islogin) !== 1) {
159
+ historyContainer.textContent = '请先登录';
160
+ return;
161
+ }
162
+ const res = await window.ShaperAI.seer.getHistory(sessionId);
163
+ if (version !== historyLoadVersion) return; // 丢弃切换前的查询结果。
164
+ if (res.code !== 200) {
165
+ historyContainer.textContent = res.message || '会话加载失败,请手动重试';
166
+ return; // 查询失败不回填本地缓存正文。
167
+ }
168
+ historyContainer.replaceChildren();
169
+ for (const message of res.messages) {
170
+ const bubble = document.createElement('div');
171
+ bubble.dataset.messageId = message.messageId;
172
+ bubble.dataset.requestId = message.requestId;
173
+ bubble.dataset.role = message.role;
174
+ bubble.textContent = message.displayText;
175
+ historyContainer.appendChild(bubble);
176
+ // displayBlocked=true 时不渲染正文或推理;REJECTED/ERROR 的 displayText 已是“消息内容异常”。
177
+ }
178
+ }
179
+ // 恢复入口:sessionId 从当前页面保存的 Relay 会话标识读取,不读取缓存正文。
180
+ const savedSessionId = sessionStorage.getItem('seer-sessionId');
181
+ if (savedSessionId) await showSession(savedSessionId);
182
+ // 历史列表点击/切换回会话时同样 await showSession(selectedSessionId),不设置轮询定时器。
183
+ ```
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: hupu-track-report
3
+ description: 支持页面加载、点击、曝光等标准数据埋点上报,用于统计分析用户流量、模块点击和页面互动情况,方便了解页面表现与转化效果。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.track(params)`
9
+
10
+ # Constraints
11
+
12
+ - 必须仅使用 window.ShaperAI.track(params) 进行打点,严禁直接引入 @hupu/hp-tracer 或手动拼接 Hermes 接口 URL
13
+ - 页面加载事件 access 由底层框架自动触发上报,业务代码切勿重复调用
14
+ - 事件类型 act 必须且只能是:click (点击)、exposure (曝光)、videoact (视频) 之一;access、onload、onPageOpen、onPageClose 以及 submit、feed_xxx 等自定义 act 都不合法;不合法 act 会触发前端 SDK warning 与日志上报
15
+ - 点击与曝光必须双向成对:同一模块只要埋了点击,就必须同时埋对应曝光;只要埋了曝光,就必须同时埋对应点击,禁止只实现单边;曝光在模块实际可见时上报,点击在用户实际点击时上报,禁止在点击时补报虚假曝光
16
+ - 点击埋点应写在事件处理器(handler)的最前端,保障先上报再请求/跳转;曝光埋点使用 IntersectionObserver 监测,可见比例达到 50% 时才上报,同一个元素在单次会话中只上报一次,重复渲染不得重复绑定或重复曝光
17
+ - 埋点上报必须控制数量:页面初始化阶段最多上报 50 个埋点,单页面 1 分钟内最多上报 200 个埋点,同一个 blk 在 1 分钟内最多上报 100 个埋点;超过限制的埋点会被前端 SDK 丢弃,不要通过循环、定时器或重复曝光规避限制
18
+ - blk 固定为 BMC001,所有埋点点位统一使用该编号,禁止使用 BMC002 等其它编号或 VOTE_MODULE、HEADER_CLICK 等语义字符串
19
+ - pos 固定为 T1;label 必须放在 ext.label 中,且必填、必须使用中文,保持简洁,控制在 10 个中文字以内(含 10 个字),禁止省略、留空或使用英文代码标识;统一使用“业务场景-模块或入口”结构,以半角连字符 - 分隔,如“活动首页-报名入口”“任务中心-奖励领取”“排行榜-选手详情”,避免只写“点击”“按钮”“提交”等无法区分业务点位的通用文案;其它扩展业务属性写在 ext.custom(小写驼峰)
20
+ - 同一模块的曝光与点击埋点必须复用完全一致的 ext.label 字符串(包括空格和标点),不得分别添加“点击”“曝光”等前后缀,两者仅通过 act 区分;发现任一模块只有 click 或只有 exposure,或两者 ext.label 不完全一致时,必须补齐配对事件并统一 label 后再交付
21
+ - 不要手动传入 pg、pi、sc 等系统字段;ext 是埋点扩展字段容器,label 和业务扩展数据必须放在 ext 内,底座会自动完成其它系统字段的补充封装
22
+
23
+ # Parameters
24
+
25
+ | 参数名 | 类型 | 是否必填 | 说明 |
26
+ | --- | --- | --- | --- |
27
+ | params | object | 是 | 埋点上报参数,包含 act (事件类型), blk (固定为 BMC001), pos (固定为 T1), ext.label (必填中文点位名称,使用“业务场景-模块或入口”结构,10 个中文字以内,同一模块点击与曝光的值必须完全一致), ext.custom (自定义小写驼峰业务数据) |
28
+
29
+ # Returns
30
+
31
+ - Type: `Promise<Response>`
32
+
33
+ ### Response Properties
34
+
35
+ | 属性名 | 类型 | 是否必填 | 说明 |
36
+ | --- | --- | --- | --- |
37
+ | ok | boolean | 否 | 是否成功唤起底层上报方法 |
38
+
39
+ # Examples
40
+
41
+ ```javascript
42
+ // 页面需已有 id="activity-join-btn" 的参与按钮;在按钮渲染后绑定一次。
43
+ const joinButton = document.getElementById("activity-join-btn");
44
+ if (joinButton) {
45
+ const point = {
46
+ blk: "BMC001",
47
+ pos: "T1",
48
+ ext: {
49
+ label: "活动首页-报名入口",
50
+ custom: { activityId: 101, entryId: "mainVenue" }
51
+ }
52
+ };
53
+
54
+ joinButton.addEventListener("click", () => {
55
+ window.ShaperAI.track({ ...point, act: "click" });
56
+ // 在埋点之后执行实际参与操作或跳转。
57
+ });
58
+
59
+ let exposed = false;
60
+ const observer = new IntersectionObserver((entries) => {
61
+ entries.forEach((entry) => {
62
+ if (!exposed && entry.isIntersecting && entry.intersectionRatio >= 0.5) {
63
+ exposed = true;
64
+ window.ShaperAI.track({ ...point, act: "exposure" });
65
+ observer.unobserve(entry.target);
66
+ }
67
+ });
68
+ }, { threshold: 0.5 });
69
+ observer.observe(joinButton);
70
+ }
71
+ ```
@@ -0,0 +1,7 @@
1
+ # 分享与素材
2
+
3
+ 分享、结果海报发帖、文件上传。本目录仅分类,技能内容暂不重构。
4
+
5
+ - [hupu-oss-upload-file](hupu-oss-upload-file/SKILL.md)
6
+ - [hupu-result-poster-posting](hupu-result-poster-posting/SKILL.md)
7
+ - [hupu-social-share](hupu-social-share/SKILL.md)
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: hupu-oss-upload-file
3
+ description: 支持在活动页内通过拍照、相册选择或合成二进制,将文件或图片直传至 Hupu OSS 并获取可用 CDN 地址。适用于用户上传头像、活动晒图、截图分享及二进制文件存证。
4
+ ---
5
+
6
+ # Usage
7
+
8
+ - JS Path: `window.ShaperAI.oss.uploadFile(params)`
9
+
10
+ # Constraints
11
+
12
+ - 必须且仅允许使用 window.ShaperAI.oss.uploadFile(params) 接口,严禁在业务端直接引入 ali-oss 或手写上传逻辑
13
+ - 入参 file 必须为标准的 HTML5 File 或 Blob 对象
14
+ - 上传过程中需要妥善处理加载等待状态(如展示 Loading),并防范请求失败或文件过大等边界情况,给予用户良好反馈
15
+ - 上传限制:支持单文件最大 10MB,支持主流图片、视频和二进制包文件。
16
+ - 本接口在 App 内运行依赖用户登录态。若用户未登录,接口会返回“未登录或登录态失效”错误,业务端需捕获该异常并引导用户去登录。
17
+
18
+ # Parameters
19
+
20
+ | 参数名 | 类型 | 是否必填 | 说明 |
21
+ | --- | --- | --- | --- |
22
+ | file | object | 是 | 待上传的 HTML5 File 或 Blob 对象 |
23
+ | filename | string | 否 | 自定义文件名,可选 |
24
+
25
+ # Returns
26
+
27
+ - Type: `Promise<Response>`
28
+
29
+ ### Response Properties
30
+
31
+ | 属性名 | 类型 | 是否必填 | 说明 |
32
+ | --- | --- | --- | --- |
33
+ | downloadUrl | string | 是 | 上传成功后的 CDN 访问绝对链接 |
34
+ | name | string | 是 | 上传成功后的文件名 |
35
+
36
+ # Examples
37
+
38
+ ```javascript
39
+ window.ShaperAI.oss.uploadFile({ file: fileObj, filename: "avatar.png" }).then(res => { console.log(res.downloadUrl); }).catch(err => { console.error("上传失败", err.message); })
40
+ ```
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: hupu-result-poster-posting
3
+ description: 使用 OSS 文件上传和虎扑发帖编辑器,创建可运行的结果海报生成与一键发帖 H5 页面;适用于“实现一个带结果海报发帖功能”“把结果生成海报并分享”等请求,不用于仅下载图片或静态展示海报。
4
+ metadata:
5
+ required-skills:
6
+ - hupu-oss-upload-file
7
+ - hupu-request-bbs-open-post-editor
8
+ ---
9
+
10
+ # 带结果海报发帖功能
11
+
12
+ 当用户提出“实现一个带结果海报发帖功能”或同义需求时,生成真实可运行的原生 H5:把页面中的结果数据绘制成分享海报,上传到 Hupu OSS,并在用户主动点击后唤起虎扑发帖编辑器预填标题、正文和海报图片。
13
+
14
+ ## 必须使用的能力
15
+
16
+ - `hupu-oss-upload-file`:只使用 `window.ShaperAI.oss.uploadFile({ file, filename })` 上传 `Blob`/`File`,读取返回的 `downloadUrl`。
17
+ - `hupu-request-bbs-open-post-editor`:只使用 `window.ShaperAI.request.bbs.openPostEditor({ title, content, imageUrl, topicId?, tagId?, topicName?, tagName? })` 唤起发帖。专区/话题未提及时,先 `await window.ShaperAI.bbsConfig.get()`,仅当 `bbsTagId` 为非空字符串时才把 `bbsTopicId` / `bbsTagId` / `bbsTopicName` / `bbsTagName` 传入;`bbsTagId` 无值或空字符串时四个字段都不要传。业务明确不要设置这四个值时,不要传、也不要从页面补。
18
+
19
+ 禁止业务代码直接使用 `fetch`、`axios`、`XMLHttpRequest`、`ali-oss`、`location.href` 或手写 `huputiyu://` Schema。不要把图片 Base64 直接塞进发帖参数,必须先上传并传 CDN URL。
20
+
21
+ ## 实施要求
22
+
23
+ 1. 阅读 [references/api-contract.md](references/api-contract.md),复制 `example/index.html` 到活动的 `h5/index.html`,替换结果字段、活动标题和可选的专区/话题参数。页面必须是原生 HTML/CSS/JS,可双击打开,不引入 Vue/React/Vite。
24
+ 2. 将结果数据集中在一个可替换的 `result` 对象中(例如排名、积分、百分位、用户昵称、日期)。所有文字绘制到 Canvas 前做长度截断或换行,避免海报溢出;同时提供可读的 DOM 文本结果,保证无 Canvas 或上传失败时页面仍可用。
25
+ 3. 可在页面初始化时生成本地海报预览;上传和唤起发帖编辑器必须由用户点击“发帖分享”触发。使用 `canvas.toBlob()` 生成 `image/png` Blob,设置稳定的海报尺寸和清晰度;Blob 为空时停止流程并提示重试。
26
+ 4. 上传前展示 Loading,调用 OSS 技能并检查返回值和 `downloadUrl`;处理 SDK 不可用、文件过大、网络失败和取消状态,失败时不得唤起发帖编辑器或伪造成功提示。
27
+ 5. 上传成功后,只有在用户主动点击分享动作时调用发帖编辑器。标题和正文使用结果数据生成,正文中不要写入 Token、PUID 或内部 URL;`imageUrl` 使用 OSS 返回的绝对 CDN URL。专区/话题未提及时先读页面 `bbsConfig.get()`,仅当 `bbsTagId` 为非空字符串才传入四个字段;`bbsTagId` 无值或空字符串时不要用页面值兜底。业务明确不要设置时不要传、也不要从页面补。检查返回 `code`,不等于 200 时展示返回的 `message`。
28
+ 6. 分享按钮需要防重复点击:单次流程使用状态机(idle → rendering → uploading → opening → done/error),上传或编辑器调用进行中时禁用按钮;出现 408、429、503 或技能返回错误时停止,不要自动重试或循环唤起。
29
+ 7. 对昵称、结果文本和服务端错误进行 HTML 转义或使用 `textContent`;不把用户输入拼入 HTML、URL Schema 或任意脚本。海报图片只接受本地 Canvas 产物或可信 OSS 返回值。
30
+ 8. 本地双击模板时允许使用静态演示结果并显示“演示模式”;在虎扑 App 内验证真实上传和发帖。成功、失败和取消都要给用户明确反馈,并保留海报预览。
31
+
32
+ ## 交付检查
33
+
34
+ - 页面有结果卡片、Canvas 海报预览、生成/重生成按钮和发帖分享按钮。
35
+ - SDK 不可用时,页面仍能展示结果和本地海报;分享动作给出可理解的降级提示。
36
+ - 上传严格使用 `ShaperAI.oss.uploadFile`,发帖严格使用 `ShaperAI.request.bbs.openPostEditor`;没有自定义网络请求或手写 Schema。
37
+ - 依赖技能随 `hupu-result-poster-posting` 一起打包,且交付说明包含图片上传成功后的 CDN URL 使用方式、发帖参数和失败行为。
@@ -0,0 +1,14 @@
1
+ # Result Poster Posting Example
2
+
3
+ This directory is a reference implementation for the `hupu-result-poster-posting` skill.
4
+
5
+ `index.html` is a standalone mobile-first H5. It renders a result object to a local Canvas poster and, only after the user clicks `发帖分享`, uploads the PNG through `window.ShaperAI.oss.uploadFile` before opening the Hupu editor with `window.ShaperAI.request.bbs.openPostEditor`.
6
+
7
+ The optional backend reference keeps the result data in the activity environment:
8
+
9
+ - `cloudfunctions/activity_api/`: the fixed `activity_api` function with `GET /api/health`, authenticated `GET /api/result/me`, and authenticated `POST /api/result/save`.
10
+ - `migrations/20260828213000_create_result_poster_results.sql`: renames the platform `demo_items` baseline to `result_poster_results`, adds result fields, a unique user index, and the `save_result_poster_result` RPC.
11
+
12
+ The page's built-in `result` object is deliberately used for local preview. In a deployed activity, load the authenticated result through `window.ShaperAI.cloud.auth` and `window.ShaperAI.cloud.request`, then replace that object before rendering. The backend never receives the poster Blob: the browser uploads it directly through the OSS capability and passes the returned absolute HTTPS CDN URL only to the post editor.
13
+
14
+ The page is intentionally usable when opened directly from disk: it shows the demo result and local poster, while the share action explains that the Hupu App SDK is required. Before publishing, apply the migration, deploy the fixed `activity_api`, replace the `result` object and optional `topicId`/`tagId`, then verify login, result save/read, upload, cancellation, editor failure, and CDN URL validation in the Hupu App.