@heybox/hb-sdk 0.6.9 → 0.7.0-alpha.2

package/skill/scripts/sync-references.mjs

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
+import ts from 'typescript';
 import { createSkillContentHash, createSkillManifest, normalizeSkillManifest } from './skill-metadata.mjs';
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
@@ -13,7 +14,9 @@ const checkMode = process.argv.includes('--check');
 const TEXT_FILE_RE = /\.(?:md|mjs|js|cjs|ts|tsx|json|txt|sh|yaml|yml)$/i;
 
 if (!repoRoot) {
-  console.error('Cannot sync hb-sdk references outside the heybox-webapp repository. Run this script from a checkout that contains packages/hb-sdk/package.json.');
+  console.error(
+    'Cannot sync hb-sdk references outside the heybox-webapp repository. Run this script from a checkout that contains packages/hb-sdk/package.json.',
+  );
   process.exit(1);
 }
 
@@ -35,7 +38,7 @@ function read(relativePath) {
 
 function extractSection(markdown, heading) {
   const lines = markdown.split('\n');
-  const start = lines.findIndex(line => line.trim() === heading);
+  const start = lines.findIndex((line) => line.trim() === heading);
   if (start === -1) return '';
   const level = heading.match(/^#+/)?.[0].length ?? 2;
   const out = [lines[start]];
@@ -67,7 +70,7 @@ function extractSection(markdown, heading) {
 
 function fenced(language, value) {
   const content = value.trimEnd();
-  const longestFence = Math.max(2, ...Array.from(content.matchAll(/`{3,}/g), match => match[0].length));
+  const longestFence = Math.max(2, ...Array.from(content.matchAll(/`{3,}/g), (match) => match[0].length));
   const fence = '`'.repeat(longestFence + 1);
   return `${fence}${language}\n${content}\n${fence}`;
 }
@@ -80,7 +83,7 @@ function header(title, sources) {
     '',
     '## Sources',
     '',
-    ...sources.map(source => `- ${source}`),
+    ...sources.map((source) => `- ${source}`),
     '',
   ].join('\n');
 }
@@ -99,10 +102,7 @@ function rewriteBundledRecipeLinks(markdown) {
 }
 
 function rewriteBundledCliLinks(markdown) {
-  return markdown.replaceAll(
-    '(./mini-program-publishing-rules)',
-    '(https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)',
-  );
+  return markdown.replaceAll('(./mini-program-publishing-rules)', '(https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)');
 }
 
 function rewriteBundledProtocolIndexLinks(markdown) {
@@ -114,14 +114,50 @@ function rewriteBundledProtocolIndexLinks(markdown) {
     .replaceAll('(../guide/)', '(recipes.md)');
 }
 
+const INTERNAL_PROTOCOL_DIAGNOSTIC_EXPORTS = new Set([
+  'RUNTIME_LOCATION_PROBE_METHOD',
+  'RuntimeLocationProbePayload',
+  'SDK_CSP_VIOLATION_METHOD',
+  'SDK_LOCATION_REPORT_METHOD',
+  'SDKCSPBlockedResourceType',
+  'SDKCSPViolationPayload',
+  'SDKLocationReportPayload',
+  'SDKLocationReportTrigger',
+]);
+
+function omitNamedExports(source, omittedNames) {
+  const sourceFile = ts.createSourceFile('protocol.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const lineStarts = sourceFile.getLineStarts();
+  const removals = [];
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) {
+      continue;
+    }
+
+    for (const element of statement.exportClause.elements) {
+      if (!omittedNames.has(element.name.text)) continue;
+
+      const { line } = sourceFile.getLineAndCharacterOfPosition(element.getStart(sourceFile));
+      const start = lineStarts[line];
+      const end = lineStarts[line + 1] ?? source.length;
+      const lineText = source.slice(start, end).trim();
+      const elementText = element.getText(sourceFile);
+
+      if (lineText !== `${elementText},` && lineText !== elementText) {
+        throw new Error(`Internal protocol export must occupy its own line: ${element.name.text}`);
+      }
+      removals.push({ start, end });
+    }
+  }
+
+  return removals
+    .sort((left, right) => right.start - left.start)
+    .reduce((result, { start, end }) => `${result.slice(0, start)}${result.slice(end)}`, source);
+}
+
 function contents(items) {
-  return [
-    '',
-    '## Contents',
-    '',
-    ...items.map(([title, anchor]) => `- [${title}](#${anchor})`),
-    '',
-  ].join('\n');
+  return ['', '## Contents', '', ...items.map(([title, anchor]) => `- [${title}](#${anchor})`), ''].join('\n');
 }
 
 function toPosix(value) {
@@ -183,7 +219,7 @@ function createCurrentSkillManifest(generatedReferences) {
   ];
   const fileEntries = Array.from(new Set(distributableFiles))
     .sort((left, right) => left.localeCompare(right))
-    .map(relativePath => ({
+    .map((relativePath) => ({
       path: relativePath,
       content: readGeneratedOrDiskSkillFile(relativePath, generatedReferences),
     }));
@@ -194,7 +230,6 @@ function createCurrentSkillManifest(generatedReferences) {
   });
 }
 
-
 const packageJson = JSON.parse(read('packages/hb-sdk/package.json'));
 const rootEntry = read('packages/hb-sdk/src/index.ts');
 const protocolEntry = read('packages/hb-sdk/src/protocol.ts');
@@ -212,6 +247,8 @@ const customInstance = frontmatterless(read('apps/docs/hb-sdk/recipes/custom-ins
 const referenceHome = frontmatterless(read('apps/docs/hb-sdk/reference/index.md'));
 const publicCapabilities = extractSection(readme, '## 能力概览');
 const capabilityBoundaries = extractSection(readme, '## 关键约束');
+const leaderboardSection = extractSection(readme, '## 云端排行榜');
+const publicProtocolEntry = omitNamedExports(protocolEntry, INTERNAL_PROTOCOL_DIAGNOSTIC_EXPORTS);
 const manifestSection = extractSection(cliGuide, '## 生产构建');
 const cliCreateSection = extractSection(cliGuide, '## 创建工坊小程序');
 const cliDevSection = extractSection(cliGuide, '## 推荐调试流程');
@@ -254,9 +291,12 @@ Removed: hb-sdk deploy`;
 
 const cliRemoteEntitySection = `Developer account selection lives under \`hb-sdk remote entity\`:
 
-${fenced('bash', `hb-sdk remote entity list
+${fenced(
+  'bash',
+  `hb-sdk remote entity list
 hb-sdk remote entity current
-hb-sdk remote entity switch <entity-id>`)}
+hb-sdk remote entity switch <entity-id>`,
+)}
 
 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.`;
 
@@ -264,22 +304,25 @@ const cliRemoteEntityDeploySection = `Before publishing, \`hb-sdk remote deploy\
 
 const files = new Map();
 
-files.set('api-root.md', `${header('Root API reference', [
-  'packages/hb-sdk/package.json',
-  'packages/hb-sdk/src/index.ts',
-  'packages/hb-sdk/src/vite/index.ts',
-  'packages/hb-sdk/README.md',
-  'apps/docs/hb-sdk/guide/quick-start.md',
-  'apps/docs/hb-sdk/guide/error-handling.md',
-  'apps/docs/hb-sdk/guide/lifecycle.md',
-  'apps/docs/hb-sdk/guide/cli.md',
-])}${contents([
-  ['Package metadata', 'package-metadata'],
-  ['Public root entrypoint', 'public-root-entrypoint'],
-  ['Vite plugin export', 'vite-plugin-export'],
-  ['App-facing concepts', 'app-facing-concepts'],
-  ['Public modules', 'public-modules'],
-])}## Package metadata
+files.set(
+  'api-root.md',
+  `${header('Root API reference', [
+    'packages/hb-sdk/package.json',
+    'packages/hb-sdk/src/index.ts',
+    'packages/hb-sdk/src/vite/index.ts',
+    'packages/hb-sdk/README.md',
+    'apps/docs/hb-sdk/guide/quick-start.md',
+    'apps/docs/hb-sdk/guide/error-handling.md',
+    'apps/docs/hb-sdk/guide/lifecycle.md',
+    'apps/docs/hb-sdk/guide/cli.md',
+  ])}${contents([
+    ['Package metadata', 'package-metadata'],
+    ['Public root entrypoint', 'public-root-entrypoint'],
+    ['Vite plugin export', 'vite-plugin-export'],
+    ['App-facing concepts', 'app-facing-concepts'],
+    ['Public modules', 'public-modules'],
+    ['Cloud leaderboard', 'cloud-leaderboard'],
+  ])}## Package metadata
 
 - Package: \`${packageJson.name}\`
 - Version at generation time: \`${packageJson.version}\`
@@ -310,53 +353,58 @@ ${rewriteBundledRecipeLinks(errorGuide)}
 ${publicCapabilities}
 
 ${rewriteBundledRecipeLinks(lifecycleGuide)}
-`);
 
-files.set('api-protocol.md', `${header('Protocol API reference', [
-  'packages/hb-sdk/src/protocol.ts',
-  'apps/docs/hb-sdk/reference/index.md',
-])}${contents([
-  ['Host/runtime-only warning', 'hostruntime-only-warning'],
-  ['Public protocol entrypoint', 'public-protocol-entrypoint'],
-  ['Generated reference index', 'generated-reference-index'],
-])}## Host/runtime-only warning
+${leaderboardSection}
+`,
+);
+
+files.set(
+  'api-protocol.md',
+  `${header('Protocol API reference', ['packages/hb-sdk/src/protocol.ts', 'apps/docs/hb-sdk/reference/index.md'])}${contents([
+    ['Host/runtime-only warning', 'hostruntime-only-warning'],
+    ['Public protocol entrypoint', 'public-protocol-entrypoint'],
+    ['Generated reference index', 'generated-reference-index'],
+  ])}## Host/runtime-only warning
 
 Use \`@heybox/hb-sdk/protocol\` only for parent-container runtime, bridge-server, protocol-contract, or \`@heybox/hb-sdk-runtime\` integration tasks. Iframe mini-program business code must use root SDK APIs and must not construct bridge envelopes, nonce handling, or raw \`postMessage\` flows.
 
 ## Public protocol entrypoint
 
-${fenced('ts', protocolEntry)}
+${fenced('ts', publicProtocolEntry)}
 
 ## Generated reference index
 
 ${rewriteBundledProtocolIndexLinks(referenceHome)}
-`);
-
-files.set('cli.md', `${header('CLI reference', [
-  'packages/hb-sdk/package.json',
-  'packages/hb-sdk/src/cli/index.ts',
-  'packages/hb-sdk/src/cli/commands/create.ts',
-  'packages/hb-sdk/src/cli/commands/dev.ts',
-  'packages/hb-sdk/src/cli/commands/build.ts',
-  'packages/hb-sdk/src/cli/commands/login.ts',
-  'apps/docs/hb-sdk/guide/cli.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 debugging', 'local-debugging'],
-  ['Production build', 'production-build'],
-  ['Deploy and publish', 'deploy-and-publish'],
-  ['Developer account scope', 'developer-account-scope'],
-  ['Remote management commands', 'remote-management-commands'],
-  ['CLI login', 'cli-login'],
-  ['Agent Skill doctor', 'agent-skill-doctor'],
-  ['Update reminders', 'update-reminders'],
-])}## When to use the CLI
+`,
+);
+
+files.set(
+  'cli.md',
+  `${header('CLI reference', [
+    'packages/hb-sdk/package.json',
+    'packages/hb-sdk/src/cli/index.ts',
+    'packages/hb-sdk/src/cli/commands/create.ts',
+    'packages/hb-sdk/src/cli/commands/dev.ts',
+    'packages/hb-sdk/src/cli/commands/build.ts',
+    'packages/hb-sdk/src/cli/commands/login.ts',
+    'apps/docs/hb-sdk/guide/cli.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 debugging', 'local-debugging'],
+    ['Production build', 'production-build'],
+    ['Deploy and publish', 'deploy-and-publish'],
+    ['Developer account scope', 'developer-account-scope'],
+    ['Remote management commands', 'remote-management-commands'],
+    ['CLI login', 'cli-login'],
+    ['Agent Skill doctor', 'agent-skill-doctor'],
+    ['Update reminders', 'update-reminders'],
+  ])}## When to use the CLI
 
 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.
 
-\`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.
+\`hb-sdk login\` is for development and publishing commands only. It does not authorize mini-program users and does not change \`auth.login()\`, \`user.getLocalIdentity()\`, or \`network.request()\` inside a mini-program.
 
 ## Command surface
 
@@ -460,25 +508,28 @@ Agent rules:
 
 ${cliUpdateSection}
 
-`);
-
-files.set('recipes.md', `${header('Recipes', [
-  'apps/docs/hb-sdk/guide/quick-start.md',
-  'apps/docs/hb-sdk/guide/auth.md',
-  'apps/docs/hb-sdk/guide/lifecycle.md',
-  'apps/docs/hb-sdk/guide/error-handling.md',
-  'apps/docs/hb-sdk/recipes/login-gate.md',
-  'apps/docs/hb-sdk/recipes/community-share.md',
-  'apps/docs/hb-sdk/recipes/custom-instance.md',
-])}${contents([
-  ['Quick start', 'quick-start'],
-  ['User and login', 'user-and-login'],
-  ['Lifecycle events', 'lifecycle-events'],
-  ['Error handling', 'error-handling'],
-  ['Login gate recipe', 'login-gate-recipe'],
-  ['Community share recipe', 'community-share-recipe'],
-  ['Custom instance recipe', 'custom-instance-recipe'],
-])}## Quick start
+`,
+);
+
+files.set(
+  'recipes.md',
+  `${header('Recipes', [
+    'apps/docs/hb-sdk/guide/quick-start.md',
+    'apps/docs/hb-sdk/guide/auth.md',
+    'apps/docs/hb-sdk/guide/lifecycle.md',
+    'apps/docs/hb-sdk/guide/error-handling.md',
+    'apps/docs/hb-sdk/recipes/login-gate.md',
+    'apps/docs/hb-sdk/recipes/community-share.md',
+    'apps/docs/hb-sdk/recipes/custom-instance.md',
+  ])}${contents([
+    ['Quick start', 'quick-start'],
+    ['User and login', 'user-and-login'],
+    ['Lifecycle events', 'lifecycle-events'],
+    ['Error handling', 'error-handling'],
+    ['Login gate recipe', 'login-gate-recipe'],
+    ['Community share recipe', 'community-share-recipe'],
+    ['Custom instance recipe', 'custom-instance-recipe'],
+  ])}## Quick start
 
 ${rewriteBundledRecipeLinks(quickStart)}
 
@@ -505,12 +556,12 @@ ${rewriteBundledRecipeLinks(communityShare)}
 ## Custom instance recipe
 
 ${rewriteBundledRecipeLinks(customInstance)}
-`);
+`,
+);
 
-files.set('safety-boundaries.md', `${header('Safety boundaries', [
-  'packages/hb-sdk/README.md',
-  'apps/docs/hb-sdk/guide/auth.md',
-])}## Required boundaries
+files.set(
+  'safety-boundaries.md',
+  `${header('Safety boundaries', ['packages/hb-sdk/README.md', 'apps/docs/hb-sdk/guide/auth.md'])}## Required boundaries
 
 ${capabilityBoundaries}
 
@@ -519,19 +570,22 @@ ${capabilityBoundaries}
 - Do not instruct mini-program code to read, extract, forward, store, or depend on token, cookie, phone number, or private credentials.
 - Negative safety statements that explain the SDK does not expose token/cookie/private credentials are correct and should be preserved.
 - Do not use raw share protocol fields, JS callbacks, activity reporting, direct post publishing, custom buttons, or upload-only flows. Public \`share.*({ post })\` options only preset an editable client post flow.
-- Do not use storage delete, clear, info listing, V2, or global Heybox client storage access.
+- Do not use storage delete, clear, info listing, or global Heybox client storage access.
 - Do not pass host-only protocol fields through \`network.request\`.
 - Do not build raw \`postMessage\` bridge flows in iframe business code.
 - Do not fetch deployed \`dist/manifest.json\` from business code; it is a build artifact for the release pipeline, not a CDN runtime asset.
 - Do not import from internal hb-sdk implementation paths; only use documented package entrypoints.
-`);
-
-files.set('llms-index.md', `${header('LLM documentation index', [
-  'apps/docs/hb-sdk/guide/**',
-  'apps/docs/hb-sdk/recipes/**',
-  'apps/docs/hb-sdk/reference/**',
-  'packages/hb-sdk/src/**',
-])}## Offline references
+`,
+);
+
+files.set(
+  'llms-index.md',
+  `${header('LLM documentation index', [
+    'apps/docs/hb-sdk/guide/**',
+    'apps/docs/hb-sdk/recipes/**',
+    'apps/docs/hb-sdk/reference/**',
+    'packages/hb-sdk/src/**',
+  ])}## Offline references
 
 The bundled references are generated directly from hand-maintained docs, generated API owner sources, and SDK/CLI sources. They do not depend on the docs site's \`.vitepress/public/llms\` mirrors.
 
@@ -545,49 +599,72 @@ The bundled references are generated directly from hand-maintained docs, generat
 ## Online supplement
 
 Online \`llms.txt\` and markdown mirrors are optional supplements, not prerequisites for offline Skill use. Their canonical public URL is not frozen: on 2026-07-10 \`https://docs.xiaoheihe.cn/hb_sdk/llms.txt\` returned 404 and the legacy URL fetch timed out. Do not claim either endpoint is available without a fresh successful response.
-`);
+`,
+);
 
-files.set('examples.md', `${header('Smoke examples and anti-examples', [
-  'packages/hb-sdk/README.md',
-  'apps/docs/hb-sdk/guide/**',
-  'apps/docs/hb-sdk/recipes/**',
-])}## Positive examples
+files.set(
+  'examples.md',
+  `${header('Smoke examples and anti-examples', [
+    'packages/hb-sdk/README.md',
+    'apps/docs/hb-sdk/guide/**',
+    'apps/docs/hb-sdk/recipes/**',
+  ])}## Positive examples
 
-### Minimal user info
+### Local identity for a network-disabled mini-program
 
-${fenced('ts', `import { ready, user } from '@heybox/hb-sdk';
+${fenced(
+  'ts',
+  `import { ready, user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
-await ready();
+export async function getLocalIdentityFromUserAction() {
+  await ready();
 
-const result = await user.getInfo();
-if (result.isLogin && result.userInfo) {
-  console.log(result.userInfo.nickname);
-}`)}
+  try {
+    return await user.getLocalIdentity();
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return undefined;
+    }
+    throw error;
+  }
+}`,
+)}
 
-### Login gate
+### Developer server session for a network-enabled mini-program
 
-${fenced('ts', `import { auth, ready, user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+${fenced(
+  'ts',
+  `import { auth, network, ready, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
-export async function ensureLogin() {
+export async function createServerSessionFromUserAction() {
   await ready();
 
-  const current = await user.getInfo();
-  if (current.isLogin && current.userInfo) return current.userInfo;
-
   try {
-    const loginResult = await auth.login();
-    return loginResult.userInfo;
+    const result = await auth.login({ scopes: ['profile'] });
+    await exchangeCodeWithDeveloperServer(result.code);
+    return { status: 'ready' as const };
   } catch (error) {
-    if (error instanceof HbMiniProgramSDKError) {
-      console.warn(error.code, error.message);
+    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+      return { status: 'cancelled' as const };
     }
-    return null;
+    throw error;
   }
-}`)}
+}
+
+async function exchangeCodeWithDeveloperServer(code: string) {
+  await network.request({
+    url: 'https://api.example.com/session/heybox',
+    method: 'POST',
+    data: { code },
+  });
+}`,
+)}
 
 ### Network request
 
-${fenced('ts', `import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+${fenced(
+  'ts',
+  `import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 try {
   await ready();
@@ -616,42 +693,55 @@ try {
     // e.g. INVALID_PARAMS for unsupported multipart shape
     console.warn(error.code, error.message);
   }
-}`)}
+}`,
+)}
 
 ### Host/runtime protocol import
 
-${fenced('ts', `import { NETWORK_REQUEST_METHOD, type NetworkRequestPayload } from '@heybox/hb-sdk/protocol';
+${fenced(
+  'ts',
+  `import { NETWORK_REQUEST_METHOD, type NetworkRequestPayload } from '@heybox/hb-sdk/protocol';
 
 // Host/runtime integration only. Do not use this in iframe business code.
 export function canHandleNetwork(method: string): method is typeof NETWORK_REQUEST_METHOD {
   return method === NETWORK_REQUEST_METHOD;
-}`)}
+}`,
+)}
 
 ### CLI local mock development
 
-${fenced('bash', `hb-sdk create my-miniapp
+${fenced(
+  'bash',
+  `hb-sdk create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
 
 # In an existing project:
-hb-sdk dev`)}
+hb-sdk dev`,
+)}
 
 ### CLI login cache
 
-${fenced('bash', `hb-sdk login
+${fenced(
+  'bash',
+  `hb-sdk login
 hb-sdk login status
-hb-sdk login clear`)}
+hb-sdk login clear`,
+)}
 
 ### Vite manifest plugin
 
-${fenced('ts', `import { miniappManifest } from '@heybox/hb-sdk/vite';
+${fenced(
+  'ts',
+  `import { miniappManifest } from '@heybox/hb-sdk/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
   plugins: [miniappManifest()],
-});`)}
+});`,
+)}
 
 ## Negative examples
 
@@ -664,7 +754,8 @@ export default defineConfig({
 - Do not treat \`hb-sdk login\` as iframe SDK authentication state.
 - Do not create a second mock runtime package when \`hb-sdk dev\` is the supported local mock workflow.
 - Do not import \`@heybox/hb-sdk/vite\` from iframe business code or fetch a deployed \`manifest.json\` directly.
-`);
+`,
+);
 
 const skillManifest = normalizeSkillManifest(createCurrentSkillManifest(files));
 
@@ -691,7 +782,12 @@ if (currentSkillManifest !== skillManifest) {
 }
 
 if (checkMode && changed) {
-  console.error(`hb-sdk skill references are out of date. Run \`node ${path.relative(repoRoot, fileURLToPath(import.meta.url)).split(path.sep).join('/')}\`.`);
+  console.error(
+    `hb-sdk skill references are out of date. Run \`node ${path
+      .relative(repoRoot, fileURLToPath(import.meta.url))
+      .split(path.sep)
+      .join('/')}\`.`,
+  );
   process.exit(1);
 }
 

