minimal-agent 0.1.9 → 0.2.0

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

@@ -0,0 +1,30 @@
+/**
+ * ============================================================
+ *  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

@@ -0,0 +1,54 @@
+/**
+ * ============================================================
+ *  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,
+  };
+}

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

@@ -0,0 +1,115 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill step 执行
+ * ------------------------------------------------------------
+ *  把一个具名 skill（skills/<name>/SKILL.md）当作"迷你 ReAct 子循环"
+ *  跑一次：复用 src/loop.ts::runQuery，让模型在子 history 内 T-A-O-R。
+ *
+ *  实现要点：
+ *    - 双源查找：cwd/skills/<name>/SKILL.md 优先，packageRoot/skills/ fallback；
+ *      支持按目录名 or 按 frontmatter::name 匹配
+ *    - 剥掉 frontmatter，body 作 system 指令；step.input 插值后作为 user
+ *    - 子 history 与外层 ctx.history 隔离，避免污染主对话
+ *    - 流式转发：runQuery yield 的事件直接 yield 出去（让 UI 看到子循环进度）
+ *    - 收集 text 事件累计为 raw.text，供 capture 绑变量使用
+ *    - maxTurns 可在 step 里覆盖，默认走 runQuery 自带（50）
+ *
+ *  capture：{ text: var_name } / { result: var_name }
+ * ============================================================
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import {
+  getResourceSearchPaths,
+  runQuery,
+  type LoopEvent,
+  type Message,
+} from '../../../../src/plugin-sdk.ts';
+import { interpolate } from '../expressions.ts';
+import type { RunContext, StepDef, StepResult, VarStack } from '../types.ts';
+
+function stripFrontmatter(content: string): string {
+  return content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}
+
+function parseFrontmatterName(content: string): string | null {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const nm = m[1].match(/^name:\s*(.+)$/m);
+  if (!nm) return null;
+  return nm[1].trim().replace(/^["']|["']$/g, '');
+}
+
+async function findSkillFile(skillName: string): Promise<string | null> {
+  const roots = getResourceSearchPaths('skills', import.meta.url);
+  for (const root of roots) {
+    let entries: { name: string; isDirectory: () => boolean }[];
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const skillFile = join(root, e.name, 'SKILL.md');
+      if (e.name === skillName) return skillFile;
+      try {
+        const md = await readFile(skillFile, 'utf8');
+        if (parseFrontmatterName(md) === skillName) return skillFile;
+      } catch {
+        // 该子目录无 SKILL.md，跳过
+      }
+    }
+  }
+  return null;
+}
+
+export async function* execSkillStep(
+  step: StepDef,
+  vars: VarStack,
+  ctx: RunContext,
+): AsyncGenerator<LoopEvent, StepResult, void> {
+  if (!step.skill) throw new Error(`step ${step.id}: 缺少 skill 字段`);
+  const skillName = interpolate(step.skill, vars);
+
+  const skillFile = await findSkillFile(skillName);
+  if (!skillFile) {
+    throw new Error(
+      `step ${step.id}: 未找到 skill "${skillName}"（cwd/skills/ 与 packageRoot/skills/ 双源均未命中）`,
+    );
+  }
+  const md = await readFile(skillFile, 'utf8');
+  const body = stripFrontmatter(md).trim();
+
+  const userInput = step.input
+    ? interpolate(step.input, vars)
+    : `请按 SKILL "${skillName}" 的指示完成任务。`;
+
+  const subHistory: Message[] = [
+    {
+      role: 'system',
+      content: `下面是要遵循的 SKILL 指示（来源：${skillFile}）：\n\n${body}`,
+    },
+  ];
+
+  let text = '';
+  for await (const ev of runQuery(userInput, {
+    provider: ctx.provider,
+    history: subHistory,
+    signal: ctx.signal,
+    maxTurns: step.maxTurns,
+  })) {
+    if (ev.type === 'text') text += ev.delta;
+    if (ev.type === 'interrupted') throw new Error('用户中断');
+    if (ev.type === 'error') throw new Error(ev.error);
+    yield ev;
+  }
+
+  const trimmed = text.trim();
+  return {
+    raw: { text: trimmed, result: trimmed },
+    preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,
+  };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * ============================================================
+ *  src/workflows/stepExecutors/tool.ts —— tool step 执行
+ * ------------------------------------------------------------
+ *  把 step.args 递归 ${var} 插值后 JSON.stringify，转发到 executeTool。
+ *  失败（ok=false）抛 Error，让 runner 走 onError 处理。
+ *
+ *  capture 字段（支持点路径）：
+ *    - `{ content: var_name }`      绑 ToolResult.content（工具回执文本）
+ *    - `{ result: var_name }`       同义，给"无结构化字段"工具用
+ *    - `{ args.content: var_name }` 绑插值后传给工具的入参（如真正写入的内容）
+ *    - `{ args.<任意字段>: var_name }` 绑入参的具名字段
+ *    P1 可扩展按工具特定字段（如 Read 的 fileSize）。
+ * ============================================================
+ */
+
+import { executeTool, getToolByName } from '../../../../src/plugin-sdk.ts';
+import { interpolateDeep } from '../expressions.ts';
+import type { RunContext, StepDef, StepResult, VarStack } from '../types.ts';
+
+export async function execToolStep(
+  step: StepDef,
+  vars: VarStack,
+  ctx: RunContext,
+): Promise<StepResult> {
+  if (!step.tool) throw new Error(`step ${step.id}: 缺少 tool 字段`);
+  const tool = getToolByName(step.tool);
+  if (!tool) throw new Error(`step ${step.id}: 未知 tool "${step.tool}"`);
+
+  const args = interpolateDeep(step.args ?? {}, vars);
+  const argsJson = JSON.stringify(args);
+  const result = await executeTool(tool.name, argsJson, ctx.signal);
+  if (!result.ok) {
+    throw new Error(result.error);
+  }
+  const content = result.content;
+  return {
+    raw: { content, result: content, args },
+    preview: content.length > 200 ? `${content.slice(0, 200)}...` : content,
+  };
+}

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

