oh-my-fable：可崩溃恢复、模型无关的 AI Agent 任务执行框架

oh-my-fable 是一个受 Fable 5 启发的 AI Agent 任务执行框架，通过 RunContext 状态管理和计划-反思机制，实现了任务的可恢复执行、自我纠错和确定性测试。

• 原作者/维护者： didrod205
• 来源平台： GitHub / NPM
• 原始标题： oh-my-fable
• 原始链接： https://github.com/didrod205/oh-my-fable
• 发布时间： 2026-06-16
• NPM 包： https://www.npmjs.com/package/oh-my-fable

---

在使用 AI Agent 处理实际任务时，开发者经常会遇到以下痛点：

1. 任务中断丢失进度：当处理多小时的复杂任务时，Agent 可能在某个步骤陷入循环，或在进程重启后完全丢失之前的进度
2. 计划迷失：在 40+ 条消息的对话历史中，Agent 容易丢失对整体计划的跟踪，不知道"我现在在哪"
3. 不可测试性：大多数 Agent 框架依赖网络调用和随机性，难以进行确定性测试

oh-my-fable 正是为解决这些问题而设计。它编码了强推理模型处理长任务的方式——先规划、再执行、持续自我纠错、永不丢失线索——将其封装为一个模型无关的执行框架。

---

整个运行过程存在于一个可序列化的 RunContext 中，每一步执行后都会保存检查点。

从这个原则自然推导出 oh-my-fable 最独特的特性：崩溃只是暂停。

── 运行 run_mqf... ──
  📋 规划了 3 个步骤：outline → draft → edit
  ▶  outline
     → 已完成
     💾 检查点已保存
  ▶  draft
  💥 进程崩溃（断电、OOM、部署等）

── 从最后一个检查点恢复 ──
  ▶  draft                ← 精确从崩溃处继续
     💾 检查点已保存
  ▶  edit
  ✅ 完成

  步骤状态：outline [done], draft [done], edit [done]

---

状态不保存在内存或对话记录中，而是持久化在 RunContext 中，每一步执行后都会保存到磁盘。即使进程在第 47 步崩溃，resume() 也能从第 47 步继续，计划和进度完好无损。

通过实现简单的 Store 接口，可以将存储后端从文件系统替换为 SQLite 或 Redis：

const result = await run(goal, { provider, store });   // 在第 2 步崩溃
// ...进程重启...
await resume(result.runId, { provider, store });        // 从第 2 步继续完成

计划是独立于对话的结构化数据，这样模型永远不会在大量文本中迷失方向。每一步执行后，**反射器（reflector）**会检查结果与目标的匹配度，并决定下一步行动：

判定结果	含义	后续动作
on_track	正常进展	执行下一步
needs_replan	结果改变了计划的假设	重新规划
blocked	同一障碍反复出现	绕过障碍或升级处理
goal_met	成功标准已满足	停止（即使有剩余步骤）

重新规划时会累积已完成的工作：已完成的步骤原样保留，只重新生成剩余部分。这样长任务会持续向前推进，而不是从头开始。

由于每次模型调用都是无状态的，开发者可以编写脚本模拟模型响应并断言循环行为——无需网络、无随机性：

import { run, ScriptedProvider, reply, MemoryStore } from "oh-my-fable";

const provider = new ScriptedProvider([
  reply.plan([{ id: "s1", intent: "do the thing" }]),
  reply.text("did it"),
  reply.reflection("goal_met"),
]);

const { status } = await run("do the thing", { provider, store: new MemoryStore() });
expect(status).toBe("done"); // 完全确定性

整个框架都采用这种方式测试——崩溃恢复、重新规划累积、预算暂停、工具循环——全部无需真实 API 调用。

---

import { run, AnthropicProvider } from "oh-my-fable";

const result = await run(
  {
    description: "调研前 3 个 Rust Web 框架并撰写对比表",
    successCriteria: ["存在对比 3 个框架的 markdown 表格"],
    constraints: ["只使用可验证的信息"],
  },
  { provider: new AnthropicProvider() }, // 读取 ANTHROPIC_API_KEY
);

console.log(result.status); // "done" | "halted" | "failed"
console.log(result.ctx.plan.steps);

安装命令：

npm i oh-my-fable  # 零运行时依赖

要求 Node ≥ 18。内置 AnthropicProvider 和 OpenAICompatProvider（兼容 OpenAI、Ollama、LM Studio、OpenRouter、Groq 等），均基于 fetch 实现，无需 SDK。