create-yss-spec 3.5.3 → 3.5.5

package/template/.pi/skills/yss-prototype-stage/scripts/build-shadcn-vue-prototype.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync, readFileSync, lstatSync } from 'node:fs';
+// Author-side build; only the fully verified offline package is published.
+import {readFile,writeFile,mkdir,mkdtemp,rm,cp,rename,lstat,realpath} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import {fileURLToPath,pathToFileURL} from 'node:url';
+import path from 'node:path';
+import {prepareOfflineHtml,sealOfflineHtml,resourceErrors,assertPrototypeTarget} from './offline-html.mjs';
+import {localPath,parseScenarios} from './scenario-contract.mjs';
+const assets=path.resolve(fileURLToPath(new URL('../assets/shadcn-vue-authoring/',import.meta.url)));
+const sha=bytes=>`sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const escape=text=>text.replace(/[<>&"]/g,c=>({'<':'&lt;','>':'&gt;','&':'&amp;','"':'&quot;'}[c]));
+export async function verifyShadcnVueSources(){
+ const registry=JSON.parse(await readFile(path.join(assets,'registry-manifest.json'),'utf8'));
+ if(registry.repository!=='https://github.com/unovue/shadcn-vue'||!/^[a-f0-9]{40}$/.test(registry.revision))throw Error('缺少固定 shadcn-vue revision');
+ for(const c of registry.components)if(!/^ui\/[a-z-]+\/[A-Za-z]+\.(?:vue|ts)$/.test(c.path)||sha(await readFile(path.join(assets,c.path)))!==c.digest)throw Error(`shadcn 组件源码摘要不匹配: ${c.path}`);
+ return registry;
+}
+export async function buildShadcnVuePrototype({projectRoot,root,feature,toolchain,entry,config,density,profile='H2'}){
+ if(!['H1','H2'].includes(profile))throw Error('profile 必须为 H1/H2');
+ if(!toolchain)throw Error('需要独立作者工具目录 toolchain；不要在共享 Skill 内安装依赖');
+ if(config&&entry)throw Error('--config 与 --entry 互斥');
+ projectRoot=path.resolve(projectRoot);root=path.resolve(root);toolchain=await realpath(toolchain);
+ await assertPrototypeTarget({projectRoot,root,feature});
+ let authorRoot=entry?path.dirname(path.resolve(entry)):path.resolve(assets,'../vue-business-patterns'),entryRef=entry?path.basename(entry):'workbench.ts',title='查询与详情';
+ let scenarios=fileURLToPath(new URL('../assets/vue-business-patterns/list-detail.scenarios.json',import.meta.url));
+ if(config){config=path.resolve(config);authorRoot=path.dirname(config);const c=JSON.parse(await readFile(await localPath(authorRoot,path.basename(config)),'utf8'));
+  if(c.schema_version!==1||!c.title?.trim()||Object.keys(c).some(k=>!['schema_version','title','entry','scenarios','density'].includes(k)))throw Error('作者配置需要 schema_version=1、title、entry、scenarios，可选 density');
+  density ??= c.density;
+  title=c.title;entryRef=c.entry;scenarios=await localPath(authorRoot,c.scenarios);
+ }
+ density ??= 'compact';
+ if(!['compact','comfortable'].includes(density))throw Error('density 必须为 compact/comfortable');
+ authorRoot=await realpath(authorRoot);
+ const entryPath=await localPath(authorRoot,entryRef),source=await readFile(entryPath,'utf8'),scenarioBytes=await readFile(scenarios);parseScenarios(scenarioBytes);
+ const expected=JSON.parse(await readFile(path.join(assets,'package.json'),'utf8')),packages={...expected.dependencies,...expected.devDependencies};
+ for(const [name,version] of Object.entries(packages))if(JSON.parse(await readFile(path.join(toolchain,'node_modules',name,'package.json'),'utf8')).version!==version)throw Error(`${name} 需要锁定 ${version}`);
+ const lock=await readFile(path.join(assets,'pnpm-lock.yaml'));
+ if(sha(await readFile(path.join(toolchain,'pnpm-lock.yaml')))!==sha(lock))throw Error('作者工具 pnpm lock 与技能基线不匹配');
+ const registry=await verifyShadcnVueSources(),theme=(await readFile(path.join(assets,'../prototype-theme.css'),'utf8'))+'\n'+await readFile(path.join(assets,'theme.css'),'utf8');
+ const require=createRequire(path.join(toolchain,'package.json')),{build}=require('esbuild');
+ const {parse,compileScript,compileTemplate,compileStyleAsync,registerTS}=require('@vue/compiler-sfc');
+ registerTS(()=>require('typescript'));
+ const typePath=p=>p.includes('/node_modules/')?path.join(toolchain,'node_modules',p.split('/node_modules/').slice(1).join('/node_modules/')):p;
+ const authored=new Map(),vueStyles=new Map();
+ // compiler-sfc reads type-only imports itself, outside esbuild's module hooks.
+ // Apply the same source boundary and capture those inputs in provenance.
+ function boundedTypeFile(request){
+  const file=path.resolve(typePath(request));
+  const base=[toolchain,assets,authorRoot].find(root=>file.startsWith(root+path.sep));
+  if(!base||!existsSync(file))return null;
+  const physical=realpathSync(file);if(!physical.startsWith(base+path.sep))return null;
+  if(base!==toolchain)for(let cursor=file;cursor!==base;cursor=path.dirname(cursor))if(lstatSync(cursor).isSymbolicLink())return null;
+  return {file,base};
+ }
+ const typeFs={fileExists:p=>!!boundedTypeFile(p),readFile:p=>{
+  const item=boundedTypeFile(p);if(!item)throw Error('Vue 类型来源越出作者或锁定依赖目录');
+  const bytes=readFileSync(item.file);
+  if(item.base===authorRoot)authored.set(item.file,{rel:path.relative(authorRoot,item.file).split(path.sep).join('/'),bytes});
+  return bytes.toString('utf8');
+ }};
+ const result=await build({absWorkingDir:authorRoot,entryPoints:[entryPath],outdir:path.join(authorRoot,'.bundle'),entryNames:'app',assetNames:'assets/[name]-[hash]',bundle:true,write:false,format:'iife',platform:'browser',target:['chrome110'],minify:true,metafile:true,legalComments:'eof',nodePaths:[path.join(toolchain,'node_modules')],loader:{'.png':'file','.jpg':'file','.jpeg':'file','.svg':'file','.webp':'file','.gif':'file'},define:{'process.env.NODE_ENV':'"production"',__VUE_OPTIONS_API__:'true',__VUE_PROD_DEVTOOLS__:'false',__VUE_PROD_HYDRATION_MISMATCH_DETAILS__:'false'},plugins:[{name:'bounded-authoring',setup(b){
+  b.onResolve({filter:/^vue-style:/},args=>({path:args.path,namespace:'vue-style'}));
+  b.onLoad({filter:/.*/,namespace:'vue-style'},args=>({...vueStyles.get(args.path),loader:'css'}));
+  b.onResolve({filter:/^(?:@\/lib\/utils$|@\/(?:components|registry\/new-york-v4)\/ui\/)/},args=>{
+   const file=args.path==='@/lib/utils'?'utils.ts':`ui/${args.path.split('/').at(-1)}/index.ts`;
+   if(file!=='utils.ts'&&!registry.components.some(x=>x.path===file))throw Error(`未收录组件 ${file}`);
+   return {path:path.join(assets,file)};
+  });
+  b.onResolve({filter:/^[^./]/},args=>{if(args.path.startsWith('@/'))throw Error(`未登记别名: ${args.path}`);if(!args.importer.includes('/node_modules/')){const name=args.path.startsWith('@')?args.path.split('/').slice(0,2).join('/'):args.path.split('/')[0];if(!Object.hasOwn(packages,name))throw Error(`未登记依赖: ${name}`);}return;});
+  b.onLoad({filter:/.*/},async args=>{
+   if(args.path.includes(`${path.sep}node_modules${path.sep}`))return;
+   const trusted=args.path.startsWith(assets+path.sep),base=trusted?assets:authorRoot,rel=path.relative(base,args.path).split(path.sep).join('/');
+   await localPath(base,rel);
+   const bytes=await readFile(args.path),ext=path.extname(args.path);
+   if(!/\.(?:vue|tsx?|jsx?|json|css|png|jpe?g|svg|webp|gif)$/.test(ext))throw Error(`未支持作者资源: ${rel}`);
+   if(/\.(?:vue|tsx?|jsx?|css)$/.test(ext)){const errors=resourceErrors(rel,bytes.toString(),{}).filter(e=>!e.includes('资源缺失或越出交付包'));if(errors.length)throw Error(errors.join('\n'));}
+   if(!trusted||args.path===entryPath)authored.set(args.path,{rel,bytes});
+   if(ext==='.vue'){
+    const {descriptor,errors}=parse(bytes.toString(),{filename:args.path});if(errors.length)throw errors[0];
+    if(descriptor.customBlocks.length||[descriptor.script,descriptor.scriptSetup,descriptor.template,...descriptor.styles].some(x=>x?.src)||descriptor.template?.lang&&descriptor.template.lang!=='html'||descriptor.styles.some(x=>x.lang&&x.lang!=='css'||x.module))throw Error('Vue 作者仅支持本地内联 script/template/CSS；不执行预处理器或自定义块');
+    const id='data-v-'+sha(bytes).slice(7,19),scoped=descriptor.styles.some(x=>x.scoped);
+    let contents;
+    if(descriptor.script||descriptor.scriptSetup){const compiled=compileScript(descriptor,{id,genDefaultAs:'__sfc__',inlineTemplate:true,fs:typeFs,templateOptions:{compilerOptions:{scopeId:scoped?id:undefined}}});contents=compiled.content;if(!descriptor.scriptSetup&&descriptor.template){const tpl=compileTemplate({source:descriptor.template.content,filename:args.path,id,scoped,compilerOptions:{bindingMetadata:compiled.bindings}});if(tpl.errors.length)throw tpl.errors[0];contents+='\n'+tpl.code.replace('export function render','function render')+'\n__sfc__.render=render;';}}
+    else {const tpl=compileTemplate({source:descriptor.template?.content||'',filename:args.path,id,scoped});if(tpl.errors.length)throw tpl.errors[0];contents=tpl.code.replace('export function render','function render')+'\nconst __sfc__={render};';}
+    for(let i=0;i<descriptor.styles.length;i++){const style=descriptor.styles[i];const result=await compileStyleAsync({source:style.content,filename:args.path,id,scoped:style.scoped});if(result.errors.length)throw result.errors[0];const key=`vue-style:${id}-${i}`;vueStyles.set(key,{contents:result.code,resolveDir:path.dirname(args.path)});contents+=`\nimport ${JSON.stringify(key)};`;}
+    if(scoped)contents+=`\n__sfc__.__scopeId=${JSON.stringify(id)};`;
+    return {contents:contents+'\nexport default __sfc__;',loader:'ts',resolveDir:path.dirname(args.path)};
+   }
+   return;
+  });
+ }}]});
+ // Every resolved package must belong to the declared dependency closure.
+ const roots=new Set();
+ for(const input of Object.keys(result.metafile.inputs)){
+  const absolute=path.resolve(authorRoot,input);if(!absolute.includes(`${path.sep}node_modules${path.sep}`))continue;
+  if(!absolute.startsWith(toolchain+path.sep))throw Error('依赖必须来自锁定作者工具目录');
+  let current=path.dirname(absolute);
+  while(current!==path.dirname(current)){try{const pkg=JSON.parse(await readFile(path.join(current,'package.json'),'utf8'));if(pkg.name&&pkg.version){roots.add(current);break;}}catch{}current=path.dirname(current);}
+ }
+ const notices=[`shadcn-vue @ ${registry.revision}\n${await readFile(path.join(assets,'SHADCN-LICENSE.txt'),'utf8')}`];
+ for(const base of [...roots].sort()){
+  const pkg=JSON.parse(await readFile(path.join(base,'package.json'),'utf8'));let license;
+  for(const name of ['LICENSE','LICENSE.md','LICENSE.txt','license','license.md'])try{license=await readFile(path.join(base,name),'utf8');break;}catch{}
+  if(!license){const records=JSON.parse(await readFile(path.join(assets,'licenses/sources.json'),'utf8')),record=records.find(r=>r.package===pkg.name&&r.version===pkg.version);if(record){license=await readFile(path.join(assets,'licenses',record.file),'utf8');if(sha(license)!==record.digest)throw Error('补充许可证摘要不匹配');}}
+  if(!license)throw Error(`缺少已打包依赖的许可文件 ${pkg.name}`);notices.push(`${pkg.name}@${pkg.version}\n${license}`);
+ }
+ const stagingParent=path.join(path.dirname(root),'build');await mkdir(stagingParent,{recursive:true});const temp=await mkdtemp(path.join(stagingParent,'.prototype-'));
+ try{
+  const project=path.join(temp,'project'),out=path.join(project,`docs/.scratch/${feature}/design/prototypes`);
+  await mkdir(path.join(project,'.template-spec/design/tokens'),{recursive:true});for(const ref of ['DESIGN.md','.template-spec/design/tokens/variables.css'])await cp(path.join(projectRoot,ref),path.join(project,ref));
+  await writeFile(path.join(temp,'scenarios.json'),scenarioBytes);
+  const manifest=await prepareOfflineHtml({projectRoot:project,root:out,feature,profile,pattern:'workbench',scenarios:path.join(temp,'scenarios.json'),title,density});
+  // Only files in the actual module closure participate in Tailwind scanning.
+  let css=`@import ${JSON.stringify(path.join(toolchain,'node_modules/tailwindcss/index.css'))} source(none);\n@source ${JSON.stringify(path.join(assets,'ui'))};\n`;
+  for(const [absolute,item] of authored)if(/\.(?:vue|[jt]sx?)$/.test(absolute))css+=`@source ${JSON.stringify(absolute)};\n`;
+  await writeFile(path.join(temp,'input.css'),css+theme);
+  const cli=JSON.parse(await readFile(path.join(toolchain,'node_modules/@tailwindcss/cli/package.json'),'utf8'));
+  execFileSync(process.execPath,[path.join(toolchain,'node_modules/@tailwindcss/cli',cli.bin.tailwindcss),'-i',path.join(temp,'input.css'),'-o',path.join(temp,'styles.css'),'--minify'],{cwd:toolchain,stdio:'pipe'});
+  let styles=await readFile(path.join(temp,'styles.css'),'utf8');
+  for(const file of result.outputFiles){const ref=path.relative(path.join(authorRoot,'.bundle'),file.path);if(ref==='app.css'){styles+='\n'+file.text;continue;}const target=await localPath(out,ref);await mkdir(path.dirname(target),{recursive:true});await writeFile(target,file.contents);}
+  await writeFile(path.join(out,'styles.css'),styles);
+  await writeFile(path.join(out,'index.html'),`<!doctype html><html lang="zh-CN" data-density="${density}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(title)}</title><link rel="stylesheet" href="./tokens.css"><link rel="stylesheet" href="./styles.css"><script src="./scenarios.js"></script><script src="./scenario-runtime.js"></script><script defer src="./app.js"></script></head><body><div id="app"></div></body></html>`);
+  const authoredFiles={};
+  for(const {rel,bytes} of authored.values()){const ref=`authoring-sources/${rel}`,target=await localPath(out,ref);await mkdir(path.dirname(target),{recursive:true});await writeFile(target,bytes);authoredFiles[ref]=sha(bytes);}
+  await mkdir(path.join(out,'component-sources'));
+  for(const item of registry.components){const target=path.join(out,'component-sources',item.path);await mkdir(path.dirname(target),{recursive:true});await cp(path.join(assets,item.path),target);}
+  await cp(path.join(assets,'utils.ts'),path.join(out,'component-sources/utils.ts'));await cp(path.join(assets,'registry-manifest.json'),path.join(out,'registry-manifest.json'));
+  const buildBasis={packages,lock_digest:sha(lock),source_digest:sha(source),theme_digest:sha(theme),registry_digest:sha(await readFile(path.join(assets,'registry-manifest.json'))),registry_revision:registry.revision,component_groups:registry.component_groups,used_component_files:registry.components.filter(c=>Object.keys(result.metafile.inputs).some(p=>path.resolve(authorRoot,p)===path.join(assets,c.path))).map(c=>c.path),support_source_digests:{'utils.ts':sha(await readFile(path.join(assets,'utils.ts')))},authored_files:authoredFiles,format:'iife',browser_runtime:'vue',toolchain_required_by_recipient:false};
+  await writeFile(path.join(out,'authoring-source.ts'),source);await writeFile(path.join(out,'token-theme.css'),theme);await writeFile(path.join(out,'build-provenance.json'),JSON.stringify(buildBasis,null,2)+'\n');await writeFile(path.join(out,'THIRD-PARTY-NOTICES.txt'),notices.join('\n\n'));
+  await writeFile(path.join(out,'yss-prototype-adapter.json'),JSON.stringify({...manifest,component_basis:'vue-shadcn-prebuilt',build_provenance:buildBasis},null,2));
+  const sealed=await sealOfflineHtml(out,profile);await assertPrototypeTarget({projectRoot,root,feature});await rename(out,root);return sealed;
+ }finally{await rm(temp,{recursive:true,force:true});}
+}
+if(process.argv[1]&&existsSync(process.argv[1])&&pathToFileURL(realpathSync(process.argv[1])).href===import.meta.url){const args={};for(let i=2;i<process.argv.length;i+=2){if(!process.argv[i].startsWith('--')||!process.argv[i+1])throw Error('参数必须是 --key value');args[process.argv[i].slice(2)]=process.argv[i+1];}const projectRoot=path.resolve(args['project-root']||'.');const root=args.root||path.join(projectRoot,'docs/.scratch',args.feature||'','design/prototypes');console.log(JSON.stringify(await buildShadcnVuePrototype({projectRoot,root,feature:args.feature,profile:args.profile,toolchain:args.toolchain,entry:args.entry,config:args.config,density:args.density}),null,2));}

