fix(llm): 🐛 修复 max_tokens 为无效值时导致的 API 错误 (#45)

修复所有 LLM 客户端中 maxTokens 检查逻辑，避免将无效值
(0, null, undefined) 传递给 API 导致错误。

问题：当 maxTokens 为 0 或 null 时，原代码 !== undefined
判断为 true，导致 API 报错 "max_tokens: must be greater than or equal to 1"

修复：将检查条件改为确保 maxTokens 是大于 0 的有效数字：
- AnthropicClient.ts
- OpenAIClient.ts
- GeminiClient.ts
- OpenAIResponsesClient.ts
- OllamaClient.ts

更新 AnthropicClient 测试以匹配新的 system 消息格式。

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jorben

src/core/infrastructure/adapters/llm/AnthropicClient.ts

@@ -40,28 +40,40 @@ export class AnthropicClient extends LLMClient {
         stream: normalizedOptions.stream || false
       };
 
-      // 只在提供了 maxTokens 时才添加到请求体
-      if (normalizedOptions.maxTokens !== undefined) {
+      // 只在提供了有效的 maxTokens 时才添加到请求体
+      if (normalizedOptions.maxTokens && normalizedOptions.maxTokens > 0) {
         requestBody.max_tokens = normalizedOptions.maxTokens;
       }
 
-      // Anthropic支持System指令，而不是作为一个普通消息
+      // Anthropic支持System指令，使用对象数组格式支持 cache_control
       const systemMessage = normalizedOptions.messages.find(msg => msg.role === 'system');
+      let systemText = '';
       if (systemMessage) {
-        const systemContent = Array.isArray(systemMessage.content)
+        systemText = Array.isArray(systemMessage.content)
           ? systemMessage.content.filter(c => c.type === 'text').map(c => (c as TextContent).text).join('\n')
           : systemMessage.content.type === 'text' ? (systemMessage.content as TextContent).text : '';
+      }
 
-        if (systemContent) {
-          requestBody.system = systemContent;
+      // Claude没有直接的JSON响应格式，但可以通过系统指令引导
+      if (normalizedOptions.response_format?.type === 'json_object') {
+        if (!systemText) {
+          systemText = "请以有效的JSON格式提供响应。";
+        } else {
+          systemText += "\n\n请以有效的JSON格式提供响应。";
         }
       }
 
-      // Claude没有直接的JSON响应格式，但可以通过系统指令引导
-      if (normalizedOptions.response_format?.type === 'json_object' && !requestBody.system) {
-        requestBody.system = "请以有效的JSON格式提供响应。";
-      } else if (normalizedOptions.response_format?.type === 'json_object' && requestBody.system) {
-        requestBody.system += "\n\n请以有效的JSON格式提供响应。";
+      // 使用对象数组格式，支持 cache_control
+      if (systemText) {
+        requestBody.system = [
+          {
+            type: 'text',
+            text: systemText,
+            cache_control: {
+              type: 'ephemeral'
+            }
+          }
+        ];
       }
 
       const response = await fetch(endpoint, {

src/core/infrastructure/adapters/llm/GeminiClient.ts

@@ -39,8 +39,8 @@ export class GeminiClient extends LLMClient {
         }
       };
 
-      // 只在提供了 maxTokens 时才添加到请求体
-      if (normalizedOptions.maxTokens !== undefined) {
+      // 只在提供了有效的 maxTokens 时才添加到请求体
+      if (normalizedOptions.maxTokens && normalizedOptions.maxTokens > 0) {
         requestBody.generationConfig.maxOutputTokens = normalizedOptions.maxTokens;
       }
 

src/core/infrastructure/adapters/llm/OllamaClient.ts

@@ -41,7 +41,8 @@ export class OllamaClient extends LLMClient {
         requestBody.options.temperature = normalizedOptions.temperature;
       }
 
-      if (normalizedOptions.maxTokens !== undefined) {
+      // 只在提供了有效的 maxTokens 时才添加到请求体
+      if (normalizedOptions.maxTokens && normalizedOptions.maxTokens > 0) {
         requestBody.options.num_predict = normalizedOptions.maxTokens;
       }
 

src/core/infrastructure/adapters/llm/OpenAIClient.ts

@@ -37,8 +37,8 @@ export class OpenAIClient extends LLMClient {
         stream: normalizedOptions.stream || false
       };
 
-      // 只在提供了 maxTokens 时才添加到请求体
-      if (normalizedOptions.maxTokens !== undefined) {
+      // 只在提供了有效的 maxTokens 时才添加到请求体
+      if (normalizedOptions.maxTokens && normalizedOptions.maxTokens > 0) {
         requestBody.max_tokens = normalizedOptions.maxTokens;
       }
 

src/core/infrastructure/adapters/llm/OpenAIResponsesClient.ts

@@ -38,8 +38,8 @@ export class OpenAIResponsesClient extends LLMClient {
         stream: normalizedOptions.stream || false
       };
 
-      // 只在提供了 maxTokens 时才添加到请求体
-      if (normalizedOptions.maxTokens !== undefined) {
+      // 只在提供了有效的 maxTokens 时才添加到请求体
+      if (normalizedOptions.maxTokens && normalizedOptions.maxTokens > 0) {
         requestBody.max_tokens = normalizedOptions.maxTokens;
       }
 

src/core/infrastructure/adapters/llm/__tests__/AnthropicClient.test.ts

@@ -67,7 +67,13 @@ describe('AnthropicClient', () => {
       const callArgs = (global.fetch as any).mock.calls[0][1]
       const body = JSON.parse(callArgs.body)
 
-      expect(body.system).toBe('You are a helpful assistant')
+      expect(body.system).toEqual([
+        {
+          type: 'text',
+          text: 'You are a helpful assistant',
+          cache_control: { type: 'ephemeral' }
+        }
+      ])
       expect(body.messages).toHaveLength(1)
       expect(body.messages[0].role).toBe('user')
     })
@@ -148,7 +154,13 @@ describe('AnthropicClient', () => {
       const callArgs = (global.fetch as any).mock.calls[0][1]
       const body = JSON.parse(callArgs.body)
 
-      expect(body.system).toContain('JSON')
+      expect(body.system).toEqual([
+        {
+          type: 'text',
+          text: '请以有效的JSON格式提供响应。',
+          cache_control: { type: 'ephemeral' }
+        }
+      ])
     })
 
     it('should append JSON instruction to existing system prompt', async () => {
@@ -173,8 +185,13 @@ describe('AnthropicClient', () => {
       const callArgs = (global.fetch as any).mock.calls[0][1]
       const body = JSON.parse(callArgs.body)
 
-      expect(body.system).toContain('You are helpful')
-      expect(body.system).toContain('JSON')
+      expect(body.system).toEqual([
+        {
+          type: 'text',
+          text: 'You are helpful\n\n请以有效的JSON格式提供响应。',
+          cache_control: { type: 'ephemeral' }
+        }
+      ])
     })
   })