Chidori (v3)  

一个让 TypeScript Agent 具备默认检查点（checkpoint）、重放（replay）和恢复（resume）能力的 Agent 框架。

在 GitHub 上为我们点亮 Star！欢迎加入我们的 Discord。

关于 v3 版本。 Chidori 最初是一个响应式运行时（reactive runtime），旨在探索如何构建持久化、可调试的 Agent。v3 版本经过了彻底的重构，将核心理念浓缩为更小巧、更精炼的架构：单一 Rust 二进制文件、TypeScript Agent 编写方式，以及将“重放”作为测试、调试、任务恢复和人机协作（human-in-the-loop）工作流的基础。早期版本的 Chidori 代码存在于 git 历史记录和之前的标签中。

目录

• 📖 关于项目
• ⚡️ 快速开始
• ▶️ 运行演示
• 🧩 核心概念
• 🚦 运行模式
• 🐍 Python SDK
• ⏪ 重放机制原理
• 🧪 示例
• 🏗 架构
• 📦 项目结构

📖 关于项目

• 使用 TypeScript 编写 Agent。 原生异步控制流、类型化输入、支持导入及编辑器工具链，无需模板 DSL。
• 确定性执行。 每个副作用都会经过一个宿主函数（host function），运行时可以对其进行记录、缓存和重放。
• 零成本检查点。 将会话调用日志保存到磁盘，随后即可通过重放实现相同的输出，且无需调用 LLM。
• 事件驱动的 Agent。 Agent 可以作为 HTTP 服务器运行，以响应 Webhook 和其他事件。
• Rust 核心，TS 和 Python SDK。 运行时是一个单一的二进制文件。SDK 通过 HTTP 与其通信，无需原生绑定（native bindings）。

⚡️ 快速开始

1. 编写 Agent

// agents/summarizer.ts
import type { Chidori } from "chidori";

export async function agent(input: { document: string }, chidori: Chidori) {
  const summary = await chidori.prompt(
    "Summarize in 3 bullets:\n" + input.document,
    { type: "summary" },
  );
  const actionItems = await chidori.prompt(
    "Extract action items:\n" + summary,
    { type: "actions" },
  );
  return { summary, actionItems };
}

2. 运行它

# 设置 LLM 提供商（本例使用 LiteLLM）
export LITELLM_API_URL=http://localhost:4401/v1
export LITELLM_API_KEY=sk-litellm-master-key

# 或者直接使用提供商的 Key
# export ANTHROPIC_API_KEY=sk-ant-...
# export OPENAI_API_KEY=sk-...

cargo build
./target/debug/chidori run agents/summarizer.ts \
  --input document="Rust is a systems programming language..."

3. 尝试示例 Agent

# 交互式示例选择器
./target/debug/chidori demo

# 极简 Agent — 无需 LLM 调用
./target/debug/chidori run examples/agents/hello.ts --input name=Colton

# 本地 TypeScript 工具 — 无需 LLM 调用
./target/debug/chidori run examples/agents/tool_use.ts \
  --input query=chidori --tools examples/tools

# 带有 Trace 的摘要 Agent
./target/debug/chidori run examples/agents/summarizer.ts \
  --input document="Rust is great." --trace

# 并行宿主任务
./target/debug/chidori run examples/agents/parallel.ts \
  --input '{"topic": "runtime snapshots"}'

# 事件驱动的 Webhook 处理程序
./target/debug/chidori serve examples/agents/webhook.ts --port 8080

▶️ 运行演示

探索 Chidori 最简单的方法是使用交互式演示选择器：

cargo build
./target/debug/chidori demo

chidori demo 会显示一个可运行示例的数字列表，其中包括无需 LLM 提供商即可运行的演示，以及在配置了环境变量后可进行 Prompt 追踪（tracing）或流式传输（streaming）的演示。选择 Hello agent 是无需配置 Key 即可体验的最快路径。

该演示会运行一个 TypeScript Agent，记录一份持久化的宿主调用日志（host-call log），并返回 JSON。直接运行命令为：

./target/debug/chidori run examples/agents/hello.ts --input name=Colton

预期输出：

{
  "greeting": "Hello, Colton!"
}

该示例展示了：

• examples/agents/hello.ts 导出了 agent(input, chidori)。
• Agent 调用了 chidori.log(...)，因此运行时记录了一次宿主调用。
• Agent 返回纯 JSON，这正是 CLI、服务器和 SDK 用户所接收到的结果。
• 检查点被写入到 examples/agents/.chidori/runs// 下，用于后续的追踪/重放工作流。

你可以检查最近一次的运行情况：

RUN_ID=$(ls -t examples/agents/.chidori/runs | head -1)
./target/debug/chidori trace "$RUN_ID" --dir examples/agents
./target/debug/chidori snapshot "$RUN_ID" --dir examples/agents

人机协作（Human-In-The-Loop）演示

该演示展示了会话 API 如何在遇到 chidori.input(...) 时暂停，并从持久化的 VM 状态恢复执行。

启动服务器：

./target/debug/chidori serve examples/agents/input_pause.ts --port 8080

在另一个终端中，创建一个会话：

curl -s http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"input":{"request":"ship the TypeScript runtime"}}'

响应将包含 "status":"paused"、"id" 以及 "pending_prompt":"Approve this request?"。使用以下命令恢复它：

SESSION_ID=<从上方获取ID>

curl -s http://localhost:8080/sessions