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

package/dist/protocol.cjs.js

@@ -32,6 +32,58 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -364,4 +416,6 @@ exports.USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD = USER_GET_PLATFORM_ACCOUNT_OV
 exports.USER_GET_STEAM_GAME_LIST_METHOD = USER_GET_STEAM_GAME_LIST_METHOD;
 exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
 exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
+exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
+exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;

package/dist/protocol.esm.js

@@ -30,6 +30,58 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -327,4 +379,4 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     },
 ];
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isMiniProgramBridgeMessage };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, parseMiniProgramRuntimePermissions };

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -1,6 +1,6 @@
 # <%= projectName %>
 
-这是通过 `hb-sdk create` 生成的黑盒外部小程序开发模板。项目使用 Vue 3、Vite、TypeScript 和 `@heybox/hb-sdk`。
+这是通过 `hb-sdk create` 生成的小黑盒工坊小程序模板。项目使用 Vue 3、Vite、TypeScript 和 `@heybox/hb-sdk`。
 
 ## 使用命令
 
@@ -19,9 +19,9 @@ npm run deploy
 
 ## 开发模式
 
-- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
+- `npm run dev`：打开本地调试页，可以使用浏览器 Mock，也可以在 Mac 版 APP 或手机小黑盒 APP 中验收。手机和电脑需要处于同一局域网。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
-- `npm run deploy -- --release-note "..."`：运行 `hb-sdk remote deploy`，构建、上传并提交当前小程序版本审核。部署前需要先执行过 `npx hb-sdk login`；多主体账号还应通过 `npx hb-sdk remote entity current` 确认服务端 current entity。远端小程序可通过 `npx hb-sdk remote create` 在 current entity 下创建并绑定，或用 `npx hb-sdk remote bind <mini-program-id>` 绑定 current entity 可管理的已有小程序。小程序名称、icon 和介绍图在开放平台版本发布中维护；CLI 项目配置只保留 `heybox.miniProgramId`，首次部署服务端会使用默认名与默认图。`selectedEntity` 只是 CLI 登录缓存中的提示快照，实际 deploy/create/bind 以服务端 current entity 为准。默认审核通过后用 `hb-sdk remote versions` 查看状态，再用 `hb-sdk remote release <version>` 发布，如需审核通过后自动发布可追加 `--auto-publish`。顶层 `hb-sdk deploy` 已删除，不再作为兼容别名保留。
+- `npm run deploy -- --release-note "..."`：检查、构建、上传并提交审核。首次提交前先运行 `npx hb-sdk login`，再用 `npx hb-sdk remote create` 创建小程序，或用 `npx hb-sdk remote bind <mini-program-id>` 绑定已有小程序。审核通过后，用 `hb-sdk remote release <version>` 发布。
 
 ## 更多能力
 
@@ -40,10 +40,6 @@ await hbSDK.storage.setStorage({
   data: { theme: 'dark' },
 });
 
