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

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,59 @@ 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 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:
 
 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 +99,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-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.4`
+- 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`：