@givolt/i3-composer-agent 2.3.1 → 2.3.3

package/skills/i3-ui-prototype/scripts/native-pilot-lib.cjs

@@ -0,0 +1,292 @@
+'use strict';
+const F=require('./native-files.cjs');
+const {fs,path,crypto,assert,hash,json,id,inside,walk,write,entries,excluded}=F;
+const skillRoot=path.resolve(__dirname,'..');
+const frameworkRoot=path.join(skillRoot,'assets/frameworks/vue-antdv-next');
+const templates=()=>require('./template-contract.cjs');
+const projectRegistry=require('./project-registry.cjs');
+function metadata(directory) { const data=json(inside(directory,'prototype.json')); assert.equal(data.schemaVersion,2,'Not a native v2 prototype'); assert.equal(data.runtime.kind,'vue-antdv-next'); return data; }
+function effectiveReview(data,current) {
+  const review=data.review;
+  if(review.status!=='approved'||(review.revision===current.revision&&review.digest===current.digest))return review;
+  return {status:'pending-review',previousApproval:review,reason:'The stored approval applies to a different revision or candidate digest'};
+}
+function analyze(options={}) {
+  if(options.execution!==undefined)assert.ok(['inline','delegated'].includes(options.execution),'Invalid execution declaration: use inline or delegated');
+  const project=path.resolve(options.project||'.');
+  return {operation:'analyze',readOnly:true,project,projectExists:fs.existsSync(project),supportedOperations:['analyze','create','revise','inspect','confirm-baseline'],execution:options.execution??null,executionEvidence:options.execution===undefined?'unverified':'caller-declared',sideEffects:[]};
+}
+function prepareTemplate(options) { return templates().prepareTemplate(options); }
+function manifest(directory) {
+  const data=metadata(directory);
+  const inputFiles=walk(directory,'inputs');
+  const inputs=entries(directory,inputFiles), inputDigest=hash(JSON.stringify(inputs));
+  const files=entries(directory,[...inputFiles,'requirements-map.json',...['app','mocks','design-system'].flatMap(folder=>walk(directory,folder,excluded))]);
+  const identity={...(data.runtime.contentReference?{business:data.business}:{}),schemaVersion:2,id:data.id,revision:data.revision,artifactKind:data.artifactKind,runtime:data.runtime,template:data.template,framework:data.framework,expertMode:data.expertMode};
+  return {schemaVersion:2,revision:data.revision,identity,inputDigest,files,digest:hash(JSON.stringify({identity,files}))};
+}
+function defaultScope() {
+  return {schemaVersion:1,title:'设备清单首期演示需求',requirements:[
+    {id:'PILOT-01',text:'设备列表支持查询、当前页多选、分页和批量变更状态',source:{type:'prd',reference:'pilot-fixture/PILOT-01',statement:'21条记录，每页10条；换页或筛选清空选择；批量操作仅影响选中记录'}},
+    {id:'PILOT-02',text:'编辑抽屉使用真实表单校验，失败保留输入，成功更新对应记录',source:{type:'prd',reference:'pilot-fixture/PILOT-02',statement:'设备名称必填；可模拟提交失败并重试'}},
+    {id:'PILOT-03',text:'加载、空、失败和恢复可触发；抽屉开合、遮罩模糊及焦点可验证',source:{type:'prd',reference:'pilot-fixture/PILOT-03',statement:'首期演示规则；不是任何生产项目的已确认权限或流程'}}
+  ],exemptions:[],openQuestions:[]};
+}
+function createPrototype(options) {
+  const installedFile=path.resolve(__dirname,'../../../.i3-composer-agent.json');
+  if(fs.existsSync(installedFile))options=require('./execution-policy.cjs').creationOptions(options,json(installedFile));
+  if(options.executionPolicy!==undefined){assert.equal(options.executionPolicy,require('./execution-policy.cjs').ID,'Unsupported execution policy');assert.equal(options.host,'codebuddy','Explicit CodeBuddy host required for A+B');}
+  assert.ok(options.framework===undefined||options.framework==='vue-antdv-next','Unsupported framework / 不支持的框架');
+  assert.ok(options.title===undefined||(typeof options.title==='string'&&options.title.trim()),'Title must be a nonempty string');
+  const project=path.resolve(options.project||'.'); assert.ok(fs.statSync(project).isDirectory(),'Project must exist'); id(options.id);
+  const mode=options.expertMode||'professional'; assert.ok(['professional','template'].includes(mode),'Invalid expert mode');
+  let provider=null;
+  if(mode==='professional') {
+    provider=require('./prototype-lib.cjs').checkDesignProvider({...options,project});
+    if(provider.availability!=='available') return {status:'needs-design-provider',provider,sideEffects:[],choices:['locate-or-repair','explicit-template-mode','analyze']};
+  }
+  assert.ok(!(options.templateRoot && options.template), 'Choose a template ID or an explicit template root');
+  const template=options.templateRoot?templates().loadTemplate(path.resolve(options.templateRoot)):templates().loadBundledTemplate(options.template);
+  const reference=template.kind==='content-reference';
+  assert.ok(!reference||options.scope,'A sourced scope file is required for business generation; no default device demo');
+  const scope=options.scope?json(path.resolve(options.scope)):defaultScope();
+  const appliesTo=projectRegistry.moduleIds(scope);
+  const selection=reference?require('./content-template.cjs').scopeInputs(template,scope,templates()):null;
+  const generation=scope.schemaVersion===3?require('./generation-contract.cjs').compile(template,scope):null;
+  const content=reference?{pageTitle:scope.title||'业务原型'}:templates().projectAdminListContent(template);
+  if(options.title!==undefined)content.pageTitle=options.title;
+  const profile=json(path.join(frameworkRoot,'profile.json'));
+  const target=inside(project,`prototypes/${options.id}`); assert.ok(!fs.existsSync(target),'Prototype exists; revise without reinitializing');
+  return projectRegistry.transaction(project,store=>{
+  let stage=null,published=false;
+  try {
+    fs.mkdirSync(path.dirname(target),{recursive:true}); stage=fs.mkdtempSync(path.join(path.dirname(target),'.native-'));
+    const registry=store.registry;
+    assert.equal(registry.schemaVersion,1); assert.ok(Array.isArray(registry.prototypes)); assert.ok(!registry.prototypes.some(p=>p.id===options.id),'Duplicate prototype ID');
+    const frameworkFiles=entries(frameworkRoot,walk(frameworkRoot,'',excluded));
+    const instanceId=crypto.randomUUID();
+    const data={schemaVersion:2,id:options.id,title:options.title||content.pageTitle||'设备清单原型',revision:'r001',artifactKind:'framework-prototype',runtime:{kind:'vue-antdv-next',version:'1',...(reference?{contentReference:true}:{})},...(reference?{business:{status:'needs-adaptation',source:'inputs/scope.json'}}:{}),template:{id:template.id,version:template.version,digest:template.digest},framework:{id:'vue-antdv-next',version:profile.version||'1',digest:hash(JSON.stringify(frameworkFiles))},expertMode:mode,expert:{status:provider?'pending':'skipped',provider},verification:{status:'not-run'},review:{status:'pending-review'},instanceId};
+    if(generation)data.runtime.generationContract=1;
+    if(options.executionPolicy){data.runtime.executionPolicy=options.executionPolicy;write(stage,'inputs/execution-policy.json',require('./execution-policy.cjs').create({host:options.host,mode,officialCallable:!options.officialSourceFallback}));}
+    write(stage,'prototype.json',data);
+    for(const file of template.files) {
+      assert.equal(file.encoding,'base64');
+      const destination=inside(stage,`inputs/template/${file.path}`); fs.mkdirSync(path.dirname(destination),{recursive:true}); fs.writeFileSync(destination,Buffer.from(file.content,'base64'));
+    }
+    write(stage,'inputs/template-snapshot.json',template);
+    write(stage,'inputs/scope.json',scope);
+    if(generation)write(stage,'inputs/generation.json',generation);
+    write(stage,'inputs/capabilities.json',selection?selection.fixed:{schemaVersion:1,definition:template.definition,bindings:template.index.bindings,regions:template.index.regions,decisions:[]});
+    write(stage,'inputs/framework.json',{profile,componentMap:generation?require('./generation-evidence.cjs').framework():json(path.join(frameworkRoot,'component-map.json')),acceptance:json(path.join(frameworkRoot,'acceptance.json')),files:frameworkFiles});
+    const checked=templates().checkInstanceCapabilities(path.join(stage,'inputs')); assert.equal(checked.status,'passed',checked.errors?.join('; '));
+    const scenarioDetails=[...checked.requiredScenarios,...(generation?.scenarios||[])],requiredScenarios=scenarioDetails.map(s=>typeof s==='string'?s:s.id);
+    const hasDrawer=reference&&(selection.fixed.regions.some(region=>region.mode==='edit-form')||generation?.bindings.some(binding=>binding.capabilityId==='dialog'&&binding.parameters.presentation==='drawer'));
+    write(stage,'inputs/acceptance.json',{schemaVersion:1,requiredScenarios,scenarioDetails,frameworkScenarios:reference?['framework-responsive','framework-instance-isolation','template-content-projection',...(hasDrawer?['framework-drawer-motion','framework-mask-blur','framework-focus-scroll']:[])]:['framework-drawer-motion','framework-mask-blur','framework-focus-scroll','framework-states','framework-responsive','framework-instance-isolation','template-content-projection'],browserReview:json(path.join(frameworkRoot,'acceptance.json')).browserReview});
+    if(options.executionPolicy){const all=json(inside(stage,'inputs/acceptance.json'));assert.ok(options.executionAssertions,`Strict policy requires --execution-assertions with fixed expected JSON facts for: ${[...all.requiredScenarios,...all.frameworkScenarios].join(', ')}`);const fixed=require('./execution-assertions.cjs').validate(json(path.resolve(options.executionAssertions)),[...all.requiredScenarios,...all.frameworkScenarios]);write(stage,'inputs/execution-assertions.json',fixed);}
+    const requirements=json(path.join(stage,'inputs/scope.json')).requirements;
+    write(stage,'requirements-map.json',{schemaVersion:2,requirements:requirements.map(r=>({...r,pages:reference?r.pages:template.index.pages.map(page=>page.id),scenarios:reference?scenarioDetails.filter(s=>s.bindingId.startsWith('app-shell/')||r.pages.some(page=>s.bindingId.startsWith(page+'/'))).map(s=>s.id):requiredScenarios})),bindings:[...(selection?selection.fixed.bindings:template.index.bindings),...(generation?.bindings||[])]});
+    const starter=path.join(frameworkRoot,reference?profile.starter:(profile.legacyStarter||profile.starter));
+    fs.cpSync(starter,path.join(stage,'app'),{recursive:true,filter:file=>!excluded(`starter/${path.relative(starter,file).split(path.sep).join('/')}`,path.basename(file))});
+    const themeBinding=(selection?selection.fixed.bindings:template.index.bindings).find(binding=>binding.capabilityId==='theme');
+    write(stage,'app/public/prototype-config.json',{instanceId,storageNamespace:`i3-native-${options.id}-${instanceId}`,mockVersion:reference?'business-v1':'admin-list-v1',title:data.title,...(reference?{pages:scope.pages.map(page=>({id:page.id,title:page.title}))}:{content}),...(generation?{presentation:generation.presentation,navigation:generation.navigation,generation:{pages:generation.pages}}:{}),...(themeBinding?{theme:templates().resolveThemeParameters(themeBinding.parameters)}:{})});
+    write(stage,'mocks/contract.json',reference?{schemaVersion:1,instanceId,status:'needs-business-data',requirements:scope.requirements.map(r=>r.id)}:{schemaVersion:1,seed:'admin-list-v1',count:21,pageSize:10,selection:'current-page-clear-on-page-or-filter',instanceId});
+    write(stage,'design-system/MASTER.md',`# ${data.title}\n\n使用 antDv-next 原生组件与主题。管理列表采用紧凑信息层级，正文与操作可读；错误在字段附近呈现。抽屉保留进入与退出过程，显式开启遮罩模糊。\n\n本地模拟，不代表生产权限。\n`);
+    if(generation)write(stage,'design-system/MASTER.md',require('./generation-evidence.cjs').designSummary(generation,`# ${data.title}\n\nPrototypeShell 提供已选原生外壳；按逐区域／字段／操作合同实现业务，补齐真实源码映射和浏览器证据。骨架不是业务完成。本地模拟不代表生产权限。`));
+    if(generation)write(stage,'design-system/implementation.json',require('./generation-evidence.cjs').initialize(generation));
+    write(stage,'design-system/decisions.json',{schemaVersion:1,records:[],reviewStatus:mode==='template'?'skipped':'pending'});
+    write(stage,'qa/design-advice.json',{schemaVersion:2,provider,queries:[],records:[],status:mode==='template'?'skipped':'pending'});
+    write(stage,'HANDOFF.md',`# ${data.title}\n\n本次为 ${mode} 模式；来源 ${template.id} ${template.version}。运行形态为真实 Vue＋antDv-next。读取 inputs 中固定合同和实际源码，勿从安装目录更新旧合同。\n\n使用 native-pilot.cjs inspect／build／preview。当前未验证，待用户评审；不要把检查通过当用户认可。\n`);
+    const candidate=manifest(stage); data.inputs={digest:candidate.inputDigest}; write(stage,'prototype.json',data);
+    fs.renameSync(stage,target); published=true;
+    const digest=manifest(target).digest;
+    registry.prototypes.push({id:options.id,directory:`prototypes/${options.id}`,appliesTo,schemaVersion:2}); store.save();
+    return {status:'created',directory:target,revision:'r001',digest};
+  } catch(error) { if(published) fs.rmSync(target,{recursive:true,force:true}); throw error; }
+  finally { if(stage&&fs.existsSync(stage)) fs.rmSync(stage,{recursive:true,force:true}); }
+  });
+}
+function inspectDesignReview(directory,current=manifest(directory)) {
+  const data=metadata(directory);
+  if(data.expertMode!=='professional') return {status:'skipped',queries:0,records:0,adoptedAdvice:[]};
+  const advice=json(inside(directory,'qa/design-advice.json')); assert.equal(advice.provider?.availability,'available','Professional provider not available');
+  assert.ok(advice.provider.digest,'Professional provider identity required');
+  assert.ok(advice.queries?.length && advice.queries.every(q=>q.query && q.source && q.resultDigest),'Real design query record required');
+  assert.ok(['reviewed','no-match'].includes(advice.status),'Design advice review pending');
+  assert.ok(advice.records?.length && advice.records.every(r=>['adopted','adjusted','rejected','no-match'].includes(r.decision) && r.query && advice.queries.some(q=>q.query===r.query) && r.resultIdentity && r.rationale && r.verification),'Advice decisions need query, identity, reasons and verification');
+  const decisions=json(inside(directory,'design-system/decisions.json'));
+  assert.ok(['reviewed','no-match'].includes(decisions.reviewStatus),'Design contract review pending');
+  const stable=r=>({query:r.query,resultIdentity:r.resultIdentity,decision:r.decision,rationale:r.rationale,implementation:r.implementation||null,verificationScenario:r.verificationScenario||null});
+  assert.deepEqual(decisions.records.map(stable),advice.records.map(stable),'Design contract differs from advice review');
+  const adoptedAdvice=advice.records.filter(r=>['adopted','adjusted'].includes(r.decision));
+  for(const record of adoptedAdvice)assert.ok(Object.hasOwn(current.files,record.implementation) && record.verificationScenario,'Adopted advice needs implementation and verified scenario');
+
+  return {status:advice.status,queries:advice.queries.length,records:advice.records.length,adoptedAdvice};
+}
+function inspectWithInputs(directory,options={},acceptedInputDigest) {
+  try {
+    const data=metadata(directory); const current=manifest(directory);
+    assert.equal(acceptedInputDigest??data.inputs.digest,current.inputDigest,'Input contract changed; explicitly revise fixed inputs');
+    const capability=templates().checkInstanceCapabilities(path.join(directory,'inputs')); assert.equal(capability.status,'passed',capability.errors?.join('; '));
+    const acceptance=json(inside(directory,'inputs/acceptance.json'));
+    require('./execution-runtime.cjs').policy(directory);
+    require('./native-devtools.cjs').readPolicy(directory);
+    for(const scenario of capability.requiredScenarios.map(s=>typeof s==='string'?s:s.id)) assert.ok(acceptance.requiredScenarios.includes(scenario),`Required scenario omitted: ${scenario}`);
+    const fixedFramework=json(inside(directory,'inputs/framework.json'));
+    if(fixedFramework.acceptance?.scenarios?.some(scenario=>scenario.id==='template-content-projection'&&scenario.required))assert.ok(acceptance.frameworkScenarios.includes('template-content-projection'),'Required template-content-projection scenario omitted from fixed framework acceptance');
+    const template=json(inside(directory,'inputs/template-snapshot.json')),mapping=json(inside(directory,'requirements-map.json')),scope=json(inside(directory,'inputs/scope.json'));
+    const generation=scope.schemaVersion===3?json(inside(directory,'inputs/generation.json')):null;
+    if(generation){assert.equal(data.runtime.generationContract,1,'Generation runtime identity is required');require('./generation-contract.cjs').verify(template,scope,generation);for(const scenario of generation.scenarios)assert.ok(acceptance.requiredScenarios.includes(scenario.id),`Generation scenario omitted: ${scenario.id}`);}
+    projectRegistry.moduleIds(scope);
+    const pageIds=new Set(data.runtime.contentReference?['app-shell',...scope.pages.map(page=>page.id)]:template.index.pages.map(page=>page.id)),bindingIds=new Set([...json(inside(directory,'inputs/capabilities.json')).bindings,...(generation?.bindings||[])].map(binding=>binding.id));
+    for(const requirement of scope.requirements)assert.ok(mapping.requirements.some(item=>item.id===requirement.id),`Requirement omitted from mapping: ${requirement.id}`);
+    for(const requirement of mapping.requirements) {
+      assert.ok(scope.requirements.some(item=>item.id===requirement.id),`Unknown mapped requirement: ${requirement.id}`);
+      if(data.runtime.contentReference)assert.deepEqual(requirement.pages,scope.requirements.find(item=>item.id===requirement.id).pages,`Business requirement page mapping changed: ${requirement.id}`);
+      assert.ok(requirement.pages?.length&&requirement.pages.every(page=>pageIds.has(page)),`Unknown page identity in requirement: ${requirement.id}`);
+      assert.ok(requirement.scenarios?.length&&requirement.scenarios.every(scenario=>acceptance.requiredScenarios.includes(scenario)||acceptance.frameworkScenarios.includes(scenario)),`Unknown scenario in requirement: ${requirement.id}`);
+    }
+    for(const binding of mapping.bindings||[])assert.ok(bindingIds.has(binding.id),`Unknown binding in mapping: ${binding.id}`);
+    for(const file of ['app/package.json','app/package-lock.json','app/src/App.vue','app/public/prototype-config.json','design-system/MASTER.md']) assert.ok(fs.existsSync(inside(directory,file)),`Missing ${file}`);
+    const config=json(inside(directory,'app/public/prototype-config.json')); assert.equal(config.instanceId,data.instanceId); assert.ok(config.storageNamespace.includes(data.instanceId),'Instance storage not isolated');
+    if(data.runtime.contentReference) {
+      assert.deepEqual(config.pages,scope.pages.map(page=>({id:page.id,title:page.title})),'Business configuration differs from fixed page scope');
+      assert.ok(['needs-adaptation','adapted'].includes(data.business?.status),'Unknown business implementation status');
+      const fixedBindings=[...json(inside(directory,'inputs/capabilities.json')).bindings,...(generation?.bindings||[])];
+      assert.deepEqual((mapping.bindings||[]).map(binding=>binding.id).sort(),fixedBindings.map(binding=>binding.id).sort(),'Business mapping omits fixed capabilities');
+    }
+    const themeBinding=json(inside(directory,'inputs/capabilities.json')).bindings.find(binding=>data.runtime.contentReference?binding.capabilityId==='theme':binding.id==='devices/device-list/theme');
+    if(themeBinding)assert.deepEqual(config.theme,templates().resolveThemeParameters(themeBinding.parameters),'Theme configuration differs from fixed input binding');
+    else assert.equal(config.theme,undefined,'Theme requires an explicit optional capability binding');
+    if(generation){assert.deepEqual(config.presentation,generation.presentation,'Customer presentation differs from fixed choices');assert.deepEqual(config.navigation,generation.navigation,'Navigation differs from fixed generation');assert.deepEqual(config.generation,{pages:generation.pages},'Business page patterns differ from fixed generation');}
+    const deps=json(inside(directory,'app/package.json')).dependencies; assert.ok(deps['antdv-next'] && deps.vue,'Native framework dependencies missing');
+    if(generation)require('./generation-evidence.cjs').validateImplementation(directory,generation,json(inside(directory,'design-system/implementation.json')),{complete:!!options.acceptance,frameworkMap:fixedFramework.componentMap});
+    if(options.acceptance) {
+      if(generation){assert.equal(generation.pendingDecisions.length,0,'Reference applicability decisions remain unresolved');assert.equal(generation.pendingReferenceElements.length,0,'Reference functional elements remain unaccounted for');}
+      if(data.runtime.contentReference)assert.equal(data.business?.status,'adapted','Business implementation pending; a scaffold cannot pass acceptance');
+      const adoptedAdvice=inspectDesignReview(directory,current).adoptedAdvice;
+      const report=options.report||json(inside(directory,json(inside(directory,'qa/latest.json')).report));
+      assert.equal(report.status,'passed'); assert.equal(report.candidateDigest,current.digest,'Browser evidence is stale'); assert.equal(report.revision,current.revision);
+      const build=verifyBuild(directory,report.buildId); assert.equal(report.buildDigest,build.buildDigest);
+      assert.ok(report.executor && report.tool && report.startedAt && report.completedAt && report.source,'Browser run provenance required');
+      require('./native-build.cjs').verifyBrowserReport(directory,report,build);
+      assert.deepEqual(report.consoleErrors,[],'Browser errors remain');
+      const required=[...acceptance.requiredScenarios,...acceptance.frameworkScenarios];
+      for(const scenario of required) assert.ok(report.journeys.some(j=>j.id===scenario && j.status==='passed'),`Missing browser scenario: ${scenario}`);
+      if(generation)require('./generation-evidence.cjs').validateObservations(directory,generation,report);
+      for(const record of adoptedAdvice)assert.ok(report.journeys.some(j=>j.id===record.verificationScenario && j.status==='passed'),`Advice verification missing: ${record.resultIdentity}`);
+      require('./execution-runtime.cjs').requireStage(directory,'delivery',module.exports,{businessReport:report});
+    }
+    return {status:'passed',level:options.acceptance?'acceptance':'structure',revision:current.revision,digest:current.digest,verification:data.verification.status,review:effectiveReview(data,current).status};
+  } catch(error) { return {status:'failed',errors:[error.message]}; }
+}
+function inspect(directory,options={}) { return inspectWithInputs(directory,options); }
+function expected(directory,options) {
+  const current=manifest(directory);
+  assert.equal(options.expectedRevision,current.revision,'Stale revision / 版本冲突'); assert.equal(options.expectedDigest,current.digest,'Candidate changed / 内容变化'); return current;
+}
+function claim(directory,options) {
+  id(options.owner); expected(directory,options);
+  const lock=inside(directory,'.prototype-write.lock'); const fd=fs.openSync(lock,'wx');
+  try { fs.writeFileSync(fd,JSON.stringify({owner:options.owner,revision:options.expectedRevision,digest:options.expectedDigest})); }
+  finally { fs.closeSync(fd); }
+  write(directory,'execution.json',{owner:options.owner,status:'editing',revision:options.expectedRevision,digest:options.expectedDigest}); return {owner:options.owner};
+}
+function release(directory,owner) {
+  const lock=inside(directory,'.prototype-write.lock'); assert.equal(json(lock).owner,owner,'Different writing owner');
+  fs.unlinkSync(lock); write(directory,'execution.json',{owner,status:'released'}); return {status:'released'};
+}
+function mutate(directory,options,fn) {
+  const lock=inside(directory,'.prototype-write.lock'); const temporary=!fs.existsSync(lock); const owner=options.owner||`run-${crypto.randomUUID()}`;
+  if(temporary) claim(directory,{...options,owner}); else { assert.equal(json(lock).owner,owner,'Candidate has another writing owner'); expected(directory,options); }
+  try { return fn(); } finally { if(temporary) release(directory,owner); }
+}
+function revise(directory,options) {
+  id(options.revision);
+  assert.ok(options.acceptInputs===undefined||typeof options.acceptInputs==='boolean','--accept-inputs must be a boolean flag');
+  return mutate(directory,options,()=>{
+    const current=manifest(directory);
+    const data=metadata(directory); assert.notEqual(data.revision,options.revision); assert.ok(!fs.existsSync(inside(directory,`baselines/${options.revision}`)),'Revision already frozen');
+    if(options.acceptInputs) {
+      const checked=inspectWithInputs(directory,{},current.inputDigest);
+      assert.equal(checked.status,'passed',checked.errors?.join('; '));
+    } else assert.equal(data.inputs.digest,current.inputDigest,'Input contract changed; revise --accept-inputs must explicitly validate the new contract');
+    assert.equal(manifest(directory).digest,current.digest,'Candidate changed while validating fixed inputs');
+    const scope=json(inside(directory,'inputs/scope.json')); projectRegistry.moduleIds(scope);
+    return projectRegistry.withInstanceAssociation(directory,scope,()=>{
+      if(options.acceptInputs)data.inputs={digest:current.inputDigest};
+      data.revision=options.revision; data.verification={status:'not-run'}; data.review={status:'pending-review'};
+      write(directory,'prototype.json',data); return manifest(directory);
+    });
+  });
+}
+function replan(directory,options) { const owner=options.owner||`replan-${crypto.randomUUID()}`;return mutate(directory,{...options,owner},()=>require('./generation-replan.cjs').run(directory,{...options,owner},module.exports)); }
+function build(directory,options={}) { const gates=require('./execution-runtime.cjs');gates.requireStage(directory,'implementation',module.exports);gates.requireStage(directory,'design',module.exports);return require('./native-build.cjs').build(directory,options,{manifest,inspect}); }
+function synchronizeIndex(options={}) {
+  id(options.id);
+  const index=projectRegistry.read(options.project),entry=index.registry.prototypes.find(item=>item.id===options.id);
+  assert.ok(entry,'Prototype is not registered');
+  const directory=inside(index.project,entry.directory),scope=json(inside(directory,'inputs/scope.json'));
+  assert.ok(scope.moduleIds!==undefined||scope.schemaVersion===2,'Legacy scope has no explicit moduleIds; do not invent or rewrite old input contracts');
+  const current=manifest(directory);
+  return mutate(directory,{...options,expectedRevision:current.revision,expectedDigest:current.digest},()=>{
+    const checked=inspect(directory);assert.equal(checked.status,'passed',checked.errors?.join('; '));
+    return projectRegistry.transaction(index.project,store=>{
+      const selected=store.registry.prototypes.find(item=>item.id===options.id);
+      assert.ok(selected&&selected.directory===entry.directory,'Prototype index entry changed during synchronization');
+      const fixed=json(inside(directory,'inputs/scope.json')),appliesTo=projectRegistry.moduleIds(fixed);
+      assert.equal(manifest(directory).digest,current.digest,'Candidate changed during synchronization');
+      selected.appliesTo=appliesTo;store.save();
+      return {status:'synchronized',index:store.file,id:selected.id,appliesTo};
+    });
+  });
+}
+function verifyBuild(directory,buildId) { return require('./native-build.cjs').verifyBuild(directory,buildId,{manifest}); }
+function preview(directory,options={}) { return require('./native-build.cjs').preview(directory,options,{manifest}); }
+function recordRun(directory,report) {
+  report=JSON.parse(JSON.stringify(report));
+  id(report.id); const current=manifest(directory); assert.equal(report.candidateDigest,current.digest,'Candidate changed during browser run'); assert.equal(report.revision,current.revision);
+  const result=inspect(directory,{acceptance:true,report}); assert.equal(result.status,'passed',result.errors?.join('; '));
+  assert.equal(manifest(directory).digest,current.digest,'Candidate changed while checking browser report');
+  const relative=`qa/runs/${report.id}/report.json`,existing=inside(directory,relative);
+  if(fs.existsSync(existing))assert.deepEqual(json(existing),report,'Published browser run is immutable; use a new run ID');
+  else write(directory,relative,report);
+  write(directory,'qa/latest.json',{report:relative});
+  const data=metadata(directory); data.verification={status:'passed',digest:current.digest,run:report.id};
+  data.review=effectiveReview(data,current);
+  if(data.expertMode==='professional') {
+    const advice=json(inside(directory,'qa/design-advice.json'));
+    data.expert.status=advice.records.some(record=>['adopted','adjusted'].includes(record.decision))?'used':advice.records.every(record=>record.decision==='no-match')?'no-match':'reviewed';
+  }
+  write(directory,'prototype.json',data); return {...result,verification:'passed'};
+}
+function confirmBaseline(directory,confirmation) {
+  assert.ok(confirmation.reviewer && confirmation.statement && confirmation.source,'Explicit human confirmation required / 人类确认');
+  const current=manifest(directory); assert.equal(confirmation.revision,current.revision); assert.equal(confirmation.digest,current.digest);
+  return mutate(directory,{expectedRevision:current.revision,expectedDigest:current.digest},()=>{
+    const checked=inspect(directory,{acceptance:true}); assert.equal(checked.status,'passed',checked.errors?.join('; '));
+    const devtoolsReview=require('./native-devtools.cjs').check(directory,module.exports);assert.ok(!devtoolsReview.required||devtoolsReview.status==='current',`Current DevTools review required: ${devtoolsReview.errors?.join('; ')||devtoolsReview.status}`);
+    const target=inside(directory,`baselines/${id(current.revision)}`); assert.ok(!fs.existsSync(target),'Baseline exists');
+    fs.mkdirSync(path.dirname(target),{recursive:true});const stage=fs.mkdtempSync(path.join(path.dirname(target),'.freeze-'));
+    try {
+      for(const [file,digest]of Object.entries(current.files)) {
+        const destination=inside(stage,file);fs.mkdirSync(path.dirname(destination),{recursive:true});fs.copyFileSync(inside(directory,file),destination);
+        assert.equal(hash(fs.readFileSync(destination)),digest,`Snapshot copy differs: ${file}`);
+      }
+      write(stage,'manifest.json',current);write(stage,'review.json',confirmation);const reviewDigest=hash(fs.readFileSync(path.join(stage,'review.json')));
+      assert.equal(manifest(directory).digest,current.digest,'Candidate changed during freezing');
+      fs.renameSync(stage,target);
+      write(directory,'baseline.json',{schemaVersion:2,revision:current.revision,digest:current.digest,reviewDigest,directory:`baselines/${current.revision}`});
+      const data=metadata(directory);data.review={status:'approved',revision:current.revision,digest:current.digest};write(directory,'prototype.json',data);return current;
+    } finally {if(fs.existsSync(stage))fs.rmSync(stage,{recursive:true,force:true});}
+  });
+}
+function compareBaseline(directory) {
+  if(!fs.existsSync(inside(directory,'baseline.json'))) return {status:'no-baseline',changes:[],protectedChanges:[]};
+  const baseline=json(inside(directory,'baseline.json')); const folder=inside(directory,baseline.directory); const saved=json(path.join(folder,'manifest.json'));
+  if(hash(fs.readFileSync(path.join(folder,'review.json')))!==baseline.reviewDigest || saved.digest!==baseline.digest || hash(JSON.stringify({identity:saved.identity,files:saved.files}))!==saved.digest || Object.entries(saved.files).some(([f,d])=>!fs.existsSync(inside(folder,f))||hash(fs.readFileSync(inside(folder,f)))!==d)) return {status:'corrupt-baseline'};
+  const current=manifest(directory); const changes=[...new Set([...Object.keys(saved.files),...Object.keys(current.files)])].filter(f=>saved.files[f]!==current.files[f]);
+  return {status:current.digest===saved.digest?'unchanged':'changed',changes,protectedChanges:changes,revision:current.revision,baselineRevision:saved.revision};
+}
+function state(directory,options={}) { return require('./native-delivery.cjs').state(directory,options,module.exports); }
+function finalize(directory,options={}) { return require('./native-delivery.cjs').finalize(directory,options,module.exports); }
+module.exports={analyze,prepareTemplate,createPrototype,manifest,inspect,inspectDesignReview,effectiveReview,claim,release,revise,replan,synchronizeIndex,build,verifyBuild,preview,recordRun,confirmBaseline,compareBaseline,state,finalize};

