@open-dy/vibecoding-sdk-taro 0.0.1 → 0.1.0

package/src/adapters/interest-card/eslint/taro.mjs

@@ -1,54 +1,20 @@
 import { createMicroappTaroEslintConfig } from '../../../eslint/taro.mjs'
-import customNavigation from './eslint-plugin-custom-navigation.mjs'
-
-const interestCardRules = [
-  {
-    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: { customNavigation },
-    rules: {
-      'customNavigation/require-custom-navigation-style': 'error',
-      'customNavigation/pages-must-use-custom-nav-space': 'error',
-    },
-  },
-]
 
 /**
- * 兴趣卡 Taro 的通用校验加上业务域导航约束。
- *
- * 公共规则仍由 `createMicroappTaroEslintConfig` 维护；这里只声明兴趣卡
- * 独有的导航能力及其旧图标包来源，避免模板复制整份 ESLint 配置。
+ * 兴趣卡 Taro 复用公共导航与页面校验，保留本地 UI 和历史图标导入兼容。
+ * 规则实现统一由公共配置维护，模板只保留 SDK 调用入口。
  */
 export function createInterestCardTaroEslintConfig(options = {}) {
-  const { overrides, ...baseOptions } = options
-  const additionalLucideSources = baseOptions.lucideImportSources === undefined
+  const additionalLucideSources = options.lucideImportSources === undefined
     ? []
-    : Array.isArray(baseOptions.lucideImportSources)
-      ? baseOptions.lucideImportSources
-      : [baseOptions.lucideImportSources]
+    : Array.isArray(options.lucideImportSources)
+      ? options.lucideImportSources
+      : [options.lucideImportSources]
 
   return createMicroappTaroEslintConfig({
-    ...baseOptions,
-    lucideImportSources: ['lucide-taro', ...additionalLucideSources],
+    ...options,
+    lucideImportSources: ['@open-dy/lucide-taro', 'lucide-taro', ...additionalLucideSources],
     preferredUiImportBase: '@/components/ui',
-    overrides(config) {
-      const withInterestCardRules = [...config, ...interestCardRules]
-      if (!overrides) return withInterestCardRules
-      if (typeof overrides === 'function') {
-        return overrides(withInterestCardRules) ?? withInterestCardRules
-      }
-      return [
-        ...withInterestCardRules,
-        ...(Array.isArray(overrides) ? overrides : [overrides]),
-      ]
-    },
   })
 }
 

package/src/build/plugins/inject-feed-card-meta.ts

