构建常见 Runifold 应用

按目标选择配方

先从产品需要的行为出发。下面所有配方都基于同一套执行模型，因此从原型升级到受约束的 Run 时，不需要更换框架。

我想要……	从这里开始	上生产前补充
向模型提一个问题	第一次运行	明确模型、超时与错误策略
返回 Rust 值	结构化输出	领域校验与拒绝处理
调用应用代码	类型化工具	Capability、预算与 Effect 策略
向界面流式返回	流式输出	断连取消与终态处理
保存会话	会话与记忆	上下文窗口与租户 Namespace
根据文档回答	检索	归因、租户过滤与评测
协调固定步骤	Workflow	Checkpoint 与恢复策略
暴露远程能力	MCP	授权分区与传输限制

单次调用与类型化输出

文本边界使用 prompt_text；应用逻辑需要明确契约时，使用结构化 Agent：

use runifold::JsonSchema;
use serde::Deserialize;
 
#[derive(Debug, Deserialize, JsonSchema)]
struct Triage {
    category: String,
    urgent: bool,
    explanation: String,
}
 
let structured = runtime
    .agent("triage")
    .system("Classify the request. Keep the explanation short.")
    .build_structured::<Triage>("triage_result")?;
 
let run = structured.agent().default_run_context();
let result = structured.run("Payment failed twice", &run).await?;
println!("{:?}", result.output);

服务商接受 Schema 不代表数据满足业务规则。反序列化之后仍要验证领域不变量；模型拒绝或输出无效时应当失败关闭，不能静默退回未验证文本。

工具、流式输出与记忆

这些能力解决的是不同问题：

Tool 允许模型提出对类型化 Rust 代码的调用；
Stream 暴露有序的模型、Tool、用量、警告和终态事件；
会话存储 跨请求保存消息和版本；
RunContext 为一次执行树携带权限、预算、取消、截止时间和 Journal 状态。

不要把聊天记录当成执行状态，也不要把 Tool 注册当成授权。分别阅读类型化工具、流式输出和会话，再按产品需要组合。

Workflow 与长期任务

模型决定下一轮模型或 Tool 调用时，使用普通 Agent；应用拥有步骤顺序、分支、汇合、 Timer、Signal 或恢复边界时，使用 Workflow。

一个持久任务应当：

定义稳定的 Step ID 与 Workflow 版本；
为每个 Step 指定 CapabilitySet；
在执行前持久化 Checkpoint 与外部 Effect；
使用带栅栏 Lease 与心跳的 Worker；
明确定义未知或不确定状态如何恢复。

依次阅读 Workflow、持久化和 Worker。

了解验证边界

Quickstart、结构化输出、Tool、流式输出、会话、委派、路由和 Web Service 示例都会在文档 CI 中使用公开的 runifold = 0.9.0 编译。编译通过证明页面与 API 一致；真实 Provider 行为仍然需要凭证和针对具体模型的 Smoke Test。

确定性行为请看测试指南，真实协议证据请看 Provider 测试。