minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/src/scriptGuard.mjs

@@ -0,0 +1,449 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/scriptGuard.mjs —— 编排脚本静态守卫
+ * ------------------------------------------------------------
+ *  本文件保持纯 JS、零依赖，因此作者期校验与运行期校验可以直接共享。
+ *  它有两个消费方，各自的加载方式完全不同：
+ *    - 引擎（TypeScript）`import` 它 —— 走 Bun/Node 的 ESM
+ *    - 创建 skill 的 `scripts/validate.mjs` 用 `node` **直接 spawn** 它
+ *  这就是它是 `.mjs` 而不是 `.ts` 的**全部理由**：`.ts` 在 npm 形态（宿主是
+ *  `node dist/main.js`）和绿色版（SDK 焊在 exe 里、磁盘没有）下都加载不了。
+ *  工作流自身是真实 ESM，可以正常 import；这里只约束校验器自己的可移植性。
+ *
+ *  ------------------------------------------------------------
+ *  诚实的能力边界（对齐 `src/irreversible/rules.ts` 的写法）：
+ *  这是**防作者手滑**的守卫，不是对抗恶意脚本的沙箱。绕过方式一抓一把 ——
+ *  `globalThis['Dat'+'e'].now()`、`Function('return Date.now()')()`、
+ *  `this.constructor.constructor(...)`。不去堵这些是有意的：脚本作者就是项目
+ *  自己人，真正的价值在于「把不确定性挡在 journal 重放之外」这个**提醒**，
+ *  而不是构筑一道假的安全边界。
+ * ============================================================
+ */
+
+/**
+ * 宿主引擎自身的 npm 包名（对应 `package.json::name`）。
+ *
+ * ⚠️ 硬编码、人工同步，不做运行时读取——`workflowFingerprint.ts` 那份同名常量
+ * 在绿色版 `bun --compile` 编译后 `import.meta.url` 会变成虚拟路径，届时靠相对
+ * 路径去读磁盘上的 `package.json` 会复现 CLAUDE.md 反复警告过的那类绿色版地雷；
+ * `scriptGuard.mjs` 还必须兼容"裸 node 直接 spawn"这条加载方式，同样不适合引入
+ * 文件系统依赖。改包名时两处一起改，这与 `moduleResolution.ts` 头注里
+ * "STATIC_IMPORT/packageName 人工同步"是同一个尺度。
+ */
+const HOST_PACKAGE_NAME = 'minimal-agent';
+
+/** 禁用的不确定性 API —— 它们会让 journal 重放失去意义（见 journal.ts）。 */
+const NONDETERMINISTIC = [
+  {
+    re: /\bDate\s*\.\s*now\s*\(/g,
+    name: 'Date.now()',
+    why: '每次调用返回不同值，会让 resume 时的调用指纹永远失配',
+  },
+  {
+    re: /\bMath\s*\.\s*random\s*\(/g,
+    name: 'Math.random()',
+    why: '同上；需要变化时请让 args 或循环下标参与，而不是取随机数',
+  },
+  {
+    re: /\bnew\s+Date\s*\(\s*\)/g,
+    name: 'new Date()（无参）',
+    why: '同上；带参数的 new Date(x) 是确定性的，不在禁用之列',
+  },
+];
+
+/**
+ * 把源码里**字符串字面量与注释的内容**替换成等长空格，保留其余字节与全部换行。
+ *
+ * 为什么必须做这一步：编排脚本正文里全是自然语言 prompt，随便一句
+ * `agent('把配置 import 进来')` 就会让裸正则误判成「用了 import 语句」。
+ * 误报一旦频繁，作者第一反应是绕开守卫而不是修脚本 —— 守卫就废了。
+ *
+ * 等长替换（不是删除）是为了让报错里的行号/列号仍然指向真实位置。
+ *
+ * 模板串的 `${...}` 内部是**真代码**，故不抹除 —— 里面调 Date.now() 一样该被抓到。
+ *
+ * 正则字面量与除号的歧义用「前一个有意义字符」启发式区分：若前一个非空白字符
+ * 属于 `(,=:[!&|?{};+-*%~^<>` 或紧跟 return/typeof 等关键词，则 `/` 开启正则。
+ * 判错的代价是可能多报一条错（响亮、可改），不会漏报 —— 这个方向是有意选的。
+ */
+export function blankLiteralsAndComments(source) {
+  const out = source.split('');
+  const n = source.length;
+  let i = 0;
+  /** 最近一个有意义（非空白、非注释）的字符，用于正则/除号消歧。 */
+  let prevSignificant = '';
+  /** 模板串嵌套栈：进入 `${` 时压栈，遇到配对 `}` 时回到模板串状态。 */
+  const templateStack = [];
+
+  /** 把 [from, to) 区间抹成空格，但保留换行（行号不能错位）。 */
+  const blank = (from, to) => {
+    for (let k = from; k < to && k < n; k++) {
+      if (out[k] !== '\n' && out[k] !== '\r') out[k] = ' ';
+    }
+  };
+
+  const REGEX_PRECEDERS = '(,=:[!&|?{};+-*%~^<>';
+
+  while (i < n) {
+    const c = source[i];
+
+    // ---- 注释 ----
+    if (c === '/' && source[i + 1] === '/') {
+      let j = i + 2;
+      while (j < n && source[j] !== '\n') j++;
+      blank(i, j);
+      i = j;
+      continue;
+    }
+    if (c === '/' && source[i + 1] === '*') {
+      let j = i + 2;
+      while (j < n && !(source[j] === '*' && source[j + 1] === '/')) j++;
+      blank(i, Math.min(j + 2, n));
+      i = Math.min(j + 2, n);
+      continue;
+    }
+
+    // ---- 单/双引号字符串 ----
+    if (c === "'" || c === '"') {
+      const quote = c;
+      let j = i + 1;
+      while (j < n) {
+        if (source[j] === '\\') {
+          j += 2;
+          continue;
+        }
+        if (source[j] === quote || source[j] === '\n') break;
+        j++;
+      }
+      blank(i + 1, j); // 保留引号本身，只抹内容
+      prevSignificant = quote;
+      i = Math.min(j + 1, n);
+      continue;
+    }
+
+    // ---- 模板串 ----
+    if (c === '`') {
+      let j = i + 1;
+      const segStart = j;
+      while (j < n) {
+        if (source[j] === '\\') {
+          j += 2;
+          continue;
+        }
+        if (source[j] === '`') break;
+        if (source[j] === '$' && source[j + 1] === '{') {
+          blank(segStart, j); // 抹掉这一段纯文本
+          templateStack.push('template');
+          j += 2;
+          prevSignificant = '{';
+          i = j;
+          break; // 回主循环，把 ${...} 内部当普通代码处理
+        }
+        j++;
+      }
+      if (templateStack.length > 0 && i === j) continue; // 已进入 ${}
+      blank(segStart, j);
+      prevSignificant = '`';
+      i = Math.min(j + 1, n);
+      continue;
+    }
+    if (c === '}' && templateStack.length > 0) {
+      // 退出 ${}，回到模板串文本段
+      templateStack.pop();
+      let j = i + 1;
+      const segStart = j;
+      while (j < n) {
+        if (source[j] === '\\') {
+          j += 2;
+          continue;
+        }
+        if (source[j] === '`') break;
+        if (source[j] === '$' && source[j + 1] === '{') {
+          blank(segStart, j);
+          templateStack.push('template');
+          i = j + 2;
+          prevSignificant = '{';
+          break;
+        }
+        j++;
+      }
+      if (templateStack.length > 0 && i > j) continue;
+      blank(segStart, j);
+      prevSignificant = '`';
+      i = Math.min(j + 1, n);
+      continue;
+    }
+
+    // ---- 正则字面量（与除号消歧）----
+    if (c === '/') {
+      const isRegex =
+        prevSignificant === '' ||
+        REGEX_PRECEDERS.includes(prevSignificant) ||
+        /\b(return|typeof|case|in|of|new|delete|void|instanceof)$/.test(
+          source.slice(Math.max(0, i - 12), i).trimEnd(),
+        );
+      if (isRegex) {
+        let j = i + 1;
+        let inClass = false;
+        while (j < n) {
+          if (source[j] === '\\') {
+            j += 2;
+            continue;
+          }
+          if (source[j] === '[') inClass = true;
+          else if (source[j] === ']') inClass = false;
+          else if (source[j] === '/' && !inClass) break;
+          else if (source[j] === '\n') break; // 未闭合，放弃当正则处理
+          j++;
+        }
+        if (j < n && source[j] === '/') {
+          blank(i + 1, j);
+          prevSignificant = '/';
+          i = j + 1;
+          while (i < n && /[a-z]/.test(source[i])) i++; // 跳过 flags
+          continue;
+        }
+      }
+    }
+
+    if (!/\s/.test(c)) prevSignificant = c;
+    i++;
+  }
+
+  return out.join('');
+}
+
+/**
+ * 收集一个全局正则在文本中的全部命中起点。
+ *
+ * 用 `matchAll` 而不是 `while ((m = re.exec(s)))` 有两个实际好处，不只是风格：
+ *  ① 上面那几条规则的正则是**模块级共享对象**，`exec` 会在它们身上留下 `lastIndex`。
+ *    忘了重置（或中途 return）就会让下一次校验从半路开始扫，表现为「同样的脚本，
+ *    第二次校验少报了一条」。`matchAll` 按规范内部克隆正则，源对象一个字节不动。
+ *  ② 零宽匹配的死循环由 `matchAll` 自己处理，不必手写 `lastIndex++` 兜底。
+ */
+function matchIndices(re, text) {
+  const out = [];
+  for (const m of text.matchAll(re)) out.push(m.index ?? 0);
+  return out;
+}
+
+/** 由 offset 求 1-based 行号。 */
+function lineOf(source, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < source.length; i++) {
+    if (source[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * 定位开头的 `export const meta = {...}`，返回字面量文本与其后的正文起点。
+ *
+ * 要求它是**开头第一个语句**（允许前置注释/空行）：meta 要在执行前被静态读出来
+ * （命令补全、/workflows 列表、inputs 映射都在真正跑脚本之前就需要它），
+ * 所以它不能依赖任何运行时状态。位置固定也让扫描逻辑不必解析整个文件。
+ */
+export function extractMetaLiteral(source) {
+  const blanked = blankLiteralsAndComments(source);
+  const m = /^[\s]*export\s+const\s+meta\s*=\s*\{/.exec(blanked);
+  if (!m) {
+    return {
+      ok: false,
+      error:
+        '脚本必须以 `export const meta = { ... }` 开头（前面可以有注释）。meta 会在执行前被静态读出，用于 /workflows 列表与 inputs 映射。',
+    };
+  }
+  const braceStart = m[0].length - 1; // 指向 '{'
+  let depth = 0;
+  let end = -1;
+  for (let i = braceStart; i < blanked.length; i++) {
+    const ch = blanked[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) {
+    return { ok: false, error: '`export const meta = {` 的花括号没有闭合。' };
+  }
+  return {
+    ok: true,
+    literal: source.slice(braceStart, end),
+    bodyOffset: end,
+    metaStart: braceStart,
+  };
+}
+
+/**
+ * 把 meta 字面量求值成对象。
+ *
+ * 要求它是**纯字面量** —— 不许出现标识符引用、函数调用、模板插值、扩展运算符。
+ * 判据是先在抹除字符串后的文本上扫可疑构造，再用一个不带任何自由变量的
+ * `Function` 求值（求值前已确认没有标识符，所以这一步拿不到外部作用域）。
+ */
+export function evaluateMetaLiteral(literal) {
+  const blanked = blankLiteralsAndComments(literal);
+  const suspicious = [
+    { re: /\.\.\./, what: '扩展运算符 ...' },
+    { re: /`/, what: '模板串（meta 必须是纯字面量）' },
+    { re: /\w\s*\(/, what: '函数调用' },
+    { re: /=>/, what: '箭头函数' },
+  ];
+  for (const s of suspicious) {
+    if (s.re.test(blanked)) {
+      return {
+        ok: false,
+        error: `meta 必须是纯字面量，但发现了${s.what}。meta 在执行前被静态读取，此时没有任何运行时值可用。`,
+      };
+    }
+  }
+  try {
+    // 这里的 new Function 是安全的：上面已逐条排除了函数调用/标识符引用/模板插值，
+    // 到这一步 literal 只可能是纯数据字面量；且构造出的函数不接受任何参数，
+    // 拿不到本模块或调用方的任何自由变量。
+    const value = new Function(`"use strict";return (${literal});`)();
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return { ok: false, error: 'meta 必须是一个对象字面量。' };
+    }
+    return { ok: true, value };
+  } catch (e) {
+    return {
+      ok: false,
+      error: `meta 字面量解析失败：${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}
+
+/**
+ * 全量校验一个编排脚本。
+ *
+ * @param {string} source  workflow.mjs 全文
+ * @param {{ filename?: string }} [opts]
+ * @returns {{ ok: boolean, errors: string[], meta?: Record<string, unknown>, bodyOffset?: number }}
+ */
+export function validateScript(source, opts = {}) {
+  const where = opts.filename ? `${opts.filename}: ` : '';
+  const errors = [];
+
+  const extracted = extractMetaLiteral(source);
+  if (!extracted.ok) {
+    return { ok: false, errors: [where + extracted.error] };
+  }
+
+  const evaluated = evaluateMetaLiteral(extracted.literal);
+  if (!evaluated.ok) {
+    return { ok: false, errors: [where + evaluated.error] };
+  }
+  const meta = evaluated.value;
+
+  if (meta.apiVersion !== 2) {
+    errors.push(`${where}meta.apiVersion 必须为 2。V2 工作流是真实 ESM 模块。`);
+  }
+
+  if (typeof meta.description !== 'string' || meta.description.trim() === '') {
+    errors.push(
+      `${where}meta.description 必填（一句话说明这个工作流做什么，会显示在 /workflows 列表里）。`,
+    );
+  }
+  // name 不从 meta 取：目录名即工作流名，单一真值，避免两处漂移。
+  if ('name' in meta) {
+    errors.push(
+      `${where}meta 不接受 name 字段：工作流名恒等于所在目录名（单一真值）。请改目录名。`,
+    );
+  }
+  if (meta.inputs !== undefined && !Array.isArray(meta.inputs)) {
+    errors.push(`${where}meta.inputs 必须是数组。`);
+  }
+  if (meta.artifacts !== undefined && !Array.isArray(meta.artifacts)) {
+    errors.push(`${where}meta.artifacts 必须是数组。`);
+  }
+  if (
+    meta.dependencies !== undefined &&
+    (!Array.isArray(meta.dependencies) ||
+      meta.dependencies.some(
+        (n) => typeof n !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(n),
+      ) ||
+      new Set(meta.dependencies).size !== meta.dependencies.length)
+  ) {
+    errors.push(`${where}meta.dependencies 必须是不重复的工作流目录名数组。`);
+  }
+  if (
+    meta.packages !== undefined &&
+    (!Array.isArray(meta.packages) ||
+      meta.packages.some((n) => typeof n !== 'string' || !/^(?:@[a-zA-Z0-9._-]+\/)?[a-zA-Z0-9._-]+$/.test(n)) ||
+      new Set(meta.packages).size !== meta.packages.length)
+  ) {
+    errors.push(`${where}meta.packages 必须是不重复的 npm 包名数组。`);
+  }
+
+  const importedPackages = new Set();
+  const imports = /(?:^|[;\n])\s*(?:import|export)\s+(?:[^'";]*?\s+from\s+)?['"]([^'"]+)['"]/gm;
+  for (const match of source.matchAll(imports)) {
+    const specifier = match[1];
+    if (specifier.startsWith('.') || specifier.startsWith('node:')) continue;
+    if (specifier.startsWith('/') || specifier.startsWith('file:')) {
+      errors.push(`${where}ESM import 不得使用绝对路径：${specifier}`);
+      continue;
+    }
+    const packageName = specifier.startsWith('@')
+      ? specifier.split('/').slice(0, 2).join('/')
+      : specifier.split('/')[0];
+    // 宿主引擎自身：Node/Bun 的包自引用 + package.json::exports 的 "./src/*"/
+    // "./plugins/*" 通配符会让 `minimal-agent/src/xxx` 解析到真实内核文件，
+    // 完全绕开 wf 分组能力对象对调度/记账/心跳/预算的管控。这不是"没声明"的
+    // 问题——即使声明进 meta.packages 也要拒绝，所以单独报错、不进
+    // importedPackages（避免作者看到"必须声明"后真的把它加进去，反而踩得更深）。
+    if (packageName === HOST_PACKAGE_NAME) {
+      errors.push(
+        `${where}禁止 import 宿主引擎自身（${specifier}）：\`${HOST_PACKAGE_NAME}\` ` +
+          `就是正在编排这个工作流的内核，一切对内核的访问必须经 wf 分组能力对象` +
+          `（wf.model/wf.tools/wf.exec/wf.fs/...），直接 import 会绕开调度排队、` +
+          `断点续跑记账、心跳与预算闸，且可能反向重入正在执行它的内核本身。`,
+      );
+      continue;
+    }
+    importedPackages.add(packageName);
+  }
+  for (const name of importedPackages) {
+    if (!meta.packages?.includes(name)) {
+      errors.push(`${where}运行时包 ${name} 必须声明在 meta.packages 中。`);
+    }
+  }
+  if (/\bimport\s*\(/.test(blankLiteralsAndComments(source).slice(extracted.bodyOffset))) {
+    errors.push(`${where}不允许动态 import()：依赖图无法静态指纹化，请改用静态 import。`);
+  }
+
+  // 正文（meta 之后）的禁用构造扫描，全部在抹除字符串/注释后的文本上做。
+  const blanked = blankLiteralsAndComments(source);
+  const bodyBlanked = blanked.slice(extracted.bodyOffset);
+  const bodyBase = extracted.bodyOffset;
+
+  for (const index of matchIndices(/\brequire\s*\(/g, bodyBlanked)) {
+    const line = lineOf(source, bodyBase + index);
+    errors.push(
+      `${where}第 ${line} 行不允许 require()：V2 工作流是 ESM，请改用静态 import。`,
+    );
+  }
+
+  for (const rule of NONDETERMINISTIC) {
+    for (const index of matchIndices(rule.re, bodyBlanked)) {
+      const line = lineOf(source, bodyBase + index);
+      errors.push(`${where}第 ${line} 行禁止使用 ${rule.name} —— ${rule.why}`);
+    }
+  }
+
+  if (!/\bexport\s+default\s+async\s+function\s+run\s*\(\s*wf\s*\)/.test(bodyBlanked)) {
+    errors.push(
+      `${where}必须导出入口：\`export default async function run(wf) { ... }\`。`,
+    );
+  }
+
+  return errors.length > 0
+    ? { ok: false, errors, meta, bodyOffset: extracted.bodyOffset }
+    : { ok: true, errors: [], meta, bodyOffset: extracted.bodyOffset };
+}