文档导航
找到适合你的 Runifold 学习路径
选择学习路线，理解执行模型，并知道下一步应该阅读哪篇指南。
第一次接触 Runifold？
先完成5 分钟 Quickstart。接着按产品任务查阅应用配方，或通过45 分钟核心课程建立完整心智模型。
探索完整平台
Runifold 不只是 Agent Library。应该从产品真正需要的能力面开始：
| 产品面 | 核心指南 |
|---|---|
| 执行内核 | RunContext、Capability 安全、Checkpoint 恢复 |
| 模型与服务商 | 模型协议、Provider Runtime、Provider 测试 |
| Agent | 构建 Agent、Tool、会话 |
| 持久工作流 | Worker、并行、版本管理、多租户 |
| 集成 | MCP 上下文与 Sampling、MCP Tasks、检索流水线、存储 |
| 质量与运维 | 评测 CLI、Task 治理、SLO、可信发布 |
设计跨越多个产品面的系统前，先阅读完整平台架构。
选择学习路径
Runifold 可以让一次简单模型调用逐步成长为有界、可观察、可恢复的系统，而不需要中途 更换另一套编排抽象。开始使用前，你不必先学完整个 Runtime。
| 你想完成的任务 | 从这里开始 | 接着阅读 |
|---|---|---|
| 在 Rust 中调用模型 | 第一次可信运行 | 选择执行 API |
| 选择并配置模型服务 | Provider 配置 | Provider Runtime、Provider 测试 |
| 构建会调用工具的 Agent | 构建 Agent | 类型化工具、结构化输出 |
| 构建聊天或助手 | 会话与记忆 | 检索、流式输出 |
| 协调多个专业 Agent | Agent 委派 | 预算与取消 |
| 执行长期业务流程 | 工作流 | 持久工作流、Effect |
| 暴露 Rust API | 部署 Web Service | RunContext、可观测性 |
| 投入生产 | 测试 | 质量评估、可观测性、可靠性 |
第一次访问时，建议先完成快速教程，再打开参考型指南。教程会建立后续页面共同使用的 词汇。
理解执行模型
五个概念贯穿整套 API：
- Run：每次执行都有身份、父级、生命周期与共享记账。
- Event：Runtime 的语义状态变化与模型可见会话分开记录。
- Capability：注册 Callable 表示它存在；授予 Capability 表示本次运行可以使用。
- Effect：外部写操作具有显式恢复与幂等语义。
- Checkpoint：持久进度可以恢复，而不会武断地假设被打断的操作一定失败。
正因为这些边界保持一致，便捷的 prompt_text 与多 Worker 持久工作流才能共用同一个
执行内核。
从原型走向生产
只在产品需要时增加约束：
| 阶段 | 加入 | 作用 |
|---|---|---|
| 探索 | prompt_text | 最短路径获得文本 |
| 集成 | 类型化输出与 Tool | 建立稳定应用契约 |
| 约束 | 显式 RunContext | 预算、权限、Deadline 与取消 |
| 弹性 | Router 与 Effect | 在不确定网络边界安全恢复 |
| 持久 | Checkpoint 与工作流 | 跨重启与长时间等待 |
| 运营 | Journal、OTel、测试与评估 | 解释并改进行为 |
不要默认堆叠所有层。简单分类接口可能永远不需要工作流；支付流程也不应该靠 Prompt 定义业务跳转。
去哪里查找答案
- 本站解释任务、决策与生产后果。
- 0.9.0 docs.rs 是 Rust API 条目级权威参考。
- GitHub 示例 提供经过编译检查的应用模式。
- 架构 RFC 解释契约为何存在，以及拒绝过哪些替代方案。
- 服务商支持 与可靠性证据 是与版本绑定的事实来源。
指南与 API Reference 看似不一致时，先固定 Crate 版本并查看对应版本的参考；确认问题 后，用最小复现报告文档差异。