@@ -0,0 +1,183 @@
+/**
+ * ============================================================
+ *  src/workflows/types.ts —— workflow runner 核心类型
+ * ------------------------------------------------------------
+ *  ralph-loop 让 LLM 自规划；workflow 反过来 —— 外层确定性 step 列表
+ *  驱动执行，LLM 只在 llm: / skill: 节点出场。本文件定义 YAML 解析
+ *  后的内存形态（WorkflowDef / StepDef），以及运行时上下文（VarStack /
+ *  RunContext）和 UI 事件（WorkflowEvent）。
+ *
+ *  与 src/types.ts 关系：WorkflowEvent 是插件**私有**事件，结构上满足
+ *  framework 的 PluginEvent 开放契约（type: string + 任意 payload），
+ *  经 plugin.ts -> pluginRunner 原样透传给 UI；UI 不识别即静默忽略。
+ *  src/types.ts 的 LoopEvent union **不**包含 workflow_*，框架零插件耦合。
+ * ============================================================
+ */
+
+import type { Message, Provider } from '../../../src/plugin-sdk.ts';
+
+// ---------------- 1. Workflow / Step 定义 ----------------
+
+export type InputType = 'string' | 'number' | 'enum';
+
+export interface InputDef {
+  name: string;
+  type: InputType;
+  required?: boolean;
+  default?: unknown;
+  /** type=enum 时必填 */
+  values?: string[];
+  description?: string;
+}
+
+export type StepKind = 'tool' | 'llm' | 'skill' | 'assert' | 'branch' | 'loop' | 'pause';
+
+/**
+ * StepDef 是 YAML 里 steps[] 元素直接反序列化的形态。
+ *
+ * 动作字段四选一（互斥优先级 type > tool > skill > llm）：
+ *   - tool: 调原子工具
+ *   - skill: 迷你 ReAct 子循环（P1）
+ *   - llm:  单轮 LLM 生成（不开工具）
+ *   - type: 控制流（assert / branch / loop / pause）
+ *
+ * 其它字段按 step 类型选择性使用，未用到的字段静默忽略。
+ */
+export interface StepDef {
+  id: string;
+  tool?: string;
+  skill?: string;
+  llm?: string;
+  type?: 'assert' | 'branch' | 'loop' | 'pause';
+
+  args?: Record<string, unknown>;
+  input?: string;
+  capture?: Record<string, string>;
+  when?: string;
+  onError?: 'halt' | 'continue';
+  maxTurns?: number;
+
+  condition?: string;
+  onFail?: string;
+  then?: StepDef[];
+  else?: StepDef[];
+  over?: string;
+  as?: string;
+  do?: StepDef[];
+
+  prompt?: string;
+}
+
+export interface WorkflowDef {
+  name: string;
+  description: string;
+  version?: string;
+  inputs?: InputDef[];
+  steps: StepDef[];
+  /** 编辑器布局信息；runner 严格忽略 */
+  __meta?: unknown;
+  /** loader 写入：yaml 来源（cwd / packageRoot），便于排错 */
+  __source?: string;
+}
+
+// ---------------- 2. 变量栈（loop scope 用） ----------------
+
+/**
+ * 简单的多帧变量栈：
+ *   - 最外层（frame 0）放 inputs + 全局变量
+ *   - 进入 loop 时 push() 新帧，存当前迭代的 as / as_idx
+ *   - 退出 loop 时 pop()
+ *
+ * get(key) 从栈顶往下找第一个匹配的 frame，类似 JS 的 lexical scope。
+ */
+export class VarStack {
+  private frames: Record<string, unknown>[] = [{}];
+
+  set(key: string, val: unknown): void {
+    this.frames[this.frames.length - 1][key] = val;
+  }
+
+  /** 写到栈底（root frame），用于 inputs / 全局常量 */
+  setGlobal(key: string, val: unknown): void {
+    this.frames[0][key] = val;
+  }
+
+  get(key: string): unknown {
+    for (let i = this.frames.length - 1; i >= 0; i--) {
+      if (key in this.frames[i]) return this.frames[i][key];
+    }
+    return undefined;
+  }
+
+  has(key: string): boolean {
+    for (let i = this.frames.length - 1; i >= 0; i--) {
+      if (key in this.frames[i]) return true;
+    }
+    return false;
+  }
+
+  push(): void {
+    this.frames.push({});
+  }
+
+  pop(): void {
+    if (this.frames.length > 1) this.frames.pop();
+  }
+
+  /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件 */
+  snapshot(): Record<string, unknown> {
+    return Object.assign({}, ...this.frames);
+  }
+}
+
+// ---------------- 3. 运行上下文 ----------------
+
+/**
+ * runner 内部传递的运行时上下文。
+ *
+ * 设计：不让 step executors 直接拿 PluginRunnerOptions，避免把"插件运行机制"
+ * 暴露到 workflow 层。RunContext 只暴露 executors 真正需要的东西。
+ */
+export interface RunContext {
+  provider: Provider;
+  signal?: AbortSignal;
+  /**
+   * 外部 history（来自 pluginRunner.runWithPlugins 的 baseHistory）。
+   * workflow runner 不直接 push 到这里；step executors 只读。
+   */
+  history: Message[];
+}
+
+// ---------------- 4. step 执行结果 ----------------
+
+/**
+ * 每个 step executor 的返回。capture 字段会从 raw 上按 capture map 取值。
+ *
+ *   - raw: 完整结构化结果，给 capture 用
+ *   - preview: 给 UI 展示的短摘要（≤200 char）
+ */
+export interface StepResult {
+  raw: Record<string, unknown>;
+  preview: string;
+}
+
+// ---------------- 5. workflow 事件（独立类型，便于 step executors 直接 yield） ----------------
+
+export type WorkflowEvent =
+  | { type: 'workflow_start'; name: string; totalSteps: number }
+  | {
+      type: 'workflow_step_start';
+      id: string;
+      kind: StepKind;
+      index: number;
+      total: number;
+    }
+  | {
+      type: 'workflow_step_end';
+      id: string;
+      ok: boolean;
+      output?: string;
+      error?: string;
+    }
+  | { type: 'workflow_step_skipped'; id: string; reason: string }
+  | { type: 'workflow_done'; name: string; vars: Record<string, unknown> };

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

