@heybox/hb-sdk 0.6.5 → 0.6.6-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.5",
+  "version": "0.6.6-alpha.1",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -51,7 +51,8 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "parse5": "^7.3.0"
+    "parse5": "^7.3.0",
+    "undici": "^7.28.0"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -92,7 +93,7 @@
     "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.3"
+    "@heybox/hb-api": "~1.25.5"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/SKILL.md

@@ -80,7 +80,9 @@ For CLI and local development:
 2. Do not use `hb-sdk login` as a workaround for mini-program user authentication.
 3. Use the built-in local debugging page instead of creating another browser Mock.
 4. Keep the Vite `miniappManifest()` plugin enabled.
-5. Treat browser Mock settings as local-only; they must not be presented as online permissions.
+5. Treat Dev Context permission changes as persistent local overrides, not online configuration changes. `hb-sdk` scopes them by real project path and `miniProgramId`, restores them after page refresh or `hb-sdk dev` restart, and clears them only after an explicit reset successfully refetches remote permissions. A regenerated Mobile App QR code may carry only a `dev_context_url` backed by a 256-bit token that expires after 5 minutes; it must not embed a permission snapshot.
+6. Require the Runtime Host to fetch the immutable Dev Session snapshot before startup. Dev Session `network.request` must use the token-bound local proxy, never a native credential adapter, and must force `useOfficialDomain: false`.
+7. Do not treat the legacy `dev_network_request` query as authorization or as a fallback. This Web-only flow must preserve existing Android/iOS URL pass-through behavior without requiring client changes.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.5`
+- Version at generation time: `0.6.6-alpha.1`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -452,7 +452,11 @@ npm run dev
 
 调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。需要定位降级原因时可使用 `hb-sdk dev --verbose`；详细错误只写入本地调试日志，其中 URL 用户名、密码和敏感 query/hash 会被遮蔽，不会进入 LAN bootstrap。
 
-Mock Host 可以在内存中切换 devtools-only 的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR；官方域名权限只读取线上快照，本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+Mock Host 可以切换开发会话的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR。权限覆盖会持久化到 `hb-sdk` 的用户级本地缓存，并按项目真实路径与启动时绑定的 `miniProgramId` 隔离；即使远端权限暂时读取失败，也会继续使用已知绑定 scope。刷新调试页或重启 `hb-sdk dev` 后仍会恢复，直到点击“恢复初始权限”。未绑定项目使用独立匿名 scope，之后绑定小程序时不会继承匿名覆盖。调试页会分别展示远端基线与本地覆盖；多个调试页或进程写入同一 scope 时以最后成功写入的完整配置为准，不提供冲突合并。缓存写入失败时当前页面仍立即生效，同时明确提示刷新或重启后会丢失。已绑定项目重置时会先重新读取远端权限，读取失败则保留当前覆盖并显示错误；匿名项目直接清除本地覆盖。
+
+切换或恢复权限时，Mobile App 二维码会同步重生成，重新扫码后的局域网页面使用同一开发权限。二维码不会携带权限内容，只携带指向本机 Mock Host 的 `dev_context_url`；该 URL 使用 256-bit 随机 token，5 分钟后失效，调试页会在会话到期时自动生成新二维码。Runtime Host 会在创建小程序 Runtime 前拉取 token 对应的不可变权限快照，并校验开发页面 origin、会话期限和快照结构。
+
+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；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 
@@ -745,6 +749,8 @@ await network.request({
 
 `network.request` 由平台 Runtime 权限控制。未授权时 SDK 会收到 `PERMISSION_DENIED` 和“当前小程序暂不支持网络请求”；即使已开启网络请求，访问黑盒官方域名仍需要运营侧单独开启官方域名配置。业务代码不能自行请求或注入 Cookie、pkey 等官方凭据。
 
+权限开启后，`network.request` 可以访问任意 HTTP(S) 目标，包括本机、局域网和保留地址。Runtime 不按目标地址类别拦截请求；宿主网络适配器仍负责实际连接、重定向和系统网络错误。
+
 ## 生命周期事件
 
 导入 SDK 根包时会 eager 创建唯一默认实例并立即开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时不会创建第二个实例；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。

package/skill/references/cli.md

@@ -111,7 +111,9 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 - SDK 初始化、用户状态与登录流程
 - 生命周期、Storage 和排行榜等能力
 
-Mock 中临时调整的权限只影响本地调试，不会修改线上配置。工坊小程序默认不能进行网络请求，网络权限暂未开放申请；不要把 Mock 中的结果当成线上能力。
+Dev Context 中调整的 `network.request` 权限不会修改线上配置，但会持久化到 `hb-sdk` 用户级本地缓存，并按项目真实路径与启动时绑定的 `miniProgramId` 隔离；远端权限暂时读取失败时仍会使用已知绑定 scope。刷新调试页或重启 `hb-sdk dev` 后覆盖仍然生效，直到点击“恢复初始权限”；未绑定项目使用独立匿名 scope，之后绑定小程序时不会继承匿名覆盖。调试页会分别展示远端基线与本地覆盖，多页面或多进程写入同一 scope 时以最后成功写入的完整配置为准，不提供冲突合并。缓存写入失败时当前页面仍立即生效，并提示刷新或重启后会丢失。已绑定项目重置时会先重新读取远端权限，读取失败则保留当前覆盖；匿名项目直接清除本地覆盖。
+
+切换权限后 Mobile App 二维码会自动重生成；二维码只携带使用 256-bit 随机 token 的 `dev_context_url`，并在 5 分钟后失效，调试页会在会话到期时自动生成新二维码。重新扫码后，Runtime Host 会拉取对应的不可变权限快照，再启动手机局域网预览。工坊小程序默认不能进行网络请求，网络权限暂未开放申请；不要把本地调试结果当成线上能力。
 
 ### 3. 再用 Mac 或手机真机验收
 
@@ -124,7 +126,7 @@ Mock 中临时调整的权限只影响本地调试，不会修改线上配置。
 
 ### 浏览器 Mock 的边界
 
-浏览器 Mock 用于提高开发效率，不代表真实客户端环境。权限切换和用户状态只保存在本地；真实权限、客户端兼容性和最终交互以 Mac 或手机小黑盒 APP 为准。
+浏览器 Mock 用于提高开发效率，不代表正式线上环境。Dev Session 的网络请求只对绑定 token 的本机或局域网开发页面生效，通过本地代理转发，不使用黑盒原生凭据 adapter；`useOfficialDomain` 始终为 `false`。代理允许访问本机、局域网和保留地址，并对初始 URL 与每次重定向分别解析和固定连接地址。旧 `dev_network_request` query 不再授权，权限只能来自有效的不可变 Dev Session 快照。该方案不要求修改 Android/iOS 客户端；用户状态仍只保存在浏览器 Mock，线上权限、客户端兼容性和最终交互仍需按真实发布配置验收。
 
 ### 常用参数
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.5+skill.648cee8ae511",
+  "skillVersion": "0.6.6-alpha.1+skill.2799351c9553",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.5",
-    "compatibility": "0.6.5"
+    "version": "0.6.6-alpha.1",
+    "compatibility": "0.6.6-alpha.1"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-648cee8ae5111e01f8e69264187b9501c9167eca7c53693079e2a487ef230106"
+  "integrity": "sha256-2799351c9553f32af834bd0a53e6d016d647aafb275dff139ddd0dfaf2261321"
 }

package/types/protocol/dev-session.d.ts

@@ -0,0 +1,25 @@
+import type { MiniProgramRuntimePermissionsSnapshot } from './runtime-permissions';
+/** Dev Shell 读取局域网 Dev Session endpoint 的 query 参数。 */
+export declare const MINI_PROGRAM_DEV_CONTEXT_QUERY_PARAM = "dev_context_url";
+/** Mock Host 创建和读取 Dev Session 的固定路径。 */
+export declare const MINI_PROGRAM_DEV_CONTEXT_PATH = "/__hb_sdk__/dev-context";
+/** Dev Session 当前使用的 schema 版本。 */
+export declare const MINI_PROGRAM_DEV_SESSION_SCHEMA_VERSION: 1;
+/** Mock Host 创建 Dev Session 时接收的请求。 */
+export interface MiniProgramDevSessionCreatePayload {
+    mini_url_origin: string;
+    runtime_permissions: MiniProgramRuntimePermissionsSnapshot;
+}
+/** Mock Host 创建 Dev Session 后返回的短期引用。 */
+export interface MiniProgramDevSessionCreateResult {
+    expires_at: number;
+    token: string;
+}
+/** Runtime Host 通过短期引用读取的不可变 Dev Session 快照。 */
+export interface MiniProgramDevSessionSnapshot {
+    schema_version: typeof MINI_PROGRAM_DEV_SESSION_SCHEMA_VERSION;
+    revision: number;
+    expires_at: number;
+    mini_url_origin: string;
+    runtime_permissions: MiniProgramRuntimePermissionsSnapshot;
+}