create-yss-spec 3.0.1 → 3.1.3

package/template/.agents/skills/yss-prototype-stage/references/prototype-profile-routing.md

@@ -9,7 +9,7 @@
 | 档位 | 名称 | 命中条件 | 默认适配器 |
 |---|---|---|---|
 | H1 | `visual-review` | 仅需确认布局、密度、层级、文案或少量关键交互；不涉及多页面导航、复杂联动、权限、恢复、冲突或真实组件差异 | 语义 HTML + 项目 Token CSS + 最小 JavaScript；可使用设计工具导出，但必须有浏览器可复验入口 |
-| H2 | `flow-review` | 多页面/路由、复杂表单联动、权限体验、失败恢复、并发冲突或需要可操作主流程测试 | 可运行前端原型；React/Vite + Ant Design v6 是受支持默认，不是强制实现 |
+| H2 | `flow-review` | 多页面/路由、复杂表单联动、权限体验、失败恢复、并发冲突或需要可操作主流程测试 | 可运行前端原型；Vue 3/Vite + Antdv Next 是受支持默认，React/Vite + Ant Design v6 为显式兼容路线 |
 
 真实 YSS/AntDV 组件行为、lockfile、props、slots、events 或 Storybook 状态不是第三种原型档位。它们属于前端实现计划、已批准切片的生产实现与实现还原验证。原型中发现的相关不确定性写入 `implementation_handoff`，不得为解决它调用 `yss-ui` 或把实现仓组件代码引入原型。
 
@@ -18,12 +18,14 @@
 - `decision_to_inform`：本轮原型要支持的具体决策。
 - `risk_assumptions` 与 `trigger_results`：机器可读档位来源。
 - Spec、交互说明、状态矩阵、设计系统与低保真评审引用。
-- 浏览器入口、产物 digest、desktop/narrow 非空渲染、console 结果。
+- 浏览器入口、产物 digest、desktop/narrow 非空渲染、console 结果，以及由 `case_id` 定位的 Visual Baseline Bundle。
 - 统一 Design QA 六轴：visual、layout、interaction、content、accessibility、cross-platform。
 - 独立原型评审引用、用户确认、blockers 和 gaps。
 - `implementation_handoff`：只记录生产组件假设、待验证事项和目标阶段，不提前执行生产组件核验。
 
-机器优先采集版本、digest、视口、截图、console 与扫描结果；人只填写决策、风险解释、允许差异和用户确认。不得把同一事实复制到多个段落。
+机器优先采集版本、digest、视口、截图、console 与扫描结果；人只填写决策、风险解释、允许差异和用户确认。PNG 基准图统一使用 sRGB、DPR 1，关闭动画并隐藏光标；长页面使用固定滚动分段，full-page 只可作总览。每张图不超过 5 MiB，整包不超过 100 MiB。不得把同一事实复制到多个段落。
+
+`visual-baseline.yaml` 是模型与实现验证的唯一图片索引。每个 case 必须绑定 route、page、state、viewport、theme、locale、data scenario、PNG digest、语义引用和允许差异；至少覆盖 1440x900 与 390x844。原型用户确认时冻结版本，后续变更创建新版本并使依赖的实现计划与 Slice Contract `stale`，禁止覆盖旧版本。
 
 ## 档位证据
 
@@ -37,8 +39,8 @@
 
 - 主流程与关键 failure / no-permission / conflict 状态可操作。
 - 验证键盘、焦点、对比度、200% zoom、reduced motion；按风险决定视觉回归。
-- 使用 AntD 时记录精确版本。fact pack 只有在版本、组件集合和项目 Token baseline digest 全部匹配且没有新 API 疑问时才可复用，否则只补增量查询。
-- 不使用 AntD 时记录 component basis，不创建空 AntD 字段。
+- 默认使用 `vue-antdv-next` 并记录 package 与精确版本；显式兼容路线记录 `react-antd-6`。fact pack 只有在 provider、版本、组件集合和项目 Token baseline digest 全部匹配且没有新 API 疑问时才可复用，否则只补增量查询。
+- 使用其他基座时记录 `component_basis`，不创建空 Antdv Next 或 AntD 字段。
 
 ### 实现阶段交接
 
@@ -62,6 +64,6 @@
 
 ## 迁移
 
