Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(desktop): 让 chat 桥自愈 Claude Code 的中段 system 消息 (#5053)

lengjingxu2cee855752c9
diff --git a/apps/desktop/src/main/maker-host/__tests__/claudeProviderBridge.test.ts b/apps/desktop/src/main/maker-host/__tests__/claudeProviderBridge.test.ts
index c2f8911af8..042f7ca8eb 100644
--- a/apps/desktop/src/main/maker-host/__tests__/claudeProviderBridge.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/claudeProviderBridge.test.ts
@@ -95,6 +95,69 @@ describe('Claude Code custom provider translation', () => {
expect(sent?.get('authorization')).toBeNull();
});
+ it('retries once with the mid-conversation system hoisted when the upstream rejects it', async () => {
+ // Claude Code 的 mid-conversation-system 把 system 投到 user 轮次之后;Google 的
+ // OpenAI 兼容层是会话级限制,不合并就整轮 400 且下一轮复现。
+ const sent: unknown[][] = [];
+ const googleOrderError = JSON.stringify({
+ error: {
+ message: JSON.stringify({
+ error: {
+ message: "'system messages are only supported at the beginning of the conversation' functionality not supported.",
+ type: 'AI_UnsupportedFunctionalityError',
+ },
+ }),
+ type: 'invalid_request_error',
+ },
+ });
+ const handler = createClaudeProviderBridge({
+ url: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',
+ protocol: 'openai-chat',
+ headers: { authorization: 'Bearer fixture-supplier-key' },
+ efforts: ['low', 'medium', 'high'],
+ capabilities: { reasoningField: 'reasoning_effort' },
+ fetchImpl: async (_url, init) => {
+ const request = JSON.parse(String(init?.body));
+ sent.push(request.messages);
+ if (sent.length === 1) return new Response(googleOrderError, { status: 400 });
+ return new Response(chatStream, { headers: { 'content-type': 'text/event-stream' } });
+ },
+ });
+ const server = createServer((req, res) => {
+ const chunks: Buffer[] = [];
+ req.on('data', chunk => chunks.push(chunk));
+ req.on('end', () => {
+ void handler.handle({ parsedBody: JSON.parse(Buffer.concat(chunks).toString()),
+ ctx: { reqId: 1, method: 'POST', url: req.url!, headers: {} }, res,
+ }).catch(() => { res.statusCode = 500; res.end(); });
+ });
+ });
+ server.listen(0, '127.0.0.1'); await once(server, 'listening');
+ try {
+ const response = await fetch(`http://127.0.0.1:${(server.address() as AddressInfo).port}/v1/messages`, {
+ method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer fixture-claude-subscription' },
+ body: JSON.stringify({ model: 'google/gemini-3.8-flash', stream: true, max_tokens: 8192,
+ system: 'You are an interactive agent.',
+ messages: [
+ { role: 'user', content: [{ type: 'text', text: 'system-reminder: context' }] },
+ { role: 'system', content: [{ type: 'text', text: 'Available agent types for the Agent tool' }] },
+ { role: 'user', content: [{ type: 'text', text: '继续' }] },
+ ],
+ }),
+ });
+ expect(await response.text()).toContain('message_stop');
+ } finally { server.closeAllConnections(); await new Promise<void>(resolve => server.close(() => resolve())); }
+ expect(sent).toHaveLength(2);
+ // 中段 system 与顶层 system 合成唯一首条 system,user 相对顺序保持。
+ expect(sent[1]).toEqual([
+ { role: 'system', content: 'You are an interactive agent.\n\nAvailable agent types for the Agent tool' },
+ { role: 'user', content: 'system-reminder: context' },
+ { role: 'user', content: '继续' },
+ ]);
+ // 首包确实带着中段 system —— 复现的是真实链路,不是被提前改写过。
+ expect(sent[0]).toContainEqual({ role: 'system', content: 'Available agent types for the Agent tool' });
+ });
+
it('keeps encrypted reasoning state private to a connection, not a shared URL', () => {
const url = 'https://openrouter.ai/api/v1/chat/completions';
expect(claudeProviderReasoningNamespace(url, 'custom:openrouter-a'))
diff --git a/apps/desktop/src/main/maker-host/claude-provider-bridge.ts b/apps/desktop/src/main/maker-host/claude-provider-bridge.ts
index 36524ea50e..9f7dcf27dc 100644
--- a/apps/desktop/src/main/maker-host/claude-provider-bridge.ts
+++ b/apps/desktop/src/main/maker-host/claude-provider-bridge.ts
@@ -4,7 +4,7 @@ import type { Effort, ProviderModelRecord } from '@cindy/model-providers';
import { reconcileOutboundReasoningEffort } from './outbound-reasoning-effort.js';
import { createPiProviderFetch, nativeBridgeApiKey } from './pi-provider-transport.js';
import { createResponsesHandler, type ResponsesBridgeHandler } from '@cindy/anthropic-responses-bridge';
-import { ChatSseTranslator, translateResponsesRequestWithContext, type ChatBridgeCapabilities, type ResponsesRequest } from '@cindy/responses-chat-bridge';
+import { ChatSseTranslator, classifySystemOrderError, coalesceLeadingSystemMessages, shouldRetrySystemNormalization, translateResponsesRequestWithContext, type ChatBridgeCapabilities, type ResponsesRequest } from '@cindy/responses-chat-bridge';
/** Reasoning blobs are private to a connection, not to a shared upstream URL. */
export function claudeProviderReasoningNamespace(url: string, providerId?: string): string {
@@ -12,6 +12,32 @@ export function claudeProviderReasoningNamespace(url: string, providerId?: strin
return `cindy-provider-${createHash('sha256').update(material).digest('hex')}/`;
}
+/**
+ * 读错误正文用于判定,带上限:上游可能回超长正文,而这里只为识别一句措辞。
+ * 判定句在正文前部(外层 error.message 里),截断不影响命中。
+ */
+const SYSTEM_ORDER_PROBE_LIMIT = 8 * 1024;
+
+async function readBoundedErrorText(response: Response): Promise<string> {
+ const reader = response.body?.getReader();
+ if (!reader) return '';
+ const decoder = new TextDecoder();
+ let text = '';
+ try {
+ while (text.length < SYSTEM_ORDER_PROBE_LIMIT) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ text += decoder.decode(value, { stream: true });
+ }
+ return text.slice(0, SYSTEM_ORDER_PROBE_LIMIT);
+ } catch {
+ return text.slice(0, SYSTEM_ORDER_PROBE_LIMIT);
+ } finally {
+ void reader.cancel().catch(() => undefined);
+ reader.releaseLock();
+ }
+}
+
/** Reuse the two existing translators without opening another server or forwarding client credentials. */
export function createClaudeProviderBridge(options: {
url: string;
@@ -49,7 +75,29 @@ export function createClaudeProviderBridge(options: {
...options.capabilities,
...(options.supportsFastMode ? { passthroughFields: [...(options.capabilities?.passthroughFields ?? []), 'service_tier'] } : {}),
} });
- const upstream = await options.fetchImpl(options.url, { ...init, body: JSON.stringify(normalizeProviderRequest(translated.request, { harness: 'claude-code', protocol: 'openai-chat', upstreamBase: options.url, model: responses.model }, { reasoningEffortAlreadyMapped: true })) });
+ const send = (request: typeof translated.request): Promise<Response> => options.fetchImpl(options.url, {
+ ...init,
+ body: JSON.stringify(normalizeProviderRequest(request, { harness: 'claude-code', protocol: 'openai-chat', upstreamBase: options.url, model: responses.model }, { reasoningEffortAlreadyMapped: true })),
+ });
+ let upstream = await send(translated.request);
+ // Claude Code 的 mid-conversation-system 会把 system 消息投到 user 轮次之后;
+ // 只接受开头 system 的上游(Google 的 OpenAI 兼容层、Qwen 模板运行器)会整轮 400,
+ // 且下一轮原样复现 → 会话卡死。这里与 responses-chat-bridge 的 handler 同口径重试一次:
+ // 只并到开头、只限本次请求内,显式策略与原生 developer 语义仍然优先。
+ if (!upstream.ok && options.capabilities?.systemMessagePolicy === undefined
+ && options.capabilities?.developerRole !== 'developer') {
+ // clone:不重试时错误正文要原样留给调用方(handler 读它做上游错误上报与呈现)。
+ const rejection = classifySystemOrderError(upstream.status, await readBoundedErrorText(upstream.clone()));
+ if (rejection && shouldRetrySystemNormalization(rejection, translated.request.messages)) {
+ const coalesced = coalesceLeadingSystemMessages(translated.request.messages);
+ if (coalesced !== translated.request.messages) {
+ translated.request.messages = coalesced;
+ // 首个响应被丢弃 → 立刻释放它的 body,别让废弃的连接/缓冲挂到本轮结束。
+ void upstream.body?.cancel().catch(() => undefined);
+ upstream = await send(translated.request);
+ }
+ }
+ }
if (!upstream.ok || !upstream.body) return upstream;
const translator = new ChatSseTranslator(responses.model, { toolContext: translated.toolContext });
const reader = upstream.body.getReader();
diff --git a/packages/responses-chat-bridge/src/__tests__/handler.test.ts b/packages/responses-chat-bridge/src/__tests__/handler.test.ts
index ff8f2c2fc9..78a348d2e1 100644
--- a/packages/responses-chat-bridge/src/__tests__/handler.test.ts
+++ b/packages/responses-chat-bridge/src/__tests__/handler.test.ts
@@ -40,6 +40,22 @@ function systemOrderError(status = 400, message = 'System message must be at the
return new Response(JSON.stringify({ error: { message, type: 'BadRequestError' } }), { status });
}
+/**
+ * Google 的 OpenAI 兼容层经由 AI SDK 抛出的形状:外层套一层 Responses/Anthropic 风格的
+ * error,真正的 AI SDK 错误被二次编码进 message 字符串里的一层 JSON。
+ */
+function googleSystemOrderError(): Response {
+ const functionality = "'system messages are only supported at the beginning of the conversation' functionality not supported.";
+ return new Response(JSON.stringify({
+ error: {
+ message: JSON.stringify({
+ error: { message: functionality, type: 'AI_UnsupportedFunctionalityError' },
+ }),
+ type: 'invalid_request_error',
+ },
+ }), { status: 400 });
+}
+
// Reduced shape of the real Codex capture: instructions + developer, user, user.
// Exact captured text is replayed separately against the official Qwen template.
function leadingSystemRequest(): ResponsesRequest {
@@ -241,6 +257,99 @@ describe('createResponsesChatHandler', () => {
expect(res.listenerCount('close')).toBe(0);
});
+ // Claude Code 的 mid-conversation-system(#3583 的 Google 版本):顶层 instructions 与
+ // agent 列表先进 system,随后 user 轮次之后还会再来一条 system。Google 的 OpenAI 兼容层
+ // 是会话级限制,只并前缀救不了它——必须把中段 system 一并提到开头,否则整轮 400 且下一轮
+ // 复现,会话卡死。
+ it('hoists a mid-conversation system message when the upstream only accepts a leading one', async () => {
+ const bodies: ChatCompletionsRequest[] = [];
+ const fetchImpl = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
+ bodies.push(JSON.parse(String(init?.body)));
+ if (bodies.length === 1) return googleSystemOrderError();
+ return streamResponse([{ choices: [{ delta: { content: 'hi' }, finish_reason: 'stop' }] }]);
+ });
+ const onUpstreamError = vi.fn();
+ const handler = createResponsesChatHandler({
+ upstreamBase: 'https://generativelanguage.googleapis.com/v1beta/openai',
+ buildHeaders: async () => ({}),
+ capabilities: { reasoningField: 'reasoning_effort' },
+ onUpstreamError,
+ }, { fetchImpl });
+ const res = new FakeResponse();
+ await handler.handle({
+ parsedBody: {
+ model: 'google/gemini-3.8-flash',
+ instructions: 'You are an interactive agent.',
+ input: [
+ { role: 'user', content: 'system-reminder: context' },
+ { role: 'system', content: 'Available agent types for the Agent tool' },
+ { role: 'user', content: 'hello' },
+ ],
+ },
+ res: res as never,
+ });
+ expect(fetchImpl).toHaveBeenCalledTimes(2);
+ // 中段 system 与开头 instructions 合成唯一首条 system,user 顺序保持。
+ expect(bodies[1].messages).toEqual([
+ {
+ role: 'system',
+ content: 'You are an interactive agent.\n\nAvailable agent types for the Agent tool',
+ },
+ { role: 'user', content: 'system-reminder: context' },
+ { role: 'user', content: 'hello' },
+ ]);
+ expect(res.status).toBe(200);
+ expect(res.chunks.join('')).toContain('event: response.completed');
+ });
+
+ it('does not widen the Qwen prefix retry into a mid-conversation hoist', async () => {
+ // `System message must be at the beginning.` 来自模板运行器,只约束开头连续段;
+ // 中段 system 不该被这条措辞牵着走(既有保守策略)。
+ const fetchImpl = vi.fn(async () => systemOrderError());
+ const handler = createResponsesChatHandler({
+ upstreamBase: 'https://vllm.example/v1', buildHeaders: async () => ({}),
+ }, { fetchImpl });
+ const res = new FakeResponse();
+ await handler.handle({
+ parsedBody: {
+ model: 'qwen3.8-27b-fp8',
+ instructions: 'base instructions',
+ input: [
+ { role: 'user', content: 'hello' },
+ { role: 'system', content: 'later instructions' },
+ ],
+ },
+ res: res as never,
+ });
+ expect(fetchImpl).toHaveBeenCalledOnce();
+ expect(res.status).toBe(400);
+ });
+
+ it('retries a Google leading-system rejection twice at most', async () => {
+ const fetchImpl = vi.fn(async () => googleSystemOrderError());
+ const onUpstreamError = vi.fn();
+ const handler = createResponsesChatHandler({
+ upstreamBase: 'https://generativelanguage.googleapis.com/v1beta/openai',
+ buildHeaders: async () => ({}),
+ onUpstreamError,
+ }, { fetchImpl });
+ const res = new FakeResponse();
+ await handler.handle({
+ parsedBody: {
+ model: 'google/gemini-3.8-flash',
+ instructions: 'base',
+ input: [
+ { role: 'user', content: 'hello' },
+ { role: 'system', content: 'later' },
+ ],
+ },
+ res: res as never,
+ });
+ expect(fetchImpl).toHaveBeenCalledTimes(2);
+ expect(res.status).toBe(400);
+ expect(onUpstreamError).toHaveBeenCalledOnce();
+ });
+
it.each([400, 401, 503])('reports only the final error when the compatibility retry fails with %s', async (status) => {
const fetchImpl = vi.fn()
.mockResolvedValueOnce(systemOrderError())
diff --git a/packages/responses-chat-bridge/src/handler.ts b/packages/responses-chat-bridge/src/handler.ts
index c7a28627f3..837681e272 100644
--- a/packages/responses-chat-bridge/src/handler.ts
+++ b/packages/responses-chat-bridge/src/handler.ts
@@ -7,6 +7,7 @@ import {
resolveConversationSessionHeaders,
withChatBridgeUserAgent,
} from './session-header.js';
+import { classifySystemOrderError, shouldRetrySystemNormalization } from './system-order.js';
import { coalesceLeadingSystemMessages, translateResponsesRequestWithContext } from './translate-request.js';
import {
UnsupportedResponsesFeatureError,
@@ -35,28 +36,6 @@ function classifyUpstreamErrorBody(text: string): 'empty' | 'json' | 'text' {
}
}
-function isSystemMessageOrderError(status: number, text: string): boolean {
- if (status !== 400) return false;
- try {
- const body: unknown = JSON.parse(text);
- return isPlainObject(body)
- && isPlainObject(body.error)
- && typeof body.error.message === 'string'
- && /^system message must be at the beginning\.?$/i.test(body.error.message.trim());
- } catch {
- return false;
- }
-}
-
-/** Only retry a prefix merge; moving later instructions across a turn changes their scope. */
-function hasConsecutiveSystemPrefix(messages: ChatMessage[]): boolean {
- let prefixLength = 0;
- while (messages[prefixLength]?.role === 'system') prefixLength += 1;
- return prefixLength > 1 && messages.every((message, index) => (
- index < prefixLength || (message.role !== 'system' && message.role !== 'developer')
- ));
-}
-
function writeJson(res: ServerResponse, status: number, body: unknown): void {
if (res.headersSent) return;
res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
@@ -286,15 +265,16 @@ export function createResponsesChatHandler(
upstream = await send();
if (!upstream.ok) {
upstreamErrorText = await readErrorText(upstream);
- // Qwen can reject instructions + developer even before the first user (#3583).
- // Retry only a precise pre-generation rejection, once and within this request.
- // Explicit policies and native developer-role semantics remain authoritative.
+ // 上游只允许 system 出现在开头:Qwen 拒 instructions + developer (#3583),
+ // Google 兼容层拒中段 system(Claude Code 的 mid-conversation-system 会带进来)。
+ // 只重试一次、只限本次请求内;显式策略与原生 developer 语义仍然优先。
+ const systemOrderRejection = classifySystemOrderError(upstream.status, upstreamErrorText);
if (
provider.capabilities?.systemMessagePolicy === undefined
&& provider.capabilities?.developerRole !== 'developer'
- && isSystemMessageOrderError(upstream.status, upstreamErrorText)
+ && systemOrderRejection !== null
&& !abort.signal.aborted
- && hasConsecutiveSystemPrefix(chatRequest.messages)
+ && shouldRetrySystemNormalization(systemOrderRejection, chatRequest.messages)
) {
const coalesced = coalesceLeadingSystemMessages(chatRequest.messages);
if (coalesced !== chatRequest.messages) {
diff --git a/packages/responses-chat-bridge/src/index.ts b/packages/responses-chat-bridge/src/index.ts
index b6eb6c1a5f..8870039266 100644
--- a/packages/responses-chat-bridge/src/index.ts
+++ b/packages/responses-chat-bridge/src/index.ts
@@ -1,5 +1,13 @@
export { ChatSseTranslator, type ChatSseTranslatorOptions } from './chat-sse-translator.js';
export { createResponsesChatHandler, type ResponsesChatHandlerOptions } from './handler.js';
+export {
+ classifySystemOrderError,
+ classifySystemOrderMessage,
+ hasConsecutiveSystemPrefix,
+ hasNonLeadingSystemMessage,
+ shouldRetrySystemNormalization,
+ type SystemOrderRejection,
+} from './system-order.js';
export {
CHAT_BRIDGE_USER_AGENT,
CODEX_THREAD_ID_HEADER,
@@ -9,6 +17,7 @@ export {
withChatBridgeUserAgent,
} from './session-header.js';
export {
+ coalesceLeadingSystemMessages,
translateResponsesRequest,
translateResponsesRequestWithContext,
type TranslatedResponsesChatRequest,
diff --git a/packages/responses-chat-bridge/src/system-order.ts b/packages/responses-chat-bridge/src/system-order.ts
new file mode 100644
index 0000000000..d83affea32
--- /dev/null
+++ b/packages/responses-chat-bridge/src/system-order.ts
@@ -0,0 +1,93 @@
+/**
+ * 上游拒绝「system 消息位置不合法」时的措辞识别与规范化判据。
+ *
+ * 两种上游、两种力度,混用会把既有保守策略放宽:
+ * - `'prefix'` 本地模板运行器(Ollama / Qwen 系):`System message must be at the beginning.`
+ * 模板只要求开头是一段连续的 system。把拆开的前缀并成一条即可,不动中段。
+ * - `'leading'` Google 的 OpenAI 兼容层(AI SDK 报错透传):
+ * `system messages are only supported at the beginning of the conversation`
+ * 这是**会话级**限制:任何位置出现 system 都不接受,只能全部提到最前。
+ *
+ * Claude Code 的 `mid-conversation-system` 会在 user 轮次之后持续注入 system 消息,
+ * 命中 'leading' 时不合并就整轮失败、且下一轮原样复现(会话卡死)。
+ */
+
+import type { ChatMessage } from './types.js';
+
+export type SystemOrderRejection = 'prefix' | 'leading';
+
+/**
+ * 单条 message 文本的判定。'leading' 那句常被上游二次编码成 JSON 字符串再当作
+ * message,故按子串匹配而非锚定全串。
+ */
+export function classifySystemOrderMessage(message: string): SystemOrderRejection | null {
+ const text = message.trim();
+ if (/^system message must be at the beginning\.?$/i.test(text)) return 'prefix';
+ if (/system messages? are only supported at the beginning of the conversation/i.test(text)) return 'leading';
+ return null;
+}
+
+/**
+ * 400 错误体 → 拒绝类型。message 可能是纯文本,也可能是被逐层二次编码的 JSON 字符串
+ * (Google 兼容层经 AI SDK 抛出的形状就是两层),逐层展开后判定。
+ */
+export function classifySystemOrderError(status: number, text: string): SystemOrderRejection | null {
+ if (status !== 400) return null;
+ let body: unknown;
+ try {
+ body = JSON.parse(text);
+ } catch {
+ return null;
+ }
+ for (let depth = 0; depth < 3; depth += 1) {
+ if (typeof body !== 'object' || body === null || Array.isArray(body)) return null;
+ const error = (body as Record<string, unknown>).error;
+ if (typeof error !== 'object' || error === null || Array.isArray(error)) return null;
+ const message = (error as Record<string, unknown>).message;
+ if (typeof message !== 'string') return null;
+ const rejection = classifySystemOrderMessage(message);
+ if (rejection) return rejection;
+ try {
+ body = JSON.parse(message);
+ } catch {
+ return null;
+ }
+ }
+ return null;
+}
+
+/** 只重试前缀合并:把中段指令跨轮次前移会改变它的作用域。 */
+export function hasConsecutiveSystemPrefix(messages: ChatMessage[]): boolean {
+ let prefixLength = 0;
+ while (messages[prefixLength]?.role === 'system') prefixLength += 1;
+ return prefixLength > 1 && messages.every((message, index) => (
+ index < prefixLength || (message.role !== 'system' && message.role !== 'developer')
+ ));
+}
+
+/** 合并确实会改变消息列表:system/developer 不止出现在开头,或开头就有多条。 */
+export function hasNonLeadingSystemMessage(messages: ChatMessage[]): boolean {
+ const isSystem = (message: ChatMessage): boolean => message.role === 'system' || message.role === 'developer';
+ const systems = messages.filter(isSystem).length;
+ if (systems === 0) return false;
+ const prefix = messages.findIndex((message) => !isSystem(message));
+ // 全是 system:多条才需要合并。
+ if (prefix === -1) return systems > 1;
+ return prefix > 1 || messages.slice(prefix).some(isSystem);
+}
+
+/**
+ * 是否值得按拒绝类型做一次规范化重试。
+ *
+ * 'prefix' 沿用既有保守策略,只并连续前缀。'leading' 是会话级拒绝,中段 system 不合并
+ * 就整轮失败、会话卡死;此时把 system/developer 全部提到开头,代价是作用域前移,
+ * 换来用户还能继续对话。
+ */
+export function shouldRetrySystemNormalization(
+ rejection: SystemOrderRejection,
+ messages: ChatMessage[],
+): boolean {
+ return rejection === 'prefix'
+ ? hasConsecutiveSystemPrefix(messages)
+ : hasNonLeadingSystemMessage(messages);
+}