@open-dy/vibecoding-cli 0.1.11 → 0.1.12-beta.c4e0af5db5e03e294f48552f203ad42582c612347.0

package/README.md

@@ -59,3 +59,13 @@ CLI 对外命令和校验入口的 JSDoc 使用 `@desc`、`@params`、`@return`
 ## 准出测试
 
 在仓库根目录运行 `node release/verification/run-release-contracts.ts`，或在本包目录运行 `pnpm test:release`。该命令构建并验证 SDK、CLI 和隔离消费者；终端进度、JUnit 报告与 push CI 配置见 [packages/TESTING.md](../TESTING.md)。
+
+## 卡片形态
+
+`config/card-routing.json` 顶层的 `cardType` 支持 `interest` 和 `post`，不改变 `cardData.serviceDomain` 的含义。缺少文件或字段时沿用兴趣卡规范；显式空值、未知枚举和损坏的配置报错。解析器只读，普通续改不会补写作品标记。
+
+工程两端的 `eslint.config.mjs` 保持现有 SDK 配置工厂调用。CLI 从宿主目录读取配置，通过 ESLint 子进程环境 `VIBECODING_CARD_TYPE` 传递形态；直接执行 ESLint 时，SDK 根据待检查文件定位所属工程，OpenCard 使用宿主配置。解析器在 SDK 构建时内置，和 CLI 使用同一份源码，不依赖命令 cwd。CLI 在作品卡检查前要求配套 SDK 导出 `CARD_TYPE_RULES_VERSION = 1`；历史项目按 Skill 的 `upgrade-to-post.md` 接入，不能只安装依赖而保留未接通的旧入口。
+
+通用和兴趣卡专用 lint 均记录成功检查时的路由配置摘要。配置新增、修改或删除后，下一次检查强制全量执行；失败不会更新摘要。作品卡另用独立 ESLint 缓存标识，防止复用兴趣卡结果。两端沿用原命令和产物结构。
+
+OpenCard 构建同样通过 `VIBECODING_CARD_TYPE` 传递形态，SDK 和编译器在作品卡 `app.json` 中输出 `meta.cardType: "post"`，兴趣卡保持旧输出。开发预览监听形态与服务域变化并自动重启；非法或临时缺失配置保留当前会话。更新工具链依赖后需先重启开发入口，独立 `dev:tt` 的配置变更也需重启。正式 build／pack 每次重新读取配置，Turbo 缓存同时包含形态环境变量和宿主路由文件。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-dy/vibecoding-cli",
-  "version": "0.1.11",
+  "version": "0.1.12-beta.c4e0af5db5e03e294f48552f203ad42582c612347.0",
   "description": "Command orchestration, validation and packaging for Douyin vibecoding Taro and OpenCard projects.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
       "import": "./src/validators/feed-card.mjs",
       "require": "./src/validators/feed-card.cjs"
     },
-    "./adapters/interest-card/opencard/*": "./src/adapters/interest-card/opencard/*"
+    "./adapters/interest-card/opencard/*": "./src/adapters/interest-card/opencard/*",
+    "./config/card-profile": "./src/config/card-profile.mjs"
   },
   "files": [
     "bin",
@@ -42,8 +43,8 @@
     "ajv": "^8.18.0"
   },
   "peerDependencies": {
-    "@open-dy/vibecoding-sdk-taro": "0.1.7",
-    "@open-dy/vibecoding-sdk-opencard": "0.1.8"
+    "@open-dy/vibecoding-sdk-taro": "0.1.8-beta.c4e0af5db5e03e294f48552f203ad42582c612347.0",
+    "@open-dy/vibecoding-sdk-opencard": "0.1.9-beta.c4e0af5db5e03e294f48552f203ad42582c612347.0"
   },
   "peerDependenciesMeta": {
     "@open-dy/vibecoding-sdk-taro": {
@@ -59,7 +60,7 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "tag": "latest",
+    "tag": "beta-c4e0af5db5e03e294f48552f203ad42582c612347",
     "access": "public"
   }
 }

package/release-provenance.json

@@ -2,19 +2,19 @@
   "schema": 1,
   "producer": "vibecoding-cli",
   "packageName": "@open-dy/vibecoding-cli",
-  "version": "0.1.11",
+  "version": "0.1.12-beta.c4e0af5db5e03e294f48552f203ad42582c612347.0",
   "source": {
-    "digest": "sha256-350c9659fe7c3ca18a6ff7a8faee2cdc768a86a7daa51d36dcc682e462abafcd",
-    "files": 91
+    "digest": "sha256-34fcbffdaf45a69167b0389ffb22452a2a3e7b4a91aa7a33795ce592582ed11b",
+    "files": 96
   },
-  "payload": "sha256-f0ca57060dd5bd116d05017f9dd20770efb7a1314888dec470c5e5704d421298",
+  "payload": "sha256-f0b684e0efcaaad251fae46f54ec60f5b2f0fe04a78f726bdb842caeada52831",
   "toolchain": {
-    "node": "v22.22.3",
+    "node": "v22.22.0",
     "runtime": {
-      "node": "v22.22.3",
+      "node": "v22.22.0",
       "platform": "linux",
       "arch": "x64",
-      "environment": "sha256-d835dde975a8a25241996191388be38b0dc9c1e5aa8b518b778f4ccdf7a5136a"
+      "environment": "sha256-5b81e7cc338f03f0ff65566f99f994cca05b90cc836ff863506eed6afe9f5a24"
     },
     "packageManager": null
   }

package/src/adapters/interest-card/opencard/lint-lynx-css.mjs

@@ -4,6 +4,7 @@
  * 规则见 lynx-css-rules.mjs；inline style 由 eslint-plugin-opencard-taro 复用同一套规则。
  */
 import fs from 'node:fs';
+import { readCardProfile } from '../../../config/card-profile.mjs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -12,6 +13,7 @@ import {
   isTextContainerDeclaration,
   lintAtRule,
   lintDeclaration,
+  lintPostCardDeclaration,
   lintSelector,
   normalizeValue,
   toKebab,
@@ -309,7 +311,7 @@ function classesInCompound(compound) {
   return names;
 }
 
