@heybox/hb-sdk 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.7.1
+
+### Docs / Agent Skill
+
+- 完善登录身份文档与自动握手接入 (@heybox/hb-sdk).
+
 ## 0.7.0
 
 - No user-facing hb-sdk package changes were detected from Conventional Commits.

package/dist/cli-chunks/{build-CsXk21Yi.cjs → build-i36rHC8w.cjs}

@@ -5,8 +5,8 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
 var runtimeGate = require('./runtime-gate-CtV7rWyX.cjs');
-var index = require('./index-EYRMHb10.cjs');
-var projectVite = require('./project-vite-eJ89lO8_.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
+var projectVite = require('./project-vite-DgIxZGf7.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-ClUhQYbA.cjs → context-DmtAhQC7.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var session = require('./session-DYEm6ALx.cjs');
+var session = require('./session-Y0Eur0YE.cjs');
 var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');

package/dist/cli-chunks/{create-vadbYtVj.cjs → create-D5bC0jY_.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-EYRMHb10.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-Dkk4qHsv.cjs → dev-CKPzEVZs.cjs}

@@ -6,15 +6,15 @@ var path = require('node:path');
 var net = require('node:net');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
-var context = require('./context-ClUhQYbA.cjs');
+var context = require('./context-DmtAhQC7.cjs');
 var node_crypto = require('node:crypto');
 var undici = require('undici');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-EYRMHb10.cjs');
-var projectVite = require('./project-vite-eJ89lO8_.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
+var projectVite = require('./project-vite-DgIxZGf7.cjs');
 var fs$1 = require('node:fs/promises');
 var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
-require('./session-DYEm6ALx.cjs');
+require('./session-Y0Eur0YE.cjs');
 require('fs');
 require('constants');
 require('stream');
@@ -1347,7 +1347,7 @@ function createHeyboxProtocol(payload) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0';
+    : '0.7.1';
 
 class DevPermissionOverrideStoreError extends Error {
     code;

package/dist/cli-chunks/{doctor-DzgWYWKU.cjs → doctor-CPdodzWY.cjs}

@@ -4,7 +4,7 @@ var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-EYRMHb10.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-EYRMHb10.cjs → index-BYXJJ0O2.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-EYRMHb10.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BYXJJ0O2.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-EYRMHb10.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BYXJJ0O2.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-EYRMHb10.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BYXJJ0O2.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-EYRMHb10.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BYXJJ0O2.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-EYRMHb10.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BYXJJ0O2.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13347,7 +13347,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.7.0';
+const BUILT_CLI_VERSION = '0.7.1';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13681,35 +13681,35 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-5TM5_o8q.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Da9gejmw.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-5TM5_o8q.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Da9gejmw.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-5TM5_o8q.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Da9gejmw.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-CsXk21Yi.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-i36rHC8w.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-vadbYtVj.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-D5bC0jY_.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-Dkk4qHsv.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-CKPzEVZs.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DzgWYWKU.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-CPdodzWY.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DxiHjrI9.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-iftAjHWt.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index-BMddcNGi.cjs → index-Dyim0XNM.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index$2 = require('./index-EYRMHb10.cjs');
+var index$2 = require('./index-BYXJJ0O2.cjs');
 var require$$0$2 = require('fs');
 var require$$2$1 = require('crypto');
 var require$$1$2 = require('path');

package/dist/cli-chunks/{login-5TM5_o8q.cjs → login-Da9gejmw.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-DYEm6ALx.cjs');
+var session = require('./session-Y0Eur0YE.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-EYRMHb10.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-eJ89lO8_.cjs → project-vite-DgIxZGf7.cjs}

@@ -5,7 +5,7 @@ var fs$1 = require('node:fs/promises');
 var node_module = require('node:module');
 var path = require('node:path');
 var node_url = require('node:url');
-var index = require('./index-EYRMHb10.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);

package/dist/cli-chunks/{remote-DxiHjrI9.cjs → remote-iftAjHWt.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var index = require('./index-EYRMHb10.cjs');
-var session = require('./session-DYEm6ALx.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
+var session = require('./session-Y0Eur0YE.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
@@ -10,7 +10,7 @@ var path = require('node:path');
 var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
 var runtimeGate = require('./runtime-gate-CtV7rWyX.cjs');
 var node_crypto = require('node:crypto');
-var context = require('./context-ClUhQYbA.cjs');
+var context = require('./context-DmtAhQC7.cjs');
 require('node:module');
 require('path');
 require('os');
@@ -271,7 +271,7 @@ function createDefaultCosClient(uploadToken, COS) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-BMddcNGi.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-Dyim0XNM.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{session-DYEm6ALx.cjs → session-Y0Eur0YE.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-EYRMHb10.cjs');
+var index = require('./index-BYXJJ0O2.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-EYRMHb10.cjs');
+var index = require('./cli-chunks/index-BYXJJ0O2.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');

package/dist/index.cjs.js

@@ -640,7 +640,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0';
+    : '0.7.1';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/index.esm.js

@@ -636,7 +636,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0';
+    : '0.7.1';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/vite.cjs.js

@@ -8,7 +8,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0';
+    : '0.7.1';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.0';
+    : '0.7.1';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",

package/skill/references/api-root.md

@@ -444,6 +444,8 @@ SDK 会自动完成握手。登录按钮应按上面的持久握手状态启用
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
+// 这是你自己的后端接口，不是黑盒 OpenAPI 地址。
+
 async function loginFromUserAction() {
   try {
     const result = await hbSDK.auth.login({ scopes: ['profile'] })

package/skill/references/cli.md

@@ -131,7 +131,7 @@ Dev Context 中调整的权限只影响当前本地调试，不会修改线上
 
 ### 浏览器 Mock 的边界
 
-浏览器 Mock 用于提高开发效率，不代表正式线上环境。本地网络调试通过开发工具转发，不提供黑盒原生凭据，也不能访问平台保留的 runtime auth 与 OpenAPI 内部路径。线上权限、客户端兼容性和最终交互仍需按真实发布配置验收。
+浏览器 Mock 用于提高开发效率，不代表正式线上环境。本地网络调试通过开发工具转发，不提供黑盒原生凭据，也不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；`auth.login()` 返回的本地模拟 code 也不能拿去请求生产 OpenAPI 换 token。线上权限、客户端兼容性和最终交互仍需按真实发布配置验收。
 
 ### 常用参数
 

package/skill/references/recipes.md

@@ -78,6 +78,8 @@ SDK 会自动完成握手。登录按钮应按上面的持久握手状态启用
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
+// 这是你自己的后端接口，不是黑盒 OpenAPI 地址。
+
 async function loginFromUserAction() {
   try {
     const result = await hbSDK.auth.login({ scopes: ['profile'] })
@@ -107,6 +109,8 @@ async function loginFromUserAction() {
 
 # 用户身份与登录
 
+`app_user_id` 是平台为“用户 × 当前小程序”生成的稳定、隔离标识，不是黑盒用户 ID。它是不透明字符串，只能在当前小程序内使用，不能解析或跨小程序关联。
+
 用户身份接入取决于小程序是否已开通 `network.request`。两类小程序使用不同的身份入口：
 
 | 小程序类型     | 身份入口                  | 结果用途                                               |
@@ -125,6 +129,8 @@ SDK 会在导入时自动握手，能力调用也会自动等待。不要在按
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 
+// 这是你自己的后端接口，不是黑盒 OpenAPI 地址。
+
 async function loginFromUserAction() {
   try {
     const { code, expiresIn, scopes } = await hbSDK.auth.login({ scopes: ['profile'] })
@@ -146,10 +152,10 @@ async function loginFromUserAction() {
 }
 ```
 
-返回值固定为 `{ code, expiresIn: 300, scopes }`：
+返回值为 `{ code, expiresIn, scopes }`。当前服务端签发的一次性 code 有效期为 300 秒，实际时长以响应中的 `expiresIn` 为准：
 
 - `code` 是一次性短期授权码，只能提交给当前小程序的开发者服务端。
-- `expiresIn` 固定为 `300` 秒，服务端应尽快使用，失败或过期后重新获取。
+- `expiresIn` 是服务端返回的有效期（当前为 `300` 秒）；服务端应尽快使用，失败或过期后重新获取，不要在业务代码中硬编码该值。
 - `scopes` 是本次授权码实际包含的 scope。
 
 `identity` 始终隐式包含，不需要也不能通过省略它来申请匿名授权。`scopes` 只填写业务确实需要的可选资料，例如 `profile`；不需要额外资料时直接调用 `auth.login()`。
@@ -158,6 +164,8 @@ async function loginFromUserAction() {
 
 开发者服务端用 access token 调用 `GET /user_miniprogram/openapi/v1/user` 读取当前用户。响应始终包含 `app_user_id`；token 含 `profile` 时还会返回 `nickname` 和 `avatar`。不要再请求已下线的 `/user/identity` 或 `/user/profile`。
 
+服务端完成换票后，应只把业务需要的 `app_user_id`、`nickname`、`avatar` 等资料或业务 session 返回给页面；页面不接触 access token。
+
 ## 用户操作和错误
 
 需要展示登录或授权 UI 时，调用必须来自按钮点击等可信用户手势，否则返回 `USER_GESTURE_REQUIRED`。用户取消、拒绝或关闭授权页面时返回 `AUTHORIZATION_CANCELLED`，业务应停留在当前页面并允许稍后重试。
@@ -214,7 +222,7 @@ async function getLocalIdentityFromUserAction() {
 }
 ```
 
-`user.getLocalIdentity()` 返回 `{ appUserId }`。同一用户在同一小程序中保持稳定，在不同小程序中取值不同；应把它当作不透明字符串，不要解析、跨小程序关联或当作黑盒用户 ID。
+`user.getLocalIdentity()` 返回 `{ appUserId }`，其中的 `appUserId` 就是上面介绍的当前小程序隔离身份。
 
 首次登录或尚未授予 identity 时，该调用可能展示 UI，因此 `getLocalIdentityFromUserAction` 必须绑定到按钮点击等可信用户操作；缺少可信手势时返回 `USER_GESTURE_REQUIRED`。用户取消、拒绝或关闭时返回 `AUTHORIZATION_CANCELLED`，不会确认或改变授权状态；业务应正常结束当前操作并允许稍后重试。
 
@@ -378,6 +386,8 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 
 已开通网络权限的小程序可以把“取得授权码并交给开发者服务端”收敛成一个用户操作函数：
 
+示例中的 URL 是开发者自己的后端接口，不是黑盒 OpenAPI 地址。
+
 ```ts
 import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.7.0+skill.f8e5c8b940ab",
+  "skillVersion": "0.7.0+skill.f24de3cc4cc5",
   "sdk": {
     "package": "@heybox/hb-sdk",
     "version": "0.7.0",
     "compatibility": "0.7.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-f8e5c8b940abd2e9c14ae3407bc99ed1a8a8b5fb15a2577433226ec48f0dad22"
+  "integrity": "sha256-f24de3cc4cc514f50dc45258570840a7f998be70f625afcf3ce8f8b41e197ff5"
 }