Runifold 常见问题
快速了解 API、Provider、Run、Tool、状态、可靠性、生产使用与版本策略。
开始与选择
Runifold 只是 Agent 框架吗？
不是。Agent 只是同一执行内核上的一个产品面。你可以独立使用 Model Protocol、
Provider Runtime、类型化 Tool、检索、MCP、评测、可观测性或持久 Workflow Runtime。
应该依赖 runifold 还是窄 Crate？
应用优先使用 runifold 门面，只启用需要的 Feature。开发 Adapter、严格缩小专用依赖
边界或发布可复用基础设施时，再使用窄 Crate。
应该从哪个 API 开始？
只要文本结果用 prompt_text；需要完整 Outcome 用 prompt；需要增量事件用 stream；
生产边界使用显式 RunContext 调用 run。参见
API 选择。
Provider 与模型
切换 Provider 是否不需要修改应用代码？
核心 Request、Run、Agent 与 Tool 是 Provider-neutral 的，但 Capability 不完全相同。
切换 Client 和模型配置之后，必须重新验证 Capability 与质量。
OpenAI-compatible 是否代表行为完全一致？
不是。它只表示端点近似某个 Wire Protocol。Stream Event、Tool、结构化输出、Usage、
Reasoning 和错误语义仍可能不同。
为什么 Runifold 不自动读取凭证？
Secret 如何进入进程应由应用决定。显式构造可以让服务端、测试、网关、浏览器和多租户
边界保持可见，也避免库静默读取环境中的权限。
Run、Tool 与状态
Agent 与 Run 有什么区别？
Agent 描述模型行为、Tool 与 Turn Policy。Run 表示一次执行树，携带身份、预算、截止
时间、取消、Capability 与 Journal。
注册 Tool 是否代表已经授权？
不是。注册只表示 Tool 存在；Run 的 CapabilitySet 决定这次执行是否可以调用它。
会话记录就是 Checkpoint 吗？
不是。会话记录是模型上下文；Checkpoint 是可恢复执行状态；Event Journal 记录已经
发生的事实。
可靠性与生产
Runifold 保证外部 Effect Exactly Once 吗？
任意远程系统都无法由通用 Runtime 保证 Exactly Once。Runifold 使用 Write-ahead
Record、Idempotency Key、结果重放与保守恢复，让应用显式处理不确定性。
什么时候使用 Workflow 而不是 Agent？
模型决定下一次模型或 Tool 调用时使用 Agent；应用拥有步骤、分支、等待、恢复或持久
Task 状态时使用 Workflow。
Runifold 可以直接用于生产吗？
项目仍处于 1.0 之前。生产采用应固定版本，在自己的环境验证准确的 Provider、模型与
Feature 组合，并以公开可靠性证据为准，不能假设所有产品面成熟度相同。
版本与支持
这套文档对应哪个版本？
当前网站与编译验证示例对应 runifold 0.9.0。
1.0 之前应该如何升级？
固定准确 Minor Release，阅读 Changelog 与迁移说明，统一更新全部 Runifold Crate，
编译示例并运行确定性测试，最后执行少量 Live Provider Smoke Test。
遇到构建或运行错误，请继续阅读故障排查。