-- 新证据只生成 schema v3 与 `artifact.prototype-deliverable`。
-- schema v1/v2 和 `artifact.high-fidelity-html-prototype` 只读兼容；已经关闭的历史证据保持有效，不回写。
-- 在途 v2 证据必须迁移到 v3 后才能关闭 `gate.prototype-verified`；回滚时停止生成 v3、恢复 v2 生成器，但不删除已产生证据。
+- 新证据只生成 schema v4、Visual Baseline schema v1 与 `artifact.prototype-deliverable`。
+- prototype evidence schema v1/v2/v3 和 `artifact.high-fidelity-html-prototype` 只读兼容；已经关闭的历史证据保持有效，不补造图片。
+- 在途 UI 证据必须迁移到 v4 并产生 Visual Baseline 后才能关闭 `gate.prototype-verified`；非 UI 功能不生成空包。

package/template/.agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { assertUserDecisionRequirement, decisionDigest, decisionIO } from "../../../../scripts/lib/user-decision.mjs";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -9,6 +10,12 @@ const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0
 const object = (value) => value && typeof value === "object" && !Array.isArray(value);
 const antdSemver = /^6\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
 const exactSemver = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
+const DEFAULT_H2_COMPONENT_BASIS = "vue-antdv-next";
+const DEFAULT_ANTDV_NEXT_VERSION = "1.5.2";
+const DEFAULT_VUE_VERSION = "3.5.21";
+const DEFAULT_VITE_VERSION = "6.4.2";
+const DEFAULT_VUE_PLUGIN_VERSION = "5.2.4";
+const H2_COMPONENT_BASES = new Set([DEFAULT_H2_COMPONENT_BASIS, "react-antd-6"]);
 const PROFILE_KIND = { H1: "visual-review", H2: "flow-review" };
 const PROFILE_BLOCK = { H1: "visual_review", H2: "flow_review" };
 
@@ -41,8 +48,8 @@ function validateConditionalCheck(check, parent, errors, allowTemplate) {
   requiredString(check, "evidence_ref", parent, errors);
 }
 