package/template/.pi/skills/yss-prototype-stage/scripts/compose-workspace-scenarios.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import {readFile,writeFile} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import {fileURLToPath,pathToFileURL} from 'node:url';
+import {parseScenarios} from './scenario-contract.mjs';
+const base=new URL('../assets/vue-business-patterns/',import.meta.url);
+const names=['list-detail','multi-step','approval','conflict','analysis','combined-query','owner-validity'];
+export async function composeWorkspaceScenarios() {
+ const inputs=Object.fromEntries(await Promise.all(names.map(async name=>{const bytes=await readFile(new URL(name+'.scenarios.json',base));return [name,{doc:parseScenarios(bytes),digest:'sha256:'+createHash('sha256').update(bytes).digest('hex')}]})));
+ const modes=[['primary','正常工作区',{}],['exceptions','失败与冲突恢复',{'multi-step':'failure',approval:'failure',conflict:'conflict','combined-query':'failure','owner-validity':'failure'}],['no-permission','只读与权限',{'list-detail':'no-permission','multi-step':'no-permission',approval:'no-permission',conflict:'no-permission','combined-query':'no-permission','owner-validity':'no-permission'}],['empty','空结果',{'list-detail':'empty',approval:'empty',analysis:'empty','combined-query':'empty'}]];
+ return {schema_version:1,scenarios:modes.map(([id,label,overrides])=>({id,label,state_ref:'.agents/skills/yss-prototype-stage/references/enterprise-workspace.md',initial_data:{pages:Object.fromEntries(names.map(name=>{
+   const selected=inputs[name].doc.scenarios.find(s=>s.id===(overrides[name]||'primary'));
+   if(!selected)throw Error(`缺少明确来源 ${name}/${overrides[name]}`);
+   return [name,{...selected,source_ref:`authoring-sources/${name}.scenarios.json`,source_digest:inputs[name].digest}];
+ }))}}))};
+}
+if(process.argv[1]&&pathToFileURL(process.argv[1]).href===import.meta.url) {
+ const target=fileURLToPath(new URL('workspace.scenarios.json',base));const bytes=JSON.stringify(await composeWorkspaceScenarios(),null,2)+'\n';
+ if(process.argv.includes('--check')){if(await readFile(target,'utf8')!==bytes)throw Error('工作区场景与来源漂移');console.log('工作区场景来源一致');}
+ else if(process.argv.includes('--write')){await writeFile(target,bytes);console.log('已组合工作区场景');}
+ else throw Error('需要 --check 或 --write');
+}

