@givolt/i3-composer-agent 2.3.1 → 2.3.2

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

@@ -0,0 +1,34 @@
+#!/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.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 '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.page); }
+    case 'create': return lib.createPrototype(options);
+    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 '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 };

package/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { checkDesignProvider } = require('./prototype-lib.cjs');
+const { discoverProviderCandidates } = require('./design-provider-discovery.cjs');
+const { resolveLocations, scopeBases, toolCandidates } = require('./prototype-locations.cjs');
+
+function skillAt(project, name, options = {}) {
+  const context = resolveLocations({ ...options, project });
+  const candidates = scopeBases(context).map(([root, scope]) => [path.join(root, 'skills', name), `${scope}-skill`]);
+  const legacyConfig = (options.env || process.env).CODEBUDDY_CONFIG_DIR;
+  if (context.host === 'codebuddy' && legacyConfig) candidates.push([path.resolve(legacyConfig, 'skills', name), 'global-skill']);
+  const found = candidates.find(([root]) => fs.existsSync(path.join(root, 'SKILL.md')));
+  return found ? { availability: 'available', root: found[0], source: found[1], invocationVerified: false }
+    : { availability: 'missing', searched: candidates.map(([root]) => root), invocationVerified: false };
+}
+function antdvTool(project, options = {}) {
+  const candidates = toolCandidates(resolveLocations({ ...options, project }), options);
+  const found = candidates.find(item => fs.existsSync(item.root));
+  if (!found) return { availability: 'missing', searched: candidates.map(item => item.root), componentVersion: '1.5.3' };
+  const { root, source } = found;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name !== '@antdv-next/cli' || typeof pkg.bin?.antdv !== 'string') throw new Error('Unexpected antDv CLI package');
+    const entry = path.resolve(root, pkg.bin.antdv), relative = path.relative(root, entry);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('CLI entry escapes its package');
+    const args = [entry, 'info', 'Table', '--ver', '1.5.2', '--format', 'json'];
+    const result = spawnSync(process.execPath, args, { cwd: project, env: { ...(options.env || process.env), ANTDV_NO_AUTO_REPORT: '1' }, encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
+    if (result.status !== 0) throw new Error(result.error?.message || result.stderr || 'CLI query failed');
+    const data = JSON.parse(result.stdout);
+    if (!data || data.name !== 'Table' || !Array.isArray(data.props) || data.error) throw new Error('CLI returned no Table knowledge');
+    return { availability: 'available', root, source, entry, version: pkg.version, command: [process.execPath, ...args], knowledgeVersion: '1.5.2', componentVersion: '1.5.3', exactKnowledgeMatch: false,
+      limitation: 'CLI knowledge 1.5.2 is reference only; verify target 1.5.3 package types/source.' };
+  } catch (error) { return { availability: 'unusable', root, source, reason: error.message }; }
+}
+function check(options = {}) {
+  const locations = resolveLocations(options), { project, host, scope } = locations;
+  const roots = scopeBases(locations).map(([base]) => path.join(base, 'skills/ui-ux-pro-max'));
+  const sources = new Map(scopeBases(locations).map(([base, scope]) => [path.join(base, 'skills/ui-ux-pro-max'), `${scope}-skill`]));
+  let discovery;
+  if (options.provider === undefined) {
+    const aliases = { 'gemini-cli': 'gemini', 'claude-code': 'claude' };
+    // Resolve global registrations from home so project-scoped plugins from the
+    // business workspace are never reused by a global installation.
+    discovery = discoverProviderCandidates({ ...options, project: scope === 'global' ? locations.home : project, host: aliases[host] || host });
+    for (const item of discovery.candidates) { roots.push(item.root); if (!sources.has(item.root)) sources.set(item.root, item.source); }
+  }
+  const uiux = checkDesignProvider({ ...options, project, host, ...(options.provider === undefined ? { providerRoots: [...new Set(roots)] } : {}) });
+  if (discovery) {
+    uiux.diagnostics.push(...discovery.diagnostics);
+    if (uiux.root) uiux.source = sources.get(uiux.root) || uiux.source;
+    for (const attempt of uiux.attempts) attempt.source = sources.get(attempt.root) || attempt.source;
+    const failure = ['ambiguous', 'disabled', 'discovery-error'].map(status => discovery.diagnostics.find(item => item.availability === status)).find(Boolean);
+    if (uiux.availability === 'missing' && failure) Object.assign(uiux, { availability: failure.availability, reason: failure.reason });
+  }
+  const scoped = { ...options, host, scope };
+  const antdv = { skill: skillAt(project, 'antdv', scoped), tool: antdvTool(project, scoped) };
+  return { status: 'checked', host, scope, project, locations, uiux, antdv, optional: true, professionalReady: uiux.availability === 'available',
+    invocationVerified: false, note: 'Read-only availability probe; the selected host must discover and actually invoke Skills. No dependency installation, migration or prototype changes.' };
+}
+function parse(argv) {
+  const operation = argv.shift() || 'check', options = {};
+  if (!['check', 'install'].includes(operation)) throw new Error('Use check or install');
+  const flags = new Set(['project', 'host', 'scope', 'skills', 'provider', 'python', 'tool']);
+  while (argv.length) {
+    const key = argv.shift();
+    if (key === '--migrate-tools' && operation === 'install') { options.migrateTools = true; continue; }
+    if (!key.startsWith('--') || !flags.has(key.slice(2)) || !argv[0] || argv[0].startsWith('--')) throw new Error(`Invalid option: ${key}`);
+    options[key.slice(2)] = argv.shift();
+  }
+  return { operation, options };
+}
+async function main(argv = process.argv.slice(2)) {
+  const { operation, options } = parse([...argv]);
+  return operation === 'check' ? check(options) : require('./optional-skill-install.cjs').install(options);
+}
+module.exports = { check, skillAt, antdvTool, parse, main };
+if (require.main === module) main().then(result => process.stdout.write(JSON.stringify(result, null, 2) + '\n'))
+  .catch(error => { process.stderr.write(JSON.stringify({ status: 'failed', errors: [error.message] }) + '\n'); process.exitCode = 1; });

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