package/skill/scripts/validate-skill.mjs

@@ -3,11 +3,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-import {
-  HB_SDK_PACKAGE_NAME,
-  HB_SDK_SKILL_NAME,
-  validateSkillManifest,
-} from './skill-metadata.mjs';
+import { HB_SDK_PACKAGE_NAME, HB_SDK_SKILL_NAME, validateSkillManifest } from './skill-metadata.mjs';
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const skillRoot = path.resolve(scriptDir, '..');
@@ -156,17 +152,18 @@ if (existsSync(skillMdPath)) {
 }
 
 const nestedReferenceFiles = existsSync(path.join(skillRoot, 'references'))
-  ? walk(path.join(skillRoot, 'references')).filter(file => path.dirname(path.relative(path.join(skillRoot, 'references'), file)).includes(path.sep))
+  ? walk(path.join(skillRoot, 'references')).filter((file) =>
+      path.dirname(path.relative(path.join(skillRoot, 'references'), file)).includes(path.sep),
+    )
   : [];
 for (const file of nestedReferenceFiles) fail(`References must be one level deep: ${skillRel(file)}`);
 
-if (existsSync(path.join(skillRoot, 'README.md'))) fail('Do not create README.md inside hb-sdk skill; keep human distribution docs outside the skill folder.');
+if (existsSync(path.join(skillRoot, 'README.md')))
+  fail('Do not create README.md inside hb-sdk skill; keep human distribution docs outside the skill folder.');
 if (existsSync(path.join(skillRoot, 'CHANGELOG.md'))) fail('Do not create CHANGELOG.md inside hb-sdk skill.');
 if (existsSync(path.join(skillRoot, 'INSTALLATION_GUIDE.md'))) fail('Do not create INSTALLATION_GUIDE.md inside hb-sdk skill.');
 