package/skills/i3-ui-prototype/scripts/native-pilot.cjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+'use strict';
+const path=require('node:path');
+const fs=require('node:fs');
+const lib=require('./native-pilot-lib.cjs');
+async function main(argv=process.argv.slice(2)) {
+  const operation=argv.shift()||'analyze'; const positional=[]; const options={};
+  while(argv.length) { const value=argv.shift(); if(value==='--') { options.command=argv.splice(0); break; } if(value.startsWith('--')) { const key=value.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase()); options[key]=!argv.length||argv[0].startsWith('--')?true:argv.shift(); } else positional.push(value); }
+  const root=positional[0]?path.resolve(positional[0]):null;
+  switch(operation) {
+    case 'analyze': return lib.analyze(options);
+    case 'paths': { const context=require('./prototype-locations.cjs').resolveLocations(options); return {...require('./project-registry.cjs').paths(options.project,options.id),host:context.host,scope:context.scope,projectKey:context.projectKey,toolsDirectory:context.toolsDirectory,cacheDirectory:context.cacheDirectory}; }
+    case 'index': return require('./project-registry.cjs').query(options);
+    case 'sync-index': return lib.synchronizeIndex(options);
+    case 'migrate-index': return require('./project-registry.cjs').migrate(options);
+    case 'browser-cache': return require('./browser-workspace.cjs').prepare(options);
+    case 'browser-cli': return require('./browser-workspace.cjs').runCli(options);
+    case 'archive-browser-output': return require('./browser-workspace.cjs').archive(options);
+    case 'prepare-template': return lib.prepareTemplate(options);
+    case 'sync-template': { const templates=require('./template-contract.cjs'); return options.check?templates.loadTemplate(root).index:templates.syncTemplate(root); }
+    case 'template-page': { const templates=require('./template-contract.cjs'); return require('./content-template.cjs').pageContent(root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template),options.page); }
+    case 'generation-options': { const templates=require('./template-contract.cjs'),snapshot=root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template),meta=require('./generation-contract.cjs').resource(snapshot,'generation.json');return {status:'passed',readOnly:true,template:snapshot.id,...meta,patterns:require('./generation-contract.cjs').definition().patterns}; }
+    case 'generation-plan': { const templates=require('./template-contract.cjs'),snapshot=root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template);const contract=require('./generation-contract.cjs');return contract.view(contract.compile(snapshot,JSON.parse(fs.readFileSync(path.resolve(options.scope),'utf8'))),options); }
+    case 'inventory': { const templates=require('./template-contract.cjs'),snapshot=root?templates.loadTemplate(root):templates.loadBundledTemplate(options.template),value=require('./template-inventory.cjs').verifySnapshot(snapshot);return options.details?value:{status:'passed',readOnly:true,template:snapshot.id,files:Object.keys(value.files).length,routes:value.routes.length,pages:value.pages.length,fragments:value.fragments.length,components:Object.keys(value.components).length,events:value.eventCount}; }
+    case 'sync-generation-assets': return require('./generation-assets.cjs').refresh(path.resolve(__dirname,'..'),{check:!!options.check});
+    case 'create': return lib.createPrototype(options);
+    case 'execution-begin': return require('./execution-runtime.cjs').begin(root,lib);
+    case 'execution-assertions-template': return require('./execution-assertions.cjs').template(options);
+    case 'execution-template': return require('./execution-runtime.cjs').template(root,lib);
+    case 'execution-check': return require('./execution-runtime.cjs').check(root,options.stage||'delivery',lib);
+    case 'manifest': return lib.manifest(root);
+    case 'inspect': return lib.inspect(root,{acceptance:!!options.acceptance});
+    case 'state': return lib.state(root,options);
+    case 'browser': return require('./native-browser.cjs').main(root,options);
+    case 'record-devtools-review': return require('./native-devtools.cjs').record(root,JSON.parse(fs.readFileSync(path.resolve(options.report),'utf8')),lib);
+    case 'finalize': return lib.finalize(root,options);
+    case 'build': return lib.build(root,options);
+    case 'preview': { const running=await lib.preview(root,options); process.stdout.write(JSON.stringify({url:running.url,buildId:running.build.buildId})+'\n'); return null; }
+    case 'revise': return lib.revise(root,options);
+    case 'replan': return lib.replan(root,options);
+    case 'claim': return lib.claim(root,options);
+    case 'release': return lib.release(root,options.owner);
+    case 'record-run': return lib.recordRun(root,JSON.parse(fs.readFileSync(path.resolve(options.report),'utf8')));
+    case 'compare-baseline': return lib.compareBaseline(root);
+    case 'confirm-baseline': return lib.confirmBaseline(root,JSON.parse(fs.readFileSync(path.resolve(options.confirmation),'utf8')));
+    default: throw new Error(`Unknown operation: ${operation}`);
+  }
+}
+if(require.main===module) main().then(result=>{if(result!==null){process.stdout.write(JSON.stringify(result,null,2)+'\n');if(result.status==='failed')process.exitCode=1;}}).catch(error=>{process.stderr.write(JSON.stringify({status:'failed',operation:process.argv[2]||'analyze',errors:[error.message]})+'\n');process.exitCode=1;});
+module.exports={main};