@@ -0,0 +1,172 @@
+import fs from 'fs';
+import path from 'path';
+
+type AppConfig = Record<string, any>;
+
+type InjectFeedCardMetaContext = {
+  appPath?: string;
+  paths?: {
+    appPath?: string;
+  };
+  modifyAppConfig: (
+    modifier: (payload: { appConfig: AppConfig }) => AppConfig,
+  ) => void;
+  modifyViteConfig?: (
+    modifier: (payload: { viteConfig: Record<string, any> }) => Record<string, any> | void,
+  ) => void;
+};
+
+const BG_MUSIC_URL_KEYS = [
+  'BgMusicUrl',
+  'BgmMusicUrl',
+  'bgMusicUrl',
+  'bg_music_url',
+  'BgMusicURL',
+];
+
+function resolveBgMusicUrl(card: unknown): string {
+  if (!card || typeof card !== 'object') {
+    return '';
+  }
+  for (const key of BG_MUSIC_URL_KEYS) {
+    const value = (card as Record<string, unknown>)[key];
+    if (typeof value === 'string' && value.startsWith('https://')) {
+      return value;
+    }
+  }
+  return '';
+}
+
+function pickBgmConfig(card: Record<string, any>): Record<string, unknown> {
+  const raw = card?.BgmConfig ?? card?.bgmConfig;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {};
+  }
+
+  const autoPlay = raw.auto_play ?? raw.AutoPlay;
+  const landingBehavior = raw.landing_behavior ?? raw.LandingBehavior;
+  const duckingVolume = raw.bgm_ducking_volume ?? raw.BgmDuckingVolume;
+  const config: Record<string, unknown> = {};
+
+  if (typeof autoPlay === 'boolean') {
+    config.auto_play = autoPlay;
+  }
+  if (typeof landingBehavior === 'string' && landingBehavior) {
+    config.landing_behavior = landingBehavior;
+  }
+  if (typeof duckingVolume === 'number' && Number.isFinite(duckingVolume)) {
+    config.bgm_ducking_volume = duckingVolume;
+  }
+
+  return config;
+}
+
+function buildBgmMeta(card: Record<string, any>) {
+  const bgm_url = resolveBgMusicUrl(card);
+  if (!bgm_url) {
+    return null;
+  }
+  return {
+    bgm_url,
+    ...pickBgmConfig(card),
+  };
+}
+
+function feedCardWatchCandidates(appPath: string): string[] {
+  return [
+    path.resolve(appPath, '..', 'feed', 'feed-card.json'),
+    path.resolve(appPath, 'feed', 'feed-card.json'),
+  ];
+}
+
+function findFeedCardJson(appPath: string): string | null {
+  return feedCardWatchCandidates(appPath).find((candidate) => fs.existsSync(candidate)) ?? null;
+}
+
+function stripInjectedBgm(appConfig: AppConfig): AppConfig {
+  if (!appConfig.meta || typeof appConfig.meta !== 'object' || Array.isArray(appConfig.meta)) {
+    return appConfig;
+  }
+  if (!('bgm' in appConfig.meta)) {
+    return appConfig;
+  }
+  const nextMeta = { ...appConfig.meta };
+  delete nextMeta.bgm;
+  if (Object.keys(nextMeta).length) {
+    appConfig.meta = nextMeta;
+  } else {
+    delete appConfig.meta;
+  }
+  return appConfig;
+}
+
+export function applyFeedCardMeta(appConfig: AppConfig, appPath: string): AppConfig {
+  const feedCardPath = findFeedCardJson(appPath);
+  if (!feedCardPath) {
+    return stripInjectedBgm(appConfig);
+  }
+
+  let card: Record<string, any>;
+  try {
+    card = JSON.parse(fs.readFileSync(feedCardPath, 'utf8'));
+  } catch {
+    return stripInjectedBgm(appConfig);
+  }
+
+  const bgm = buildBgmMeta(card);
+  if (!bgm) {
+    return stripInjectedBgm(appConfig);
+  }
+
+  const prevMeta =
+    appConfig.meta && typeof appConfig.meta === 'object' && !Array.isArray(appConfig.meta)
+      ? appConfig.meta
+      : {};
+  appConfig.meta = {
+    ...prevMeta,
+    bgm,
+  };
+  return appConfig;
+}
+
+function applyMetaToCompilerContext(compilerCtx: Record<string, any> | undefined, appPath: string) {
+  if (!compilerCtx?.app?.config) {
+    return;
+  }
+  applyFeedCardMeta(compilerCtx.app.config, appPath);
+}
+
+export default function injectFeedCardMetaPlugin(ctx: InjectFeedCardMetaContext) {
+  const resolveAppPath = () => ctx.paths?.appPath || ctx.appPath || process.cwd();
+
+  ctx.modifyAppConfig(({ appConfig }) => {
+    if (process.env.TARO_ENV === 'h5') {
+      return appConfig;
+    }
+    return applyFeedCardMeta(appConfig, resolveAppPath());
+  });
+
+  ctx.modifyViteConfig?.(({ viteConfig }) => {
+    if (process.env.TARO_ENV === 'h5') {
+      return viteConfig;
+    }
+    const appPath = resolveAppPath();
+    const watchFiles = feedCardWatchCandidates(appPath);
+    viteConfig.plugins = Array.isArray(viteConfig.plugins) ? viteConfig.plugins : [];
+    viteConfig.plugins.push({
+      name: 'watch-feed-card-meta',
+      async buildStart() {
+        if (this.meta.watchMode) {
+          watchFiles.forEach((file) => this.addWatchFile(file));
+        }
+        try {
+          const info = await (this as any).load({ id: 'taro:compiler' });
+          applyMetaToCompilerContext(info?.meta?.viteCompilerContext, appPath);
+        } catch {
+          // 拿不到 compiler context 时仍保留 modifyAppConfig 首轮注入。
+        }
+      },
+    });
+    return viteConfig;
+  });
+}