package/template/.pi/skills/yss-prototype-stage/scripts/export-business-patterns.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import {pathToFileURL} from 'node:url';
+import path from 'node:path';
+import {exportVuePatterns} from './export-vue-patterns.mjs';
+export const exportBusinessPatterns=exportVuePatterns;
+if(process.argv[1]&&existsSync(process.argv[1])&&import.meta.url===pathToFileURL(realpathSync(process.argv[1])).href){const args={};for(let i=2;i<process.argv.length;i+=2)args[process.argv[i].slice(2)]=process.argv[i+1];console.log(JSON.stringify(await exportBusinessPatterns({projectRoot:path.resolve(args['project-root']||'.'),output:args.output,toolchain:args.toolchain})));}

package/template/.pi/skills/yss-prototype-stage/scripts/export-low-fidelity-exercise.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import {mkdtemp,mkdir,cp,readFile,writeFile,readdir,rename,rm} from 'node:fs/promises';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {writeScenarios} from './scenario-contract.mjs';
+import {prepareComparison} from './prototype-comparison.mjs';
+export async function exportLowFidelityExercise({projectRoot,output}){
+ output=path.resolve(output);try{if((await readdir(output)).length)throw Error('目标非空，拒绝覆盖');}catch(e){if(e.code!=='ENOENT')throw e;}
+ await mkdir(path.dirname(output),{recursive:true});const temp=await mkdtemp(path.join(path.dirname(output),'.low-fidelity-'));
+ try{await mkdir(path.join(temp,'.template-spec/design/tokens'),{recursive:true});for(const ref of ['DESIGN.md','.template-spec/design/tokens/variables.css'])await cp(path.join(projectRoot,ref),path.join(temp,ref));
+  const doc=JSON.parse(await readFile(new URL('../assets/native-workbench/scenarios.json',import.meta.url)));doc.scenarios=doc.scenarios.filter(s=>['primary','failure'].includes(s.id));for(const s of doc.scenarios)s.state_ref='comparison-record.md';
+  const bytes=JSON.stringify(doc,null,2)+'\n';await writeFile(path.join(temp,'shared.json'),bytes);await cp(new URL('../references/low-fidelity-exercise.md',import.meta.url),path.join(temp,'record.md'));
+  for(const mode of ['single','batch','queue']){const root=path.join(temp,mode);await writeScenarios(root,bytes);for(const file of ['index.html','styles.css','app.js'])await writeFile(path.join(root,file),(await readFile(new URL(`../assets/low-fidelity-exercise/${file}`,import.meta.url),'utf8')).replaceAll('__MODE__',mode));await cp(path.join(temp,'.template-spec/design/tokens/variables.css'),path.join(root,'tokens.css'));}
+  const input={schema_version:2,comparison_id:'low-fidelity-exercise',title:'低保真：资料审批组织方式',comparison_ref:'record.md',scenario_ref:'shared.json',cases:[{id:'normal',label:'正常处理',scenario:'primary'},{id:'retry',label:'失败恢复',scenario:'failure'}],variants:['single','batch','queue'].map((id,i)=>({id,label:['逐项处理','批量处理','引导队列'][i],root:id,entry:'index.html',cases:['normal','retry']}))};await writeFile(path.join(temp,'input.json'),JSON.stringify(input));const result=await prepareComparison({projectRoot:temp,feature:'exercise',input:'input.json'});await rename(result.root,output);return {root:output,entry:path.join(output,'index.html')};
+ }finally{await rm(temp,{recursive:true,force:true});}
+}
+if(process.argv[1]&&existsSync(process.argv[1])&&import.meta.url===pathToFileURL(realpathSync(process.argv[1])).href){const args={};for(let i=2;i<process.argv.length;i+=2)args[process.argv[i].slice(2)]=process.argv[i+1];console.log(JSON.stringify(await exportLowFidelityExercise({projectRoot:path.resolve(args['project-root']||'.'),output:args.output})));}