package/skills/i3-ui-prototype/scripts/optional-skill-install.cjs

@@ -0,0 +1,203 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+const sources = require('../assets/optional-skills/sources.json');
+
+function selection(value = 'none') {
+  if (typeof value !== 'string') throw new Error('Optional Skill selection must be a string');
+  const names = [...new Set(value.split(',').map(name => name.trim()))];
+  if (names.length === 1 && names[0] === 'none') return [];
+  if (!names.length || names.some(name => !['uiux', 'antdv'].includes(name))) throw new Error('Choose none, uiux, antdv or uiux,antdv');
+  return names;
+}
+function safePath(project, relative) {
+  let current = project;
+  for (const part of relative.split('/')) {
+    if (!part || part === '..') throw new Error('Invalid install path');
+    current = path.join(current, part);
+    try { if (fs.lstatSync(current).isSymbolicLink()) throw new Error(`Install path contains a symlink: ${current}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return current;
+}
+function verify(data, expected, algorithm = 'sha256', encoding = 'hex') {
+  if (crypto.createHash(algorithm).update(data).digest(encoding) !== expected) throw new Error('Official download integrity mismatch');
+  return data;
+}
+async function download(url, expected, algorithm, encoding) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(60000) });
+  if (!response.ok) throw new Error(`Official download failed: HTTP ${response.status}`);
+  const data = Buffer.from(await response.arrayBuffer());
+  if (data.length > 50 * 1024 * 1024) throw new Error('Official download exceeds size limit');
+  return verify(data, expected, algorithm, encoding);
+}
+function npmEntry() {
+  const directory = path.dirname(process.execPath);
+  const candidates = [process.env.npm_execpath, path.join(directory, '../lib/node_modules/npm/bin/npm-cli.js'), path.join(directory, 'node_modules/npm/bin/npm-cli.js')];
+  for (const folder of (process.env.PATH || '').split(path.delimiter)) {
+    const entry = path.join(folder, 'npm');
+    if (fs.existsSync(entry)) candidates.push(fs.realpathSync(entry));
+  }
+  const found = candidates.find(file => file && path.basename(file) === 'npm-cli.js' && fs.existsSync(file));
+  if (!found) throw new Error('Cannot locate npm-cli.js; use a standard Node.js/npm installation');
+  return found;
+}
+function run(entry, args, cwd, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entry, ...args], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '', failed = false;
+    const timer = setTimeout(() => { failed = true; child.kill(); reject(new Error('Official installer timed out')); }, 180000);
+    for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => {
+      output += chunk;
+      if (output.length > 5 * 1024 * 1024) { failed = true; child.kill(); reject(new Error('Official installer output exceeds limit')); }
+    });
+    child.once('error', error => { clearTimeout(timer); failed = true; reject(error); });
+    child.once('close', code => { clearTimeout(timer); if (!failed) code === 0 ? resolve() : reject(new Error(`Official installer failed (${code}): ${output.slice(-1500)}`)); });
+  });
+}
+function validateSkill(folder, name) {
+  const entry = fs.readFileSync(path.join(folder, 'SKILL.md'), 'utf8');
+  if (!new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, 'm').test(entry)) throw new Error(`Official Skill identity mismatch: ${name}`);
+  function visit(directory) {
+    for (const item of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (item.isSymbolicLink()) throw new Error('Official Skill contains a symbolic link');
+      if (item.isDirectory()) visit(path.join(directory, item.name));
+      else if (!item.isFile()) throw new Error('Official Skill contains an unsupported file');
+    }
+  }
+  visit(folder);
+  if (name === 'ui-ux-pro-max') for (const file of ['scripts/search.py', 'scripts/core.py', 'scripts/design_system.py', 'data/ux-guidelines.csv']) {
+    if (!fs.existsSync(path.join(folder, file))) throw new Error(`Incomplete UIUX resources: ${file}`);
+  }
+}
+function uiuxPaths(packageRoot, skill, context, platform) {
+  const templates = path.join(packageRoot, 'assets/templates');
+  const config = JSON.parse(fs.readFileSync(path.join(templates, 'platforms', `${platform}.json`), 'utf8'));
+  const template = fs.readFileSync(path.join(templates, 'base/skill-content.md'), 'utf8');
+  const scriptFile = path.join(context.destination, 'scripts/search.py');
+  const script = (context.scope === 'global' ? scriptFile : path.relative(context.project, scriptFile)).split(path.sep).join('/');
+  const command = /^[a-zA-Z0-9_./:-]+$/.test(script) ? script : process.platform === 'win32' ? "'" + script.replaceAll("'", "''") + "'" : "'" + script.replaceAll("'", "'\\''") + "'";
+  const parameters = { TITLE: config.title, DESCRIPTION: config.description, SCRIPT_PATH: command, SKILL_OR_WORKFLOW: config.skillOrWorkflow,
+    QUICK_REFERENCE: config.sections.quickReference ? '\n' + fs.readFileSync(path.join(templates, 'base/quick-reference.md'), 'utf8') : '' };
+  const file = path.join(skill, 'SKILL.md'), original = fs.readFileSync(file, 'utf8');
+  const header = original.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/)?.[0];
+  if (!header) throw new Error('Official UIUX frontmatter is missing');
+  // Only official template placeholders are parameterized. The downloaded
+  // template and CLI code remain unchanged; paths work in every supported host.
+  const body = template.replace(/\{\{([A-Z_]+)\}\}/g, (match, key) => {
+    if (!Object.hasOwn(parameters, key)) throw new Error(`Unknown official UIUX placeholder: ${key}`);
+    return parameters[key];
+  });
+  fs.writeFileSync(file, header + body);
+  return { platform, script, command, templateSha256: crypto.createHash('sha256').update(template).digest('hex') };
+}
+async function prepareOfficial(name, stage, context) {
+  const source = sources[name], tool = path.join(stage, 'tool'), workspace = path.join(stage, 'workspace');
+  fs.mkdirSync(tool, { recursive: true }); fs.mkdirSync(workspace);
+  const archive = await download(source.tarball, source.integrity.slice(7), 'sha512', 'base64');
+  fs.writeFileSync(path.join(tool, 'source.tgz'), archive);
+  const env = { ...process.env, npm_config_cache: path.join(stage, 'npm-cache'), npm_config_offline: 'false', NPM_CONFIG_OFFLINE: 'false', npm_config_update_notifier: 'false', ANTDV_NO_AUTO_REPORT: '1' };
+  await run(npmEntry(), ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock', './source.tgz'], tool, env);
+  const packageRoot = path.join(tool, 'node_modules', source.packageName), pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  if (pkg.name !== source.packageName || pkg.version !== source.version) throw new Error('Official CLI version mismatch');
+  let skill, pathParameters;
+  if (name === 'uiux') {
+    const platform = ['codebuddy', 'workbuddy'].includes(context.host) ? 'codebuddy' : context.host === 'codex' ? 'codex' : context.host === 'claude-code' ? 'claude' : 'universal';
+    await run(path.join(packageRoot, pkg.bin.uipro), ['init', '--ai', platform, '--offline'], workspace, env);
+    const config = JSON.parse(fs.readFileSync(path.join(packageRoot, 'assets/templates/platforms', `${platform}.json`), 'utf8'));
+    skill = path.join(workspace, config.folderStructure.root, config.folderStructure.skillPath);
+    pathParameters = uiuxPaths(packageRoot, skill, context, platform);
+  } else {
+    skill = path.join(workspace, 'antdv'); fs.mkdirSync(skill);
+    fs.writeFileSync(path.join(skill, 'SKILL.md'), await download(source.skillUrl, source.skillSha256));
+  }
+  fs.writeFileSync(path.join(skill, 'LICENSE'), await download(source.licenseUrl, source.licenseSha256));
+  const receipt = JSON.stringify({ ...source, installedAt: new Date().toISOString(), installer: 'i3 optional dependency preparation; official templates retained',
+    ...(pathParameters ? { pathParameters } : {}) }, null, 2) + '\n';
+  fs.writeFileSync(path.join(skill, 'UPSTREAM-ORIGIN.json'), receipt);
+  if (name === 'antdv') fs.writeFileSync(path.join(tool, 'UPSTREAM-ORIGIN.json'), receipt);
+  return { skill, tool };
+}
+async function install(options = {}, services = {}) {
+  if (options.provider !== undefined || options.tool !== undefined) throw new Error('--provider and --tool are for read-only check');
+  const deps = require('./prototype-dependencies.cjs');
+  const names = selection(options.skills), before = deps.check(options), context = before.locations;
+  if (options.migrateTools && (context.scope !== 'project' || !names.includes('antdv'))) throw new Error('--migrate-tools requires project scope and selected antdv');
+  if (!names.length) return { status: 'skipped', selected: [], detection: before };
+  const pending = [], preserved = [];
+  const safe = file => safePath(path.parse(file).root, path.relative(path.parse(file).root, file).split(path.sep).join('/'));
+  for (const name of names) {
+    const source = sources[name], destination = safe(path.join(context.skillsDirectory, source.skillName));
+    const available = name === 'uiux' ? before.uiux.availability === 'available' : before.antdv.skill.availability === 'available';
+    const needsSkill = !available;
+    if (needsSkill && fs.existsSync(destination)) throw new Error(`Existing Skill preserved; repair or choose its actual provider path: ${destination}`);
+    const toolDestination = name === 'antdv' ? safe(path.join(context.toolsDirectory, 'antdv-cli')) : null;
+    if (name === 'antdv' && before.antdv.tool.availability === 'unusable') throw new Error(`Existing tool unusable; preserved: ${before.antdv.tool.root}`);
+    const needsTool = name === 'antdv' && before.antdv.tool.availability === 'missing' && !fs.existsSync(toolDestination);
+    if (name === 'antdv' && before.antdv.tool.availability === 'missing' && fs.existsSync(toolDestination)) throw new Error(`Existing tool directory preserved: ${toolDestination}`);
+    let migration;
+    if (name === 'antdv' && options.migrateTools && fs.existsSync(path.join(context.project, '.prototype-tools'))) {
+      migration = safe(path.join(context.project, '.prototype-tools/antdv-cli'));
+      if (!fs.existsSync(migration)) {
+        if (fs.existsSync(path.join(context.project, '.prototype-tools/node_modules/@antdv-next/cli'))) throw new Error('Legacy mixed tools have no independent i3 ownership; preserved');
+        migration = undefined;
+      }
+    }
+    if (migration) {
+      let receipt;
+      try { receipt = JSON.parse(fs.readFileSync(path.join(migration, 'UPSTREAM-ORIGIN.json'), 'utf8')); } catch { /* handled below */ }
+      if (!receipt?.installer?.startsWith('i3 optional dependency preparation') || receipt.packageName !== sources.antdv.packageName || receipt.version !== sources.antdv.version || receipt.integrity !== sources.antdv.integrity) throw new Error('Legacy tool has no verified i3 ownership; preserved');
+      if (deps.antdvTool(context.project, { ...options, host: context.host, scope: context.scope, tool: path.join(migration, 'node_modules/@antdv-next/cli') }).availability !== 'available') throw new Error('Legacy tool query failed; preserved');
+      if (fs.existsSync(toolDestination)) throw new Error(`Existing tool directory preserved: ${toolDestination}`);
+    }
+    if (needsSkill || needsTool || migration) pending.push({ name, destination, needsSkill, toolDestination, needsTool, migration });
+    if (!needsSkill) preserved.push(name);
+  }
+  if (!pending.length) return { status: 'reused', selected: names, preserved, detection: before };
+  const tools = safe(context.toolsDirectory), committed = [], created = [];
+  const lock = path.join(tools, '.i3-optional-install.lock');
+  let descriptor, stage, result;
+  const mkdir = directory => { if (!fs.existsSync(directory)) { mkdir(path.dirname(directory)); fs.mkdirSync(directory); created.push(directory); } };
+  try {
+    mkdir(tools); descriptor = fs.openSync(lock, 'wx');
+    stage = fs.mkdtempSync(path.join(tools, '.i3-optional-stage-'));
+    const moves = [];
+    for (const item of pending) {
+      if (item.needsSkill || item.needsTool) {
+        (services.progress || (message => process.stderr.write(message + '\n')))(`准备官方依赖：${item.name}（${context.host} / ${context.scope}）`);
+        const folder = path.join(stage, item.name); fs.mkdirSync(folder);
+        const prepared = await (services.prepare || prepareOfficial)(item.name, folder, { ...context, destination: item.destination });
+        if (item.needsSkill) { validateSkill(prepared.skill, sources[item.name].skillName); moves.push({ from: prepared.skill, to: item.destination }); }
+        if (item.needsTool) moves.push({ from: prepared.tool, to: item.toolDestination });
+      }
+      if (item.migration) moves.push({ from: item.migration, to: item.toolDestination, migration: true });
+    }
+    for (const move of moves) {
+      const { from, to } = move; safe(from); safe(to);
+      if (fs.existsSync(to)) throw new Error(`Destination appeared during install; preserved: ${to}`);
+      mkdir(path.dirname(to)); fs.renameSync(from, to); committed.push(move);
+    }
+    const detection = deps.check(options);
+    if (names.includes('antdv') && detection.antdv.tool.availability !== 'available') throw new Error('Installed or migrated antDv tool query failed');
+    const migrated = committed.filter(item => item.migration).map(item => ({ from: item.from, to: item.to }));
+    result = { status: migrated.length && pending.every(item => !item.needsSkill && !item.needsTool) ? 'migrated' : 'installed', selected: names, preserved,
+      installed: pending.filter(item => item.needsSkill || item.needsTool).map(item => item.name), migrated, detection,
+      note: 'Reload the selected host or open a new session if needed. Installation/probing does not prove Skill invocation. Existing prototypes are unchanged.' };
+  } catch (error) {
+    for (const move of committed.reverse()) {
+      if (move.migration) fs.renameSync(move.to, move.from);
+      else fs.rmSync(move.to, { recursive: true, force: true });
+    }
+    throw error;
+  } finally {
+    if (stage) fs.rmSync(stage, { recursive: true, force: true });
+    if (descriptor !== undefined) { fs.closeSync(descriptor); fs.unlinkSync(lock); }
+    for (const directory of created.reverse()) if (fs.existsSync(directory) && !fs.readdirSync(directory).length) fs.rmdirSync(directory);
+  }
+  const legacy = path.join(context.project, '.prototype-tools');
+  if (result.migrated.length && !fs.readdirSync(legacy).length) fs.rmdirSync(legacy);
+  return result;
+}
+module.exports = { install, selection, safePath, verify, validateSkill };