@heybox/hb-sdk 0.6.6-alpha.1 → 0.6.6-alpha.3

package/dist/cli-chunks/{session-BRwveiW8.cjs → session-YJ8xNESM.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-gP0K2xx1.cjs');
+var index = require('./index-QAkYgxPI.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-gP0K2xx1.cjs');
+var index = require('./cli-chunks/index-QAkYgxPI.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');

package/dist/devtools/mock-host/main.js

@@ -4245,15 +4245,150 @@ function getPositiveNumber(value, fallback) {
     return numberValue;
 }
 
+const MINI_PROGRAM_DEV_SHELL_PROTOCOL = 'heybox-mini-dev:';
+function isMiniProgramDevShellHref(href) {
+    try {
+        return isMiniProgramDevShellUrl(new URL(href));
+    }
+    catch {
+        return false;
+    }
+}
+function isMiniProgramDevShellUrl(url) {
+    return url.protocol === MINI_PROGRAM_DEV_SHELL_PROTOCOL;
+}
+
+function readMiniProgramRuntimeSharePostOptions(value, options) {
+    if (value === undefined || value === null) {
+        return {};
+    }
+    if (!isMiniProgramRuntimeRecord(value)) {
+        return invalidSharePostResult(`${options.method} post 必须是对象或 null`);
+    }
+    const topicIds = readTopicIds(value.topicIds);
+    const topics = readTopics(value.topics);
+    const invalidMessages = [...topicIds.invalidMessages, ...topics.invalidMessages];
+    let normalizedTopicIds = topicIds.values;
+    if (options.maxTopicIds !== undefined && normalizedTopicIds.length > options.maxTopicIds) {
+        invalidMessages.push(`${options.method} post.topicIds 最多允许 ${options.maxTopicIds} 项`);
+        normalizedTopicIds = normalizedTopicIds.slice(0, options.maxTopicIds);
+    }
+    const post = createNormalizedPostOptions(normalizedTopicIds, topics.values);
+    if (!post) {
+        invalidMessages.push(`${options.method} post 至少需要一个有效的 topicIds 或 topics`);
+    }
+    return {
+        post,
+        invalidMessage: invalidMessages[0],
+    };
+}
+function handleMiniProgramRuntimeSharePostValidation(result, platformAdapter, invoke) {
+    if (!result.invalidMessage) {
+        return invoke(result.post);
+    }
+    const invalidMessage = result.invalidMessage;
+    return isMiniProgramShareDevelopmentRuntime(platformAdapter).then((isDevelopment) => {
+        if (isDevelopment) {
+            throw createMiniProgramRuntimeBridgeError('INVALID_PARAMS', invalidMessage);
+        }
+        return invoke(result.post);
+    });
+}
+function readTopicIds(value) {
+    if (value === undefined) {
+        return { values: [], invalidMessages: [] };
+    }
+    if (!Array.isArray(value)) {
+        return { values: [], invalidMessages: ['post.topicIds 必须是数组'] };
+    }
+    const values = [];
+    const seen = new Set();
+    const invalidMessages = [];
+    for (const item of value) {
+        const normalized = normalizeTopicId(item);
+        if (!normalized) {
+            invalidMessages.push('post.topicIds 每项必须是正整数或非空字符串');
+            continue;
+        }
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            values.push(normalized);
+        }
+    }
+    return { values, invalidMessages };
+}
+function readTopics(value) {
+    if (value === undefined) {
+        return { values: [], invalidMessages: [] };
+    }
+    if (!Array.isArray(value)) {
+        return { values: [], invalidMessages: ['post.topics 必须是数组'] };
+    }
+    const values = [];
+    const seen = new Set();
+    const invalidMessages = [];
+    for (const item of value) {
+        const normalized = typeof item === 'string' ? item.trim() : '';
+        if (!normalized || normalized.startsWith('#') || normalized.endsWith('#')) {
+            invalidMessages.push('post.topics 每项必须是不含首尾 # 的非空字符串');
+            continue;
+        }
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            values.push(normalized);
+        }
+    }
+    return { values, invalidMessages };
+}
+function normalizeTopicId(value) {
+    if (typeof value === 'number') {
+        return Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+    }
+    if (typeof value === 'string') {
+        return value.trim() || undefined;
+    }
+    return undefined;
+}
+function createNormalizedPostOptions(topicIds, topics) {
+    if (topicIds.length === 0 && topics.length === 0) {
+        return undefined;
+    }
+    return {
+        ...(topicIds.length > 0 ? { topicIds } : {}),
+        ...(topics.length > 0 ? { topics } : {}),
+    };
+}
+function invalidSharePostResult(message) {
+    return { invalidMessage: message };
+}
+async function isMiniProgramShareDevelopmentRuntime(platformAdapter) {
+    try {
+        if (isMiniProgramDevShellHref(platformAdapter.app.getCurrentHref())) {
+            return true;
+        }
+    }
+    catch {
+        // 环境读取失败时继续使用宿主的显式开发态判断。
+    }
+    try {
+        return Boolean(await platformAdapter.app.isDevRuntime?.());
+    }
+    catch {
+        return false;
+    }
+}
+
 /** 截图并唤起分享。 */
 function shareMiniProgramRuntimeScreenshot(payload, platformAdapter) {
     const options = readMiniProgramScreenshotOptions(payload);
     const rect = options.rect || getMiniProgramRuntimeViewportRect(platformAdapter);
-    return platformAdapter.share.shareScreenshot({
+    const postResult = readMiniProgramRuntimeSharePostOptions(payload && typeof payload === 'object' ? payload.post : undefined, { method: 'share.screenshot' });
+    return handleMiniProgramRuntimeSharePostValidation(postResult, platformAdapter, (post) => platformAdapter.share.shareScreenshot({
         rect,
         delay: options.delay,
         saveToAlbum: options.saveToAlbum,
-    });
+        post,
+    }));
 }
 function readMiniProgramScreenshotOptions(payload) {
     if (payload === undefined || payload === null) {
@@ -4288,7 +4423,17 @@ function readScreenshotRect(value) {
 
 /** 展示基础分享面板。 */
 function showMiniProgramRuntimeShareMenu(payload, platformAdapter, context = {}) {
-    return platformAdapter.share.showShareMenu(readMiniProgramShareMenuOptions(payload, platformAdapter, context));
+    const options = readMiniProgramShareMenuOptions(payload, platformAdapter, context);
+    let postResult = readMiniProgramRuntimeSharePostOptions(payload.post, {
+        maxTopicIds: 1,
+        method: 'share.showShareMenu',
+    });
+    if (options.channel && postResult.post) {
+        postResult = {
+            invalidMessage: postResult.invalidMessage || 'share.showShareMenu channel 与 post 不能同时使用',
+        };
+    }
+    return handleMiniProgramRuntimeSharePostValidation(postResult, platformAdapter, (post) => platformAdapter.share.showShareMenu({ ...options, post }));
 }
 function readMiniProgramShareMenuOptions(payload, platformAdapter, context) {
     assertMiniProgramRuntimeRecord(payload, 'share.showShareMenu 参数必须是对象');
@@ -5201,6 +5346,7 @@ function createBrowserMockRuntimePlatformAdapter(options) {
     return {
         app: {
             getCurrentHref: options.getCurrentHref,
+            isDevRuntime: () => true,
         },
         launch: {
             async getMiniProgramInfo() {

package/dist/index.cjs.js

@@ -325,7 +325,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.6-alpha.1';
+    : '0.6.6-alpha.3';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/index.esm.js

@@ -321,7 +321,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.6-alpha.1';
+    : '0.6.6-alpha.3';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -20,8 +20,8 @@ npm run deploy
 ## 开发模式
 
 - `npm run dev`：打开本地调试页，可以使用浏览器 Mock，也可以在 Mac 版 APP 或手机小黑盒 APP 中验收。手机和电脑需要处于同一局域网。
-- `npm run build`：先执行 TypeScript 检查，再构建生产产物。
-- `npm run deploy -- --release-note "..."`：检查、构建、上传并提交审核。首次提交前先运行 `npx hb-sdk login`，再用 `npx hb-sdk remote create` 创建小程序，或用 `npx hb-sdk remote bind <mini-program-id>` 绑定已有小程序。审核通过后，用 `hb-sdk remote release <version>` 发布。
+- `npm run build`：先执行 TypeScript 检查，再通过 `hb-sdk build` 构建生产产物。
+- `npm run deploy -- --release-note "..."`：检查、执行项目的 `scripts.build`、上传并提交审核。首次提交前先运行 `npx hb-sdk login`，再用 `npx hb-sdk remote create` 创建小程序，或用 `npx hb-sdk remote bind <mini-program-id>` 绑定已有小程序。审核通过后，用 `hb-sdk remote release <version>` 发布。
 
 ## 更多能力
 

package/dist/templates/vue3-vite-ts/package.json.ejs

@@ -10,7 +10,7 @@
     "hb-sdk": "hb-sdk",
     "dev": "hb-sdk dev",
     "deploy": "hb-sdk remote deploy",
-    "build": "vue-tsc --noEmit && vite build",
+    "build": "vue-tsc --noEmit && hb-sdk build",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",
     "test:unit": "vitest run",

package/dist/vite.cjs.js

@@ -7,7 +7,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.6-alpha.1';
+    : '0.6.6-alpha.3';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.6-alpha.1';
+    : '0.6.6-alpha.3';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.6-alpha.1",
+  "version": "0.6.6-alpha.3",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",

package/skill/SKILL.md

@@ -11,7 +11,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 
 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, browser Mock, device debugging, CLI login, Agent Skill diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
+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.
@@ -21,7 +21,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 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, local debugging, device debugging, CLI login, Agent Skill doctor, and update reminders, read `references/cli.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`.
@@ -45,30 +45,35 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 5. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
 6. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
 7. Use the default SDK instance exposed by the root package.
+8. 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 login`, `hb-sdk login status`, and `hb-sdk login clear` only for development and publishing commands. This login does not change the mini-program user's login state.
-5. 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.
-6. 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.
-7. 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.
-8. Use `hb-sdk remote deploy --release-note <text>` to check, build, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
-9. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
-10. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
-11. 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.
-12. Use `--json` for script consumption and `--verbose` only when concise output is insufficient for diagnosis.
-13. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
-14. Do not print or expose cookies, tokens, private headers, or other credentials.
+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 the mini-program user's login 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. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
+14. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
+15. 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.
+16. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
+17. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
+18. 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, post publishing, or upload-only flows.
+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.

package/skill/references/api-protocol.md

@@ -144,6 +144,7 @@ export type {
   MiniProgramScreenshotOptions,
   MiniProgramScreenshotRect,
   MiniProgramShareChannel,
+  MiniProgramSharePostOptions,
   MiniProgramShowShareMenuOptions,
 } from './modules/share';
 export type { GetStoragePayload, GetStorageResult, SetStoragePayload } from './modules/storage';
@@ -222,7 +223,7 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 3 | 66 | 57 | 0 |
-| Protocol API | 0 | 3 | 43 | 67 | 32 |
+| Root API | 2 | 3 | 67 | 57 | 0 |
+| Protocol API | 0 | 3 | 44 | 67 | 32 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
 | Vite API | 0 | 1 | 0 | 0 | 0 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.6-alpha.1`
+- Version at generation time: `0.6.6-alpha.3`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -99,6 +99,7 @@ export type {
   MiniProgramScreenshotRect,
   MiniProgramShareChannel,
   MiniProgramShareModule,
+  MiniProgramSharePostOptions,
   MiniProgramShowShareMenuOptions,
   ScreenshotPayload,
   ScreenshotResult,
@@ -355,7 +356,7 @@ function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
 
 ## Manifest
 
-`@heybox/hb-sdk/vite` 提供构建时插件 `miniappManifest()`。Vite 项目完成 `vite build` 后，会在输出目录写入 `manifest.json`：
+`@heybox/hb-sdk/vite` 提供构建时插件 `miniappManifest()`。项目通过 `hb-sdk build` 完成生产构建后，会在固定的 `dist/` 中写入 `manifest.json`：
 
 ```json
 {
@@ -364,7 +365,7 @@ function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
 }
 ```
 
-`version` 来自小程序项目自身的 `package.json.version`，`sdkVersion` 来自当前安装 SDK 的构建版本且不能由业务覆盖。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
+`version` 来自小程序项目自身的 `package.json.version`，`sdkVersion` 来自当前安装 SDK 的构建版本且不能由业务覆盖。`hb-sdk build` 要求项目显式注册这个插件；`hb-sdk create` 生成的模板默认已注册，现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
 
 ```ts
 import { miniappManifest } from '@heybox/hb-sdk/vite';
@@ -382,13 +383,13 @@ export default defineConfig({
 
 插件只接受单页应用：输出目录只能存在入口 `index.html`。build 会用结构化 HTML parser 校验入口，并把平台 CSP 插入 `<head>` 首位；已有 CSP 会原样保留，两份策略按浏览器交集生效。正式策略禁止 `fetch`、XHR、WebSocket、EventSource、Beacon、Worker、iframe、表单和对象加载等浏览器原生出口；业务网络请求应使用 `network.request()`。dev 使用相同策略，只额外放行当前 Vite 的精确 HMR WebSocket 地址。
 
-meta refresh、外部 anchor、`dns-prefetch`、`preconnect`、`prerender`、外部资源 URL 和额外 HTML 会使 build 失败。内联 script/style 允许，但 `unsafe-eval` 不允许。`dev` 和手动 Vite build 不再请求远端最低 SDK 版本；构建仍会把当前 `sdkVersion` 写入 Manifest，`hb-sdk remote deploy` 仍校验 Manifest 结构并经过服务端 precheck / submit-audit 策略。
+meta refresh、外部 anchor、`dns-prefetch`、`preconnect`、`prerender`、外部资源 URL 和额外 HTML 会使 build 失败。内联 script/style 允许，但 `unsafe-eval` 不允许。`dev`、`hb-sdk build` 和手动 Vite build 都不请求远端最低 SDK 版本；构建仍会把当前 `sdkVersion` 写入 Manifest，`hb-sdk remote deploy` 仍校验 Manifest 结构并经过服务端 precheck / submit-audit 策略。
 
 失败与警告语义：
 
-- 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
-- `package.json.version` 不是非空字符串：`vite build` 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 直接失败，必须改成实际 SemVer。
+- 读取 `package.json` 失败或 JSON 解析失败：build 直接失败，并输出具体原因。
+- `package.json.version` 不是非空字符串：build 直接失败。
+- `package.json.version` 仍是模板默认值 `0.0.0`：build 直接失败，必须改成实际 SemVer。
 - 版本号不是严格 SemVer、包含 build metadata 或缺少 `sdkVersion`：build/deploy 直接失败。
 
 `manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
@@ -545,6 +546,10 @@ await share.showShareMenu({
   title: '我的小程序页面',
   desc: '来自黑盒小程序的分享',
   imageUrl: 'https://imgheybox.max-c.com/demo.png',
+  post: {
+    topicIds: [235709],
+    topics: ['无畏契约战绩'],
+  },
 });
 ```
 
@@ -552,15 +557,23 @@ await share.showShareMenu({
 `/tools/common_share?user_miniprogram_id=...` 分享落地页。只有确实要分享外部
 HTTP(S) 页面时才显式传 `url`。
 
+`post` 用于给“转发到社区”预置可编辑的分区与话题。`topicIds` 接受正整数或非空字符串并按首次出现顺序去重；`topics` 只传话题内容，不要包含首尾 `#`。`showShareMenu()` 只支持一个默认分区，并且不能与 `channel` 同时使用；本地 Mock、App Dev Shell 和开发 Runtime 会直接拒绝这类错误，生产 Runtime 会过滤非法项、只取第一个分区并继续普通分享。`post: null` 等同于不配置。
+
 截图分享：
 
 ```ts
 await share.screenshot({
   delay: 100,
   saveToAlbum: true,
+  post: {
+    topicIds: [235709, 66739],
+    topics: ['无畏契约战绩'],
+  },
 });
 ```
 
+截图分享支持多个预置分区；分区与话题仍由用户在客户端发帖页中确认和修改，SDK 不会直接发布内容。
+
 ### 基础 UI
 
 ```ts

package/skill/references/cli.md

@@ -8,6 +8,7 @@
 - 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
 
@@ -17,6 +18,7 @@
 - [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)
@@ -34,6 +36,7 @@ Use the bundled `hb-sdk` CLI to create a workshop mini-program, open the local d
 ```text
 hb-sdk create <project-name>
 hb-sdk dev [--port <port>] [--mock-port <port>] [--no-open]
+hb-sdk build [--env <name>] [--verbose]
 hb-sdk login
 hb-sdk login status
 hb-sdk login clear
@@ -139,6 +142,35 @@ Dev Context 中调整的 `network.request` 权限不会修改线上配置，但
 
 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.
 
+## Production build
+
+## 生产构建
+
+```bash
+hb-sdk build [--env <name>] [--verbose]
+```
+
+`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
+
+推荐由项目的 `scripts.build` 保留类型检查：
+
+```json
+{
+  "scripts": {
+    "build": "vue-tsc --noEmit && hb-sdk build"
+  }
+}
+```
+
+构建命令只支持 `--env` 和 `--verbose`。已有项目继续使用 `vite build` 仍然兼容，不会自动迁移。
+
+Agent rules:
+
+- Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry.
+- Require explicit `miniappManifest()` configuration and keep typechecking in the project's `scripts.build`.
+- Do not claim `hb-sdk build` needs login, binding, or network access, and do not invent unsupported build flags.
+- Existing `vite build` projects remain compatible and must not be auto-migrated.
+
 ## Deploy and publish
 
 ## 部署发布
@@ -158,7 +190,7 @@ hb-sdk remote bind mp_xxxxxxxx
 hb-sdk remote deploy --release-note "修复登录状态展示"
 ```
 
-这条命令会完成检查、构建、上传和提交审核。默认在审核通过后等待手动发布；普通低风险版本可以追加 `--auto-publish`。完整命令见 `hb-sdk remote --help`，提交要求见[小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)。
+这条命令会完成检查、执行项目的 `scripts.build`、上传和提交审核，因此项目定义的类型检查仍会执行。默认在审核通过后等待手动发布；普通低风险版本可以追加 `--auto-publish`。完整命令见 `hb-sdk remote --help`，提交要求见[小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)。
 
 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.
 

package/skill/references/recipes.md

@@ -9,6 +9,7 @@
 - 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
@@ -18,6 +19,7 @@
 - [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
 
@@ -355,6 +357,57 @@ async function handleSubmit() {
 - 用户主动点击登录、提交、收藏等动作时，再调用 `login`。
 - 登录态变化后，父容器应派发 `authChange`，页面可据此刷新用户相关 UI。
 
+## Community share recipe
+
+
+# 社区分享预置
+
+`share.showShareMenu()` 和 `share.screenshot()` 可以给客户端的“转发到社区”流程预置分区与话题。预置内容进入发帖页后仍可由用户修改，SDK 不会直接发布内容。
+
+## 普通分享
+
+普通分享只支持一个默认分区，并且配置 `post` 时不要同时指定站外 `channel`。
+
+```ts
+import { ready, share } from '@heybox/hb-sdk'
+
+await ready()
+
+await share.showShareMenu({
+  title: '本局战绩',
+  desc: '查看我的完整战绩',
+  post: {
+    topicIds: [235709],
+    topics: ['无畏契约战绩'],
+  },
+})
+```
+
+## 截图分享
+
+截图分享可以预置多个分区，客户端发帖页负责最终选择与确认。
+
+```ts
+await share.screenshot({
+  delay: 100,
+  saveToAlbum: true,
+  post: {
+    topicIds: [235709, 66739],
+    topics: ['无畏契约战绩'],
+  },
+})
+```
+
+## 参数边界
+
+- `topicIds` 接受正整数或非空字符串，按首次出现顺序去重。
+- `topics` 只传话题内容，不要添加首尾 `#`；字符串会先 trim 再去重。
+- `post: null` 等同于不配置社区发帖预置，`post: {}` 是无效配置。
+- 本地 Mock、App Dev Shell 和开发 Runtime 会对无效配置返回 `INVALID_PARAMS`。
+- 生产 Runtime 会过滤无效项；普通分享只使用第一个有效分区，配置冲突时保留站外 `channel`，不会阻断原分享流程。
+
+调用方不能通过该 API 传客户端协议、回调、自定义按钮或发布指令。
+
 ## Custom instance recipe
 
 

package/skill/references/safety-boundaries.md

@@ -23,7 +23,7 @@
 
 - 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, post publishing, custom buttons, or upload-only flows.
+- 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 pass host-only protocol fields through `network.request`.
 - Do not build raw `postMessage` bridge flows in iframe business code.