@heybox/hb-sdk 0.6.8-alpha.1 → 0.6.8

package/skill/references/cli.md

@@ -106,6 +106,8 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 
 未登录或未绑定小程序时，浏览器、Mac 和手机调试入口仍然可用，但受管能力会默认拒绝。登录并绑定后，调试页才能根据当前小程序的线上配置提示差异。
 
+`hb-sdk dev` 会在启动 Vite 前读取远端权限。只有远端权限快照有效、`network.request.status=enabled` 且 `useOfficialDomain=true` 时才跳过平台 CSP；未登录、未绑定、读取失败、非法快照或仅在 Dev Context 中开启本地权限覆盖时都继续注入 CSP。
+
 ### 2. 先用浏览器 Mock 验收
 
 浏览器 Mock 支持热更新，适合快速检查：
@@ -152,6 +154,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
 
+直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端权限；仅当 `network.request.status=enabled` 且 `useOfficialDomain=true` 时向子构建传递已验证上下文并跳过平台 CSP。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
+
 推荐由项目的 `scripts.build` 保留类型检查：
 
 ```json

package/skill/references/examples.md

@@ -48,7 +48,7 @@ export async function ensureLogin() {
 ### Network request
 
 ```ts
-import { ready, network, HbMiniProgramNetworkError } from '@heybox/hb-sdk';
+import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 try {
   await ready();
@@ -59,9 +59,23 @@ try {
     validateStatus: status => status >= 200 && status < 400,
   });
   console.log(response.data.ok);
+
+  // form POST only: App Host does not support multipart/form-data
+  await network.request({
+    url: 'https://api.example.com/form',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
+    },
+    data: new URLSearchParams({ gameId: '3', roleId: '1' }).toString(),
+  });
 } catch (error) {
   if (error instanceof HbMiniProgramNetworkError) {
-    console.warn(error.status, error.response?.data);
+    // Target HTTP non-2xx, or host-side network_error (message says so)
+    console.warn(error.status, error.message, error.data);
+  } else if (error instanceof HbMiniProgramSDKError) {
+    // e.g. INVALID_PARAMS for unsupported multipart shape
+    console.warn(error.code, error.message);
   }
 }
 ```
@@ -116,6 +130,7 @@ export default defineConfig({
 - Do not create raw `postMessage` bridge envelopes in business pages.
 - Do not call unsupported storage delete/clear/info operations.
 - Do not pass raw internal share/network protocol fields from mini-program code.
+- Do not send `multipart/form-data` (or handcrafted multipart bodies) through `network.request`; use form-urlencoded string body or a dedicated upload capability.
 - Do not treat `hb-sdk login` as iframe SDK authentication state.
 - Do not create a second mock runtime package when `hb-sdk dev` is the supported local mock workflow.
 - Do not import `@heybox/hb-sdk/vite` from iframe business code or fetch a deployed `manifest.json` directly.

package/skill/references/safety-boundaries.md

@@ -14,6 +14,8 @@
 - `auth.login()` 只能由明确的用户操作触发，不要在页面初始化时自动登录。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
+- 仅当远端已启用 `network.request` 且 `useOfficialDomain=true` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。
 - 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
 
 ## Agent rules

package/skill/scripts/sync-references.mjs

@@ -587,7 +587,7 @@ export async function ensureLogin() {
 
 ### Network request
 
-${fenced('ts', `import { ready, network, HbMiniProgramNetworkError } from '@heybox/hb-sdk';
+${fenced('ts', `import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 try {
   await ready();
@@ -598,9 +598,23 @@ try {
     validateStatus: status => status >= 200 && status < 400,
   });
   console.log(response.data.ok);
+
+  // form POST only: App Host does not support multipart/form-data
+  await network.request({
+    url: 'https://api.example.com/form',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
+    },
+    data: new URLSearchParams({ gameId: '3', roleId: '1' }).toString(),
+  });
 } catch (error) {
   if (error instanceof HbMiniProgramNetworkError) {
-    console.warn(error.status, error.response?.data);
+    // Target HTTP non-2xx, or host-side network_error (message says so)
+    console.warn(error.status, error.message, error.data);
+  } else if (error instanceof HbMiniProgramSDKError) {
+    // e.g. INVALID_PARAMS for unsupported multipart shape
+    console.warn(error.code, error.message);
   }
 }`)}
 
