hb-sdk

hb-sdk Agent Procedure

Apply these instructions when writing, reviewing, or debugging code that consumes @heybox/hb-sdk or uses the companion hb-sdk CLI.

Step 1: Classify the task

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 startup, production build, 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 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 for mini-program business code.
3. For common business flows, read references/recipes.md.
4. For CLI commands, production builds, 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.
8. For smoke-test expectations, positive examples, and anti-examples, read references/examples.md.
9. For evaluating whether another agent followed this skill, read references/smoke-evaluation.md.
10. For mini-program listing/audit/compliance review, fetch the online rules Markdown from https://open.xiaoheihe.cn/docs/hb_sdk/llms/guide/mini-program-publishing-rules.md. Do not rely on a bundled references/ copy of this document; if the URL is unavailable or returns the docs app shell instead of Markdown, report that the online rules are unavailable and do not complete the review from stale local text.

Step 3: Follow import rules

1. Import app-facing SDK APIs from @heybox/hb-sdk.
2. Import protocol contracts from @heybox/hb-sdk/protocol only in host/runtime/protocol-maintenance code.
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 workshop mini-program code

1. Import the root package eagerly; the SDK starts its handshake automatically and capability calls wait for it internally.
2. For a network-enabled mini-program, use auth.login({ scopes? }) to obtain { code, expiresIn: 300, scopes }. Identity is always implicit; request only optional scopes the business actually needs.
3. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
4. For a network-disabled mini-program, call user.getInfo() to read the current login state and userInfo.app_user_id. This read is silent and does not require a trusted user action. It cannot obtain a code or call OpenAPI.
5. Handle HbMiniProgramSDKError for SDK initialization and capability failures.
6. Handle HbMiniProgramNetworkError separately when HTTP completed but validateStatus rejected the status.
7. Use getHandshakeState() for the current persistent handshake state and onHandshakeStateChange() for an immediate replay plus future changes. Cancel the returned subscription when the page or component unmounts.
8. Treat the non-replayed ready lifecycle event only as an edge notification. After a duplicate handshake it may repeat, so never use it as state or as the source for enabling a late-mounted control.
9. Use the default SDK instance exposed by the root package. For gesture-gated controls, initialize from the current handshake state, subscribe to changes, and enable the control only when status === 'ready'. Keep calls such as auth.login() in the original user-action callback; do not wait for handshake inside that callback.
10. When authorization UI is required, call auth.login() from a trusted user action. Missing gesture returns USER_GESTURE_REQUIRED; cancelling, rejecting, or closing returns AUTHORIZATION_CANCELLED and does not confirm or change authorization. An already-authorized auth.login() request may return a new code silently.
11. user.getSteamGameList() is available only to network-disabled mini-programs. In a network-enabled mini-program it returns SERVER_API_REQUIRED, and there is no Steam library authorization scope or OpenAPI resource. Treat user.getInfo() returning SERVER_API_REQUIRED as a server-boundary signal, not as logged-out state.
12. Use share.showShareMenu({ post }) or share.screenshot({ post }) to preset editable community destinations and topics. Pass partition IDs through topicIds and topic text without surrounding # through topics; do not construct the underlying client post protocol.

Step 5: Use CLI workflows

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 build [--env <name>] [--verbose] as the recommended production build entry. It directly owns the Vite build, always cleans and writes dist/, and works without CLI login, project binding, or network access.
5. Keep miniappManifest() explicitly enabled in vite.config.ts; hb-sdk build must fail when the required Manifest or Runtime gate output is missing.
6. Keep project typechecking in scripts.build, for example vue-tsc --noEmit && hb-sdk build; hb-sdk build does not run typechecking or invoke scripts.build itself.
7. Existing projects may continue to use vite build; do not auto-migrate them. Do not invent --mode, --json, config, or output-directory flags for hb-sdk build.
8. Use hb-sdk login, hb-sdk login status, and hb-sdk login clear only for development and publishing commands. This login does not change auth.login(), user.getInfo(), or the mini-program user's authorization state.
9. 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.
10. 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.
11. 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.
12. Use hb-sdk remote deploy --release-note <text> to run the project's scripts.build, upload, and submit the current project for audit. Do not recommend the removed top-level hb-sdk deploy alias.
13. hb-sdk dev and hb-sdk remote deploy skip the platform CSP only when the validated remote permission snapshot has network.request.status=enabled. useOfficialDomain does not participate in CSP skip decisions. Direct hb-sdk build, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
14. After approval, use hb-sdk remote release <version> for manual release or --auto-publish when an eligible low-risk version should release automatically.
15. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
16. 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.
17. Use --json for remote script consumption and --verbose only when concise output is insufficient for diagnosis.
18. Use hb-sdk doctor to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
19. Do not print or expose cookies, tokens, private headers, or other credentials.

Step 6: Preserve capability boundaries

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, direct post publishing, or upload-only flows. Public share.*({ post }) options only preset an editable client post flow and never publish automatically.
3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
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.
7. Do not use network.request() to reach platform-reserved runtime auth or OpenAPI internal paths.
8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.

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 auth.login() or mini-program user authorization.
3. Use the built-in local debugging page instead of creating another browser Mock.
4. Keep the Vite miniappManifest() plugin enabled.
5. Treat permission changes made in the hb-sdk dev debugging page as local debugging overrides, not online configuration changes. Use the page's reset action to return to the remote baseline.
6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.

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 workshop mini-program business code.
3. Preserve compatibility with existing SDK clients.

Step 7: Validate changes

1. Run the nearest package tests and builds with repo-native commands when editing this repository.
2. When modifying docs, skill instructions, CLI guidance, or public agent-skill sync points, start with:
   • pnpm --filter @heybox/hb-sdk run check:docs-sync
   • cat packages/hb-sdk/DOC_SYNC_CHECKLIST.md
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, 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:
   • unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'
7. When adding or modifying the deploy command or its upload pipeline, also run:
   • pnpm --filter @heybox/hb-sdk run check:boundary
   • pnpm --filter @heybox/hb-sdk run test:unit
   • Verify dist/cli.cjs does not have any require('cos-nodejs-sdk-v5') left after build:cli; the boundary check enforces this automatically.
8. Verify the canonical payload before publishing:
   • pnpm exec hbexec hb-sdk sync
   • pnpm exec hbexec hb-sdk check
   • For a release artifact, run pnpm exec hbexec hb-sdk sync --out-dir <payload-dir> and then pnpm exec hbexec hb-sdk check-artifact --artifact-dir <payload-dir>.