minimal-agent 0.1.9 → 0.2.0

package/plugins/ralph-wiggum/test/verificationGate.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  parseVerifyArgs,
+  verifyFileExists,
+  verifyFileContains,
+  runVerification,
+} from '../src/verificationGate.ts';
+import type { Check } from '../src/verificationGate.ts';
+
+describe('verificationGate', () => {
+  describe('parseVerifyArgs', () => {
+    it('解析 --verify shell:xxx', () => {
+      const checks = parseVerifyArgs('--verify "shell:npm test"');
+      expect(checks).toHaveLength(1);
+      expect(checks[0].type).toBe('shell');
+      expect(checks[0].command).toBe('npm test');
+    });
+
+    it('解析多个 --verify', () => {
+      const checks = parseVerifyArgs(
+        '--verify "shell:npm test" --verify "file_exists:src/index.ts" --verify "file_contains:README.md:minimal-agent"',
+      );
+      expect(checks).toHaveLength(3);
+      expect(checks[0].type).toBe('shell');
+      expect(checks[1].type).toBe('file_exists');
+      expect(checks[2].type).toBe('file_contains');
+    });
+
+    it('无 --verify 返回空数组', () => {
+      const checks = parseVerifyArgs('--max-iterations 50 "some task"');
+      expect(checks).toHaveLength(0);
+    });
+
+    it('空字符串返回空数组', () => {
+      const checks = parseVerifyArgs('');
+      expect(checks).toHaveLength(0);
+    });
+
+    it('忽略无效类型', () => {
+      const checks = parseVerifyArgs('--verify "invalid:value"');
+      expect(checks).toHaveLength(0);
+    });
+
+    it('解析 test_count', () => {
+      const checks = parseVerifyArgs('--verify "test_count:10"');
+      expect(checks).toHaveLength(1);
+      expect(checks[0].type).toBe('test_count');
+      expect(checks[0].minCount).toBe(10);
+    });
+  });
+
+  describe('verifyFileExists', () => {
+    it('存在的文件通过', () => {
+      const result = verifyFileExists('package.json');
+      expect(result.passed).toBe(true);
+      expect(result.output).toContain('存在');
+    });
+
+    it('不存在的文件不通过', () => {
+      const result = verifyFileExists('__nonexistent_file_xyz__');
+      expect(result.passed).toBe(false);
+      expect(result.output).toContain('不存在');
+    });
+  });
+
+  describe('verifyFileContains', () => {
+    it('文件包含模式串通过', () => {
+      const result = verifyFileContains('package.json', '"name"');
+      expect(result.passed).toBe(true);
+    });
+
+    it('文件不包含模式串不通过', () => {
+      const result = verifyFileContains('package.json', '__xyz_pattern_not_exist__');
+      expect(result.passed).toBe(false);
+    });
+
+    it('不存在的文件不通过', () => {
+      const result = verifyFileContains('__nonexistent__', 'pattern');
+      expect(result.passed).toBe(false);
+      expect(result.output).toContain('无法读取');
+    });
+  });
+
+  describe('runVerification', () => {
+    it('无验证项直接通过', async () => {
+      const result = await runVerification([]);
+      expect(result.passed).toBe(true);
+      expect(result.summary).toContain('无验证项');
+    });
+
+    it('全部通过的检查返回 passed=true', async () => {
+      const checks: Check[] = [
+        { type: 'file_exists', file: 'package.json' },
+        { type: 'file_contains', file: 'package.json', pattern: '"name"' },
+      ];
+      const result = await runVerification(checks);
+      expect(result.passed).toBe(true);
+      expect(result.details).toHaveLength(2);
+      expect(result.details.every((d) => d.passed)).toBe(true);
+    });
+
+    it('有失败的检查返回 passed=false', async () => {
+      const checks: Check[] = [
+        { type: 'file_exists', file: '__nonexistent__' },
+      ];
+      const result = await runVerification(checks);
+      expect(result.passed).toBe(false);
+      expect(result.summary).toContain('❌');
+    });
+
+    it('混合结果返回 passed=false', async () => {
+      const checks: Check[] = [
+        { type: 'file_exists', file: 'package.json' },
+        { type: 'file_exists', file: '__nonexistent__' },
+      ];
+      const result = await runVerification(checks);
+      expect(result.passed).toBe(false);
+      expect(result.details[0].passed).toBe(true);
+      expect(result.details[1].passed).toBe(false);
+    });
+  });
+});

