Clawnicle是一个用Rust编写的智能体持久化运行时，通过SQLite日志记录工具调用和LLM完成事件，实现崩溃恢复、确定性重放和预算控制，让AI智能体工作流具备Temporal式的持久执行能力。

Clawnicle：为LLM智能体打造的Rust持久化运行时\n\n在构建基于大语言模型的智能体应用时，一个核心挑战是如何处理长时间运行任务中的故障恢复。当智能体正在调用外部API、执行工具调用或与LLM交互时，如果进程崩溃或网络中断，传统实现往往需要从头重新开始，造成时间和成本的浪费。Clawnicle正是为解决这一问题而诞生的Rust库，它为LLM智能体带来了企业级的持久化执行能力。\n\n## 项目背景与设计哲学\n\nClawnicle的设计灵感来源于Temporal的持久化执行模型，但专门针对LLM智能体的特点进行了重新设计。其核心思想是将智能体的工作流视为一个异步函数，所有工具调用和LLM完成操作都通过一个Context对象进行，该对象会将每个事件追加写入SQLite日志。当进程重启后，库会从日志中读取已完成的步骤，直接返回缓存结果而无需重新执行，从而实现"从断点续传"的效果。\n\n这种设计模式解决了智能体开发中的几个关键痛点：重复执行昂贵的LLM调用、因崩溃导致的工作流中断、以及难以追踪和调试的执行历史。通过将执行状态外化到持久化存储，智能体获得了类似视频游戏存档点的能力。\n\n## 核心机制解析\n\n### 日志驱动的执行模型\n\nClawnicle采用追加式SQLite日志作为单一事实来源。每个工具调用通过cx.call(\"step_id\", ...)执行，系统会检查该步骤ID是否已存在于日志中。如果存在，直接返回缓存的输出；如果不存在，则执行闭包并将结果写入日志。这种机制天然支持幂等性——相同的步骤ID在相同工作流中总是返回相同结果。\n\n### 崩溃恢复与确定性重放\n\n当进程在工作流执行过程中被终止，重启后库会重新运行工作流函数。已完成步骤会从日志中短路返回，只有未完成的步骤会实际执行。这种确定性重放保证了给定相同日志，重放总是产生相同结果。开发者可以安全地终止进程，而无需担心丢失进度或产生不一致状态。\n\n### 智能重试与预算控制\n\nClawnicle内置了带指数退避和每次尝试超时的重试机制call_with_retry，每次重试尝试都会被记录到日志中，便于事后审查。更重要的是，系统支持工作流级别的预算控制，可以限制token数量、美元成本或墙钟时间。预算检查在调用前和重试前执行，超预算后的调用会返回Error::BudgetExceeded。\n\n### LLM感知缓存\n\n针对LLM调用的特殊性，Clawnicle提供了complete_llm(provider, request)方法，该方法会对模型、消息、温度、最大token数等参数进行哈希，并缓存响应。重新请求相同的提示将直接返回缓存结果，无需接触提供商API，既节省成本又提高响应速度。\n\n## 典型使用场景\n\n考虑一个代币扫描智能体的实现：\n\nrust\nasync fn scan_token(cx: &mut Context, mint: &str) -> Result<Verdict> {\n let dex = cx\n .call_with_retry(\n &format!(\"dex_fetch:{mint}\"),\n RetryPolicy::exponential_3(),\n || async { dexscreener::fetch(mint).await },\n )\n .await?;\n\n let helius = cx\n .call(&format!(\"helius_fetch:{mint}\"), || async {\n helius::fetch(mint).await\n })\n .await?;\n\n let verdict = run_gates(&dex, &helius);\n cx.complete(&verdict)?;\n Ok(verdict)\n}\n\n\n如果在DexScreener调用和Helius调用之间杀死进程，重启后DexScreener调用会从日志短路返回，只有Helius调用会实际执行。这种细粒度的恢复能力对于涉及多个外部依赖的复杂工作流尤为重要。\n\n## 性能特征\n\n根据项目提供的基准测试数据，Clawnicle在常见操作上的性能表现如下：\n\n- 小负载日志追加：约21微秒\n- 2KB负载日志追加：约34微秒\n- 首次工具调用：约1.4毫秒\n- 缓存工具调用（重放短路）：约3.7微秒\n- 缓存LLM完成：约4.5微秒\n\n这些数字表明，持久化带来的开销在可接受范围内，而缓存命中的情况几乎无感知。对于需要频繁与外部服务交互的智能体应用，这种 trade-off 是值得的。\n\n## 与现有方案的对比\n\n在Rust生态中，有几个项目涉及类似领域，但各有侧重：\n\n- Temporal Rust SDK：提供通用持久化执行能力，但处于alpha阶段且语言无关\n- Restate：Rust原生但模型无关，支持多语言\n- rig-rs：专为智能体设计，但缺乏持久化能力\n- oracle.omen：支持持久化但对LLM无感知\n\nClawnicle的独特定位在于它是Rust原生、智能体优先、支持日志持久化且LLM感知的运行时，填补了上述方案之间的交集空白。\n\n## 项目状态与展望\n\n目前Clawnicle处于v0开发阶段，前5周已交付工作区、事件模式、SQLite日志、Context API、重试/预算/取消机制、LLM提供商抽象层、检查CLI和基准测试等核心功能。剩余工作包括并发工作流的调度器、第二个非加密货币参考工作负载，以及发布文档。\n\n对于需要构建可靠、可观测、可恢复的智能体应用的Rust开发者来说，Clawnicle代表了一个有前景的基础设施选择。随着项目的成熟，它有望成为LLM智能体持久化执行领域的标杆实现。

