agentic-flow-kit 2.0.0 → 2.1.0

package/src/install/plan.mjs

@@ -1,12 +1,28 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { HOSTS } from '../hosts/registry.mjs';
+import { HOSTS, hostTargetRel, isAgentTemplate, modelRoleForAgent } from '../hosts/registry.mjs';
+import { makeT } from '../i18n.mjs';
+import { parseFrontmatter, yamlScalar } from './frontmatter.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const KIT_ROOT = path.resolve(HERE, '..', '..');
 export const TEMPLATES = path.join(KIT_ROOT, 'templates');
 export const LOCALES = path.join(KIT_ROOT, 'locales');
+// host-meta 存放生成技能指针/索引用的模板，不参与 templates/hosts/<host> 的静态枚举
+export const HOST_META = path.join(TEMPLATES, 'host-meta');
+
+// 模板目录可能被本机运行过脚本（评测凭证、缓存、本地模型角色）。这些是运行态，
+// 既不该进包，也不该被安装到目标项目——尤其 evals/results.jsonl 是行为评测凭证，
+// 若随模板出厂，会让每个新装项目“凭空”获得一张当前内容的合格凭证。
+const RUNTIME_DIRS = new Set(['.agents/cache', '.agents/tmp', '.agents/tools']);
+const RUNTIME_FILES = new Set([
+  '.agents/verifications.jsonl',
+  '.agents/judgments.jsonl',
+  '.agents/evals/results.jsonl',
+  '.agents/config/model-roles.local.json',
+  '.agents/notes/runtime-env.local.md',
+]);
 
 export function listFiles(dir) {
   if (!fs.existsSync(dir)) return [];
@@ -15,8 +31,12 @@ export function listFiles(dir) {
     for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
       const childAbs = path.join(abs, ent.name);
       const childRel = rel ? `${rel}/${ent.name}` : ent.name;
-      if (ent.isDirectory()) walk(childAbs, childRel);
-      else if (ent.isFile()) out.push(childRel);
+      if (ent.isDirectory()) {
+        if (RUNTIME_DIRS.has(childRel)) continue;
+        walk(childAbs, childRel);
+      } else if (ent.isFile() && !RUNTIME_FILES.has(childRel)) {
+        out.push(childRel);
+      }
     }
   };
   walk(dir, '');
@@ -28,11 +48,135 @@ function localeOverride(lang, targetRel) {
   return fs.existsSync(p) ? p : null;
 }
 