-export function lintCssText(source, { filename = 'input.css' } = {}) {
+export function lintCssText(source, { filename = 'input.css', cardType = 'interest' } = {}) {
   const allowRoot = isAppCss(filename);
   const findings = scanComments(source).errors.map(({ index, message }) => ({
     id: "css-comment", severity: "error", ...lineAt(source, index), message,
@@ -340,7 +342,7 @@ export function lintCssText(source, { filename = 'input.css' } = {}) {
     }
     if (node.type === 'decl') {
       if (currentRule) currentRule.decls.push(node);
-      for (const item of lintDeclaration(node.prop, node.value)) {
+      for (const item of [...lintDeclaration(node.prop, node.value), ...(cardType === 'post' ? lintPostCardDeclaration(node.prop, node.value) : [])]) {
         findings.push({
           ...item,
           line: node.line,
@@ -642,7 +644,7 @@ function lintHiddenTextParentUsage(rules, textParentClasses, filename, extraFind
 
 export function lintProject(
   srcDir = SRC,
-  { projectRoot = path.resolve(srcDir, '..') } = {},
+  { projectRoot = path.resolve(srcDir, '..'), cardType = 'interest' } = {},
 ) {
   const cssFiles = listFiles(srcDir, (name) => name.endsWith('.css'));
   const tsxFiles = listFiles(srcDir, (name) => /\.[jt]sx$/.test(name));
@@ -652,7 +654,7 @@ export function lintProject(
   const allRules = [];
   for (const file of cssFiles) {
     const filename = path.relative(projectRoot, file).replace(/\\/g, '/');
-    const { findings, rules } = lintCssText(fs.readFileSync(file, 'utf8'), { filename });
+    const { findings, rules } = lintCssText(fs.readFileSync(file, 'utf8'), { filename, cardType });
     for (const item of findings) reports.push({ ...item, file: filename });
     for (const rule of rules) allRules.push({ ...rule, file: filename });
   }
@@ -666,9 +668,9 @@ export function lintProject(
   return reports;
 }
 
-export function lintOpenCardProject(projectRoot) {
+export function lintOpenCardProject(projectRoot, { cardType = 'interest' } = {}) {
   const root = path.resolve(projectRoot);
-  return lintProject(path.join(root, 'src'), { projectRoot: root });
+  return lintProject(path.join(root, 'src'), { projectRoot: root, cardType });
 }
 
 function printReports(reports) {
@@ -907,7 +909,8 @@ export function main() {
     assertSelfTest();
     return;
   }
-  const reports = lintProject();
+  const { cardType } = readCardProfile({ projectRoot: path.dirname(ROOT) });
+  const reports = lintProject(SRC, { cardType });
   if (reports.length === 0) return;
   console.error(`ERROR: Lynx CSS lint 失败（${reports.length}）：机械禁写见 rendering.md，不要手工 grep。`);
   printReports(reports);

package/src/adapters/interest-card/opencard/lint.sh

@@ -7,6 +7,14 @@ ROOT="${1:?Missing project root}"
 shift
 cd "$ROOT"
 ADAPTER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROFILE_ENTRY="$ADAPTER_DIR/../../../config/card-lint.mjs"
+PROFILE="$(node "$PROFILE_ENTRY" prepare "$(dirname "$ROOT")" "$ROOT")"
+read -r CARD_TYPE FORCE_FULL PROFILE_SIGNATURE <<< "$PROFILE"
+export VIBECODING_CARD_TYPE="$CARD_TYPE"
+echo "[opencard lint] cardType=${CARD_TYPE}; config=$(dirname "$ROOT")/config/card-routing.json"
+[[ "$FORCE_FULL" != "1" ]] || LINT_INCREMENTAL=0
+ESLINT_CACHE="node_modules/.cache/eslint/opencard-src"
+[[ "$CARD_TYPE" != "post" ]] || ESLINT_CACHE="${ESLINT_CACHE}-post-v1"
 
 resolve_git_base() {
   local top
@@ -97,9 +105,9 @@ launch tsc tsc --noEmit
 
 if [[ "${RUN_ESLINT}" -eq 1 ]]; then
   if [[ "${#ESLINT_FILES[@]}" -gt 0 ]]; then
-    launch eslint eslint --cache --cache-location node_modules/.cache/eslint/opencard-src "${ESLINT_FILES[@]}"
+    launch eslint eslint --cache --cache-location "$ESLINT_CACHE" "${ESLINT_FILES[@]}"
   else
-    launch eslint eslint --cache --cache-location node_modules/.cache/eslint/opencard-src 'src/**/*.{js,jsx,ts,tsx}'
+    launch eslint eslint --cache --cache-location "$ESLINT_CACHE" 'src/**/*.{js,jsx,ts,tsx}'
   fi
 fi
 
@@ -129,3 +137,4 @@ if [[ "${FAILED}" -ne 0 ]]; then
   echo "[opencard lint] ERROR: lint 失败，需要修改后重新检测，直到通过为止" >&2
   exit 1
 fi
+node "$PROFILE_ENTRY" complete "$(dirname "$ROOT")" "$ROOT" "$PROFILE_SIGNATURE"

package/src/adapters/interest-card/opencard/lynx-css-rules.mjs

@@ -506,3 +506,12 @@ export function formatFinding(file, line, column, message) {
   const loc = column ? `${line}:${column}` : String(line);
   return `${file}:${loc}: ${message}`;
 }
+
+/** Restrict scrolling only for post cards; legacy rules remain unchanged. */
+export function lintPostCardDeclaration(property, value) {
+  const name = toKebab(property);
+  if (/^overflow(?:-[xy])?$/.test(name) && String(value).replace(/\s*!important\s*$/i, '').trim().split(/\s+/).some(token => /^(auto|scroll)$/i.test(token))) {
+    return [{ id: 'post-card-scroll', severity: 'error', message: '作品卡不支持滚动交互。请通过点击切换内容，不使用 overflow: auto / scroll。' }];
+  }
+  return [];
+}

package/src/build/opencard-environment.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs'
+import { parseCardType } from '../config/card-profile.mjs'
 import path from 'node:path'
 
 /** Locate host routing for standalone preview callers without a resolved CLI context. */
@@ -23,13 +24,13 @@ export function resolveCardRoutingPath(context) {
     : findRoutingPath(context.root)
 }
 
-export function readCardRouting(context) {
+export function readCardRouting(context, { allowMissing = true } = {}) {
   const file = resolveCardRoutingPath(context)
   let raw
   try {
     raw = fs.readFileSync(file, 'utf8')
   } catch (error) {
-    if (error.code === 'ENOENT') return {}
+    if (error.code === 'ENOENT' && allowMissing) return {}
     throw error
   }
   let routing
@@ -47,10 +48,15 @@ export function readCardRouting(context) {
   if (!['closed', 'open', 'none'].includes(serviceDomain)) {
     throw new Error(`${file} cardData.serviceDomain must be none, open, or closed; got ${JSON.stringify(serviceDomain)}。\n${guidance}`)
   }
+  parseCardType(routing, file)
   return routing
 }
 
 /** Pass to the compiler child only; never mutate the CLI process environment. */
-export function openCardBuildEnvironment(context) {
-  return { IS_CARD_CLOSED_DOMAIN: String(readCardRouting(context)?.cardData?.serviceDomain === 'closed') }
+export function openCardBuildEnvironment(context, options) {
+  const routing = readCardRouting(context, options)
+  return {
+    IS_CARD_CLOSED_DOMAIN: String(routing?.cardData?.serviceDomain === 'closed'),
+    VIBECODING_CARD_TYPE: parseCardType(routing, resolveCardRoutingPath(context)),
+  }
 }

package/src/build/turbo-config.mjs

@@ -7,10 +7,26 @@ const ARRAY_FIELDS = new Set(['env', 'inputs', 'outputs', 'dependsOn'])
 // These settings are part of the CLI contract. They are kept here, rather
 // than in generated projects, so all projects receive the same cache key and
 // closed-domain environment behavior as the CLI is upgraded.
+const PROJECT_BUILD_ENV = [
+  'APP_ID',
+  'OPEN_CARD_ID',
+  'DOUYIN_CLOUD_ENV_ID',
+  'DOUYIN_CLOUD_DEV_ENV_ID',
+  'DOUYIN_CLOUD_SERVICE_ID',
+  'AUDIT_DOUYIN_CLOUD_ENV_ID',
+  'AUDIT_DOUYIN_CLOUD_SERVICE_ID',
+  'DOUYIN_CLOUD_CLOSED_DOMAIN_SERVICE_ID',
+]
+
 const OPENCARD_DEFAULTS = {
   tasks: {
     'build:raw': {
-      env: ['IS_CARD_CLOSED_DOMAIN'],
+      env: [
+        'IS_CARD_CLOSED_DOMAIN',
+        'VIBECODING_CARD_TYPE',
+        ...PROJECT_BUILD_ENV,
+        'AUDIT_DOUYIN_CLOUD_CLOSED_DOMAIN_SERVICE_ID',
+      ],
       inputs: ['../config/card-routing.json'],
     },
   },
@@ -19,7 +35,7 @@ const OPENCARD_DEFAULTS = {
 const TARO_DEFAULTS = {
   tasks: {
     '//#build:tt:raw': {
-      env: ['IS_CARD_CLOSED_DOMAIN'],
+      env: ['IS_CARD_CLOSED_DOMAIN', 'VIBECODING_CARD_TYPE', ...PROJECT_BUILD_ENV],
       inputs: ['config/card-routing.json'],
     },
   },

package/src/cli.mjs

@@ -20,7 +20,7 @@ Commands:
   build                  Build the selected target
   lint                   Type-check, lint and validate source structure
   verify                 Run static and/or runtime verification
-  validate <name>        Run feed-card, routes, empty or opencard-structure
+  validate <name>        Run feed-card, feed-background, routes, empty or opencard-structure
   init-mysql-db          Initialize the Taro server database
   pack                   Build deployment archives
   docs                   Locate the selected project's installed SDK reference

package/src/commands/build.mjs

@@ -5,6 +5,7 @@ import { readEnvFile } from '../core/environment.mjs'
 import { resolveProjectBinary, resolveSdkTaroEntry, runProcess, runTasks } from '../core/runner.mjs'
 import { writeWebConfig } from '../core/web-config.mjs'
 import { validateRoutes } from '../validators/routes.mjs'
+import { validateImageInline } from '../validators/image-inline.mjs'
 
 function taroEnvironment(root, extra = {}) {
   const home = path.join(root, '.home')
@@ -101,6 +102,7 @@ export async function runBuild(context, options = {}) {
   }
   if (context.target === 'opencard') {
     await buildOpenCard(context, buildOptions)
+    if (!options.watch) validateImageInline(context)
     return
   }
 
@@ -138,4 +140,5 @@ export async function runBuild(context, options = {}) {
   }
   await runTasks(tasks, { label: 'build' })
   validateRoutes(context)
+  if (!options.watch) validateImageInline(context)
 }

package/src/commands/lint.mjs

@@ -7,12 +7,26 @@ import { validateNonEmptyTaro } from '../validators/empty-project.mjs'
 import { validateOpenCardStructure } from '../validators/opencard-structure.mjs'
 import { validateSqlQueries } from '../validators/sql.mjs'
 import { validateWidgetShell } from '../validators/widget-shell.mjs'
+import { prepareCardLint, ensureCardLintSupport } from '../config/card-lint.mjs'
 
 const globalConfigs = [
   'eslint.config.mjs', 'tsconfig.json', 'package.json', 'pnpm-lock.yaml',
   'opencard/eslint.config.mjs', 'opencard/tsconfig.json', 'opencard/package.json',
+  'config/card-routing.json',
 ]
 
+async function lintProfile(projectRoot, lintRoot) {
+  // A programmatic legacy caller may not supply a complete project.
+  if (!existsSync(path.join(projectRoot, 'package.json')) &&
+      !existsSync(path.join(projectRoot, 'config/card-routing.json'))) {
+    return { cardType: 'interest', full: false, complete() {} }
+  }
+  const profile = prepareCardLint({ projectRoot, lintRoot })
+  await ensureCardLintSupport({ projectRoot, lintRoot, cardType: profile.cardType })
+  console.log(`[lint] cardType=${profile.cardType}; config=${profile.configPath}`)
+  return profile
+}
+
 export async function changedFiles(root, patterns, capture = runCaptured) {
   try {
     const baseCandidates = ['origin/main', 'origin/master']
@@ -71,8 +85,8 @@ export function selectOpenCardEslintFiles(changed) {
   return { runEslint: files.length > 0, files }
 }
 
-export function runLynxCss(root, lintProject = lintOpenCardProject) {
-  const findings = lintProject(root)
+export function runLynxCss(root, lintProject = lintOpenCardProject, options = {}) {
+  const findings = lintProject(root, options)
   if (findings.length === 0) return
   const details = findings.map((finding) =>
     `${finding.file}:${finding.line}:${finding.column} ${finding.message}`,
@@ -85,16 +99,18 @@ export function runLynxCss(root, lintProject = lintOpenCardProject) {
 export async function lintOpenCard(context, options = {}) {
   const root = context.target === 'opencard' ? context.root : context.opencardRoot
   if (!root) return
+  const profile = await lintProfile(context.taroRoot ?? path.dirname(root), root)
   const projectRoot = context.taroRoot && existsSync(path.join(context.taroRoot, 'node_modules/.bin/tsc'))
     ? context.taroRoot
     : root
   const tsc = resolveProjectBinary(projectRoot, 'tsc')
   const eslint = resolveProjectBinary(projectRoot, 'eslint')
   mkdirSync(path.join(root, 'node_modules/.cache/eslint'), { recursive: true })
-  const eslintArgs = ['--cache', '--cache-location', 'node_modules/.cache/eslint/opencard-src']
+  const eslintArgs = ['--cache', '--cache-location', `node_modules/.cache/eslint/opencard-src${profile.cardType === 'post' ? '-post-v1' : ''}`]
   let changed = []
-  if (options.incremental) {
-    changed = await changedFiles(context.taroRoot ?? root, ['opencard/src/**'])
+  if (options.incremental && !profile.full) {
+    changed = await changedFiles(context.taroRoot ?? root, ['opencard/src/**', ...globalConfigs])
+    if (changed.some(file => globalConfigs.includes(file))) changed = []
     if (changed.length > 0) {
       console.log(`[opencard lint] incremental mode (${changed.length} files)`)
     }
@@ -105,29 +121,32 @@ export async function lintOpenCard(context, options = {}) {
   const tasks = [
     { name: 'opencard-structure', run: async () => validateOpenCardStructure(validationContext) },
     { name: 'opencard-widget-shell', run: async () => validateWidgetShell(validationContext) },
-    { name: 'opencard-lynx-css', run: () => runLynxCss(root, options.lintProject) },
+    { name: 'opencard-lynx-css', run: () => runLynxCss(root, options.lintProject, { cardType: profile.cardType }) },
     { name: 'opencard-tsc', run: () => runProcess(tsc, ['--noEmit'], { cwd: root }) },
   ]
   if (eslintSelection.runEslint) {
     tasks.push({
       name: 'opencard-eslint',
-      run: () => runProcess(eslint, eslintArgs, { cwd: root }),
+      run: () => runProcess(eslint, eslintArgs, { cwd: root, env: { VIBECODING_CARD_TYPE: profile.cardType } }),
     })
   }
   await runTasks(tasks, { label: 'opencard lint' })
+  profile.complete()
 }
 
 export async function runLint(context, options = {}) {
-  const incremental = options.incremental || process.env.LINT_INCREMENTAL === '1'
+  let incremental = options.incremental || process.env.LINT_INCREMENTAL === '1'
   if (context.target === 'opencard') {
     await lintOpenCard(context, { incremental })
     return
   }
 
+  const profile = await lintProfile(context.root, context.root)
+  if (profile.full) incremental = false
   validateNonEmptyTaro(context)
   const tsc = resolveProjectBinary(context.root, 'tsc')
   const eslint = resolveProjectBinary(context.root, 'eslint')
-  const eslintArgs = ['--cache', '--cache-location', 'node_modules/.cache/eslint/root-src']
+  const eslintArgs = ['--cache', '--cache-location', `node_modules/.cache/eslint/root-src${profile.cardType === 'post' ? '-post-v1' : ''}`]
   const changed = incremental ? await incrementalLintFiles(context.root) : []
   if (incremental) {
     const files = changed.filter((file) => file.startsWith('src/'))
@@ -143,7 +162,9 @@ export async function runLint(context, options = {}) {
   if (full || changed.some((file) => file.startsWith('src/'))) {
     tasks.push(
       { name: 'taro-tsc', run: () => runProcess(tsc, ['--noEmit'], { cwd: context.root }) },
-      { name: 'taro-eslint', run: () => runProcess(eslint, eslintArgs, { cwd: context.root }) },
+      { name: 'taro-eslint', run: () => runProcess(eslint, eslintArgs, {
+        cwd: context.root, env: { VIBECODING_CARD_TYPE: profile.cardType },
+      }) },
     )
   }
   if (full || serverChanged || closedDomainChanged) {
@@ -173,4 +194,5 @@ export async function runLint(context, options = {}) {
     tasks.push({ name: 'opencard-lint', run: () => lintOpenCard(context, { incremental: !full }) })
   }
   await runTasks(tasks, { label: 'lint' })
+  profile.complete()
 }

package/src/commands/validate.mjs

@@ -1,5 +1,5 @@
 import { UsageError } from '../core/errors.mjs'
-import { validateFeedCard } from '../validators/feed-card.mjs'
+import { validateFeedCard, validateProjectCardBackground } from '../validators/feed-card.mjs'
 import { validateNonEmptyTaro } from '../validators/empty-project.mjs'
 import { validateOpenCardStructure } from '../validators/opencard-structure.mjs'
 import { validateRoutes } from '../validators/routes.mjs'
@@ -9,6 +9,9 @@ export async function runValidate(context, validator) {
     case 'feed-card':
       validateFeedCard(context)
       return
+    case 'feed-background':
+      validateProjectCardBackground(context)
+      return
     case 'routes':
       validateRoutes(context)
       return
@@ -20,7 +23,7 @@ export async function runValidate(context, validator) {
       return
     default:
       throw new UsageError(
-        `Unknown validator: ${validator || '<missing>'}\nAvailable validators: feed-card, routes, empty, opencard-structure`,
+        `Unknown validator: ${validator || '<missing>'}\nAvailable validators: feed-card, feed-background, routes, empty, opencard-structure`,
       )
   }
 }

package/src/config/card-lint.mjs

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createRequire } from 'node:module'
+import { readCardProfile } from './card-profile.mjs'
+
+function stateFile(lintRoot) {
+  return path.join(lintRoot, 'node_modules/.cache/eslint/card-profile.json')
+}
+
+function commit(lintRoot, signature) {
+  const file = stateFile(lintRoot)
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify({ signature }) + '\n')
+}
+
+// Only a successful lint records the configuration it actually checked. This
+// also catches untracked/deleted routing files and switches outside a Git diff.
+export function prepareCardLint({ projectRoot, lintRoot }) {
+  const profile = readCardProfile({ projectRoot })
+  let raw = 'missing'
+  try { raw = readFileSync(profile.configPath, 'utf8') } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+  const signature = createHash('sha256').update(`card-rules-v1\n${raw}`).digest('hex')
+  let previous
+  try { previous = JSON.parse(readFileSync(stateFile(lintRoot), 'utf8')).signature } catch {}
+  return { ...profile, signature, full: previous !== signature, complete: () => commit(lintRoot, signature) }
+}
+
+/** Fail an explicit upgrade if its installed SDK cannot enforce post rules. */
+export async function ensureCardLintSupport({ projectRoot, lintRoot, cardType }) {
+  if (cardType !== 'post') return
+  const entry = projectRoot === lintRoot
+    ? '@open-dy/vibecoding-sdk-taro/eslint/taro'
+    : '@open-dy/vibecoding-sdk-opencard/eslint/opencard'
+  try {
+    const require = createRequire(path.join(lintRoot, 'package.json'))
+    const sdk = await import(pathToFileURL(require.resolve(entry)).href)
+    if (sdk.CARD_TYPE_RULES_VERSION !== 1) throw new Error('CARD_TYPE_RULES_VERSION must be 1')
+  } catch (error) {
+    throw new Error(`作品卡 lint 需要升级配套 SDK：${entry}。${error.message}`, { cause: error })
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    const [action, projectRoot, lintRoot, signature] = process.argv.slice(2)
+    if (action === 'prepare') {
+      const state = prepareCardLint({ projectRoot, lintRoot })
+      await ensureCardLintSupport({ projectRoot, lintRoot, cardType: state.cardType })
+      console.log(`${state.cardType} ${state.full ? '1' : '0'} ${state.signature}`)
+    } else if (action === 'complete' && /^[a-f0-9]{64}$/.test(signature ?? '')) {
+      commit(lintRoot, signature)
+    } else throw new Error('Expected prepare or complete with project and lint roots')
+  } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}

package/src/config/card-profile.mjs

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * @desc 校验卡片形态；缺少字段保留历史兴趣卡语义，不写回配置。
+ * @params {object} config 已解析的工程配置。
+ * @params {string} [source] 错误信息中的配置来源。
+ * @return {'interest'|'post'} 卡片形态。
+ * @example parseCardType({ cardType: 'post' })
+ */
+export function parseCardType(config, source = 'card-routing.json') {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`${source} must contain an object`)
+  }
+  if (!Object.hasOwn(config, 'cardType')) return 'interest'
+  if (config.cardType !== 'interest' && config.cardType !== 'post') {
+    throw new Error(`${source}: cardType must be interest or post; got ${JSON.stringify(config.cardType)}`)
+  }
+  return config.cardType
+}
+
+/**
+ * @desc 从明确的宿主工程目录读取形态，供 CLI 与两端 SDK 共用。
+ * @params {{projectRoot: string}} options 宿主工程绝对路径；OpenCard 配置也传宿主目录。
+ * @return {{cardType: 'interest'|'post', configPath: string}} 形态及配置来源。
+ * @example readCardProfile({ projectRoot: '/workspace/project/card-app' })
+ */
+export function readCardProfile({ projectRoot }) {
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
+    throw new Error('readCardProfile requires an absolute projectRoot')
+  }
+  const configPath = path.join(projectRoot, 'config/card-routing.json')
+  let raw
+  try {
+    raw = readFileSync(configPath, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { cardType: 'interest', configPath }
+    throw error
+  }
+  let config
+  try {
+    config = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`${configPath} must contain valid JSON: ${error.message}`)
+  }
+  return { cardType: parseCardType(config, configPath), configPath }
+}
+
+function findEslintHost(filename, target) {
+  let directory = path.dirname(filename)
+  while (true) {
+    // Stop at the owning package/config instead of inheriting another project's
+    // routing. An OpenCard package belongs to its immediate host directory.
+    if (existsSync(path.join(directory, 'package.json')) ||
+        existsSync(path.join(directory, 'eslint.config.mjs')) ||
+        existsSync(path.join(directory, 'project.card.json'))) {
+      return target === 'opencard' ? path.dirname(directory) : directory
+    }
+    if (existsSync(path.join(directory, '.git'))) return undefined
+    const parent = path.dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}
+
+/**
+ * @desc 创建作品卡文件匹配器；CLI 传入形态，直接 ESLint 从待检查文件定位工程。
+ * @params {{cardType?: 'interest'|'post', target: 'taro'|'opencard'}} options SDK 配置及目标端。
+ * @params {object} [environment] CLI 子进程环境。
+ * @return {(filename: string) => boolean} 是否启用作品卡配置。
+ * @example createPostCardMatcher({ target: 'taro' })('/workspace/app/src/index.ts')
+ */
+export function createPostCardMatcher(options, environment = process.env) {
+  const configured = options.cardType ?? environment.VIBECODING_CARD_TYPE
+  // An explicitly supplied null must not silently fall back to legacy rules.
+  const explicit = options.cardType !== undefined
+  if (explicit || configured !== undefined) {
+    const cardType = parseCardType({ cardType: explicit ? options.cardType : configured }, 'ESLint cardType')
+    return () => cardType === 'post'
+  }
+  return filename => {
+    const projectRoot = findEslintHost(filename, options.target)
+    return projectRoot ? readCardProfile({ projectRoot }).cardType === 'post' : false
+  }
+}
+
+// The legacy shell entry uses the same parser as the SDK-owned ESLint configs.
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    console.log(readCardProfile({ projectRoot: path.resolve(process.argv[2]) }).cardType)
+  } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}

package/src/preview/watch-card-routing.mjs

@@ -1,4 +1,4 @@
-import { watchFile, unwatchFile, readFileSync } from 'node:fs'
+import { watchFile, unwatchFile } from 'node:fs'
 import { resolveCardRoutingPath, openCardBuildEnvironment } from '../build/opencard-environment.mjs'
 
 // Polling follows atomic file replacements and also works when config/ is absent
@@ -6,13 +6,13 @@ import { resolveCardRoutingPath, openCardBuildEnvironment } from '../build/openc
 export async function startRoutingPreview({ root, start, onError = console.error, signal, pollMs = 250, debounceMs = 150 }) {
   const context = { root }
   const file = resolveCardRoutingPath(context)
-  let mode = openCardBuildEnvironment(context).IS_CARD_CLOSED_DOMAIN
+  let mode = openCardBuildEnvironment(context)
   const controller = new AbortController()
   const cancelStart = () => controller.abort()
   signal?.addEventListener('abort', cancelStart, { once: true })
   if (signal?.aborted) controller.abort()
   async function launch(value) {
-    const runtime = await start({ IS_CARD_CLOSED_DOMAIN: value }, controller.signal)
+    const runtime = await start({ ...value }, controller.signal)
     let closing
     return { ...runtime, close: () => (closing ??= Promise.resolve().then(() => runtime.close())) }
   }
@@ -30,10 +30,7 @@ export async function startRoutingPreview({ root, start, onError = console.error
 
   function readMode() {
     // During watching, deletion/incomplete saves must not become an open default.
-    const routing = JSON.parse(readFileSync(file, 'utf8'))
-    const domain = routing?.cardData?.serviceDomain
-    if (!['closed', 'open', 'none'].includes(domain)) throw new Error(`${file}: cardData.serviceDomain must be closed, open, or none`)
-    return String(domain === 'closed')
+    return openCardBuildEnvironment(context, { allowMissing: false })
   }
   async function refresh() {
     if (stopped) return
@@ -46,8 +43,9 @@ export async function startRoutingPreview({ root, start, onError = console.error
       lastError = error.message
       return
     }
-    if (mode === next) return
-    console.log(`[opencard] Domain changed; restarting preview (closed=${next})`)
+    if (mode.IS_CARD_CLOSED_DOMAIN === next.IS_CARD_CLOSED_DOMAIN &&
+        mode.VIBECODING_CARD_TYPE === next.VIBECODING_CARD_TYPE) return
+    console.log(`[opencard] Routing changed; restarting preview (closed=${next.IS_CARD_CLOSED_DOMAIN}, cardType=${next.VIBECODING_CARD_TYPE})`)
     await current.close()
     if (stopped) return
     current = await launch(next)

package/src/validators/feed-card.cjs

@@ -1,5 +1,6 @@
 const fs = require("node:fs");
 const path = require("node:path");
+const { spawnSync } = require("node:child_process");
 const Ajv = require("ajv");
 
 function failFast(message) {
@@ -55,6 +56,37 @@ function resolveFeedCardSchema(projectRoot) {
   return schemaPath;
 }
 
+function validateCardBackground(data) {
+  const validator = path.join(__dirname, "validate-card-background.py");
+  const result = spawnSync("python3", [
+    validator,
+    "--url", data.CardBackgroundUrl,
+    "--primary-color", data.PrimaryColor || "",
+  ], { encoding: "utf8", timeout: 20_000 });
+  if (result.error) {
+    throw new Error(`Background image validation could not run: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || "Background image validation failed.").trim());
+  }
+  return JSON.parse(result.stdout);
+}
+
+function validateProjectCardBackground(context) {
+  if (context.target !== "taro") {
+    throw new Error("Feed background validation requires --target taro");
+  }
+  const jsonPath = path.join(context.root, "feed/feed-card.json");
+  if (!fs.existsSync(jsonPath)) return { skipped: true };
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+  } catch (error) {
+    failFast(`Invalid JSON syntax in ${jsonPath}: ${error.message}`);
+  }
+  return validateCardBackground(data);
+}
+
 function validateFeedCard(context, options = {}) {
   if (context.target !== "taro") {
     throw new Error("Feed card validation requires --target taro");
@@ -140,6 +172,8 @@ function validateFeedCard(context, options = {}) {
     reportAndExit(errors);
   }
 
+  validateCardBackground(data);
+
   if (options.touchTimestamp !== false) {
     data.__timestamp = Date.now();
     try {
@@ -153,4 +187,4 @@ function validateFeedCard(context, options = {}) {
   return { skipped: false };
 }
 
-module.exports = { resolveFeedCardSchema, validateFeedCard };
+module.exports = { resolveFeedCardSchema, validateFeedCard, validateCardBackground, validateProjectCardBackground };

package/src/validators/feed-card.mjs

@@ -25,8 +25,22 @@ export function resolveFeedCardSchema(projectRoot) {
  * @params {object} context CLI 工程上下文。
  * @params {object} [options] 校验选项。
  * @return {unknown} 校验器返回的结果；发现错误时抛出 CliError。
- * @example validateFeedCard(context, { full: true })
+ * @example validateFeedCard(context)
  */
 export function validateFeedCard(context, options = {}) {
   return runValidation(() => validator.validateFeedCard(context, options))
 }
+
+export function validateCardBackground(data) {
+  return runValidation(() => validator.validateCardBackground(data))
+}
+
+/**
+ * @desc 单独实测 feed-card.json 指向的最终背景图与 PrimaryColor 底部承接。
+ * @params {object} context CLI 工程上下文。
+ * @return {unknown} 图片尺寸和底部色彩/纹理指标；发现错误时抛出 CliError。
+ * @example validateProjectCardBackground(context)
+ */
+export function validateProjectCardBackground(context) {
+  return runValidation(() => validator.validateProjectCardBackground(context))
+}

package/src/validators/image-inline.mjs

@@ -0,0 +1,82 @@
+import { readFileSync, statSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+const IMAGE_INLINE_LIMIT = 4096;
+const SKILL_GUIDANCE = "请查阅 microapp-optimize-interest-card/SKILL.md 中的图片规则";
+
+/** Validate the image inventory after compilation. Findings only warn. */
+export function validateImageInline(context) {
+  const cardRoot =
+    context.target === "opencard" ? context.root : context.opencardRoot;
+  if (!cardRoot || (context.target !== "opencard" && !context.hasOpenCard)) {
+    return { warnings: 0, unverified: 0 };
+  }
+  const reportFile = path.join(
+    cardRoot, "node_modules/.cache/vibecoding/image-inline-tt.json",
+  );
+  try {
+    const report = JSON.parse(readFileSync(reportFile, "utf8"));
+    if (report.schemaVersion !== 3 || report.status !== "complete" ||
+      report.target !== "tt" ||
+      realpathSync(report.projectRoot) !== realpathSync(cardRoot) ||
+      !Array.isArray(report.findings) || !Array.isArray(report.issues) ||
+      !report.findings.every(item => item && typeof item.file === "string" && Number.isInteger(item.line) && item.line > 0 &&
+        Number.isInteger(item.column) && item.column > 0 &&
+        (item.kind === "import" || item.kind === "data-url") &&
+        (item.kind === "import" ? typeof item.image === "string" : typeof item.dataUrl === "string")) ||
+      !report.issues.every(issue => typeof issue === "string")) {
+      throw new Error("图片检查报告格式或工程身份不匹配");
+    }
+    const warnings = [];
+    const issues = [...report.issues];
+    for (const item of report.findings) {
+      let bytes;
+      try {
+        if (item.kind === "import") {
+          const info = statSync(path.resolve(cardRoot, item.image));
+          if (!info.isFile()) throw new Error("图片路径不是文件");
+          bytes = info.size;
+        } else {
+          const match = /^data:image\/[a-z0-9.+-]+(?:;[a-z0-9_-]+=[^;,\s]+)*;base64,([a-z0-9+/]*={0,2})$/i.exec(item.dataUrl);
+          const encoded = match?.[1];
+          if (!encoded || encoded.length % 4 === 1) throw new Error("图片 Base64 编码无效");
+          const decoded = Buffer.from(encoded, "base64");
+          if (decoded.toString("base64").replace(/=+$/, "") !== encoded.replace(/=+$/, "") ||
+            (encoded.includes("=") && encoded.length % 4 !== 0)) {
+            throw new Error("图片 Base64 编码无效");
+          }
+          bytes = decoded.length;
+        }
+      } catch (error) {
+        issues.push(`${item.file}:${item.line}:${item.column} 检查未完成：${error.message}。`);
+        continue;
+      }
+      if (bytes < IMAGE_INLINE_LIMIT) continue;
+      warnings.push(`  ${item.file}:${item.line}:${item.column}\n` +
+        (item.kind === "import"
+          ? `    类型：图片 import\n    原图：${item.image}\n    大小：${bytes} bytes\n`
+          : `    类型：固定 Base64 图片\n    解码大小：${bytes} bytes\n`));
+    }
+    if (warnings.length || issues.length) console.warn("=== 图片性能检测报告 ===\n");
+    if (warnings.length) {
+      console.warn(`检测到以下图片 import 或固定 Base64 图片大小 ≥${IMAGE_INLINE_LIMIT} 字节，存在内联图片性能风险。${SKILL_GUIDANCE}并在确认问题后上传图片以修复以下图片性能问题：\n`);
+      for (const warning of warnings) console.warn(warning);
+      console.warn(`共 ${warnings.length} 条可能的图片性能问题`);
+    }
+    if (issues.length) {
+      console.warn("图片检查未完成：");
+      for (const issue of issues) console.warn(`  ${issue}`);
+      if (!warnings.length) console.warn(`${SKILL_GUIDANCE}。`);
+    }
+    return { warnings: warnings.length, unverified: issues.length };
+  } catch (error) {
+    console.warn("=== 图片性能检测报告 ===\n");
+    console.warn(
+      "图片检查未完成：未取得有效报告。" +
+        "请检查 SDK 版本及构建日志。" +
+        ` (${error.message})`,
+    );
+    console.warn(`${SKILL_GUIDANCE}。`);
+    return { warnings: 0, unverified: 1 };
+  }
+}

package/src/validators/opencard-structure.mjs

@@ -53,7 +53,7 @@ export function validateOpenCardStructure(context) {
         `found ${preloadCount} preload call(s). ` +
         'Use taro.preloadMiniApp({ appList }) on the Card instance provided by useCardTaro from @tarojs/taro (opencard-taro); ' +
         'this is not a named export of @open-dy/vibecoding-sdk-opencard. ' +
-        'See ${SKILL_DIR}/references/opencard/api.md, section "小程序跳转预加载", for the lifecycle guards and example.',
+        'See ${CAPABILITY_SKILL_DIR}/references/opencard/runtime.md, section "小程序跳转预加载", for the lifecycle guards and example.',
       )
     }
   }

package/src/validators/validate-card-background.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Validate the bottom continuation of a Feed Card background.
+
+The current composer emits a 1440x2560 RGB PNG with an exact baseColor fill
+below its hero.  Existing cards also contain earlier valid variants with a
+same-hue darkened or softly feathered continuation.  This compatibility gate
+therefore samples the whole bottom 30%, requiring a low-texture, same-hue
+continuation while still rejecting raw heroes or attachments that run to the
+host-button safety area.
+"""
+
+import argparse
+import json
+import math
+import struct
+import sys
+import urllib.request
+import zlib
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+SAMPLE_W = 72
+SAMPLE_H = 128
+BOTTOM_START_RATIO = 0.70
+MAX_HORIZONTAL_TEXTURE = 3.0
+MAX_VERTICAL_TEXTURE = 4.0
+MAX_HUE_DELTA = 12.0
+LOW_SATURATION = 15.0
+MAX_NEUTRAL_COLOR_DISTANCE = 24.0
+
+
+def fail(message):
+    raise ValueError(message)
+
+
+def parse_color(value):
+    if not isinstance(value, str) or len(value) != 7 or not value.startswith("#"):
+        fail("PrimaryColor must be a #RRGGBB value for background validation.")
+    try:
+        return tuple(int(value[index:index + 2], 16) for index in (1, 3, 5))
+    except ValueError:
+        fail("PrimaryColor must be a #RRGGBB value for background validation.")
+
+
+def download(url):
+    request = urllib.request.Request(url, headers={"User-Agent": "vibecoding-feed-background-validator/1"})
+    with urllib.request.urlopen(request, timeout=15) as response:
+        content = response.read(12 * 1024 * 1024 + 1)
+    if len(content) > 12 * 1024 * 1024:
+        fail("CardBackgroundUrl exceeds the 12 MiB validation download limit.")
+    return content
+
+
+def paeth(a, b, c):
+    p = a + b - c
+    pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
+    return a if pa <= pb and pa <= pc else (b if pb <= pc else c)
+
+
+def decode_png(content):
+    if not content.startswith(PNG_SIGNATURE):
+        fail("CardBackgroundUrl must point to the final PNG produced by the background pipeline; received a non-PNG image.")
+    position = len(PNG_SIGNATURE)
+    width = height = bit_depth = color_type = interlace = None
+    idat = []
+    while position < len(content):
+        if position + 12 > len(content):
+            fail("CardBackgroundUrl PNG is truncated.")
+        size = struct.unpack(">I", content[position:position + 4])[0]
+        chunk_type = content[position + 4:position + 8]
+        chunk = content[position + 8:position + 8 + size]
+        position += size + 12
+        if chunk_type == b"IHDR":
+            width, height, bit_depth, color_type, compression, filter_method, interlace = struct.unpack(">IIBBBBB", chunk)
+            if compression != 0 or filter_method != 0:
+                fail("CardBackgroundUrl PNG uses an unsupported PNG encoding.")
+        elif chunk_type == b"IDAT":
+            idat.append(chunk)
+        elif chunk_type == b"IEND":
+            break
+    if not width or not height or bit_depth != 8 or color_type not in (2, 6) or interlace != 0:
+        fail("CardBackgroundUrl must be a non-interlaced 8-bit RGB or RGBA PNG.")
+    channels = 4 if color_type == 6 else 3
+    row_bytes = width * channels
+    raw = zlib.decompress(b"".join(idat))
+    if len(raw) != height * (row_bytes + 1):
+        fail("CardBackgroundUrl PNG pixel data is invalid.")
+    rows, previous, cursor = [], bytearray(row_bytes), 0
+    for _ in range(height):
+        filter_type = raw[cursor]
+        cursor += 1
+        encoded = raw[cursor:cursor + row_bytes]
+        cursor += row_bytes
+        row = bytearray(row_bytes)
+        for index, value in enumerate(encoded):
+            left = row[index - channels] if index >= channels else 0
+            up = previous[index]
+            up_left = previous[index - channels] if index >= channels else 0
+            if filter_type == 0:
+                row[index] = value
+            elif filter_type == 1:
+                row[index] = (value + left) & 255
+            elif filter_type == 2:
+                row[index] = (value + up) & 255
+            elif filter_type == 3:
+                row[index] = (value + ((left + up) // 2)) & 255
+            elif filter_type == 4:
+                row[index] = (value + paeth(left, up, up_left)) & 255
+            else:
+                fail("CardBackgroundUrl PNG uses an unsupported row filter.")
+        rows.append(row)
+        previous = row
+    return width, height, channels, rows
+
+
+def rgb_to_hsl(rgb):
+    r, g, b = (channel / 255.0 for channel in rgb)
+    maximum, minimum = max(r, g, b), min(r, g, b)
+    lightness = (maximum + minimum) / 2.0
+    if maximum == minimum:
+        return 0.0, 0.0, lightness * 100.0
+    delta = maximum - minimum
+    saturation = delta / (2.0 - maximum - minimum) if lightness > 0.5 else delta / (maximum + minimum)
+    if maximum == r:
+        hue = ((g - b) / delta + (6.0 if g < b else 0.0)) / 6.0
+    elif maximum == g:
+        hue = ((b - r) / delta + 2.0) / 6.0
+    else:
+        hue = ((r - g) / delta + 4.0) / 6.0
+    return hue * 360.0, saturation * 100.0, lightness * 100.0
+
+
+def hue_delta(first, second):
+    return min(abs(first - second), 360.0 - abs(first - second))
+
+
+def color_distance(first, second):
+    return sum(abs(first[index] - second[index]) for index in range(3)) / 3.0
+
+
+def inspect(content, primary):
+    width, height, channels, rows = decode_png(content)
+    if abs(width / height - 9 / 16) > 0.01:
+        fail(f"CardBackgroundUrl must be 9:16, got {width}x{height}.")
+
+    bottom_start = math.floor(height * BOTTOM_START_RATIO)
+    for y in range(bottom_start, height):
+        row = rows[y]
+        for x in range(width):
+            offset = x * channels
+            if channels == 4 and row[offset + 3] != 255:
+                fail("CardBackgroundUrl bottom continuation must be fully opaque.")
+
+    sample_x = [round(index * (width - 1) / (SAMPLE_W - 1)) for index in range(SAMPLE_W)]
+    sample_y = [round(index * (height - 1) / (SAMPLE_H - 1)) for index in range(SAMPLE_H)]
+    pixels = [
+        [tuple(rows[y][x * channels + channel] for channel in range(3)) for x in sample_x]
+        for y in sample_y
+    ]
+    sample_start = math.floor(SAMPLE_H * BOTTOM_START_RATIO)
+    bottom = pixels[sample_start:]
+    horizontal = [color_distance(row[index], row[index - 1]) for row in bottom for index in range(1, SAMPLE_W)]
+    vertical = [
+        color_distance(bottom[row_index][column], bottom[row_index - 1][column])
+        for row_index in range(1, len(bottom))
+        for column in range(SAMPLE_W)
+    ]
+    average = tuple(round(sum(pixel[channel] for row in bottom for pixel in row) / (len(bottom) * SAMPLE_W)) for channel in range(3))
+    average_hue, _, _ = rgb_to_hsl(average)
+    primary_hue, primary_saturation, _ = rgb_to_hsl(primary)
+    horizontal_texture = sum(horizontal) / len(horizontal)
+    vertical_texture = sum(vertical) / len(vertical)
+    issues = []
+    if horizontal_texture > MAX_HORIZONTAL_TEXTURE:
+        issues.append(f"horizontal texture={horizontal_texture:.1f}>{MAX_HORIZONTAL_TEXTURE}")
+    if vertical_texture > MAX_VERTICAL_TEXTURE:
+        issues.append(f"vertical texture={vertical_texture:.1f}>{MAX_VERTICAL_TEXTURE}")
+    if primary_saturation < LOW_SATURATION:
+        neutral_distance = color_distance(average, primary)
+        if neutral_distance > MAX_NEUTRAL_COLOR_DISTANCE:
+            issues.append(f"neutral color distance={neutral_distance:.1f}>{MAX_NEUTRAL_COLOR_DISTANCE}")
+    else:
+        delta = hue_delta(average_hue, primary_hue)
+        if delta > MAX_HUE_DELTA:
+            issues.append(f"hue delta={delta:.1f}>{MAX_HUE_DELTA}")
+    if issues:
+        fail(
+            "CardBackgroundUrl bottom 30% is not a low-texture PrimaryColor continuation (" +
+            ", ".join(issues) +
+            "). Re-run the background four-step pipeline or regenerate a same-hue solid/gradient extension."
+        )
+    return {
+        "width": width,
+        "height": height,
+        "bottomStartY": bottom_start,
+        "bottomHorizontalTexture": round(horizontal_texture, 2),
+        "bottomVerticalTexture": round(vertical_texture, 2),
+        "bottomAverage": "#" + "".join(f"{channel:02x}" for channel in average),
+        "primaryColor": "#" + "".join(f"{channel:02x}" for channel in primary),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--url", required=True)
+    parser.add_argument("--primary-color", required=True)
+    args = parser.parse_args()
+    result = inspect(download(args.url), parse_color(args.primary_color))
+    print(json.dumps(result, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        print(f"[Background Validation Failed] {error}", file=sys.stderr)
+        sys.exit(1)