-const textFiles = existsSync(skillRoot)
-  ? walk(skillRoot).filter(file => /\.(md|yaml|yml|json|txt)$/.test(file))
-  : [];
+const textFiles = existsSync(skillRoot) ? walk(skillRoot).filter((file) => /\.(md|yaml|yml|json|txt)$/.test(file)) : [];
 
 const negativeMarkers = [
   'do not',
@@ -189,7 +186,8 @@ const negativeMarkers = [
   '无',
   '禁止',
 ];
-const positiveCredentialPattern = /\b(read|extract|forward|store|persist|depend on|use|request|expose|get|parse|send)\b.*\b(token|cookie|credentials?|phone number|login state)\b/i;
+const positiveCredentialPattern =
+  /\b(read|extract|forward|store|persist|depend on|use|request|expose|get|parse|send)\b.*\b(token|cookie|credentials?|phone number|login state)\b/i;
 const unsupportedStoragePattern = /\b(removeStorage|clearStorage|getStorageInfo|getStorageV2|delete storage|clear storage)\b/i;
 const rawProtocolPattern = /\b(raw postMessage|construct bridge|bridge envelope|nonce handling|mutate bridge|sdk\.handshake)\b/i;
 const removedUserLoginPattern = /\b(?:hbSDK\.)?user\.login\s*\(/;
@@ -199,10 +197,16 @@ for (const file of textFiles) {
   const content = read(file);
   if (file.endsWith('.md')) validateLocalMarkdownLinks(file, content);
   if (removedUserLoginPattern.test(content)) {
-    fail(`Removed API guidance found in ${relative}: use auth.login() instead of user.login().`);
+    fail(
+      `Removed API guidance found in ${relative}: use auth.login() for network-enabled server authentication or user.getLocalIdentity() for network-disabled local identity instead of user.login().`,
+    );
   }
 
-  if (new RegExp(`${HB_SDK_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/(?!(?:protocol|vite|miniapp-publish)\\b)[A-Za-z0-9_./-]+`).test(content)) {
+  if (
+    new RegExp(`${HB_SDK_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/(?!(?:protocol|vite|miniapp-publish)\\b)[A-Za-z0-9_./-]+`).test(
+      content,
+    )
+  ) {
     fail(
       `Deep/internal hb-sdk import guidance found in ${relative}. Only @heybox/hb-sdk, @heybox/hb-sdk/protocol, @heybox/hb-sdk/vite, and @heybox/hb-sdk/miniapp-publish are allowed.`,
     );
@@ -211,7 +215,7 @@ for (const file of textFiles) {
   const lines = content.split('\n');
   lines.forEach((line, index) => {
     const lower = line.toLowerCase();
-    const isNegative = negativeMarkers.some(marker => lower.includes(marker));
+    const isNegative = negativeMarkers.some((marker) => lower.includes(marker));
     if (positiveCredentialPattern.test(line) && !isNegative) {
       fail(`Unsafe positive credential guidance in ${relative}:${index + 1}: ${line.trim()}`);
     }