Feature request: handle stop_reason "refusal" from Claude Fable 5 / Opus 5 with automatic model fallback
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
**客户端版本**: 0.1.22
**反馈类型**: feature
---
## 背景
Claude Fable 5 / Opus 5 内置安全分类器,部分请求会被婉拒:返回的不是错误,而是一个正常响应但 `stop_reason: "refusal"`。在 Cindy 中碰到这种情况时,当前会话直接停在被拒状态,用户只能手动换模型重发,体验中断。
Anthropic 官方文档专门给出了应用侧的处理方案:
https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback
## 建议
希望 Cindy 在调用 Claude 的请求层接入 refusal fallback,两条路径任一即可:
1. **服务端 fallback(beta)**:请求加 `fallbacks: "default"` + `anthropic-beta: server-side-fallback-2026-07-01` header,API 被拒后自动换推荐备选模型重试,流式场景还能保留已产出的部分输出继续。
2. **客户端 fallback(SDK middleware,更推荐)**:官方 SDK 全系内置 `BetaRefusalFallbackMiddleware` / `betaRefusalFallbackMiddleware`,client 构造时配备选模型列表(如 Opus 4.8),被拒请求自动重试,并自动带 `fallback-credit-2026-07-01` header 避免重复计费;配合共享 `BetaFallbackState` 把同一会话后续轮次钉在接受了请求的模型上。这条路不依赖服务端/网关透传,对走自定义网关(LiteLLM 等)的用户更稳。
## 使用场景
在 Cindy 中以 Fable 5 作为主模型进行日常 agent 工作时遇到 refusal,会话中断。期望行为:Cindy 自动 fallback 到备选模型继续,并在 UI 上标注实际服务模型(响应的 `model` 字段/`fallback` content block 都可识别)。
## 备注
- 用户走公司网关(LiteLLM proxy)时,服务端方案需网关透传 `fallbacks` 参数与 beta header;SDK middleware 方案无此依赖。
- 相关文档:sticky routing、fallback credit 计费细节见同页 accordion 与 https://platform.claude.com/docs/en/build-with-claude/fallback-credit
---
**版本区域**: CN
**OS**: win32 x64 (10.0.26200)
**界面语言**: zh-CN
Contributor guide
Research direction
Start by locating Cindy’s Claude request layer and the model-selection or retry entry points, then review the linked Anthropic refusal fallback documentation. Trace how streamed responses expose stop_reason, model, and fallback content blocks, and identify the UI path that displays the active model. Done means a refusal retries with the configured fallback, preserves the session behavior, and shows which model served the response.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- ai, backend-api-design, frontend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100