@@ -646,6 +660,7 @@ export default defineConfig({
 - Do not create raw \`postMessage\` bridge envelopes in business pages.
 - Do not call unsupported storage delete/clear/info operations.
 - Do not pass raw internal share/network protocol fields from mini-program code.
+- Do not send \`multipart/form-data\` (or handcrafted multipart bodies) through \`network.request\`; use form-urlencoded string body or a dedicated upload capability.
 - Do not treat \`hb-sdk login\` as iframe SDK authentication state.
 - Do not create a second mock runtime package when \`hb-sdk dev\` is the supported local mock workflow.
 - Do not import \`@heybox/hb-sdk/vite\` from iframe business code or fetch a deployed \`manifest.json\` directly.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.8-alpha.0+skill.e34106bdd1de",
+  "skillVersion": "0.6.8+skill.79001ff42152",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.8-alpha.0",
-    "compatibility": "0.6.8-alpha.0"
+    "version": "0.6.8",
+    "compatibility": "0.6.8"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-e34106bdd1dea827b5d991d2142e079bbdfa3cb4288141e1a6c7418ec2bf8ced"
+  "integrity": "sha256-79001ff42152003dc0b79b0ddd0945843f7eade237defb024c609a5d5b3048c0"
 }

package/types/core/network-sanitize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Mock Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+export type MiniProgramNetworkHeadersLike = Record<string, string>;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+export declare function sanitizeNetworkRequestUrl(url: string): string;
+/**
+ * 脱敏请求/响应头；敏感名（含 heybox 前缀）替换为 `[redacted]`。
+ */
+export declare function sanitizeNetworkHeaders(headers?: MiniProgramNetworkHeadersLike): MiniProgramNetworkHeadersLike;
+/**
+ * 预览请求/响应 data：递归脱敏敏感字段，截断长文本与大数组。
+ */
+export declare function previewNetworkData(data: unknown): unknown;
+/**
+ * 递归脱敏日志对象（payload / result）：敏感 key、headers、url 字段统一处理。
+ */
+export declare function redactNetworkLogValue(value: unknown): unknown;
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+export declare function sanitizeDiagnosticMessage(message: string): string;
+export declare function isSensitiveNetworkHeaderName(headerName: string): boolean;
+export declare function isSensitiveNetworkKey(key: string): boolean;

package/types/modules/network/index.d.ts

@@ -1,5 +1,7 @@
 import type { MiniProgramRequester } from '../../core/client';
 export { NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
+export { createNetworkRequestFailureLog, formatNetworkRequestFailureMessage, logNetworkRequestFailure, previewNetworkData, sanitizeNetworkHeaders, sanitizeNetworkRequestUrl, } from './observability';
+export { describeHostNetworkFailure, isMultipartContentType, isUnsupportedMultipartNetworkRequest, looksLikeMultipartBody, NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE, readNetworkContentType, } from './request-shape';
 /** `network.request` 请求头。 */
 export type MiniProgramNetworkHeaders = Record<string, string>;
 /** `network.request` 查询参数。 */

package/types/modules/network/observability.d.ts

@@ -0,0 +1,39 @@
+import type { MiniProgramNetworkHeaders, MiniProgramNetworkRequestConfig } from './index';
+export { previewNetworkData, redactNetworkLogValue, sanitizeDiagnosticMessage, sanitizeNetworkHeaders, sanitizeNetworkRequestUrl, } from '../../core/network-sanitize';
+export type NetworkRequestFailureKind = 'http_status' | 'invalid_response' | 'bridge_error' | 'unknown';
+export interface NetworkRequestFailureLog {
+    kind: NetworkRequestFailureKind;
+    method: string;
+    url: string;
+    status?: number;
+    statusText?: string;
+    code?: string;
+    message?: string;
+    headers?: MiniProgramNetworkHeaders;
+    dataPreview?: unknown;
+    timeout?: number;
+    withCredentials?: boolean;
+}
+/**
+ * 记录 `network.request` 失败，保证异常路径在开发者控制台可观测。
+ *
+ * @remarks
+ * - 仅用于诊断，不改变错误抛出语义。
+ * - 会脱敏 token/cookie 等敏感头与字段，并截断 body 预览。
+ * - detail 构造与 logger 调用均包在 try 内，日志失败不得影响业务错误抛出。
+ */
+export declare function logNetworkRequestFailure(config: MiniProgramNetworkRequestConfig, error: unknown, extras: {
+    kind: NetworkRequestFailureKind;
+    status?: number;
+    statusText?: string;
+    data?: unknown;
+    headers?: MiniProgramNetworkHeaders;
+}): void;
+export declare function createNetworkRequestFailureLog(config: MiniProgramNetworkRequestConfig, error: unknown, extras: {
+    kind: NetworkRequestFailureKind;
+    status?: number;
+    statusText?: string;
+    data?: unknown;
+    headers?: MiniProgramNetworkHeaders;
+}): NetworkRequestFailureLog;
+export declare function formatNetworkRequestFailureMessage(detail: NetworkRequestFailureLog): string;

package/types/modules/network/request-shape.d.ts

@@ -0,0 +1,44 @@
+/**
+ * network.request 请求体形态校验与宿主失败诊断文案。
+ *
+ * @remarks
+ * App Host 的 heybox 客户端代发 transport 仅声明 form/json，不支持 multipart。
+ * 本地 Mock 若直接走 fetch 会“能通”，上线后却变成难以理解的 500 network_error。
+ * 因此在 SDK 侧统一提前拒绝 multipart，并在宿主伪装 HTTP 失败时给出可操作提示。
+ */
+/** multipart 不被 App Host 支持时的稳定说明（开发者可见）。 */
+export declare const NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE = "network.request \u4E0D\u652F\u6301 multipart/form-data\u3002App Host \u5BA2\u6237\u7AEF\u4EE3\u53D1\u4EC5\u652F\u6301 application/x-www-form-urlencoded\uFF08form\uFF09\u4E0E application/json\uFF1B\u8BF7\u5C06 data \u7F16\u7801\u4E3A form \u5B57\u7B26\u4E32\uFF08\u4F8B\u5982 new URLSearchParams({...}).toString()\uFF09\u5E76\u8BBE\u7F6E Content-Type: application/x-www-form-urlencoded\u3002\u6587\u4EF6\u4E0A\u4F20\u8BF7\u4F7F\u7528\u4E13\u7528\u4E0A\u4F20\u80FD\u529B\uFF0C\u52FF\u624B\u5199 multipart boundary\u3002";
+/**
+ * 读取请求头中的 Content-Type（大小写不敏感）。
+ */
+export declare function readNetworkContentType(headers: Record<string, string> | undefined): string | undefined;
+/**
+ * 判断 Content-Type 是否声明为 multipart/form-data。
+ */
+export declare function isMultipartContentType(contentType: string | undefined): boolean;
+/**
+ * 判断字符串 body 是否像手写 multipart 实体。
+ */
+export declare function looksLikeMultipartBody(data: unknown): boolean;
+/**
+ * 判断公开请求配置是否使用了 Host 不支持的 multipart 形态。
+ */
+export declare function isUnsupportedMultipartNetworkRequest(config: {
+    data?: unknown;
+    headers?: Record<string, string>;
+}): boolean;
+/**
+ * 从宿主返回的“完成态”响应中提取更清晰的失败原因。
+ *
+ * @remarks
+ * Host 可能把 transport 不支持等内部错误包装成 HTTP 500 + `{ status: 'network_error', msg }`。
+ * 此时 `status=500` 并不代表目标站点返回了 500。
+ */
+export declare function describeHostNetworkFailure(response: {
+    config?: {
+        data?: unknown;
+        headers?: Record<string, string>;
+    };
+    data?: unknown;
+    status: number;
+}): string | undefined;

package/types/vite/html-policy.d.ts

@@ -1,4 +1,5 @@
 export declare const PRODUCTION_CSP: string;
 export declare function enforceMiniappHtmlPolicy(html: string, options?: {
     hmrWebSocketUrl?: string;
+    skipPlatformCsp?: boolean;
 }): string;

package/types/vite/runtime-permission-env.d.ts

@@ -0,0 +1,9 @@
+export declare const HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV = "HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN";
+export declare const HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV = "HB_SDK_RUNTIME_PERMISSION_CONTEXT";
+export declare function shouldSkipMiniappPlatformCspFromEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare function createMiniappPlatformCspEnv(env: NodeJS.ProcessEnv, skipPlatformCsp: boolean): {
+    HB_SDK_RUNTIME_PERMISSION_CONTEXT: string;
+    HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN: string;
+    TZ?: string | undefined;
+};
+export declare function withMiniappPlatformCspEnv<T>(skipPlatformCsp: boolean, action: () => Promise<T>, env?: NodeJS.ProcessEnv): Promise<T>;