minimal-agent 0.2.0 → 0.3.1

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

@@ -1,193 +0,0 @@
-/**
- * ============================================================
- *  src/workflows/loader.ts —— workflow yaml 双源加载 + 最小校验
- * ------------------------------------------------------------
- *  - 扫描 cwd/workflows/ 与 packageRoot/workflows/（cwd 优先，复用
- *    getResourceSearchPaths 契约）
- *  - 一个坏 yaml 不应拖累其它工作流（catch 单文件错误，继续扫描）
- *  - 目录不存在 / 为空 → 静默返回 []（默认 T-A-O-R 不受影响）
- *
- *  P0 不引 AJV；下面手写 ≤80 行的最小校验器，只挡死硬性错误：
- *    - name / description / steps 必填且类型正确
- *    - steps 非空
- *    - 每个 step 必须有且只有一个动作字段（tool / skill / llm / type）
- *
- *  P1 切 AJV 做完整 schema。
- * ============================================================
- */
-
-import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-
-import { parse as parseYamlLib } from 'yaml';
-
-import { getResourceSearchPaths } from '../../../src/plugin-sdk.ts';
-import type { StepDef, WorkflowDef } from './types.ts';
-
-export class WorkflowLoadError extends Error {
-  constructor(message: string, public readonly file?: string) {
-    super(message);
-    this.name = 'WorkflowLoadError';
-  }
-}
-
-/**
- * 扫描双源目录，返回所有 *.yaml / *.yml 解析后的 workflow。
- * 永远不抛；坏文件 console.warn 并跳过。
- */
-export async function listWorkflows(): Promise<WorkflowDef[]> {
-  const out: WorkflowDef[] = [];
-  const seen = new Set<string>();
-  const roots = getResourceSearchPaths('workflows', import.meta.url);
-
-  for (const root of roots) {
-    let entries: string[];
-    try {
-      entries = await readdir(root);
-    } catch {
-      continue;
-    }
-    for (const f of entries) {
-      if (!f.endsWith('.yaml') && !f.endsWith('.yml')) continue;
-      const full = join(root, f);
-      try {
-        const def = await parseWorkflowFile(full);
-        if (!seen.has(def.name)) {
-          seen.add(def.name);
-          out.push(def);
-        }
-      } catch (e) {
-        // eslint-disable-next-line no-console
-        console.warn(`[workflows] 忽略损坏的 yaml ${full}: ${(e as Error).message}`);
-      }
-    }
-  }
-  return out;
-}
-
-/** 按 name 查找。找不到返回 null —— 调用方决定如何提示用户。 */
-export async function findWorkflowByName(name: string): Promise<WorkflowDef | null> {
-  const all = await listWorkflows();
-  return all.find((w) => w.name === name) ?? null;
-}
-
-/** 读单个 yaml 文件 → 解析 → 校验。失败抛 WorkflowLoadError。 */
-export async function parseWorkflowFile(file: string): Promise<WorkflowDef> {
-  let raw: string;
-  try {
-    raw = await readFile(file, 'utf8');
-  } catch (e) {
-    throw new WorkflowLoadError(`无法读取 ${file}: ${(e as Error).message}`, file);
-  }
-  let data: unknown;
-  try {
-    data = parseYamlLib(raw);
-  } catch (e) {
-    throw new WorkflowLoadError(`yaml 语法错误: ${(e as Error).message}`, file);
-  }
-  if (!data || typeof data !== 'object') {
-    throw new WorkflowLoadError('yaml 根节点必须是对象', file);
-  }
-  validate(data as Record<string, unknown>, file);
-  const def = data as WorkflowDef;
-  def.__source = file;
-  return def;
-}
-
-// ---------------- 手写最小校验 ----------------
-
-function validate(obj: Record<string, unknown>, file: string): void {
-  if (typeof obj.name !== 'string' || obj.name.length === 0) {
-    throw new WorkflowLoadError("缺少必填字段 'name'（string）", file);
-  }
-  if (typeof obj.description !== 'string' || obj.description.length === 0) {
-    throw new WorkflowLoadError("缺少必填字段 'description'（string）", file);
-  }
-  if (!Array.isArray(obj.steps) || obj.steps.length === 0) {
-    throw new WorkflowLoadError("缺少必填字段 'steps' 或为空数组", file);
-  }
-  validateSteps(obj.steps as unknown[], file, '');
-  if (obj.inputs !== undefined) {
-    if (!Array.isArray(obj.inputs)) {
-      throw new WorkflowLoadError("'inputs' 必须是数组", file);
-    }
-    for (const [i, item] of (obj.inputs as unknown[]).entries()) {
-      if (!item || typeof item !== 'object') {
-        throw new WorkflowLoadError(`inputs[${i}] 必须是对象`, file);
-      }
-      const r = item as Record<string, unknown>;
-      if (typeof r.name !== 'string' || r.name.length === 0) {
-        throw new WorkflowLoadError(`inputs[${i}].name 必填`, file);
-      }
-      if (r.type !== undefined && r.type !== 'string' && r.type !== 'number' && r.type !== 'enum') {
-        throw new WorkflowLoadError(`inputs[${i}].type 必须是 string/number/enum`, file);
-      }
-      if (r.type === 'enum' && (!Array.isArray(r.values) || r.values.length === 0)) {
-        throw new WorkflowLoadError(`inputs[${i}].values 必填（type=enum 时）`, file);
-      }
-    }
-  }
-}
-
-function validateSteps(steps: unknown[], file: string, pathPrefix: string): void {
-  const seenIds = new Set<string>();
-  for (const [i, item] of steps.entries()) {
-    const p = pathPrefix ? `${pathPrefix}.steps[${i}]` : `steps[${i}]`;
-    if (!item || typeof item !== 'object') {
-      throw new WorkflowLoadError(`${p} 必须是对象`, file);
-    }
-    const s = item as Record<string, unknown>;
-    if (typeof s.id !== 'string' || s.id.length === 0) {
-      throw new WorkflowLoadError(`${p}.id 必填`, file);
-    }
-    // id 唯一仅在同级 steps 数组内强制
-    if (seenIds.has(s.id)) {
-      throw new WorkflowLoadError(`${p}.id "${s.id}" 在当前 steps 列表中重复`, file);
-    }
-    seenIds.add(s.id);
-
-    // 动作字段恰好一个
-    const actionFields: (keyof StepDef)[] = ['tool', 'skill', 'llm', 'type'];
-    const present = actionFields.filter((k) => s[k] !== undefined);
-    if (present.length === 0) {
-      throw new WorkflowLoadError(
-        `${p} 必须有以下字段之一: tool / skill / llm / type`,
-        file,
-      );
-    }
-    if (present.length > 1) {
-      throw new WorkflowLoadError(
-        `${p} 同时设置了 ${present.join(', ')}；只允许其中一个`,
-        file,
-      );
-    }
-
-    // 控制流字段一致性
-    if (s.type === 'branch' && s.condition === undefined) {
-      throw new WorkflowLoadError(`${p} type=branch 必须带 'condition'`, file);
-    }
-    if (s.type === 'loop') {
-      if (s.over === undefined) throw new WorkflowLoadError(`${p} type=loop 必须带 'over'`, file);
-      if (typeof s.as !== 'string' || s.as.length === 0) {
-        throw new WorkflowLoadError(`${p} type=loop 必须带 'as'`, file);
-      }
-      if (!Array.isArray(s.do)) {
-        throw new WorkflowLoadError(`${p} type=loop 必须带 'do' 数组`, file);
-      }
-      validateSteps(s.do as unknown[], file, `${p}.do`);
-    }
-    if (s.type === 'assert' && s.condition === undefined) {
-      throw new WorkflowLoadError(`${p} type=assert 必须带 'condition'`, file);
-    }
-    if (s.type === 'branch') {
-      if (s.then !== undefined && !Array.isArray(s.then)) {
-        throw new WorkflowLoadError(`${p}.then 必须是数组`, file);
-      }
-      if (s.else !== undefined && !Array.isArray(s.else)) {
-        throw new WorkflowLoadError(`${p}.else 必须是数组`, file);
-      }
-      if (Array.isArray(s.then)) validateSteps(s.then as unknown[], file, `${p}.then`);
-      if (Array.isArray(s.else)) validateSteps(s.else as unknown[], file, `${p}.else`);
-    }
-  }
-}

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