Clawnicle：为LLM智能体打造的Rust持久化运行时\n\n在构建基于大语言模型的智能体应用时，一个核心挑战是如何处理长时间运行任务中的故障恢复。当智能体正在调用外部API、执行工具调用或与LLM交互时，如果进程崩溃或网络中断，传统实现往往需要从头重新开始，造成时间和成本的浪费。Clawnicle正是为解决这一问题而诞生的Rust库，它为LLM智能体带来了企业级的持久化执行能力。\n\n项目背景与设计哲学\n\nClawnicle的设计灵感来源于Temporal的持久化执行模型，但专门针对LLM智能体的特点进行了重新设计。其核心思想是将智能体的工作流视为一个异步函数，所有工具调用和LLM完成操作都通过一个Context对象进行，该对象会将每个事件追加写入SQLite日志。当进程重启后，库会从日志中读取已完成的步骤，直接返回缓存结果而无需重新执行，从而实现"从断点续传"的效果。\n\n这种设计模式解决了智能体开发中的几个关键痛点：重复执行昂贵的LLM调用、因崩溃导致的工作流中断、以及难以追踪和调试的执行历史。通过将执行状态外化到持久化存储，智能体获得了类似视频游戏存档点的能力。\n\n核心机制解析\n\n日志驱动的执行模型\n\nClawnicle采用追加式SQLite日志作为单一事实来源。每个工具调用通过cx.call(\"step_id\", ...)执行，系统会检查该步骤ID是否已存在于日志中。如果存在，直接返回缓存的输出；如果不存在，则执行闭包并将结果写入日志。这种机制天然支持幂等性——相同的步骤ID在相同工作流中总是返回相同结果。\n\n崩溃恢复与确定性重放\n\n当进程在工作流执行过程中被终止，重启后库会重新运行工作流函数。已完成步骤会从日志中短路返回，只有未完成的步骤会实际执行。这种确定性重放保证了给定相同日志，重放总是产生相同结果。开发者可以安全地终止进程，而无需担心丢失进度或产生不一致状态。\n\n智能重试与预算控制\n\nClawnicle内置了带指数退避和每次尝试超时的重试机制call_with_retry，每次重试尝试都会被记录到日志中，便于事后审查。更重要的是，系统支持工作流级别的预算控制，可以限制token数量、美元成本或墙钟时间。预算检查在调用前和重试前执行，超预算后的调用会返回Error::BudgetExceeded。\n\nLLM感知缓存\n\n针对LLM调用的特殊性，Clawnicle提供了complete_llm(provider, request)方法，该方法会对模型、消息、温度、最大token数等参数进行哈希，并缓存响应。重新请求相同的提示将直接返回缓存结果，无需接触提供商API，既节省成本又提高响应速度。\n\n典型使用场景\n\n考虑一个代币扫描智能体的实现：\n\nrust\nasync fn scan_token(cx: &mut Context, mint: &str) -> Result<Verdict> {\n let dex = cx\n .call_with_retry(\n &format!(\"dex_fetch:{mint}\"),\n RetryPolicy::exponential_3(),\n || async { dexscreener::fetch(mint).await },\n )\n .await?;\n\n let helius = cx\n .call(&format!(\"helius_fetch:{mint}\"), || async {\n helius::fetch(mint).await\n })\n .await?;\n\n let verdict = run_gates(&dex, &helius);\n cx.complete(&verdict)?;\n Ok(verdict)\n}\n\n\n如果在DexScreener调用和Helius调用之间杀死进程，重启后DexScreener调用会从日志短路返回，只有Helius调用会实际执行。这种细粒度的恢复能力对于涉及多个外部依赖的复杂工作流尤为重要。\n\n性能特征\n\n根据项目提供的基准测试数据，Clawnicle在常见操作上的性能表现如下：\n\n- 小负载日志追加：约21微秒\n- 2KB负载日志追加：约34微秒\n- 首次工具调用：约1.4毫秒\n- 缓存工具调用（重放短路）：约3.7微秒\n- 缓存LLM完成：约4.5微秒\n\n这些数字表明，持久化带来的开销在可接受范围内，而缓存命中的情况几乎无感知。对于需要频繁与外部服务交互的智能体应用，这种 trade-off 是值得的。\n\n与现有方案的对比\n\n在Rust生态中，有几个项目涉及类似领域，但各有侧重：\n\n- Temporal Rust SDK：提供通用持久化执行能力，但处于alpha阶段且语言无关\n- Restate：Rust原生但模型无关，支持多语言\n- rig-rs：专为智能体设计，但缺乏持久化能力\n- oracle.omen：支持持久化但对LLM无感知\n\nClawnicle的独特定位在于它是Rust原生、智能体优先、支持日志持久化且LLM感知的运行时，填补了上述方案之间的交集空白。\n\n项目状态与展望\n\n目前Clawnicle处于v0开发阶段，前5周已交付工作区、事件模式、SQLite日志、Context API、重试/预算/取消机制、LLM提供商抽象层、检查CLI和基准测试等核心功能。剩余工作包括并发工作流的调度器、第二个非加密货币参考工作负载，以及发布文档。\n\n对于需要构建可靠、可观测、可恢复的智能体应用的Rust开发者来说，Clawnicle代表了一个有前景的基础设施选择。随着项目的成熟，它有望成为LLM智能体持久化执行领域的标杆实现。