@open-dy/vibecoding-sdk-taro 0.0.1-beta.4 → 0.0.1-beta.6

package/dist/eslint/eslint-plugin-custom-navigation.mjs

@@ -0,0 +1,290 @@
+/**
+ * 强制小程序页面使用自定义导航栏：app config 必须声明 navigationStyle: 'custom'，
+ * page config 若声明 navigationStyle 也只能是 custom，每个页面必须显式声明导航前景色，
+ * 且每个页面入口必须接入顶部避让。
+ */
+import { createRequire } from 'node:module';
+
+const ts = createRequire(import.meta.url)('typescript');
+
+const CUSTOM = 'custom';
+const NAVIGATION_TEXT_STYLES = new Set(['black', 'white']);
+
+const CUSTOM_NAV_IMPORTS = new Set([
+  '@/components/custom-nav-space',
+  '@/hooks/use-custom-nav-layout',
+  '@/lib/custom-nav-layout',
+]);
+
+const FORBIDDEN_NAVIGATION_APIS = new Map([
+  ['setNavigationBarTitle', '禁止修改导航栏标题'],
+  ['setNavigationBarColor', '禁止修改导航栏颜色、前景色或状态栏样式'],
+  ['showNavigationBarLoading', '禁止显示导航栏 loading'],
+  ['hideNavigationBarLoading', '禁止隐藏导航栏 loading'],
+  ['hideHomeButton', '禁止隐藏左上角首页或 logo 按钮'],
+]);
+
+function getPropertyName(prop) {
+  if (!ts.isPropertyAssignment(prop)) return null;
+  if (ts.isIdentifier(prop.name)) return prop.name.text;
+  if (ts.isStringLiteral(prop.name)) return prop.name.text;
+  return null;
+}
+
+function getStringLiteral(node) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  return null;
+}
+
+function getStaticPropertyName(node) {
+  if (!node.computed && node.property.type === 'Identifier') {
+    return node.property.name;
+  }
+  if (
+    node.computed &&
+    node.property.type === 'Literal' &&
+    typeof node.property.value === 'string'
+  ) {
+    return node.property.value;
+  }
+  return null;
+}
+
+function getPropertyKeyName(node) {
+  if (!node.computed && node.key.type === 'Identifier') {
+    return node.key.name;
+  }
+  if (node.key.type === 'Literal' && typeof node.key.value === 'string') {
+    return node.key.value;
+  }
+  return null;
+}
+
+/**
+ * @returns {{ windowStyle: string | null, pageStyle: string | null, windowTextStyle: string | null, pageTextStyle: string | null, invalid: Array<{ kind: string, value: string | null }> } | null}
+ */
+function extractNavigationStyles(filePath, text) {
+  const sf = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  let result = null;
+
+  function fromObjectLiteral(obj) {
+    const out = {
+      windowStyle: null,
+      pageStyle: null,
+      windowTextStyle: null,
+      pageTextStyle: null,
+      invalid: [],
+    };
+
+    for (const prop of obj.properties) {
+      if (!ts.isPropertyAssignment(prop)) continue;
+      const key = getPropertyName(prop);
+
+      if (key === 'navigationStyle') {
+        const value = getStringLiteral(prop.initializer);
+        out.pageStyle = value;
+        if (value !== CUSTOM) {
+          out.invalid.push({ kind: 'page', value });
+        }
+      }
+
+      if (key === 'navigationBarTextStyle') {
+        out.pageTextStyle = getStringLiteral(prop.initializer);
+      }
+
+      if (key === 'window' && ts.isObjectLiteralExpression(prop.initializer)) {
+        for (const windowProp of prop.initializer.properties) {
+          if (!ts.isPropertyAssignment(windowProp)) continue;
+          const windowKey = getPropertyName(windowProp);
+          if (windowKey === 'navigationStyle') {
+            const value = getStringLiteral(windowProp.initializer);
+            out.windowStyle = value;
+            if (value !== CUSTOM) {
+              out.invalid.push({ kind: 'window', value });
+            }
+          }
+          if (windowKey === 'navigationBarTextStyle') {
+            out.windowTextStyle = getStringLiteral(windowProp.initializer);
+          }
+        }
+      }
+    }
+
+    return out;
+  }
+
+  function visit(node) {
+    if (result) return;
+    if (ts.isExportAssignment(node) && !node.isExportEquals && node.expression) {
+      const expr = node.expression;
+      if (
+        ts.isCallExpression(expr) &&
+        expr.arguments[0] &&
+        ts.isObjectLiteralExpression(expr.arguments[0])
+      ) {
+        result = fromObjectLiteral(expr.arguments[0]);
+      } else if (ts.isObjectLiteralExpression(expr)) {
+        result = fromObjectLiteral(expr);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return result;
+}
+
+const CONFIG_MESSAGE =
+  '小程序页面必须使用自定义导航栏：navigationStyle 只能是 "custom"，禁止改成 default 或其他值。' +
+  '页面顶部请用 <CustomNavSpace /> 或 useCustomNavLayout() 避让状态栏与胶囊。';
+
+const TEXT_STYLE_MESSAGE =
+  '请根据该页面首次进入时顶部区域的实际明暗，显式设置 navigationBarTextStyle：' +
+  '浅色顶部使用 "black"，深色顶部使用 "white"。';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const requireCustomNavigationStyle = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '强制自定义导航，并要求 app fallback 与每个页面显式声明导航前景色',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filePath = context.filename.replace(/\\/g, '/');
+    const isApp = filePath.endsWith('/src/app.config.ts') || filePath.endsWith('src/app.config.ts');
+    const isPageConfig = /\/src\/pages\/.+\.config\.ts$/.test(filePath);
+    if (!isApp && !isPageConfig) return {};
+
+    return {
+      Program(node) {
+        const sourceText = context.sourceCode.getText(node);
+        const parsed = extractNavigationStyles(filePath, sourceText);
+
+        if (!parsed) {
+          context.report({
+            node,
+            message: `无法解析 ${isApp ? 'defineAppConfig' : 'definePageConfig'}，请使用对象字面量声明。${CONFIG_MESSAGE}`,
+          });
+          return;
+        }
+
+        if (isApp && parsed.windowStyle !== CUSTOM) {
+          context.report({
+            node,
+            message:
+              `src/app.config.ts 的 window.navigationStyle 必须为 "custom"（当前：${parsed.windowStyle ?? '未设置'}）。${CONFIG_MESSAGE}`,
+          });
+        }
+
+        const textStyle = isApp ? parsed.windowTextStyle : parsed.pageTextStyle;
+        if (!NAVIGATION_TEXT_STYLES.has(textStyle)) {
+          context.report({
+            node,
+            message:
+              `${isApp ? 'src/app.config.ts 的 window' : '页面配置'}.navigationBarTextStyle ` +
+              `必须为 "black" 或 "white"（当前：${textStyle ?? '未设置'}）。${TEXT_STYLE_MESSAGE}`,
+          });
+        }
+
+        for (const item of parsed.invalid) {
+          if (isApp && item.kind === 'window') continue;
+          context.report({
+            node,
+            message:
+              `禁止将 ${item.kind === 'window' ? 'window.' : ''}navigationStyle 设为 ${JSON.stringify(item.value)}。${CONFIG_MESSAGE}`,
+          });
+        }
+      },
+    };
+  },
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const pagesMustUseCustomNavSpace = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '页面入口必须使用 CustomNavSpace 或 useCustomNavLayout 避让自定义导航栏区域',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filePath = context.filename.replace(/\\/g, '/');
+    if (!/\/src\/pages\/.+\/index\.[jt]sx$/.test(filePath)) return {};
+
+    let used = false;
+
+    return {
+      ImportDeclaration(node) {
+        if (typeof node.source.value === 'string' && CUSTOM_NAV_IMPORTS.has(node.source.value)) {
+          used = true;
+        }
+      },
+      'Program:exit'(node) {
+        if (used) return;
+        context.report({
+          node,
+          message:
+            '小程序页面必须 import <CustomNavSpace /> 或 useCustomNavLayout() 做顶部避让，' +
+            '禁止改回原生导航，也禁止只用固定 pt-* / safe-area 代替。',
+        });
+      },
+    };
+  },
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noNavigationControlApis = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '禁止小程序页面调用会修改宿主导航栏或左上角按钮的 API',
+    },
+    schema: [],
+  },
+  create(context) {
+    function report(node, apiName) {
+      const reason = FORBIDDEN_NAVIGATION_APIS.get(apiName);
+      if (!reason) return;
+
+      context.report({
+        node,
+        message:
+          `小程序页面禁止使用 ${apiName}：${reason}。` +
+          '导航栏和左上角按钮由宿主及自定义导航模板统一管理。',
+      });
+    }
+
+    return {
+      MemberExpression(node) {
+        report(node.property, getStaticPropertyName(node));
+      },
+      ImportSpecifier(node) {
+        const importedName = node.imported.type === 'Identifier'
+          ? node.imported.name
+          : node.imported.value;
+        report(node.imported, importedName);
+      },
+      Property(node) {
+        if (node.parent.type !== 'ObjectPattern') return;
+        report(node.key, getPropertyKeyName(node));
+      },
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier') return;
+        report(node.callee, node.callee.name);
+      },
+    };
+  },
+};
+
+export default {
+  rules: {
+    'require-custom-navigation-style': requireCustomNavigationStyle,
+    'pages-must-use-custom-nav-space': pagesMustUseCustomNavSpace,
+    'no-navigation-control-apis': noNavigationControlApis,
+  },
+};

