@open-dy/vibecoding-cli 0.0.1-beta.1

package/src/validators/routes.cjs

@@ -0,0 +1,470 @@
+const fs = require('fs');
+const path = require('path');
+
+function validateRoutes(context, options = {}) {
+if (context.target !== 'taro') return;
+const ROOT = context.root;
+const routesDir = options.routesDir || '/tmp/routes';
+const CLIENT_FILE = path.join(routesDir, 'client-routes.json');
+const OPENCARD_CLIENT_FILE = path.join(routesDir, 'opencard-client-routes.json');
+const SERVER_FILE = path.join(routesDir, 'server-routes.json');
+const CLOSED_DOMAIN_SERVER_FILE = path.join(routesDir, 'closed-domain-server-routes.json');
+const FEED_CARD_SCHEMA_FILE = path.join(ROOT, 'feed/feed-card.json');
+const CARD_ROUTING_CONFIG_FILE = path.join(ROOT, 'config/card-routing.json');
+const OPENCARD_DIR = path.join(ROOT, 'opencard');
+const CLOSED_DOMAIN_SERVER_DIR = path.join(ROOT, 'closed-domain-server');
+const OPEN_DOMAIN_SERVER_SRC_DIR = path.join(ROOT, 'server', 'src');
+const OPENAPI_MODULE = '@open-dy/ai_coding_sdk/openapi';
+const CLOSED_DOMAIN_OPENAPI_METHODS = new Set([
+  'getUserConstellation',
+  'getUserInterest',
+  'getUserBasicData',
+  'getUserFollowing',
+  'getAIUserProfile',
+  'getAIUserDataInfo',
+  'getAIUserItemList',
+]);
+const SERVER_SOURCE_EXTENSIONS = new Set([
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+  '.mts',
+  '.cts',
+]);
+
+function loadJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`文件不存在: ${filePath}`);
+    console.error('请确保前端和服务端都已经至少构建过一次。');
+    throw new Error('前后端路由一致性检测失败');
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function withRouteSourceTag(routes, sourceLabel) {
+  return routes.map((route) => ({
+    ...route,
+    file: `${sourceLabel}/${route.file}`,
+  }));
+}
+
+function loadClientRoutes() {
+  const clientRoutes = withRouteSourceTag(loadJson(CLIENT_FILE), '主应用');
+  if (!fs.existsSync(OPENCARD_DIR)) {
+    return clientRoutes;
+  }
+
+  return clientRoutes.concat(
+    withRouteSourceTag(loadJson(OPENCARD_CLIENT_FILE), 'opencard'),
+  );
+}
+
+function normalizeUrl(url) {
+  return '/' + url.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function isStaticUrl(url) {
+  return !url.includes('${') && !url.includes('<dynamic>');
+}
+
+function matchRoute(clientUrl, serverRoutes) {
+  const normalized = normalizeUrl(clientUrl);
+
+  return serverRoutes.find((route) => {
+    const routePath = normalizeUrl(String(route.path));
+    if (normalized === routePath) return true;
+
+    const routeParts = routePath.split('/');
+    const clientParts = normalized.split('/');
+    if (routeParts.length !== clientParts.length) return false;
+
+    return routeParts.every((part, i) => part.startsWith(':') || part === clientParts[i]);
+  });
+}
+
+function loadCardRoutingConfig() {
+  if (!fs.existsSync(CARD_ROUTING_CONFIG_FILE)) {
+    console.warn(`未找到 ${CARD_ROUTING_CONFIG_FILE}，按历史项目兼容逻辑默认检查开放域服务。`);
+    return null;
+  }
+
+  const config = loadJson(CARD_ROUTING_CONFIG_FILE);
+  const cardData = config?.cardData;
+  if (config?.version !== 1 || cardData?.path !== '/api/dy_card/data') {
+    console.error(`卡片路由配置非法: ${CARD_ROUTING_CONFIG_FILE}`);
+    throw new Error('前后端路由一致性检测失败');
+  }
+
+  if (
+    cardData.routes !== undefined &&
+    (!Array.isArray(cardData.routes) ||
+      cardData.routes.some(
+        (route) => typeof route !== 'string' || !route.trim(),
+      ))
+  ) {
+    console.error(`卡片路由配置非法: ${CARD_ROUTING_CONFIG_FILE} 的 cardData.routes 必须是非空字符串数组`);
+    throw new Error('前后端路由一致性检测失败');
+  }
+
+  const routes = Array.isArray(cardData.routes)
+    ? cardData.routes.map((route) => normalizeUrl(route))
+    : [];
+  if (!routes.includes(cardData.path)) {
+    routes.unshift(cardData.path);
+  }
+
+  return {
+    ...config,
+    cardData: {
+      ...cardData,
+      routes,
+    },
+  };
+}
+
+function loadCardDataServerRoutes(openDomainServerRoutes, cardRoutingConfig) {
+  if (!cardRoutingConfig) {
+    return openDomainServerRoutes;
+  }
+
+  const cardData = cardRoutingConfig.cardData;
+  switch (cardData.serviceDomain) {
+    case 'open':
+      return openDomainServerRoutes;
+    case 'closed':
+      if (!fs.existsSync(path.join(CLOSED_DOMAIN_SERVER_DIR, 'package.json'))) {
+        console.error(`card-routing.json 声明 cardData.serviceDomain=closed，但 ${CLOSED_DOMAIN_SERVER_DIR}/package.json 不存在。`);
+        throw new Error('前后端路由一致性检测失败');
+      }
+      return loadClosedDomainServerRoutes(true);
+    case 'none':
+      return [];
+    default:
+      console.error(`卡片服务域非法: ${String(cardData.serviceDomain)}`);
+      throw new Error('前后端路由一致性检测失败');
+  }
+}
+
+function assertCardRoutesUseOneService(
+  cardRoutingConfig,
+  openDomainServerRoutes,
+  closedDomainServerRoutes,
+) {
+  if (!cardRoutingConfig || cardRoutingConfig.cardData.serviceDomain === 'none') {
+    return;
+  }
+
+  for (const cardRoute of cardRoutingConfig.cardData.routes) {
+    const openMatch = matchRoute(cardRoute, openDomainServerRoutes);
+    const closedMatch = matchRoute(cardRoute, closedDomainServerRoutes);
+    if (openMatch && closedMatch) {
+      console.error(
+        `卡片接口 ${cardRoute} 同时注册在开放域和封闭域；同一张异形卡只能选择一个服务域。`,
+      );
+      throw new Error('前后端路由一致性检测失败');
+    }
+
+    const selectedRoutes =
+      cardRoutingConfig.cardData.serviceDomain === 'closed'
+        ? closedDomainServerRoutes
+        : openDomainServerRoutes;
+    if (!matchRoute(cardRoute, selectedRoutes)) {
+      console.error(
+        `卡片接口 ${cardRoute} 未在 ${cardRoutingConfig.cardData.serviceDomain} 服务注册。`,
+      );
+      throw new Error('前后端路由一致性检测失败');
+    }
+  }
+}
+
+function loadClosedDomainServerRoutes(required = false) {
+  if (!fs.existsSync(path.join(CLOSED_DOMAIN_SERVER_DIR, 'package.json'))) {
+    if (required) {
+      console.error(`card-routing.json 声明封闭域服务，但 ${CLOSED_DOMAIN_SERVER_DIR}/package.json 不存在。`);
+      throw new Error('前后端路由一致性检测失败');
+    }
+    return [];
+  }
+  if (!fs.existsSync(CLOSED_DOMAIN_SERVER_FILE)) {
+    if (required) {
+      console.error(`封闭域服务已选择，但路由文件不存在: ${CLOSED_DOMAIN_SERVER_FILE}`);
+      console.error('请先构建 closed-domain-server，再执行 check-routes。');
+      throw new Error('前后端路由一致性检测失败');
+    }
+    return [];
+  }
+  return loadJson(CLOSED_DOMAIN_SERVER_FILE);
+}
+
+function isClosedDomainUrl(url) {
+  return normalizeUrl(url).startsWith('/api/closed_domain/');
+}
+
+function maskCommentsAndStrings(source, maskStrings) {
+  let result = '';
+  let state = 'code';
+  let quote = '';
+
+  for (let index = 0; index < source.length; index += 1) {
+    const current = source[index];
+    const next = source[index + 1];
+
+    if (state === 'line-comment') {
+      if (current === '\n') {
+        state = 'code';
+        result += '\n';
+      } else {
+        result += ' ';
+      }
+      continue;
+    }
+
+    if (state === 'block-comment') {
+      if (current === '*' && next === '/') {
+        result += '  ';
+        index += 1;
+        state = 'code';
+      } else {
+        result += current === '\n' ? '\n' : ' ';
+      }
+      continue;
+    }
+
+    if (state === 'string') {
+      if (current === '\\') {
+        result += maskStrings ? ' ' : current;
+        if (next !== undefined) {
+          result += maskStrings ? (next === '\n' ? '\n' : ' ') : next;
+          index += 1;
+        }
+      } else {
+        result += maskStrings ? (current === '\n' ? '\n' : ' ') : current;
+        if (current === quote) {
+          state = 'code';
+          quote = '';
+        }
+      }
+      continue;
+    }
+
+    if (current === '/' && next === '/') {
+      result += '  ';
+      index += 1;
+      state = 'line-comment';
+      continue;
+    }
+    if (current === '/' && next === '*') {
+      result += '  ';
+      index += 1;
+      state = 'block-comment';
+      continue;
+    }
+    if (current === "'" || current === '"' || current === '\u0060') {
+      state = 'string';
+      quote = current;
+      result += maskStrings ? ' ' : current;
+      continue;
+    }
+    result += current;
+  }
+
+  return result;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function isOpenAPIModule(moduleName) {
+  return moduleName === OPENAPI_MODULE || moduleName.startsWith(`${OPENAPI_MODULE}/`);
+}
+
+function closedDomainMethodFromSubpath(moduleName) {
+  if (!moduleName.startsWith(`${OPENAPI_MODULE}/`)) return null;
+  const method = moduleName.slice(OPENAPI_MODULE.length + 1).split('/').pop().replace(/\.[cm]?[jt]s$/, '');
+  return CLOSED_DOMAIN_OPENAPI_METHODS.has(method) ? method : null;
+}
+
+function bindingIsCalled(code, binding) {
+  return new RegExp(`\\b${escapeRegExp(binding)}\\s*(?:\\?\\.\\s*)?\\(`).test(code);
+}
+
+function namespaceMethodIsCalled(code, namespace, method) {
+  return new RegExp(
+    `\\b${escapeRegExp(namespace)}\\s*(?:\\?\\.|\\.)\\s*${escapeRegExp(method)}\\s*(?:\\?\\.\\s*)?\\(`,
+  ).test(code);
+}
+
+function parseNamedBindings(specifiers, aliasSeparator) {
+  return specifiers.split(',').map((specifier) => {
+    const normalized = specifier.trim().replace(/^type\s+/, '');
+    const parts = normalized.split(aliasSeparator).map((part) => part.trim());
+    return { imported: parts[0], local: parts[1] || parts[0] };
+  });
+}
+
+function findClosedDomainOpenAPICalls(source) {
+  const sourceWithoutComments = maskCommentsAndStrings(source, false);
+  const executableCode = maskCommentsAndStrings(source, true);
+  const methods = new Set();
+
+  const recordNamedBindings = (specifiers, aliasSeparator) => {
+    for (const { imported, local } of parseNamedBindings(specifiers, aliasSeparator)) {
+      if (CLOSED_DOMAIN_OPENAPI_METHODS.has(imported) && bindingIsCalled(executableCode, local)) {
+        methods.add(imported);
+      }
+    }
+  };
+
+  const namedImportPattern = /\bimport\s*\{([\s\S]*?)\}\s*from\s*(['"])([^'"]+)\2/g;
+  for (const match of sourceWithoutComments.matchAll(namedImportPattern)) {
+    if (isOpenAPIModule(match[3])) recordNamedBindings(match[1], /\s+as\s+/);
+  }
+
+  const namespaceImportPattern = /\bimport\s*\*\s*as\s*([A-Za-z_$][\w$]*)\s*from\s*(['"])([^'"]+)\2/g;
+  for (const match of sourceWithoutComments.matchAll(namespaceImportPattern)) {
+    if (!isOpenAPIModule(match[3])) continue;
+    for (const method of CLOSED_DOMAIN_OPENAPI_METHODS) {
+      if (namespaceMethodIsCalled(executableCode, match[1], method)) methods.add(method);
+    }
+  }
+
+  const defaultImportPattern = /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*(['"])([^'"]+)\2/g;
+  for (const match of sourceWithoutComments.matchAll(defaultImportPattern)) {
+    const method = closedDomainMethodFromSubpath(match[3]);
+    if (method && bindingIsCalled(executableCode, match[1])) methods.add(method);
+  }
+
+  const namedRequirePattern = /\b(?:const|let|var)\s*\{([^}]+)\}\s*=\s*require\s*\(\s*(['"])([^'"]+)\2\s*\)/g;
+  for (const match of sourceWithoutComments.matchAll(namedRequirePattern)) {
+    if (isOpenAPIModule(match[3])) recordNamedBindings(match[1], /\s*:\s*/);
+  }
+
+  const namespaceRequirePattern = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\s*\(\s*(['"])([^'"]+)\2\s*\)/g;
+  for (const match of sourceWithoutComments.matchAll(namespaceRequirePattern)) {
+    if (!isOpenAPIModule(match[3])) continue;
+    const subpathMethod = closedDomainMethodFromSubpath(match[3]);
+    if (subpathMethod && bindingIsCalled(executableCode, match[1])) methods.add(subpathMethod);
+    for (const method of CLOSED_DOMAIN_OPENAPI_METHODS) {
+      if (namespaceMethodIsCalled(executableCode, match[1], method)) methods.add(method);
+    }
+  }
+
+  const directRequirePattern = /\brequire\s*\(\s*(['"])([^'"]+)\1\s*\)\s*(?:\?\.|\.)\s*([A-Za-z_$][\w$]*)\s*(?:\?\.\s*)?\(/g;
+  for (const match of sourceWithoutComments.matchAll(directRequirePattern)) {
+    if (isOpenAPIModule(match[2]) && CLOSED_DOMAIN_OPENAPI_METHODS.has(match[3])) {
+      methods.add(match[3]);
+    }
+  }
+
+  return Array.from(methods).sort();
+}
+
+function listServerSourceFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  const sourceFiles = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      sourceFiles.push(...listServerSourceFiles(entryPath));
+    } else if (entry.isFile() && SERVER_SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+      sourceFiles.push(entryPath);
+    }
+  }
+  return sourceFiles.sort();
+}
+
+function assertOpenDomainServerDoesNotCallClosedDomainOpenAPI() {
+  const violations = [];
+  for (const filePath of listServerSourceFiles(OPEN_DOMAIN_SERVER_SRC_DIR)) {
+    const source = fs.readFileSync(filePath, 'utf-8');
+    for (const method of findClosedDomainOpenAPICalls(source)) {
+      violations.push({ filePath, method });
+    }
+  }
+
+  if (violations.length === 0) return;
+
+  console.error('--- 开放域服务调用封闭域 OpenAPI 校验失败 ---\n');
+  console.error('以下封闭域高敏 OpenAPI 只能在 closed-domain-server/ 中调用：');
+  for (const violation of violations) {
+    console.error(`  ${path.relative(ROOT, violation.filePath)}: ${violation.method}()`);
+  }
+  throw new Error('前后端路由一致性检测失败');
+}
+
+function main() {
+  const clientRoutes = loadClientRoutes();
+  const openDomainServerRoutes = loadJson(SERVER_FILE);
+  const closedDomainServerRoutes = loadClosedDomainServerRoutes();
+  const cardRoutingConfig = loadCardRoutingConfig();
+
+  console.log('=== 前后端路由一致性检测报告 ===\n');
+
+  assertOpenDomainServerDoesNotCallClosedDomainOpenAPI();
+
+  // If feed-card.json exists, we require /api/dy_card/data to be present on server side.
+  // This is a hard requirement because the feed card renderer relies on this endpoint.
+  if (fs.existsSync(FEED_CARD_SCHEMA_FILE)) {
+    const requiredPath = '/api/dy_card/data';
+    const cardDataServerRoutes = loadCardDataServerRoutes(
+      openDomainServerRoutes,
+      cardRoutingConfig,
+    );
+    const matched = matchRoute(requiredPath, cardDataServerRoutes);
+    if (!matched) {
+      console.error('--- Feed 卡接口校验失败 ---\n');
+      console.error(`检测到 ${FEED_CARD_SCHEMA_FILE}，但服务端未注册必需接口：${requiredPath}`);
+      console.error('请在 card-routing.json 声明的服务域实现并注册该接口（通常为 Controller: @Controller(\'api\') + @All(\'dy_card/data\')）。');
+      throw new Error('前后端路由一致性检测失败');
+    }
+  }
+
+  assertCardRoutesUseOneService(
+    cardRoutingConfig,
+    openDomainServerRoutes,
+    closedDomainServerRoutes,
+  );
+
+  const configuredCardRoutes = cardRoutingConfig?.cardData?.routes || [];
+  const mismatched = [];
+  for (const cr of clientRoutes) {
+    if (cr.url.startsWith('http://') || cr.url.startsWith('https://') || !isStaticUrl(cr.url)) {
+      continue;
+    }
+
+    const isCardRoute = configuredCardRoutes.some((cardRoute) =>
+      matchRoute(cr.url, [{ path: cardRoute }]),
+    );
+    const serverRoutes = isCardRoute
+      ? loadCardDataServerRoutes(openDomainServerRoutes, cardRoutingConfig)
+      : isClosedDomainUrl(cr.url)
+        ? closedDomainServerRoutes
+        : openDomainServerRoutes;
+    if (matchRoute(cr.url, serverRoutes)) {
+      continue;
+    } else {
+      mismatched.push(cr);
+    }
+  }
+
+  console.log('--- 检测结果 ---\n');
+
+  if (mismatched.length > 0) {
+    console.error(`未匹配（${mismatched.length} 条）：以下前端请求路径未匹配到所选服务域的服务端路由，请检查前端请求路径、服务域配置，或确认服务端已注册对应路由`);
+    for (const r of mismatched) {
+      console.error(`  [${r.method}] ${r.url}  (来源: ${r.file})`);
+    }
+    throw new Error('前后端路由一致性检测失败');
+  } else {
+    console.log('所有前端静态请求路径均已在服务端注册对应路由，检测通过。');
+  }
+}
+
+return main();
+}
+
+module.exports = { validateRoutes };

package/src/validators/routes.mjs

@@ -0,0 +1,17 @@
+import validator from './routes.cjs'
+import { CliError } from '../core/errors.mjs'
+
+/**
+ * @desc 校验工程中声明的页面路由与源码入口是否一致。
+ * @params {object} context CLI 工程上下文。
+ * @params {object} options 路由校验选项。
+ * @return {unknown} 校验器返回的结果；发现错误时抛出 CliError。
+ * @example validateRoutes(context, { target: 'taro' })
+ */
+export function validateRoutes(context, options) {
+  try {
+    return validator.validateRoutes(context, options)
+  } catch (error) {
+    throw new CliError(error.message)
+  }
+}

package/src/validators/sql.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { CliError } from '../core/errors.mjs'
+
+const SOURCE_EXTENSIONS = /\.(?:cjs|cts|js|mjs|mts|ts)$/u
+const IGNORED_DIRECTORIES = new Set(['.git', 'node_modules', 'dist', 'build'])
+const UNSUPPORTED_PAGINATION = /\b(?:LIMIT|OFFSET)\s+\?/giu
+
+function sourceFiles(root) {
+  if (!root || !existsSync(root)) return []
+  const files = []
+  const visit = (directory) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) visit(path.join(directory, entry.name))
+        continue
+      }
+      if (SOURCE_EXTENSIONS.test(entry.name)) files.push(path.join(directory, entry.name))
+    }
+  }
+  visit(root)
+  return files
+}
+
+function lineNumber(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+export function findUnsupportedPagination(root) {
+  const findings = []
+  for (const file of sourceFiles(root)) {
+    const source = readFileSync(file, 'utf8')
+    for (const match of source.matchAll(UNSUPPORTED_PAGINATION)) {
+      findings.push({
+        file: path.relative(root, file),
+        line: lineNumber(source, match.index ?? 0),
+        match: match[0],
+      })
+    }
+  }
+  return findings
+}
+
+export function validateSqlQueries(roots) {
+  const normalizedRoots = (Array.isArray(roots) ? roots : [roots]).filter(Boolean)
+  const findings = normalizedRoots.flatMap((root) =>
+    findUnsupportedPagination(path.join(root, 'src')),
+  )
+  if (findings.length === 0) return findings
+
+  const details = findings.map(({ file, line, match }) => `${file}:${line} (${match})`).join('\n')
+  throw new CliError(
+    'SQL pagination placeholders are not supported by the project database proxy.\n' +
+      `${details}\n` +
+      'Validate the page size and offset as integers, then use fixed SQL or safe integer literals; keep user data parameterized.',
+  )
+}

package/src/validators/widget-shell.mjs

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+
+function listCssFiles(directory, files = []) {
+  if (!existsSync(directory)) return files
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name)
+    if (entry.isDirectory()) {
+      listCssFiles(target, files)
+    } else if (entry.name.endsWith('.css')) {
+      files.push(target)
+    }
+  }
+  return files
+}
+
+function rootRule(source) {
+  const match = /\.widget-root\s*\{([\s\S]*?)\}/m.exec(source)
+  return match?.[1] ?? ''
+}
+
+function hasDeclaration(css, property, value) {
+  const expression = new RegExp(
+    `${property.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:\\s*${value}`,
+    'i',
+  )
+  return expression.test(css)
+}
+
+function formatFinding(file, line, column, message) {
+  return `${file}:${line}:${column} ${message}`
+}
+
+export function validateWidgetShell(context) {
+  const root = context.target === 'opencard' ? context.root : context.opencardRoot
+  if (!root) return { skipped: true, findings: [] }
+
+  const pageFile = path.join(root, 'src/pages/index/index.tsx')
+  const sourceDirectory = path.join(root, 'src')
+  const findings = []
+  if (!existsSync(pageFile)) {
+    findings.push({
+      file: 'src/pages/index/index.tsx',
+      line: 1,
+      column: 1,
+      message: '缺少 OpenCard 页面入口。',
+    })
+  } else {
+    const page = readFileSync(pageFile, 'utf8')
+    if (!/<View\b[^>]*className\s*=\s*(?:"[^"]*\bwidget-root\b[^"]*"|'[^']*\bwidget-root\b[^']*')/m.test(page)) {
+      findings.push({
+        file: 'src/pages/index/index.tsx',
+        line: 1,
+        column: 1,
+        message: '页面根 View 必须使用 widget-root 作为固定 widget 底板。',
+      })
+    }
+  }
+
+  const cssFiles = listCssFiles(sourceDirectory)
+  const css = cssFiles.map((file) => readFileSync(file, 'utf8')).join('\n')
+  const shell = rootRule(css)
+  if (!shell) {
+    findings.push({
+      file: 'src/pages/index/index.css',
+      line: 1,
+      column: 1,
+      message: '缺少 .widget-root CSS。',
+    })
+  } else {
+    const checks = [
+      [/box-sizing\s*:\s*border-box/i, '底板必须使用 box-sizing: border-box。'],
+      [/display\s*:\s*flex/i, '底板必须使用 Flex 布局。'],
+      [/height\s*:\s*100%/i, '底板必须使用 height: 100%，不能使用 100vh。'],
+      [/background(?:-color)?\s*:\s*(?!transparent|none)[^;]+/i, '底板必须有非透明背景。'],
+      [/border\s*:\s*1px\s+(?:solid|dashed|dotted)\s+[^;]+/i, '底板必须有 1px 描边。'],
+      [/border-radius\s*:\s*(?:12px|var\(--[A-Za-z0-9_-]+\))/i, '底板四角必须使用 12px 圆角。'],
+    ]
+    for (const [expression, message] of checks) {
+      if (!expression.test(shell)) {
+        findings.push({
+          file: 'src/pages/index/index.css',
+          line: 1,
+          column: 1,
+          message,
+        })
+      }
+    }
+    if (hasDeclaration(shell, 'height', '100vh')) {
+      findings.push({
+        file: 'src/pages/index/index.css',
+        line: 1,
+        column: 1,
+        message: '固定 widget 禁止使用 height: 100vh。',
+      })
+    }
+  }
+
+  if (findings.length > 0) {
+    console.warn(`WARN: OpenCard widget 底板校验未通过（${findings.length}），不阻断构建`)
+    for (const finding of findings) {
+      console.warn(formatFinding(finding.file, finding.line, finding.column, finding.message))
+    }
+  }
+
+  return { skipped: false, findings }
+}