帮助
排查 Runifold 应用故障
按照可重复路径诊断安装、凭证、模型能力、Stream、重试、Workflow、存储与恢复问题。
安装与编译
| 现象 | 常见原因 | 处理 |
|---|---|---|
找不到 ProviderModelExt 或 from_api_key | 使用了旧版 runifold | 确认 runifold = "0.9.0"，运行 cargo update -p runifold |
| 无法导入 Provider Module | Cargo Feature 未启用 | 启用 openai、anthropic、gemini、ollama 或 bedrock |
| 找不到 Tokio Main Macro | Runtime Feature 缺失 | 启用 tokio/macros 与 tokio/rt-multi-thread |
| 两个 Runifold 类型不兼容 | 混用了不同版本的 Crate | 把所有 runifold-* Crate 更新到同一版本 |
| 编译器版本过低 | 不满足 MSRV | Runifold 0.9.0 需要 Rust 1.88 或更高 |
从下面三个命令开始诊断：
rustc --version
cargo tree -i runifold
cargo check认证与端点
HTTP 401 通常表示凭证缺失、无效、被撤销或来自错误环境。403 通常表示身份存在，但缺少 项目、模型、区域或组织权限。404 可能表示模型 ID 或 Base URL 与所选 Provider Protocol 不匹配。
必须检查启动应用的同一个进程环境，不能打印 Secret。日志只记录配置是否存在、选择了 哪个 Provider 和模型，以及脱敏后的错误类别。
模型与 Capability 错误
纯文本成功但 Tool 或结构化输出失败时：
- 确认准确模型支持该 Feature；
- 查看 Runifold Warning 与完整 Outcome；
- 确认 Adapter 是原生实现或使用了正确的兼容 Wire Protocol；
- 把请求缩小到最小复现；
- 针对这个模型与 Feature 组合运行 Live Smoke Test。
必需的结构化输出或 Tool 失败时，不能静默降级为未验证文本。
超时、重试与 Stream
Network Timeout 约束一次操作，Run Deadline 约束整个执行树的有效生命周期。调整限制前， 先确定触发的是哪个边界。
拒绝、无效请求、Capability Denied、Budget Exhausted 或不确定写入不能盲目重试。 Runifold 只会重试 Adapter 标记为安全的错误，应用层重试也必须遵守同一规则。
Stream 看起来被截断时，确认 Consumer 一直读取到 Terminal Event、处理 Error Event， 并且没有丢弃最后的 Usage 或 Outcome。下游客户端断开时应取消 Run。
Workflow、存储与恢复
| 现象 | 首先检查 |
|---|---|
| Workflow 恢复到旧定义 | Definition Version 与 Checkpoint Schema |
| 两个 Worker 执行同一 Task | Lease Fencing Token 与心跳过期 |
| 重启后已完成 Tool 再次运行 | Write-ahead Effect Record 与 Idempotency Key |
| Task 一直没有唤醒 | Signal Name、Tenant Scope、Retention 与 Timer Clock |
| Checkpoint 更新被拒绝 | 陈旧 Revision 或 Compare-and-swap 冲突 |
不确定状态不能视为成功。保留记录，与外部系统协调，并应用显式 Resume Policy。
构建有效的最小复现
请包含：
- 准确的
runifold与 Rust 版本； - 已启用的 Cargo Feature；
- 不含凭证的 Provider 与模型 ID；
- 最小 Request、Tool Schema 或 Workflow Definition；
- 脱敏错误 Kind 与 Retry Safety 分类；
- 错误发生在离线测试还是只发生在 Live 环境；
- 不含用户内容的 Run ID 与 Invocation ID。
先用 Scripted Model 或 Cassette 复现。如果只有真实服务失败，再增加带严格预算的 Provider Smoke Test，并比较 Wire Capability 证据。