@givolt/i3-composer-agent 2.2.3 → 2.3.1

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

@@ -0,0 +1,259 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const templateRegistry = require('./template-adapters.cjs').createTemplateRegistry();
+const { discoverProviderCandidates } = require('./design-provider-discovery.cjs');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const json = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+function ensure(condition, message) { if (!condition) throw new Error(message); }
+function identifier(value) { ensure(typeof value === 'string' && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value), 'Invalid identifier / 无效标识'); return value; }
+function contained(root, relative) {
+  ensure(typeof relative === 'string' && relative && !path.isAbsolute(relative) && !relative.split(/[\\/]/).some(p => p === '..'), 'Path must remain inside prototype');
+  root = fs.existsSync(root) ? fs.realpathSync(root) : path.resolve(root);
+  const file = path.resolve(root, relative);
+  ensure(file.startsWith(root + path.sep), 'Path escapes prototype');
+  let current = root;
+  for (const part of path.relative(root, file).split(path.sep)) {
+    current = path.join(current, part);
+    ensure(!fs.existsSync(current) || !fs.lstatSync(current).isSymbolicLink(), 'Refusing symlink / 符号链接');
+  }
+  return file;
+}
+function files(root, prefix = '') {
+  return fs.readdirSync(path.join(root, prefix), { withFileTypes: true }).flatMap(entry => {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    ensure(!entry.isSymbolicLink(), `Refusing symlink: ${relative}`);
+    return entry.isDirectory() ? files(root, relative) : entry.isFile() ? [relative] : [];
+  }).sort();
+}
+function write(root, relative, value) {
+  const file = contained(root, relative);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, typeof value === 'string' ? value : JSON.stringify(value, null, 2) + '\n');
+}
+function atomicJson(root, relative, value) {
+  const file = contained(root, relative);
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  try { fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { flag: 'wx' }); fs.renameSync(temp, file); }
+  finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
+}
+function listTemplates(options = {}, registry = templateRegistry) {
+  return registry.list(options);
+}
+function tokensCss(tokens) {
+  const entries = Object.entries({ ...tokens.semantic, ...tokens.component });
+  ensure(entries.length && entries.every(([key, value]) => /^[a-z][a-z0-9-]*$/.test(key) && typeof value === 'string' && !/[;{}<>\n\r]/.test(value)), 'Invalid design token values');
+  return ':root {\n' + entries.map(([key, value]) => `  --${key}: ${value};`).join('\n') + '\n}\n';
+}
+function providerVersion(root) {
+  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 {} }
+    }
+  }
+  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 });
+  ensure(run.status === 0, `UI/UX Pro Max query unavailable: ${run.error?.code || (run.stderr || '').trim().slice(0, 400)}`);
+  return JSON.parse(run.stdout);
+}
+function checkDesignProvider(options = {}) {
+  const discovery = discoverProviderCandidates(options);
+  const attempts = [];
+  const roots = discovery.candidates.map(candidate => path.resolve(candidate.root));
+  const diagnostics = discovery.diagnostics;
+  if (discovery.contextRequired) return { availability: 'needs-context', searched: roots, attempts, diagnostics, reason: '请指定当前宿主 --host，或传入宿主实际提供的 --provider 技能路径；尚不能判断是否已安装' };
+  for (const candidate of discovery.candidates) {
+    const root = path.resolve(candidate.root);
+    if (!fs.existsSync(root)) { attempts.push({ root, source: candidate.source, availability: 'missing', reason: '技能路径不存在' }); continue; }
+    const required = ['SKILL.md', 'scripts/search.py', 'scripts/core.py', 'scripts/design_system.py', ...['ux-guidelines', 'styles', 'colors', 'typography', 'products', 'landing', 'ui-reasoning'].map(name => `data/${name}.csv`)];
+    const missing = required.filter(file => !fs.existsSync(path.join(root, file)));
+    if (missing.length) { attempts.push({ root, source: candidate.source, availability: 'unusable', missing, reason: '技能资源不完整' }); continue; }
+    try {
+      const probe = queryProvider(root, 'error summary validation', { python: options.python, domain: 'ux' });
+      ensure(probe.domain === 'ux' && probe.results?.length, 'No verified UX probe result');
+      attempts.push({ root, source: candidate.source, availability: 'available' });
+      return { availability: 'available', root, source: candidate.source, version: providerVersion(root), digest: hash(required.map(file => hash(fs.readFileSync(path.join(root, file)))).join('\n')), searched: roots, attempts, diagnostics };
+    } catch (error) { attempts.push({ root, source: candidate.source, availability: 'unusable', reason: error.message }); }
+  }
+  const failure = attempts.find(attempt => attempt.availability === 'unusable') || ['ambiguous', 'disabled', 'discovery-error'].map(status => diagnostics.find(item => item.availability === status)).find(Boolean);
+  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) {
+  const project = path.resolve(options.project || '.');
+  const id = identifier(options.id);
+  const selected = registry.resolve(options.template || registry.defaultId());
+  const template = selected.entry;
+  const expertMode = options.expertMode || 'professional';
+  ensure(['professional', 'template'].includes(expertMode), 'Mode must be professional or template');
+  const provider = expertMode === 'professional' ? checkDesignProvider({ ...options, project }) : null;
+  if (provider && provider.availability !== 'available') {
+    let action = { id: 'locate', label: '提供当前宿主或实际技能路径' };
+    if (provider.availability === 'missing' && !options.provider) action = { id: 'install', label: '安装并继续' };
+    if (provider.availability === 'unusable') action = { id: 'repair', label: '修复已安装技能并重试' };
+    if (provider.availability === 'disabled') action = { id: 'enable', label: '启用已安装插件并重试' };
+    return { status: 'needs-design-provider', provider, message: `专业增强模式需要可用的 UI/UX Pro Max。${provider.reason}。也可明确选择模板模式继续。`, choices: [action, { id: 'template', label: '模板模式继续' }, { id: 'prepare', label: '先整理需求和模板选择' }] };
+  }
+  ensure(fs.existsSync(project) && fs.statSync(project).isDirectory(), 'Project directory does not exist');
+  const directory = contained(project, `prototypes/${id}`);
+  ensure(!fs.existsSync(directory), 'Prototype already exists / 原型已存在，使用 revise 或另选标识');
+  const lockPath = contained(project, '.i3-ui-prototypes.lock');
+  const lock = fs.openSync(lockPath, 'wx');
+  try {
+  const registryPath = contained(project, '.i3-ui-prototypes.json');
+  const registry = fs.existsSync(registryPath) ? json(registryPath) : { schemaVersion: 1, prototypes: [] };
+  ensure(registry.schemaVersion === 1 && Array.isArray(registry.prototypes), 'Invalid project prototype registry');
+  ensure(!registry.prototypes.some(entry => entry.id === id), 'Prototype registry already contains identifier');
+  const preset = selected.preset;
+  const sourceDigest = template.digest;
+  fs.mkdirSync(path.dirname(directory), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(path.dirname(directory), '.i3-prototype-'));
+  let created = false;
+  try {
+    const metadata = { schemaVersion: 1, id, revision: 'r001', artifactKind: 'html-review', title: options.title || selected.context.manifest.defaultTitle, template: { id: template.id, version: template.version, digest: sourceDigest, adapter: selected.adapterId }, expertMode, expert: { status: provider ? 'pending' : 'skipped', provider }, verification: { status: 'not-run' }, review: { status: 'pending-review' } };
+    const initialized = selected.adapter.initialize(staging, { id, title: metadata.title, purpose: options.purpose }, selected.context);
+    Object.assign(metadata, initialized.metadata);
+    selected.adapter.validateRuntime(metadata);
+    write(staging, 'prototype.json', metadata);
+    write(staging, 'app/config.json', { id, title: metadata.title, templateName: template.name, layout: preset.layout });
+    const tokens = { primitive: preset.primitive, semantic: preset.semantic, component: preset.component };
+    write(staging, 'design-system/tokens.json', tokens);
+    write(staging, 'app/tokens.css', tokensCss(tokens));
+    write(staging, 'qa/design-advice.json', { schemaVersion: 1, mode: expertMode, provider, records: [] });
+    write(staging, 'HANDOFF.md', `# ${metadata.title} 原型交接\n\n模板：${template.name} ${template.version}。模式：${expertMode === 'template' ? '模板模式' : '专业增强模式（专业建议待适配）'}。\n\n运行：在本目录执行 \`node app/serve.cjs\`，按终端显示地址打开。业务数据是本地演示。\n\n${initialized.handoff || ''}读取 requirements-map.json、design-system/MASTER.md 与 qa/REPORT.md。当前为 pending-review；用户明确确认同一版本后才可冻结基线。HTML 交互参考进入框架工程时需要组件和接口映射。\n`);
+    write(staging, 'qa/REPORT.md', '# 原型检查\n\n尚未执行浏览器验收。验证及用户评审分别记录。\n');
+    ensure(!fs.existsSync(directory), 'Prototype already exists');
+    fs.renameSync(staging, directory);
+    created = true;
+    registry.prototypes.push({ id, directory: `prototypes/${id}`, appliesTo: [] });
+    atomicJson(project, '.i3-ui-prototypes.json', registry);
+  } catch (error) { if (created) fs.rmSync(directory, { recursive: true, force: true }); throw error; }
+  finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
+  return { status: 'created', directory, template: template.id, expertMode };
+  } finally { fs.closeSync(lock); fs.unlinkSync(lockPath); }
+}
+function contentManifest(directory, registry = templateRegistry) {
+  const metadata = json(contained(directory, 'prototype.json'));
+  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))];
+  const entries = Object.fromEntries(paths.sort().map(file => [file, hash(fs.readFileSync(contained(directory, file)))]));
+  return { schemaVersion: 1, revision: metadata.revision, identity, files: entries, digest: hash(JSON.stringify({ identity, files: entries })) };
+}
+function checkPrototype(directory, options = {}, registry = templateRegistry) {
+  const errors = [];
+  try {
+    const metadata = json(contained(directory, 'prototype.json'));
+    ensure(metadata.schemaVersion === 1 && metadata.artifactKind === 'html-review', 'Invalid prototype contract');
+    ensure(metadata.template?.id && metadata.template.version && /^[a-f0-9]{64}$/.test(metadata.template.digest), 'A computed template version and SHA-256 digest are required');
+    identifier(metadata.id); identifier(metadata.revision);
+    ensure(['professional', 'template'].includes(metadata.expertMode), 'Invalid expert mode');
+    const selected = registry.forInstance(metadata);
+    selected.adapter.validateRuntime(metadata, options);
+    const tokens = json(contained(directory, 'design-system/tokens.json'));
+    ensure(fs.readFileSync(contained(directory, 'app/tokens.css'), 'utf8') === tokensCss(tokens), 'Design tokens and actual stylesheet are inconsistent');
+    const mapping = json(contained(directory, 'requirements-map.json'));
+    ensure(mapping.schemaVersion === 1 && mapping.requirements?.length, 'Requirements mapping is required');
+    const ids = new Set();
+    for (const requirement of mapping.requirements) {
+      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;
+    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) {
+      const content = fs.readFileSync(path.join(directory, file), 'utf8');
+      for (const match of content.matchAll(/(?:\s|<)(?:src|href)=["']([^"'#]+)["']|(?:import[^;]*?from\s*|import\s*)["']([^"']+)["']/g)) {
+        const reference = match[1] || match[2];
+        if (/^(?:https?:|data:|mailto:|node:)/.test(reference)) continue;
+        const relative = path.relative(directory, path.resolve(path.dirname(path.join(directory, file)), reference));
+        ensure(fs.existsSync(contained(directory, relative)), `Missing local reference: ${file} → ${reference}`);
+      }
+    }
+    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');
+    }
+    if (options.acceptance) {
+      const evidence = json(contained(directory, 'qa/browser.json'));
+      ensure(evidence.status === 'passed' && evidence.digest === manifest.digest && evidence.revision === manifest.revision, 'Current matching browser evidence / 浏览器证据 required');
+      ensure(evidence.source && evidence.journeys?.length && evidence.journeys.every(item => item.status === 'passed') && Array.isArray(evidence.consoleErrors) && !evidence.consoleErrors.length && evidence.screenshots?.length && evidence.viewports?.length >= 2, 'Browser acceptance incomplete');
+      for (const file of evidence.screenshots) ensure(fs.statSync(contained(directory, file)).size > 0, 'Missing screenshot evidence');
+      const required = new Set(mapping.requirements.flatMap(requirement => requirement.scenarios));
+      for (const scenario of required) ensure(evidence.journeys.some(item => item.id === scenario && item.status === 'passed'), `Missing browser scenario: ${scenario}`);
+    }
+    return { status: 'passed', revision: manifest.revision, digest: manifest.digest, acceptance: Boolean(options.acceptance) };
+  } catch (error) { errors.push(error.message); return { status: 'failed', errors }; }
+}
+function freezeBaseline(directory, confirmation, registry = templateRegistry) {
+  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');
+  const target = contained(directory, `baselines/${identifier(current.revision)}`);
+  ensure(!fs.existsSync(target), 'Baseline already exists / 基线已存在');
+  const result = checkPrototype(directory, { acceptance: true }, registry);
+  ensure(result.status === 'passed', result.errors?.join('; '));
+  const staging = contained(directory, `baselines/.${current.revision}-${crypto.randomUUID()}`);
+  try {
+    fs.mkdirSync(staging, { recursive: true });
+    for (const file of Object.keys(current.files)) { const destination = contained(staging, file); fs.mkdirSync(path.dirname(destination), { recursive: true }); fs.copyFileSync(contained(directory, file), destination); }
+    write(staging, 'manifest.json', current);
+    write(staging, 'review.json', { ...confirmation, approvedAt: new Date().toISOString() });
+    ensure(Object.entries(current.files).every(([file, digest]) => hash(fs.readFileSync(contained(staging, file))) === digest) && contentManifest(directory, registry).digest === current.digest, 'Candidate changed while freezing snapshot');
+    const reviewDigest = hash(fs.readFileSync(contained(staging, 'review.json')));
+    fs.renameSync(staging, target);
+    atomicJson(directory, 'baseline.json', { schemaVersion: 1, revision: current.revision, digest: current.digest, reviewDigest, directory: `baselines/${current.revision}` });
+    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';
+    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 (!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);
+  const approved = json(contained(snapshot, 'manifest.json'));
+  const reviewFile = contained(snapshot, 'review.json');
+  if (baseline.revision !== approved.revision || !fs.existsSync(reviewFile) || hash(fs.readFileSync(reviewFile)) !== baseline.reviewDigest) return { status: 'corrupt-baseline', changes: [], protectedChanges: [] };
+  if (approved.digest !== baseline.digest || hash(JSON.stringify({ identity: approved.identity, files: approved.files })) !== approved.digest || Object.entries(approved.files).some(([file, digest]) => !fs.existsSync(contained(snapshot, file)) || hash(fs.readFileSync(contained(snapshot, file))) !== digest)) return { status: 'corrupt-baseline', changes: [], protectedChanges: [] };
+  const current = contentManifest(directory, registry);
+  const changes = [...new Set([...Object.keys(approved.files), ...Object.keys(current.files)])].filter(file => approved.files[file] !== current.files[file]);
+  const selectionChanged = JSON.stringify(approved.identity.template) !== JSON.stringify(current.identity.template) || approved.identity.expertMode !== current.identity.expertMode;
+  const runtime = registry.forInstance(current.identity).runtime;
+  // Shared design contracts remain protected for every runtime; adapters add
+  // their own runtime resources and identity fields rather than replacing it.
+  const shared = ['app/tokens.css', 'app/index.html', 'requirements-map.json'];
+  const protectedChanges = changes.filter(file => file.startsWith('design-system/') || shared.includes(file) || runtime.protectedFiles.includes(file) || runtime.protectedDirectories.some(prefix => file.startsWith(prefix)));
+  if (runtime.identityFields.some(field => JSON.stringify(approved.identity[field]) !== JSON.stringify(current.identity[field]))) protectedChanges.push('runtime-contract');
+  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) {
+  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');
+  metadata.revision = revision; metadata.review = { status: 'pending-review' }; metadata.verification = { status: 'not-run' };
+  atomicJson(directory, 'prototype.json', metadata);
+  return { status: 'revised', revision };
+}
+function parseArgs(argv) {
+  const options = {}, positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) { positional.push(argv[i]); continue; }
+    const key = argv[i].slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    if (['acceptance', 'enforceBaseline', 'designSystem'].includes(key)) options[key] = true;
+    else { ensure(argv[i + 1] && !argv[i + 1].startsWith('--'), `Missing option value: ${argv[i]}`); options[key] = argv[++i]; }
+  }
+  return { options, positional };
+}
+module.exports = { initPrototype, listTemplates, checkDesignProvider, queryProvider, contentManifest, checkPrototype, freezeBaseline, compareBaseline, revisePrototype, parseArgs };

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