-const response = await hbSDK.network.request({
-  method: 'GET',
-  url: 'https://jsonplaceholder.typicode.com/todos/1',
-});
 ```
 
-工坊小程序通常不要传 `url`；宿主 runtime 会自动生成当前小程序的通用分享页。只有确实要分享外部 HTTP(S) 页面时才显式传 `url`。
+工坊小程序默认不能进行网络请求，网络权限暂未开放申请。

package/dist/vite.cjs.js

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

package/dist/vite.esm.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.4-alpha.0';
+    : '0.6.5';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.4-alpha.0",
+  "version": "0.6.5",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hb-sdk
-description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, host/runtime protocol integration, and mini-program listing/audit/compliance review. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
+description: Uses @heybox/hb-sdk and its hb-sdk CLI to build, debug, review, and publish workshop mini-programs for the Heybox App. Use for public SDK APIs, lifecycle events, hb-sdk create/dev/login/doctor, browser Mock and device debugging, or publishing checks. Don't use for private credentials, internal Heybox client protocols, private package paths, or non-Heybox SDKs.
 ---
 
 # hb-sdk Agent Procedure
@@ -9,19 +9,19 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 
 ## Step 1: Classify the task
 
-1. If the task is iframe mini-program business code, use the root package import path `@heybox/hb-sdk`.
+1. If the task is workshop mini-program business code, use the root package import path `@heybox/hb-sdk`.
 2. If the task is parent-container runtime, bridge-server, protocol contract, or `@heybox/hb-sdk-runtime` work, use `@heybox/hb-sdk/protocol` only for shared constants and types.
-3. If the task is project scaffolding, local Vite startup, browser mock runtime, CLI login cache, Agent Skill version diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
+3. If the task is project scaffolding, local startup, browser Mock, device debugging, CLI login, Agent Skill diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
 4. If the task is reviewing a mini-program for submission, listing, audit, publishing, content compliance, data/privacy compliance, runtime quality, or icon/cover design requirements, use the online publishing rules workflow.
 5. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
-6. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, protocol contracts, or mini-program listing/audit/compliance review, do not apply this skill.
+6. If the task is not about Heybox workshop mini-program SDK usage, CLI usage, protocol contracts, or listing/audit/compliance review, do not apply this skill.
 
 ## Step 2: Load only the needed reference
 
 1. For root SDK imports, singleton usage, modules, and errors, read `references/api-root.md`.
-2. For host/runtime protocol contracts only, read `references/api-protocol.md`. Do not use this reference to build iframe business-code bridge messages.
+2. For host/runtime protocol contracts only, read `references/api-protocol.md`. Do not use this reference for mini-program business code.
 3. For common business flows, read `references/recipes.md`.
-4. For CLI commands, local mock runtime, generated templates, CLI login cache, Agent Skill doctor, and update reminders, read `references/cli.md`.
+4. For CLI commands, local debugging, device debugging, CLI login, Agent Skill doctor, and update reminders, read `references/cli.md`.
 5. For allowed/forbidden capabilities and security boundaries, read `references/safety-boundaries.md`.
 6. For Vite build manifest behavior, read `references/api-root.md` and `references/safety-boundaries.md`.
 7. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
@@ -36,71 +36,57 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 3. Never import from internal hb-sdk implementation paths; only use the documented package entrypoints.
 4. Prefer named imports for focused code and the default `hbSDK` singleton for compact page-level examples.
 
-## Step 4: Implement iframe mini-program code
+## Step 4: Implement workshop mini-program code
 
 1. Call `await ready()` or `await hbSDK.ready()` near page startup when the page uses SDK capabilities.
 2. Use `user.getInfo()` to read current login state without triggering login.
 3. Use `auth.login()` only when the user action requires login.
-4. Handle `HbMiniProgramSDKError` for bridge/runtime/protocol failures.
+4. Handle `HbMiniProgramSDKError` for SDK initialization and capability failures.
 5. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
 6. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
-7. Import the root package eagerly; version 0.6 exposes only the unique default SDK instance and starts its handshake as a required import side effect.
+7. Use the default SDK instance exposed by the root package.
 
 ## Step 5: Use CLI workflows
 
-1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
-2. Use `hb-sdk dev` for local browser, Mac App, or mobile App debugging through the built-in mock runtime host. Vite and native dev-shell entrypoints only require the local `mini_url`: a missing project binding, CLI login, remote dev-context failure, or the 3-second context timeout must fall back to an anonymous local sandbox instead of blocking startup. Anonymous mode denies managed capabilities by default. When a verified remote dev context is available, the Mock Host uses its Runtime permission snapshot as the initial local simulation and reports local-versus-online permission differences.
-3. Use `hb-sdk remote ...` for developer-owned remote mini-program management. Top-level `hb-sdk deploy` has been hard-cut and must not be recommended as a compatibility alias.
-4. Use `hb-sdk remote entity list`, `hb-sdk remote entity current`, and `hb-sdk remote entity switch <entity-id>` to inspect or change the developer platform server-side current entity before remote management commands.
-5. Use `hb-sdk remote create` to create a remote mini-program under the server-side current entity and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after current-entity manageability is verified. CLI project configuration contains only `package.json.heybox.miniProgramId`; mini-program name, icon, and cover images are maintained on the Open platform version-publish flow. On first submit without prior approved profile, the server injects a default name and default images.
-6. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Mini-program name and image changes must go through version audit, so the CLI must not expose a basic-info update command.
-7. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, validates that the bound mini-program belongs to the server-side current entity before precheck/build/upload, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API. Deploy and `--from-version` do not fetch or compare the client-side `minimumSdkVersion`; Manifest validation and server-side precheck / submit-audit policy still apply. When `--env <name>` or `HB_SDK_ENV=<name>` selects an environment preset, deploy also passes the same name to the project build as its Vite mode. The deploy upload pipeline rejects actual upload artifacts over 100MiB before any upload request, processes CDN upload metadata and callback confirmation at 50 files per batch, keeps 4-way upload concurrency within each batch, and validates CDN-returned keys exactly against the local expected upload keys.
-8. Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a previously uploaded remote version artifact and submit a new audit version without reading local `dist`, building, or uploading.
-9. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
-10. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
-11. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
-12. For development routing or gray validation, use `HB_SDK_SERVICE_TAG` to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to CLI backend requests. Repository-local path-specific routing can still be configured in `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`).
-13. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
-14. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
-15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
-16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; these entrypoints remain available in anonymous mode. The phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
-18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
-19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
-20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
-21. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-22. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-23. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-24. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
-25. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
-26. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
-27. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
+1. Use `hb-sdk create <project-name>` to scaffold a workshop mini-program.
+2. Use `hb-sdk dev` for browser, Mac App, or mobile App debugging. These entries remain available without CLI login or project binding, but managed capabilities are denied by default.
+3. Use `--port`, `--mock-port`, and `--no-open` when the default local ports or browser opening behavior need to be controlled.
+4. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for development and publishing commands. This login does not change the mini-program user's login state.
+5. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
+6. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
+7. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
+8. Use `hb-sdk remote deploy --release-note <text>` to check, build, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
+9. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
+10. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
+11. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
+12. Use `--json` for script consumption and `--verbose` only when concise output is insufficient for diagnosis.
+13. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
+14. Do not print or expose cookies, tokens, private headers, or other credentials.
 
 ## Step 6: Preserve capability boundaries
 
-For iframe mini-program business code:
+For workshop mini-program business code:
 
 1. Do not read or request tokens, cookies, phone numbers, or private credentials from the SDK.
 2. Do not expose raw share protocol fields, JS callbacks, activity reporting, custom buttons, post publishing, or upload-only flows.
 3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
-4. Do not pass raw host protocol fields through `network.request`; use only the public axios-like request config.
-5. Do not construct bridge envelopes, nonce logic, or raw `postMessage` calls.
+4. Use only the public `network.request` configuration.
+5. Do not use private package paths or client protocols.
 6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
 
 For CLI and local development:
 
 1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
-2. Do not use `hb-sdk login` as a workaround for iframe SDK authentication.
-3. Do not bypass `hb-sdk dev` by adding a second browser mock host.
-4. Keep the Vite `miniappManifest()` plugin enabled so builds only start in a compatible APP Runtime. Normal deploy always runs the project build.
-5. Keep Mock Host permission overrides in devtools-only memory. They must not rebuild the iframe, interrupt Vite HMR, mutate online permissions, or be passed through URL query parameters.
-6. Treat remote dev context as optional diagnostics and initialization data. Do not use a public mini-program detail request as a dev startup gate.
+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.
 
 For host/runtime/protocol-maintenance code:
 
 1. Use `@heybox/hb-sdk/protocol` for shared constants and type contracts.
-2. Keep raw protocol details inside the host/runtime boundary; do not leak them into app-facing SDK examples or iframe business code.
-3. Keep bridge handshake and nonce behavior idempotent and compatible with existing SDK clients.
+2. Keep raw protocol details inside the host/runtime boundary; do not leak them into app-facing SDK examples or workshop mini-program business code.
+3. Preserve compatibility with existing SDK clients.
 
 ## Step 7: Validate changes
 
@@ -111,7 +97,7 @@ For host/runtime/protocol-maintenance code:
 3. When preparing a package release, run `pnpm --filter @heybox/hb-sdk run release:prepare -- --bump patch` or `pnpm --filter @heybox/hb-sdk run release:prepare -- --version <x.y.z>`. The release assistant updates both package versions, inserts `packages/hb-sdk/CHANGELOG.md`, and runs `check:changelog`. Use `--ai-command "<command>"` or `HB_SDK_CHANGELOG_AI_COMMAND` when an AI writer should rewrite the Conventional Commit draft. Review the entry for Mini-program developers and Host/Runtime integration maintainers, and do not expose Runtime internal adapter, state-machine, or security-policy details.
 4. When modifying this repo's source skill at `packages/hb-sdk/skill` and preparing distributable artifacts, also run:
    - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
-5. When modifying CLI, mock runtime, package exports, or package dependency direction, also run:
+5. When modifying CLI, local debugging, package exports, or package dependency direction, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
 6. Inspect the generated zip before distribution:

package/skill/references/api-protocol.md

@@ -31,6 +31,13 @@ export {
   SDK_LOCATION_REPORT_METHOD,
 } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
+export { isManagedMiniProgramRuntimePermissionKey, parseMiniProgramRuntimePermissions } from './protocol/runtime-permissions';
+export type {
+  MiniProgramRuntimePermissionEntry,
+  MiniProgramRuntimePermissionStatus,
+  MiniProgramRuntimePermissionsSnapshot,
+  ParsedMiniProgramRuntimePermissions,
+} from './protocol/runtime-permissions';
 export type {
   MiniProgramBridgeError,
   MiniProgramBridgeMessage,
@@ -139,11 +146,7 @@ export type {
   MiniProgramShareChannel,
   MiniProgramShowShareMenuOptions,
 } from './modules/share';
-export type {
-  GetStoragePayload,
-  GetStorageResult,
-  SetStoragePayload,
-} from './modules/storage';
+export type { GetStoragePayload, GetStorageResult, SetStoragePayload } from './modules/storage';
 export type {
   GetWindowInfoPayload,
   GetWindowInfoResult,
@@ -173,13 +176,7 @@ export type {
   ShowToastPayload,
   ShowToastResult,
 } from './modules/ui';
-export type {
-  MiniProgramVibrateIntensity,
-  SetClipboardPayload,
-  SetClipboardResult,
-  VibratePayload,
-  VibrateResult,
-} from './modules/device';
+export type { MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult } from './modules/device';
 export type {
   ClosePayload,
   CloseResult,
@@ -210,18 +207,22 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | 说明 |
 | --- | --- |
-| [Root API](api-root.md) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
-| [Protocol API](#public-protocol-entrypoint) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
+| [Root API](api-root.md) | `@heybox/hb-sdk` 的默认导出、命名导出与公开能力。 |
+| [Protocol API](#public-protocol-entrypoint) | `@heybox/hb-sdk/protocol` 的协议常量、消息类型与 method 契约。 |
+| [Miniapp Publish API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/) | `@heybox/hb-sdk/miniapp-publish` 的构建产物发布前的公开校验工具。 |
+| [Vite API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/) | `@heybox/hb-sdk/vite` 的Vite 工坊小程序插件。 |
 
 ## 查询建议
 
 - 想查业务接入路径：先看 [Guide](recipes.md)。
-- 想查导出符号：从 Root API 或 Protocol API 进入对应分类页。
+- 想查导出符号：从上方对应公开入口进入分类页。
 - 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
 
 ## 统计
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 3 | 66 | 57 | 4 |
-| Protocol API | 0 | 1 | 43 | 68 | 35 |
+| Root API | 2 | 3 | 66 | 57 | 0 |
+| Protocol API | 0 | 3 | 43 | 67 | 32 |
+| Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
+| Vite API | 0 | 1 | 0 | 0 | 0 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.4-alpha.0`
+- Version at generation time: `0.6.5`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -450,9 +450,9 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。
+调试页会通过 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 权限模拟，不会重建 iframe，因此不影响 Vite HMR；本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+Mock Host 可以在内存中切换 devtools-only 的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR；官方域名权限只读取线上快照，本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：