@@ -1,313 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/runner.ts —— workflow 顺序执行器
- * ------------------------------------------------------------
- *  AsyncGenerator，按 yaml.steps[] 顺序执行：
- *    - when: 不满足 → yield workflow_step_skipped
- *    - 命中动作字段 → 调对应 step executor
- *    - capture: 把 result.raw 上的字段绑到 VarStack
- *    - onError: halt（默认）→ yield error 后 return；continue → 记录后跳过
- *    - 信号 abort → yield interrupted 后 return
- *
- *  支持的 step kind（loader 已校验）：
- *    - tool / llm / assert    —— 原子动作（execXxxStep 返回 StepResult）
- *    - skill                  —— 迷你 ReAct 子循环（透传子事件 + 累计 text）
- *    - branch / loop / pause  —— 控制流，直接在 runSteps 内处理（不走 executor）
- *
- *  控制流嵌套通过 runSteps 递归实现：branch.then/else / loop.do 子数组
- *  是 StepDef[]，调用方语义与顶层 def.steps 一致；变量栈用 VarStack.push/pop
- *  在 loop 迭代间隔离 `${as}` / `${as}_idx`。
- * ============================================================
- */
-
-import { getWorkingDir, type LoopEvent } from '../../../src/plugin-sdk.ts';
-import { evalExpr, interpolate } from './expressions.ts';
-import { execAssertStep } from './stepExecutors/assert.ts';
-import { execLlmStep } from './stepExecutors/llm.ts';
-import { execSkillStep } from './stepExecutors/skill.ts';
-import { execToolStep } from './stepExecutors/tool.ts';
-import type {
-  RunContext,
-  StepDef,
-  StepKind,
-  StepResult,
-  WorkflowDef,
-  WorkflowEvent,
-} from './types.ts';
-import { VarStack } from './types.ts';
-import { WorkflowState } from './workflowState.ts';
-
-function stepKind(step: StepDef): StepKind {
-  if (step.type) return step.type;
-  if (step.tool) return 'tool';
-  if (step.skill) return 'skill';
-  if (step.llm) return 'llm';
-  return 'assert'; // 不会到这里（loader 已校验），兜底
-}
-
-function readPath(root: Record<string, unknown>, path: string): unknown {
-  const parts = path.split('.');
-  let cur: unknown = root;
-  for (const p of parts) {
-    if (cur == null || typeof cur !== 'object') return undefined;
-    cur = (cur as Record<string, unknown>)[p];
-  }
-  return cur;
-}
-
-function bindCapture(
-  captureMap: Record<string, string>,
-  result: StepResult,
-  vars: VarStack,
-): void {
-  for (const [resultField, varName] of Object.entries(captureMap)) {
-    const value = resultField.includes('.')
-      ? readPath(result.raw, resultField)
-      : result.raw[resultField];
-    vars.set(varName, value);
-  }
-}
-
-/**
- * 分发"动作"型 step（tool / llm / skill / assert）到对应 executor。
- * 控制流 step（branch / loop / pause）由 runSteps 直接处理，不走这里。
- */
-async function* dispatchActionStep(
-  step: StepDef,
-  vars: VarStack,
-  ctx: RunContext,
-): AsyncGenerator<LoopEvent, StepResult, void> {
-  if (step.type === 'assert') return execAssertStep(step, vars);
-  if (step.tool) return await execToolStep(step, vars, ctx);
-  if (step.llm) return await execLlmStep(step, vars, ctx);
-  if (step.skill) return yield* execSkillStep(step, vars, ctx);
-  throw new Error(`step ${step.id}: 无可执行字段（tool/llm/skill/assert）`);
-}
-
-/**
- * 递归执行 steps[]。返回 true 表示该 block 已 halt（上游应中止）。
- *
- * yields 混合事件：WorkflowEvent + LoopEvent（skill 子循环转发 / error / interrupted）。
- * index/total 字段相对**当前 block**，嵌套 block 自有计数（branch.then 内 3 步就报 total=3）。
- */
-async function* runSteps(
-  steps: StepDef[],
-  vars: VarStack,
-  ctx: RunContext,
-  state: WorkflowState,
-): AsyncGenerator<WorkflowEvent | LoopEvent, boolean, void> {
-  for (let i = 0; i < steps.length; i++) {
-    const step = steps[i];
-    if (ctx.signal?.aborted) {
-      yield { type: 'interrupted' };
-      return true;
-    }
-
-    // when 条件
-    if (step.when) {
-      let pass = false;
-      try {
-        pass = Boolean(evalExpr(interpolate(step.when, vars), vars));
-      } catch (e) {
-        const errMsg = `when 表达式错误: ${(e as Error).message}`;
-        yield {
-          type: 'workflow_step_end',
-          id: step.id,
-          ok: false,
-          error: errMsg,
-        };
-        yield {
-          type: 'error',
-          error: `Workflow halted at step "${step.id}": ${errMsg}`,
-        };
-        return true;
-      }
-      if (!pass) {
-        yield {
-          type: 'workflow_step_skipped',
-          id: step.id,
-          reason: 'when=false',
-        };
-        await state.appendProgress(`- ${step.id} skipped (when=false)`);
-        continue;
-      }
-    }
-
-    const kind = stepKind(step);
-    yield {
-      type: 'workflow_step_start',
-      id: step.id,
-      kind,
-      index: i,
-      total: steps.length,
-    };
-
-    // ---------- 控制流：branch ----------
-    if (step.type === 'branch') {
-      let cond = false;
-      try {
-        cond = Boolean(evalExpr(interpolate(step.condition ?? 'false', vars), vars));
-      } catch (e) {
-        const errMsg = `branch 条件错误: ${(e as Error).message}`;
-        await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-        yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-        yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-        return true;
-      }
-      const branch = cond ? step.then : step.else;
-      if (Array.isArray(branch) && branch.length > 0) {
-        const childHalted = yield* runSteps(branch, vars, ctx, state);
-        if (childHalted) return true;
-      }
-      await state.appendProgress(`✓ ${step.id} (branch=${cond})`);
-      await state.writeVars(vars.snapshot());
-      yield {
-        type: 'workflow_step_end',
-        id: step.id,
-        ok: true,
-        output: `branch=${cond}`,
-      };
-      continue;
-    }
-
-    // ---------- 控制流：loop ----------
-    if (step.type === 'loop') {
-      let arr: unknown;
-      try {
-        arr = evalExpr(interpolate(step.over ?? '[]', vars), vars);
-      } catch (e) {
-        const errMsg = `loop over 表达式错误: ${(e as Error).message}`;
-        await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-        yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-        yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-        return true;
-      }
-      if (!Array.isArray(arr)) {
-        const errMsg = `loop over 必须求值为数组，得到 ${typeof arr}`;
-        await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-        yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-        yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-        return true;
-      }
-      const asName = step.as ?? 'item';
-      let iterCount = 0;
-      for (let idx = 0; idx < arr.length; idx++) {
-        if (ctx.signal?.aborted) {
-          yield { type: 'interrupted' };
-          return true;
-        }
-        vars.push();
-        vars.set(asName, arr[idx]);
-        vars.set(`${asName}_idx`, idx);
-        const childHalted = yield* runSteps(step.do ?? [], vars, ctx, state);
-        vars.pop();
-        if (childHalted) return true;
-        iterCount++;
-      }
-      await state.appendProgress(`✓ ${step.id} (loop ×${iterCount})`);
-      await state.writeVars(vars.snapshot());
-      yield {
-        type: 'workflow_step_end',
-        id: step.id,
-        ok: true,
-        output: `loop ${iterCount} 次`,
-      };
-      continue;
-    }
-
-    // ---------- 控制流：pause ----------
-    //
-    // 非交互模式（CLI -p / 测试）下无法真的暂停等待人工，直接当成 skipped。
-    // 交互模式（TUI）需要 UI 层接住 step_skipped 把 reason 渲染出来 —— P0 已
-    // 走通这条 UI 路径。step.prompt 用于把"暂停理由"传给上层呈现。
-    if (step.type === 'pause') {
-      const msg = step.prompt
-        ? interpolate(step.prompt, vars)
-        : 'pause（非交互模式直接跳过）';
-      await state.appendProgress(`- ${step.id} pause: ${msg}`);
-      yield {
-        type: 'workflow_step_skipped',
-        id: step.id,
-        reason: `pause: ${msg}`,
-      };
-      yield {
-        type: 'workflow_step_end',
-        id: step.id,
-        ok: true,
-        output: 'paused (skipped in non-interactive mode)',
-      };
-      continue;
-    }
-
-    // ---------- 普通动作 step：tool / llm / skill / assert ----------
-    try {
-      const result = yield* dispatchActionStep(step, vars, ctx);
-      if (step.capture) bindCapture(step.capture, result, vars);
-      await state.appendProgress(`✓ ${step.id} (${kind})`);
-      await state.writeVars(vars.snapshot());
-      yield {
-        type: 'workflow_step_end',
-        id: step.id,
-        ok: true,
-        output: result.preview,
-      };
-    } catch (e) {
-      const errMsg = (e as Error).message ?? String(e);
-      await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-      if (step.onError === 'continue') {
-        yield {
-          type: 'workflow_step_end',
-          id: step.id,
-          ok: false,
-          error: errMsg,
-        };
-        continue;
-      }
-      yield {
-        type: 'workflow_step_end',
-        id: step.id,
-        ok: false,
-        error: errMsg,
-      };
-      yield {
-        type: 'error',
-        error: `Workflow halted at step "${step.id}": ${errMsg}`,
-      };
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * 运行一个 workflow。
- *
- * yields 混合事件：本地 WorkflowEvent（workflow_* 系列，UI 静默忽略不渲染）
- * + 通用 LoopEvent（error / interrupted 等，UI 识别并渲染）。
- * 经 plugin.ts -> pluginRunner 透传给 UI；workflow_* 由 PluginEvent 开放契约承载。
- */
-export async function* runWorkflow(
-  def: WorkflowDef,
-  inputs: Record<string, unknown>,
-  ctx: RunContext,
-): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
-  const vars = new VarStack();
-  vars.setGlobal('inputs', inputs);
-
-  const state = new WorkflowState(getWorkingDir());
-  await state.init(def.name, inputs);
-
-  yield {
-    type: 'workflow_start',
-    name: def.name,
-    totalSteps: def.steps.length,
-  };
-
-  try {
-    const halted = yield* runSteps(def.steps, vars, ctx, state);
-    if (halted) return;
-    yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
-  } finally {
-    await state.cleanup();
-  }
-}

package/plugins/workflow-runner/src/stepExecutors/assert.ts

@@ -1,30 +0,0 @@
-/**
- * ============================================================
- *  src/workflows/stepExecutors/assert.ts —— assert step 执行
- * ------------------------------------------------------------
- *  evalExpr(condition) → 真值通过；假值抛错（带 onFail 自定义信息）。
- * ============================================================
- */
-
-import { evalExpr, interpolate } from '../expressions.ts';
-import type { StepDef, StepResult, VarStack } from '../types.ts';
-
-export function execAssertStep(step: StepDef, vars: VarStack): StepResult {
-  if (typeof step.condition !== 'string') {
-    throw new Error(`step ${step.id}: assert 缺少 condition`);
-  }
-  let ok: boolean;
-  try {
-    const expanded = interpolate(step.condition, vars);
-    ok = Boolean(evalExpr(expanded, vars));
-  } catch (e) {
-    throw new Error(`assert 表达式求值失败: ${(e as Error).message}`);
-  }
-  if (!ok) {
-    const msg = step.onFail
-      ? interpolate(step.onFail, vars)
-      : `assertion failed: ${step.condition}`;
-    throw new Error(msg);
-  }
-  return { raw: { ok: true }, preview: 'assert passed' };
-}

package/plugins/workflow-runner/src/stepExecutors/llm.ts

@@ -1,54 +0,0 @@
-/**
- * ============================================================
- *  src/workflows/stepExecutors/llm.ts —— llm step 执行
- * ------------------------------------------------------------
- *  单轮 LLM 生成。关键设计：
- *    - tools: [] —— 不开任何工具（工具调用应该写成 tool: step）
- *    - 自带独立 system + user 两条消息，不污染主 history
- *    - 流式累积文本（reasoning 字段在这里忽略；只关心最终文本）
- *
- *  capture：
- *    - `{ text: var_name }` 绑生成文本
- *    - `{ result: var_name }` 同义
- * ============================================================
- */
-
-import { chat, type Message } from '../../../../src/plugin-sdk.ts';
-import { interpolate } from '../expressions.ts';
-import type { RunContext, StepDef, StepResult, VarStack } from '../types.ts';
-
-const LLM_STEP_SYSTEM =
-  '你正在被一个 workflow 调用。只输出本步骤要求的内容本身，不要寒暄、不要列要求复述、不要工具调用语法。';
-
-export async function execLlmStep(
-  step: StepDef,
-  vars: VarStack,
-  ctx: RunContext,
-): Promise<StepResult> {
-  if (typeof step.llm !== 'string') throw new Error(`step ${step.id}: 缺少 llm 字段`);
-  const prompt = interpolate(step.llm, vars);
-
-  const messages: Message[] = [
-    { role: 'system', content: LLM_STEP_SYSTEM },
-    { role: 'user', content: prompt },
-  ];
-
-  let text = '';
-  for await (const ev of chat({
-    provider: ctx.provider,
-    messages,
-    tools: [],
-    signal: ctx.signal,
-  })) {
-    if (ev.type === 'text_delta') text += ev.delta;
-    if (ev.type === 'done' && ev.stopReason === 'aborted') {
-      throw new Error('用户中断');
-    }
-  }
-
-  const trimmed = text.trim();
-  return {
-    raw: { text: trimmed, result: trimmed },
-    preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,
-  };
-}