agentic-flow-kit 1.8.7 → 2.1.0

package/src/install/apply.mjs

@@ -0,0 +1,138 @@
+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';
+const GITATTR_END = '# <<< agentic-flow-kit gitattributes';
+const GITIGNORE_BEGIN = '# >>> agentic-flow-kit ignores';
+const GITIGNORE_END = '# <<< agentic-flow-kit ignores';
+
+const BINARY_EXT = new Set(['.exe', '.png', '.jpg', '.jpeg', '.gif', '.ico', '.ttf', '.woff', '.woff2', '.zip', '.gz', '.pdf']);
+
+function isBinary(file) {
+  return BINARY_EXT.has(path.extname(file).toLowerCase());
+}
+
+function readText(abs) {
+  return fs.readFileSync(abs, 'utf8');
+}
+
+function eolOf(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function mergeBlock(existing, block, begin, end) {
+  const eol = eolOf(existing);
+  const normalized = block.replace(/\r?\n/g, eol);
+  const beginIdx = existing.indexOf(begin);
+  const endIdx = existing.indexOf(end);
+  if (beginIdx >= 0 && endIdx > beginIdx) {
+    const after = endIdx + end.length;
+    return existing.slice(0, beginIdx) + normalized + existing.slice(after);
+  }
+  const sep = existing.length && !existing.endsWith(eol) ? eol : '';
+  const gap = existing.length ? eol : '';
+  return `${existing}${sep}${gap}${normalized}${eol}`;
+}
+
+export function readPlanEntry(entry, 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 }) {
+  const stats = { create: 0, update: 0, skip: 0, conflict: 0, merge: 0 };
+  const nextFiles = { ...(manifest.files || {}) };
+  const writes = [];
+
+  for (const entry of plan.entries) {
+    const abs = path.join(plan.target, entry.targetRel);
+    const exists = fs.existsSync(abs);
+    const currentHash = exists ? sha256Text(readText(abs)) : null;
+    const managedHash = manifest.files ? manifest.files[entry.targetRel] : null;
+
+    if (entry.kind === 'merge-gitattributes' || entry.kind === 'merge-gitignore') {
+      const text = readPlanEntry(entry, vars) || '';
+      const begin = entry.kind === 'merge-gitattributes' ? GITATTR_BEGIN : GITIGNORE_BEGIN;
+      const end = entry.kind === 'merge-gitattributes' ? GITATTR_END : GITIGNORE_END;
+      const block = `${begin}\n${text.trimEnd()}\n${end}\n`;
+      const existing = exists ? readText(abs) : '';
+      const merged = exists ? mergeBlock(existing, block, begin, end) : block;
+      if (existing === merged) {
+        stats.skip += 1;
+        log('skip', `${entry.targetRel}（已是最新）`);
+        continue;
+      }
+      writes.push({ abs, text: merged, targetRel: entry.targetRel });
+      stats.merge += 1;
+      log(exists ? 'update' : 'create', `${entry.targetRel}（合并块）`);
+      continue;
+    }
+
+    const text = readPlanEntry(entry, vars);
+    if (text == null) {
+      stats.skip += 1;
+      log('skip', `${entry.targetRel}（二进制模板跳过）`);
+      continue;
+    }
+
+    if (!exists) {
+      writes.push({ abs, text, targetRel: entry.targetRel });
+      stats.create += 1;
+      log('create', entry.targetRel);
+      continue;
+    }
+
+    if (force || (managedHash && managedHash === currentHash)) {
+      writes.push({ abs, text, targetRel: entry.targetRel });
+      stats.update += 1;
+      log('update', entry.targetRel);
+      continue;
+    }
+
+    if (managedHash && managedHash !== currentHash) {
+      stats.conflict += 1;
+      log('conflict', `${entry.targetRel}（已安装后被修改，跳过；--force 可覆盖）`);
+      continue;
+    }
+
+    stats.skip += 1;
+    log('skip', `${entry.targetRel}（已存在且非本工具安装，跳过；--force 可覆盖）`);
+  }
+
+  if (!dryRun) {
+    for (const w of writes) {
+      fs.mkdirSync(path.dirname(w.abs), { recursive: true });
+      fs.writeFileSync(w.abs, w.text, 'utf8');
+      nextFiles[w.targetRel] = sha256Text(w.text);
+    }
+  }
+
+  return { stats, files: nextFiles };
+}
+
+export function summaryLine(stats, t) {
+  return t('install.summary', {
+    create: stats.create,
+    update: stats.update,
+    merge: stats.merge,
+    skip: stats.skip,
+    conflict: stats.conflict,
+  });
+}

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, '\\$&');
+}

package/src/install/manifest.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const MANIFEST_REL = '.agents/install-manifest.json';
+
+export function readManifest(target) {
+  const file = path.join(target, MANIFEST_REL);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeManifest(target, manifest) {
+  const file = path.join(target, MANIFEST_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+
+export function sha256Text(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+export function sha256File(abs) {
+  return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+}
+
+export function emptyManifest({ kitVersion, language, hosts, stack }) {
+  return {
+    kit: 'agentic-flow-kit',
+    version: kitVersion,
+    installedAt: new Date().toISOString(),
+    language,
+    hosts,
+    stack,
+    files: {},
+  };
+}

package/src/install/plan.mjs

@@ -0,0 +1,241 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 [];
+  const out = [];
+  const walk = (abs, rel) => {
+    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()) {
+        if (RUNTIME_DIRS.has(childRel)) continue;
+        walk(childAbs, childRel);
+      } else if (ent.isFile() && !RUNTIME_FILES.has(childRel)) {
+        out.push(childRel);
+      }
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+function localeOverride(lang, targetRel) {
+  const p = path.join(LOCALES, lang, 'overrides', 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，宿主只写自己的点目录。
+// 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', extra = {}) => {
+    const entry = { srcAbs, targetRel: targetRel.replace(/\\/g, '/'), category, priority, kind, ...extra };
+    plan.push(entry);
+    return entry;
+  };
+
+  // 1) 引擎核心
+  for (const rel of listFiles(path.join(TEMPLATES, 'engine'))) {
+    push(path.join(TEMPLATES, 'engine', rel), rel, 'engine', 10);
+  }
+
+  // 2) 项目 profile（栈相关配置与 AGENTS.md）
+  for (const rel of listFiles(path.join(TEMPLATES, 'profiles', stack))) {
+    push(path.join(TEMPLATES, 'profiles', stack, rel), rel, 'profile', 20);
+  }
+
+  // 3) 宿主适配层
+  for (const host of hosts) {
+    const h = HOSTS[host];
+    if (!h) continue;
+    for (const rel of listFiles(path.join(TEMPLATES, 'hosts', host))) {
+      // 加固配置是 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;
+      }
+    }
+  }
+
+  // 4) 数据资产脚手架（空目录由 scaffold 中的 .gitkeep 保证）
+  for (const rel of listFiles(path.join(TEMPLATES, 'scaffold'))) {
+    push(path.join(TEMPLATES, 'scaffold', rel), rel, 'scaffold', 10);
+  }
+
+  // 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) 语言包覆盖（按目标路径镜像）
+  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);
+
+  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;
+}