minimal-agent 0.12.0 → 0.14.0

package/skills/workflow-creator/scripts/list-resources.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * skills/workflow-creator/scripts/list-resources.mjs
+ *   —— 现场列出「这台机器上现在有什么可用」
+ *
+ * 用法：
+ *   node skills/workflow-creator/scripts/list-resources.mjs          全部
+ *   node skills/workflow-creator/scripts/list-resources.mjs --tools  只列工具
+ *   node skills/workflow-creator/scripts/list-resources.mjs --skills 只列 skills
+ *   node skills/workflow-creator/scripts/list-resources.mjs --json   机器可读
+ *
+ * ⚠️ **为什么要有这个脚本，而不是在 SKILL.md 里写一张表**
+ *
+ * 写死的清单必然过时。工具会增删（现在 40+ 个）、skills 是运行时扫目录的
+ * （现在近 30 个，用户还能在自己项目里放）、插件也可能装卸。SKILL.md 里那张
+ * 手抄表一旦落后，agent 照着它写就会：
+ *   · 用不上已经存在的能力 → **重复造轮子**（自己写 PPT 生成逻辑而不是用 pptx skill）
+ *   · 写出不存在的工具名 → 被 `allowedTools` 静默过滤，agent 少了能力还不报错
+ *
+ * 所以：**清单靠现场查，判断靠 SKILL.md**。这个脚本负责前者。
+ *
+ * 纯 JS、零依赖、只读 —— 和 scriptGuard.mjs 一样要能被 `node` 直接 spawn。
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, '..', '..', '..');
+
+const argv = process.argv.slice(2);
+const wantJson = argv.includes('--json');
+const only = argv.find((a) => ['--tools', '--skills', '--plugins'].includes(a));
+
+// ---------------------------------------------------------------------------
+//  工具：**直接问内核要 ALL_TOOLS 的真实 name 字段**
+//
+//  ⚠️ 不要从变量名推断。第一版就是那么干的（`lspTool` → `Lsp`、
+//  `webFetchTool` → `Webfetch`、`genImageTool` → `GenImage`），全都是**错的**
+//  真名分别是 `LSP` / `WebFetch` / `GenerateImage`。
+//  一个「防止写错工具名」的脚本自己给出错的名字，比没有这个脚本更糟 ——
+//  作者会照着它写，然后被 allowedTools 静默过滤掉。
+//
+//  所以走 bun 拿真值。本项目本来就是 bun 跑的（package.json 的 scripts 全是），
+//  拿不到时**明说降级**，绝不假装准确。
+// ---------------------------------------------------------------------------
+function listTools() {
+  // ⚠️ probe 里**一个空格、一个 `>` 都不能有**：Windows 上要靠 shell 才找得到 bun，
+  // 而 shell 会按空格拆参数、把 `>` 当重定向 —— 两者都会让命令当场被截断。
+  // 所以用 `JSON.stringify(值, 属性白名单)` 这个冷门重载拿字段，
+  // 而不是 `.map(t => t.name)`（既有箭头又有空格）。
+  const probe =
+    "import{ALL_TOOLS}from'./src/tools/index.ts';" +
+    "console.log(JSON.stringify(ALL_TOOLS,['name']))";
+  const r = spawnSync('bun', ['-e', probe], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  if (r.status === 0 && r.stdout) {
+    const line = r.stdout.trim().split('\n').pop();
+    try {
+      const arr = JSON.parse(line);
+      const names = arr.map((o) => o?.name).filter((n) => typeof n === 'string');
+      if (names.length > 0) return { names, exact: true };
+    } catch {
+      /* 落到下面的降级 */
+    }
+  }
+  return { names: [], exact: false, why: (r.stderr || '').trim().slice(0, 200) };
+}
+
+/** 工具太多，按用途归组 —— agent 要的是「做这件事用哪个」，不是字母序清单。 */
+const TOOL_GROUPS = [
+  ['读写文件', ['Read', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Trash']],
+  ['查找', ['Glob', 'Grep', 'LSP']],
+  ['执行命令', ['Bash', 'PowerShell', 'TerminalCapture']],
+  ['联网', ['WebSearch', 'WebFetch', 'WebBrowser', 'Download']],
+  ['生成媒体', ['GenerateImage', 'GenerateSpeech', 'Snip']],
+  ['桌面操控', ['ComputerUse']],
+  ['问人 / 交付', ['AskUserQuestion', 'PresentResult']],
+  ['子任务 / 技能', ['Agent', 'Skill', 'Advisor']],
+  ['长期记忆', ['RecallMemory', 'RememberMemory', 'SearchConversations']],
+  ['worktree', ['EnterWorktree', 'ExitWorktree']],
+];
+
+// ---------------------------------------------------------------------------
+//  skills：扫 skills/*/SKILL.md 的 frontmatter
+// ---------------------------------------------------------------------------
+function listSkills() {
+  const dir = join(ROOT, 'skills');
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    const f = join(dir, e.name, 'SKILL.md');
+    if (!existsSync(f)) continue;
+    const head = readFileSync(f, 'utf8').slice(0, 1200);
+    const desc = head.match(/^description:\s*([\s\S]*?)(?=\n[a-z_-]+:|\n---)/m);
+    out.push({
+      name: e.name,
+      description: (desc?.[1] ?? '').replace(/\s+/g, ' ').trim().slice(0, 100),
+    });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ---------------------------------------------------------------------------
+//  插件：带 plugin.json 的目录 + 它们暴露的东西
+// ---------------------------------------------------------------------------
+function listPlugins() {
+  const dir = join(ROOT, 'plugins');
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    const manifest = join(dir, e.name, '.claude-plugin', 'plugin.json');
+    if (!existsSync(manifest)) continue;
+    let meta = {};
+    try {
+      meta = JSON.parse(readFileSync(manifest, 'utf8'));
+    } catch {
+      /* 坏 manifest 不阻断 */
+    }
+    const cmdDir = join(dir, e.name, 'commands');
+    const commands = existsSync(cmdDir)
+      ? readdirSync(cmdDir)
+          .filter((f) => f.endsWith('.md'))
+          .map((f) => `/${f.replace(/\.md$/, '')}`)
+      : [];
+    out.push({
+      name: meta.name ?? e.name,
+      description: String(meta.description ?? '').slice(0, 120),
+      commands,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+//  输出
+// ---------------------------------------------------------------------------
+const toolInfo = listTools();
+const tools = toolInfo.names;
+const skills = listSkills();
+const plugins = listPlugins();
+
+if (wantJson) {
+  console.log(
+    JSON.stringify(
+      { tools, toolsExact: toolInfo.exact, skills, plugins },
+      null,
+      2,
+    ),
+  );
+  process.exit(0);
+}
+
+const show = (k) => !only || only === `--${k}`;
+
+if (show('tools')) {
+  if (!toolInfo.exact) {
+    // 宁可不报，也不给一份可能是错的工具名清单 —— 作者会照着它写，
+    // 然后被 allowedTools 静默过滤掉，比没有清单更糟。
+    console.log('\n⚠️  拿不到工具清单 —— 需要 bun 可用（本项目本来就用 bun 跑）。');
+    if (toolInfo.why) console.log(`   ${toolInfo.why}`);
+    console.log('   工具名请直接看 src/tools/index.ts::ALL_TOOLS。\n');
+  } else {
+    console.log(
+      `\n═══ 工具（${tools.length} 个）—— 用于 tool() / allowedTools ═══\n`,
+    );
+    const seen = new Set();
+    for (const [group, names] of TOOL_GROUPS) {
+      const have = names.filter((n) => tools.includes(n));
+      if (have.length === 0) continue;
+      for (const n of have) seen.add(n);
+      console.log(`  ${group.padEnd(14)} ${have.join('  ')}`);
+    }
+    const rest = tools.filter((t) => !seen.has(t));
+    if (rest.length > 0) console.log(`  ${'其它'.padEnd(14)} ${rest.join('  ')}`);
+    console.log(
+      '\n  ⚠️ allowedTools 里写错的名字会被**静默过滤**（引擎会发 warning，但别依赖它）。',
+    );
+  }
+}
+
+if (show('skills')) {
+  console.log(`\n═══ Skills（${skills.length} 个）—— 用 skill(名字, 任务描述) 调 ═══\n`);
+  for (const s of skills) {
+    console.log(`  ${s.name.padEnd(22)} ${s.description}`);
+  }
+  console.log(
+    '\n  提示：现有 Skill 的能力、输入与产出契约匹配当前阶段时优先复用；不匹配时不要为迁就 Skill 扭曲流程。',
+  );
+}
+
+if (show('plugins')) {
+  console.log(`\n═══ 插件（${plugins.length} 个）═══\n`);
+  for (const p of plugins) {
+    console.log(`  ${p.name.padEnd(24)} ${p.commands.join(' ') || '（无命令）'}`);
+    if (p.description) console.log(`  ${' '.repeat(24)} ${p.description}`);
+  }
+}
+
+console.log('');

package/skills/workflow-creator/scripts/scaffold.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * 生成最小动态工作流目录。默认只创建真正必需的 workflow.mjs 和 README.md；
+ * scripts/prompts/assets 只有显式请求才创建，避免空目录和失效模板。
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function findRepoRoot() {
+  const marker = join('plugins', 'workflow-runner', 'src', 'scriptGuard.mjs');
+  for (const start of [HERE, process.cwd()]) {
+    let dir = resolve(start);
+    for (let i = 0; i < 8; i++) {
+      if (existsSync(join(dir, marker))) return dir;
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+  }
+  return null;
+}
+
+function optionValue(prefix) {
+  const inline = process.argv.find((arg) => arg.startsWith(`${prefix}=`));
+  if (inline) return inline.slice(prefix.length + 1);
+  const index = process.argv.indexOf(prefix);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+const name = process.argv[2];
+if (!name || name.startsWith('-')) {
+  console.error(
+    '用法：scaffold.mjs <名字> [--with=scripts,prompts,assets] [--workflows-root=<目录>]',
+  );
+  process.exit(1);
+}
+if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+  console.error(`名字只能含字母数字 . _ -，收到「${name}」。`);
+  process.exit(1);
+}
+
+const root = findRepoRoot();
+if (!root) {
+  console.error('找不到 minimal-agent 仓库根，请在仓库内运行。');
+  process.exit(1);
+}
+
+const requested = new Set(
+  String(optionValue('--with') ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean),
+);
+const allowed = new Set(['scripts', 'prompts', 'assets']);
+const unknown = [...requested].filter((item) => !allowed.has(item));
+if (unknown.length) {
+  console.error(
+    `--with 不支持：${unknown.join(', ')}；可选 scripts,prompts,assets`,
+  );
+  process.exit(1);
+}
+
+const configuredRoot = optionValue('--workflows-root');
+const workflowsRoot = configuredRoot
+  ? isAbsolute(configuredRoot)
+    ? configuredRoot
+    : resolve(configuredRoot)
+  : join(root, 'workflows');
+const dir = join(workflowsRoot, name);
+if (existsSync(dir)) {
+  console.error(`${dir} 已存在，不覆盖。`);
+  process.exit(1);
+}
+
+await mkdir(dir, { recursive: true });
+for (const subdir of requested)
+  await mkdir(join(dir, subdir), { recursive: true });
+
+const workflow = `export const meta = {
+  apiVersion: 2,
+  description: 'TODO：一句话说明这个工作流交付什么成果',
+  inputs: [{ name: 'request', required: true, greedy: true }],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+  // 先定义阶段契约：输入、输出、执行方式、成功证据、失败与恢复语义。
+  // 纯计算直接 import；确定性副作用用 wf.fs/wf.exec/wf.tools；开放判断用 wf.model。
+  const result = await wf.model.generate(
+    \`根据以下请求给出结果：\\n\\n\${wf.input.values.request}\`,
+    { label: '生成结果' },
+  )
+
+  wf.output.message(result)
+  return { result }
+}
+`;
+
+await writeFile(join(dir, 'workflow.mjs'), workflow, 'utf8');
+await writeFile(
+  join(dir, 'README.md'),
+  `# ${name}
+
+## 意图与边界
+TODO：解决什么问题；什么情况不应使用这个工作流。
+
+## 阶段契约
+TODO：逐阶段写明输入、输出、执行方式、成功证据、失败与恢复语义。
+
+## 输入与产物
+TODO：输入含义、产物路径与格式、最终验收方式。
+
+## 前置条件与已知限制
+TODO：仅记录真实存在的依赖和限制。
+`,
+  'utf8',
+);
+
+if (requested.has('scripts')) {
+  await writeFile(
+    join(dir, 'scripts', 'README.md'),
+    `确定性辅助脚本放在这里并使用 .mjs。工作流中通过：
+
+  await wf.exec.file('./scripts/<脚本>.mjs', ['子命令', '参数'])
+
+调用独立进程；纯计算辅助模块应直接 import。提示词用 wf.runtime.workflowDir 定位，
+不要假设当前 cwd 是工作流目录。
+`,
+    'utf8',
+  );
+}
+
+console.log(`✅ 已生成 ${dir}`);
+console.log(
+  `   可选目录：${requested.size ? [...requested].join(', ') : '无（按需再加）'}`,
+);
+console.log('');
+console.log('下一步：');
+console.log(`  1. 填写 ${join(dir, 'README.md')} 的阶段契约`);
+console.log(`  2. 编辑 ${join(dir, 'workflow.mjs')}`);
+console.log(
+  `  3. node skills/workflow-creator/scripts/validate.mjs ${join(dir, 'workflow.mjs')}`,
+);

package/skills/workflow-creator/scripts/validate.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * skills/workflow-creator/scripts/validate.mjs —— 工作流脚本校验
+ *
+ * 用法：
+ *   node skills/workflow-creator/scripts/validate.mjs workflows/<名字>/workflow.mjs
+ *   node skills/workflow-creator/scripts/validate.mjs --all      # 校验全部工作流
+ *   node skills/workflow-creator/scripts/validate.mjs --api-doc  # 只跑 api.md 对账
+ *
+ * 四层检查：
+ *  ① 引擎那份 scriptGuard.mjs（禁用构造 / meta 形状）—— **不另写一份**，
+ *    否则作者期与运行期的判据会分家，那正是这个文件要防的事。
+ *  ② 脊梁规则：声明了产物、也用了 agent()，却全脚本没有一次 exists()/verify()
+ *    → 这条工作流没有任何核实，agent 一旦 announce-not-do 就静默烂尾。
+ *  ③ api.md 与 WorkflowContext 能力注册表对账 —— 手抄的参考会漂移，而漂移的参考比
+ *    没有参考更糟（它会教错）。
+ *  ④ 配套目录检查：源码中可静态确定的 scripts/prompts/assets 引用必须存在。
+ *
+ * 退出码：0 全通过（可能有 warning）；1 有 error。
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** 从若干起点逐级向上找 minimal-agent 仓库根（认 plugins/workflow-runner/src 为标志）。 */
+function findRepoRoot() {
+  const marker = join('plugins', 'workflow-runner', 'src', 'scriptGuard.mjs');
+  for (const start of [HERE, process.cwd()]) {
+    let dir = resolve(start);
+    for (let i = 0; i < 8; i++) {
+      if (existsSync(join(dir, marker))) return dir;
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+  }
+  return null;
+}
+
+const ROOT = findRepoRoot();
+if (!ROOT) {
+  console.error(
+    '找不到 minimal-agent 仓库根（需要 plugins/workflow-runner/src/scriptGuard.mjs）。\n' +
+      '请在 minimal-agent 仓库内运行本脚本 —— 它刻意复用引擎那份守卫，不自己再写一份。',
+  );
+  process.exit(1);
+}
+
+const ENGINE = join(ROOT, 'plugins', 'workflow-runner', 'src');
+const { validateScript, blankLiteralsAndComments } = await import(
+  pathToFileURL(join(ENGINE, 'scriptGuard.mjs')).href
+);
+const CONTEXT_CAPABILITIES = JSON.parse(
+  await readFile(join(ENGINE, 'workflowContextCapabilities.json'), 'utf8'),
+);
+const CONTEXT_NAMES = Object.entries(CONTEXT_CAPABILITIES).flatMap(([group, names]) =>
+  names.map((name) => `wf.${group}.${name}`),
+);
+
+/** 统计某个调用在**抹除字符串与注释后**的源码里出现几次（避免 prompt 文本误命中）。 */
+function countCalls(blanked, name) {
+  const re = new RegExp(`${name.replace(/\\./g, '\\\\.')}\\s*\\(`, 'g');
+  return (blanked.match(re) ?? []).length;
+}
+
+/**
+ * 脊梁规则检查。
+ *
+ * 判据刻意保守（宁可漏报不要误报）：只有当「用了 agent() **且** 声明了产物
+ * **且** 全脚本一次 exists()/verify() 都没有」时才报。这三条同时成立时，
+ * 这条工作流对 announce-not-do 是完全没有防护的。
+ */
+function checkSpine(source, meta) {
+  const blanked = blankLiteralsAndComments(source);
+  const agents = countCalls(blanked, 'wf.model.agent');
+  if (agents === 0) return null;
+
+  const declaresArtifacts =
+    (Array.isArray(meta?.artifacts) && meta.artifacts.length > 0) ||
+    countCalls(blanked, 'wf.output.artifact') > 0;
+  if (!declaresArtifacts) return null;
+
+  // 脊梁规则的本质是「**不盲信 agent 的自述**」，核实形态不止一种：
+  //   ① 核实文件      exists() / verify()
+  //   ② 核实协议令牌  openState.match(/OPEN=([a-z]+)/) 之后判定
+  //   ③ 核实结构化产出 parseJson(text) 之后判字段
+  //
+  // ⚠️ 早先只认 ①，于是 wechat-reading-shots 被误报 —— 它的 agent 调用一个文件都
+  // 不产出（产物是 ComputerUse observe 直接返回的截图），核实的是 `OPEN=ok` /
+  // `PAGE=N M` 这类协议令牌，守卫其实很严。**误报比漏报更伤**：作者一旦习惯
+  // 「这个警告可以忽略」，真正该看的那次也会被划过去。
+  const checks =
+    countCalls(blanked, 'wf.fs.exists') +
+    countCalls(blanked, 'wf.check.verify') +
+    (blanked.match(/\.match\s*\(/g)?.length ?? 0);
+  if (checks > 0) return null;
+
+  return (
+    `脚本有 ${agents} 处 agent() 调用并声明了产物，却没有任何核实。\n` +
+    '    agent 一旦「宣告要做却没动手」（announce-not-do），这条工作流会静默交付一个不存在的产物。\n' +
+    '    核实方式任选其一：exists()/verify() 查文件、.match() 取协议令牌、parseJson() 解析结构化产出。\n' +
+    '    参见 references/patterns.md 的脊梁规则。'
+  );
+}
+
+/** api.md 的能力表里列了哪些完整路径。 */
+async function namesInApiDoc() {
+  const doc = await readFile(join(HERE, '..', 'references', 'api.md'), 'utf8');
+  const table = doc.slice(doc.indexOf('## 能力表'), doc.indexOf('## 选项'));
+  const names = new Set();
+  for (const m of table.matchAll(/^\|\s*`([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+)`\s*\|/gm)) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+async function checkApiDoc() {
+  const documented = await namesInApiDoc();
+  const declared = new Set(CONTEXT_NAMES);
+  const missing = [...declared].filter((n) => !documented.has(n));
+  const extra = [...documented].filter((n) => !declared.has(n));
+  const problems = [];
+  if (missing.length) {
+    problems.push(
+      `api.md 的能力表漏了：${missing.join(', ')}（引擎注入了但参考里没写，作者不会知道它存在）`,
+    );
+  }
+  if (extra.length) {
+    problems.push(
+      `api.md 的能力表多了：${extra.join(', ')}（参考里写了但引擎没注入，作者照着写会踩空）`,
+    );
+  }
+  return problems;
+}
+
+/**
+ * 真实加载 ESM 模块。默认 run 不执行，因此不会启动业务；相对 import 与运行时包
+ * 也会按生产规则解析，避免作者期校验与运行期分家。
+ */
+async function checkSyntax(file) {
+  try {
+    const mod = await import(`${pathToFileURL(file).href}?validate=${encodeURIComponent(String(process.pid))}`);
+    if (typeof mod.default !== 'function') return '缺少 default run(wf) 导出';
+    return null;
+  } catch (e) {
+    return `语法错误：${e instanceof Error ? e.message : String(e)}`;
+  }
+}
+
+/**
+ * 检查工作流源码中能静态确定的配套文件引用。动态文件名无法假装验证，但其
+ * scripts/prompts/assets 根目录仍必须存在。路径只允许落在当前工作流目录或仓库
+ * workflows 下，避免校验器替脚本接受越界引用。
+ */
+function checkCompanionReferences(source, file) {
+  const problems = [];
+  const workflowDir = dirname(resolve(file));
+  const workflowName = basename(workflowDir);
+  const workflowsRoot = dirname(workflowDir);
+  const checked = new Set();
+
+  const checkPath = (candidate, label) => {
+    const absolute = normalize(resolve(candidate));
+    const allowed =
+      absolute === workflowDir ||
+      absolute.startsWith(`${workflowDir}${sep}`) ||
+      absolute.startsWith(`${workflowsRoot}${sep}`);
+    if (!allowed) {
+      problems.push(`${label} 越出 workflows 目录：${absolute}`);
+      return;
+    }
+    if (checked.has(absolute)) return;
+    checked.add(absolute);
+    if (!existsSync(absolute)) problems.push(`${label} 不存在：${absolute}`);
+  };
+
+  // 完整静态文件引用：workflows/foo/scripts/a.mjs 或 scripts/a.mjs。
+  const exact =
+    /(?:^|[\s'"`(,=])(?:workflows\/([A-Za-z0-9._-]+)\/)?(scripts|prompts|assets)\/([A-Za-z0-9._/-]+\.[A-Za-z0-9._-]+)/gm;
+  for (const match of source.matchAll(exact)) {
+    const [, owner, kind, tail] = match;
+    const base = owner ? join(workflowsRoot, owner) : workflowDir;
+    checkPath(join(base, kind, tail), `配套文件引用 ${match[0]}`);
+  }
+
+  // 动态尾部至少检查根目录，例如 const PROMPTS='workflows/x/prompts'。
+  const roots =
+    /(?:^|[\s'"`(,=])(?:workflows\/([A-Za-z0-9._-]+)\/)?(scripts|prompts|assets)(?=[/'"`])/gm;
+  for (const match of source.matchAll(roots)) {
+    const [, owner, kind] = match;
+    // 普通英文叙述偶尔会出现裸单词；只检查当前工作流或显式 workflows 前缀。
+    if (!owner && !source.includes(`${kind}/`)) continue;
+    const base = owner ? join(workflowsRoot, owner) : workflowDir;
+    checkPath(join(base, kind), `配套目录引用 ${owner ? `workflows/${owner}/` : ''}${kind}`);
+  }
+
+  // 显式写错工作流名通常是复制后忘改，比“文件不存在”更容易定位。
+  for (const match of source.matchAll(/workflows\/([A-Za-z0-9._-]+)\/(scripts|prompts|assets)/g)) {
+    if (match[1] !== workflowName && !existsSync(join(workflowsRoot, match[1]))) {
+      problems.push(`引用了未知工作流目录 workflows/${match[1]}/（当前是 ${workflowName}）`);
+    }
+  }
+  return [...new Set(problems)];
+}
+
+async function validateOne(file) {
+  const source = await readFile(file, 'utf8');
+  const verdict = validateScript(source, { filename: file });
+  const errors = [...verdict.errors];
+  const warnings = [];
+
+  if (verdict.ok) {
+    const syntax = await checkSyntax(file);
+    if (syntax) errors.push(syntax);
+    const spine = checkSpine(source, verdict.meta);
+    if (spine) warnings.push(spine);
+    errors.push(...checkCompanionReferences(source, file));
+  }
+  return { file, errors, warnings };
+}
+
+async function listWorkflowScripts() {
+  const dir = join(ROOT, 'workflows');
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    const p = join(dir, e.name, 'workflow.mjs');
+    if (existsSync(p)) out.push(p);
+  }
+  return out;
+}
+
+// ---- 主流程 ----
+const argv = process.argv.slice(2);
+let failed = false;
+
+const apiProblems = await checkApiDoc();
+if (apiProblems.length) {
+  failed = true;
+  console.error('❌ api.md 与 WorkflowContext 能力注册表不同步：');
+  for (const p of apiProblems) console.error(`   · ${p}`);
+} else if (argv.includes('--api-doc')) {
+  console.log('✅ api.md 与 WorkflowContext 能力注册表一致');
+}
+if (argv.includes('--api-doc')) process.exit(failed ? 1 : 0);
+
+const targets = argv.includes('--all')
+  ? await listWorkflowScripts()
+  : argv.filter((a) => !a.startsWith('--'));
+
+if (targets.length === 0) {
+  console.error('用法：validate.mjs <workflow.mjs> | --all | --api-doc');
+  process.exit(1);
+}
+
+for (const t of targets) {
+  const r = await validateOne(t);
+  const rel = r.file.replace(`${ROOT}\\`, '').replace(`${ROOT}/`, '');
+  if (r.errors.length) {
+    failed = true;
+    console.error(`❌ ${rel}`);
+    for (const e of r.errors) console.error(`   · ${e}`);
+  } else if (r.warnings.length) {
+    console.warn(`⚠️  ${rel}`);
+    for (const w of r.warnings) console.warn(`   · ${w}`);
+  } else {
+    console.log(`✅ ${rel}`);
+  }
+}
+
+process.exit(failed ? 1 : 0);