-function validateCommonV3(data, errors, allowTemplate) {
-  for (const field of ["feature", "prototype_ref", "prototype_profile", "profile_kind", "profile_decision", "upstream_refs", "source_visual", "design_baseline", "browser_delivery", "design_qa", "profile_evidence", "implementation_handoff", "review", "user_confirmation", "gaps", "blockers"]) required(data, field, "root", errors);
+function validateCommonV4(data, errors, allowTemplate) {
+  for (const field of ["feature", "prototype_ref", "prototype_profile", "profile_kind", "profile_decision", "upstream_refs", "source_visual", "design_baseline", "visual_baseline", "browser_delivery", "design_qa", "profile_evidence", "implementation_handoff", "review", "user_confirmation", "gaps", "blockers"]) required(data, field, "root", errors);
   requiredString(data, "feature", "root", errors);
   requiredString(data, "prototype_ref", "root", errors);
   if (!Object.hasOwn(PROFILE_KIND, data.prototype_profile)) errors.push("root.prototype_profile 必须为 H1/H2；真实组件验证不属于原型档位");
@@ -65,12 +72,24 @@ function validateCommonV3(data, errors, allowTemplate) {
   if (object(visual) && !["required", "not-applicable"].includes(visual.ideation_status)) errors.push("source_visual.ideation_status 必须为 required/not-applicable");
 
   const baseline = data.design_baseline;
+  requiredString(baseline, "canonical_design_ref", "design_baseline", errors);
+  requiredString(baseline, "canonical_design_digest", "design_baseline", errors);
+  if (object(baseline) && baseline.canonical_design_ref !== "DESIGN.md" && !(allowTemplate && /<[^>]+>/.test(baseline.canonical_design_ref ?? ""))) errors.push("design_baseline.canonical_design_ref 必须为 DESIGN.md");
   requiredString(baseline, "project_design_ref", "design_baseline", errors);
   requireArray(baseline, "project_token_refs", "design_baseline", errors, { nonEmpty: true });
   requiredString(baseline, "project_token_baseline_digest", "design_baseline", errors);
   required(baseline, "project_override_reviewed", "design_baseline", errors);
   if (!allowTemplate && baseline?.project_override_reviewed !== true) errors.push("design_baseline.project_override_reviewed 必须为 true");
 
+  const visualBaseline = data.visual_baseline;
+  for (const field of ["manifest_ref", "baseline_id", "version", "digest", "status", "case_ids"]) required(visualBaseline, field, "visual_baseline", errors);
+  for (const field of ["manifest_ref", "baseline_id", "version", "digest", "status"]) requiredString(visualBaseline, field, "visual_baseline", errors);
+  requireArray(visualBaseline, "case_ids", "visual_baseline", errors, { nonEmpty: true });
+  if (!allowTemplate && visualBaseline?.status !== "approved") errors.push("visual_baseline.status 必须为 approved");
+  if (!allowTemplate && !/^visual-baseline\.[a-z0-9][a-z0-9-]*$/.test(visualBaseline?.baseline_id ?? "")) errors.push("visual_baseline.baseline_id 非法");
+  if (!allowTemplate && !/^v[1-9][0-9]*$/.test(visualBaseline?.version ?? "")) errors.push("visual_baseline.version 必须形如 v1");
+  if (!allowTemplate && !/^sha256:[a-f0-9]{64}$/.test(visualBaseline?.digest ?? "")) errors.push("visual_baseline.digest 必须为 sha256 摘要");
+
   const browser = data.browser_delivery;
   for (const field of ["delivery_kind", "entry_ref", "rendered_nonblank", "prototype_digest", "viewports", "console_result", "console_ref"]) required(browser, field, "browser_delivery", errors);
   requiredString(browser, "delivery_kind", "browser_delivery", errors);
@@ -84,7 +103,7 @@ function validateCommonV3(data, errors, allowTemplate) {
     if (!viewport) errors.push(`browser_delivery.viewports 缺少 ${requiredViewport}`);
     else {
       requiredString(viewport, "size", `browser_delivery.viewports.${requiredViewport}`, errors);
-      requiredString(viewport, "screenshot_ref", `browser_delivery.viewports.${requiredViewport}`, errors);
+      requireArray(viewport, "case_ids", `browser_delivery.viewports.${requiredViewport}`, errors, { nonEmpty: true });
       if (!allowTemplate) requiredPassed(viewport, "result", `browser_delivery.viewports.${requiredViewport}`, errors, allowTemplate);
     }
   }
@@ -119,10 +138,10 @@ function validateCommonV3(data, errors, allowTemplate) {
     requireArray(data.user_confirmation, "simulations_or_gaps", "user_confirmation", errors);
   }
 
-  for (const legacy of ["prototype_stack", "visual_semantic_mapping", "antd", "browser_verification", "accessibility_verification"]) if (data[legacy] !== undefined) errors.push(`schema v3 禁止旧字段 root.${legacy}`);
+  for (const legacy of ["prototype_stack", "visual_semantic_mapping", "antd", "browser_verification", "accessibility_verification"]) if (data[legacy] !== undefined) errors.push(`schema v4 禁止旧字段 root.${legacy}`);
 }
 
-function validateProfileV3(data, errors, allowTemplate) {
+function validateProfileV4(data, errors, allowTemplate) {
   const blocks = object(data.profile_evidence) ? Object.keys(data.profile_evidence) : [];
   const expected = PROFILE_BLOCK[data.prototype_profile];
   if (blocks.length !== 1 || blocks[0] !== expected) errors.push(`profile_evidence 必须且只能包含 ${expected}`);
@@ -149,29 +168,48 @@ function validateProfileV3(data, errors, allowTemplate) {
     required(facts, "applicable", "profile_evidence.flow_review.prototype_library_facts", errors);
     requiredString(facts, "component_basis", "profile_evidence.flow_review.prototype_library_facts", errors);
     if (facts?.applicable === true) {
-      for (const field of ["source", "actual_antd_version", "manifest_ref", "manifest_digest", "project_token_baseline_digest"]) requiredString(facts, field, "profile_evidence.flow_review.prototype_library_facts", errors);
+      for (const field of ["source", "manifest_ref", "manifest_digest", "canonical_design_digest", "project_token_baseline_digest"]) requiredString(facts, field, "profile_evidence.flow_review.prototype_library_facts", errors);
       requireArray(facts, "components_covered", "profile_evidence.flow_review.prototype_library_facts", errors, { nonEmpty: true });
-      if (!allowTemplate && !antdSemver.test(facts.actual_antd_version ?? "")) errors.push("H2 actual_antd_version 必须是明确 antd 6.x semver");
+      if (facts.component_basis === "react-antd-6" && facts.actual_antd_version !== undefined) {
+        if (!allowTemplate && !antdSemver.test(facts.actual_antd_version ?? "")) errors.push("H2 actual_antd_version 必须是明确 antd 6.x semver");
+      } else {
+        for (const field of ["library_package", "library_version"]) requiredString(facts, field, "profile_evidence.flow_review.prototype_library_facts", errors);
+        if (!allowTemplate && !exactSemver.test(facts.library_version ?? "")) errors.push("H2 library_version 必须是明确 semver");
+        if (facts.component_basis === "vue-antdv-next" && facts.library_package !== "antdv-next") errors.push("vue-antdv-next 必须使用 antdv-next package");
+        if (facts.component_basis === "react-antd-6" && (facts.library_package !== "antd" || (!allowTemplate && !antdSemver.test(facts.library_version ?? "")))) errors.push("react-antd-6 必须使用明确的 antd 6.x 版本");
+      }
       if (!["fact-pack", "cli-run"].includes(facts.source)) errors.push("H2 prototype_library_facts.source 必须为 fact-pack/cli-run");
       if (!allowTemplate && facts.project_token_baseline_digest !== data.design_baseline.project_token_baseline_digest) errors.push("H2 fact pack 的项目 Token digest 已失效");
+      if (!allowTemplate && facts.canonical_design_digest !== data.design_baseline.canonical_design_digest) errors.push("H2 fact pack 的 DESIGN.md digest 已失效");
       if (!allowTemplate && facts.new_api_uncertainty !== false) errors.push("H2 fact pack 存在新 API 疑问，必须增量查询");
     }
     for (const forbidden of ["real_component_verified", "implementation_repo_ref", "component_library_version", "harness_ref", "story_refs"]) if (evidence[forbidden] !== undefined) errors.push(`H2 原型禁止生产组件字段 ${forbidden}`);
   }
 }
 
-export function validatePrototypeEvidence(data, { allowTemplate = false, allowLegacy = false } = {}) {
+export function prototypeDecisionSnapshot(data) {
+  return { prototype_ref: data.prototype_ref, prototype_digest: data.browser_delivery?.prototype_digest, visual_baseline: data.visual_baseline, design_baseline: data.design_baseline, upstream_refs: data.upstream_refs, operable_scope: data.user_confirmation?.operable_scope, simulations_or_gaps: data.user_confirmation?.simulations_or_gaps };
+}
+
+export function validatePrototypeEvidence(data, { allowTemplate = false, allowLegacy = false, ...decisionOptions } = {}) {
   const errors = [];
   const warnings = [];
   if (!object(data)) return { errors: ["原型证据必须是对象"], warnings };
-  if ([1, 2].includes(data.schema_version)) {
-    if (!allowLegacy) errors.push(`schema_version ${data.schema_version} 是只读旧证据；在途工作关闭 gate.prototype-verified 前必须迁移到 3`);
+  if ([1, 2, 3].includes(data.schema_version)) {
+    if (!allowLegacy) errors.push(`schema_version ${data.schema_version} 是只读旧证据；在途工作关闭 gate.prototype-verified 前必须迁移到 4`);
     else warnings.push(`legacy prototype evidence schema v${data.schema_version}; read-only`);
     return { errors, warnings };
   }
-  if (data.schema_version !== 3) return { errors: ["schema_version 必须为 3"], warnings };
-  validateCommonV3(data, errors, allowTemplate);
-  validateProfileV3(data, errors, allowTemplate);
+  if (data.schema_version !== 4) return { errors: ["schema_version 必须为 4"], warnings };
+  validateCommonV4(data, errors, allowTemplate);
+  validateProfileV4(data, errors, allowTemplate);
+  if (!allowTemplate && errors.length === 0) {
+    try {
+      const confirmation = data.user_confirmation;
+      assertUserDecisionRequirement({ boundary: "gate.user-confirmation", subject_ref: confirmation.decision_subject_ref, scope: confirmation.operable_scope, user_decision_ref: confirmation.user_decision_ref }, decisionOptions);
+      if (decisionDigest(decisionIO(decisionOptions).document(confirmation.decision_subject_ref)) !== decisionDigest(prototypeDecisionSnapshot(data))) throw new TypeError("user-decision-stale: 原型与用户所见快照不一致");
+    } catch (error) { errors.push(error.message); }
+  }
   return { errors, warnings };
 }
 
@@ -190,13 +228,49 @@ export async function prepareStaticPrototype({ projectRoot, root, feature }) {
   await mkdir(resolvedRoot, { recursive: true });
   for (const forbidden of ["package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock"]) if (existsSync(path.join(resolvedRoot, forbidden))) throw new TypeError(`H1 静态适配器拒绝已有 ${forbidden}`);
   await writeFile(path.join(resolvedRoot, "index.html"), `<!doctype html>\n<html lang="zh-CN">\n<head>\n  <meta charset="utf-8">\n  <meta name="viewport" content="width=device-width,initial-scale=1">\n  <title>${feature} · H1 visual review</title>\n  <link rel="stylesheet" href="./styles.css">\n</head>\n<body>\n  <main id="prototype" aria-labelledby="page-title">\n    <header><p class="eyebrow">H1 · visual-review</p><h1 id="page-title">${feature}</h1></header>\n    <section class="surface" aria-label="原型内容"><p>请在此实现已评审的视觉布局与少量关键交互。</p><button type="button" id="prototype-action">关键操作</button><p role="status" id="prototype-status"></p></section>\n  </main>\n  <script>document.querySelector('#prototype-action').addEventListener('click',()=>{document.querySelector('#prototype-status').textContent='交互已触发';});</script>\n</body>\n</html>\n`);
-  await writeFile(path.join(resolvedRoot, "styles.css"), `@import url("../../../../design/tokens/variables.css");\n:root{font-family:var(--font-family,system-ui,sans-serif);color:var(--text-color,#1f2329);background:var(--layout-background,#f0f2f5)}*{box-sizing:border-box}body{margin:0}main{max-width:1440px;margin:auto;padding:24px}.eyebrow{color:var(--brand-primary,#3371ff)}.surface{padding:20px;border-radius:8px;background:var(--container-background,#fff);box-shadow:0 1px 3px rgb(0 0 0/.08)}button{min-height:32px;padding:0 16px;border:0;border-radius:6px;color:#fff;background:var(--brand-primary,#3371ff)}button:focus-visible{outline:3px solid color-mix(in srgb,var(--brand-primary,#3371ff),white 55%);outline-offset:2px}@media(max-width:576px){main{padding:12px}.surface{padding:12px}}\n`);
+  await writeFile(path.join(resolvedRoot, "styles.css"), `@import url("../../../../design/tokens/variables.css");\n:root{font-family:var(--brand-font-family,system-ui,sans-serif);color:var(--brand-color-text);background:var(--brand-color-bg-layout)}*{box-sizing:border-box}body{margin:0}main{max-width:1440px;margin:auto;padding:var(--brand-size-lg)}.eyebrow{color:var(--brand-color-primary)}.surface{padding:var(--yss-card-compact-padding,var(--brand-size));border-radius:var(--brand-border-radius-lg);background:var(--brand-color-bg-container);box-shadow:0 1px 3px rgb(0 0 0/.08)}button{min-height:var(--yss-control-height-compact);padding:var(--brand-size-xxs) var(--brand-size-sm);border:0;border-radius:var(--brand-border-radius);color:var(--yss-color-on-primary,var(--brand-color-bg-container));background:var(--yss-color-primary-control,var(--brand-color-primary))}button:hover{background:var(--yss-color-primary-control-hover,var(--brand-color-primary-hover))}button:focus-visible{outline:3px solid color-mix(in srgb,var(--yss-color-primary-control,var(--brand-color-primary)),white 55%);outline-offset:2px}@media(max-width:576px){main{padding:var(--brand-size-sm)}.surface{padding:var(--brand-size-sm)}}\n`);
   const manifest = { schema_version: 1, feature, prototype_profile: "H1", profile_kind: "visual-review", runtime_build_required: false, entry: `docs/.scratch/${feature}/design/prototypes/index.html`, theme_source: "docs/design/tokens/variables.css" };
   await writeFile(path.join(resolvedRoot, "yss-prototype-adapter.json"), `${JSON.stringify(manifest, null, 2)}\n`);
   return manifest;
 }
 
-export async function prepareFlowPrototype({ projectRoot, root, feature, targetAntdVersion, pnpmVersion }) {
+async function writeIfMissing(file, content) {
+  if (!existsSync(file)) await writeFile(file, content);
+}
+
+async function prepareVueFlowPrototype({ projectRoot, root, feature, libraryVersion, pnpmVersion, vueVersion, viteVersion, vuePluginVersion, factPackRef }) {
+  for (const [field, version] of Object.entries({ libraryVersion, pnpmVersion, vueVersion, viteVersion, vuePluginVersion })) {
+    if (!exactSemver.test(version ?? "")) throw new TypeError(`${field} 必须是明确 semver`);
+  }
+  const { resolvedProject, resolvedRoot } = safePrototypeRoot(projectRoot, root, feature);
+  const themeSourcePath = path.join(resolvedProject, "docs/design/tokens/theme.json");
+  if (!existsSync(themeSourcePath)) throw new TypeError(`缺少项目主题: ${themeSourcePath}`);
+  const themeSource = JSON.parse(await readFile(themeSourcePath, "utf8"));
+  await mkdir(path.join(resolvedRoot, "src"), { recursive: true });
+  const packagePath = path.join(resolvedRoot, "package.json");
+  const pkg = existsSync(packagePath) ? JSON.parse(await readFile(packagePath, "utf8")) : {};
+  if (pkg.dependencies?.react || pkg.dependencies?.antd) throw new TypeError("Vue/Antdv Next H2 不得静默覆盖 React/AntD starter；请显式选择 react-antd-6 或使用新的原型目录");
+  pkg.name ??= `${feature}-prototype`;
+  pkg.version ??= "0.0.0";
+  pkg.private = true;
+  pkg.type = "module";
+  pkg.packageManager = `pnpm@${pnpmVersion}`;
+  pkg.scripts = { dev: "vite --host 127.0.0.1", build: "vite build", preview: "vite preview --host 127.0.0.1", ...(pkg.scripts ?? {}) };
+  pkg.dependencies = { ...(pkg.dependencies ?? {}), "@vitejs/plugin-vue": vuePluginVersion, "antdv-next": libraryVersion, vite: viteVersion, vue: vueVersion };
+  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+  await writeIfMissing(path.join(resolvedRoot, "index.html"), `<!doctype html>\n<html lang="zh-CN">\n<head>\n  <meta charset="UTF-8">\n  <meta name="viewport" content="width=device-width, initial-scale=1.0">\n  <title>${feature} · H2 flow review</title>\n</head>\n<body>\n  <div id="app"></div>\n  <script type="module" src="/src/main.js"></script>\n</body>\n</html>\n`);
+  await writeIfMissing(path.join(resolvedRoot, "vite.config.mjs"), `import { defineConfig } from "vite";\nimport vue from "@vitejs/plugin-vue";\n\nexport default defineConfig({ plugins: [vue()] });\n`);
+  await writeIfMissing(path.join(resolvedRoot, "src/main.js"), `import { createApp } from "vue";\nimport Antdv from "antdv-next";\nimport App from "./App.vue";\nimport "antdv-next/dist/reset.css";\nimport "./styles.css";\n\ncreateApp(App).use(Antdv).mount("#app");\n`);
+  await writeIfMissing(path.join(resolvedRoot, "src/App.vue"), `<script setup>\nimport { computed, ref } from "vue";\nimport { createYssTheme } from "./yss-theme.js";\n\nconst dark = ref(false);\nconst yssTheme = computed(() => createYssTheme({ dark: dark.value }));\n</script>\n\n<template>\n  <a-config-provider :theme="yssTheme">\n    <main aria-labelledby="page-title">\n      <p class="eyebrow">H2 · flow-review</p>\n      <h1 id="page-title">${feature}</h1>\n      <p>请在此实现已评审的主流程与关键异常状态。</p>\n      <a-button type="primary" @click="dark = !dark">切换主题以验证反馈</a-button>\n    </main>\n  </a-config-provider>\n</template>\n`);
+  await writeIfMissing(path.join(resolvedRoot, "src/styles.css"), `:root{font-family:system-ui,sans-serif;color:var(--text-color,#1f2329);background:var(--layout-background,#f0f2f5)}*{box-sizing:border-box}body{margin:0}main{max-width:1440px;margin:auto;padding:24px}.eyebrow{color:var(--brand-primary,#3371ff)}@media(max-width:576px){main{padding:12px}}\n`);
+  const generated = ['import { theme } from "antdv-next";', "", `const source = ${JSON.stringify(themeSource, null, 2)};`, 'const layoutKeys = new Set(["layoutHeaderHeight", "layoutSiderBackground", "layoutBodyBackground"]);', "export const yssLayoutTokens = Object.fromEntries(Object.entries(source.token ?? {}).filter(([key]) => layoutKeys.has(key)));", "const seed = Object.fromEntries(Object.entries(source.token ?? {}).filter(([key]) => !layoutKeys.has(key)));", "export function createYssTheme({ dark = false } = {}) {", "  return { algorithm: dark ? [theme.darkAlgorithm, theme.compactAlgorithm] : [theme.defaultAlgorithm, theme.compactAlgorithm], token: seed };", "}", ""].join("\n");
+  await writeFile(path.join(resolvedRoot, "src/yss-theme.js"), generated);
+  const manifest = { schema_version: 3, feature, prototype_profile: "H2", profile_kind: "flow-review", design_standard: "yss-antdv-next", component_basis: "vue-antdv-next", framework: "vue", library: { package: "antdv-next", version: libraryVersion }, framework_packages: { vue: vueVersion, vite: viteVersion, "@vitejs/plugin-vue": vuePluginVersion }, package_manager: `pnpm@${pnpmVersion}`, fact_pack_ref: factPackRef, theme_source: "docs/design/tokens/theme.json", theme_adapter: `docs/.scratch/${feature}/design/prototypes/src/yss-theme.js`, next_commands: ["pnpm install", "pnpm build"] };
+  await writeFile(path.join(resolvedRoot, "yss-prototype-adapter.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+async function prepareReactFlowPrototype({ projectRoot, root, feature, targetAntdVersion, pnpmVersion }) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
   if (!antdSemver.test(targetAntdVersion ?? "")) throw new TypeError("targetAntdVersion 必须是明确的 antd 6.x semver");
   if (!exactSemver.test(pnpmVersion ?? "")) throw new TypeError("pnpmVersion 必须是明确 semver");
@@ -218,29 +292,62 @@ export async function prepareFlowPrototype({ projectRoot, root, feature, targetA
   return manifest;
 }
 
+export async function prepareFlowPrototype({ projectRoot, root, feature, componentBasis, libraryVersion, targetAntdVersion, pnpmVersion, vueVersion = DEFAULT_VUE_VERSION, viteVersion = DEFAULT_VITE_VERSION, vuePluginVersion = DEFAULT_VUE_PLUGIN_VERSION, factPackRef }) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
+  const resolvedBasis = componentBasis ?? (targetAntdVersion ? "react-antd-6" : DEFAULT_H2_COMPONENT_BASIS);
+  if (!H2_COMPONENT_BASES.has(resolvedBasis)) throw new TypeError(`componentBasis 必须为 ${[...H2_COMPONENT_BASES].join("/")}`);
+  if (resolvedBasis === "react-antd-6") return prepareReactFlowPrototype({ projectRoot, root, feature, targetAntdVersion: targetAntdVersion ?? libraryVersion, pnpmVersion });
+  const resolvedLibraryVersion = libraryVersion ?? DEFAULT_ANTDV_NEXT_VERSION;
+  return prepareVueFlowPrototype({ projectRoot, root, feature, libraryVersion: resolvedLibraryVersion, pnpmVersion, vueVersion, viteVersion, vuePluginVersion, factPackRef: factPackRef ?? `docs/design/facts/antdv-next/${resolvedLibraryVersion}/manifest.json` });
+}
+
 export const preparePrototype = prepareFlowPrototype;
 
-export async function validatePrototypeProject({ root, profile = "H2", targetAntdVersion }) {
+export async function validatePrototypeProject({ root, profile = "H2", componentBasis, libraryVersion, targetAntdVersion }) {
   const errors = [];
   if (!Object.hasOwn(PROFILE_KIND, profile)) return { errors: ["profile 必须为 H1/H2"] };
   if (!existsSync(path.join(root, "index.html"))) errors.push("缺少浏览器入口 index.html");
   if (!existsSync(path.join(root, "yss-prototype-adapter.json"))) errors.push("缺少 yss-prototype-adapter.json");
   if (profile === "H1") {
     for (const forbidden of ["package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock"] ) if (existsSync(path.join(root, forbidden))) errors.push(`H1 不得依赖 ${forbidden}`);
-    if (!existsSync(path.join(root, "styles.css"))) errors.push("H1 缺少 styles.css");
+    const stylesPath = path.join(root, "styles.css");
+    if (!existsSync(stylesPath)) errors.push("H1 缺少 styles.css");
+    else {
+      const styles = await readFile(stylesPath, "utf8");
+      for (const token of ["--brand-font-family", "--brand-color-text", "--brand-color-bg-layout", "--brand-color-bg-container", "--yss-color-primary-control", "--yss-control-height-compact"]) if (!styles.includes(token)) errors.push(`H1 styles.css 未消费项目 Token ${token}`);
+      for (const staleAlias of ["--font-family", "--layout-background", "--container-background", "--brand-primary"]) if (styles.includes(staleAlias)) errors.push(`H1 styles.css 使用过时变量 ${staleAlias}`);
+      for (const hardcodedDeclaration of ["padding:24px", "padding:20px", "min-height:32px", "border-radius:8px", "border-radius:6px"]) if (styles.includes(hardcodedDeclaration)) errors.push(`H1 styles.css 硬编码视觉基线 ${hardcodedDeclaration}`);
+    }
     return { errors };
   }
   const packagePath = path.join(root, "package.json");
   if (!existsSync(packagePath)) return { errors: [...errors, "缺少 package.json"] };
   const pkg = JSON.parse(await readFile(packagePath, "utf8"));
   if (profile === "H2") {
-    if (targetAntdVersion) {
-      if (pkg.dependencies?.antd !== targetAntdVersion) errors.push(`package.json 必须精确锁定 antd ${targetAntdVersion}`);
-      if (!antdSemver.test(targetAntdVersion)) errors.push("targetAntdVersion 必须是 antd 6.x semver");
+    const adapterPath = path.join(root, "yss-prototype-adapter.json");
+    const adapter = existsSync(adapterPath) ? JSON.parse(await readFile(adapterPath, "utf8")) : {};
+    const resolvedBasis = componentBasis ?? (targetAntdVersion ? "react-antd-6" : adapter.component_basis ?? (adapter.prototype_framework === "react" ? "react-antd-6" : DEFAULT_H2_COMPONENT_BASIS));
+    if (resolvedBasis === "react-antd-6") {
+      const resolvedVersion = targetAntdVersion ?? libraryVersion ?? adapter.target_antd_version;
+      if (pkg.dependencies?.antd !== resolvedVersion) errors.push(`package.json 必须精确锁定 antd ${resolvedVersion}`);
+      if (!antdSemver.test(resolvedVersion ?? "")) errors.push("React H2 libraryVersion 必须是 antd 6.x semver");
       if (!existsSync(path.join(root, "src/yss-theme.js"))) errors.push("React/AntD H2 缺少 src/yss-theme.js");
       const sourceFiles = ["src/App.jsx", "src/App.tsx", "src/main.jsx", "src/main.tsx"].filter((file) => existsSync(path.join(root, file)));
       const source = (await Promise.all(sourceFiles.map((file) => readFile(path.join(root, file), "utf8")))).join("\n");
       if (!/ConfigProvider/.test(source) || !/yssTheme/.test(source)) errors.push("React/AntD H2 入口必须通过 ConfigProvider 消费 yssTheme");
+    } else if (resolvedBasis === "vue-antdv-next") {
+      const resolvedVersion = libraryVersion ?? adapter.library?.version ?? DEFAULT_ANTDV_NEXT_VERSION;
+      if (pkg.dependencies?.["antdv-next"] !== resolvedVersion) errors.push(`package.json 必须精确锁定 antdv-next ${resolvedVersion}`);
+      if (!exactSemver.test(resolvedVersion ?? "")) errors.push("Vue H2 libraryVersion 必须是明确 semver");
+      for (const [name, expected] of Object.entries(adapter.framework_packages ?? {})) if (pkg.dependencies?.[name] !== expected) errors.push(`package.json 必须精确锁定 ${name} ${expected}`);
+      for (const file of ["vite.config.mjs", "src/main.js", "src/App.vue", "src/yss-theme.js"]) if (!existsSync(path.join(root, file))) errors.push(`Vue/Antdv Next H2 缺少 ${file}`);
+      const sourceFiles = ["src/App.vue", "src/main.js", "src/yss-theme.js"].filter((file) => existsSync(path.join(root, file)));
+      const source = (await Promise.all(sourceFiles.map((file) => readFile(path.join(root, file), "utf8")))).join("\n");
+      if (!/a-config-provider/.test(source) || !/yssTheme/.test(source)) errors.push("Vue/Antdv Next H2 必须通过 ConfigProvider 消费 yssTheme");
+      if (!/compactAlgorithm/.test(source)) errors.push("Vue/Antdv Next H2 主题必须消费 compactAlgorithm");
+      if (adapter.schema_version !== 3 || adapter.component_basis !== "vue-antdv-next" || adapter.framework !== "vue") errors.push("Vue/Antdv Next H2 adapter manifest 必须使用 provider-neutral schema v3");
+    } else {
+      errors.push(`不支持的 H2 component basis: ${resolvedBasis}`);
     }
     if (!String(pkg.packageManager ?? "").startsWith("pnpm@")) errors.push("H2 package.json 必须记录实际 pnpm packageManager");
     if (!existsSync(path.join(root, "pnpm-lock.yaml"))) errors.push("H2 缺少 pnpm-lock.yaml");
@@ -275,11 +382,11 @@ async function main(argv) {
     return;
   }
   if (["prepare", "prepare-flow"].includes(command)) {
-    process.stdout.write(`${JSON.stringify(await prepareFlowPrototype({ projectRoot: parsed["project-root"], root: parsed.root, feature: parsed.feature, targetAntdVersion: parsed["target-antd-version"], pnpmVersion: parsed["pnpm-version"] }), null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(await prepareFlowPrototype({ projectRoot: parsed["project-root"], root: parsed.root, feature: parsed.feature, componentBasis: parsed["component-basis"], libraryVersion: parsed["library-version"], targetAntdVersion: parsed["target-antd-version"], pnpmVersion: parsed["pnpm-version"], vueVersion: parsed["vue-version"] ?? DEFAULT_VUE_VERSION, viteVersion: parsed["vite-version"] ?? DEFAULT_VITE_VERSION, vuePluginVersion: parsed["vue-plugin-version"] ?? DEFAULT_VUE_PLUGIN_VERSION, factPackRef: parsed["fact-pack-ref"] }), null, 2)}\n`);
     return;
   }
   if (command === "validate-project") {
-    const result = await validatePrototypeProject({ root: parsed.root, profile: parsed.profile ?? "H2", targetAntdVersion: parsed["target-antd-version"] });
+    const result = await validatePrototypeProject({ root: parsed.root, profile: parsed.profile ?? "H2", componentBasis: parsed["component-basis"], libraryVersion: parsed["library-version"], targetAntdVersion: parsed["target-antd-version"] });
     if (result.errors.length > 0) throw new TypeError(result.errors.join("\n"));
     process.stdout.write("prototype project contract passed\n");
     return;