+function applyLocaleOverrides(lang, entries) {
+  for (const entry of entries) {
+    const override = localeOverride(lang, entry.targetRel);
+    if (!override) continue;
+    entry.srcAbs = override;
+    delete entry.getText;
+  }
+  return entries;
+}
+
+function dedupe(entries) {
+  const byTarget = new Map();
+  for (const entry of entries.sort((a, b) => a.priority - b.priority)) byTarget.set(entry.targetRel, entry);
+  return [...byTarget.values()];
+}
+
+function has(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+// 单次替换：overrides 优先，其次全局 vars；不递归扫描已插入的内容。
+function fillTemplate(template, vars, overrides = {}) {
+  return String(template).replace(/\{\{(\w+)\}\}/g, (m, key) => {
+    if (has(overrides, key)) return String(overrides[key]);
+    if (has(vars, key)) return String(vars[key]);
+    return m;
+  });
+}
+
+function readTemplate(abs, fallback) {
+  return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : fallback;
+}
+
+function readSkillMeta(entry) {
+  let name = path.basename(path.dirname(entry.targetRel));
+  let description = name;
+  try {
+    const fm = parseFrontmatter(fs.readFileSync(entry.srcAbs, 'utf8'));
+    if (fm.name) name = fm.name;
+    if (fm.description) description = fm.description;
+  } catch {
+    /* 源缺失时保留目录名 */
+  }
+  return { name, description, targetRel: entry.targetRel };
+}
+
+function buildSkillsList(skills, t) {
+  if (!skills.length) return `- ${t('host.skillsIndexEmpty')}`;
+  return skills
+    .map((s) => t('host.skillsIndexLine', { name: s.name, description: s.description, path: s.targetRel }))
+    .join('\n');
+}
+
+function addGeneratedSkillSurfaces({ plan, hosts, skillEntries, t }) {
+  const skills = skillEntries.map(readSkillMeta).sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const host of hosts) {
+    const h = HOSTS[host];
+    if (!h?.skills) continue;
+
+    if (h.skills.mode === 'native') {
+      const template = readTemplate(path.join(HOST_META, host, 'skill-pointer.md'), [
+        '---',
+        'name: {{skillName}}',
+        'description: {{skillDescription}}',
+        '---',
+        '{{pointer}}',
+        '',
+      ].join('\n'));
+      for (const skill of skills) {
+        const overrides = {
+          skillName: skill.name,
+          skillDescription: yamlScalar(skill.description),
+          skillPath: skill.targetRel,
+          pointer: t('host.skillPointer', { path: skill.targetRel }),
+        };
+        plan.push({
+          srcAbs: path.join(HOST_META, host, 'skill-pointer.md'),
+          targetRel: `${h.dir}/${h.skills.dir}/${skill.name}/${h.skills.file}`,
+          category: 'host',
+          // 生成器读取语言覆盖后的技能 frontmatter，优先于静态宿主技能回退件。
+          priority: 35,
+          kind: 'generated',
+          getText: (vars) => fillTemplate(template, vars, overrides),
+        });
+      }
+      continue;
+    }
+
+    // shared / index：生成一个可发现入口，不复制技能正文
+    const hasCommands = Boolean(h.commands);
+    const targetRel = hasCommands
+      ? `${h.dir}/${h.commands.dir}/wf-skills.md`
+      : `${h.dir}/SKILLS.md`;
+    const templateAbs = hasCommands
+      ? path.join(HOST_META, host, 'skill-index.md')
+      : path.join(HOST_META, 'SKILLS.md');
+    const template = readTemplate(templateAbs, [
+      '---',
+      'description: {{indexDescription}}',
+      '---',
+      '{{skillsList}}',
+      '',
+    ].join('\n'));
+    const overrides = {
+      indexDescription: t('host.skillsIndexDescription'),
+      title: t('host.skillsIndexTitle'),
+      skillsList: buildSkillsList(skills, t),
+    };
+    plan.push({
+      srcAbs: templateAbs,
+      targetRel,
+      category: 'host',
+      priority: 25,
+      kind: 'generated',
+      getText: (vars) => fillTemplate(template, vars, overrides),
+    });
+  }
+}
+
 // 构建安装计划。targetRel 使用 / 分隔；profile 覆盖 engine，宿主只写自己的点目录。