package/plugins/workflow-runner/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "workflow-runner",
+  "version": "0.1.0",
+  "description": "YAML workflow DAG executor for minimal-agent. Provides /workflow and /workflows commands."
+}

package/plugins/workflow-runner/commands/workflow.md

@@ -0,0 +1,15 @@
+---
+description: 运行 YAML 工作流（DAG 执行器），用 --input k=v 传参
+argument-hint: <name> [--input key=value ...]
+---
+
+# /workflow
+
+本命令由 workflow-runner 插件接管（plugin.ts.runCommand），不会把 prompt 喂给 LLM。
+直接调用插件内置的 YAML DAG 执行器，按 steps 顺序运行 tool / llm / assert / branch / loop 等节点。
+
+用法示例：
+
+  /workflow hello-workflow --input name=alice --input lang=zh
+
+输入 /workflows 查看可用工作流列表。

package/plugins/workflow-runner/commands/workflows.md

@@ -0,0 +1,8 @@
+---
+description: 列出当前 cwd 与插件包内可用的 YAML 工作流
+---
+
+# /workflows
+
+由 workflow-runner 插件接管（plugin.ts.runCommand），扫描 cwd/workflows/ 与
+plugin 自带 examples/ 下的 *.yaml，把名称 + 一行描述列出来。

package/plugins/workflow-runner/plugin.ts

@@ -0,0 +1,42 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/plugin.ts
+ * ------------------------------------------------------------
+ *  workflow-runner 插件入口。接管 /workflow 与 /workflows 两个命令的执行：
+ *  不走声明式 markdown→LLM 通道，而是直接调插件内置的 YAML DAG 执行器。
+ *
+ *  执行器与全部依赖都住在本插件目录 ./src/，外部 src/ 一行不改。
+ *  插件只通过 src/plugin-sdk.ts 取框架运行时（runQuery / chat / executeTool 等）。
+ *
+ *  契约：default export 一个 PluginApi 对象。框架 pluginLoader 会按 pluginRoot
+ *  缓存这次 import，所以 cold start 后 dynamic import 只跑一次。
+ * ============================================================
+ */
+
+import type { PluginApi } from '../../src/plugin-sdk.ts';
+import { runWorkflowFromCommand, runWorkflowsList } from './src/index.ts';
+
+const api: PluginApi = {
+  async *runCommand(commandName, args, ctx) {
+    if (commandName === 'workflows') {
+      yield* runWorkflowsList();
+      return;
+    }
+
+    if (commandName === 'workflow') {
+      yield* runWorkflowFromCommand(args, {
+        provider: ctx.provider,
+        history: ctx.history,
+        signal: ctx.signal,
+      });
+      return;
+    }
+
+    yield {
+      type: 'error',
+      error: `workflow-runner: 未知命令 /${commandName}`,
+    };
+  },
+};
+
+export default api;

package/plugins/workflow-runner/src/expressions.ts

