@heybox/hb-sdk 0.6.7-alpha.2 → 0.6.8-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +226 -0
- package/README.md +65 -583
- package/dist/cli-chunks/{build-CQmYxfxm.cjs → build-BfhZ07Qv.cjs} +4 -4
- package/dist/cli-chunks/{context-ChkYWwH_.cjs → context-CqoGNt7d.cjs} +2 -2
- package/dist/cli-chunks/{create-CC5r_8bL.cjs → create-us7swTbU.cjs} +1 -1
- package/dist/cli-chunks/{dev-CD-38TgO.cjs → dev-Bf49EoR8.cjs} +6 -6
- package/dist/cli-chunks/{doctor-43yEfVr0.cjs → doctor-CzETlRvH.cjs} +21 -3
- package/dist/cli-chunks/{index-CQnkS0Z8.cjs → index-BMhV2-vd.cjs} +14 -14
- package/dist/cli-chunks/{index-BM6oH2Hs.cjs → index-Cd37cCQM.cjs} +2 -2
- package/dist/cli-chunks/{index-BQm5XmMC.cjs → index-v4-6fbXX.cjs} +29 -2
- package/dist/cli-chunks/{login-BmisXAdp.cjs → login-Cb5ShNVQ.cjs} +2 -2
- package/dist/cli-chunks/{project-vite-D9_v57vp.cjs → project-vite-WP6NzC3p.cjs} +1 -1
- package/dist/cli-chunks/{remote-BXtT6M2f.cjs → remote-Co84uKvV.cjs} +28 -8
- package/dist/cli-chunks/{runtime-gate-B2MQf1vc.cjs → runtime-gate-DfMJQGH9.cjs} +1 -1
- package/dist/cli-chunks/{session-BjtjhtPg.cjs → session-9A8AY7YK.cjs} +1 -1
- package/dist/cli.cjs +1 -1
- package/dist/index.cjs.js +1 -1
- package/dist/index.esm.js +1 -1
- package/dist/miniapp-publish.cjs.js +29 -2
- package/dist/miniapp-publish.esm.js +29 -2
- package/dist/vite.cjs.js +1 -1
- package/dist/vite.esm.js +1 -1
- package/package.json +3 -1
- package/skill/references/api-protocol.md +0 -10
- package/skill/references/api-root.md +153 -353
- package/skill/references/safety-boundaries.md +6 -9
- package/skill/scripts/sync-references.mjs +10 -20
- package/skill/skill.json +4 -4
package/README.md
CHANGED
|
@@ -1,644 +1,126 @@
|
|
|
1
1
|
# @heybox/hb-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
小黑盒 APP 小程序工坊的前端 SDK 与开发 CLI，用于创建、调试、构建和发布工坊小程序，并在业务页面中调用小黑盒开放能力。
|
|
4
|
+
|
|
5
|
+
SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部协议、登录凭据或私有实现入口。本地浏览器调试请使用 `hb-sdk dev` 提供的 Mock 环境，发布前仍需在小黑盒 APP 中完成真机验收。
|
|
4
6
|
|
|
5
7
|
## 快速开始
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
### 创建新项目
|
|
8
10
|
|
|
9
11
|
```bash
|
|
10
|
-
npx @heybox/hb-sdk create my-miniapp
|
|
12
|
+
npx @heybox/hb-sdk@latest create my-miniapp
|
|
11
13
|
cd my-miniapp
|
|
12
14
|
npm install
|
|
13
15
|
npm run dev
|
|
14
16
|
```
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试页进入 Mac 或手机端验收。
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
### 接入已有项目
|
|
19
21
|
|
|
20
22
|
```bash
|
|
21
23
|
npm install @heybox/hb-sdk
|
|
22
24
|
```
|
|
23
25
|
|
|
24
|
-
|
|
26
|
+
页面启动时等待 SDK 就绪，再读取当前用户状态：
|
|
25
27
|
|
|
26
28
|
```ts
|
|
27
29
|
import hbSDK from '@heybox/hb-sdk';
|
|
28
30
|
|
|
29
31
|
await hbSDK.ready();
|
|
30
32
|
|
|
31
|
-
const
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
console.log(user.userInfo.nickname);
|
|
33
|
+
const result = await hbSDK.user.getInfo();
|
|
34
|
+
if (result.isLogin && result.userInfo) {
|
|
35
|
+
console.log(result.userInfo.nickname);
|
|
35
36
|
}
|
|
36
37
|
```
|
|
37
38
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
```ts
|
|
41
|
-
import { auth, ready, user } from '@heybox/hb-sdk';
|
|
42
|
-
|
|
43
|
-
await ready();
|
|
44
|
-
|
|
45
|
-
const currentUser = await user.getInfo();
|
|
46
|
-
|
|
47
|
-
if (!currentUser.isLogin) {
|
|
48
|
-
await auth.login();
|
|
49
|
-
}
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## 运行环境
|
|
53
|
-
|
|
54
|
-
SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注入 bridge nonce，并通过 `postMessage` 与 SDK 通信。普通浏览器直接打开小程序页面时通常无法完成握手；本地开发请优先使用：
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
npm run dev
|
|
58
|
-
```
|
|
39
|
+
`ready()` 只表示 SDK 可以调用，不代表用户已经登录。需要登录时，请在按钮点击等明确的用户操作中调用 `hbSDK.auth.login()`。
|
|
59
40
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
Mock Host 可以切换开发会话的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR。权限覆盖会持久化到 `hb-sdk` 的用户级本地缓存，并按项目真实路径与启动时绑定的 `miniProgramId` 隔离；即使远端权限暂时读取失败，也会继续使用已知绑定 scope。刷新调试页或重启 `hb-sdk dev` 后仍会恢复，直到点击“恢复初始权限”。未绑定项目使用独立匿名 scope，之后绑定小程序时不会继承匿名覆盖。调试页会分别展示远端基线与本地覆盖；多个调试页或进程写入同一 scope 时以最后成功写入的完整配置为准，不提供冲突合并。缓存写入失败时当前页面仍立即生效，同时明确提示刷新或重启后会丢失。已绑定项目重置时会先重新读取远端权限，读取失败则保留当前覆盖并显示错误；匿名项目直接清除本地覆盖。
|
|
63
|
-
|
|
64
|
-
切换或恢复权限时，Mobile App 二维码会同步重生成，重新扫码后的局域网页面使用同一开发权限。二维码不会携带权限内容，只携带指向本机 Mock Host 的 `dev_context_url`；该 URL 使用 256-bit 随机 token，5 分钟后失效，调试页会在会话到期时自动生成新二维码。Runtime Host 会在创建小程序 Runtime 前拉取 token 对应的不可变权限快照，并校验开发页面 origin、会话期限和快照结构。
|
|
65
|
-
|
|
66
|
-
Dev Session 中的 `network.request` 通过同一 token 绑定的本地代理转发，不会调用黑盒原生凭据 adapter，也不会携带 Cookie、pkey 等宿主凭据；`useOfficialDomain` 固定为 `false`。旧 `dev_network_request` query 不再提供授权，不能作为 Dev Session 快照的降级或覆盖入口。此链路只调整 Web 侧 CLI、Mock Host 和 Runtime Host，Android/iOS 客户端继续透传 URL，无需修改。官方域名权限只读取线上快照，本地设置不会修改线上权限；调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
|
|
67
|
-
|
|
68
|
-
在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
|
|
69
|
-
|
|
70
|
-
```json
|
|
71
|
-
{
|
|
72
|
-
"scripts": {
|
|
73
|
-
"dev": "hb-sdk dev"
|
|
74
|
-
}
|
|
75
|
-
}
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
## 常用能力
|
|
79
|
-
|
|
80
|
-
### 用户与登录
|
|
81
|
-
|
|
82
|
-
`user.getInfo()` 只读取当前登录态，不会主动唤起登录。需要用户操作时再调用 `auth.login()`。
|
|
41
|
+
已有 Vite 项目还需要启用构建插件：
|
|
83
42
|
|
|
84
43
|
```ts
|
|
85
|
-
import {
|
|
86
|
-
|
|
87
|
-
const result = await user.getInfo();
|
|
88
|
-
|
|
89
|
-
if (!result.isLogin) {
|
|
90
|
-
const loginResult = await auth.login();
|
|
91
|
-
console.log(loginResult.userInfo);
|
|
92
|
-
}
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
SDK 只返回允许暴露给外部小程序的公开资料，不会返回 token、cookie、手机号或其他私有凭据。
|
|
96
|
-
|
|
97
|
-
需要当前用户更完整资料时，可以使用 current-user scoped API。这些 API 与 `user.getInfo()` 一样不会主动唤起登录；未登录时返回普通未登录结果，业务应只在用户操作后调用 `auth.login()`。
|
|
98
|
-
|
|
99
|
-
```ts
|
|
100
|
-
const detail = await user.getCurrentUserDetail();
|
|
101
|
-
|
|
102
|
-
if (detail.isLogin) {
|
|
103
|
-
console.log(detail.data.nickname, detail.data.level_info);
|
|
104
|
-
}
|
|
105
|
-
|
|
106
|
-
const steam = await user.getPlatformAccountInfo('steam');
|
|
107
|
-
|
|
108
|
-
if (steam.isLogin && steam.is_bound) {
|
|
109
|
-
console.log(steam.account_info.steamid);
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
const games = await user.getSteamGameList({
|
|
113
|
-
limit: 20,
|
|
114
|
-
sort: 'weeks',
|
|
115
|
-
});
|
|
116
|
-
|
|
117
|
-
if (games.isLogin && games.isBound) {
|
|
118
|
-
console.log(games.data.gameList);
|
|
119
|
-
}
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
`user.getCurrentUserDetail()` 返回当前用户展示资料，`user.getCurrentUserProfile()` 返回更敏感的个人资料字段。`user.getPlatformAccountOverview()` 返回 `steam`、`epic`、`xbox`、`psn`、`switch`、`pc_hardware`、`mobile` 的绑定/隐藏状态；`user.getPlatformAccountInfo(platform)` 只支持这些平台字面量，未绑定平台返回 `account_info: null`，不会抛出未绑定错误。`user.getSteamGameList(options)` 返回当前用户 Steam 游戏库，未登录或未绑定 Steam 时返回状态对象；分页 `limit` 默认 20、最大 100，`sort` 支持 `weeks`、`all`、`achieved`。
|
|
123
|
-
|
|
124
|
-
这些 API 仍然只面向当前登录用户，不支持传入 `userid` 查询其他人。平台账号详情和 Steam 游戏库会过滤好友列表、客户端路由协议和页面 UI 状态字段；敏感字段按独立 permission key 管理，后续可由宿主策略按能力或平台收紧。
|
|
125
|
-
|
|
126
|
-
### 分享
|
|
127
|
-
|
|
128
|
-
```ts
|
|
129
|
-
import { share } from '@heybox/hb-sdk';
|
|
130
|
-
|
|
131
|
-
await share.showShareMenu({
|
|
132
|
-
title: '我的小程序页面',
|
|
133
|
-
desc: '来自黑盒小程序的分享',
|
|
134
|
-
imageUrl: 'https://imgheybox.max-c.com/demo.png',
|
|
135
|
-
post: {
|
|
136
|
-
topicIds: [235709],
|
|
137
|
-
topics: ['无畏契约战绩'],
|
|
138
|
-
},
|
|
139
|
-
});
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
工坊小程序通常不要传 `url`；宿主 runtime 会按当前小程序生成
|
|
143
|
-
`/tools/common_share?user_miniprogram_id=...` 分享落地页。只有确实要分享外部
|
|
144
|
-
HTTP(S) 页面时才显式传 `url`。
|
|
145
|
-
|
|
146
|
-
`post` 用于给“转发到社区”预置可编辑的分区与话题。`topicIds` 接受正整数或非空字符串并按首次出现顺序去重；`topics` 只传话题内容，不要包含首尾 `#`。`showShareMenu()` 只支持一个默认分区，并且不能与 `channel` 同时使用；本地 Mock、App Dev Shell 和开发 Runtime 会直接拒绝这类错误，生产 Runtime 会过滤非法项、只取第一个分区并继续普通分享。`post: null` 等同于不配置。
|
|
147
|
-
|
|
148
|
-
截图分享：
|
|
149
|
-
|
|
150
|
-
```ts
|
|
151
|
-
await share.screenshot({
|
|
152
|
-
delay: 100,
|
|
153
|
-
saveToAlbum: true,
|
|
154
|
-
post: {
|
|
155
|
-
topicIds: [235709, 66739],
|
|
156
|
-
topics: ['无畏契约战绩'],
|
|
157
|
-
},
|
|
158
|
-
});
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
截图分享支持多个预置分区；分区与话题仍由用户在客户端发帖页中确认和修改，SDK 不会直接发布内容。通过截图分享进入社区发帖流程时，客户端会自动把帖子关联到当前小程序，开发者无需配置额外来源字段。
|
|
162
|
-
|
|
163
|
-
### 基础 UI
|
|
164
|
-
|
|
165
|
-
```ts
|
|
166
|
-
import { ui } from '@heybox/hb-sdk';
|
|
167
|
-
|
|
168
|
-
await ui.showToast({
|
|
169
|
-
message: '保存成功',
|
|
170
|
-
status: 'success',
|
|
171
|
-
});
|
|
172
|
-
|
|
173
|
-
await ui.showLoading({
|
|
174
|
-
dismissible: true,
|
|
175
|
-
});
|
|
176
|
-
|
|
177
|
-
await ui.hideLoading();
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
`showToast()` 的 `message` 会 trim 后发送给宿主，不能为空，最长 120 个字符；`status` 只支持 `success` 和 `error`，不传时展示普通文本 toast。loading 是全局单例，多次 `showLoading()` 会覆盖当前配置，`hideLoading()` 在未展示时也会成功。
|
|
181
|
-
|
|
182
|
-
### 设备能力
|
|
183
|
-
|
|
184
|
-
```ts
|
|
185
|
-
import { device } from '@heybox/hb-sdk';
|
|
186
|
-
|
|
187
|
-
await device.vibrate({
|
|
188
|
-
intensity: 'light',
|
|
189
|
-
delay: 0,
|
|
190
|
-
});
|
|
191
|
-
|
|
192
|
-
await device.setClipboard({
|
|
193
|
-
text: 'hello',
|
|
194
|
-
});
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
`vibrate()` 的 `intensity` 默认为 `light`，还支持 `medium` 和 `heavy`；`delay` 默认为 `0`，必须是 `0..5000` 的整数毫秒。`setClipboard()` 第一版只支持文本写入，`text` 必须是非空字符串，最长 10000 个字符，不会自动 trim 写入内容，也不提供读取或清空剪贴板能力。
|
|
198
|
-
|
|
199
|
-
### 导航控制
|
|
200
|
-
|
|
201
|
-
```ts
|
|
202
|
-
import { navigation } from '@heybox/hb-sdk';
|
|
203
|
-
|
|
204
|
-
await navigation.reload();
|
|
205
|
-
await navigation.close();
|
|
206
|
-
|
|
207
|
-
await navigation.openAppPage({
|
|
208
|
-
target: 'game_detail',
|
|
209
|
-
appId: 578080,
|
|
210
|
-
gameType: 'pc',
|
|
211
|
-
});
|
|
212
|
-
|
|
213
|
-
await navigation.openAppPage({
|
|
214
|
-
target: 'user_detail',
|
|
215
|
-
userId: '239040',
|
|
216
|
-
});
|
|
217
|
-
|
|
218
|
-
await navigation.openAppPage({
|
|
219
|
-
target: 'post_detail',
|
|
220
|
-
linkId: 57670836,
|
|
221
|
-
rootCommentId: 123,
|
|
222
|
-
commentId: 456,
|
|
223
|
-
});
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
`navigation.close()` 请求宿主关闭当前小程序容器，`navigation.reload()` 请求宿主重载当前小程序页面/容器。调用后 JS 上下文可能被宿主销毁，不保证后续代码继续执行；这两个能力不接受 `reason`、`force`、`confirm` 或 `fallbackUrl` 等扩展参数。
|
|
227
|
-
|
|
228
|
-
`navigation.openAppPage()` 请求宿主打开受 SDK 白名单约束的黑盒 App 页面。当前支持 `target: 'game_detail'`，必填 `appId` 与 `gameType`；`gameType` 支持 `pc`、`console`、`mobile`，可选 `page: 'game' | 'wiki'`、`hSrc`、`skuId`。也支持 `target: 'user_detail'`，必填 `userId`；支持 `target: 'post_detail'`，必填 `linkId`，可选 `rootCommentId` 与 `commentId` 定位评论。
|
|
229
|
-
|
|
230
|
-
### 窗口信息
|
|
231
|
-
|
|
232
|
-
```ts
|
|
233
|
-
import { viewport } from '@heybox/hb-sdk';
|
|
234
|
-
|
|
235
|
-
const windowInfo = await viewport.getWindowInfo();
|
|
236
|
-
|
|
237
|
-
console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
### 导航栏样式
|
|
241
|
-
|
|
242
|
-
```ts
|
|
243
|
-
import { viewport } from '@heybox/hb-sdk';
|
|
244
|
-
|
|
245
|
-
await viewport.setNavigationBarStyle({
|
|
246
|
-
foregroundStyle: 'light',
|
|
247
|
-
});
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
`foregroundStyle` 设置导航栏关闭按钮与状态栏图标/文字的明暗样式：`light` 表示白色前景，适合深色背景；`dark` 表示黑色前景，适合浅色背景。该能力不设置导航栏背景色，也不支持关闭按钮与状态栏分别配置。
|
|
251
|
-
|
|
252
|
-
### 隔离 Storage
|
|
253
|
-
|
|
254
|
-
```ts
|
|
255
|
-
import { storage } from '@heybox/hb-sdk';
|
|
256
|
-
|
|
257
|
-
await storage.setStorage({
|
|
258
|
-
key: 'settings',
|
|
259
|
-
data: {
|
|
260
|
-
theme: 'dark',
|
|
261
|
-
},
|
|
262
|
-
});
|
|
263
|
-
|
|
264
|
-
const { data } = await storage.getStorage<{ theme: string }>({
|
|
265
|
-
key: 'settings',
|
|
266
|
-
});
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
storage key 只允许 1-128 位字母、数字、下划线和连字符。父容器会按小程序维度隔离 key，外部小程序不能读写黑盒客户端全局 storage。
|
|
270
|
-
|
|
271
|
-
### 云端排行榜
|
|
272
|
-
|
|
273
|
-
`cloud.leaderboard` 是平台托管的远端排行榜能力，不是本地 storage，也不是通用网络请求。小程序页面不能传 `userId`；宿主和服务端会按当前登录用户注入身份。
|
|
274
|
-
|
|
275
|
-
```ts
|
|
276
|
-
import { cloud } from '@heybox/hb-sdk';
|
|
277
|
-
|
|
278
|
-
const entry = await cloud.leaderboard.submit({
|
|
279
|
-
key: 'cube_run_total',
|
|
280
|
-
score: 150,
|
|
281
|
-
extra: {
|
|
282
|
-
run: 2,
|
|
283
|
-
},
|
|
284
|
-
});
|
|
285
|
-
|
|
286
|
-
const list = await cloud.leaderboard.getList({
|
|
287
|
-
key: 'cube_run_total',
|
|
288
|
-
limit: 20,
|
|
289
|
-
});
|
|
290
|
-
|
|
291
|
-
const current = await cloud.leaderboard.getCurrentUserEntry({
|
|
292
|
-
key: 'cube_run_total',
|
|
293
|
-
});
|
|
294
|
-
|
|
295
|
-
await cloud.leaderboard.deleteCurrentUserEntry({
|
|
296
|
-
key: 'cube_run_total',
|
|
297
|
-
});
|
|
298
|
-
|
|
299
|
-
const info = await cloud.leaderboard.getInfo({
|
|
300
|
-
key: 'cube_run_total',
|
|
301
|
-
});
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
排行榜需要先通过管理端创建；管理端创建成功时服务端会同步准备记录集合，之后运行时可立即读写。`key` 不传时服务端会查找当前小程序已创建的 `default` 榜单，不存在时会拒绝请求，不会自动创建空榜。单个小程序最多创建 3 个排行榜，超出时服务端返回 `LEADERBOARD_LIMIT_EXCEEDED`。
|
|
305
|
-
|
|
306
|
-
`order` 在创建榜单时固定，`desc` 表示分数越大越靠前，`asc` 表示分数越小越靠前。同分时按更早更新时间优先，再按 `userId` 稳定排序。`rankLimit` 为 `0` 表示列表不限制展示名次；大于 `0` 时限制 `getList()` 展示范围。当前用户记录仍会保留，但 `submit()` 和 `getCurrentUserEntry()` 只精确计算前 5000 名，且会优先受 `rankLimit` 限制；超过 `min(rankLimit, 5000)`（`rankLimit=0` 时按 5000）时返回 `ranked: false`、`rank: 0`。
|
|
307
|
-
|
|
308
|
-
`submit()` 只在本次 `score` 更优时更新当前用户记录，并返回最终 `LeaderboardEntry`；如果分数不更优，`extra` 也不会更新。同一用户同一榜单的并发提交由服务端串行保护，锁冲突时返回 `LEADERBOARD_SUBMIT_LOCKED`，业务可稍后重试。首次提交未传 `extra` 会保存为空对象；已有记录提交更优分数但未传 `extra` 时会保留旧 `extra`，需要清空时请显式传 `{}`。`score` 必须是有限安全数字，绝对值不能超过 `Number.MAX_SAFE_INTEGER`；`extra` 必须是 JSON 对象，序列化后的 UTF-8 长度不能超过 2048 字节。
|
|
309
|
-
|
|
310
|
-
`getList()` 默认 20 条、最多 100 条；`cursor` 是服务端返回的不透明分页游标，只能把上一页返回的值原样传给下一次 `getList()`，不要解析、拼接或自行构造。非法 cursor 会按参数错误拒绝。服务端会短暂缓存榜单头部结果，当前缓存前 500 条或 `rankLimit` 范围内记录，`submit()`、`deleteCurrentUserEntry()` 和管理端删榜会触发缓存失效；业务不要依赖毫秒级实时刷新。`getInfo()` 返回 `key/order/rankLimit`，其中 `rankLimit` 不包含当前用户记录的 5000 名精确排名计算上限。
|
|
311
|
-
|
|
312
|
-
排行榜后端错误会保留为 `HbMiniProgramSDKError.code`，常见值包括 `LEADERBOARD_DEFAULT_NOT_FOUND`、`LEADERBOARD_LIMIT_EXCEEDED`、`LEADERBOARD_SUBMIT_LOCKED`、`LEADERBOARD_TABLE_NOT_READY`、`InvalidArgument`、`NotFound`、`ResourceExhausted`、`Unauthenticated`。业务可以按 `code` 区分未建榜、并发提交、数据表配置异常、参数错误、容量限制和未登录等场景。
|
|
313
|
-
|
|
314
|
-
### 网络请求
|
|
315
|
-
|
|
316
|
-
`network.request()` 提供窄化的 axios-like 接口。SDK 只接受公开请求字段，真实请求由父容器运行时映射到宿主网络能力。
|
|
317
|
-
|
|
318
|
-
```ts
|
|
319
|
-
import { HbMiniProgramNetworkError, network } from '@heybox/hb-sdk';
|
|
320
|
-
|
|
321
|
-
try {
|
|
322
|
-
const response = await network.request<{ ok: boolean }>({
|
|
323
|
-
url: 'https://api.example.com/demo',
|
|
324
|
-
method: 'GET',
|
|
325
|
-
headers: {
|
|
326
|
-
accept: 'application/json',
|
|
327
|
-
},
|
|
328
|
-
});
|
|
329
|
-
|
|
330
|
-
console.log(response.status, response.data.ok);
|
|
331
|
-
} catch (error) {
|
|
332
|
-
if (error instanceof HbMiniProgramNetworkError) {
|
|
333
|
-
console.log(error.response.status, error.response.data);
|
|
334
|
-
}
|
|
335
|
-
}
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
默认只有 `2xx` 会 resolve；`4xx/5xx` 这类已完成 HTTP 响应会抛出 `HbMiniProgramNetworkError`。可以用 `validateStatus` 调整 SDK 本地判定逻辑，函数不会跨 bridge 传给父容器。
|
|
339
|
-
|
|
340
|
-
```ts
|
|
341
|
-
await network.request({
|
|
342
|
-
url: 'https://api.example.com/demo',
|
|
343
|
-
validateStatus: (status) => status < 500,
|
|
344
|
-
});
|
|
345
|
-
```
|
|
346
|
-
|
|
347
|
-
支持的 HTTP method 为 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`。
|
|
348
|
-
|
|
349
|
-
`network.request` 由平台 Runtime 权限控制。未授权时 SDK 会收到 `PERMISSION_DENIED` 和“当前小程序暂不支持网络请求”；即使已开启网络请求，访问黑盒官方域名仍需要运营侧单独开启官方域名配置。业务代码不能自行请求或注入 Cookie、pkey 等官方凭据。
|
|
350
|
-
|
|
351
|
-
权限开启后，`network.request` 可以访问任意 HTTP(S) 目标，包括本机、局域网和保留地址。Runtime 不按目标地址类别拦截请求；宿主网络适配器仍负责实际连接、重定向和系统网络错误。
|
|
352
|
-
|
|
353
|
-
## 生命周期事件
|
|
354
|
-
|
|
355
|
-
导入 SDK 根包时会 eager 创建唯一默认实例并立即开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时不会创建第二个实例；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
|
|
356
|
-
|
|
357
|
-
```ts
|
|
358
|
-
import { on } from '@heybox/hb-sdk';
|
|
359
|
-
|
|
360
|
-
const unsubscribeShow = on('show', (payload) => {
|
|
361
|
-
console.log('页面展示', payload.timestamp, payload.source);
|
|
362
|
-
});
|
|
44
|
+
import { miniappManifest } from '@heybox/hb-sdk/vite';
|
|
45
|
+
import { defineConfig } from 'vite';
|
|
363
46
|
|
|
364
|
-
|
|
365
|
-
|
|
47
|
+
export default defineConfig({
|
|
48
|
+
base: './',
|
|
49
|
+
plugins: [miniappManifest()],
|
|
366
50
|
});
|
|
367
|
-
|
|
368
|
-
unsubscribeShow();
|
|
369
|
-
unsubscribeAuth();
|
|
370
51
|
```
|
|
371
52
|
|
|
372
|
-
|
|
53
|
+
完整接入步骤见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start)。
|
|
373
54
|
|
|
374
55
|
## 错误处理
|
|
375
56
|
|
|
376
|
-
|
|
57
|
+
初始化或能力调用失败时，SDK 会抛出公开错误：
|
|
377
58
|
|
|
378
59
|
```ts
|
|
379
|
-
import { HbMiniProgramSDKError
|
|
60
|
+
import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk';
|
|
380
61
|
|
|
381
62
|
try {
|
|
382
|
-
await ready();
|
|
63
|
+
await hbSDK.ready();
|
|
383
64
|
} catch (error) {
|
|
384
65
|
if (error instanceof HbMiniProgramSDKError) {
|
|
385
|
-
console.
|
|
386
|
-
}
|
|
387
|
-
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
网络请求已完成但 HTTP 状态不满足 `validateStatus` 时会抛出 `HbMiniProgramNetworkError`，其 `response` 字段包含标准化后的 `status`、`headers`、`data` 和原始公共请求配置快照。
|
|
391
|
-
|
|
392
|
-
## CLI
|
|
393
|
-
|
|
394
|
-
`@heybox/hb-sdk` 随包提供 `hb-sdk` CLI。脚手架项目已在 npm scripts 中接好常用命令；已有项目也可以自行添加 scripts。
|
|
395
|
-
|
|
396
|
-
| 命令 | 作用 |
|
|
397
|
-
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
398
|
-
| `hb-sdk create <project-name>` | 创建外部小程序模板。 |
|
|
399
|
-
| `hb-sdk dev [--runtime-url <url>]` | 启动 Vite 和浏览器 mock 宿主；远端权限可用时使用真实快照，否则以缺失快照启动并默认拒绝受管能力。 |
|
|
400
|
-
| `hb-sdk build [--env <name>]` | 直接使用项目 Vite 构建固定的 `dist/` 生产产物；不执行类型检查，也不要求登录或绑定小程序。 |
|
|
401
|
-
| `hb-sdk login [--login-base-url <url>] [--no-select-entity]` | 登录 Heybox，并把 CLI 自己需要的登录态和登录入口环境保存在本地缓存中；默认会引导多主体用户选择服务端 current entity。 |
|
|
402
|
-
| `hb-sdk login status` | 查看脱敏后的 CLI 登录态。 |
|
|
403
|
-
| `hb-sdk login clear` | 清理 CLI 登录态。 |
|
|
404
|
-
| `hb-sdk doctor` | 检查本机 `hb-sdk` Agent Skill 是否匹配当前 SDK，并输出手动安装/刷新命令。 |
|
|
405
|
-
| `hb-sdk remote access` | 查看当前 CLI 用户是否具备创建和管理工坊小程序的资格。 |
|
|
406
|
-
| `hb-sdk remote entity list` | 列出当前 CLI 用户可切换的开发者主体，并标记服务端 current entity。 |
|
|
407
|
-
| `hb-sdk remote entity current` | 查看服务端 current entity，以及该主体的小程序工坊权限状态。 |
|
|
408
|
-
| `hb-sdk remote entity switch <entity-id>` | 切换开发者平台服务端 current entity；不会修改项目绑定的小程序 ID。 |
|
|
409
|
-
| `hb-sdk remote list [--status <status>] [--keyword <text>]` | 列出当前 CLI 用户可管理的远端工坊小程序，用于发现并绑定当前项目。 |
|
|
410
|
-
| `hb-sdk remote create [--yes] [--force-bind]` | 在服务端 current entity 下创建远端工坊小程序并写入当前项目的 `package.json.heybox.miniProgramId`。 |
|
|
411
|
-
| `hb-sdk remote bind <mini-program-id> [--force]` | 校验当前 CLI 用户可管理目标小程序后，再把它绑定到当前项目。 |
|
|
412
|
-
| `hb-sdk remote info` | 查看当前项目绑定的小程序详情及完整只读 Runtime 权限/config。 |
|
|
413
|
-
| `hb-sdk remote allowlist list/add/remove/set ...` | 管理绑定小程序的预览白名单。 |
|
|
414
|
-
| `hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]` | 构建、上传并提交当前小程序版本审核；`--from-version` 复用指定历史版本产物。 |
|
|
415
|
-
| `hb-sdk remote versions` | 列出绑定小程序的远端版本。 |
|
|
416
|
-
| `hb-sdk remote preview <version>` | 查看指定版本的远端预览入口。 |
|
|
417
|
-
| `hb-sdk remote release <version> [--yes]` | 发布审核通过的版本；非 TTY 环境必须传 `--yes`。 |
|
|
418
|
-
| `hb-sdk remote withdraw <version> [--yes] [--reason <text>]` | 撤回审核中或已通过但未发布的版本；非 TTY 环境必须传 `--yes`。 |
|
|
419
|
-
| `hb-sdk remote take-down [--yes]` | 下架当前线上小程序；非 TTY 环境必须传 `--yes`。 |
|
|
420
|
-
| `hb-sdk remote reopen [--yes]` | 重新上架已下架的小程序；非 TTY 环境必须传 `--yes`。 |
|
|
421
|
-
| `hb-sdk remote square hide [--yes]` | 隐藏当前绑定小程序在普通用户侧的小程序工坊广场展示；白名单用户仍可见，直接链接不受影响；非 TTY 环境必须传 `--yes`。 |
|
|
422
|
-
| `hb-sdk remote square show` | 恢复当前绑定小程序在普通用户侧的小程序工坊广场展示。 |
|
|
423
|
-
|
|
424
|
-
远端平台操作统一放在 `hb-sdk remote` 命令组下；顶层 `hb-sdk deploy` 已硬切删除，不再作为兼容别名保留。`hb-sdk login` 仍是顶层命令，因为它管理 CLI 登录态，不绑定到某个具体小程序。开发者主体的事实源是服务端 current entity；CLI 登录缓存中的 `selectedEntity` 只是上次选择时的提示快照，用于 `login status` 展示和漂移排障，不能作为权限或归属判断依据。
|
|
425
|
-
|
|
426
|
-
`hb-sdk remote ...` 支持通用参数 `--json`、`--api-base-url <url>`、`--login-base-url <url>`、`--allow-unsafe-api-base-url` 和 `--verbose`。其中 `--json` 会让 stdout 只输出一个 JSON 对象，进度、警告和诊断信息不应污染 stdout。
|
|
427
|
-
|
|
428
|
-
所有命令都支持 `--verbose` / `-v`。默认输出只展示关键阶段状态、可访问 URL、下一步命令和可直接处理的错误提示；需要排查后端 envelope、HTTP 状态、trace id、原始响应体、cache 路径、API origin、逐文件上传进度或提交审核原始失败原因时，再追加 `--verbose` 查看详细调试信息。交互式终端会用颜色、符号和 loading 动画区分成功、警告、错误与耗时步骤；CI、非 TTY 和管道输出会退化为 `[hb-sdk] LEVEL ...` 这种稳定文本行。
|
|
429
|
-
|
|
430
|
-
## hb-sdk build
|
|
431
|
-
|
|
432
|
-
生产构建推荐使用：
|
|
433
|
-
|
|
434
|
-
```bash
|
|
435
|
-
hb-sdk build [--env <name>] [--verbose]
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
`hb-sdk build` 直接调用当前项目安装的 Vite，固定清理并重新生成 `dist/`，然后校验 `index.html`、`manifest.json` 和可上传产物。命令只负责生产构建，不执行 `scripts.build` 或 TypeScript 类型检查，也不需要 CLI 登录、项目绑定或远端网络。`--env <name>` 用于选择同名构建环境；除 `--env` 和 `--verbose` 外不提供其他构建参数。
|
|
439
|
-
|
|
440
|
-
项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。推荐让项目脚本保留类型检查：
|
|
441
|
-
|
|
442
|
-
```json
|
|
443
|
-
{
|
|
444
|
-
"scripts": {
|
|
445
|
-
"build": "vue-tsc --noEmit && hb-sdk build"
|
|
66
|
+
console.error(error.code, error.message);
|
|
67
|
+
} else {
|
|
68
|
+
throw error;
|
|
446
69
|
}
|
|
447
70
|
}
|
|
448
71
|
```
|
|
449
72
|
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
## hb-sdk remote deploy
|
|
453
|
-
|
|
454
|
-
`hb-sdk remote deploy` 把版本预检、build、CDN 上传、提交审核 API 串成单条命令。顶层 `hb-sdk deploy` 已删除；旧脚本必须改成 `hb-sdk remote deploy`。命令前置要求：
|
|
455
|
-
|
|
456
|
-
1. `package.json` 必须含 `heybox.miniProgramId` 字段，CLI 只从这里读 mini program id：
|
|
457
|
-
```json
|
|
458
|
-
{
|
|
459
|
-
"heybox": {
|
|
460
|
-
"miniProgramId": "mp_xxxxxxxx"
|
|
461
|
-
}
|
|
462
|
-
}
|
|
463
|
-
```
|
|
464
|
-
2. 已运行过 `hb-sdk login` 登录 Heybox；多主体用户应确认 `hb-sdk remote entity current` 指向要发布的主体。
|
|
465
|
-
3. 当前项目绑定的小程序必须属于服务端 current entity；如不一致，先运行 `hb-sdk remote entity switch <entity-id>` 切换主体。
|
|
466
|
-
4. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
|
|
467
|
-
5. 小程序名称、icon 和介绍图在开放平台版本发布中维护；CLI 项目配置只保留 `heybox.miniProgramId`。首次部署且无历史审核通过资料时，服务端使用默认名与默认图。
|
|
468
|
-
6. 每次部署都要准备发布日志：`hb-sdk remote deploy --release-note "..."`。发布日志 trim 后不能为空，最多 500 个字符，允许换行；CI / 非 TTY 环境缺失时会直接失败，TTY 环境会提示输入。
|
|
469
|
-
7. 项目根有 `scripts.build`，会被 CLI 通过 lockfile 自动选用的 `pnpm`、`yarn` 或 `npm` 触发；无 lockfile 时回退 `npm`。
|
|
470
|
-
8. 构建产物落在 `dist/`，包含 `index.html` 和 `manifest.json`。
|
|
471
|
-
|
|
472
|
-
执行流程：
|
|
73
|
+
网络状态码校验失败会抛出 `HbMiniProgramNetworkError`。错误字段和处理建议见 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/)。
|
|
473
74
|
|
|
474
|
-
|
|
475
|
-
2. 读取服务端 current entity 和绑定小程序详情，确认 `detail.entity_id` 与 current entity 一致；主体不一致时直接失败，不触发 precheck、build、upload 或 submit audit。
|
|
476
|
-
3. 普通 remote deploy 读取 `package.json.version`，主体校验通过后、build 前调用 `/mall/developer/user_miniprogram/version/precheck`，入参为 `mini_program_id`、`version`、`release_note`、`auto_publish`。
|
|
477
|
-
4. 触发 `<pm> run build`。
|
|
478
|
-
5. 解析 `dist/manifest.json`，校验 `version` 与自动生成的 `sdkVersion` 均为合法 SemVer，自动剥离 BOM；普通 remote deploy 要求业务版本与 precheck 使用的 `package.json.version` 一致。
|
|
479
|
-
6. `--from-version <version>` 会跳过本地 build、`dist/` 读取和 CDN 上传，直接让远端复用指定历史版本产物提交审核。
|
|
480
|
-
7. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
|
|
481
|
-
8. 校验所有上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
|
|
482
|
-
9. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 COS。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
|
|
483
|
-
10. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
|
|
484
|
-
11. 全部上传成功后调用 `/mall/developer/user_miniprogram/version/submit_audit`；`--from-version` 路径会直接调用提交审核接口并传入 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL；后端原始失败细节只在 `--verbose` 下展示。
|
|
75
|
+
## 能力概览
|
|
485
76
|
|
|
486
|
-
|
|
77
|
+
除 `ready()` 外，SDK 还提供 `on()` 和 `off()` 处理前后台、登录态等生命周期事件。
|
|
487
78
|
|
|
488
|
-
|
|
79
|
+
| 模块 | 用途 |
|
|
80
|
+
| ------------ | -------------------------------- |
|
|
81
|
+
| `auth` | 由用户操作触发登录 |
|
|
82
|
+
| `user` | 读取当前用户、账号资料和游戏数据 |
|
|
83
|
+
| `share` | 打开分享或截图分享流程 |
|
|
84
|
+
| `ui` | 展示 Toast 和 Loading |
|
|
85
|
+
| `device` | 调用振动和剪贴板能力 |
|
|
86
|
+
| `navigation` | 关闭、刷新页面或打开小黑盒页面 |
|
|
87
|
+
| `viewport` | 读取窗口信息和设置导航栏样式 |
|
|
88
|
+
| `storage` | 读写当前小程序的隔离存储 |
|
|
89
|
+
| `cloud` | 使用小程序云端排行榜 |
|
|
90
|
+
| `network` | 发起经过平台授权的网络请求 |
|
|
489
91
|
|
|
490
|
-
|
|
92
|
+
具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
|
|
491
93
|
|
|
492
|
-
|
|
94
|
+
## 关键约束
|
|
493
95
|
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
|
|
500
|
-
hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
|
|
501
|
-
hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
|
|
502
|
-
|
|
503
|
-
HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.1:8080 --release-note "本地后台联调"
|
|
504
|
-
```
|
|
96
|
+
- `ready()` 不代表用户已登录；使用 `user.getInfo()` 判断登录状态。
|
|
97
|
+
- `auth.login()` 只能由明确的用户操作触发，不要在页面初始化时自动登录。
|
|
98
|
+
- `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
|
|
99
|
+
- 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
|
|
100
|
+
- 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
|
|
505
101
|
|
|
506
|
-
|
|
102
|
+
## CLI 主流程
|
|
507
103
|
|
|
508
104
|
```bash
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
hb-sdk remote deploy --env test --release-note "测试环境验证" # 一次加载三项配置
|
|
515
|
-
hb-sdk remote info --env test # 复用同一预设
|
|
516
|
-
HB_SDK_ENV=test hb-sdk remote versions # 环境变量形式，CI 友好
|
|
517
|
-
hb-sdk remote deploy --env-file .env.local --release-note "本地联调" # 显式指定文件路径
|
|
518
|
-
hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度" # 单项 flag 覆盖预设
|
|
519
|
-
```
|
|
520
|
-
|
|
521
|
-
`--env <name>` 会读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级高于 `--env`；两者也可通过 `HB_SDK_ENV=<name>` 触发。加载遵循 dotenv 惯例：不覆盖进程已有的同名变量，因此 CI 或命令行显式设置的值优先。使用 `--env <name>` 或 `HB_SDK_ENV=<name>` 执行 `remote deploy` 时，CLI 还会把同一个 `name` 作为 `--mode <name>` 传给项目 build，使 CLI 后端环境与 Vite mode 保持一致。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。`--verbose` 会打印生效的文件路径和被跳过的 key。
|
|
522
|
-
|
|
523
|
-
`--api-base-url` 优先于 `HB_SDK_API_BASE_URL`，影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`--login-base-url` 优先于 `HB_SDK_LOGIN_BASE_URL`，用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。`--service-tag <tag>` 优先于 `HB_SDK_SERVICE_TAG`，给 Heybox 后台请求附加 `x-rylai-service-tag` header，并复用命中的 tag 追加 `special_tag` 请求参数，用于开发环境路由或灰度验证。仓库内开发也可继续在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 path-prefix 级 `special_tag`。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
|
|
524
|
-
|
|
525
|
-
## hb-sdk remote 命令参考
|
|
526
|
-
|
|
527
|
-
`hb-sdk remote` 默认作用于当前项目绑定的小程序，即 `package.json.heybox.miniProgramId`。`remote list` 只展示服务端 current entity 下可管理的小程序，用于发现和绑定；会改变远端状态的命令仍然只操作当前绑定的小程序，不接受临时 `mini_program_id` 参数。需要查看或切换开发者主体时，使用 `hb-sdk remote entity ...`；CLI 不会根据本地绑定自动切换主体。
|
|
528
|
-
|
|
529
|
-
| 命令 | 说明 |
|
|
530
|
-
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
531
|
-
| `hb-sdk remote access` | 查询当前 CLI 用户是否具备管理工坊小程序的资格。 |
|
|
532
|
-
| `hb-sdk remote entity list` | 列出可切换开发者主体，并标记服务端 current entity。 |
|
|
533
|
-
| `hb-sdk remote entity current` | 查看服务端 current entity 和该主体的小程序工坊权限状态。 |
|
|
534
|
-
| `hb-sdk remote entity switch <entity-id>` | 切换服务端 current entity；只允许切到 `entity list` 返回的主体。 |
|
|
535
|
-
| `hb-sdk remote list [--status <status>] [--keyword <text>]` | 列出 current entity 下当前 CLI 用户可管理的小程序，并标出当前绑定项。 |
|
|
536
|
-
| `hb-sdk remote create [--yes] [--force-bind]` | 在 current entity 下创建远端小程序并绑定当前项目；多主体非 TTY 环境必须传 `--yes` 确认使用当前主体；已有绑定时必须显式传 `--force-bind` 才能覆盖。 |
|
|
537
|
-
| `hb-sdk remote bind <mini-program-id> [--force]` | 先校验 current entity 可管理目标小程序，再写入当前项目绑定；`--force` 只允许覆盖本地绑定，不跳过远端校验或主体一致性校验。 |
|
|
538
|
-
| `hb-sdk remote info` | 查看当前绑定小程序的远端详情。 |
|
|
539
|
-
| `hb-sdk remote allowlist list` | 查看预览白名单。 |
|
|
540
|
-
| `hb-sdk remote allowlist add <heybox-id...>` | 添加十进制 Heybox ID 到预览白名单。 |
|
|
541
|
-
| `hb-sdk remote allowlist remove <heybox-id...>` | 从预览白名单移除非 owner 条目。 |
|
|
542
|
-
| `hb-sdk remote allowlist set <heybox-id...>` | 替换非 owner 白名单条目，并保留平台返回的 owner 语义。 |
|
|
543
|
-
| `hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]` | 构建、上传或复用历史产物并提交当前版本审核。 |
|
|
544
|
-
| `hb-sdk remote versions` | 列出当前绑定小程序的远端版本。 |
|
|
545
|
-
| `hb-sdk remote preview <version>` | 查看指定版本的远端预览入口。 |
|
|
546
|
-
| `hb-sdk remote release <version> [--yes]` | 发布审核通过的版本；交互式终端会确认，非 TTY 必须传 `--yes`。 |
|
|
547
|
-
| `hb-sdk remote withdraw <version> [--yes] [--reason <text>]` | 撤回审核中或已通过但未发布的版本；交互式终端会确认，非 TTY 必须传 `--yes`。 |
|
|
548
|
-
| `hb-sdk remote take-down [--yes]` | 下架当前线上小程序；交互式终端会确认，非 TTY 必须传 `--yes`。 |
|
|
549
|
-
| `hb-sdk remote reopen [--yes]` | 重新上架已下架的小程序；交互式终端会确认，非 TTY 必须传 `--yes`。 |
|
|
550
|
-
| `hb-sdk remote square hide [--yes]` | 隐藏当前绑定小程序在普通用户侧的小程序工坊广场展示；白名单用户仍可见，直接链接不受影响；交互式终端会确认，非 TTY 必须传 `--yes`。 |
|
|
551
|
-
| `hb-sdk remote square show` | 恢复当前绑定小程序在普通用户侧的小程序工坊广场展示。 |
|
|
552
|
-
|
|
553
|
-
CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe SDK，也不会改变 `auth.login()`、`user.getInfo()`、`network.request()` 或 mock 宿主中的用户状态。`hb-sdk login` 成功后会尝试读取开发者主体列表：单主体自动确认或切换为 current entity，多主体交互式环境要求选择主体，多主体非 TTY 环境只提示后续运行 `hb-sdk remote entity switch <entity-id>`；显式传 `--no-select-entity` 时只写登录态，不修改服务端 current entity。`hb-sdk login status` 默认展示脱敏状态、`heyboxId`、`loginBaseUrl`、登录时间和本地 `selectedEntity` 提示快照；`--verbose` 额外展示 cache 路径。不输出 `pkey`、cookie 或完整请求头。`selectedEntity` 不是权限事实源，每次 remote 命令仍以服务端 current entity 为准。
|
|
554
|
-
|
|
555
|
-
`create`、`dev`、`remote ...`、`login`、`login status`、`login clear`、`doctor` 这些 CLI 命令会在成功执行后检查 npm registry 上的 `@heybox/hb-sdk@latest`。普通命令的检查结果会缓存 24 小时；如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。`doctor` 已经诊断出 `SDK_MISMATCH` 时不会再追加统一提醒，避免同一次输出里重复提示升级 SDK。`hb-sdk --version` / `hb-sdk -V` 会直接请求 npm registry 获取 latest，不读取本地缓存；stdout 只输出版本号，升级提醒继续按 warn 级别写到 stderr。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒；`CI=true` 时也会自动跳过检查。
|
|
556
|
-
|
|
557
|
-
## SDK 与 Runtime
|
|
558
|
-
|
|
559
|
-
`@heybox/hb-sdk` 跑在 iframe 内部，由外部小程序业务页面使用。`@heybox/hb-sdk-runtime` 跑在 iframe 外部，由黑盒宿主壳层使用，负责启动 iframe、注入 nonce、维护 bridge server、注册能力 handler、转发宿主生命周期与登录态变化。
|
|
560
|
-
|
|
561
|
-
两者共享同一套 bridge 协议。协议字段、事件名或能力 payload 发生变化时，应按同一批次联动升级 SDK 与 runtime；不要只升级其中一侧后假定另一侧自动兼容。
|
|
562
|
-
|
|
563
|
-
## 能力边界
|
|
564
|
-
|
|
565
|
-
- 导入 SDK 根包时会 eager 创建唯一默认实例并立即开始握手；`ready()` 只等待这次握手结果。
|
|
566
|
-
- `ready()` 只等待已有握手结果，不主动触发新的握手；调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
|
|
567
|
-
- `user.getInfo()`、`user.getCurrentUserDetail()`、`user.getCurrentUserProfile()`、`user.getPlatformAccountOverview()`、`user.getPlatformAccountInfo(platform)` 和 `user.getSteamGameList(options)` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
|
|
568
|
-
- 当前用户详情和平台账号 API 只允许读取当前登录用户，不支持传入 `userid` 查询其他人，也不透传 `/account/home_v2/` 原始响应。
|
|
569
|
-
- 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
|
|
570
|
-
- `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
|
|
571
|
-
- `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
|
|
572
|
-
- 构建产物可以包含 `dist/manifest.json`，业务代码不应自行 fetch 已部署的 manifest；这个文件由发布流水线读取并上送后台。
|
|
573
|
-
|
|
574
|
-
## Manifest
|
|
575
|
-
|
|
576
|
-
`@heybox/hb-sdk/vite` 提供构建时插件 `miniappManifest()`。项目通过 `hb-sdk build` 完成生产构建后，会在固定的 `dist/` 中写入 `manifest.json`：
|
|
577
|
-
|
|
578
|
-
```json
|
|
579
|
-
{
|
|
580
|
-
"version": "1.2.3",
|
|
581
|
-
"sdkVersion": "0.6.1"
|
|
582
|
-
}
|
|
105
|
+
hb-sdk create my-miniapp
|
|
106
|
+
hb-sdk dev
|
|
107
|
+
hb-sdk build
|
|
108
|
+
hb-sdk remote deploy --release-note "本次更新说明"
|
|
583
109
|
```
|
|
584
110
|
|
|
585
|
-
|
|
111
|
+
| 命令 | 用途 |
|
|
112
|
+
| ---------------------- | -------------------------------------- |
|
|
113
|
+
| `hb-sdk create` | 创建带默认配置的工坊小程序 |
|
|
114
|
+
| `hb-sdk dev` | 启动浏览器 Mock 和真机调试入口 |
|
|
115
|
+
| `hb-sdk build` | 执行生产构建与产物校验，不包含类型检查 |
|
|
116
|
+
| `hb-sdk remote deploy` | 构建、上传并提交当前版本审核 |
|
|
586
117
|
|
|
587
|
-
|
|
588
|
-
import { miniappManifest } from '@heybox/hb-sdk/vite';
|
|
589
|
-
import { defineConfig } from 'vite';
|
|
590
|
-
|
|
591
|
-
export default defineConfig({
|
|
592
|
-
base: './',
|
|
593
|
-
plugins: [miniappManifest()],
|
|
594
|
-
});
|
|
595
|
-
```
|
|
596
|
-
|
|
597
|
-
`base: './'` 用于让构建产物里的 JS/CSS/图片资源以 `./assets/...` 相对路径引用，避免小程序资源目录不是站点根路径时访问 `/assets/...` 失败。若没有显式配置 `base`，`miniappManifest()` 也会在 build 时默认补成 `./`。
|
|
598
|
-
|
|
599
|
-
工坊小程序构建产物只能在兼容的小黑盒 Runtime 中启动。普通浏览器直接打开时不会执行标准业务脚本，并会提示在小黑盒 APP 内打开。项目应使用标准 Vite module 入口。
|
|
600
|
-
|
|
601
|
-
插件只接受单页应用：输出目录只能存在入口 `index.html`。build 和 dev 都会把平台 CSP 插入 `<head>` 首位，已有 CSP 始终原样保留；两份策略按浏览器交集生效。平台 CSP 在脚本、样式、图片、字体和媒体指令中放行 `xiaoheihe.cn`、`max-c.com`、`debugmode.cn`、`maxjia.com` 的 HTTPS 根域及子域；入口 HTML 中相应资源标签也可使用这些官方 HTTPS URL。
|
|
602
|
-
|
|
603
|
-
平台 CSP 会禁止 `fetch`、XHR、WebSocket、EventSource、Beacon、Worker、iframe、表单和对象加载等浏览器原生出口；`connect-src` 始终为 `'none'`，dev 只额外放行当前 Vite 的精确 HMR WebSocket 地址。需要宿主授权的业务网络请求仍应使用 `network.request()`。
|
|
604
|
-
|
|
605
|
-
meta refresh、外部 anchor、`dns-prefetch`、`preconnect`、`prerender`、非官方外部资源 URL 和额外 HTML 会使 build 失败。内联 script/style 允许，但 `unsafe-eval` 不允许。`dev`、`hb-sdk build` 和手动 Vite build 都不请求远端最低 SDK 版本；构建仍会把当前 `sdkVersion` 写入 Manifest，`hb-sdk remote deploy` 仍校验 Manifest 结构并经过服务端 precheck / submit-audit 策略。
|
|
606
|
-
|
|
607
|
-
失败与警告语义：
|
|
608
|
-
|
|
609
|
-
- 读取 `package.json` 失败或 JSON 解析失败：build 直接失败，并输出具体原因。
|
|
610
|
-
- `package.json.version` 不是非空字符串：build 直接失败。
|
|
611
|
-
- `package.json.version` 仍是模板默认值 `0.0.0`：build 直接失败，必须改成实际 SemVer。
|
|
612
|
-
- 版本号不是严格 SemVer、包含 build metadata 或缺少 `sdkVersion`：build/deploy 直接失败。
|
|
613
|
-
|
|
614
|
-
`manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
|
|
615
|
-
|
|
616
|
-
## 导出
|
|
617
|
-
|
|
618
|
-
默认导出 `hbSDK`，包含 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`、`cloud`、`network`、`ui`、`device`、`navigation`。
|
|
619
|
-
|
|
620
|
-
常用命名导出：
|
|
621
|
-
|
|
622
|
-
- `ready`、`on`、`off`
|
|
623
|
-
- `auth`、`user`、`share`、`viewport`、`storage`、`cloud`、`network`、`ui`、`device`、`navigation`
|
|
624
|
-
- `HbMiniProgramSDKError`、`HbMiniProgramNetworkError`
|
|
625
|
-
- 各模块公开类型，例如 `MiniProgramNetworkRequestConfig`、`MiniProgramNetworkResponse`、`MiniProgramUserInfoResult`
|
|
626
|
-
|
|
627
|
-
协议常量、消息类型、能力目录、payload/result 映射、守卫和 Runtime 权限快照解析器只通过 `@heybox/hb-sdk/protocol` 子入口导出。`parseMiniProgramRuntimePermissions` 是正式 Runtime 与 Mock Host 共用的 fail-closed 解析 owner；`@heybox/hb-sdk-runtime` 保留同名兼容导出。iframe 小程序业务代码不应构造 raw bridge message、解析宿主权限快照，也不应直接处理 nonce 或 `postMessage` 信封；宿主运行时等非业务页面代码使用 `@heybox/hb-sdk/protocol`。
|
|
628
|
-
|
|
629
|
-
构建时插件 `miniappManifest` 通过 `@heybox/hb-sdk/vite` 子入口导出，仅供 `vite.config.ts` 使用，不应在小程序业务代码里 import。
|
|
630
|
-
|
|
631
|
-
从 0.5 升级时请阅读 [0.6 迁移说明](./docs/migration-0.6.md)。
|
|
632
|
-
|
|
633
|
-
## 本仓库开发
|
|
634
|
-
|
|
635
|
-
```bash
|
|
636
|
-
pnpm --filter @heybox/hb-sdk run test:unit
|
|
637
|
-
pnpm --filter @heybox/hb-sdk run build:package
|
|
638
|
-
pnpm --filter @heybox/hb-sdk run check:boundary
|
|
639
|
-
pnpm exec hbexec hb-sdk check
|
|
640
|
-
```
|
|
118
|
+
远端提交前需要完成 CLI 登录和小程序绑定。完整的登录、绑定、预览、版本与发布流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。
|
|
641
119
|
|
|
642
|
-
|
|
120
|
+
## 文档
|
|
643
121
|
|
|
644
|
-
|
|
122
|
+
- [快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start)
|
|
123
|
+
- [CLI 与本地调试](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)
|
|
124
|
+
- [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)
|
|
125
|
+
- [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/)
|
|
126
|
+
- [小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)
|