package/src/build/taro.ts

@@ -484,6 +484,7 @@ export function createMicroappTaroConfig(
         path.resolve(SDK_DIR, "plugins/app-config.cjs"),
         { previewBasePath }
       ],
+      [path.resolve(SDK_DIR, "plugins/inject-feed-card-meta.cjs"), {}],
       [
         "@tarojs/plugin-inject", // 注入抖音小程序的一些原生事件
         {

package/src/components/miniapp-open-card.ts

@@ -6,21 +6,53 @@ declare const tt: {
   getEnvInfoSync?: () => { microapp?: { envType?: string } }
 } | undefined
 
+/**
+ * @desc SDK 根据宿主环境选择的卡片版本；不是业务组件的可配置属性。
+ * @example const version: MiniappOpenCardEnvVersion = 'current'
+ * @ai-intent 描述 SDK 自动选择的内嵌卡环境版本。
+ * @ai-when 需要理解宿主环境与卡片版本的对应关系时。
+ * @ai-avoid 不要向 MiniappOpenCard 传入 envVersion 覆盖环境选择。
+ * @ai-example const version: MiniappOpenCardEnvVersion = 'current'
+ */
 export type MiniappOpenCardEnvVersion = 'current' | 'latest' | 'preview'
 
+/**
+ * @desc 内嵌卡加载错误的事件 detail；可选错误字段由平台提供。
+ * @example const detail: MiniappOpenCardErrorDetail = { errMsg: '卡片加载失败' }
+ * @ai-intent 识别内嵌卡加载失败的事件字段。
+ * @ai-when 宿主需要通过 onError 展示错误或记录诊断信息时。
+ * @ai-avoid 不要假设可选错误编号或类型一定存在。
+ * @ai-example const detail: MiniappOpenCardErrorDetail = { errMsg: '卡片加载失败' }
+ */
 export interface MiniappOpenCardErrorDetail {
+  /** @desc 平台返回的错误消息。 */
   errMsg: string
+  /** @desc 平台错误编号；平台未提供时省略。 */
   errNo?: number
+  /** @desc 平台错误码；平台未提供时省略。 */
   errorCode?: number
+  /** @desc 平台错误类型；平台未提供时省略。 */
   errorType?: string
 }
 
+/**
+ * @desc 普通 Taro 宿主的内嵌卡属性；沿用 StandardProps，但不接受 children 或 envVersion。
+ * @example const props: MiniappOpenCardProps = { appId: OPEN_CARD_ID, path: 'pages/index/index', initData: {} }
+ * @ai-intent 配置宿主实际承载的 OpenCard 页面。
+ * @ai-when 普通小程序或兴趣卡落地页需要渲染内嵌卡时。
+ * @ai-avoid 不要传小程序 APP_ID、未确认的页面路径或私域结果作为 initData。
+ * @ai-example const props: MiniappOpenCardProps = { appId: OPEN_CARD_ID, path: 'pages/index/index', initData: {} }
+ */
 export interface MiniappOpenCardProps extends Omit<StandardProps, 'children'> {
+  /** @desc 已确认的目标 OpenCard 标识；承载当前工程时使用非空 OPEN_CARD_ID，不使用小程序 APP_ID。 */
   appId: string
+  /** @desc 目标卡片的真实页面路径，例如 pages/index/index。 */
   path: string
   /** @desc 卡片初始化对象；省略时传空对象。禁止传 null、数组或 JSON 字符串。 */
   initData?: Record<string, unknown>
+  /** @desc 卡片加载成功时调用；event.detail 为空对象。 */
   onLoad?: BaseEventOrigFunction<Record<string, never>>
+  /** @desc 卡片加载失败时调用；读取 event.detail 中的错误消息与平台可选错误字段。 */
   onError?: BaseEventOrigFunction<MiniappOpenCardErrorDetail>
 }
 
@@ -28,7 +60,20 @@ export interface MiniappOpenCardProps extends Omit<StandardProps, 'children'> {
  * @desc 承载同一 OpenCard；SDK 选择环境版本并为空初始化参数提供对象，错误类型直接报错。
  * @params {MiniappOpenCardProps} props 卡片标识、页面路径和生命周期回调。
  * @return {React.ReactElement} 注入环境版本与初始化对象的原生卡片组件。
- * @example <MiniappOpenCard appId={OPEN_CARD_ID} path="pages/index/index" initData={{}} />
+ * @remarks development 使用 latest，preview 使用 preview，production、未知或无法读取的环境使用 current；业务不传 envVersion。
+ * initData 省略时 SDK 传入空对象，传 null、数组、字符串或其他非普通对象会抛出 TypeError；业务示例显式传 {}。
+ * 宿主只承载卡片。封闭域请求、数据处理与结果 UI 留在卡内，不通过 initData 或事件把私域结果交给宿主。
+ * @example
+ * ```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-intent 在普通 Taro 宿主中渲染已确认的 OpenCard 页面。
+ * @ai-when 用户要求内嵌卡，或宿主需要通过同一封闭域卡片呈现其结果时。
+ * @ai-avoid 不要手写原生标签、传 envVersion 或把卡内私域结果转移到宿主。
+ * @ai-example createElement(MiniappOpenCard, { appId: OPEN_CARD_ID, path: 'pages/index/index', initData: {} })
  */
 export function MiniappOpenCard(props: MiniappOpenCardProps) {
   const initData = props.initData === undefined ? {} : props.initData

package/src/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/src/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;
@@ -69,7 +70,7 @@ function createLucideColorCheckPlugin(importSources = ['@open-dy/lucide-taro'])
 const cssImportGuardPlugin = {
   processors: {
     css: {
-      preprocess(text) {
+      preprocess(text, filename) {
         const lines = text.replace(/\/\*[\s\S]*?\*\//g, comment => {
           if (comment.includes('eslint-')) return comment;
           return comment.replace(/[^\n]/g, ' ');
@@ -101,6 +102,18 @@ const cssImportGuardPlugin = {
           ].join(' ');
         });
 
+        // Scope this guard to the SDK-based host app; OpenCard has its own CSS pipeline.
+        if (filename.replaceAll('\\', '/').endsWith('/src/app.css')) {
+          const css = lines.join('\n');
+          const imports = [...css.matchAll(/@import\s+(?:url\(\s*)?['"]([^'"]+)['"]/g)]
+            .map(match => match[1]);
+          const usesSdkTheme = imports.some(value => /^@[^/]+\/vibecoding-sdk-taro\/ui\/tailwind\.css$/.test(value));
+          const hasUtilities = imports.some(value => ['weapp-tailwindcss', 'tailwindcss', 'tailwindcss/utilities.css', 'weapp-tailwindcss/utilities.css'].includes(value))
+            || /@tailwind\s+utilities\s*;/.test(css);
+          if (usesSdkTheme && !hasUtilities) {
+            virtualLines[0] = `${virtualLines[0] ?? ''} __cssMissingTailwindEntry();`;
+          }
+        }
         return [virtualLines.join('\n')];
       },
       postprocess(messages) {
@@ -249,6 +262,16 @@ function collectStaticStrings(node, result = []) {
 
 const tailwindEnforcementPlugin = {
   rules: {
+    'require-utilities-entry': {
+      create(context) {
+        return {
+          CallExpression(node) {
+            if (node.callee?.name !== '__cssMissingTailwindEntry') return;
+            context.report({ node, message: 'src/app.css 缺少 Tailwind 工具类入口。请保留模板的 @import "weapp-tailwindcss";；SDK ui/tailwind.css 只提供主题和组件扫描，不能替代此入口。' });
+          },
+        };
+      },
+    },
     'no-arbitrary-font-size': {
       create(context) {
         function reportArbitraryFontSize(node, className) {
@@ -440,15 +463,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',
@@ -508,6 +541,7 @@ export function createMicroappTaroEslintConfig(options = {}) {
     },
     processor: 'local/css',
     rules: {
+      'tailwind/require-utilities-entry': 'error',
       'no-undef': 'off',
       'tailwind/no-arbitrary-font-size': 'error',
       'no-restricted-syntax': ['error', ...baseRestrictedSyntaxRules],