package/dist/eslint/taro.mjs

@@ -6,6 +6,7 @@ import reactHooksPlugin from 'eslint-plugin-react-hooks';
 import importPlugin from 'eslint-plugin-import';
 import globals from 'globals';
 import microappPages from './eslint-plugin-microapp-pages.mjs';
+import customNavigation from './eslint-plugin-custom-navigation.mjs';
 
 const REMOTE_CSS_IMPORT_PATTERN =
   /@import\s+(?:url\(\s*['"]?((?:https?:)?\/\/[^'")\s]+)['"]?\s*\)|['"]((?:https?:)?\/\/[^'"\s]+)['"])/g;
@@ -440,15 +441,25 @@ export function createMicroappTaroEslintConfig(options = {}) {
       'tailwindcss/no-custom-classname': 'off',
     },
   },
+  {
+    files: ['src/**/*.{js,jsx,ts,tsx}'],
+    plugins: { customNavigation },
+    rules: {
+      'customNavigation/no-navigation-control-apis': 'error',
+    },
+  },
   {
     files: ['src/**/*.{js,jsx,ts,tsx}'],
     ignores: ['src/network.ts'],
     plugins: {
       lucide: lucideColorCheckPlugin,
       microappPages,
+      customNavigation,
       tailwind: tailwindEnforcementPlugin,
     },
     rules: {
+      'customNavigation/require-custom-navigation-style': 'error',
+      'customNavigation/pages-must-use-custom-nav-space': 'error',
       'microappPages/nav-url-in-app-pages': 'error',
       // 'microappPages/page-dirs-in-app-pages': 'error',
       'microappPages/declared-pages-must-exist': 'error',

package/dist/reference/llms.txt

@@ -1,36 +1,78 @@
-# SDK API index
-
-> Generated from structured public SDK contracts and AI-facing JSDoc tags. Read `sdk-api.md` for the entry index, `sdk-api/<subpath>/<API>.md` for a focused API page, and `sdk-api.json` for machine-readable contracts.
-
-## Entry points
-- `@open-dy/vibecoding-sdk-taro` — 根入口：类型与聚合导出。
-- `@open-dy/vibecoding-sdk-taro/runtime` — SDK 公开 API。 ([docs](./sdk-api/runtime/index.md))
-- `@open-dy/vibecoding-sdk-taro/interest-card/runtime/microapp` — 兴趣卡普通小程序适配器，复用 runtime 入口。 ([docs](./sdk-api/runtime/index.md))
-- `@open-dy/vibecoding-sdk-taro/interest-card/eslint/taro` — 公开导出入口。
-- `@open-dy/vibecoding-sdk-taro/interest-card/types/taro` — 公开导出入口。
-- `@open-dy/vibecoding-sdk-taro/ui` — React UI 组件入口。
-- `@open-dy/vibecoding-sdk-taro/ui/*` — React UI 组件入口。
-- `@open-dy/vibecoding-sdk-taro/ui/theme.css` — UI 样式资源入口。
-- `@open-dy/vibecoding-sdk-taro/ui/tailwind.css` — UI 样式资源入口。
-- `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card` — 公开导出入口。
-- `@open-dy/vibecoding-sdk-taro/build/taro` — SDK 公开 API。 ([docs](./sdk-api/build/taro/index.md))
-- `@open-dy/vibecoding-sdk-taro/types/taro` — 平台类型声明入口。
-- `@open-dy/vibecoding-sdk-taro/reference/sdk-api.md` — 已生成的机器可读或 Markdown 参考文档。
-- `@open-dy/vibecoding-sdk-taro/reference/sdk-api.json` — 已生成的机器可读或 Markdown 参考文档。
-- `@open-dy/vibecoding-sdk-taro/reference/llms.txt` — 已生成的机器可读或 Markdown 参考文档。
-- `@open-dy/vibecoding-sdk-taro/reference/sdk-api/*` — 已生成的机器可读或 Markdown 参考文档。
-- `@open-dy/vibecoding-sdk-taro/eslint/taro` — 场景化 ESLint 配置入口。
-- `@open-dy/vibecoding-sdk-taro/eslint/server` — 场景化 ESLint 配置入口。
-- `@open-dy/vibecoding-sdk-taro/build` — 构建能力聚合入口；详细契约见 build/taro 和 build/opencard。 ([docs](./sdk-api/build/taro/index.md))
+# @open-dy/vibecoding-sdk-taro
+
+> API documentation for @open-dy/vibecoding-sdk-taro, covering runtime APIs, build configuration and component contracts.
+
+Start with the SDK overview, then follow the relevant API or module link. Import paths and types are documented on the linked pages.
+
+Companion libraries are separate project dependencies, imported from their own package names.
+
+## Documentation
+
+- [SDK overview](./sdk-api.md): Complete public entry points and documentation directory.
+- [API manifest](./sdk-api.json): Machine-readable signatures, parameters, return values and usage constraints.
 
 ## APIs
-- [createMicroappClient](./sdk-api/runtime/createMicroappClient.md) — 创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。
-  Import: `@open-dy/vibecoding-sdk-taro/runtime`
-- [CreateMicroappClientOptions](./sdk-api/runtime/CreateMicroappClientOptions.md) — 配置普通小程序 Network 的平台渠道。
-  Import: `@open-dy/vibecoding-sdk-taro/runtime`
-- [BuildContext](./sdk-api/build/taro/BuildContext.md) — Taro 构建阶段共享的编译上下文。
-  Import: `@open-dy/vibecoding-sdk-taro/build/taro`
-- [CreateMicroappTaroConfigOptions](./sdk-api/build/taro/CreateMicroappTaroConfigOptions.md) — 创建普通小程序 Taro 配置的选项。
-  Import: `@open-dy/vibecoding-sdk-taro/build/taro`
-- [createMicroappTaroConfig](./sdk-api/build/taro/createMicroappTaroConfig.md) — 创建普通小程序的 Taro/Vite 构建配置。
-  Import: `@open-dy/vibecoding-sdk-taro/build/taro`
+
+- [createMicroappClient](./sdk-api/runtime/createMicroappClient.md): 创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
+- [CreateMicroappClientOptions](./sdk-api/runtime/CreateMicroappClientOptions.md): 配置普通小程序 Network 的平台渠道。 Import: `@open-dy/vibecoding-sdk-taro/runtime`.
+- [MiniappOpenCard](./sdk-api/components/miniapp-open-card/MiniappOpenCard.md): 承载同一 OpenCard；SDK 选择环境版本并为空初始化参数提供对象，错误类型直接报错。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.
+- [MiniappOpenCardProps](./sdk-api/components/miniapp-open-card/MiniappOpenCardProps.md): 普通 Taro 宿主的内嵌卡属性；沿用 StandardProps，但不接受 children 或 envVersion。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.
+- [MiniappOpenCardErrorDetail](./sdk-api/components/miniapp-open-card/MiniappOpenCardErrorDetail.md): 内嵌卡加载错误的事件 detail；可选错误字段由平台提供。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.
+- [MiniappOpenCardEnvVersion](./sdk-api/components/miniapp-open-card/MiniappOpenCardEnvVersion.md): SDK 根据宿主环境选择的卡片版本；不是业务组件的可配置属性。 Import: `@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`.
+- [BuildContext](./sdk-api/build/taro/BuildContext.md): Taro 构建阶段共享的编译上下文。 Import: `@open-dy/vibecoding-sdk-taro/build/taro`.
+- [CreateMicroappTaroConfigOptions](./sdk-api/build/taro/CreateMicroappTaroConfigOptions.md): 创建普通小程序 Taro 配置的选项。 Import: `@open-dy/vibecoding-sdk-taro/build/taro`.
+- [createMicroappTaroConfig](./sdk-api/build/taro/createMicroappTaroConfig.md): 创建普通小程序的 Taro/Vite 构建配置。 Import: `@open-dy/vibecoding-sdk-taro/build/taro`.
+
+## UI modules
+
+- [accordion](./sdk-api/ui/accordion/index.md): API reference for the accordion module; Taro only.
+- [alert-dialog](./sdk-api/ui/alert-dialog/index.md): API reference for the alert-dialog module; Taro only.
+- [alert](./sdk-api/ui/alert/index.md): API reference for the alert module; Taro only.
+- [aspect-ratio](./sdk-api/ui/aspect-ratio/index.md): API reference for the aspect-ratio module; Taro only.
+- [avatar](./sdk-api/ui/avatar/index.md): API reference for the avatar module; Taro only.
+- [badge](./sdk-api/ui/badge/index.md): API reference for the badge module; Taro only.
+- [button-group](./sdk-api/ui/button-group/index.md): API reference for the button-group module; Taro only.
+- [button](./sdk-api/ui/button/index.md): API reference for the button module; Taro only.
+- [calendar](./sdk-api/ui/calendar/index.md): API reference for the calendar module; Taro only.
+- [card](./sdk-api/ui/card/index.md): API reference for the card module; Taro only.
+- [carousel](./sdk-api/ui/carousel/index.md): API reference for the carousel module; Taro only.
+- [checkbox](./sdk-api/ui/checkbox/index.md): API reference for the checkbox module; Taro only.
+- [collapsible](./sdk-api/ui/collapsible/index.md): API reference for the collapsible module; Taro only.
+- [combobox](./sdk-api/ui/combobox/index.md): API reference for the combobox module; Taro only.
+- [dialog](./sdk-api/ui/dialog/index.md): API reference for the dialog module; Taro only.
+- [drawer](./sdk-api/ui/drawer/index.md): API reference for the drawer module; Taro only.
+- [dropdown-menu](./sdk-api/ui/dropdown-menu/index.md): API reference for the dropdown-menu module; Taro only.
+- [empty](./sdk-api/ui/empty/index.md): API reference for the empty module; Taro only.
+- [field](./sdk-api/ui/field/index.md): API reference for the field module; Taro only.
+- [helpers](./sdk-api/ui/helpers/index.md): API reference for the helpers module; Taro only.
+- [input-group](./sdk-api/ui/input-group/index.md): API reference for the input-group module; Taro only.
+- [input-otp](./sdk-api/ui/input-otp/index.md): API reference for the input-otp module; Taro only.
+- [input](./sdk-api/ui/input/index.md): API reference for the input module; Taro only.
+- [item](./sdk-api/ui/item/index.md): API reference for the item module; Taro only.
+- [label](./sdk-api/ui/label/index.md): API reference for the label module; Taro only.
+- [menubar](./sdk-api/ui/menubar/index.md): API reference for the menubar module; Taro only.
+- [navigation-menu](./sdk-api/ui/navigation-menu/index.md): API reference for the navigation-menu module; Taro only.
+- [pagination](./sdk-api/ui/pagination/index.md): API reference for the pagination module; Taro only.
+- [popover](./sdk-api/ui/popover/index.md): API reference for the popover module; Taro only.
+- [portal](./sdk-api/ui/portal/index.md): API reference for the portal module; Taro only.
+- [progress](./sdk-api/ui/progress/index.md): API reference for the progress module; Taro only.
+- [radio-group](./sdk-api/ui/radio-group/index.md): API reference for the radio-group module; Taro only.
+- [resizable](./sdk-api/ui/resizable/index.md): API reference for the resizable module; Taro only.
+- [scroll-area](./sdk-api/ui/scroll-area/index.md): API reference for the scroll-area module; Taro only.
+- [select](./sdk-api/ui/select/index.md): API reference for the select module; Taro only.
+- [separator](./sdk-api/ui/separator/index.md): API reference for the separator module; Taro only.
+- [sheet](./sdk-api/ui/sheet/index.md): API reference for the sheet module; Taro only.
+- [skeleton](./sdk-api/ui/skeleton/index.md): API reference for the skeleton module; Taro only.
+- [slider](./sdk-api/ui/slider/index.md): API reference for the slider module; Taro only.
+- [sonner](./sdk-api/ui/sonner/index.md): API reference for the sonner module; Taro only.
+- [spinner](./sdk-api/ui/spinner/index.md): API reference for the spinner module; Taro only.
+- [switch](./sdk-api/ui/switch/index.md): API reference for the switch module; Taro only.
+- [table](./sdk-api/ui/table/index.md): API reference for the table module; Taro only.
+- [tabs](./sdk-api/ui/tabs/index.md): API reference for the tabs module; Taro only.
+- [textarea](./sdk-api/ui/textarea/index.md): API reference for the textarea module; Taro only.
+- [toggle-group](./sdk-api/ui/toggle-group/index.md): API reference for the toggle-group module; Taro only.
+- [toggle](./sdk-api/ui/toggle/index.md): API reference for the toggle module; Taro only.
+
+## Companion libraries
+
+- [@open-dy/lucide-taro](./sdk-api/libraries/lucide-taro.md): Taro 图标组件、属性、Provider 和 TabBar PNG 工具；独立依赖，OpenCard 不使用。

package/dist/reference/sdk-api/build/taro/BuildContext.md

@@ -3,7 +3,7 @@
 <!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
 
 导入路径：`@open-dy/vibecoding-sdk-taro/build/taro`
-源码：`src/build/taro.ts`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/build/taro.ts`（仅补缺或排错时读取）。
 
 #### 说明
 
@@ -22,7 +22,12 @@ const context: BuildContext = { isH5: true, isTt: false, mode: 'development', pr
 | 意图 | 描述 SDK 构建插件收到的 Taro 编译上下文。 |
 | 适用时机 | 需要根据 H5、TT 或开发模式调整构建配置时。 |
 | 避免 | 不要在业务页面中手动伪造该上下文或修改构建产物。 |
-| 示例 | `{ isH5: true, isTt: false, mode: 'development', projectRoot }` |
+
+示例：
+
+```ts
+{ isH5: true, isTt: false, mode: 'development', projectRoot }
+```
 
 #### 声明
 

package/dist/reference/sdk-api/build/taro/CreateMicroappTaroConfigOptions.md

@@ -3,7 +3,7 @@
 <!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
 
 导入路径：`@open-dy/vibecoding-sdk-taro/build/taro`
-源码：`src/build/taro.ts`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/build/taro.ts`（仅补缺或排错时读取）。
 
 #### 说明
 
@@ -31,7 +31,6 @@ createMicroappTaroConfig({ projectRoot: process.cwd() })
 | 意图 | 配置普通小程序的 Taro/Vite 构建入口。 |
 | 适用时机 | 需要从项目构建脚本创建普通小程序配置时。 |
 | 避免 | 不要在业务代码中直接调用 Taro/Vite 内部构建 API。 |
-| 示例 | `createMicroappTaroConfig({ projectRoot: process.cwd() })` |
 
 #### 声明
 

package/dist/reference/sdk-api/build/taro/createMicroappTaroConfig.md

@@ -3,7 +3,7 @@
 <!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
 
 导入路径：`@open-dy/vibecoding-sdk-taro/build/taro`
-源码：`src/build/taro.ts`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/build/taro.ts`（仅补缺或排错时读取）。
 
 #### 说明
 
@@ -30,7 +30,6 @@ createMicroappTaroConfig({ projectRoot: process.cwd() })
 | 意图 | 创建普通小程序的 Taro/Vite 构建配置。 |
 | 适用时机 | 构建脚本需要加载普通小程序的 SDK 配置时。 |
 | 避免 | 不要在业务页面调用该构建工厂，也不要绕过 SDK 修改代理配置。 |
-| 示例 | `createMicroappTaroConfig({ projectRoot: process.cwd() })` |
 
 #### 声明
 

package/dist/reference/sdk-api/components/miniapp-open-card/MiniappOpenCard.md

@@ -0,0 +1,109 @@
+# MiniappOpenCard
+
+<!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
+
+导入路径：`@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/components/miniapp-open-card.ts`（仅补缺或排错时读取）。
+
+#### 说明
+
+承载同一 OpenCard；SDK 选择环境版本并为空初始化参数提供对象，错误类型直接报错。
+
+参数：
+
+| 名称 | 说明 |
+| --- | --- |
+| `props` | 卡片标识、页面路径和生命周期回调。 |
+
+返回：注入环境版本与初始化对象的原生卡片组件。
+
+备注：development 使用 latest，preview 使用 preview，production、未知或无法读取的环境使用 current；业务不传 envVersion。
+initData 省略时 SDK 传入空对象，传 null、数组、字符串或其他非普通对象会抛出 TypeError；业务示例显式传 {}。
+宿主只承载卡片。封闭域请求、数据处理与结果 UI 留在卡内，不通过 initData 或事件把私域结果交给宿主。
+
+示例：
+
+```tsx
+import { MiniappOpenCard } from '@open-dy/vibecoding-sdk-taro/components/miniapp-open-card'
+export function EmbeddedCard({ openCardId }: { openCardId: string }) {
+  return <MiniappOpenCard appId={openCardId} path="pages/index/index" initData={{}} onError={(event) => console.error(event.detail.errMsg)} />
+}
+```
+
+#### AI 使用约束
+
+| 规则 | 内容 |
+| --- | --- |
+| 意图 | 在普通 Taro 宿主中渲染已确认的 OpenCard 页面。 |
+| 适用时机 | 用户要求内嵌卡，或宿主需要通过同一封闭域卡片呈现其结果时。 |
+| 避免 | 不要手写原生标签、传 envVersion 或把卡内私域结果转移到宿主。 |
+
+示例：
+
+```ts
+createElement(MiniappOpenCard, { appId: OPEN_CARD_ID, path: 'pages/index/index', initData: {} })
+```
+
+#### 声明
+
+```ts
+function MiniappOpenCard(props: MiniappOpenCardProps);
+```
+
+### MiniappOpenCard 的类型契约
+
+#### 工厂签名
+
+```ts
+(props: MiniappOpenCardProps): React.ReactElement<MiniappOpenCardProps & { envVersion: MiniappOpenCardEnvVersion; }, string | React.JSXElementConstructor<any>>
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| props | `MiniappOpenCardProps` | 卡片标识、页面路径和生命周期回调。 |
+
+##### props 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| appId | `string` | 已确认的目标 OpenCard 标识；承载当前工程时使用非空 OPEN_CARD_ID，不使用小程序 APP_ID。 |
+| path | `string` | 目标卡片的真实页面路径，例如 pages/index/index。 |
+| initData? | `Record<string, unknown> \| undefined` | 卡片初始化对象；省略时传空对象。禁止传 null、数组或 JSON 字符串。 |
+| onLoad? | `BaseEventOrigFunction<Record<string, never>> \| undefined` | 卡片加载成功时调用；event.detail 为空对象。 |
+| onError? | `BaseEventOrigFunction<MiniappOpenCardErrorDetail> \| undefined` | 卡片加载失败时调用；读取 event.detail 中的错误消息与平台可选错误字段。 |
+| style? | `string \| React.CSSProperties \| undefined` | 组件的内联样式, 可以动态设置的内联样式 |
+| id? | `string \| undefined` | 组件的唯一标示, 保持整个页面唯一 |
+| className? | `string \| undefined` | 同 `class`，在 React/Preact 里一般使用 `className` 作为 `class` 的代称 |
+| key? | `string \| number \| undefined` | 如果列表中项目的位置会动态改变或者有新的项目添加到列表中， 需要使用 `wx:key` 来指定列表中项目的唯一的标识符。 |
+| hidden? | `boolean \| undefined` | 组件是否显示, 所有组件默认显示 |
+| animation? | `TaroGeneral.IAnyObject \| { actions: TaroGeneral.IAnyObject[]; } \| undefined` | 动画属性 |
+| ref? | `React.LegacyRef<any> \| undefined` | 引用 |
+| dangerouslySetInnerHTML? | `{ __html: string; } \| undefined` | 渲染 HTML |
+| compileMode? | `string \| boolean \| undefined` | 是否开启编译模式 或者 是否是编译模式的子渲染函数 |
+| harmonyDirection? | `"row" \| "column" \| "flex" \| undefined` | 自定义容器组件的方向 |
+| onTouchStart? | `((event: ITouchEvent) => void) \| undefined` | 手指触摸动作开始 |
+| onTouchMove? | `((event: ITouchEvent) => void) \| undefined` | 手指触摸后移动 |
+| onTouchCancel? | `((event: ITouchEvent) => void) \| undefined` | 手指触摸动作被打断，如来电提醒，弹窗 |
+| onTouchEnd? | `((event: ITouchEvent) => void) \| undefined` | 手指触摸动作结束 |
+| onClick? | `((event: ITouchEvent) => void) \| undefined` | 手指触摸后马上离开 |
+| onLongPress? | `((event: CommonEvent) => void) \| undefined` | 手指触摸后，超过350ms再离开，如果指定了事件回调函数并触发了这个事件，tap事件将不被触发 |
+| onLongClick? | `((event: CommonEvent) => void) \| undefined` | 手指触摸后，超过350ms再离开（推荐使用 longpress 事件代替） |
+| onTransitionEnd? | `((event: CommonEvent) => void) \| undefined` | 会在 WXSS transition 或 Taro.createAnimation 动画结束后触发 |
+| onAnimationStart? | `((event: CommonEvent) => void) \| undefined` | 会在一个 WXSS animation 动画开始时触发 |
+| onAnimationIteration? | `((event: CommonEvent) => void) \| undefined` | 会在一个 WXSS animation 一次迭代结束时触发 |
+| onAnimationEnd? | `((event: CommonEvent) => void) \| undefined` | 会在一个 WXSS animation 动画完成时触发 |
+| onTouchForceChange? | `((event: CommonEvent) => void) \| undefined` | 在支持 3D Touch 的 iPhone 设备，重按时会触发 |
+
+#### 返回值
+
+- 类型：`React.ReactElement<MiniappOpenCardProps & { envVersion: MiniappOpenCardEnvVersion; }, string | React.JSXElementConstructor<any>>`
+
+##### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| type | `string \| React.JSXElementConstructor<any>` |  |
+| props | `MiniappOpenCardProps & { envVersion: MiniappOpenCardEnvVersion; }` |  |
+| key | `string \| null` |  |

package/dist/reference/sdk-api/components/miniapp-open-card/MiniappOpenCardEnvVersion.md

@@ -0,0 +1,38 @@
+# MiniappOpenCardEnvVersion
+
+<!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
+
+导入路径：`@open-dy/vibecoding-sdk-taro/components/miniapp-open-card`
+源码：实际安装的 `@open-dy/vibecoding-sdk-taro` 包内 `src/components/miniapp-open-card.ts`（仅补缺或排错时读取）。
+
+#### 说明
+
+SDK 根据宿主环境选择的卡片版本；不是业务组件的可配置属性。
+
+示例：
+
+```ts
+const version: MiniappOpenCardEnvVersion = 'current'
+```
+
+#### AI 使用约束
+
+| 规则 | 内容 |
+| --- | --- |
+| 意图 | 描述 SDK 自动选择的内嵌卡环境版本。 |
+| 适用时机 | 需要理解宿主环境与卡片版本的对应关系时。 |
+| 避免 | 不要向 MiniappOpenCard 传入 envVersion 覆盖环境选择。 |
+
+#### 声明
+
+```ts
+export type MiniappOpenCardEnvVersion = 'current' | 'latest' | 'preview';
+```
+
+### MiniappOpenCardEnvVersion 的类型契约
+
+#### 类型
+
+```ts
+MiniappOpenCardEnvVersion
+```