@heybox/hb-sdk 0.9.1-alpha.5 → 0.9.1-alpha.7

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.1-alpha.7 - 2026-10-16
+
+### 新增能力
+
+- 新增 `network.upload()`，使用受控文件发送 raw PUT/POST 或 multipart 上传，支持查询参数、请求头、进度、取消与响应状态校验。
+
+### 问题修复
+
+- 文件和目录选择不再受普通请求超时限制，允许用户完成较长时间的系统选择操作。
+- 补充上传、文件系统与下载验收，并按实际平台能力处理大小边界和多选限制。
+
+## 0.9.1-alpha.6 - 2026-10-15
+
+### 新增能力
+
+- 新增 `hb-sdk feedback`，可打开小程序工坊反馈页面，或提交问题、复现步骤、日志与截图链接，进入现有私有客服工单。
+- 新增 `hb-sdk feedback list`、`detail` 和 `reply`，查看本人小程序工坊工单并向未关闭的原工单追加信息。
+
+### 文档与工具
+
+- 提交前后明确说明私有工单性质、编号与详情链接，并提示在 App「设置 → 帮助与反馈 → 我的反馈」跟进。
+- 智能体新建前先查看已有工单，确认同一问题后优先补充；服务端未确认工单隔离时拒绝读取和回复。
+- 补充开发常见问题及反馈入口。
+
 ## 0.9.1-alpha.5
 
 - 工作区卡片 Controller v2 支持在本地开发入口调试，并校验控制器依赖、权限及卡片参数。

package/README.md

@@ -56,7 +56,7 @@ hb-sdk skill install --all-agents
 
 SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。声明 `userInfo` 后，可通过 `user.getInfo()` 读取当前小程序内的隔离身份和已授权资料：
 
-使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 都只需要 `userInfo`，不依赖公开 `network` 权限；`network` 仅约束 `network.request()` 与 `network.download()`，线上使用仍需平台批准。`network` 和 `companion` 可在开放平台“小程序管理 → 权限申请”中提交申请，开发者不能申请访问官方域名。`hb-sdk dev` 可临时补齐普通网络和 Companion 的批准缺口，但不能补齐官方域名，调试台会持续提示发布后不可用。完整配置、本地调试边界和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
+使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 都只需要 `userInfo`，不依赖公开 `network` 权限；`network` 约束 `network.request()`、`network.download()` 与 `network.upload()`，线上使用仍需平台批准。`network` 和 `companion` 可在开放平台“小程序管理 → 权限申请”中提交申请，开发者不能申请访问官方域名。`hb-sdk dev` 可临时补齐普通网络和 Companion 的批准缺口，但不能补齐官方域名，调试台会持续提示发布后不可用。完整配置、本地调试边界和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
 
 需要可信用户手势的按钮不能在点击回调里等待握手。页面加载时先用 `getHandshakeState()` 读取当前状态，再用 `onHandshakeStateChange()` 订阅并立即接收当前状态；仅在 `status === 'ready'` 时启用按钮，并在组件或页面销毁时调用订阅返回的取消函数。`ready` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
 
@@ -181,7 +181,9 @@ console.log(info.sdk.version);
 
 `resizable` 只约束**用户手动拖拽**；**位置不开放**：开发者不能声明或设置窗口位置，位置由用户拖拽产生并由宿主按小程序身份本地记忆。完整语义见[窗口尺寸与可缩放性](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size)。
 
-## 文件与下载
+## 文件与传输
+
+`network.upload()` 接收一个可读 `FileHandle`，由 Host 直接流式上传到开发者指定 URL。raw 支持 PUT（默认）/POST，multipart 固定 POST 并可携带字符串字段；支持进度、取消、空闲超时、可选大小限制和标准 HTTP 响应。文件字节不经过 iframe，上传期间应保持源文件不变；首版不自动重试、分片、续传或复制快照。PC、Android、iOS、OHOS 按真实 Host primitive 启用，旧 Host 明确拒绝。完整示例见[文件能力与沙箱](https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox)。
 
 `files` 提供当前小程序私有 sandbox 和由用户选择授予的外部 File/Directory；
 `network.download()` 将 GET 响应直接流式写入受控目标，下载字节不经过 iframe bridge。
