@heybox/hb-sdk 0.6.4 → 0.6.5

package/skill/references/cli.md

@@ -9,38 +9,32 @@
 - packages/hb-sdk/src/cli/commands/create.ts
 - packages/hb-sdk/src/cli/commands/dev.ts
 - packages/hb-sdk/src/cli/commands/login.ts
-- packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs
 - apps/docs/hb-sdk/guide/cli.md
-- packages/hb-sdk/README.md
 
 ## Contents
 
 - [When to use the CLI](#when-to-use-the-cli)
 - [Command surface](#command-surface)
 - [Create a mini-program template](#create-a-mini-program-template)
-- [Local dev and mock runtime](#local-dev-and-mock-runtime)
-- [Deploy and backend operations](#deploy-and-backend-operations)
-- [Remote entity scope](#remote-entity-scope)
+- [Local debugging](#local-debugging)
+- [Deploy and publish](#deploy-and-publish)
+- [Developer account scope](#developer-account-scope)
 - [Remote management commands](#remote-management-commands)
-- [CLI login cache](#cli-login-cache)
+- [CLI login](#cli-login)
 - [Agent Skill doctor](#agent-skill-doctor)
 - [Update reminders](#update-reminders)
-- [Repository validation commands](#repository-validation-commands)
-- [Generated template README](#generated-template-readme)
 ## When to use the CLI
 
-Use the bundled `hb-sdk` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, managing the CLI's own Heybox auth cache, or inspecting/switching the developer platform current entity for remote mini-program management.
+Use the bundled `hb-sdk` CLI to create a workshop mini-program, open the local debugging page, test in the Heybox Mac or mobile App, or manage and publish a remote mini-program.
 
-Do not use the CLI to replace iframe SDK calls. `hb-sdk login` is for CLI commands only and does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-host user state.
-
-The CLI, templates, and mock host are owned by `@heybox/hb-sdk`. Do not create a second mock runtime package or move CLI guidance outside this package unless the package boundary changes.
+`hb-sdk login` is for development and publishing commands only. It does not change `auth.login()`, `user.getInfo()`, or `network.request()` inside a mini-program.
 
 ## Command surface
 
 ```text
 hb-sdk create <project-name>
-hb-sdk dev [--port <port>] [--mock-port <port>] [--runtime-url <url>] [--no-open]
-hb-sdk login [--login-base-url <url>] [--no-select-entity]
+hb-sdk dev [--port <port>] [--mock-port <port>] [--no-open]
+hb-sdk login
 hb-sdk login status
 hb-sdk login clear
 hb-sdk doctor
@@ -73,134 +67,111 @@ Top-level `hb-sdk deploy` has been hard-cut and must not be documented as a vali
 
 ## Create a mini-program template
 
-## 创建外部小程序模板
+## 创建工坊小程序
+
+新项目可以直接从模板开始：
 
 ```bash
-npx @heybox/hb-sdk create my-miniapp
+npx @heybox/hb-sdk@latest create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
 ```
 
-`hb-sdk create <target-path>` 会生成 Vue 3、Vite、TypeScript 和 npm 模板。参数可以是目录名、相对/绝对路径或 `.`；生成的 `package.json.name` 取解析后目标目录的 basename，并校验为合法的非 scoped npm 包名。目标目录不存在时会创建；目标目录已存在但非空时会拒绝覆盖。模板使用 Vite 8，需要 Node.js `^20.19.0` 或 `>=22.12.0`。
-
-CLI 只生成文件，不会自动安装依赖、初始化 git 或打开编辑器。生成模板后优先运行 `npm run dev`，它会启动 Vite 服务和内置 mock runtime host。
+已有项目则在项目目录运行 `npm run dev` 或 `hb-sdk dev`。
 
 Agent rules:
 
-- Prefer `hb-sdk create <project-name>` for a new standalone external mini-program template.
+- Prefer `hb-sdk create <project-name>` for a new workshop mini-program.
 - After creation, the expected next steps are `npm install` and `npm run dev`.
 - Do not claim the CLI installs dependencies, initializes git, opens an editor, or overwrites non-empty directories.
 - Treat `project-name` as an unscoped npm package name and project directory.
 
-## Local dev and mock runtime
+## Local debugging
 
-## 本地开发模式
+## 推荐调试流程
 
-已有小程序项目中可以直接运行：
+### 1. 启动调试页
 
 ```bash
 hb-sdk dev
 ```
 
-`hb-sdk dev` 会从当前目录向上查找最近的 `package.json`。Vite、内置 mock runtime host、Mac 启动协议和手机二维码的基础启动只依赖本地页面地址，不要求项目先绑定或 CLI 先登录。项目已绑定时，CLI 会限时 3 秒读取远端 dev context；成功后用真实 Runtime 权限快照初始化 Mock Host，失败或超时则输出脱敏警告并继续匿名调试，`network.request` 等受管能力默认拒绝。需要定位降级原因时可使用 `hb-sdk dev --verbose`；详细错误只写入本地调试日志，其中 URL 用户名、密码和敏感 query/hash 会被遮蔽，不会进入 LAN bootstrap。公开 `detail` 查询不再是 dev 启动门禁。本地 `package.json` 无法解析等配置错误不会被降级，命令会直接报错。调试页默认自动打开；需要真实黑盒小程序容器加载同一页面时，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。
+CLI 会启动页面服务并自动打开本地调试页。调试页会展示小程序、浏览器 Mock、Mac 启动入口和手机二维码。
 
-常用参数：
+<img src="https://static.max-c.com/static/heybox/webapp/heybox-docs/docs-hb_sdk/assets/local-preview-debug-page.png" alt="hb-sdk 本地调试页、浏览器 Mock 和真机调试入口" style="width: 100%; max-width: 860px;" />
 
-| 参数                  | 说明                                                                                                       |
-| --------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `--port <port>`       | 指定小程序 Vite dev server 端口，默认从 `5173` 开始。                                                      |
-| `--mock-port <port>`  | 指定 mock host 端口，默认从 `5174` 开始。                                                                  |
-| `--runtime-url <url>` | 真实客户端调试时传给 dev shell 的自定义 runtime 地址；手机扫码时 loopback host 会自动改写为所选局域网 IP。 |
-| `--no-open`           | 不自动打开浏览器调试页。                                                                                   |
+未登录或未绑定小程序时，浏览器、Mac 和手机调试入口仍然可用，但受管能力会默认拒绝。登录并绑定后，调试页才能根据当前小程序的线上配置提示差异。
 
-## Mock runtime 边界
+### 2. 先用浏览器 Mock 验收
 
-`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。Mac 协议和手机二维码始终携带本地页面地址；远端 dev context 可用时还会携带已验证的小程序 ID，不可用时则进入匿名本地沙箱。真机 dev shell 不依赖公开 `detail` 查询完成启动。真实 Mac / Mobile App dev shell 加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+浏览器 Mock 支持热更新，适合快速检查：
 
-不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
+- 页面布局和主要交互
+- SDK 初始化、用户状态与登录流程
+- 生命周期、Storage 和排行榜等能力
 
-浏览器 Mock 的权限状态只存在于 Mock Host 内存中，URL query 不能提供或覆盖权限。远端 dev context 可用时，Mock Host 以线上快照作为初始值；不可用时匿名状态默认拒绝受管能力。开发者可以在调试页临时切换 `network.request` 权限；官方域名权限只读取线上快照，不能在 devtools 中手动调整。变更只会重建 devtools-only mock runtime，不会重建 iframe 或中断 Vite HMR，也不会修改线上配置。调试页会对比线上快照并提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。
+Mock 中临时调整的权限只影响本地调试，不会修改线上配置。工坊小程序默认不能进行网络请求，网络权限暂未开放申请；不要把 Mock 中的结果当成线上能力。
 
-本地 mock runtime 下已授权的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。CLI 登录态和远端 dev context 也不会注入 iframe。
+### 3. 再用 Mac 或手机真机验收
 
-Use `hb-sdk dev` for local browser SDK debugging. 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. The phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
+需要确认真实客户端表现时，从调试页选择一种方式：
 
-## Deploy and backend operations
+- 点击「在 Mac 版 APP 中启动」。
+- 在「Mobile App」区域选择局域网网卡，再用手机小黑盒 APP 扫码。
 
-## 部署发布
+手机与电脑需要处于同一局域网。二维码无法访问时，先确认选择了正确的 **Network** 网卡。发布前至少完成一次真实客户端验收。
 
-```bash
-hb-sdk remote deploy --release-note "修复登录状态展示，补充异常提示"
-hb-sdk remote deploy --release-note "审核通过后自动发布" --auto-publish
-hb-sdk remote deploy --from-version 1.2.3 --release-note "复用 1.2.3 历史产物"
-```
+### 浏览器 Mock 的边界
 
-`hb-sdk remote deploy` 把预检、构建、上传和提交审核串成一条命令。顶层 `hb-sdk deploy` 已硬切删除，不再作为兼容别名保留：
-
-1. 读取 `package.json.heybox.miniProgramId`，缺失即报错。
-2. 校验登录态，需先 `hb-sdk login`。
-3. 运行 `hb-sdk remote access` 确认当前主体具备开发者资格；未开通时按开放平台的小程序工坊申请入口提交申请。
-4. 读取并校验 `--release-note`；TTY 环境缺失时会提示输入，CI / 非 TTY 环境缺失时直接失败。建议让 AI 生成 1-5 条简短发布日志。
-5. 普通 remote deploy 先读取 `package.json.version`，登录后、build 前调用版本预检接口；预检通过后才执行 `<pm> run build`。
-6. `--from-version <version>` 跳过本地构建、`dist/` 读取和上传，复用指定历史版本产物提交审核。
-7. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
-8. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
-9. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
-10. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
-11. CLI 会分批上传构建产物并校验平台返回的文件集合；任何批次异常都会停止后续上传且不会提交审核。
-12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会补充逐文件诊断，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
-13. 全部上传成功后调用提交审核接口；`--from-version` 路径会直接提交 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL。
-
-`mini_program_id` 没有 CLI flag，必须落在 `package.json` 里：
-
-```json
-{
-  "heybox": {
-    "miniProgramId": "mp_xxxxxxxx"
-  }
-}
-```
+浏览器 Mock 用于提高开发效率，不代表真实客户端环境。权限切换和用户状态只保存在本地；真实权限、客户端兼容性和最终交互以 Mac 或手机小黑盒 APP 为准。
+
+### 常用参数
 
-`manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。小程序构建产物需要使用相对资源路径；`hb-sdk create` 模板会显式配置 `base: './'`，未配置 `base` 的项目也会由 `miniappManifest()` 在 build 时默认补成 `./`。构建产物只能在兼容的小黑盒 Runtime 中启动，普通浏览器直接打开时不会执行标准业务脚本。
+| 参数                  | 用途                             |
+| --------------------- | -------------------------------- |
+| `--port <port>`       | 指定页面开发服务端口。           |
+| `--mock-port <port>`  | 指定本地调试端口。           |
+| `--no-open`           | 启动后不自动打开浏览器。         |
+| `--verbose`           | 出现问题时输出更详细的诊断信息。 |
 
-CLI 的 `dev` 启动、本地 Vite build、`remote deploy` 本地构建和 `--from-version` 路径都不主动查询或比较 `minimumSdkVersion`；Mac / Mobile dev shell 仍会在加载 iframe 前执行宿主侧兼容性与平台配置检查。Manifest 结构校验、版本 precheck 和服务端 submit-audit 策略仍然生效。
+Use `hb-sdk dev` to open the local debugging page. The "在 Mac 版 APP 中启动" button opens the page in the Mac App; the "Mobile App" QR code opens it in the phone App after a LAN interface is selected. These entries remain available without CLI login or project binding, but managed capabilities are denied by default. The phone and computer must be on the same LAN. If an embedded browser cannot open the App, use the system browser.
 
-默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。`--auto-publish` 只适用于普通低风险版本；重大功能、活动联动、商业化、用户数据、外部账号绑定或风控策略变更应保持手动发布。需要指定用户预览未发布候选版本时，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
+## Deploy and publish
+
+## 部署发布
 
-需要给构建选择 Vite mode 时，可以使用 `--env <name>` 或 `HB_SDK_ENV=<name>`。CLI 会从当前目录向上找到项目根，读取 `.env.<name>`，把其中所有合法 key 注入当前进程和后续 build（不覆盖已有值），并将同一个 `name` 作为 `--mode <name>` 传给项目 build。`--env-file <path>` 可以相对调用目录指定其他预设文件，且优先级高于 `--env`。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过，其他读取错误会直接失败。
+浏览器和真机验收通过后，首次提交前需要登录 CLI 并绑定小程序：
 
 ```bash
-# 项目根准备 .env.preview
-#   VITE_API_ORIGIN=https://api.example.com
+hb-sdk login
+hb-sdk remote create
+# 或绑定已有小程序
+hb-sdk remote bind mp_xxxxxxxx
+```
+
+绑定完成后，`package.json` 中会记录 `heybox.miniProgramId`。提交审核使用：
 
-hb-sdk remote deploy --env preview --release-note "预览模式构建"
-HB_SDK_ENV=preview hb-sdk remote deploy --release-note "预览模式构建"
-hb-sdk remote deploy --env-file .env.local --release-note "本地配置构建"
+```bash
+hb-sdk remote deploy --release-note "修复登录状态展示"
 ```
 
-预设不会覆盖进程已有的同名环境变量，因此优先级为进程 env > `.env` 预设 > 默认值。
+这条命令会完成检查、构建、上传和提交审核。默认在审核通过后等待手动发布；普通低风险版本可以追加 `--auto-publish`。完整命令见 `hb-sdk remote --help`，提交要求见[小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)。
 
-Before precheck, build, upload, or submit audit, `hb-sdk remote deploy` must verify that the current project's bound mini-program belongs to the server-side current entity. If `detail.entity_id` differs from the current entity, the command fails with both entity ids/names and suggests `hb-sdk remote entity switch <entity-id>`. It must not auto-switch entities and must not continue into precheck/build/upload/submit on mismatch.
+Before publishing, `hb-sdk remote deploy` verifies that the bound mini-program belongs to the current developer account. If it does not, the command stops and asks the user to switch accounts.
 
 Agent rules:
 
 - Use `hb-sdk remote deploy --release-note <text>` for normal build, upload, and submit-audit flows.
 - Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a remote history artifact.
-- Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
+- If the bound mini-program does not belong to the current developer account, stop and ask the user to switch accounts.
 - Never recommend top-level `hb-sdk deploy`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest `hb-sdk remote versions` and then `hb-sdk remote release <version>` after approval. Do not send the user to Open for manual publish when the CLI command exists.
 - Use `hb-sdk remote allowlist add <heybox_id>` when preview access needs to be granted.
-- Use `--api-base-url <url>` or `HB_SDK_API_BASE_URL` for remote platform backend APIs.
-- Use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging against non-Heybox or non-HTTPS API origins.
-- Use `--login-base-url <url>` or `HB_SDK_LOGIN_BASE_URL` for CLI browser login and remote command login-environment validation.
-- Use `packages/hb-sdk/src/cli/config.ts` with `RylaiServiceTagConfig` only when Heybox backend API requests need the development-only `x-rylai-service-tag` header and matching `special_tag` query parameter.
-- Custom base URLs must be origin-only; API origins must be Heybox trusted HTTPS unless the unsafe debug switch is explicit. Do not include path, query, or hash.
-- Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
 
-## Remote entity scope
+## Developer account scope
 
-Developer entity selection lives under `hb-sdk remote entity`:
+Developer account selection lives under `hb-sdk remote entity`:
 
 ```bash
 hb-sdk remote entity list
@@ -208,55 +179,18 @@ hb-sdk remote entity current
 hb-sdk remote entity switch <entity-id>
 ```
 
-The authoritative current entity is the developer platform server-side current entity. The CLI auth cache may contain a `selectedEntity` value, but that value is only a hint snapshot for `hb-sdk login status` display and drift troubleshooting. Do not use `selectedEntity` as the source of truth for permissions, ownership, create, bind, deploy, or release decisions.
-
-`hb-sdk login` tries to make the server-side current entity explicit after browser login. Zero entities leaves login successful and prints a guidance message. One entity is displayed and, when needed, switched to current. Multiple entities in a TTY prompt for a choice; multiple entities in non-interactive mode do not block login but tell the user to run `hb-sdk remote entity switch <entity-id>`. Passing `--no-select-entity` writes only the login state and does not modify the server-side current entity.
+Remote management commands use the current developer account. Use `current` to confirm it and `switch` to change it before creating, binding, or publishing a mini-program.
 
 Agent rules:
 
-- Treat the server-side current entity as the authority for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, reopen, and square-display workflows.
-- Treat CLI `selectedEntity` as a display/debug snapshot only; it can drift from the server-side current entity and must not be used as a permission source.
+- Treat the current developer account as the scope for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, reopen, and square-display workflows.
 - Use `hb-sdk remote entity current` when a user needs to confirm which entity create/deploy will use.
 - Use `hb-sdk remote entity switch <entity-id>` to change entity scope. Do not recommend `--entity-id` or an environment variable as a remote command override.
 - `hb-sdk remote list` lists mini-programs in the current entity scope only; do not promise cross-entity aggregation.
 
 ## Remote management commands
 
-## 远端管理命令
-
-远端平台操作统一放在 `hb-sdk remote` 命令组下，默认作用于当前项目绑定的小程序，也就是 `package.json.heybox.miniProgramId`。`remote list` 只用于发现可管理的小程序；会改变远端状态的命令仍然只操作当前绑定的小程序，不接受临时 `mini_program_id` 参数。
 
-常用命令：
-
-```bash
-hb-sdk remote access
-hb-sdk remote entity list
-hb-sdk remote entity current
-hb-sdk remote entity switch <entity-id>
-hb-sdk remote list
-hb-sdk remote create
-hb-sdk remote bind mp_xxxxxxxx
-hb-sdk remote info
-hb-sdk remote allowlist add 12345678
-hb-sdk remote versions
-hb-sdk remote preview 1.2.3
-hb-sdk remote release 1.2.3
-hb-sdk remote withdraw 1.2.3 --reason "需要修复说明"
-hb-sdk remote take-down
-hb-sdk remote reopen
-hb-sdk remote square hide
-hb-sdk remote square show
-```
-
-`hb-sdk remote create` 会创建远端工坊小程序并写入当前项目绑定；已有绑定时必须传 `--force-bind` 才能覆盖。`hb-sdk remote bind <mini-program-id>` 会先校验当前 CLI 用户可管理目标小程序，再写入本地配置；`--force` 只允许覆盖本地绑定，不跳过远端校验。
-
-小程序名称、icon 和介绍图在开放平台「版本发布」中维护并随版本审核。CLI 项目配置只保留 `package.json.heybox.miniProgramId`；首次部署且没有历史审核资料时，服务端会使用默认名称「我的小程序」与平台默认图片。
-
-`hb-sdk remote square hide` 会隐藏当前绑定小程序在普通用户侧的小程序工坊广场展示；白名单用户仍可在小程序工坊广场看到，直接链接访问已发布版本也不受影响。`hb-sdk remote square show` 会恢复普通用户侧的小程序工坊广场展示。
-
-`hb-sdk remote release`、`withdraw`、`take-down`、`reopen` 和 `square hide` 会改变审核、发布或用户侧可见状态。交互式终端会展示目标和变更内容后要求确认；非 TTY 环境必须传 `--yes`。`entity switch`、`square show` 和 allowlist 写操作当前不会进行这层 CLI 确认，自动化脚本不要为它们假设存在确认保护。
-
-所有 `hb-sdk remote` 子命令都支持 `--json`。开启后 stdout 只输出一个 JSON 对象；进度、警告、版本提醒和 verbose 诊断不能污染 stdout。`remote deploy --json` 不进行交互式 release note 提示，必须显式传 `--release-note`。
 
 Agent rules:
 
@@ -271,137 +205,32 @@ Agent rules:
 - Require confirmation or `--yes` for `hb-sdk remote release`, `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and `hb-sdk remote square hide`.
 - Use `--json` for script consumption and keep stdout as exactly one JSON object.
 
-## CLI login cache
+## CLI login
 
 ## CLI 登录态
 
+CLI 登录态只用于开发工具和远端管理，不等同于小程序内的用户登录态，也不会改变 `auth.login()` 或 `user.getInfo()` 的结果。
+
 ```bash
-hb-sdk login
 hb-sdk login status
 hb-sdk login clear
 ```
 
-- `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
-- 登录成功后默认还会查询开发者主体；`--no-select-entity` 会跳过登录后的主体选择。
-- `hb-sdk login status` 默认展示脱敏状态、`heyboxId`、`loginBaseUrl` 和登录时间；`--verbose` 额外展示 cache 路径。不输出 `pkey`、cookie 或完整请求头。
-- `hb-sdk login clear` 只清理 `hb-sdk` 自己命名空间中的 Heybox 登录态。
-
-这份 CLI 登录态不会注入 iframe SDK，也不会改变 `hb-sdk dev` 的 mock 用户、`auth.login()`、`user.getInfo()` 或 `network.request()` 行为。
-
 Agent rules:
 
-- Keep CLI auth cache separate from iframe SDK login state.
-- Keep `selectedEntity` guidance explicit: it is only a hint snapshot, while every remote command uses the server-side current entity.
+- Keep CLI login separate from the mini-program user login state.
 - It is correct to say status output is redacted.
 - Do not expose or template pkey, cookie, token, or private credential values.
 - Use `hb-sdk login clear` only to clear the `hb-sdk` CLI namespace.
 
 ## Agent Skill doctor
 
-## Agent Skill doctor
-
-```bash
-hb-sdk doctor
-```
-
-`hb-sdk doctor` 用来诊断本机 `hb-sdk` Agent Skill 是否匹配当前 SDK。它会对比当前 `@heybox/hb-sdk` 版本、远端 latest skill 元数据，以及本机 `$CODEX_HOME/skills/hb-sdk/skill.json`；没有 `CODEX_HOME` 时读取 `~/.codex/skills/hb-sdk/skill.json`。
-
-`doctor` 只诊断，不修改本地文件。需要安装或刷新 skill 时，按输出提示手动执行 `npx skills add`。
-
-| 状态                 | 含义                                                     |
-| -------------------- | -------------------------------------------------------- |
-| `OK`                 | SDK、远端 latest skill、本机 skill 全部匹配。            |
-| `SKILL_MISSING`      | 本机没有安装 `hb-sdk` skill。                            |
-| `SKILL_OUTDATED`     | 本机 `skillVersion` 与远端 latest 不一致。               |
-| `SDK_MISMATCH`       | 当前 SDK 版本与远端 latest skill 声明的 SDK 版本不一致。 |
-| `REMOTE_UNAVAILABLE` | 无法读取公开 manifest，诊断失败且不会修改本地文件。      |
-
-手动安装或刷新 skill：
-
-```bash
-npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk
-```
 
-如果状态是 `SDK_MISMATCH`，先升级 `@heybox/hb-sdk@latest`，再重新运行 `hb-sdk doctor` 并按提示安装 latest skill。当前只维护 latest skill，不维护历史 SDK 的 skill 快照。
 
 Agent rules:
 
 - Use `hb-sdk doctor` for read-only diagnosis of local SDK, remote latest skill metadata, and local skill metadata.
 - 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`.
 - If doctor reports `SDK_MISMATCH`, tell the user to upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-- The supported local skill path is `$CODEX_HOME/skills/hb-sdk/skill.json`, falling back to `~/.codex/skills/hb-sdk/skill.json`.
 
 ## Update reminders
-
-## 版本提醒
-
-`hb-sdk create`、`hb-sdk dev`、`hb-sdk remote ...`、`hb-sdk login`、`hb-sdk login status`、`hb-sdk login clear`、`hb-sdk doctor` 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。普通命令的检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。`hb-sdk doctor` 已经诊断出 `SDK_MISMATCH` 时不会再追加统一提醒，避免同一次输出里重复提示升级 SDK。`hb-sdk --version` / `hb-sdk -V` 会直接请求 npm registry 获取 latest，不读取本地缓存；stdout 只输出版本号，升级提醒继续按 warn 级别写到 stderr。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
-
-## Repository validation commands
-
-## 本仓库开发
-
-```bash
-pnpm --filter @heybox/hb-sdk run test:unit
-pnpm --filter @heybox/hb-sdk run build:package
-pnpm --filter @heybox/hb-sdk run check:boundary
-pnpm exec hbexec hb-sdk check
-```
-
-`check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。
-
-`hbexec hb-sdk check` 只读校验 docs、skill references，并在临时目录生成与校验 `agent-skills` payload；不要求 canonical artifact 已存在，也不包含 changelog。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。
-
-## Generated template README
-
-````md
-# <%= projectName %>
-
-这是通过 `hb-sdk create` 生成的黑盒外部小程序开发模板。项目使用 Vue 3、Vite、TypeScript 和 `@heybox/hb-sdk`。
-
-## 使用命令
-
-```bash
-npm install
-npm run dev
-npm run typecheck
-npm run test:unit
-npm run build
-npm run deploy
-```
-
-## 依赖说明
-
-`@heybox/hb-sdk` 是小程序页面运行时会 import 的 SDK，因此模板把它放在 `dependencies`。Vite、TypeScript、Vitest 等只参与本地开发、测试或构建的工具放在 `devDependencies`。
-
-## 开发模式
-
-- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法唤起系统 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` 已删除，不再作为兼容别名保留。
-
-## 更多能力
-
-模板页面只保留最小接入示例。其他常用能力可以直接从 `@heybox/hb-sdk` 调用：
-
-```ts
-import hbSDK from '@heybox/hb-sdk';
-
-await hbSDK.share.showShareMenu({
-  title: '<%= projectName %>',
-  desc: '分享描述',
-});
-
-await hbSDK.storage.setStorage({
-  key: 'settings',
-  data: { theme: 'dark' },
-});
-
-const response = await hbSDK.network.request({
-  method: 'GET',
-  url: 'https://jsonplaceholder.typicode.com/todos/1',
-});
-```
-
-工坊小程序通常不要传 `url`；宿主 runtime 会自动生成当前小程序的通用分享页。只有确实要分享外部 HTTP(S) 页面时才显式传 `url`。
-````

package/skill/references/recipes.md

@@ -24,7 +24,7 @@
 
 # 快速开始
 
-如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
+如果页面不需要小黑盒开放能力，可以不接入 SDK。这是最短接入路径：等待 SDK 就绪，然后读取当前用户登录态。
 
 ```ts
 import hbSDK from '@heybox/hb-sdk'
@@ -78,13 +78,11 @@ onUnmounted(stopAuthChange)
 
 ## ready 的含义
 
-`ready()` 表示 SDK 已完成与父容器的握手，可以安全调用开放能力。SDK 在收到 `ready` 前会自动重试握手；如果超过总超时时间仍未成功，会抛出 `READY_TIMEOUT`。它不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
+`ready()` 表示 SDK 已就绪，可以安全调用开放能力。如果当前不在可用的小程序运行环境中，它会抛出公开错误。`ready()` 不等价于“用户已登录”，用户状态需要通过 `user.getInfo()` 或 `authChange` 判断。
 
 ## 默认单例适合什么场景
 
-默认单例适合一个页面只有一个 SDK 上下文的情况。大多数小程序页面都应该使用默认单例，因为它可以避免重复握手和重复维护事件监听。
-
-0.6 起根入口只提供唯一默认实例并在导入时立即握手，不再允许业务创建独立实例。测试需要隔离 bridge 时应在应用边界替换公开模块。
+大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
 
 ## User and login
 
@@ -96,7 +94,7 @@ onUnmounted(stopAuthChange)
 - `user.getInfo()`：静默读取当前登录态与公开基础资料。
 - `auth.login()`：唤起黑盒登录流程，并返回登录后的最新公开用户资料。
 - `user.getCurrentUserDetail()`：读取当前用户展示详情。
-- `user.getCurrentUserProfile()`：读取当前用户敏感资料，需要对应 Runtime 权限。
+- `user.getCurrentUserProfile()`：读取当前用户敏感资料，需要对应平台权限。
 - `user.getPlatformAccountOverview()` / `getPlatformAccountInfo()`：读取平台账号概览或指定平台详情。
 - `user.getSteamGameList()`：读取当前用户 Steam 游戏库。
 
@@ -147,7 +145,7 @@ async function ensureLogin() {
 
 不会暴露 token、cookie、手机号或任何可用于调用主站私有接口的凭据。
 
-current-user scoped API 返回独立的 `UserScopedResult<T>`。未登录时是 `{ isLogin: false, data: null }`；已登录时才有 `data`。其中 `getCurrentUserProfile()` 可能返回生日、邮箱、教育和职业等敏感资料，必须按最小必要原则使用，并以 Runtime 权限结果为准；不要把这些字段理解为 `getInfo()` 的默认返回值。
+current-user scoped API 返回独立的 `UserScopedResult<T>`。未登录时是 `{ isLogin: false, data: null }`；已登录时才有 `data`。其中 `getCurrentUserProfile()` 可能返回生日、邮箱、教育和职业等敏感资料，必须按最小必要原则使用，并以平台权限结果为准；不要把这些字段理解为 `getInfo()` 的默认返回值。
 
 ```ts
 const profile = await user.getCurrentUserProfile()
@@ -183,7 +181,7 @@ onUnmounted(stopAuthChange)
 
 # 事件与生命周期
 
-SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
+SDK 通过 `on` 监听小程序生命周期和业务事件。
 
 ```ts
 import { onUnmounted } from 'vue'
@@ -212,12 +210,12 @@ onUnmounted(stopLifecycleEvents)
 
 | 事件         | 触发时机                 | 典型用途           |
 | ------------ | ------------------------ | ------------------ |
-| `launch`     | 小程序首次完成握手并启动 | 初始化一次性数据   |
-| `ready`      | SDK 可安全调用开放能力   | 标记 bridge 可用   |
+| `launch`     | 小程序首次启动           | 初始化一次性数据   |
+| `ready`      | SDK 可安全调用开放能力 | 标记 SDK 可用      |
 | `show`       | 小程序页面展示           | 刷新可见态数据     |
 | `hide`       | 小程序页面隐藏           | 暂停轮询、暂停播放 |
-| `unload`     | 当前 Runtime 上下文终止  | 清理资源并停止请求 |
-| `error`      | 父容器或开放能力运行异常 | 统一错误上报       |
+| `unload`     | 当前小程序运行环境终止 | 清理资源并停止请求 |
+| `error`      | 小程序或开放能力运行异常 | 统一错误上报       |
 | `authChange` | 登录状态变化             | 刷新用户信息和权限 |
 
 完整载荷与事件名见：
@@ -239,7 +237,10 @@ onUnmounted(stopLifecycleEvents)
 
 # 错误处理
 
-SDK 公开两类标准错误：`HbMiniProgramSDKError` 表示 handshake、bridge、Runtime 或 capability 故障；`HbMiniProgramNetworkError` 表示 HTTP 已完成，但状态没有通过 `validateStatus`。
+SDK 公开两类标准错误：
+
+- `HbMiniProgramSDKError`：SDK 初始化或开放能力调用失败。
+- `HbMiniProgramNetworkError`：网络请求已返回，但 HTTP 状态未通过 `validateStatus`。
 
 ```ts
 import {
@@ -265,19 +266,14 @@ try {
 }
 ```
 
-## SDK 内置错误
+## 处理原则
 
-| code              | 场景                              | 建议处理                           |
-| ----------------- | --------------------------------- | ---------------------------------- |
-| `NOT_IN_IFRAME`   | 当前页面不在小程序沙盒 iframe 中  | 提示运行环境错误，检查父容器接入   |
-| `MISSING_NONCE`   | URL 中缺少 `hb_mini_bridge_nonce` | 检查父容器 URL 注入逻辑            |
-| `READY_TIMEOUT`   | SDK 握手超时                      | 检查父容器是否幂等响应重试的 `sdk.handshake` |
-| `HANDSHAKE_FAILED` | 握手消息发送失败                 | 检查 iframe、nonce 与 Host 消息通道 |
-| `RUNTIME_UNAVAILABLE` | Runtime 已执行 `unload`       | 停止当前上下文请求并结束页面工作 |
-| `REQUEST_TIMEOUT` | 开放能力调用超时                  | 提示重试，并上报 method            |
-| `INVALID_NETWORK_RESPONSE` | Host 返回的网络响应结构无效 | 上报 Host/Runtime 协议问题 |
+- 根据 `error.code` 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
+- 权限失败时给出可理解的提示，不要将它当成未登录。
+- 超时或运行环境不可用时，允许用户重试或退出当前流程。
+- 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
 
-父容器返回失败响应时，SDK 也会包装成 `HbMiniProgramSDKError`，此时 `code` 由父容器开放能力定义。
+完整错误码和字段见 [HbMiniProgramSDKError](api-root.md) 与 [HbMiniProgramNetworkError](api-root.md)。
 
 ## 业务层建议
 
@@ -307,10 +303,6 @@ function reportSDKError(code: string, message: string, data?: unknown) {
 }
 ```
 
-## 超时时间
-
-默认握手超时时间是 10000ms。0.6 起业务不能通过独立实例修改该值；超时应作为 Host/Runtime 启动异常处理。
-
 ## Login gate recipe