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

package/skill/scripts/sync-references.mjs

@@ -93,7 +93,16 @@ function rewriteBundledRecipeLinks(markdown) {
   return markdown
     .replaceAll('(../recipes/custom-instance)', '(#custom-instance-recipe)')
     .replaceAll('(../reference/protocol/interfaces/MiniProgramEventPayloadMap)', '(api-root.md)')
-    .replaceAll('(../reference/protocol/types/#miniprogrameventname)', '(api-root.md)');
+    .replaceAll('(../reference/protocol/types/#miniprogrameventname)', '(api-root.md)')
+    .replaceAll('(../reference/root/classes/HbMiniProgramSDKError)', '(api-root.md)')
+    .replaceAll('(../reference/root/classes/HbMiniProgramNetworkError)', '(api-root.md)');
+}
+
+function rewriteBundledCliLinks(markdown) {
+  return markdown.replaceAll(
+    '(./mini-program-publishing-rules)',
+    '(https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)',
+  );
 }
 
 function rewriteBundledProtocolIndexLinks(markdown) {
@@ -191,7 +200,6 @@ const rootEntry = read('packages/hb-sdk/src/index.ts');
 const protocolEntry = read('packages/hb-sdk/src/protocol.ts');
 const viteEntry = read('packages/hb-sdk/src/vite/index.ts');
 const cliEntry = read('packages/hb-sdk/src/cli/index.ts');
-const cliTemplateReadme = read('packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs');
 const readme = read('packages/hb-sdk/README.md');
 const cliGuide = frontmatterless(read('apps/docs/hb-sdk/guide/cli.md'));
 const quickStart = frontmatterless(read('apps/docs/hb-sdk/guide/quick-start.md'));
@@ -210,20 +218,16 @@ const sdkRuntimeRelation = extractSection(readme, '## SDK 与 Runtime');
 const capabilityBoundaries = extractSection(readme, '## 能力边界');
 const manifestSection = extractSection(readme, '## Manifest');
 const cliSummarySection = extractSection(readme, '## CLI');
-const repositoryDevelopment = extractSection(readme, '## 本仓库开发');
-const cliCreateSection = extractSection(cliGuide, '## 创建外部小程序模板');
-const cliDevSection = [
-  extractSection(cliGuide, '## 本地开发模式'),
-  extractSection(cliGuide, '## Mock runtime 边界'),
-].filter(Boolean).join('\n\n');
+const cliCreateSection = extractSection(cliGuide, '## 创建工坊小程序');
+const cliDevSection = extractSection(cliGuide, '## 推荐调试流程');
 const cliDeploySection = extractSection(cliGuide, '## 部署发布');
 const cliRemoteSection = extractSection(cliGuide, '## 远端管理命令');
 const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
 const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
 const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
 const cliCommandSurface = `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
@@ -251,17 +255,15 @@ hb-sdk remote square show
 
 Removed: hb-sdk deploy`;
 
-const cliRemoteEntitySection = `Developer entity selection lives under \`hb-sdk remote entity\`:
+const cliRemoteEntitySection = `Developer account selection lives under \`hb-sdk remote entity\`:
 
 ${fenced('bash', `hb-sdk remote entity list
 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.
+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.`;
 
-\`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.`;
-
-const cliRemoteEntityDeploySection = `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.`;
+const cliRemoteEntityDeploySection = `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.`;
 
 const files = new Map();
 
@@ -343,29 +345,23 @@ files.set('cli.md', `${header('CLI reference', [
   '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 \`${packageJson.name}\`. 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
 
@@ -379,20 +375,20 @@ ${cliCreateSection}
 
 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
 
 ${cliDevSection}
 
-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.
+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.
 
-## Deploy and backend operations
+## Deploy and publish
 
-${cliDeploySection}
+${rewriteBundledCliLinks(cliDeploySection)}
 
 ${cliRemoteEntityDeploySection}
 
@@ -400,25 +396,18 @@ 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
 
 ${cliRemoteEntitySection}
 
 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.
@@ -440,14 +429,13 @@ 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
 
 ${cliLoginSection}
 
 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.
@@ -461,19 +449,11 @@ 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 \`${packageJson.name}@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
 
 ${cliUpdateSection}
 
-## Repository validation commands
-
-${repositoryDevelopment}
-
-## Generated template README
-
-${fenced('md', cliTemplateReadme)}
 `);
 
 files.set('recipes.md', `${header('Recipes', [

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.4+skill.36b02466ef23",
+  "skillVersion": "0.6.6-alpha.0+skill.cfc5c9fb3951",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.4",
-    "compatibility": "0.6.4"
+    "version": "0.6.6-alpha.0",
+    "compatibility": "0.6.6-alpha.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-36b02466ef23a54c71c1eff6f9610dfa63d25d423529b20a6d8d50c8f1e85eaf"
+  "integrity": "sha256-cfc5c9fb39515fb1aa10fa2fc4db030d31ff0034b389062e009c0d6f2195e9e4"
 }

package/types/protocol/dev-session.d.ts

@@ -0,0 +1,25 @@
+import type { MiniProgramRuntimePermissionsSnapshot } from './runtime-permissions';
+/** Dev Shell 读取局域网 Dev Session endpoint 的 query 参数。 */
+export declare const MINI_PROGRAM_DEV_CONTEXT_QUERY_PARAM = "dev_context_url";
+/** Mock Host 创建和读取 Dev Session 的固定路径。 */
+export declare const MINI_PROGRAM_DEV_CONTEXT_PATH = "/__hb_sdk__/dev-context";
+/** Dev Session 当前使用的 schema 版本。 */
+export declare const MINI_PROGRAM_DEV_SESSION_SCHEMA_VERSION: 1;
+/** Mock Host 创建 Dev Session 时接收的请求。 */
+export interface MiniProgramDevSessionCreatePayload {
+    mini_url_origin: string;
+    runtime_permissions: MiniProgramRuntimePermissionsSnapshot;
+}
+/** Mock Host 创建 Dev Session 后返回的短期引用。 */
+export interface MiniProgramDevSessionCreateResult {
+    expires_at: number;
+    token: string;
+}
+/** Runtime Host 通过短期引用读取的不可变 Dev Session 快照。 */
+export interface MiniProgramDevSessionSnapshot {
+    schema_version: typeof MINI_PROGRAM_DEV_SESSION_SCHEMA_VERSION;
+    revision: number;
+    expires_at: number;
+    mini_url_origin: string;
+    runtime_permissions: MiniProgramRuntimePermissionsSnapshot;
+}