@heybox/hb-sdk 0.6.4-alpha.0 → 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,145 +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
-hb-sdk create my-miniapp
+npx @heybox/hb-sdk@latest create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
 ```
 
-`hb-sdk create <project-name>` 会生成 Vue 3、Vite、TypeScript 和 npm 模板。`project-name` 同时作为目录名和 `package.json` 的 `name`，必须是合法的非 scoped npm 包名。目标目录不存在时会创建；目标目录已存在但非空时会拒绝覆盖。
-
-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` 等受管能力默认拒绝。公开 `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-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 历史产物"
-hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
-hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
-HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.0.1:8080 --release-note "本地后台联调"
-```
+### 浏览器 Mock 的边界
 
-`hb-sdk remote deploy` 把预检、构建、上传和提交审核串成一条命令。顶层 `hb-sdk deploy` 已硬切删除，不再作为兼容别名保留：
-
-1. 读取 `package.json.heybox.miniProgramId`，缺失即报错。
-2. 校验登录态，需先 `hb-sdk login`。
-3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
-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. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
-12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 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 为准。
+
+### 常用参数
+
+| 参数                  | 用途                             |
+| --------------------- | -------------------------------- |
+| `--port <port>`       | 指定页面开发服务端口。           |
+| `--mock-port <port>`  | 指定本地调试端口。           |
+| `--no-open`           | 启动后不自动打开浏览器。         |
+| `--verbose`           | 出现问题时输出更详细的诊断信息。 |
 
-`manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。小程序构建产物需要使用相对资源路径；`hb-sdk create` 模板会显式配置 `base: './'`，未配置 `base` 的项目也会由 `miniappManifest()` 在 build 时默认补成 `./`。构建产物只能在兼容的小黑盒 Runtime 中启动，普通浏览器直接打开时不会执行标准业务脚本。
+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.
 
-`dev`、手动 Vite build、`remote deploy` 的本地构建和 `--from-version` 路径都不执行客户端 `minimumSdkVersion` 查询或比较；Manifest 结构校验、版本 precheck 和服务端 submit-audit 策略仍然生效。
+## Deploy and publish
 
-默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。如需让指定用户预览未发布候选版本，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
+## 部署发布
 
-内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，优先用 `--service-tag <tag>` 或 `HB_SDK_SERVICE_TAG`。path-prefix 级 `special_tag` 仍可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
+浏览器和真机验收通过后，首次提交前需要登录 CLI 并绑定小程序：
 
-`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
+```bash
+hb-sdk login
+hb-sdk remote create
+# 或绑定已有小程序
+hb-sdk remote bind mp_xxxxxxxx
+```
 
-切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。CLI 支持加载 `.env.<name>` 预设，把其中的 `HB_SDK_*` 变量一次性注入当前进程（不覆盖已有值）：`--env <name>` 读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级更高，也可用 `HB_SDK_ENV=<name>` 触发。使用 `--env <name>` 或 `HB_SDK_ENV=<name>` 执行 `remote deploy` 时，CLI 还会把同一个 `name` 作为 `--mode <name>` 传给项目 build，使 CLI 后端环境与 Vite mode 保持一致。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。
+绑定完成后，`package.json` 中会记录 `heybox.miniProgramId`。提交审核使用：
 
 ```bash
-# 项目根准备 .env.test
-#   HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
-#   HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
-#   HB_SDK_SERVICE_TAG=my-test-tag
-
-hb-sdk remote deploy --env test --release-note "测试环境验证"
-hb-sdk remote info --env test
-HB_SDK_ENV=test hb-sdk remote versions
-hb-sdk remote deploy --env-file .env.local --release-note "本地联调"
-hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
+hb-sdk remote deploy --release-note "修复登录状态展示"
 ```
 
-`--env-file` 优先于 `--env`，`--service-tag` / `--api-base-url` / `--login-base-url` 优先于 `.env` 预设注入的同名变量，而预设又不会覆盖进程已有的环境变量，因此优先级为 flag > 进程 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
@@ -219,52 +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 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`、`hb-sdk remote withdraw`、`hb-sdk remote take-down`、`hb-sdk remote reopen` 和 `hb-sdk remote square hide` 会改变审核、发布或用户侧可见状态。交互式终端会展示小程序 id、名称、当前状态、目标版本和操作，再要求确认；非 TTY 环境必须传 `--yes`。
-
-所有 `hb-sdk remote` 子命令都支持 `--json`。开启后 stdout 只输出一个 JSON 对象；进度、警告、版本提醒和 verbose 诊断不能污染 stdout。
 
 Agent rules:
 
@@ -279,138 +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 --login-base-url https://login.test.xiaoheihe.cn
 hb-sdk login status
 hb-sdk login clear
 ```
 
-- `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
-- `hb-sdk login --login-base-url <url>` 会打开指定登录 origin，并把该登录环境写入 CLI 登录态。
-- `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`。
-````