minimal-agent 0.2.0 → 0.3.1

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

@@ -0,0 +1,369 @@
+/**
+ * ============================================================
+ *  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.js';
+const PUNCT2 = new Set(['==', '!=', '>=', '<=', '&&', '||']);
+const PUNCT1 = new Set(['(', ')', '[', ']', ',', '.', '!', '>', '<']);
+function tokenize(src) {
+    const out = [];
+    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;
+}
+function peek(c) {
+    return c.pos < c.toks.length ? c.toks[c.pos] : null;
+}
+function eat(c) {
+    return c.toks[c.pos++];
+}
+function isPunct(c, v) {
+    const t = peek(c);
+    return !!t && t.kind === 'punct' && t.value === v;
+}
+const BUILTINS = {
+    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, vars) {
+    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, vars) {
+    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, vars) {
+    if (isPunct(c, '!')) {
+        eat(c);
+        return !truthy(parseNot(c, vars));
+    }
+    return parseComparison(c, vars);
+}
+function parseComparison(c, vars) {
+    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 > right;
+            case '<':
+                return left < right;
+            case '>=':
+                return left >= right;
+            case '<=':
+                return left <= right;
+        }
+    }
+    return left;
+}
+function parsePrimary(c, vars) {
+    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 = [];
+        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 = [];
+            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 = 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[next.value] : undefined;
+        }
+        return cur;
+    }
+    throw new Error(`无法解析 token: ${JSON.stringify(t)}`);
+}
+function truthy(v) {
+    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, vars) {
+    const toks = tokenize(expr);
+    if (toks.length === 0)
+        return undefined;
+    const 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, vars) {
+    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) {
+    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(value, vars) {
+    if (typeof value === 'string') {
+        return interpolate(value, vars);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => interpolateDeep(v, vars));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            // 注意：key 也插值（loop 里 `hook_${idx}` 这种），但只对字符串 key 有意义
+            const newKey = interpolate(k, vars);
+            out[newKey] = interpolateDeep(v, vars);
+        }
+        return out;
+    }
+    return value;
+}

package/plugins/workflow-runner/src/index.js

@@ -0,0 +1,216 @@
+/**
+ * ============================================================
+ *  src/workflows/index.ts —— /workflow 与 /workflows 命令的胶水层
+ * ------------------------------------------------------------
+ *  作为 pluginRunner 与 runner 之间的桥：
+ *    - runWorkflowFromCommand：解析 /workflow <name> --input k=v args 调度
+ *    - runWorkflowsList：处理 /workflows 列表展示（yield "text" 事件让 UI 显示）
+ *
+ *  R1 红线：本文件只在 pluginRunner 命中 workflow 模式时才被 import。
+ *  不污染默认 T-A-O-R 路径。
+ * ============================================================
+ */
+import { findWorkflowByName, listWorkflows } from './loader.js';
+import { runWorkflow } from './runner.js';
+/**
+ * 把 "/workflow <name> [pos1 pos2 ...] [--input k=v ...]" 拆成 name + 显式 inputs + 位置参数。
+ * 简单解析器（不依赖第三方）：
+ *   - 第一个非 flag token = name；末尾 ".yaml" / ".yml" 自动剥（便于直接用文件名）
+ *   - 之后所有非 flag token 收进 positional[]，由调用方按 def.inputs 声明顺序映射
+ *   - --input k=v 显式 KV，优先级高于位置参数（同名 input 不会被位置参数覆盖）
+ *   - 不识别其他 flag（保守跳过其后一个 token）
+ */
+export function parseWorkflowArgs(rawArgs) {
+    const tokens = tokenizeArgs(rawArgs);
+    const inputs = {};
+    const positional = [];
+    let name = null;
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === '--input') {
+            const kv = tokens[i + 1];
+            if (!kv)
+                break;
+            const eq = kv.indexOf('=');
+            if (eq > 0) {
+                inputs[kv.slice(0, eq)] = kv.slice(eq + 1);
+            }
+            i++;
+            continue;
+        }
+        if (t.startsWith('--')) {
+            // 未知 flag：跳过其后一个 token（保守地认为它带值）
+            i++;
+            continue;
+        }
+        if (name === null) {
+            name = t.replace(/\.ya?ml$/i, '');
+        }
+        else {
+            positional.push(t);
+        }
+    }
+    return { name, inputs, positional };
+}
+/** 简单 token 化：双引号包裹的整体当一个 token；其它按空白切。 */
+function tokenizeArgs(s) {
+    const out = [];
+    let i = 0;
+    while (i < s.length) {
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        if (i >= s.length)
+            break;
+        if (s[i] === '"' || s[i] === "'") {
+            const q = s[i];
+            i++;
+            let acc = '';
+            while (i < s.length && s[i] !== q) {
+                acc += s[i++];
+            }
+            if (i < s.length)
+                i++;
+            out.push(acc);
+        }
+        else {
+            let acc = '';
+            while (i < s.length && !/\s/.test(s[i])) {
+                acc += s[i++];
+            }
+            out.push(acc);
+        }
+    }
+    return out;
+}
+/**
+ * 把字符串形态的 input 值按 InputDef.type 转成合适的 JS 类型 + 校验。
+ * 校验失败抛 Error，pluginRunner 会把它转成 error event。
+ */
+function coerceInputs(raw, defs) {
+    const out = {};
+    if (!defs)
+        return { ...raw };
+    for (const def of defs) {
+        const rawVal = raw[def.name];
+        if (rawVal === undefined) {
+            if (def.required) {
+                throw new Error(`缺少必填 input: ${def.name}`);
+            }
+            if (def.default !== undefined) {
+                out[def.name] = def.default;
+            }
+            continue;
+        }
+        if (def.type === 'number') {
+            const n = parseFloat(rawVal);
+            if (Number.isNaN(n))
+                throw new Error(`input ${def.name} 必须是数字，收到 "${rawVal}"`);
+            out[def.name] = n;
+        }
+        else if (def.type === 'enum') {
+            if (!def.values?.includes(rawVal)) {
+                throw new Error(`input ${def.name} 必须是 [${def.values?.join(', ')}] 之一，收到 "${rawVal}"`);
+            }
+            out[def.name] = rawVal;
+        }
+        else {
+            out[def.name] = rawVal;
+        }
+    }
+    // 未声明的 input 也透传（让 yaml 里可以引用 ad-hoc 变量）
+    for (const k of Object.keys(raw)) {
+        if (!(k in out))
+            out[k] = raw[k];
+    }
+    return out;
+}
+/** /workflow <name> [pos...] [--input k=v] —— 主入口，由 pluginRunner 调用。 */
+export async function* runWorkflowFromCommand(rawArgs, opts) {
+    const { name, inputs: rawInputs, positional } = parseWorkflowArgs(rawArgs);
+    if (!name) {
+        yield {
+            type: 'error',
+            error: '/workflow 用法: /workflow <name> [val ...] [--input key=val ...]\n输入 /workflows 查看可用工作流。',
+        };
+        return;
+    }
+    const def = await findWorkflowByName(name);
+    if (!def) {
+        yield {
+            type: 'error',
+            error: `未找到 workflow "${name}"。输入 /workflows 查看可用列表。`,
+        };
+        return;
+    }
+    // 位置参数严格按"第 i 个位置参数 ↔ def.inputs[i]"对应。
+    // --input k=v 显式优先：已显式的 input 不被位置参数覆盖（对应的位置参数被丢弃，会 warn）。
+    // 多余的位置参数（超过 def.inputs 数量）也被丢弃（会 warn）。
+    const overriddenByKV = [];
+    if (positional.length > 0 && def.inputs) {
+        const max = Math.min(positional.length, def.inputs.length);
+        for (let i = 0; i < max; i++) {
+            const inputDef = def.inputs[i];
+            if (inputDef.name in rawInputs) {
+                // 已被 --input 占位，位置参数被丢弃
+                if (rawInputs[inputDef.name] !== positional[i]) {
+                    overriddenByKV.push(`${inputDef.name}=${JSON.stringify(rawInputs[inputDef.name])} (位置参数 ${JSON.stringify(positional[i])} 被忽略)`);
+                }
+            }
+            else {
+                rawInputs[inputDef.name] = positional[i];
+            }
+        }
+    }
+    // warn：超量位置参数（用户写多了，提示一下）
+    if (def.inputs && positional.length > def.inputs.length) {
+        const dropped = positional.slice(def.inputs.length);
+        yield {
+            type: 'workflow_warning',
+            message: `⚠ 忽略了 ${dropped.length} 个多余位置参数: ${dropped.map((d) => JSON.stringify(d)).join(' ')}（workflow "${name}" 只声明了 ${def.inputs.length} 个 input）`,
+        };
+    }
+    // warn：位置参数被 --input 覆盖
+    if (overriddenByKV.length > 0) {
+        yield {
+            type: 'workflow_warning',
+            message: `⚠ --input 优先级高于位置参数，以下位置参数被覆盖：${overriddenByKV.join('; ')}`,
+        };
+    }
+    let coerced;
+    try {
+        coerced = coerceInputs(rawInputs, def.inputs);
+    }
+    catch (e) {
+        yield { type: 'error', error: e.message };
+        return;
+    }
+    const ctx = {
+        provider: opts.provider,
+        signal: opts.signal,
+        history: opts.history,
+    };
+    yield* runWorkflow(def, coerced, ctx);
+}
+/** /workflows —— 列出可用 workflow。yield 一条 text 事件让 UI 显示。 */
+export async function* runWorkflowsList() {
+    const list = await listWorkflows();
+    if (list.length === 0) {
+        yield {
+            type: 'text',
+            delta: '当前没有可用工作流。在 cwd/workflows/ 下放 *.yaml 即可（参考 workflows/schema.json 或 docs/workflow-design.md）。\n',
+        };
+        yield { type: 'turn_done' };
+        return;
+    }
+    const lines = ['可用工作流：'];
+    for (const w of list) {
+        lines.push(`  /workflow ${w.name}  —  ${w.description.split('\n')[0].trim()}`);
+    }
+    lines.push('');
+    lines.push('运行示例:');
+    lines.push('  /workflow <name> <val>            位置参数（按 inputs 声明顺序，第一个 input 直接写值）');
+    lines.push('  /workflow <name>.yaml <val>       .yaml 后缀可省');
+    lines.push('  /workflow <name> --input k=v      显式 KV（多 input 或想跳过中间 input 时用）');
+    yield { type: 'text', delta: lines.join('\n') + '\n' };
+    yield { type: 'turn_done' };
+}