package/template/.pi/skills/yss-prototype-stage/scripts/export-vue-patterns.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import {mkdtemp,mkdir,cp,writeFile,readdir,rename,rm} from 'node:fs/promises';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {buildShadcnVuePrototype} from './build-shadcn-vue-prototype.mjs';
+const catalog={workspace:'企业多页工作区','component-states':'组件状态展示'};
+const patterns={'list-detail':'查询与详情','multi-step':'分步表单','approval':'审批与权限',conflict:'冲突与恢复',analysis:'高密度分析','combined-query':'组合查询','owner-validity':'负责人及有效期表单'};
+export async function exportVuePatterns({projectRoot,output,toolchain}){
+ output=path.resolve(output);try{if((await readdir(output)).length)throw Error('目标非空，拒绝覆盖');}catch(e){if(e.code!=='ENOENT')throw e;}
+ await mkdir(path.dirname(output),{recursive:true});const temp=await mkdtemp(path.join(path.dirname(output),'.business-patterns-'));
+ try{
+  const fixture=path.join(temp,'fixture'),bundle=path.join(temp,'bundle');await mkdir(path.join(fixture,'.template-spec/design/tokens'),{recursive:true});await mkdir(bundle);
+  for(const ref of ['DESIGN.md','.template-spec/design/tokens/variables.css'])await cp(path.join(projectRoot,ref),path.join(fixture,ref));
+  for(const name of Object.keys({...patterns,...catalog})){const root=path.join(fixture,`docs/.scratch/${name}/design/prototypes`);await buildShadcnVuePrototype({projectRoot:fixture,root,feature:name,toolchain,config:new URL(`../assets/vue-business-patterns/${name}-standard.config.json`,import.meta.url).pathname});await cp(root,path.join(bundle,name),{recursive:true});}
+  await cp(path.join(projectRoot,'.template-spec/design/tokens/variables.css'),path.join(bundle,'tokens.css'));
+  await writeFile(path.join(bundle,'index.html'),`<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Vue 企业页面模式</title><link rel="stylesheet" href="tokens.css"><style>body{font-family:var(--brand-font-family);color:var(--brand-color-text);background:var(--brand-color-bg-layout);padding:var(--brand-size-lg)}a{color:var(--yss-color-primary-control)}li{margin-block:var(--brand-size)}</style><h1>Vue 企业页面模式</h1><p>维护教学示例；场景及保存结果为本地模拟，不代表已批准产品。</p><ul>${Object.entries({...patterns,...catalog}).map(([id,label])=>`<li><a href="${id}/index.html">${label}</a></li>`).join('')}</ul></html>`);
+  await rename(bundle,output);return {root:output,entry:path.join(output,'index.html'),patterns:Object.keys(patterns)};
+ }finally{await rm(temp,{recursive:true,force:true});}
+}
+if(process.argv[1]&&existsSync(process.argv[1])&&import.meta.url===pathToFileURL(realpathSync(process.argv[1])).href){const args={};for(let i=2;i<process.argv.length;i+=2)args[process.argv[i].slice(2)]=process.argv[i+1];console.log(JSON.stringify(await exportVuePatterns({projectRoot:path.resolve(args['project-root']||'.'),output:args.output,toolchain:args.toolchain})));}

package/template/.pi/skills/yss-prototype-stage/scripts/offline-html.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile, readdir, lstat } from "node:fs/promises";
 import path from "node:path";
+import {writeScenarios,scenarioScript} from "./scenario-contract.mjs";
 
 const manifestName = "yss-prototype-adapter.json";
 const sha = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
@@ -20,17 +21,17 @@ async function inventory(root, relative = "") {
   return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b, "en")));
 }
 