@@ -0,0 +1,371 @@
+/**
+ * ============================================================
+ *  src/workflows/expressions.ts —— workflow 表达式引擎（mini）
+ * ------------------------------------------------------------
+ *  WHY 不直接 eval / Function？
+ *    Workflow 来源不可信（用户编辑器生成 / 别人贡献的 yaml），允许任意
+ *    JS 执行 = 任意远程代码执行。所以我们手写一个**只支持必要语法**的
+ *    递归下降解析器：常量、变量引用、点路径、字符串/数字字面量、数组、
+ *    比较、布尔运算、白名单内置函数。
+ *
+ *  支持的语法：
+ *    expr    := or
+ *    or      := and ( '||' and )*
+ *    and     := not ( '&&' not )*
+ *    not     := '!' not | comparison
+ *    comparison := primary ( ('==' | '!=' | '>=' | '<=' | '>' | '<') primary )?
+ *    primary := number | string | array | call | path | '(' expr ')'
+ *    array   := '[' expr (',' expr)* ']'
+ *    call    := IDENT '(' expr (',' expr)* ')'   // 白名单
+ *    path    := IDENT ('.' IDENT)*               // 变量 + 点路径
+ *
+ *  白名单函数：fileExists / length / lower / upper
+ *
+ *  插值：${EXPR} —— 把 EXPR 求值后 toString 替换；对象/数组用 JSON.stringify。
+ *  interpolateDeep 递归处理对象/数组/字符串。
+ * ============================================================
+ */
+
+import { existsSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+
+import { getWorkingDir } from '../../../src/plugin-sdk.ts';
+import type { VarStack } from './types.ts';
+
+// ---------------- Tokenizer ----------------
+
+type Token =
+  | { kind: 'num'; value: number }
+  | { kind: 'str'; value: string }
+  | { kind: 'ident'; value: string }
+  | { kind: 'punct'; value: string };
+
+const PUNCT2 = new Set(['==', '!=', '>=', '<=', '&&', '||']);
+const PUNCT1 = new Set(['(', ')', '[', ']', ',', '.', '!', '>', '<']);
+
+function tokenize(src: string): Token[] {
+  const out: Token[] = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+      i++;
+      continue;
+    }
+    // 字符串
+    if (c === '"' || c === "'") {
+      const quote = c;
+      let s = '';
+      i++;
+      while (i < src.length && src[i] !== quote) {
+        if (src[i] === '\\' && i + 1 < src.length) {
+          const nx = src[i + 1];
+          s += nx === 'n' ? '\n' : nx === 't' ? '\t' : nx;
+          i += 2;
+        } else {
+          s += src[i++];
+        }
+      }
+      if (src[i] !== quote) throw new Error(`未闭合的字符串：${src}`);
+      i++;
+      out.push({ kind: 'str', value: s });
+      continue;
+    }
+    // 数字
+    if ((c >= '0' && c <= '9') || (c === '-' && src[i + 1] >= '0' && src[i + 1] <= '9')) {
+      let j = i;
+      if (src[j] === '-') j++;
+      while (j < src.length && ((src[j] >= '0' && src[j] <= '9') || src[j] === '.')) j++;
+      out.push({ kind: 'num', value: parseFloat(src.slice(i, j)) });
+      i = j;
+      continue;
+    }
+    // 双字符标点
+    const two = src.slice(i, i + 2);
+    if (PUNCT2.has(two)) {
+      out.push({ kind: 'punct', value: two });
+      i += 2;
+      continue;
+    }
+    // 单字符标点
+    if (PUNCT1.has(c)) {
+      out.push({ kind: 'punct', value: c });
+      i++;
+      continue;
+    }
+    // 标识符
+    if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_') {
+      let j = i;
+      while (
+        j < src.length &&
+        ((src[j] >= 'a' && src[j] <= 'z') ||
+          (src[j] >= 'A' && src[j] <= 'Z') ||
+          (src[j] >= '0' && src[j] <= '9') ||
+          src[j] === '_')
+      ) {
+        j++;
+      }
+      out.push({ kind: 'ident', value: src.slice(i, j) });
+      i = j;
+      continue;
+    }
+    throw new Error(`非法字符 '${c}' 在表达式 "${src}"`);
+  }
+  return out;
+}
+
+// ---------------- Parser → AST → eval（一次性递归下降，零 AST 对象） ----------------
+
+interface Cursor {
+  toks: Token[];
+  pos: number;
+}
+
+function peek(c: Cursor): Token | null {
+  return c.pos < c.toks.length ? c.toks[c.pos] : null;
+}
+function eat(c: Cursor): Token {
+  return c.toks[c.pos++];
+}
+function isPunct(c: Cursor, v: string): boolean {
+  const t = peek(c);
+  return !!t && t.kind === 'punct' && t.value === v;
+}
+
+const BUILTINS: Record<string, (args: unknown[]) => unknown> = {
+  fileExists(args) {
+    const p = String(args[0] ?? '');
+    if (!p) return false;
+    const abs = isAbsolute(p) ? p : join(getWorkingDir(), p);
+    return existsSync(abs);
+  },
+  length(args) {
+    const v = args[0];
+    if (typeof v === 'string' || Array.isArray(v)) return v.length;
+    if (v && typeof v === 'object') return Object.keys(v).length;
+    return 0;
+  },
+  lower(args) {
+    return String(args[0] ?? '').toLowerCase();
+  },
+  upper(args) {
+    return String(args[0] ?? '').toUpperCase();
+  },
+};
+
+function parseOr(c: Cursor, vars: VarStack): unknown {
+  let left = parseAnd(c, vars);
+  while (isPunct(c, '||')) {
+    eat(c);
+    const right = parseAnd(c, vars);
+    left = truthy(left) || truthy(right);
+  }
+  return left;
+}
+function parseAnd(c: Cursor, vars: VarStack): unknown {
+  let left = parseNot(c, vars);
+  while (isPunct(c, '&&')) {
+    eat(c);
+    const right = parseNot(c, vars);
+    left = truthy(left) && truthy(right);
+  }
+  return left;
+}
+function parseNot(c: Cursor, vars: VarStack): unknown {
+  if (isPunct(c, '!')) {
+    eat(c);
+    return !truthy(parseNot(c, vars));
+  }
+  return parseComparison(c, vars);
+}
+function parseComparison(c: Cursor, vars: VarStack): unknown {
+  const left = parsePrimary(c, vars);
+  const t = peek(c);
+  if (t && t.kind === 'punct' && ['==', '!=', '>=', '<=', '>', '<'].includes(t.value)) {
+    eat(c);
+    const right = parsePrimary(c, vars);
+    switch (t.value) {
+      case '==':
+        // eslint-disable-next-line eqeqeq
+        return left == right;
+      case '!=':
+        // eslint-disable-next-line eqeqeq
+        return left != right;
+      case '>':
+        return (left as number) > (right as number);
+      case '<':
+        return (left as number) < (right as number);
+      case '>=':
+        return (left as number) >= (right as number);
+      case '<=':
+        return (left as number) <= (right as number);
+    }
+  }
+  return left;
+}
+function parsePrimary(c: Cursor, vars: VarStack): unknown {
+  const t = peek(c);
+  if (!t) throw new Error('表达式意外结束');
+
+  if (t.kind === 'punct' && t.value === '(') {
+    eat(c);
+    const v = parseOr(c, vars);
+    if (!isPunct(c, ')')) throw new Error("缺少 ')'");
+    eat(c);
+    return v;
+  }
+  if (t.kind === 'punct' && t.value === '[') {
+    eat(c);
+    const arr: unknown[] = [];
+    if (!isPunct(c, ']')) {
+      arr.push(parseOr(c, vars));
+      while (isPunct(c, ',')) {
+        eat(c);
+        arr.push(parseOr(c, vars));
+      }
+    }
+    if (!isPunct(c, ']')) throw new Error("缺少 ']'");
+    eat(c);
+    return arr;
+  }
+  if (t.kind === 'num') {
+    eat(c);
+    return t.value;
+  }
+  if (t.kind === 'str') {
+    eat(c);
+    return t.value;
+  }
+  if (t.kind === 'ident') {
+    eat(c);
+    // 函数调用？
+    if (isPunct(c, '(')) {
+      eat(c);
+      const argv: unknown[] = [];
+      if (!isPunct(c, ')')) {
+        argv.push(parseOr(c, vars));
+        while (isPunct(c, ',')) {
+          eat(c);
+          argv.push(parseOr(c, vars));
+        }
+      }
+      if (!isPunct(c, ')')) throw new Error("缺少 ')'");
+      eat(c);
+      const fn = BUILTINS[t.value];
+      if (!fn) throw new Error(`未知函数 "${t.value}"。白名单：${Object.keys(BUILTINS).join(', ')}`);
+      return fn(argv);
+    }
+    // 字面常量
+    if (t.value === 'true') return true;
+    if (t.value === 'false') return false;
+    if (t.value === 'null') return null;
+    // 变量 + 点路径
+    let cur: unknown = vars.get(t.value);
+    while (isPunct(c, '.')) {
+      eat(c);
+      const next = eat(c);
+      if (next.kind !== 'ident') throw new Error('点号后必须是标识符');
+      cur = cur != null && typeof cur === 'object' ? (cur as Record<string, unknown>)[next.value] : undefined;
+    }
+    return cur;
+  }
+  throw new Error(`无法解析 token: ${JSON.stringify(t)}`);
+}
+
+function truthy(v: unknown): boolean {
+  if (v === null || v === undefined) return false;
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'number') return v !== 0 && !Number.isNaN(v);
+  if (typeof v === 'string') return v.length > 0;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === 'object') return Object.keys(v).length > 0;
+  return true;
+}
+
+// ---------------- 对外 API ----------------
+
+/** 计算表达式（裸的，不带 ${} 包裹）。失败抛错。 */
+export function evalExpr(expr: string, vars: VarStack): unknown {
+  const toks = tokenize(expr);
+  if (toks.length === 0) return undefined;
+  const cursor: Cursor = { toks, pos: 0 };
+  const v = parseOr(cursor, vars);
+  if (cursor.pos !== toks.length) {
+    throw new Error(`表达式多余 token: "${expr}"`);
+  }
+  return v;
+}
+
+/**
+ * 字符串插值：把 "${EXPR}" 替换成 EXPR 求值结果。
+ * 多个 ${} 串联也支持。括号配对识别 —— "${ ${nested} }" 会被当成一个外层
+ * EXPR（内部 ${nested} 文本原样，但表达式里不允许 ${} 语法，所以会报错）。
+ *
+ * 转义：`\$` → 字面 $，跳过插值。
+ */
+export function interpolate(template: string, vars: VarStack): string {
+  let out = '';
+  let i = 0;
+  while (i < template.length) {
+    const c = template[i];
+    if (c === '\\' && template[i + 1] === '$') {
+      out += '$';
+      i += 2;
+      continue;
+    }
+    if (c === '$' && template[i + 1] === '{') {
+      // 找匹配的 '}'
+      let depth = 1;
+      let j = i + 2;
+      while (j < template.length && depth > 0) {
+        if (template[j] === '{') depth++;
+        else if (template[j] === '}') depth--;
+        if (depth > 0) j++;
+      }
+      if (depth !== 0) {
+        // 不匹配；原样输出
+        out += template.slice(i);
+        return out;
+      }
+      const expr = template.slice(i + 2, j);
+      const v = evalExpr(expr, vars);
+      out += stringify(v);
+      i = j + 1;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+function stringify(v: unknown): string {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+/** 递归对对象/数组/字符串做插值；其它原样返回。 */
+export function interpolateDeep<T>(value: T, vars: VarStack): T {
+  if (typeof value === 'string') {
+    return interpolate(value, vars) as unknown as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => interpolateDeep(v, vars)) as unknown as T;
+  }
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      // 注意：key 也插值（loop 里 `hook_${idx}` 这种），但只对字符串 key 有意义
+      const newKey = interpolate(k, vars);
+      out[newKey] = interpolateDeep(v, vars);
+    }
+    return out as unknown as T;
+  }
+  return value;
+}