agentic-flow-kit 2.0.0 → 2.1.0

package/src/commands/doctor.mjs

@@ -3,8 +3,9 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { readManifest } from '../install/manifest.mjs';
 import { doctorGit } from '../git/config.mjs';
-import { HOSTS } from '../hosts/registry.mjs';
+import { HOSTS, hostTargetRel } from '../hosts/registry.mjs';
 import { listFiles, TEMPLATES } from '../install/plan.mjs';
+import { ROLE_NAMES, readInjectedModels, readLocalModelRoles } from '../models/resolve.mjs';
 import { resolveTarget } from './install.mjs';
 
 const HOOK_FILES = ['pre-commit', 'commit-msg', 'post-commit', 'pre-merge-commit', 'pre-push'];
@@ -12,7 +13,8 @@ const HOOK_FILES = ['pre-commit', 'commit-msg', 'post-commit', 'pre-merge-commit
 export function doctorCommand({ args, t }) {
   const target = resolveTarget(args);
   const checks = [];
-  const add = (ok, name, detail, fix) => checks.push({ ok, name, detail, fix });
+  const add = (ok, name, detail, fix, extra = {}) => checks.push({ ok, name, detail, fix, ...extra });
+  const roleVal = (entry) => (typeof entry === 'string' ? entry : entry?.model || null);
 
   const manifest = readManifest(target);
   if (!manifest) {
@@ -47,9 +49,52 @@ export function doctorCommand({ args, t }) {
       continue;
     }
     for (const rel of listFiles(path.join(TEMPLATES, 'hosts', host))) {
-      const targetRel = host === 'claude' && rel === 'CLAUDE.md' ? 'CLAUDE.md' : `${h.dir}/${rel}`;
+      if (rel === 'settings.hardened.json') continue; // 替换源，不独立安装
+      const targetRel = hostTargetRel(host, rel);
       if (!fs.existsSync(path.join(target, targetRel))) add(false, `host ${host}: ${targetRel}`, t('doctor.fileMissing'));
     }
+    // 能力缺口：没有 hooks / modelField 的宿主，相关保证只能是 advisory。
+    if (!h.hooks) add(true, `guarantee ${host}`, t('doctor.guaranteeGap', { host, capability: 'hooks' }), '', { warn: true });
+    if (h.agents && !h.agents.modelField) add(true, `guarantee ${host}`, t('doctor.guaranteeGap', { host, capability: 'model injection' }), '', { warn: true });
+  }
+
+  // 安装档位与交付面：lean 允许没有 CI；standard/enterprise 应有可运行 CI。
+  const tier = manifest?.tier || 'standard';
+  add(true, 'tier', t('doctor.tier', { tier }));
+  if (tier !== 'lean') {
+    const ci = ['azure-pipelines.yml', '.github/workflows/ci.yml'].filter((rel) => fs.existsSync(path.join(target, rel)));
+    if (ci.length) add(true, 'ci', ci.join(', '));
+    else add(true, 'ci', t('doctor.ciMissing', { paths: 'azure-pipelines.yml / .github/workflows/ci.yml' }), '', { warn: true });
+  }
+  if (manifest?.hardened) add(true, 'hardened', t('doctor.hardenedHint'), '', { warn: true });
+
+  // 模型配置是用户本地状态：存在则校验，缺失不失败（旧安装保持 doctor 全过）。
+  const localModels = readLocalModelRoles(target);
+  if (localModels.error) {
+    add(false, 'model-roles.local', t('doctor.modelConfigInvalid'));
+  } else if (localModels.exists) {
+    add(true, 'model-roles.local', path.relative(target, localModels.file) || localModels.file);
+    const value = (entry) => (typeof entry === 'string' ? entry : entry?.model);
+    const code = value(localModels.roles.code);
+    const review = value(localModels.roles.review);
+    if (code && review && code === review) {
+      add(true, 'models heterogeneous', t('doctor.reviewSameAsCode'));
+    }
+    for (const role of ROLE_NAMES) {
+      if (value(localModels.roles[role]) == null) continue;
+      add(true, `model ${role}`, String(value(localModels.roles[role])));
+    }
+    // 模型漂移：本地配置 vs 已安装子代理的 model 字段。升级前必须先评测（model-upgrade 技能）。
+    const injected = readInjectedModels({ target, hosts: manifest?.hosts || [] });
+    for (const host of manifest?.hosts || []) {
+      for (const role of ROLE_NAMES) {
+        const local = localModels.hosts?.[host]?.[role] ?? roleVal(localModels.roles[role]);
+        const installed = injected[host]?.[role];
+        if (local != null && installed != null && String(local) !== String(installed)) {
+          add(true, `drift ${host}/${role}`, t('doctor.modelDrift', { host, role, installed, local }), '', { warn: true });
+        }
+      }
+    }
   }
 
   const nodeMajor = Number(process.versions.node.split('.')[0]);
@@ -58,7 +103,8 @@ export function doctorCommand({ args, t }) {
   let failed = 0;
   for (const c of checks) {
     if (c.ok) {
-      console.log(`✓ ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+      const mark = c.warn ? '!' : '✓';
+      console.log(`${mark} ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
     } else {
       failed += 1;
       console.log(`✗ ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);

package/src/commands/install.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { flag } from '../cli/args.mjs';
 import { buildPlan } from '../install/plan.mjs';
 import { applyPlan, summaryLine } from '../install/apply.mjs';
@@ -8,6 +9,9 @@ import { emptyManifest, readManifest, writeManifest } from '../install/manifest.
 import { buildVars } from '../render/tokens.mjs';
 import { HOST_NAMES, resolveHost } from '../hosts/registry.mjs';
 import { configureGit, isGitRepo } from '../git/config.mjs';
+import {
+  parseModelFlags, readInjectedModels, resolveModels, summarizeModels, writeLocalModelRoles,
+} from '../models/resolve.mjs';
 
 export function readKitVersion() {
   try {
@@ -52,30 +56,117 @@ export function resolveHosts(args, t, fallback = []) {
   return out;
 }
 
-export function detectStack(target) {
+// 根目录标记，先匹配者胜出。package.json 放在最后，避免吞掉 Cargo.toml / go.mod / pom.xml / tsconfig.json。
+// label 是菜单上的典型标记；match 返回实际命中的文件名。
+const STACK_MARKERS = [
+  {
+    stack: 'dotnet',
+    label: '.sln / .csproj',
+    match: (names) => names.find((n) => n.endsWith('.sln')) || names.find((n) => n.endsWith('.csproj')) || null,
+  },
+  { stack: 'rust', label: 'Cargo.toml', match: (names) => (names.includes('Cargo.toml') ? 'Cargo.toml' : null) },
+  { stack: 'go', label: 'go.mod', match: (names) => (names.includes('go.mod') ? 'go.mod' : null) },
+  {
+    stack: 'java',
+    label: 'pom.xml / build.gradle',
+    match: (names) => ['pom.xml', 'build.gradle', 'build.gradle.kts'].find((n) => names.includes(n)) || null,
+  },
+  { stack: 'typescript', label: 'tsconfig.json', match: (names) => (names.includes('tsconfig.json') ? 'tsconfig.json' : null) },
+  { stack: 'node', label: 'package.json', match: (names) => (names.includes('package.json') ? 'package.json' : null) },
+];
+
+export function stackMarkerLabel(stack) {
+  return STACK_MARKERS.find((marker) => marker.stack === stack)?.label || '';
+}
+
+export function matchStack(names) {
+  const list = Array.isArray(names) ? names : [];
+  for (const marker of STACK_MARKERS) {
+    const file = marker.match(list);
+    if (file) return { stack: marker.stack, file };
+  }
+  return { stack: 'empty', file: null };
+}
+
+export function detectStackDetail(target) {
   let top = [];
   try {
     top = fs.readdirSync(target);
   } catch {
-    return 'empty';
+    return { stack: 'empty', file: null };
   }
-  if (top.some((n) => n.endsWith('.sln') || n.endsWith('.csproj'))) return 'dotnet';
-  if (top.includes('package.json')) return 'node';
-  return 'empty';
+  return matchStack(top);
+}
+
+export function detectStack(target) {
+  return detectStackDetail(target).stack;
 }
 
+// 可选技术栈单一来源：TUI 向导栈菜单由它生成
+export const STACKS = ['dotnet', 'node', 'typescript', 'rust', 'go', 'java', 'empty'];
+
 export function resolveStack(args, target) {
   const stack = String(args.stack || args.profile || detectStack(target));
   const abs = fileURLToPath(new URL(`../../templates/profiles/${stack}/`, import.meta.url));
   return fs.existsSync(abs) ? stack : 'empty';
 }
 
-export function installCommand({ args, t, lang }) {
+export function installCommand({ args, t, lang, onLog }) {
   const hosts = resolveHosts(args, t);
-  return runInstall({ args, t, lang, hosts, commandLabel: 'install' });
+  return runInstall({ args, t, lang, hosts, commandLabel: 'install', onLog });
+}
+
+const ACTION_MARK = { create: '+', update: '~', skip: '-', conflict: '!', merge: '~' };
+
+export function formatInstallLog(action, msg) {
+  return `${ACTION_MARK[action] || ' '} ${msg}`;
+}
+
+// 「已是最新」在升级时会占绝大多数，进度条已能表达。冲突和其余跳过必须留下原文。
+export function installLogNotable(action, msg) {
+  if (action === 'conflict') return true;
+  if (action === 'skip') return !String(msg).includes('已是最新');
+  return false;
+}
+
+// CLI 缺省进度行：action 前缀 + 消息（TUI 经 onLog 接管渲染）
+function logLine(action, msg) {
+  console.log(formatInstallLog(action, msg));
+}
+
+function normalizeModelMode(value) {
+  const v = String(value || 'recommend').toLowerCase();
+  return ['recommend', 'detect', 'inherit'].includes(v) ? v : 'recommend';
+}
+
+// 派生工件（索引/引擎地图）从单源现场取数生成，不能静态随模板漂移。
+// 它们不进 manifest：属于生成区，升级时重新生成即可。
+function generateDerivedArtifacts(target) {
+  for (const script of ['gen-workflow-index.mjs', 'gen-engine-map.mjs']) {
+    const abs = path.join(target, '.agents', 'scripts', script);
+    if (!fs.existsSync(abs)) continue;
+    try {
+      spawnSync(process.execPath, [abs], {
+        cwd: target, stdio: 'ignore', windowsHide: true, timeout: 30000,
+      });
+    } catch { /* 派生工件失败不阻断安装；verify/dream 会报漂移 */ }
+  }
 }
 
-export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories, commandLabel, stackOverride }) {
+const TIERS = ['lean', 'standard', 'enterprise'];
+function normalizeTier(value, t) {
+  const v = String(value || 'standard').toLowerCase();
+  if (!TIERS.includes(v)) {
+    const err = new Error(t('error.badTier', { value: value || '' }));
+    err.code = 'BAD_TIER';
+    throw err;
+  }
+  return v;
+}
+
+// onLog 回调契约：(action, msg, done, total) —— action ∈ create/update/skip/conflict/merge，
+// done/total 为已完成/总文件数，供 TUI 渲染 spinner 进度；缺省走 CLI 前缀行。
+export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories, commandLabel, stackOverride, onLog = logLine }) {
   const target = resolveTarget(args);
   const dryRun = flag(args, 'dry-run');
   const force = flag(args, 'force');
@@ -84,8 +175,49 @@ export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories
   const previous = readManifest(target);
   const hostSet = [...new Set([...(previous?.hosts || []), ...hosts])];
   const trackHosts = flag(args, 'track-hosts');
+  // 档位：CLI > --hardened（=enterprise）> 既有 manifest > standard。
+  // 档位只影响交付面（CI / 加固），不削弱引擎门禁。
+  const tier = normalizeTier(
+    args.tier || (flag(args, 'hardened') ? 'enterprise' : null) || previous?.tier || 'standard',
+    t,
+  );
+  const hardened = flag(args, 'hardened') || tier === 'enterprise' || Boolean(previous?.hardened && !args.tier);
 
-  const plan = buildPlan({ target, hosts: planHosts, lang, stack, projectName, categories });
+  let modelFlags;
+  try {
+    modelFlags = parseModelFlags(args.models || []);
+  } catch (err) {
+    if (err.code !== 'BAD_MODEL') throw err;
+    const e = new Error(t('error.badModel', { value: err.value || '' }));
+    e.code = 'BAD_MODEL';
+    throw e;
+  }
+  const tuiModels = args.tuiModels || null;
+  const explicitModels = Object.keys(modelFlags.global).length > 0
+    || Object.keys(modelFlags.hosts).length > 0
+    || Boolean(tuiModels && Object.keys(tuiModels).length);
+  const modelMode = normalizeModelMode(args['model-mode']);
+  // 升级默认不重新探测：以本地 model-roles.local.json 为准，保证 agent 文件哈希稳定。
+  const shouldProbe = !previous || commandLabel === 'add-host' || explicitModels || modelMode === 'detect' || flag(args, 'probe-models');
+  const previousModels = commandLabel === 'upgrade'
+    ? readInjectedModels({ target, hosts: planHosts })
+    : {};
+  const models = flag(args, 'no-model-config') ? null : resolveModels({
+    hosts: planHosts,
+    target,
+    cli: modelFlags,
+    tui: tuiModels,
+    previous: previousModels,
+    mode: modelMode,
+    probe: shouldProbe,
+    allowCli: flag(args, 'probe-models'),
+  });
+
+  const plan = buildPlan({
+    target, hosts: planHosts, lang, stack, projectName, categories, models: models?.hosts, tier, hardened,
+  });
+  let done = 0;
+  const total = plan.entries.length;
   const vars = buildVars({
     target,
     projectName,
@@ -99,6 +231,13 @@ export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories
 
   console.log(t('install.start', { command: commandLabel, target }));
   console.log(t('install.plan', { hosts: hostSet.join(', '), stack, lang, count: plan.entries.length }));
+  console.log(t('install.tier', { tier, hardened: t(hardened ? 'tui.yes' : 'tui.no') }));
+  if (models) {
+    console.log(t('install.models', { models: summarizeModels(models) }));
+    for (const warning of models.warnings || []) {
+      console.log(t('install.modelWarning', { host: warning.host, role: warning.role }));
+    }
+  }
   if (dryRun) console.log(t('install.dryRun'));
 
   const manifest = previous || emptyManifest({
@@ -114,15 +253,21 @@ export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories
     manifest,
     dryRun,
     force,
-    log: (action, msg) => {
-      const prefix = { create: '+', update: '~', skip: '-', conflict: '!', merge: '~' }[action] || ' ';
-      console.log(`${prefix} ${msg}`);
-    },
+    log: (action, msg) => onLog(action, msg, (done += 1), total),
   });
 
   console.log(summaryLine(result.stats, t));
 
   if (!dryRun) {
+    generateDerivedArtifacts(target);
+    // 模型 ID 是机器本地状态：只写 gitignore 的 local 覆盖，不进 manifest。
+    if (models && (commandLabel !== 'upgrade' || explicitModels)) {
+      const saved = writeLocalModelRoles(target, models, {
+        overwrite: explicitModels || commandLabel === 'add-host',
+      });
+      if (saved.written) console.log(t('install.localModels', { path: path.join(target, '.agents/config/model-roles.local.json') }));
+    }
+
     const next = {
       ...manifest,
       version: KIT_VERSION,
@@ -130,6 +275,8 @@ export function runInstall({ args, t, lang, hosts, planHosts = hosts, categories
       language: lang,
       hosts: hostSet,
       stack,
+      tier,
+      hardened,
       files: result.files,
     };
     writeManifest(target, next);

package/src/hosts/registry.mjs

@@ -1,16 +1,124 @@
 // 宿主注册表：v1 十宿主。dir 为宿主点目录；rootMemory 为项目根记忆文件（仅 Claude 有）。
+// 能力字段描述安装器可以写什么、怎么写；探测不到的字段保持 null，不编造目录。
 // tracked 仅描述当前本仓的人库政策，不影响安装能力。
+
 export const HOSTS = {
-  trae: { dir: '.trae', label: 'Trae', tracked: true },
-  codebuddy: { dir: '.codebuddy', label: 'CodeBuddy', tracked: true },
-  claude: { dir: '.claude', label: 'Claude Code', tracked: false, rootMemory: 'CLAUDE.md' },
-  opencode: { dir: '.opencode', label: 'OpenCode', tracked: false },
-  qwen: { dir: '.qwen', label: 'Qwen Code', tracked: false },
-  pi: { dir: '.pi', label: 'PI', tracked: false },
-  cline: { dir: '.cline', label: 'Cline', tracked: false },
-  commandcode: { dir: '.commandcode', label: 'Command Code', tracked: false },
-  qoder: { dir: '.qoder', label: 'Qoder', tracked: false },
-  zcode: { dir: '.zcode', label: 'ZCode', tracked: false },
+  trae: {
+    dir: '.trae',
+    label: 'Trae',
+    tracked: true,
+    commands: { dir: 'commands', ext: '.md' },
+    agents: { dir: 'agents', ext: '.md', modelField: null, inheritValue: null },
+    skills: { mode: 'index' },
+    hooks: { file: 'hooks.json', format: 'json' },
+    modelProbe: { configs: [], env: [], cli: [] },
+  },
+  codebuddy: {
+    dir: '.codebuddy',
+    label: 'CodeBuddy',
+    tracked: true,
+    commands: { dir: 'commands', ext: '.md' },
+    agents: { dir: 'agents', ext: '.md', modelField: null, inheritValue: null },
+    // CodeBuddy 官方文档不可得；本地既有 .codebuddy/skills/<name>/SKILL.md 约定
+    skills: { mode: 'native', dir: 'skills', file: 'SKILL.md' },
+    hooks: { file: 'settings.json', format: 'json' },
+    modelProbe: { configs: ['~/.codebuddy/settings.json'], env: ['CODEBUDDY_MODEL'], cli: [] },
+  },
+  claude: {
+    dir: '.claude',
+    label: 'Claude Code',
+    tracked: false,
+    rootMemory: 'CLAUDE.md',
+    commands: { dir: 'commands', ext: '.md' },
+    agents: { dir: 'agents', ext: '.md', modelField: 'model', inheritValue: 'inherit' },
+    skills: { mode: 'native', dir: 'skills', file: 'SKILL.md' },
+    hooks: { file: 'settings.json', format: 'json' },
+    modelProbe: {
+      configs: ['~/.claude/settings.json'],
+      env: ['ANTHROPIC_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL'],
+      cli: [],
+    },
+  },
+  opencode: {
+    dir: '.opencode',
+    label: 'OpenCode',
+    tracked: false,
+    commands: { dir: 'commands', ext: '.md' },
+    // 省略 model = 继承父级；不写 inherit 值
+    agents: { dir: 'agents', ext: '.md', modelField: 'model', inheritValue: null },
+    skills: { mode: 'native', dir: 'skills', file: 'SKILL.md' },
+    hooks: null,
+    modelProbe: { configs: ['~/.config/opencode/opencode.json'], env: ['OPENCODE_MODEL'], cli: [] },
+  },
+  qwen: {
+    dir: '.qwen',
+    label: 'Qwen Code',
+    tracked: false,
+    commands: { dir: 'commands', ext: '.md' },
+    agents: { dir: 'agents', ext: '.md', modelField: 'model', inheritValue: 'inherit' },
+    // Qwen 原生发现 .agents/skills；不复制宿主技能副本
+    skills: { mode: 'shared' },
+    hooks: { file: 'settings.json', format: 'json' },
+    modelProbe: { configs: ['~/.qwen/settings.json'], env: ['QWEN_MODEL'], cli: [] },
+  },
+  pi: {
+    dir: '.pi',
+    label: 'PI',
+    tracked: false,
+    commands: null,
+    // PI 的 model 是网关限定 ID，没有 inherit 语义；解析不到时保留模板原值
+    agents: { dir: 'agents', ext: '.md', modelField: 'model', inheritValue: null },
+    skills: { mode: 'index' },
+    hooks: null,
+    modelProbe: { configs: ['~/.pi/settings.json'], env: ['PI_MODEL'], cli: [] },
+  },
+  cline: {
+    dir: '.cline',
+    label: 'Cline',
+    tracked: false,
+    // Cline 的 workflows 是 Markdown 工作流，用作技能索引入口
+    commands: { dir: 'workflows', ext: '.md' },
+    agents: { dir: 'agents', ext: '.yml', modelField: null, inheritValue: null },
+    skills: { mode: 'index' },
+    hooks: null,
+    modelProbe: { configs: [], env: [], cli: [] },
+  },
+  commandcode: {
+    dir: '.commandcode',
+    label: 'Command Code',
+    tracked: false,
+    commands: { dir: 'commands', ext: '.md' },
+    agents: { dir: 'agents', ext: '.md', modelField: 'model', inheritValue: 'inherit' },
+    // Command Code 原生发现 .agents/skills；不复制宿主技能副本
+    skills: { mode: 'shared' },
+    hooks: { file: 'settings.json', format: 'json' },
+    modelProbe: {
+      configs: ['~/.commandcode/settings.json'],
+      env: ['COMMANDCODE_MODEL'],
+      // cmd --list-models 是唯一已核实的非交互列表命令；Windows 上跳过 cmd（可能是系统 cmd.exe）
+      cli: [{ command: 'cmd', args: ['--list-models'] }, { command: 'commandcode', args: ['--list-models'] }],
+    },
+  },
+  qoder: {
+    dir: '.qoder',
+    label: 'Qoder',
+    tracked: false,
+    commands: { dir: 'commands', ext: '.md' },
+    agents: { dir: 'agents', ext: '.md', modelField: null, inheritValue: null },
+    skills: { mode: 'index' },
+    hooks: { file: 'settings.json', format: 'json' },
+    modelProbe: { configs: ['~/.qoder/settings.json'], env: [], cli: [] },
+  },
+  zcode: {
+    dir: '.zcode',
+    label: 'ZCode',
+    tracked: false,
+    commands: null,
+    agents: { dir: 'agents', ext: '.md', modelField: null, inheritValue: null },
+    skills: { mode: 'index' },
+    hooks: { file: 'config.json', format: 'json' },
+    modelProbe: { configs: ['~/.zcode/config.json'], env: [], cli: [] },
+  },
 };
 
 export const HOST_NAMES = Object.keys(HOSTS);
@@ -24,3 +132,39 @@ export function resolveHost(name) {
   }
   return { name: key, ...HOSTS[key] };
 }
+
+// 宿主模板相对路径 -> 目标相对路径。rootMemory 文件放项目根，其余放宿主点目录。
+export function hostTargetRel(name, rel) {
+  const h = HOSTS[name];
+  if (!h) {
+    const err = new Error(`unknown host: ${name}`);
+    err.code = 'UNKNOWN_HOST';
+    throw err;
+  }
+  const normalized = String(rel).replace(/\\/g, '/');
+  if (h.rootMemory && normalized === h.rootMemory) return h.rootMemory;
+  return `${h.dir}/${normalized}`;
+}
+
+// 子代理文件名 -> 引擎模型角色。未知角色按 judgment 处理（强推理默认更稳）。
+const MODEL_ROLE_BY_AGENT = {
+  implementer: 'code',
+  'independent-reviewer': 'review',
+  'pr-verifier': 'review',
+  'pr-adjudicator': 'judgment',
+  'pr-finder': 'judgment',
+  'ui-verifier': 'judgment',
+  'wiki-compiler': 'judgment',
+};
+
+export function modelRoleForAgent(rel) {
+  const base = String(rel).split('/').pop().replace(/\.[^.]+$/, '');
+  return MODEL_ROLE_BY_AGENT[base] || 'judgment';
+}
+
+export function isAgentTemplate(hostName, rel) {
+  const h = HOSTS[hostName];
+  if (!h?.agents) return false;
+  const normalized = String(rel).replace(/\\/g, '/');
+  return normalized.startsWith(`${h.agents.dir}/`) && normalized.endsWith(h.agents.ext);
+}

package/src/i18n.mjs

@@ -7,6 +7,9 @@ const KIT = path.resolve(HERE, '..');
 const LOCALES = path.join(KIT, 'locales');
 const FALLBACK = 'zh-CN';
 
+// 支持语言单一来源：cli/main.mjs 的 SUPPORTED_LANGS 与 TUI 向导语言菜单都由它派生
+export const LANGUAGES = ['zh-CN', 'en'];
+
 const cache = new Map();
 export function loadCatalog(lang) {
   if (cache.has(lang)) return cache.get(lang);

package/src/install/apply.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { render } from '../render/tokens.mjs';
+import { setField } from './frontmatter.mjs';
 import { sha256Text } from './manifest.mjs';
 
 const GITATTR_BEGIN = '# >>> agentic-flow-kit gitattributes';
@@ -37,9 +38,22 @@ function mergeBlock(existing, block, begin, end) {
 }
 
 export function readPlanEntry(entry, vars) {
-  if (isBinary(entry.srcAbs)) return null;
-  const raw = readText(entry.srcAbs);
-  return render(raw, vars);
+  let text;
+  if (typeof entry.getText === 'function') {
+    text = entry.getText(vars);
+  } else {
+    if (!entry.srcAbs || isBinary(entry.srcAbs)) return null;
+    text = render(readText(entry.srcAbs), vars);
+  }
+
+  // 模型注入必须在语言覆盖/渲染之后：manifest 记录的是最终文本哈希。
+  if (entry.modelField && entry.modelRole && typeof entry.modelValue === 'string') {
+    const value = entry.modelValue.trim();
+    if (value && (value !== 'inherit' || entry.modelInherit)) {
+      text = setField(text, entry.modelField, value);
+    }
+  }
+  return text;
 }
 
 export function applyPlan({ plan, vars, manifest, dryRun, force, log }) {

package/src/install/frontmatter.mjs

@@ -0,0 +1,84 @@
+// 无依赖 frontmatter 读写：只处理单行 key: value，够用于宿主 agent / skill 头部。
+// 不引入 YAML 解析器；description 等含空格/冒号的值在写入时用 JSON 双引号转义（YAML 合法）。
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+function eolOf(text) {
+  return String(text).includes('\r\n') ? '\r\n' : '\n';
+}
+
+function unquote(value) {
+  const v = String(value).trim();
+  if (v.startsWith('"') && v.endsWith('"')) {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v.slice(1, -1);
+    }
+  }
+  if (v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1).replace(/''/g, "'");
+  return v;
+}
+
+export function splitFrontmatter(text) {
+  const s = String(text ?? '');
+  const m = FRONTMATTER_RE.exec(s);
+  if (!m) return { has: false, frontmatter: '', body: s, eol: eolOf(s) };
+  const eol = eolOf(s);
+  return { has: true, frontmatter: m[1], body: s.slice(m[0].length), eol };
+}
+
+export function parseFrontmatter(text) {
+  const { frontmatter } = splitFrontmatter(text);
+  const out = {};
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith('#')) continue;
+    const i = t.indexOf(':');
+    if (i <= 0) continue;
+    const key = t.slice(0, i).trim();
+    if (!key) continue;
+    out[key] = unquote(t.slice(i + 1).trim());
+  }
+  return out;
+}
+
+export function getField(text, key) {
+  return parseFrontmatter(text)[key];
+}
+
+// 写/替换/删除单行字段；无 frontmatter 时在文首新建。value 为 null/undefined 表示删除。
+export function setField(text, key, value) {
+  const s = String(text ?? '');
+  const { has, frontmatter, body, eol } = splitFrontmatter(s);
+  const lines = has ? frontmatter.split(/\r?\n/) : [];
+  const idx = lines.findIndex((line) => new RegExp(`^\\s*${escapeRe(key)}\\s*:`).test(line));
+
+  if (value == null) {
+    if (!has || idx < 0) return s;
+    lines.splice(idx, 1);
+  } else {
+    const line = `${key}: ${yamlScalar(value)}`;
+    if (idx >= 0) lines[idx] = line;
+    else lines.push(line);
+  }
+
+  if (!has) return `---${eol}${lines.join(eol)}${eol}---${eol}${eol}${s}`;
+  return `---${eol}${lines.join(eol)}${eol}---${eol}${body}`;
+}
+
+export function yamlScalar(value) {
+  const s = String(value);
+  if (s === '') return '""';
+  // 安全裸值：字母数字 + 常见模型 ID 标点；排除 YAML 布尔/空值/数字
+  if (/^[A-Za-z0-9_./:@+~=-]+$/.test(s)
+    && !/^(true|false|null|yes|no|on|off|~)$/i.test(s)
+    && !/^-?\d+(\.\d+)?$/.test(s)) {
+    return s.includes('#') ? JSON.stringify(s) : s;
+  }
+  return JSON.stringify(s);
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}