@@ -215,7 +217,8 @@ console.log(await downloaded.readText());
 不认识新 method 时返回 `METHOD_NOT_FOUND`。
 新 PC 的下载字节留在插件 Node 并直接原子落盘，不提供 Blob 或内存假实现。
 
-外部 picker 必须从可信用户操作触发。`files.saveFile({ suggestedName })` 返回精确 File 授权，
+外部 picker 必须从可信用户操作触发。`files.pickFiles()`、`files.pickDirectory()` 和
+`files.saveFile()` 的选择等待不设固定超时，不受 SDK 普通请求超时配置影响；确认、取消或 SDK / Runtime 会话结束后才结束操作。`files.saveFile({ suggestedName })` 返回精确 File 授权，
 不会额外保留 Directory 授权；新 PC 当前先让用户选择保存目录，再以 `suggestedName` 独占创建空文件，
 同名文件返回 `FILE_ALREADY_EXISTS`。V1 不接受 `accept`，只有 `pickFiles()` 支持扩展名过滤。完整路径、
 创建、存在性和下载语义见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start#文件与下载)。
@@ -326,7 +329,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `storage`    | 读写当前小程序的隔离存储                        |
 | `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
 | `cloud`      | 使用小程序云端排行榜                            |
-| `network`    | 发起经过平台授权的网络请求，并声明受控流式下载  |
+| `network`    | 发起经过平台授权的网络请求及受控文件传输  |
 | `companion`  | 准备、启动并控制当前版本审核过的桌面辅助应用    |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
@@ -512,3 +515,25 @@ Controller 使用 `@heybox/hb-sdk/card-controller` 编写，普通页面使用
 
 卡片合同只在开发构建时依赖私有 `@ai-desktop/view-contract`，发布 JS 与声明已封装所需代码和类型。
 用户安装 hb-sdk 不需要该私有包；`check:bundled-contract` 阻止未内联引用进入发布制品。
+
+## 开发反馈
+
+小程序工坊开发者反馈统一进入现有私有客服工单。登录后只能查看自己的反馈，客服通过现有后台派单和回复。
+
+```bash
+hb-sdk feedback                       # 打开现有反馈页面，预选开发者分类
+hb-sdk feedback --no-open              # 只输出地址
+hb-sdk feedback submit --desc "调用失败" --app-id app123 --api hb.network.request
+hb-sdk feedback submit --desc "调用失败" --screenshot https://cdn.example.com/error.png --json
+hb-sdk feedback list --json            # 先查看本人已有的小程序工坊工单
+hb-sdk feedback detail 9527 --json     # 查看内容和客服回复
+hb-sdk feedback reply 9527 --desc "补充复现步骤" --json
+```
+
+问题描述必填；AppID、关联 API、SDK 版本、环境、复现步骤、日志及截图选填。使用 `--scene` 补充复现步骤，`--log-file` 读取日志文件。完整正文最多 5000 字符；截图参数接受已经上传的 HTTP(S) URL，可重复，最多 10 张。CLI 不会上传本地图片文件，网页图片上传复用现有反馈页。
+
+提交时从现有分类接口查找“小程序工坊”分类（兼容原“小程序工坊开发者”和“小程序工坊开发者反馈”名称）及“开发中的常见问题”问题项，再调用 `/bbs/web/feedback/user/post`。分类未配置时拒绝提交；上线前需配置分类、问题项，并绑定客服组和派单优先级。提交结果包含原有工单 ID 和详情链接，不再创建独立 SDK 反馈记录。提交前会明确提示将创建私有反馈工单；使用提交时的同一小黑盒账号，在 App「设置 → 帮助与反馈 → 我的反馈」查看进展、客服回复或补充信息，也可打开返回的工单详情链接。`--json` 的成功结果包含 `message` 和 `follow_up` 说明，提交前提示输出到 stderr，不影响 stdout JSON 解析。
+
+列表支持 `--offset` 和 `--limit`（最多 50 条），详情和回复只允许访问当前登录账号在小程序工坊分类 `71` 下的工单。回复复用原工单，不占新建额度；已解决或关闭的工单不能继续回复。新能力需要后端支持范围隔离；服务未更新时会明确报错，不回退为读取全部工单。
+
+新建前先用 `feedback list` 查看已有工单，必要时用 `detail` 确认是否为同一问题；同一问题优先 `reply`。CLI 不会自动进行语义查重或合并，不能确认时由用户判断。

package/dist/cli-chunks/browser-DS7b1F4w.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+var index = require('./index-85kvRV7B.cjs');
+
+async function openExternalUrl(url) {
+    try {
+        await index.open(url);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+exports.openExternalUrl = openExternalUrl;

package/dist/cli-chunks/{build-D91J_GAa.cjs → build-Blt2jVCf.cjs}

@@ -1,29 +1,35 @@
 'use strict';
 
-var runtimeGate = require('./runtime-gate-CfAkz0p-.cjs');
+var runtimeGate = require('./runtime-gate-MNA7lKMW.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-L7OfyRcl.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-lj-frZ7T.cjs');
 require('node:crypto');
 require('node:zlib');
-var index = require('./index-TQwjvNjL.cjs');
-var projectVite = require('./project-vite-CN6mMjzX.cjs');
+var index = require('./index-85kvRV7B.cjs');
+var projectVite = require('./project-vite-C9OxeWTo.cjs');
 require('node:module');
 require('node:url');
 require('fs');
 require('path');
 require('os');
 require('inspector');
-require('./version-C_NaCZ8O.cjs');
+require('./version-CrnB-YNH.cjs');
 require('node:async_hooks');
+require('constants');
+require('stream');
+require('util');
+require('assert');
 require('readline');
 require('tty');
-require('assert');
 require('events');
-require('stream');
 require('buffer');
-require('util');
+require('node:process');
+require('node:buffer');
+require('node:util');
+require('node:child_process');
+require('node:os');
 
 function areStringArraysEqual(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);

package/dist/cli-chunks/{context-Xdd45FFd.cjs → context-LHhIFnwm.cjs}

@@ -3,10 +3,10 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-L7OfyRcl.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-lj-frZ7T.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-DZrr6RYK.cjs');
+var index = require('./index-85kvRV7B.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);
@@ -525,20 +525,20 @@ async function listUserMiniprogramVersions(options, runtime) {
 }
 async function remoteGet(path, query, runtime) {
     const pathWithQuery = createPathWithQuery(path, query);
-    const context = session.createHeyboxOpenPlatformRequestContext(runtime.session, pathWithQuery);
+    const context = index.createHeyboxOpenPlatformRequestContext(runtime.session, pathWithQuery);
     const fetchImpl = runtime.fetchImpl ?? fetch;
-    const response = await fetchImpl(session.createHeyboxApiUrl(runtime.baseUrl ?? context.baseUrl, pathWithQuery, context.platformParams), {
+    const response = await fetchImpl(index.createHeyboxApiUrl(runtime.baseUrl ?? context.baseUrl, pathWithQuery, context.platformParams), {
         method: 'GET',
         headers: context.headers,
     });
     return readRequiredResult(response, pathWithQuery);
 }
 async function remotePostForm(path, fields, runtime, options = {}) {
-    const context = session.createHeyboxOpenPlatformRequestContext(runtime.session, path, {
+    const context = index.createHeyboxOpenPlatformRequestContext(runtime.session, path, {
         contentType: 'application/x-www-form-urlencoded',
     });
     const fetchImpl = runtime.fetchImpl ?? fetch;
-    const response = await fetchImpl(session.createHeyboxApiUrl(runtime.baseUrl ?? context.baseUrl, path, context.platformParams), {
+    const response = await fetchImpl(index.createHeyboxApiUrl(runtime.baseUrl ?? context.baseUrl, path, context.platformParams), {
         method: 'POST',
         headers: context.headers,
         body: createFormBody(fields),
@@ -549,11 +549,11 @@ async function remotePostForm(path, fields, runtime, options = {}) {
     return readRequiredResult(response, path);
 }
 async function readRequiredResult(response, pathWithQuery) {
-    const result = await session.readHeyboxApiEnvelope(response, { pathWithQuery, requireResult: true });
+    const result = await index.readHeyboxApiEnvelope(response, { pathWithQuery, requireResult: true });
     return result;
 }
 async function readOptionalResult(response, pathWithQuery) {
-    return session.readHeyboxApiEnvelope(response, { pathWithQuery, requireResult: false });
+    return index.readHeyboxApiEnvelope(response, { pathWithQuery, requireResult: false });
 }
 function createPathWithQuery(path, query) {
     const params = new URLSearchParams();
@@ -586,16 +586,16 @@ function createFormBody(fields) {
 
 async function resolveRemoteEnvironment(options = {}, runtime = {}) {
     const env = options.env ?? process.env;
-    const apiBaseUrl = session.resolveHeyboxApiBaseUrl({ ...options, env });
-    const loginBaseUrl = session.resolveHeyboxLoginBaseUrl({ ...options, env });
-    const session$1 = options.session ?? (await (runtime.requireAuthSession ?? session.requireHeyboxAuthSession)({ loginBaseUrl }));
+    const apiBaseUrl = index.resolveHeyboxApiBaseUrl({ ...options, env });
+    const loginBaseUrl = index.resolveHeyboxLoginBaseUrl({ ...options, env });
+    const session = options.session ?? (await (runtime.requireAuthSession ?? index.requireHeyboxAuthSession)({ loginBaseUrl }));
     return {
         apiBaseUrl,
         loginBaseUrl,
         allowUnsafeApiBaseUrl: options.allowUnsafeApiBaseUrl === true || isTruthyEnvFlag(env.HB_SDK_ALLOW_UNSAFE_API_BASE_URL),
         env,
         fetchImpl: runtime.fetchImpl ?? options.fetchImpl ?? fetch,
-        session: session$1,
+        session,
     };
 }
 function createRemoteApiClientForEnvironment(environment) {

package/dist/cli-chunks/{create-BzpdRC5r.cjs → create-BCtecycP.cjs}

@@ -5,17 +5,24 @@ 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-TQwjvNjL.cjs');
+var index = require('./index-85kvRV7B.cjs');
 require('node:module');
 require('os');
-require('node:crypto');
+require('constants');
+require('stream');
+require('util');
+require('assert');
 require('readline');
 require('tty');
-require('assert');
 require('events');
-require('stream');
 require('buffer');
-require('util');
+require('node:crypto');
+require('node:process');
+require('node:buffer');
+require('node:url');
+require('node:util');
+require('node:child_process');
+require('node:os');
 
 var ejs = {};
 

package/dist/cli-chunks/{dev-C7acO3Kt.cjs → dev-5yTbdw-i.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var session = require('./session-DZrr6RYK.cjs');
-var context = require('./context-Xdd45FFd.cjs');
+var index = require('./index-85kvRV7B.cjs');
+var context = require('./context-LHhIFnwm.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-L7OfyRcl.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-lj-frZ7T.cjs');
 var os = require('node:os');
 var path = require('node:path');
 var net = require('node:net');
@@ -13,12 +13,11 @@ var node_http = require('node:http');
 var node_module = require('node:module');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-TQwjvNjL.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-CN6mMjzX.cjs');
-var version = require('./version-C_NaCZ8O.cjs');
+var browser = require('./browser-DS7b1F4w.cjs');
+var projectVite = require('./project-vite-C9OxeWTo.cjs');
+var version = require('./version-CrnB-YNH.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1993,8 +1992,8 @@ const DEFAULT_CHANNEL_TRANSPORT = {
 };
 const IPV4_LOOPBACK_ADDRESSES = new net.BlockList();
 IPV4_LOOPBACK_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
-const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-C7acO3Kt.cjs', document.baseURI).href)))('ws');
-const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-C7acO3Kt.cjs', document.baseURI).href)))('parse5');
+const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-5yTbdw-i.cjs', document.baseURI).href)))('ws');
+const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-5yTbdw-i.cjs', document.baseURI).href)))('parse5');
 const BROWSER_DEV_HOST_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'devtools/browser-dev-host'),
     path.resolve(__dirname, '../devtools/browser-dev-host'),
@@ -11094,7 +11093,7 @@ function assertNodeRuntimeCapabilities(ctx, settings) {
 function createNodeRealtimeDriverRegistry() {
     const registry = createRuntimeRealtimeDriverRegistry();
     registry.registerLazy('node-websocket', async () => {
-        const mod = await Promise.resolve().then(function () { return require('./index.esm-dgqkvowo.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-B2j8wByD.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -14905,7 +14904,7 @@ function createBrowserDevHostCliAuth(options = {}) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const noRedirectFetch = (input, init) => fetchImpl(input, { ...init, redirect: 'manual' });
     const store = options.store ?? { env: options.env };
-    const readSession = options.readSession ?? (() => session.readHeyboxAuthSession(store));
+    const readSession = options.readSession ?? (() => index.readHeyboxAuthSession(store));
     let lastKey = '';
     let revision = 0;
     let profileKey = '';
@@ -15810,7 +15809,7 @@ async function runDevCommand(options, runtime = {}) {
     let browserDevHost;
     try {
         browserDevHost = await runDevStartupTask(logger, '正在启动浏览器调试页服务', () => startBrowserDevHostServer({
-            openPlatformBaseUrl: session.resolveHeyboxOpenPlatformBaseUrl(runtime.env),
+            openPlatformBaseUrl: index.resolveHeyboxOpenPlatformBaseUrl(runtime.env),
             appUrl,
             devSessionId,
             devContext: currentDevContext,
@@ -16035,7 +16034,7 @@ async function loadDevLaunchContext(options) {
     const anonymous = (warning) => ({ context: { source: 'anonymous', warning,
             declaredPermissions: localPermissions.permissions ?? {}, platforms,
             runtimePermissions: runtimePermissionEnv.composeMiniappRuntimePermissions(localPermissions, undefined).runtimePermissions }, miniProgram: null });
-    if (!(await session.readHeyboxAuthSession({ env: options.env })))
+    if (!(await index.readHeyboxAuthSession({ env: options.env })))
         return anonymous('尚未登录 CLI，真实手机和 PC 调试不可用');
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId)

package/dist/cli-chunks/{doctor-BgHRDQmG.cjs → doctor-CnMPJ0xu.cjs}

@@ -3,19 +3,26 @@
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-TQwjvNjL.cjs');
+var index = require('./index-85kvRV7B.cjs');
 require('node:module');
-require('node:fs');
 require('path');
 require('os');
-require('node:crypto');
+require('fs');
+require('constants');
+require('stream');
+require('util');
+require('assert');
 require('readline');
 require('tty');
-require('assert');
 require('events');
-require('stream');
 require('buffer');
-require('util');
+require('node:crypto');
+require('node:process');
+require('node:buffer');
+require('node:url');
+require('node:util');
+require('node:child_process');
+require('node:fs');
 
 const CANDIDATES = [
     path.resolve(__dirname, '..', 'package.json'),