-export function buildPlan({ target, hosts, lang, stack, projectName, categories }) {
+// models: { [host]: { code?, judgment?, review? } }，用于注入宿主子代理 model 字段。
+export function buildPlan({ target, hosts, lang, stack, projectName, categories, models = null, tier = 'standard', hardened = false }) {
+  const t = makeT(lang);
   const plan = [];
-  const push = (srcAbs, targetRel, category, priority = 10, kind = 'file') => {
-    plan.push({ srcAbs, targetRel: targetRel.replace(/\\/g, '/'), category, priority, kind });
+  const push = (srcAbs, targetRel, category, priority = 10, kind = 'file', extra = {}) => {
+    const entry = { srcAbs, targetRel: targetRel.replace(/\\/g, '/'), category, priority, kind, ...extra };
+    plan.push(entry);
+    return entry;
   };
 
   // 1) 引擎核心
@@ -50,8 +194,18 @@ export function buildPlan({ target, hosts, lang, stack, projectName, categories
     const h = HOSTS[host];
     if (!h) continue;
     for (const rel of listFiles(path.join(TEMPLATES, 'hosts', host))) {
-      const targetRel = host === 'claude' && rel === 'CLAUDE.md' ? 'CLAUDE.md' : `${h.dir}/${rel}`;
-      push(path.join(TEMPLATES, 'hosts', host, rel), targetRel, 'host', 30);
+      // 加固配置是 settings.json 的替换源，不作为独立文件安装。
+      if (rel === 'settings.hardened.json') continue;
+      const srcAbs = (hardened && host === 'claude' && rel === 'settings.json')
+        ? path.join(TEMPLATES, 'hosts', host, 'settings.hardened.json')
+        : path.join(TEMPLATES, 'hosts', host, rel);
+      const entry = push(srcAbs, hostTargetRel(host, rel), 'host', 30);
+      if (h.agents?.modelField && isAgentTemplate(host, rel)) {
+        entry.modelRole = modelRoleForAgent(rel);
+        entry.modelField = h.agents.modelField;
+        entry.modelInherit = h.agents.inheritValue;
+        entry.modelValue = models?.[host]?.[entry.modelRole] ?? null;
+      }
     }
   }
 
@@ -62,21 +216,25 @@ export function buildPlan({ target, hosts, lang, stack, projectName, categories
 
   // 5) git 门禁与合并策略
   for (const rel of listFiles(path.join(TEMPLATES, 'git'))) {
+    // lean 档不生成 CI：小项目先跑本地钩子；standard/enterprise 才落 CI。
+    if (tier === 'lean' && (rel === 'azure-pipelines.yml' || rel.startsWith('.github/'))) continue;
     if (rel === '.gitattributes') push(path.join(TEMPLATES, 'git', rel), '.gitattributes', 'git', 40, 'merge-gitattributes');
     else if (rel === '.gitignore.engine') push(path.join(TEMPLATES, 'git', rel), '.gitignore', 'git', 40, 'merge-gitignore');
     else push(path.join(TEMPLATES, 'git', rel), rel, 'git', 40);
   }
 
   // 6) 语言包覆盖（按目标路径镜像）
-  for (const entry of plan) {
-    const override = localeOverride(lang, entry.targetRel);
-    if (override) entry.srcAbs = override;
-  }
+  applyLocaleOverrides(lang, plan);
+  let deduped = dedupe(plan);
+
+  // 7) 从覆盖后的 .agents/skills/<name>/SKILL.md 生成宿主技能面
+  const skillEntries = deduped.filter((e) => /^\.agents\/skills\/[^/]+\/SKILL\.md$/.test(e.targetRel));
+  addGeneratedSkillSurfaces({ plan, hosts, skillEntries, t });
+
+  // 生成项同样允许按目标路径覆盖，然后二次去重（静态宿主文件优先级更高）
+  applyLocaleOverrides(lang, plan);
+  deduped = dedupe(plan);
 
-  // 同目标去重：高优先级覆盖低优先级
-  const byTarget = new Map();
-  for (const entry of plan.sort((a, b) => a.priority - b.priority)) byTarget.set(entry.targetRel, entry);
-  let deduped = [...byTarget.values()];
   if (categories && categories.length) deduped = deduped.filter((e) => categories.includes(e.category));
 
   return { target, hosts, lang, stack, projectName, entries: deduped };

package/src/models/known.mjs

@@ -0,0 +1,13 @@
+// 仅收录已核实的推荐别名。没有可靠来源的宿主不合成模型列表；探测不到就 inherit/手填。
+export const KNOWN_MODELS = {
+  // Claude Code 子代理 model 接受 alias / full name；alias 随主模型档位走
+  claude: [
+    { id: 'sonnet', roles: ['code'], note: 'balanced' },
+    { id: 'haiku', roles: ['code'], note: 'fast/cheap' },
+    { id: 'opus', roles: ['judgment', 'review'], note: 'strong reasoning' },
+  ],
+};
+
+export function knownFor(host, role) {
+  return (KNOWN_MODELS[host] || []).filter((m) => m.roles.includes(role)).map((m) => m.id);
+}

package/src/models/probe.mjs

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { HOSTS } from '../hosts/registry.mjs';
+
+// 只读探测：宿主配置 / 环境变量为默认来源；CLI 列表命令必须显式允许。
+// 任何失败都静默降级，安装不能被探测拖死或卡在认证提示上。
+export function probeModels({
+  host,
+  target = process.cwd(),
+  home = os.homedir(),
+  env = process.env,
+  allowCli = false,
+  exec = spawnSync,
+} = {}) {
+  const h = HOSTS[host];
+  if (!h) return [];
+
+  const found = [];
+  const add = (id, source) => {
+    const s = String(id ?? '').trim();
+    if (!s || s.length > 200) return;
+    // 模型 ID 常见字符：provider/model、:tag、#variant、@version、+build
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:/#@+~=-]*$/.test(s)) return;
+    found.push({ id: s, source });
+  };
+
+  for (const raw of h.modelProbe?.configs || []) {
+    const json = readJsonLoose(resolveConfigPath(raw, target, home));
+    if (json) collectModels(json, add);
+  }
+  for (const key of h.modelProbe?.env || []) {
+    const value = env[key];
+    if (value) add(value, 'env');
+  }
+
+  if (allowCli) {
+    for (const cli of h.modelProbe?.cli || []) {
+      if (!cli?.command) continue;
+      // Windows 的 `cmd` 往往是系统 cmd.exe，误执行会变成 shell 探测
+      if (process.platform === 'win32' && /^cmd(\.exe)?$/i.test(cli.command)) continue;
+      const r = exec(cli.command, cli.args || [], {
+        encoding: 'utf8',
+        timeout: 1500,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      if (!r || r.error || r.status !== 0 || !r.stdout) continue;
+      for (const id of parseCliModels(r.stdout)) add(id, 'cli');
+    }
+  }
+
+  const seen = new Set();
+  return found.filter((m) => {
+    if (seen.has(m.id)) return false;
+    seen.add(m.id);
+    return true;
+  }).slice(0, 20);
+}
+
+function resolveConfigPath(raw, target, home) {
+  const s = String(raw);
+  if (s === '~') return home;
+  if (s.startsWith('~/') || s.startsWith('~\\')) return path.join(home, s.slice(2));
+  return path.isAbsolute(s) ? s : path.resolve(target, s);
+}
+
+// 容忍 JSONC（注释/尾逗号）；解析失败返回 null，不抛。
+export function readJsonLoose(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(stripJsonComments(text));
+  } catch {
+    return null;
+  }
+}
+
+export function stripJsonComments(text) {
+  let out = '';
+  let inString = false;
+  let quote = '';
+  let escape = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (escape) escape = false;
+      else if (ch === '\\') escape = true;
+      else if (ch === quote) inString = false;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      quote = ch;
+      out += ch;
+      continue;
+    }
+    if (ch === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1;
+      out += '\n';
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i += 1;
+      continue;
+    }
+    out += ch;
+  }
+  return out.replace(/,\s*([}\]])/g, '$1');
+}
+
+function collectModels(value, add, depth = 0) {
+  if (depth > 7 || value == null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === 'string') add(item, 'config');
+      else collectModels(item, add, depth + 1);
+    }
+    return;
+  }
+  if (typeof value !== 'object') return;
+  for (const [key, child] of Object.entries(value)) {
+    if (/^(model|modelId|defaultModel|fastModel|subagentModel|primaryModel)$/i.test(key)) {
+      if (typeof child === 'string') add(child, 'config');
+      else collectModels(child, add, depth + 1);
+      continue;
+    }
+    if (/^(models|providers|provider)$/i.test(key)) {
+      collectModels(child, add, depth + 1);
+      continue;
+    }
+    // 只向下钻一层常见容器，避免把任意 settings 里的普通字符串当模型
+    if (child && typeof child === 'object' && /^(opencode|qwen|claude|pi|commandcode|qoder|zcode)$/i.test(key)) {
+      collectModels(child, add, depth + 1);
+    }
+  }
+}
+
+export function parseCliModels(stdout) {
+  const clean = String(stdout).replace(/\x1b\[[0-9;]*m/g, '');
+  const out = [];
+  for (const line of clean.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    // 只过滤整行表头；`provider/model-a` 这类以 provider 开头的合法 ID 必须保留。
+    if (!trimmed
+      || /^(?:available\s+models?|models?|usage|name|provider)\s*:?$/i.test(trimmed)
+      || /^-+$/.test(trimmed)) continue;
+    // 取行内第一个像模型 ID 的 token；表格分隔线/标题会被过滤
+    const token = trimmed.split(/\s+/).find((t) => /^[A-Za-z0-9][A-Za-z0-9._:/#@+~=-]*$/.test(t)
+      && (/[/:.]/.test(t) || t.length > 3));
+    if (token) out.push(token.replace(/[,;]+$/, ''));
+  }
+  return out;
+}