-function resourceErrors(file, text, files) {
+export function resourceErrors(file, text, files) {
   const errors = [];
   const refs = [];
-  if (/\.html?$/i.test(file)) {
+  if (/\.(?:html?|vue)$/i.test(file)) {
     for (const tag of text.matchAll(/<(?:script|link|img|source|iframe|video|audio|object|embed)\b[^>]*>/gi)) {
-      for (const attr of tag[0].matchAll(/\b(?:src|href|poster|data)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) refs.push(attr[1] ?? attr[2] ?? attr[3]);
+      for (const attr of tag[0].matchAll(/(?<![:\w-])\b(?:src|href|poster|data)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) refs.push(attr[1] ?? attr[2] ?? attr[3]);
       if (/\bsrcset\s*=/i.test(tag[0])) errors.push(`${file}: 离线包请使用明确的本地 src，srcset 需先转换并复验`);
     }
     if (/<base\b/i.test(text) || /<script\b[^>]*\btype\s*=\s*["']?module\b/i.test(text)) errors.push(`${file}: file:// 交付不使用 base 或 module script`);
   }
-  if (/\.(?:css|html?)$/i.test(file)) {
+  if (/\.(?:css|html?|vue)$/i.test(file)) {
     for (const match of text.matchAll(/url\(\s*["']?([^"')]+)["']?\s*\)|@import\s+["']([^"']+)["']/gi)) refs.push((match[1] ?? match[2]).trim());
   }
   for (const ref of refs) {
@@ -41,27 +42,32 @@ function resourceErrors(file, text, files) {
     const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), decoded));
     if (target.startsWith("../") || !Object.hasOwn(files, target)) errors.push(`${file}: 资源缺失或越出交付包 ${ref}`);
   }
-  if (/\.(?:jsx?|html?)$/i.test(file) && /\b(?:fetch\s*\(|XMLHttpRequest|WebSocket|EventSource|import\s*\(|serviceWorker\s*\.)/.test(text)) errors.push(`${file}: 离线默认路线不依赖网络、动态模块或 Service Worker；使用随包场景数据`);
+  if (/\.(?:(?:jsx?|tsx?|vue)|html?)$/i.test(file) && /\b(?:fetch\s*\(|XMLHttpRequest|WebSocket|EventSource|import\s*\(|serviceWorker\s*\.)/.test(text)) errors.push(`${file}: 离线默认路线不依赖网络、动态模块或 Service Worker；使用随包场景数据`);
   return errors;
 }
 
-async function inspect(root, profile, checkDigests) {
+async function inspect(root, profile, checkDigests, allowLegacy = false) {
   const errors = [];
   let manifest, files;
   try {
     files = await inventory(root);
     manifest = JSON.parse(await readFile(path.join(root, manifestName), "utf8"));
   } catch (error) { return { errors: [error.message] }; }
-  if (manifest.schema_version !== 4 || !["html-css-js", "react-antd-prebuilt"].includes(manifest.component_basis) || manifest.runtime_build_required !== false) errors.push("原型必须使用 offline-html adapter schema v4 / html-css-js / runtime_build_required=false");
+  if (manifest.schema_version !== 4 || !["html-css-js", "vue-shadcn-prebuilt", ...(allowLegacy ? ["react-antd-prebuilt", "react-shadcn-prebuilt"] : [])].includes(manifest.component_basis) || manifest.runtime_build_required !== false) errors.push("原型必须使用 offline-html adapter schema v4 / html-css-js 或 vue-shadcn-prebuilt / runtime_build_required=false；React 作者路线已退役，仅允许只读 legacy 校验");
   if (manifest.prototype_profile !== profile || manifest.profile_kind !== (profile === "H1" ? "visual-review" : "flow-review")) errors.push("adapter 档位与验证档位不一致");
   if (manifest.entry !== "index.html" || !files[manifest.entry]) errors.push("缺少本地 index.html 入口");
+  if (manifest.visual_preset) {
+    if (manifest.visual_preset.name !== "yss-enterprise" || !["compact", "comfortable"].includes(manifest.visual_preset.density)) errors.push("未知原型视觉预设或密度");
+    const entry = await readFile(path.join(root, "index.html"), "utf8").catch(() => "");
+    if (!entry.includes(`data-density="${manifest.visual_preset.density}"`)) errors.push("视觉预设与页面密度不一致");
+  }
   for (const file of ["styles.css", "tokens.css", "app.js", "scenarios.js"]) if (!files[file]) errors.push(`缺少 ${file}`);
   for (const file of Object.keys(files)) {
     if (/(^|\/)(node_modules|package\.json|(?:pnpm|package)-lock\.(?:yaml|json)|yarn\.lock)(\/|$)/.test(file)) errors.push(`交付包不得依赖 ${file}`);
-    if (/\.(css|jsx?|html?)$/i.test(file)) {
+    if (/\.(css|(?:jsx?|tsx?|vue)|html?)$/i.test(file)) {
       const content = await readFile(path.join(root, file), "utf8");
       // Compiled dependencies contain network API names; inspect authored code and require real offline browser evidence.
-      if (!(manifest.component_basis === "react-antd-prebuilt" && file === "app.js")) errors.push(...resourceErrors(file, content, files));
+      if (!(["react-antd-prebuilt", "react-shadcn-prebuilt", "vue-shadcn-prebuilt"].includes(manifest.component_basis) && file === "app.js")) errors.push(...resourceErrors(file, content, files));
     }
   }
   if (manifest.component_basis === "react-antd-prebuilt") {
@@ -73,6 +79,25 @@ async function inspect(root, profile, checkDigests) {
     if (!files["THIRD-PARTY-NOTICES.txt"] || !files["build-provenance.json"]) errors.push("缺少构建来源或第三方许可");
     else { try { if (JSON.stringify(JSON.parse(await readFile(path.join(root, "build-provenance.json"), "utf8"))) !== JSON.stringify(build)) errors.push("构建来源与 manifest 不匹配"); } catch { errors.push("构建来源不是有效 JSON"); } }
   }
+  if (["react-shadcn-prebuilt", "vue-shadcn-prebuilt"].includes(manifest.component_basis)) {
+    const vue = manifest.component_basis === "vue-shadcn-prebuilt", runtime = vue ? "vue" : "react", helper = vue ? "utils.ts" : "cn.ts";
+    const build = manifest.build_provenance;
+    if (build?.format !== "iife" || build?.browser_runtime !== runtime || build?.toolchain_required_by_recipient !== false) errors.push("shadcn 必须离线预构建，接收者无需工具链");
+    for (const [field, ref] of Object.entries({source_digest:vue?"authoring-source.ts":"authoring-source.tsx",theme_digest:"token-theme.css",registry_digest:"registry-manifest.json"})) if (!files[ref] || build?.[field] !== files[ref]) errors.push(`shadcn 源文件与构建来源摘要不一致: ${field}`);
+    if (!files[`component-sources/${helper}`] || build?.support_source_digests?.[helper] !== files[`component-sources/${helper}`]) errors.push("shadcn 辅助源码摘要不匹配");
+    if (!/^sha256:[a-f0-9]{64}$/.test(build?.lock_digest ?? "")) errors.push("缺少 shadcn lock_digest");
+    for (const name of (vue ? ["vue", "@vue/compiler-sfc", "reka-ui", "esbuild", "tailwindcss", "@tailwindcss/cli"] : ["react", "react-dom", "esbuild", "radix-ui", "tailwindcss", "@tailwindcss/cli"])) if (!/^\d+\.\d+\.\d+$/.test(build?.packages?.[name] ?? "")) errors.push(`shadcn 作者工具需要精确版本 ${name}`);
+    try {
+      const registry = JSON.parse(await readFile(path.join(root, "registry-manifest.json"), "utf8"));
+      if (registry.repository !== (vue ? "https://github.com/unovue/shadcn-vue" : "https://github.com/shadcn-ui/ui") || !/^[a-f0-9]{40}$/.test(registry.revision) || registry.revision !== build.registry_revision || !registry.components?.length) errors.push("shadcn 固定源码来源缺失或不一致");
+      for (const item of registry.components ?? []) if (!(vue ? /^ui\/[a-z-]+\/[A-Za-z]+\.(?:vue|ts)$/ : /^ui\/[a-z-]+\.tsx$/).test(item.path) || item.digest !== files[`component-sources/${vue ? item.path : path.posix.basename(item.path)}`]) errors.push(`shadcn 组件源码摘要不匹配: ${item.path}`);
+      if (vue && (build.packages.vue !== build.packages['@vue/compiler-sfc'] || !Array.isArray(build.used_component_files) || !build.used_component_files.length || build.used_component_files.some(p=>!registry.components.some(c=>c.path===p)))) errors.push("Vue 编译器版本或实际组件依赖闭包不匹配");
+      if (JSON.stringify(JSON.parse(await readFile(path.join(root, "build-provenance.json"), "utf8"))) !== JSON.stringify(build)) errors.push("构建来源与 manifest 不匹配");
+    } catch { errors.push("shadcn 构建来源不是有效 JSON"); }
+    if (!files["THIRD-PARTY-NOTICES.txt"]) errors.push("缺少第三方许可");
+  }
+  if (files["scenarios.json"]) {try {if(await readFile(path.join(root,"scenarios.js"),"utf8")!==scenarioScript(await readFile(path.join(root,"scenarios.json"))))errors.push("场景 JSON 与派生脚本不一致");if(!files["scenario-runtime.js"])errors.push("缺少场景运行时");}catch(e){errors.push(e.message);}}
+  if (manifest.build_provenance?.authored_files) for(const [ref,hash] of Object.entries(manifest.build_provenance.authored_files))if(files[ref]!==hash)errors.push(`作者来源摘要漂移: ${ref}`);
   if (files["styles.css"]) {
     const styles = await readFile(path.join(root, "styles.css"), "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"]) if (!styles.includes(token)) errors.push(`styles.css 未消费项目 Token ${token}`);
@@ -83,8 +108,9 @@ async function inspect(root, profile, checkDigests) {
   return { errors, manifest, files };
 }
 
-export async function validateOfflineHtml(root, profile) {
-  const { errors } = await inspect(root, profile, true);
+export async function validateOfflineHtml(root, profile, { allowLegacy = false, projectRoot } = {}) {
+  const { errors, manifest } = await inspect(root, profile, true, allowLegacy);
+  if(projectRoot && manifest) for(const source of [manifest.design_source,manifest.token_source]) {try {if(sha(await readFile(path.join(projectRoot,source.path)))!==source.digest)errors.push(`当前项目来源已漂移: ${source.path}`);}catch(e){errors.push(e.message);}}
   return { errors };
 }
 
@@ -96,26 +122,37 @@ export async function sealOfflineHtml(root, profile) {
   return manifest;
 }
 
-export async function prepareOfflineHtml({ projectRoot, root, feature, profile, pattern = "editor" }) {
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
-  if (!["editor", "workbench"].includes(pattern)) throw new Error("pattern 必须为 editor/workbench");
-  const expected = path.resolve(projectRoot, "docs/.scratch", feature, "design/prototypes");
-  if (path.resolve(root) !== expected) throw new TypeError(`原型目录必须精确匹配 ${expected}`);
-  for (let current = path.resolve(root); current.startsWith(`${path.resolve(projectRoot)}${path.sep}`); current = path.dirname(current)) {
-    if (existsSync(current) && (await lstat(current)).isSymbolicLink()) throw new Error(`原型路径不允许符号链接: ${current}`);
-  }
-  // Refuse an occupied destination instead of replacing an existing or frozen prototype.
-  if (existsSync(root) && ((await lstat(root)).isSymbolicLink() || (await readdir(root)).length)) throw new Error("原型目录已存在内容；请在保留旧版本后选择新 feature 工作目录，不覆盖已有原型");
+export async function prepareOfflineHtml({ projectRoot, root, feature, profile, pattern = "editor", scenarios, title, density = "compact" }) {
+  await assertPrototypeTarget({projectRoot,root,feature,pattern});
+  if (!["compact", "comfortable"].includes(density)) throw new Error("density 必须为 compact/comfortable");
   const design = await readFile(path.join(projectRoot, "DESIGN.md"));
   const tokens = await readFile(path.join(projectRoot, ".template-spec/design/tokens/variables.css"));
   await mkdir(root, { recursive: true });
-  for (const file of ["index.html", "styles.css", "app.js", "scenarios.js"]) {
+  for (const file of ["index.html", "styles.css", "app.js"]) {
     const folder = pattern === "workbench" && file !== "scenarios.js" ? new URL("../assets/native-workbench/", import.meta.url) : assetRoot;
     const source = await readFile(new URL(file, folder), "utf8");
-    await writeFile(path.join(root, file), source.replaceAll("__FEATURE__", feature).replaceAll("__PROFILE__", profile));
+    let output=source.replaceAll("__FEATURE__", feature).replaceAll("__PROFILE__", profile);
+    if (file === "index.html") output=output.replace('<html ', `<html data-density="${density}" `);
+    if (file === "styles.css") output+='\n'+await readFile(new URL('../assets/prototype-theme.css',import.meta.url),'utf8');
+    if(file==="index.html") {output=output.replace(/<script[^>]*src="\.\/scenarios.js"[^>]*><\/script>/g, "").replace("</head>", "<script src=\"./scenarios.js\"></script><script src=\"./scenario-runtime.js\"></script></head>");if(title)output=output.replace(/<title>.*?<\/title>/,`<title>${title.replace(/[<>&"]/g,c=>({"<":"&lt;",">":"&gt;","&":"&amp;",'"':"&quot;"})[c])}</title>`);}
+    await writeFile(path.join(root, file), output);
   }
+  await writeScenarios(root,scenarios?await readFile(scenarios):await readFile(new URL(`../assets/${pattern==="workbench"?"native-workbench":"offline-html"}/scenarios.json`,import.meta.url)));
   await writeFile(path.join(root, "tokens.css"), tokens);
   const manifest = { schema_version: 4, feature, pattern, prototype_profile: profile, profile_kind: profile === "H1" ? "visual-review" : "flow-review", component_basis: "html-css-js", runtime_build_required: false, entry: "index.html", design_source: { path: "DESIGN.md", digest: sha(design) }, token_source: { path: ".template-spec/design/tokens/variables.css", digest: sha(tokens) }, files: {} };
+  manifest.visual_preset = { name: "yss-enterprise", density };
   await writeFile(path.join(root, manifestName), JSON.stringify(manifest));
   return sealOfflineHtml(root, profile);
 }
+
+export async function assertPrototypeTarget({projectRoot,root,feature,pattern="workbench"}) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
+  if (!["editor", "workbench"].includes(pattern)) throw new Error("pattern 必须为 editor/workbench");
+  const expected = path.resolve(projectRoot, "docs/.scratch", feature, "design/prototypes");
+  if (path.resolve(root) !== expected) throw new TypeError(`原型目录必须精确匹配 ${expected}`);
+  for (let current = path.resolve(root); current.startsWith(`${path.resolve(projectRoot)}${path.sep}`); current = path.dirname(current)) {
+    if (existsSync(current) && (await lstat(current)).isSymbolicLink()) throw new Error(`原型路径不允许符号链接: ${current}`);
+  }
+  // Refuse an occupied destination instead of replacing an existing or frozen prototype.
+  if (existsSync(root) && ((await lstat(root)).isSymbolicLink() || (await readdir(root)).length)) throw new Error("原型目录已存在内容；请在保留旧版本后选择新 feature 工作目录，不覆盖已有原型");
+}

package/template/.pi/skills/yss-prototype-stage/scripts/prototype-comparison.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+// Review-only snapshots. This tool never writes prototype approval or product evidence.
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, writeFile, mkdir, mkdtemp, rename, rm, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { resourceErrors } from './offline-html.mjs';
+import {parseScenarios,scenarioScript} from './scenario-contract.mjs';
+
+const manifestName = 'comparison-manifest.json';
+const assets = new URL('../assets/comparison/', import.meta.url);
+const hash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const id = value => typeof value === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(value);
+const requireThat = (test, message) => { if (!test) throw new Error(message); };
+const json = value => JSON.stringify(value, null, 2) + '\n';
+
+function relative(ref) {
+  requireThat(typeof ref === 'string' && ref.length && !/[\\?#%\x00-\x1f]/.test(ref) && !/^(?:\/|[a-z][\w+.-]*:)/i.test(ref) && ref.split('/').every(x => x && x !== '.' && x !== '..'), `需要包内相对路径: ${ref}`);
+  return ref;
+}
+async function safe(root, ref) {
+  relative(ref);
+  let current = root;
+  for (const part of ref.split('/')) {
+    current = path.join(current, part);
+    try { requireThat(!(await lstat(current)).isSymbolicLink(), `不允许符号链接: ${ref}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return current;
+}
+async function inventory(root, prefix = '') {
+  requireThat(!(await lstat(root)).isSymbolicLink(), '不允许符号链接目录');
+  const files = {};
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const ref = prefix + entry.name;
+    relative(ref);
+    requireThat(!entry.isSymbolicLink(), `不允许符号链接: ${ref}`);
+    if (entry.isDirectory()) Object.assign(files, await inventory(path.join(root, entry.name), ref + '/'));
+    else {
+      requireThat(entry.isFile(), `不是普通文件: ${ref}`);
+      if (ref !== manifestName) files[ref] = hash(await readFile(path.join(root, entry.name)));
+    }
+  }
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b, 'en')));
+}
+function keys(object, allowed, name) {
+  requireThat(object && typeof object === 'object' && !Array.isArray(object), `${name} 必须是对象`);
+  requireThat(Object.keys(object).every(k => allowed.includes(k)), `${name} 存在未知字段；比较包不承载批准或业务状态定义`);
+}
+function definition(input, legacy = false) {
+  keys(input, ['schema_version', 'comparison_id', 'title', 'comparison_ref', 'scenario_ref', 'variants', 'cases'], 'input');
+  requireThat(input.schema_version === (legacy ? 1 : 2) && id(input.comparison_id) && typeof input.title === 'string' && input.title.trim(), '需要 schema_version=2、安全 comparison_id 和 title');
+  relative(input.comparison_ref); relative(input.scenario_ref);
+  requireThat(Array.isArray(input.variants) && input.variants.length >= 2 && input.variants.length <= 3, '需要 2–3 个候选');
+  requireThat(Array.isArray(input.cases) && input.cases.length, '需要共同场景');
+  for (const item of input.cases) {
+    keys(item, ['id', 'label', 'scenario'], 'case');
+    requireThat(id(item.id) && id(item.scenario) && typeof item.label === 'string' && item.label.trim(), '场景需要安全 id/scenario 和 label');
+  }
+  requireThat(new Set(input.cases.map(c => c.id)).size === input.cases.length, 'case id 重复');
+  for (const item of input.variants) {
+    keys(item, ['id', 'label', 'root', 'entry', 'cases'], 'variant');
+    requireThat(id(item.id) && typeof item.label === 'string' && item.label.trim(), '候选需要安全 id 和 label');
+    relative(item.root); relative(item.entry);
+    requireThat(/\.html?$/.test(item.entry), '候选入口必须是 HTML');
+    requireThat(Array.isArray(item.cases) && item.cases.length === input.cases.length && new Set(item.cases).size === item.cases.length && input.cases.every(c => item.cases.includes(c.id)), '候选缺少共同场景或场景重复');
+  }
+  requireThat(new Set(input.variants.map(v => v.id)).size === input.variants.length, 'variant id 重复');
+}
+function view(manifest) {
+  return { title: manifest.title, variants: manifest.variants.map(({ id, label, entry }) => ({ id, label, entry })), cases: manifest.schema_version===1?manifest.cases:manifest.cases.map(c=>({...c,dataDigest:manifest.scenario_digests[c.scenario]})) };
+}
+function browserData(manifest) {
+  return `window.prototypeComparison = ${JSON.stringify(view(manifest)).replaceAll('<', '\\u003c').replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029')};\n`;
+}
+
+export async function prepareComparison({ projectRoot, feature, input: inputPath }) {
+  requireThat(id(feature), 'feature 必须为 kebab-case');
+  const project = await realpath(projectRoot);
+  const input = JSON.parse(await readFile(await safe(project, inputPath), 'utf8'));
+  definition(input);
+  const output = await safe(project, `docs/.scratch/${feature}/design/comparisons/${input.comparison_id}`);
+  try { requireThat((await readdir(output)).length === 0, '比较目录非空，拒绝覆盖'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const sources = [input.comparison_ref, input.scenario_ref, 'DESIGN.md', '.template-spec/design/tokens/variables.css'];
+  const bytes = await Promise.all(sources.map(async ref => readFile(await safe(project, ref))));
+  const scenes=parseScenarios(bytes[1]);
+  requireThat(input.cases.every(c=>scenes.scenarios.some(s=>s.id===c.scenario)), "共同场景 ID 不存在");
+  const scenarioDigests=Object.fromEntries(scenes.scenarios.map(s=>[s.id,hash(JSON.stringify(s.initial_data))]));
+  // Check all inputs before creating the review package. Candidate roots must not contain the output.
+  const candidates = [];
+  for (const variant of input.variants) {
+    const source = await safe(project, variant.root);
+    requireThat(output !== source && !output.startsWith(source + path.sep), '候选目录不能包含比较输出');
+    const files = await inventory(source);
+    requireThat(files[variant.entry], `候选入口缺失: ${variant.id}`);
+    requireThat(files['scenarios.json'] === hash(bytes[1]) && files['scenarios.js'] === hash(scenarioScript(bytes[1])) && files['scenario-runtime.js'], `候选 ${variant.id} 的 scenarios.js 与共同来源不一致`);
+    requireThat(files['tokens.css'] === hash(bytes[3]), `候选 ${variant.id} 的 tokens.css 与项目快照不一致`);
+    for (const ref of Object.keys(files)) {
+      if (/\.(?:css|js|html?)$/.test(ref)) requireThat(resourceErrors(ref, await readFile(path.join(source, ref), 'utf8'), files).length === 0, `候选 ${variant.id} 含非离线或缺失资源: ${ref}`);
+    }
+    candidates.push({ variant, source, files });
+  }
+  await mkdir(path.dirname(output), { recursive: true });
+  const staging = await mkdtemp(path.join(path.dirname(output), '.comparison-'));
+  try {
+    const names = ['comparison-record.md', 'scenarios.json', 'DESIGN.md', 'tokens.css'];
+    const bindings = [];
+    await mkdir(path.join(staging, 'sources'));
+    for (let i = 0; i < sources.length; i++) {
+      const snapshot = `sources/${names[i]}`;
+      await writeFile(path.join(staging, snapshot), bytes[i]);
+      bindings.push({ source_ref: sources[i], snapshot, digest: hash(bytes[i]) });
+    }
+    for (const file of ['index.html', 'comparison.js', 'comparison.css']) await writeFile(path.join(staging, file), await readFile(new URL(file, assets)));
+    const variants = [];
+    for (const { variant, source, files } of candidates) {
+      const base = `variants/${variant.id}`;
+      for (const ref of Object.keys(files)) {
+        const target = path.join(staging, base, ref);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, await readFile(path.join(source, ref)));
+      }
+      const entry = `${base}/${variant.entry}`;
+      let html = await readFile(path.join(staging, entry), 'utf8');
+      requireThat(/<\/body\s*>/i.test(html), `候选 ${variant.id} 缺少 body 结束标签`);
+      await writeFile(path.join(staging, entry), html);
+      variants.push({ id: variant.id, label: variant.label, entry, source_root: variant.root, cases: variant.cases });
+    }
+    const manifest = { schema_version: 2, scenario_digests:scenarioDigests, purpose: 'review-only', comparison_id: input.comparison_id, title: input.title, variants, cases: input.cases, bindings, files: {} };
+    await writeFile(path.join(staging, manifestName), json(manifest));
+    await writeFile(path.join(staging, 'comparison-data.js'), browserData(manifest));
+    await sealComparison(staging);
+    // rename replaces only an empty directory; a concurrent nonempty destination fails.
+    await rename(staging, output);
+    return { root: output, entry: path.join(output, 'index.html') };
+  } catch (error) { await rm(staging, { recursive: true, force: true }); throw error; }
+}
+
+async function inspect(root, checkDigests, projectRoot, allowLegacy = false) {
+  const files = await inventory(root);
+  const manifest = JSON.parse(await readFile(path.join(root, manifestName), 'utf8'));
+  keys(manifest, ['schema_version', 'purpose', 'comparison_id', 'title', 'variants', 'cases', 'bindings', 'files', 'scenario_digests'], 'manifest');
+  const legacy=manifest.schema_version===1;
+  requireThat((manifest.schema_version===2 || (legacy&&allowLegacy)) && manifest.purpose==='review-only', '当前比较包仅支持 review-only v2；v1 需要 --allow-legacy 只读检查');
+  requireThat(Array.isArray(manifest.bindings) && manifest.bindings.length === 4, '来源绑定缺失');
+  const [record, scenarios, design, tokens] = manifest.bindings;
+  const snapshots = ['sources/comparison-record.md', legacy?'sources/scenarios.js':'sources/scenarios.json', 'sources/DESIGN.md', 'sources/tokens.css'];
+  for (const [i, binding] of manifest.bindings.entries()) {
+    keys(binding, ['source_ref', 'snapshot', 'digest'], 'binding'); relative(binding.source_ref);
+    requireThat(binding.snapshot === snapshots[i] && files[binding.snapshot] === binding.digest, '来源快照摘要不一致');
+    if (projectRoot) requireThat(hash(await readFile(await safe(await realpath(projectRoot), binding.source_ref))) === binding.digest, `来源已漂移: ${binding.source_ref}`);
+  }
+  requireThat(design.source_ref === 'DESIGN.md' && tokens.source_ref === '.template-spec/design/tokens/variables.css', '设计来源不符合项目合同');
+  requireThat(Array.isArray(manifest.variants), '候选缺失');
+  const input = { schema_version: manifest.schema_version, comparison_id: manifest.comparison_id, title: manifest.title, comparison_ref: record.source_ref, scenario_ref: scenarios.source_ref, cases: manifest.cases, variants: manifest.variants.map(v => {
+    keys(v, ['id', 'label', 'entry', 'source_root', 'cases'], 'manifest variant');
+    requireThat(id(v.id) && v.entry.startsWith(`variants/${v.id}/`), '候选入口越界');
+    return { id: v.id, label: v.label, root: v.source_root, entry: v.entry, cases: v.cases };
+  }) };
+  definition(input,legacy);
+  if(!legacy){const bytes=await readFile(path.join(root,scenarios.snapshot)),doc=parseScenarios(bytes);requireThat(manifest.cases.every(c=>doc.scenarios.some(s=>s.id===c.scenario)), '共同场景 ID 不存在');requireThat(JSON.stringify(manifest.scenario_digests)===JSON.stringify(Object.fromEntries(doc.scenarios.map(s=>[s.id,hash(JSON.stringify(s.initial_data))]))), '场景初始化摘要不一致');}
+  for (const variant of manifest.variants) {
+    requireThat(files[variant.entry], `候选入口缺失: ${variant.id}`);
+    requireThat(files[`variants/${variant.id}/${legacy?'scenarios.js':'scenarios.json'}`] === scenarios.digest, '候选场景数据不一致');
+    if(!legacy)requireThat(files[`variants/${variant.id}/scenarios.js`]===hash(scenarioScript(await readFile(path.join(root,scenarios.snapshot)))) && files[`variants/${variant.id}/scenario-runtime.js`], '候选场景脚本或运行时不一致');
+    requireThat(files[`variants/${variant.id}/tokens.css`] === tokens.digest, '候选 Token 不一致');
+  }
+  for (const ref of Object.keys(files)) {
+    requireThat(!/(^|\/)(?:node_modules|package\.json|(?:pnpm|package)-lock\.(?:yaml|json)|yarn\.lock)(\/|$)/.test(ref), `离线包不得携带 ${ref}`);
+    if (/\.(?:css|js|html?)$/.test(ref)) {
+      const errors = resourceErrors(ref, await readFile(path.join(root, ref), 'utf8'), files);
+      requireThat(!errors.length, errors.join('\n'));
+    }
+  }
+  for (const ref of ['index.html', 'comparison.js', 'comparison.css']) requireThat(files[ref], `评审资源缺失: ${ref}`);
+  if (checkDigests) {
+    requireThat(await readFile(path.join(root, 'comparison-data.js'), 'utf8') === browserData(manifest), '运行时比较配置与 manifest 不一致');
+    requireThat(JSON.stringify(manifest.files) === JSON.stringify(files), '比较资源摘要或清单已变化，请审查后重新 seal');
+  }
+  return manifest;
+}
+export async function sealComparison(root) {
+  const manifest = await inspect(root, false);
+  await writeFile(path.join(root, 'comparison-data.js'), browserData(manifest));
+  manifest.files = await inventory(root);
+  await writeFile(path.join(root, manifestName), json(manifest));
+  return manifest;
+}
+export async function validateComparison(root, projectRoot, {allowLegacy=false} = {}) {
+  try { const manifest=await inspect(root, true, projectRoot,allowLegacy); return { errors: [], ...(manifest.schema_version===1?{warnings:["历史 v1 只读校验：未验证应用初始化"]}:{}) }; }
+  catch (error) { return { errors: [error.message] }; }
+}
+if (process.argv[1] && existsSync(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: {...Object.fromEntries(['project-root', 'feature', 'input', 'root'].map(k => [k, { type: 'string' }])), 'allow-legacy':{type:'boolean'}} });
+    const [command] = positionals;
+    requireThat(positionals.length === 1, '用法: prepare --project-root ... --feature ... --input ... | seal/validate --root ...');
+    let result;
+    if (command === 'prepare') result = await prepareComparison({ projectRoot: values['project-root'], feature: values.feature, input: values.input });
+    else if (command === 'seal') { await sealComparison(values.root); result = { result: 'sealed', purpose: 'review-only' }; }
+    else if (command === 'validate') { result = await validateComparison(values.root, values['project-root'], {allowLegacy:values['allow-legacy']}); if (result.errors.length) process.exitCode = 1; }
+    else throw new Error('未知比较命令');
+    process.stdout.write(json(result));
+  } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }
+}