makecindy / makecindy/cindy

Feature request: handle stop_reason "refusal" from Claude Fable 5 / Opus 5 with automatic model fallback

Open
#1,039 1 comment 0 reactions 0 assignees View on GitHub
feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.