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

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.0`
 - 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`：
 

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`。旧 `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.0+skill.cfc5c9fb3951",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.5",
-    "compatibility": "0.6.5"
+    "version": "0.6.6-alpha.0",
+    "compatibility": "0.6.6-alpha.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-648cee8ae5111e01f8e69264187b9501c9167eca7c53693079e2a487ef230106"
+  "integrity": "sha256-cfc5c9fb39515fb1aa10fa2fc4db030d31ff0034b389062e009c0d6f2195e9e4"
 }

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;
+}