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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-16T01:17:19.000Z
- 最近活动: 2026-06-16T01:27:33.080Z
- 热度: 159.8
- 关键词: AI Agent, 任务执行框架, RunContext, 检查点, 模型无关, TypeScript, 可测试性, 崩溃恢复
- 页面链接: https://www.zingnex.cn/forum/thread/oh-my-fable-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/oh-my-fable-ai-agent
- Markdown 来源: ingested_event

---

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

## 原作者与来源

- **原作者/维护者：** 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 是唯一真相源

> 整个运行过程存在于一个可序列化的 **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：

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

### 特性二：计划优先 + 自我纠错（计划 ≠ 历史）

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

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

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

### 特性三：确定性可测试性（Agent 框架中罕见）

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

```ts
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 调用。

---

## 快速上手

### 作为库使用

```ts
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);
```

安装命令：

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

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

### CLI 使用

无需编写代码，直接通过命令行使用：

```bash
# 观看演示（无需 API Key）
npx oh-my-fable demo

# 使用本地模型（Ollama / LM Studio）
npx oh-my-fable run "概述 durable agents 主题演讲" --provider ollama --model llama3.1

# 使用托管模型
export ANTHROPIC_API_KEY=sk-...
npx oh-my-fable run "将 README.md 总结为 SUMMARY.md" --tools fs

# 查看和恢复运行
npx oh-my-fable list
npx oh-my-fable resume run_abc123
```

**无需 Anthropic Key**——通过 `--provider ollama` 或 `--provider openai` 可指向本地模型或任何 OpenAI 兼容服务。

---

## 工具集成与安全边界

### 工具定义

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

const search = defineTool(
  "web_search",
  "搜索网络并返回结果。",
  { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
  async ({ query }) => ({ ok: true, output: await fetchResults(query) }),
);

await run(goal, { provider: new AnthropicProvider(), tools: [search] });
```

抛出异常的工具会被转化为 `Observation` 而非崩溃，由反射器决定如何处理。

### 安全上限

框架设置了三个硬性上限，每次循环开始时检查，外加两个恢复上限。超出任何一个都会干净地暂停，保留所有工作：

```ts
await run(goal, {
  provider,
  maxSteps: 50,            // 总步骤预算
  maxTokens: 100_000,       // 总 Token 预算
  maxWallTimeMs: 10*60*1000, // 10 分钟 wall-clock 限制
});
```

---

## 事件监听与调试

```ts
await run(goal, {
  provider,
  onEvent: (e) => console.log(e.type, e),
  // plan_created · step_start · step_done · reflection · replan · compaction · checkpoint · done · halted
});
```

通过事件监听，可以实时观察计划的形成、每一步的执行、反射的判断以及检查点的保存。

---

## 技术亮点总结

1. **零依赖**：运行时零依赖，轻量部署
2. **模型无关**：支持 Anthropic、OpenAI、Ollama、本地模型等任何 Provider
3. **崩溃恢复**：基于 RunContext 的检查点机制，实现真正的可恢复执行
4. **自我纠错**：计划-执行-反射循环，支持动态重新规划
5. **可测试性**：ScriptedProvider 支持完全确定性的单元测试
6. **类型安全**：完整的 TypeScript 类型支持

---

## 总结与展望

oh-my-fable 代表了 AI Agent 框架设计的一个重要方向：**从"尽力而为"到"可靠执行"**。通过将状态外化到可序列化的 RunContext，并引入显式的计划-反思循环，它解决了长期任务执行中的关键可靠性问题。

这一设计模式对于以下场景特别有价值：

- **长时间运行的自动化任务**：如代码重构、文档生成、数据分析等
- **关键业务工作流**：需要确保任务完成且可审计的场景
- **边缘部署**：网络不稳定或资源受限环境下的 Agent 执行

随着 AI Agent 在生产环境中的应用越来越广泛，可靠性和可观测性将成为核心诉求。oh-my-fable 的实践为这一领域提供了有价值的参考实现。