@@ -0,0 +1,65 @@
+/**
+ * ============================================================
+ *  src/workflows/workflowState.ts —— workflow 运行状态持久化
+ * ------------------------------------------------------------
+ *  与 GoalState 类似的轻量目录模型，但只用于 debug / 中断恢复（P0 不实现
+ *  恢复，只写出现场）。目录结构：
+ *
+ *    <cwd>/.minimal-agent-workflow/
+ *      ├── current.json    # { name, startedAt }
+ *      ├── inputs.json     # 用户传入的 inputs 快照
+ *      ├── vars.json       # 最后一次成功 step 后的 VarStack.snapshot()
+ *      └── progress.md     # 时间戳追加的 step 完成日志
+ *
+ *  init() 进 workflow 前 reset 一次；cleanup() 在 finally 把文件删掉
+ *  + rmdir（保持 /new 扫描 .minimal-agent-* 子目录的语义一致）。
+ *
+ *  与 GoalState 的核心区别：workflow 不需要 PHASE / completion / learnings 文件，
+ *  因为执行流程是确定性的，没有 LLM 自规划过程。
+ * ============================================================
+ */
+
+import { mkdir, writeFile, appendFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const STATE_DIR = '.minimal-agent-workflow';
+
+export class WorkflowState {
+  readonly dir: string;
+  constructor(workingDir: string) {
+    this.dir = join(workingDir, STATE_DIR);
+  }
+
+  async init(name: string, inputs: Record<string, unknown>): Promise<void> {
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(
+      join(this.dir, 'current.json'),
+      JSON.stringify({ name, startedAt: new Date().toISOString() }, null, 2),
+      'utf8',
+    );
+    await writeFile(
+      join(this.dir, 'inputs.json'),
+      JSON.stringify(inputs, null, 2),
+      'utf8',
+    );
+    await writeFile(join(this.dir, 'progress.md'), `# ${name}\n\n`, 'utf8');
+  }
+
+  async appendProgress(line: string): Promise<void> {
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    await appendFile(join(this.dir, 'progress.md'), `- ${ts} ${line}\n`, 'utf8').catch(() => {});
+  }
+
+  async writeVars(snapshot: Record<string, unknown>): Promise<void> {
+    await writeFile(
+      join(this.dir, 'vars.json'),
+      JSON.stringify(snapshot, null, 2),
+      'utf8',
+    ).catch(() => {});
+  }
+
+  async cleanup(): Promise<void> {
+    await rm(this.dir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/plugins/workflow-runner/test/cli.e2e.test.ts

@@ -0,0 +1,114 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/test/cli.e2e.test.ts
+ * ------------------------------------------------------------
+ *  最外层 CLI 端到端：拉子进程跑 `bun src/main.tsx -p "/workflow ..."`,
+ *  验证 stdout / stderr / 退出码 / 文件副作用 全链路。
+ *
+ *  覆盖 3 个用例：
+ *    1. golden path：/workflow cli-e2e --input topic=world → exit 0 + 文件落盘
+ *    2. /workflows 列出 cli-e2e
+ *    3. 缺必填 input → exit 1 + 错误信息含 "topic"
+ *
+ *  fake provider env：workflow 是 tool-only，永不调 API；fake env 仅满足
+ *  main.tsx 的 provider 配置校验。
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const REPO_ROOT = resolve(import.meta.dir, '..', '..', '..');
+const FIXTURE = join(import.meta.dir, 'fixtures', 'cli-e2e.yaml');
+
+const SPAWN_TIMEOUT = 60_000;
+
+interface SpawnResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+async function spawnMain(promptArg: string, cwd: string): Promise<SpawnResult> {
+  const proc = Bun.spawn(
+    ['bun', 'src/main.tsx', '-d', cwd, '-p', promptArg],
+    {
+      cwd: REPO_ROOT,
+      env: {
+        ...process.env,
+        MINIMAL_AGENT_BASE_URL: 'http://fake.invalid',
+        MINIMAL_AGENT_API_KEY: 'fake-key',
+        MINIMAL_AGENT_MODEL: 'fake-model',
+        MINIMAL_AGENT_CONTEXT_WINDOW: '128000',
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    },
+  );
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { exitCode, stdout, stderr };
+}
+
+describe('CLI 端到端 /workflow（拉子进程跑 main.tsx）', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cli-e2e-'));
+    mkdirSync(join(tmp, 'workflows'), { recursive: true });
+    copyFileSync(FIXTURE, join(tmp, 'workflows', 'cli-e2e.yaml'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it(
+    'golden path：跑完 + 文件落盘 + exit 0',
+    async () => {
+      const r = await spawnMain(
+        '/workflow cli-e2e --input topic=world',
+        tmp,
+      );
+      expect(r.exitCode).toBe(0);
+      const filePath = join(tmp, 'out', 'world', 'note.txt');
+      expect(existsSync(filePath)).toBe(true);
+      expect(readFileSync(filePath, 'utf8')).toBe('topic=world ok');
+    },
+    SPAWN_TIMEOUT,
+  );
+
+  it(
+    '/workflows 列出 cli-e2e',
+    async () => {
+      const r = await spawnMain('/workflows', tmp);
+      expect(r.exitCode).toBe(0);
+      expect(r.stdout).toContain('cli-e2e');
+    },
+    SPAWN_TIMEOUT,
+  );
+
+  it(
+    '缺必填 input → exit 1 + 错误信息含 "topic"',
+    async () => {
+      const r = await spawnMain('/workflow cli-e2e', tmp);
+      expect(r.exitCode).toBe(1);
+      expect(r.stderr).toContain('topic');
+    },
+    SPAWN_TIMEOUT,
+  );
+});