@@ -0,0 +1,89 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const assert = require('node:assert/strict');
+const builtins = Object.freeze({
+  'easel-html': require('./adapters/easel-html.cjs'),
+  'legacy-html': require('./adapters/legacy-html.cjs'),
+});
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const identifier = value => typeof value === 'string' && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+function safePath(root, relative) {
+  assert.ok(typeof relative === 'string' && relative && !path.isAbsolute(relative) && !path.win32.isAbsolute(relative) && !relative.includes('\\') && relative.split('/').every(part => part && part !== '.' && part !== '..'), 'Unsafe template path / 模板路径无效');
+  let file = root;
+  for (const part of relative.split('/')) {
+    file = path.join(file, part);
+    assert.ok(!fs.lstatSync(file).isSymbolicLink(), 'Refusing template symlink / 模板符号链接');
+  }
+  return file;
+}
+function inventory(root, relative) {
+  const file = safePath(root, relative), stat = fs.statSync(file);
+  if (stat.isDirectory()) return fs.readdirSync(file).sort().flatMap(name => inventory(root, `${relative}/${name}`));
+  assert.ok(stat.isFile(), 'Template resource must be a regular file');
+  return [relative];
+}
+function createTemplateRegistry({ assetRoot = path.resolve(__dirname, '../assets/templates'), adapters = builtins } = {}) {
+  const root = fs.realpathSync(assetRoot);
+  const read = file => JSON.parse(fs.readFileSync(safePath(root, file), 'utf8'));
+  function catalog() {
+    const value = read('catalog.json');
+    assert.equal(value.schemaVersion, 2, 'Invalid template catalog');
+    assert.ok(Array.isArray(value.templates) && Array.isArray(value.legacyTemplates), 'Invalid template entries');
+    const ids = new Set();
+    for (const entry of [...value.templates, ...value.legacyTemplates]) {
+      assert.ok(identifier(entry.id) && !ids.has(entry.id), 'Duplicate or invalid template identifier'); ids.add(entry.id);
+      assert.ok(['available', 'planned', 'legacy'].includes(entry.availability), 'Invalid template availability');
+      if (entry.preview) {
+        const preview = entry.preview.split(/[?#]/)[0];
+        safePath(root, preview);
+      }
+    }
+    assert.ok(identifier(value.defaultTemplate) && value.templates.some(entry => entry.id === value.defaultTemplate && entry.availability === 'available'), 'Invalid default template');
+    return value;
+  }
+  function resolve(id) {
+    assert.ok(identifier(id), 'Invalid template identifier');
+    const value = catalog(), entry = [...value.templates, ...value.legacyTemplates].find(item => item.id === id);
+    assert.ok(entry, 'Unknown template');
+    assert.notEqual(entry.availability, 'planned', 'Template is planned / 该类型尚未建设，不能生成替代演示');
+    assert.ok(typeof entry.version === 'string' && entry.version, 'Template version is required');
+    assert.ok(typeof entry.manifest === 'string' && entry.manifest.startsWith(`${id}/`), 'Template manifest must belong to its template');
+    const manifest = read(entry.manifest);
+    assert.equal(manifest.schemaVersion, 1, 'Invalid template manifest');
+    assert.ok(identifier(manifest.adapter) && Object.hasOwn(adapters, manifest.adapter), 'Unknown template adapter; no common-runtime fallback');
+    const adapter = adapters[manifest.adapter], runtime = adapter.runtime;
+    assert.ok(typeof adapter.version === 'string' && adapter.version && ['fingerprintInputs', 'initialize', 'validateRuntime'].every(method => typeof adapter[method] === 'function'), 'Invalid template adapter contract');
+    assert.ok(runtime && identifier(runtime.kind), 'Invalid runtime contract');
+    for (const key of ['requiredFiles', 'identityFields', 'excludedBrowserPrefixes', 'protectedFiles', 'protectedDirectories']) assert.ok(Array.isArray(runtime[key]) && runtime[key].every(item => typeof item === 'string'), `Invalid runtime contract: ${key}`);
+    assert.ok(manifest.resources && typeof manifest.resources === 'object' && !Array.isArray(manifest.resources), 'Template resources are required');
+    assert.ok(typeof manifest.defaultTitle === 'string' && manifest.defaultTitle, 'Template default title is required');
+    safePath(root, manifest.preset);
+    for (const resource of Object.values(manifest.resources)) inventory(root, resource);
+    const context = { entry, manifest, resources: manifest.resources, resource(name) {
+      assert.ok(Object.hasOwn(manifest.resources, name), `Missing declared template resource: ${name}`);
+      return safePath(root, manifest.resources[name]);
+    } };
+    const inputs = adapter.fingerprintInputs(context);
+    assert.ok(Array.isArray(inputs) && inputs.length, 'Adapter fingerprint inputs are required');
+    const paths = [...new Set([entry.manifest, manifest.preset, ...inputs].flatMap(file => inventory(root, file)))].sort();
+    const implementations = [__filename, ...(adapter.implementationFiles || [])].map(file => ({ file: path.basename(file), digest: hash(fs.readFileSync(file)) }));
+    const digest = hash(JSON.stringify({ catalogEntry: entry, adapter: manifest.adapter, version: adapter.version, runtime, implementations, files: paths.map(file => [file, hash(fs.readFileSync(safePath(root, file)))]) }));
+    return { entry: { ...entry, digest }, adapterId: manifest.adapter, adapter, runtime, context, preset: read(manifest.preset) };
+  }
+  return {
+    defaultId: () => catalog().defaultTemplate,
+    resolve,
+    list(options = {}) {
+      const value = catalog(), entries = options.legacy ? value.legacyTemplates : options.includeLegacy ? [...value.templates, ...value.legacyTemplates] : value.templates;
+      return entries.map(entry => entry.availability === 'planned' ? { ...entry, digest: null } : resolve(entry.id).entry);
+    },
+    forInstance(metadata) {
+      const template = resolve(metadata.template?.id);
+      assert.ok(!metadata.template.adapter || metadata.template.adapter === template.adapterId, 'Template adapter does not match registered runtime');
+      return template;
+    },
+  };
+}
+module.exports = { createTemplateRegistry };

package/skills/i3-using-agent-skills/SKILL.md

@@ -30,6 +30,7 @@ Task arrives
     │
     ├── Don't know what you want yet? ──────→ i3-interview-me
     ├── Have a rough concept, need variants? → i3-idea-refine
+    ├── UI prototype/template/review baseline? → i3-ui-prototype
     ├── New project/feature/change? ──→ i3-spec-driven-development
     ├── No quality bar written down? ──→ i3-constraint-driven-development
     ├── Have a spec, need tasks? ──────→ i3-planning-and-task-breakdown
@@ -54,6 +55,10 @@ Task arrives
     └── Deploying/launching? ─────────→ i3-shipping-and-launch
 ```
 
+## Prototype Routing
+
+For template selection, interactive prototype generation, prototype review or approved prototype baseline maintenance, invoke the `i3-ui-prototype` skill. Explicit prototype requests can start from a minimal business brief; retain unconfirmed rules as open questions. Production UI component implementation remains with `i3-frontend-ui-engineering`; read an applicable prototype baseline first when one exists. Use either the host native router or this meta-skill as the primary discovery mechanism.
+
 ## Core Operating Behaviors
 
 These behaviors apply at all times, across all skills. They are non-negotiable.