@@ -48,17 +48,27 @@ function tokensCss(tokens) {
   return ':root {\n' + entries.map(([key, value]) => `  --${key}: ${value};`).join('\n') + '\n}\n';
 }
 function providerVersion(root) {
+  const receipt = path.join(root, 'UPSTREAM-ORIGIN.json');
+  if (fs.existsSync(receipt)) {
+    try { const source = json(receipt); if (source.packageName === 'ui-ux-pro-max-cli' && typeof source.version === 'string') return source.version; } catch {}
+  }
   for (let folder = root, i = 0; i < 5; i++, folder = path.dirname(folder)) {
     for (const name of ['skill.json', '.claude-plugin/plugin.json', '.codebuddy-plugin/plugin.json', 'package.json']) {
       const file = path.join(folder, name);
-      if (fs.existsSync(file)) { try { const version = json(file).version; if (version) return version; } catch {} }
+      if (fs.existsSync(file)) {
+        try {
+          const metadata = json(file);
+          if (name === 'package.json' && !['ui-ux-pro-max', 'ui-ux-pro-max-cli'].includes(metadata.name)) continue;
+          if (metadata.version) return metadata.version;
+        } catch {}
+      }
     }
   }
   return 'unversioned';
 }
 function queryProvider(root, query, options = {}) {
   const mode = options.stack ? ['--stack', options.stack] : options.designSystem ? ['--design-system'] : ['--domain', options.domain || 'ux'];
-  const run = spawnSync(options.python || 'python3', ['-B', path.join(root, 'scripts/search.py'), query, ...mode, '--json'], { encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
+  const run = spawnSync(options.python || (process.platform === 'win32' ? 'python' : 'python3'), ['-B', path.join(root, 'scripts/search.py'), query, ...mode, '--json'], { encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
   ensure(run.status === 0, `UI/UX Pro Max query unavailable: ${run.error?.code || (run.stderr || '').trim().slice(0, 400)}`);
   return JSON.parse(run.stdout);
 }
@@ -85,6 +95,7 @@ function checkDesignProvider(options = {}) {
   return { ...(failure || {}), availability: failure?.availability || 'missing', searched: roots, attempts, diagnostics, reason: failure?.reason || (options.provider ? '指定的 UI/UX Pro Max 技能路径不存在，请核对 --provider' : '当前宿主未发现 UI/UX Pro Max；可安装，或传入宿主实际提供的 --provider 技能路径') };
 }
 function initPrototype(options, registry = templateRegistry) {
+  if (options.framework === 'vue-antdv-next' || options.template === 'admin-list') return require('./native-pilot-lib.cjs').createPrototype(options);
   const project = path.resolve(options.project || '.');
   const id = identifier(options.id);
   const selected = registry.resolve(options.template || registry.defaultId());
@@ -139,6 +150,7 @@ function initPrototype(options, registry = templateRegistry) {
 }
 function contentManifest(directory, registry = templateRegistry) {
   const metadata = json(contained(directory, 'prototype.json'));
+  if (metadata.schemaVersion === 2) return require('./native-pilot-lib.cjs').manifest(directory);
   const identity = { id: metadata.id, revision: metadata.revision, template: metadata.template, expertMode: metadata.expertMode, artifactKind: metadata.artifactKind };
   for (const field of registry.forInstance(metadata).runtime.identityFields) if (Object.hasOwn(metadata, field)) identity[field] = metadata[field];
   const paths = ['requirements-map.json', 'qa/design-advice.json', ...['app', 'mocks', 'design-system'].flatMap(folder => files(directory, folder))];
@@ -146,6 +158,7 @@ function contentManifest(directory, registry = templateRegistry) {
   return { schemaVersion: 1, revision: metadata.revision, identity, files: entries, digest: hash(JSON.stringify({ identity, files: entries })) };
 }
 function checkPrototype(directory, options = {}, registry = templateRegistry) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').inspect(directory, options);
   const errors = [];
   try {
     const metadata = json(contained(directory, 'prototype.json'));
@@ -164,7 +177,8 @@ function checkPrototype(directory, options = {}, registry = templateRegistry) {
       ensure(requirement.id && !ids.has(requirement.id), 'Requirement identifiers must be unique'); ids.add(requirement.id);
       ensure(requirement.pages?.length && requirement.scenarios?.length && requirement.roles?.length && requirement.actions?.length, `Incomplete business mapping: ${requirement.id}`);
     }
-    const runtimeFiles = selected.runtime.requiredFiles;
+    const runtimeFiles = [...selected.runtime.requiredFiles];
+    if (metadata.runtime?.offlineVersion === 1) runtimeFiles.push('app/offline.js');
     for (const file of ['app/index.html', 'app/tokens.css', 'app/config.json', 'design-system/MASTER.md', 'design-system/tokens.json', ...runtimeFiles]) contained(directory, file) && ensure(fs.existsSync(path.join(directory, file)), `Missing resource: ${file}`);
     const browserFiles = files(directory, 'app').filter(file => /\.(?:html|mjs|js|css)$/.test(file) && !selected.runtime.excludedBrowserPrefixes.some(prefix => file.startsWith(prefix)));
     for (const file of browserFiles) {
@@ -179,7 +193,7 @@ function checkPrototype(directory, options = {}, registry = templateRegistry) {
     const manifest = contentManifest(directory, registry);
     if (metadata.expertMode === 'professional' && options.acceptance) {
       const advice = json(contained(directory, 'qa/design-advice.json'));
-      ensure(advice.provider?.digest && advice.records.some(record => ['adopted', 'adjusted'].includes(record.decision) && record.query && record.resultIdentity && record.rationale && record.verification), 'Professional advice has not been verified and adopted');
+      ensure(advice.provider?.digest && advice.records.length && advice.records.every(record => ['adopted', 'adjusted', 'rejected', 'no-match'].includes(record.decision) && record.query && record.resultIdentity && record.rationale && record.verification), 'Professional advice has not been queried and reviewed');
     }
     if (options.acceptance) {
       const evidence = json(contained(directory, 'qa/browser.json'));
@@ -193,6 +207,7 @@ function checkPrototype(directory, options = {}, registry = templateRegistry) {
   } catch (error) { errors.push(error.message); return { status: 'failed', errors }; }
 }
 function freezeBaseline(directory, confirmation, registry = templateRegistry) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').confirmBaseline(directory, confirmation);
   const current = contentManifest(directory, registry);
   ensure(confirmation.revision === current.revision && confirmation.digest === current.digest, 'Human confirmation must match current changed content / 确认版本及内容必须一致');
   ensure(confirmation.reviewer?.trim() && confirmation.statement?.trim() && confirmation.source?.trim(), 'Explicit human confirmation / 人类确认 required');
@@ -213,12 +228,16 @@ function freezeBaseline(directory, confirmation, registry = templateRegistry) {
     const metadata = json(contained(directory, 'prototype.json'));
     metadata.review = { status: 'approved', revision: current.revision, digest: current.digest, source: confirmation.source };
     metadata.verification = { status: 'passed', digest: current.digest };
-    if (metadata.expertMode === 'professional') metadata.expert.status = 'used';
+    if (metadata.expertMode === 'professional') {
+      const advice = json(contained(directory, 'qa/design-advice.json'));
+      metadata.expert.status = advice.records.some(record => ['adopted', 'adjusted'].includes(record.decision)) ? 'used' : advice.records.every(record => record.decision === 'no-match') ? 'no-match' : 'reviewed';
+    }
     atomicJson(directory, 'prototype.json', metadata);
   } finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
   return current;
 }
 function compareBaseline(directory, registry = templateRegistry) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').compareBaseline(directory);
   if (!fs.existsSync(contained(directory, 'baseline.json'))) return { status: 'no-baseline', changes: [], protectedChanges: [] };
   const baseline = json(contained(directory, 'baseline.json'));
   const snapshot = contained(directory, baseline.directory);
@@ -238,7 +257,8 @@ function compareBaseline(directory, registry = templateRegistry) {
   if (selectionChanged) protectedChanges.push('template-or-expert-mode');
   return { status: changes.length || protectedChanges.length ? 'changed' : 'unchanged', baselineRevision: baseline.revision, currentRevision: current.revision, changes, protectedChanges };
 }
-function revisePrototype(directory, revision) {
+function revisePrototype(directory, revision, options = {}) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').revise(directory, { ...options, revision });
   identifier(revision);
   const metadata = json(contained(directory, 'prototype.json'));
   ensure(revision !== metadata.revision && !fs.existsSync(contained(directory, `baselines/${revision}`)), 'Use a new unused revision identifier');

package/skills/i3-ui-prototype/scripts/prototype-locations.cjs

@@ -0,0 +1,65 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+// Reviewed mirror of i3's installer target table; maintenance tests require byte equality.
+const registry = require('../assets/optional-skills/host-targets.json');
+const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
+function globalSkillsDir(agent, home, env) {
+  const config = agent.globalSkillsDir;
+  if (!config) return null;
+  let base = home;
+  if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+  if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
+  if (config.alternatives && !fs.existsSync(path.join(home, path.dirname(config.path)))) {
+    const alternative = config.alternatives.find(relative => fs.existsSync(path.join(home, path.dirname(relative))));
+    if (alternative) return path.join(home, alternative);
+  }
+  return path.resolve(base, config.path);
+}
+function installedContext() {
+  const file = path.resolve(__dirname, '../../../.i3-composer-agent.json');
+  if (!fs.existsSync(file)) return {};
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (data.name !== 'i3-composer-agent' || !Array.isArray(data.agents)) throw new Error('Invalid i3 installation context');
+  return { hosts: data.agents, scope: data.scope };
+}
+function resolveLocations(options = {}) {
+  const installed = installedContext();
+  if (!options.host && installed.hosts?.length > 1) throw new Error('Multiple installed hosts; specify --host');
+  const selected = options.host || installed.hosts?.[0] || 'codebuddy';
+  const host = aliases[selected] || selected, scope = options.scope || 'project';
+  const agent = registry.agents.find(item => item.id === host);
+  if (!agent) throw new Error(`Unknown host: ${host}`);
+  if (!['project', 'global'].includes(scope)) throw new Error('Use scope project or global');
+  const project = fs.realpathSync(path.resolve(options.project || '.'));
+  if (!fs.statSync(project).isDirectory()) throw new Error('Project must be a directory');
+  const home = path.resolve(options.home || os.homedir()), env = options.env || process.env;
+  const projectSkills = path.resolve(project, agent.projectSkillsDir), globalSkills = globalSkillsDir(agent, home, env);
+  if (scope === 'global' && !globalSkills) throw new Error(`${agent.label}: project installation only`);
+  const skillsDirectory = scope === 'project' ? projectSkills : globalSkills, base = path.dirname(skillsDirectory);
+  const projectBase = path.dirname(projectSkills), globalBase = globalSkills ? path.dirname(globalSkills) : null;
+  // Some hosts put skills directly in the workspace; tools still get a host directory.
+  const projectToolsBase = projectBase === project ? path.join(project, `.${host}`) : projectBase;
+  return { host, scope, project, home, skillsDirectory, base, projectSkills, globalSkills,
+    projectBase, globalBase, projectToolsBase,
+    toolsDirectory: path.join(scope === 'global' ? globalBase : projectToolsBase, 'tools/i3-prototype') };
+}
+function scopeBases(context) {
+  return context.scope === 'global' ? [[context.globalBase, 'global']] : [[context.projectBase, 'project'], ...(context.globalBase ? [[context.globalBase, 'global']] : [])];
+}
+function toolCandidates(context, options = {}) {
+  if (options.tool !== undefined) {
+    if (!path.isAbsolute(options.tool)) throw new Error('--tool requires an absolute antDv package directory');
+    return [{ root: path.resolve(options.tool), source: 'explicit-tool' }];
+  }
+  return [
+    ...toolBases(context).map(([base, scope]) => ({ root: path.join(base, 'tools/i3-prototype/antdv-cli/node_modules/@antdv-next/cli'), source: `${scope}-tool` })),
+    ...(context.scope === 'project' ? ['.prototype-tools/antdv-cli/node_modules/@antdv-next/cli', '.prototype-tools/node_modules/@antdv-next/cli']
+      .map(relative => ({ root: path.join(context.project, relative), source: 'legacy-project-tool' })) : []),
+  ].filter((item, index, all) => all.findIndex(other => other.root === item.root) === index);
+}
+function toolBases(context) {
+  return context.scope === 'global' ? [[context.globalBase, 'global']] : [[context.projectToolsBase, 'project'], ...(context.globalBase ? [[context.globalBase, 'global']] : [])];
+}
+module.exports = { registry, globalSkillsDir, resolveLocations, scopeBases, toolBases, toolCandidates };

package/skills/i3-ui-prototype/scripts/sync-template.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+const { prepareTemplate, syncTemplate, loadTemplate } = require('./template-contract.cjs');
+try {
+  const args = process.argv.slice(2);
+  const option = name => { const index = args.indexOf(name); return index < 0 ? undefined : args[index + 1]; };
+  let result;
+  if (args.includes('--prepare')) {
+    if (!option('--project')) throw new Error('--prepare requires --project <directory>');
+    const prepared = prepareTemplate({ project: option('--project'), id: option('--id') });
+    result = { status: 'passed', directory: prepared.directory, created: prepared.created, digest: prepared.index.digest };
+  } else {
+    const directory = args.find(arg => !arg.startsWith('--'));
+    if (!directory) throw new Error('Usage: sync-template.cjs <directory> [--check] | --prepare --project <directory> [--id <id>]');
+    const index = args.includes('--check') ? loadTemplate(directory).index : syncTemplate(directory);
+    result = { status: 'passed', templateId: index.templateId, digest: index.digest, bindings: index.bindings.length };
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }