minimal-agent 0.13.0 → 0.14.0

package/plugins/workflow-runner/test/scriptGuard.test.ts

@@ -0,0 +1,276 @@
+/**
+ * plugins/workflow-runner/test/scriptGuard.test.ts —— 编排脚本静态守卫
+ *
+ * 这组测试真正在守的是**误报**，不是漏报。
+ *
+ * 漏报的后果是脚本跑起来才报错（响亮、可查）；而误报的后果要命得多：编排脚本
+ * 正文全是自然语言 prompt，`agent('把配置 import 进来')` 这种句子遍地都是。
+ * 只要裸正则扫一次源码，这类句子就会被判成「用了 import 语句」——作者第一反应
+ * 不会是改脚本，而是想办法绕开守卫，守卫从此形同虚设。
+ *
+ * 所以下面「不该误报」的用例比「该抓到」的用例更重要，删任何一条都是在削弱守卫的
+ * 可信度而不是它的严格度。
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  blankLiteralsAndComments,
+  evaluateMetaLiteral,
+  extractMetaLiteral,
+  validateScript,
+} from '../src/scriptGuard.mjs';
+
+/** 一个最小的合法脚本头，供各用例拼接正文。 */
+const HEAD = `export const meta = { apiVersion: 2, description: '测试用' }\nexport default async function run(wf) {\n`;
+const END = `\n}\n`;
+
+describe('词法抹除：字符串与注释的内容不参与扫描', () => {
+  test('★ prompt 里出现 import 一词不得被抹除逻辑漏掉（否则必误报）', () => {
+    const out = blankLiteralsAndComments(`agent('请把配置 import 进来')`);
+    expect(out).not.toContain('import');
+    expect(out.startsWith("agent('")).toBe(true); // 引号本身保留，仅内容抹空
+  });
+
+  test('注释内容整体抹除，但换行保留（行号不能错位）', () => {
+    const src = `// 别用 Date.now()\nlog('ok')`;
+    const out = blankLiteralsAndComments(src);
+    expect(out).not.toContain('Date.now');
+    expect(out.split('\n').length).toBe(src.split('\n').length);
+  });
+
+  test('真正的代码原样保留', () => {
+    expect(blankLiteralsAndComments('const t = Date.now()')).toBe(
+      'const t = Date.now()',
+    );
+  });
+
+  test('★ 模板串：文本段抹除，${} 内部是真代码必须保留', () => {
+    const out = blankLiteralsAndComments(
+      'const s = `导入 import 数据 ${Math.random()}`',
+    );
+    expect(out).not.toContain('import');
+    expect(out).toContain('Math.random()');
+  });
+
+  test('★ 嵌套模板串里的不确定性调用仍要保留', () => {
+    const out = blankLiteralsAndComments(
+      'const s = `a ${`b ${Date.now()}`} c`',
+    );
+    expect(out).toContain('Date.now()');
+  });
+
+  test('★ 正则字面量含引号，不得打乱其后字符串的配对', () => {
+    // 朴素扫描会把正则里的 ' 当成字符串开始，从此整段错位。
+    const out = blankLiteralsAndComments(
+      `const re = /['"]/g; const x = 'import'`,
+    );
+    expect(out).toContain('/    /g');
+    expect(out).not.toContain('import');
+  });
+
+  test('除号不得被误当成正则开始', () => {
+    const out = blankLiteralsAndComments(`const r = a / b; const c = 'import'`);
+    expect(out).toContain('a / b');
+    expect(out).not.toContain('import');
+  });
+
+  test('抹除后长度不变（报错行号靠这个精确）', () => {
+    const src = `const a = 'hello'; // 注释\nconst b = \`x\${1}\`;`;
+    expect(blankLiteralsAndComments(src).length).toBe(src.length);
+  });
+});
+
+describe('meta 提取与求值', () => {
+  test('提取开头的 meta 字面量，并给出正文起点', () => {
+    const src = `export const meta = { description: 'x', inputs: [{ name: 'a' }] }\nlog('hi')`;
+    const r = extractMetaLiteral(src);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.literal).toContain('description');
+      expect(src.slice(r.bodyOffset)).toContain("log('hi')");
+    }
+  });
+
+  test('允许 meta 之前有注释', () => {
+    const src = `// 说明\n/* 块注释 */\nexport const meta = { description: 'x' }\n`;
+    expect(extractMetaLiteral(src).ok).toBe(true);
+  });
+
+  test('没有 meta → 明确报错而不是静默当空对象', () => {
+    const r = extractMetaLiteral(`log('hi')`);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toContain('export const meta');
+  });
+
+  test('花括号未闭合 → 报错，不吞', () => {
+    const r = extractMetaLiteral(`export const meta = { description: 'x'\n`);
+    expect(r.ok).toBe(false);
+  });
+
+  test('纯字面量求值成功', () => {
+    const r = evaluateMetaLiteral(
+      `{ description: 'x', artifacts: ['a/b.md'] }`,
+    );
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value.artifacts).toEqual(['a/b.md']);
+  });
+
+  test.each([
+    ['函数调用', '{ description: makeDesc() }'],
+    ['模板串', '{ description: `x${1}` }'],
+    ['扩展运算符', `{ ...base, description: 'x' }`],
+    ['箭头函数', `{ description: 'x', f: () => 1 }`],
+  ])('拒绝非纯字面量：%s', (_label, literal) => {
+    const r = evaluateMetaLiteral(literal);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toContain('纯字面量');
+  });
+});
+
+describe('validateScript：该抓的要抓到', () => {
+  test.each([
+    ['动态 import()', `const m = await import('./x.mjs')`, 'import()'],
+    ['require()', `const x = require('fs')`, 'require()'],
+    ['Date.now()', 'const t = Date.now()', 'Date.now()'],
+    ['Math.random()', 'const r = Math.random()', 'Math.random()'],
+    ['无参 new Date()', 'const d = new Date()', 'new Date()'],
+  ])('%s 必须被拒绝', (_label, body, expected) => {
+    const r = validateScript(HEAD + body + END);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toContain(expected);
+  });
+
+  test('带参数的 new Date(x) 是确定性的，不在禁用之列', () => {
+    const r = validateScript(`${HEAD}const d = new Date(wf.input.values.stamp)${END}`);
+    expect(r.ok).toBe(true);
+  });
+
+  test('真实 ESM 允许静态相对导入', () => {
+    const r = validateScript(`${HEAD.replace('export default async function run(wf) {\n', "import { x } from './x.mjs';\nexport default async function run(wf) {\n")}return x${END}`);
+    expect(r.ok).toBe(true);
+  });
+
+  test('报错要带行号 —— 长脚本里没有行号等于没报', () => {
+    const body = `${'log("x")\n'.repeat(20)}const t = Date.now()`;
+    const r = validateScript(HEAD + body + END);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toMatch(/第 23 行/);
+  });
+
+  test('同一种违规出现多次要逐条报出，不是只报第一条', () => {
+    const r = validateScript(
+      `${HEAD}const a = Date.now()\nconst b = Date.now()${END}`,
+    );
+    const hits = r.errors.filter((e) => e.includes('Date.now()'));
+    expect(hits.length).toBe(2);
+  });
+});
+
+describe('validateScript：禁止 import 宿主引擎自身（包自引用红线）', () => {
+  // package.json::exports 里的 "./src/*"/"./plugins/*" 通配符 + Node/Bun 包
+  // 自引用，会让 `minimal-agent/src/xxx` 解析到真实内核文件、绕开 wf 分组能力
+  // 对象。这条必须比"未声明在 meta.packages"更早触发，且文案不能引导作者
+  // "去声明一下就好了"。
+  const withImport = HEAD.replace(
+    'export default async function run(wf) {\n',
+    "import { runQuery } from 'minimal-agent/src/loop.js';\nexport default async function run(wf) {\n",
+  );
+
+  test('★ 未声明 meta.packages 时同样要点名"宿主引擎自身"，不是泛泛的未声明错误', () => {
+    const r = validateScript(withImport + 'return 1' + END);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toContain('宿主引擎自身');
+    expect(r.errors.join('\n')).not.toContain('必须声明在 meta.packages 中');
+  });
+
+  test('★ 即使声明进 meta.packages 也要拒绝——这不是"没声明"的问题', () => {
+    const src = withImport.replace(
+      "description: '测试用'",
+      "description: '测试用', packages: ['minimal-agent']",
+    );
+    const r = validateScript(src + 'return 1' + END);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toContain('宿主引擎自身');
+  });
+});
+
+describe('validateScript：不该误报的必须放行', () => {
+  test('★ prompt 文本里的 import / require / Date.now 一律不算违规', () => {
+    const r = validateScript(
+      `${HEAD}await wf.model.agent('把配置 import 进来，必要时 require() 一下，并记录 Date.now()')${END}`,
+    );
+    expect(r.ok).toBe(true);
+  });
+
+  test('★ 注释里写这些词也不算违规（文档里常要提到它们）', () => {
+    const r = validateScript(
+      `${HEAD}// 这里刻意不用 Date.now()，理由见 journal.ts\nwf.output.progress({message:'ok'})${END}`,
+    );
+    expect(r.ok).toBe(true);
+  });
+
+  test('一个正常的编排脚本整体通过', () => {
+    const src = `export const meta = {
+  apiVersion: 2,
+  description: '审计路由的鉴权缺失',
+  inputs: [{ name: 'dir', required: true }],
+  artifacts: ['out/audit.md'],
+}
+export default async function run(wf) {
+const files = await wf.tools.call('Glob', { pattern: \`\${wf.input.values.dir}/**/*.ts\` })
+const findings = []
+for (const f of files) {
+  const r = await wf.model.agent(\`审计 \${f} 的鉴权检查\`, { label: f })
+  if (r) findings.push(r)
+}
+await wf.tools.call('Write', { file_path: 'out/audit.md', content: findings.join('\\n') })
+wf.output.message('审计完成')
+return findings
+}
+`;
+    const r = validateScript(src);
+    expect(r.errors).toEqual([]);
+    expect(r.ok).toBe(true);
+    expect(r.meta?.description).toBe('审计路由的鉴权缺失');
+  });
+
+  test('默认入口必须是 async function run(wf)', () => {
+    const wrong = `export const meta = { apiVersion: 2, description: 'x' }\nexport default function execute(context) { return context; }`;
+    expect(validateScript(wrong).errors.join('\n')).toContain(
+      'export default async function run(wf)',
+    );
+  });
+});
+
+describe('validateScript：meta 的形状约束', () => {
+  test('description 必填', () => {
+    const r = validateScript(`export const meta = { apiVersion: 2 }\nexport default async function run(){}`);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toContain('description');
+  });
+
+  test('★ 拒绝 meta.name —— 工作流名恒等于目录名，两处声明必然漂移', () => {
+    const r = validateScript(
+      `export const meta = { apiVersion: 2, name: 'foo', description: 'x' }\nexport default async function run(){}`,
+    );
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toContain('目录名');
+  });
+
+  test.each([
+    ['inputs', `export const meta = { apiVersion: 2, description: 'x', inputs: 'a' }\nexport default async function run(){}`],
+    ['artifacts', `export const meta = { apiVersion: 2, description: 'x', artifacts: 'a' }\nexport default async function run(){}`],
+  ])('%s 必须是数组', (field, src) => {
+    const r = validateScript(src);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join('\n')).toContain(field);
+  });
+
+  test('文件名会出现在错误信息里（批量校验时要能定位到是哪个工作流）', () => {
+    const r = validateScript(`log('x')`, {
+      filename: 'workflows/foo/workflow.mjs',
+    });
+    expect(r.errors[0]).toContain('workflows/foo/workflow.mjs');
+  });
+});

package/plugins/workflow-runner/test/skillDocSync.test.ts

@@ -0,0 +1,78 @@
+/**
+ * plugins/workflow-runner/test/skillDocSync.test.ts —— 创建 skill 的参考文档漂移守护
+ *
+ * 守的是一类**只会静默教错**的问题：`skills/workflow-creator/references/api.md`
+ * 是 agent 写工作流时唯一会照抄的参考。它与引擎注入的实际能力一旦分家：
+ *   · 漏写 → agent 不知道那个能力存在，会绕远路自己造轮子
+ *   · 多写 → agent 照着写出 `undefined is not a function`
+ *
+ * 光这一轮就新增了 sh / resetContext / parseJson / images / contextFiles 五样 ——
+ * 手抄的参考一周内必然漂移，所以必须有自动对账。
+ *
+ * `skills/workflow-creator/scripts/validate.mjs --api-doc` 跑的是同一份判据；
+ * 这里再放一份进 `bun test`，是因为没人会记得每次改完 api.ts 都手动跑那个脚本。
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { WORKFLOW_CONTEXT_CAPABILITIES } from '../src/workflowContext.js';
+import { parseFrontmatter } from '../../../src/prompts/skillList.js';
+
+const REPO = join(import.meta.dir, '..', '..', '..');
+const API_DOC = join(
+  REPO,
+  'skills',
+  'workflow-creator',
+  'references',
+  'api.md',
+);
+
+/** 抽出 api.md「能力表」里列出的名字（表格首列的反引号形式）。 */
+function documentedNames(): Set<string> {
+  const doc = readFileSync(API_DOC, 'utf8');
+  const start = doc.indexOf('## 能力表');
+  const nextHeading = doc.indexOf('\n## ', start + 4);
+  const table = doc.slice(start, nextHeading < 0 ? undefined : nextHeading);
+  const names = new Set<string>();
+  for (const m of table.matchAll(
+    /^\|\s*`(wf\.[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)`\s*\|/gm,
+  )) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+describe('创建 skill 的 api.md 与引擎清单同步', () => {
+  test('★ 能力表列出的路径集合 == 机器可读能力注册表', () => {
+    const registered = Object.entries(WORKFLOW_CONTEXT_CAPABILITIES).flatMap(
+      ([group, names]) => names.map((name) => `wf.${group}.${name}`),
+    );
+    expect([...documentedNames()].sort()).toEqual(registered.sort());
+  });
+
+  test('能力表本身非空 —— 防「切片没切到、空集合等于空集合」的假通过', () => {
+    expect(documentedNames().size).toBeGreaterThan(10);
+  });
+
+  test('★ SKILL.md 能被生产解析器认出 —— 认不出整个技能不会被扫描到', () => {
+    const dir = join(REPO, 'skills', 'workflow-creator');
+    const meta = parseFrontmatter(readFileSync(join(dir, 'SKILL.md'), 'utf8'), dir);
+
+    // ⚠️ 断言必须走 skillList.ts 的**同一个**解析器，不能另写判据。
+    // 曾经这里写 `startsWith('---\n')`，而解析器用的是 `/^---\r?\n/` ——
+    // core.autocrlf=true 的 Windows 检出把 LF 换成 CRLF，测试当场红，
+    // 而技能其实一直好好地被扫描到。测试比生产严 = 训练人忽略红灯。
+    expect(meta).not.toBeNull();
+    expect(meta!.name).toBe('workflow-creator');
+    // description 决定 agent 会不会想起来用它，缺了等于技能存在但无人问津
+    expect(meta!.description.length).toBeGreaterThan(0);
+  });
+
+  test('CRLF 与 LF 两种行尾都必须解析得出 —— 锁死上面那条教训', () => {
+    const body = '---\nname: x\ndescription: d\n---\n正文\n';
+    expect(parseFrontmatter(body, '/tmp/x')?.name).toBe('x');
+    expect(parseFrontmatter(body.replace(/\n/g, '\r\n'), '/tmp/x')?.name).toBe('x');
+  });
+});