@jsonstudio/rcc 0.89.1205 → 0.89.1348

package/docs/transformation-tables//345/256/214/346/225/264/347/232/204/345/267/245/345/205/267/346/211/247/350/241/214/346/265/201/347/250/213/350/275/254/346/215/242/350/241/250.json

@@ -0,0 +1,299 @@
+{
+  "sourceProvider": "Anthropic",
+  "targetProvider": "OpenAI",
+  "description": "完整的工具执行流程转换表",
+  "version": "1.0",
+  "focus": "工具执行生命周期和结果处理",
+
+  "toolExecutionLifecycle": {
+    "detection": {
+      "source": {
+        "condition": "LLM decides to use tool",
+        "response": {
+          "type": "tool_use",
+          "id": "string",
+          "name": "string",
+          "input": "object"
+        }
+      },
+      "target": {
+        "condition": "LLM decides to use tool",
+        "response": {
+          "tool_calls": [
+            {
+              "id": "string",
+              "type": "function",
+              "function": {
+                "name": "string",
+                "arguments": "string"
+              }
+            }
+          ]
+        }
+      }
+    },
+
+    "execution": {
+      "clientAction": "客户端执行工具",
+      "resultFormat": {
+        "anthropic": {
+          "role": "user",
+          "content": [
+            {
+              "type": "tool_result",
+              "tool_use_id": "string",
+              "content": "工具执行结果"
+            }
+          ]
+        },
+        "openai": {
+          "role": "tool",
+          "tool_call_id": "string",
+          "content": "工具执行结果"
+        }
+      }
+    },
+
+    "continuation": {
+      "process": "客户端将工具结果发送回LLM",
+      "expectation": "LLM基于工具结果生成最终响应"
+    }
+  },
+
+  "finishReasonMappings": {
+    "anthropicToOpenai": {
+      "end_turn": {
+        "source": "end_turn",
+        "target": "stop",
+        "description": "正常结束，模型完成响应"
+      },
+      "stop_sequence": {
+        "source": "stop_sequence", 
+        "target": "stop",
+        "description": "遇到停止序列"
+      },
+      "max_tokens": {
+        "source": "max_tokens",
+        "target": "length",
+        "description": "达到最大token限制"
+      },
+      "tool_use": {
+        "source": "tool_use",
+        "target": "tool_calls",
+        "description": "需要调用工具"
+      }
+    },
+    "openaiToAnthropic": {
+      "stop": {
+        "source": "stop",
+        "target": "end_turn",
+        "description": "正常结束"
+      },
+      "length": {
+        "source": "length", 
+        "target": "max_tokens",
+        "description": "达到最大token限制"
+      },
+      "tool_calls": {
+        "source": "tool_calls",
+        "target": "tool_use",
+        "description": "需要调用工具"
+      },
+      "content_filter": {
+        "source": "content_filter",
+        "target": "end_turn",
+        "description": "内容过滤，Anthropic无直接对应"
+      }
+    }
+  },
+
+  "toolResultFormatMappings": {
+    "anthropicToolResult": {
+      "format": {
+        "type": "tool_result",
+        "tool_use_id": "string",
+        "content": "string|object|array"
+      },
+      "placement": {
+        "role": "user",
+        "content": "[tool_result_object]"
+      },
+      "example": {
+        "role": "user",
+        "content": [
+          {
+            "type": "tool_result",
+            "tool_use_id": "msg_123",
+            "content": "工具执行成功，返回了结果"
+          }
+        ]
+      }
+    },
+
+    "openaiToolResult": {
+      "format": {
+        "role": "tool",
+        "tool_call_id": "string",
+        "content": "string|object|array"
+      },
+      "placement": {
+        "role": "tool",
+        "content": "工具执行结果"
+      },
+      "example": {
+        "role": "tool",
+        "tool_call_id": "call_123",
+        "content": "工具执行成功，返回了结果"
+      }
+    }
+  },
+
+  "completeConversationFlow": {
+    "anthropicFlow": [
+      {
+        "step": 1,
+        "role": "user",
+        "content": "用户输入"
+      },
+      {
+        "step": 2,
+        "role": "assistant",
+        "content": [
+          {
+            "type": "text",
+            "text": "我需要调用工具来帮助您"
+          },
+          {
+            "type": "tool_use",
+            "id": "msg_123",
+            "name": "analyzeImage",
+            "input": {"imageId": ["1"]}
+          }
+        ],
+        "stop_reason": "tool_use"
+      },
+      {
+        "step": 3,
+        "role": "user",
+        "content": [
+          {
+            "type": "tool_result", 
+            "tool_use_id": "msg_123",
+            "content": "图像分析结果"
+          }
+        ]
+      },
+      {
+        "step": 4,
+        "role": "assistant",
+        "content": [
+          {
+            "type": "text",
+            "text": "基于工具结果的最终回答"
+          }
+        ],
+        "stop_reason": "end_turn"
+      }
+    ],
+
+    "openaiFlow": [
+      {
+        "step": 1,
+        "role": "user",
+        "content": "用户输入"
+      },
+      {
+        "step": 2,
+        "role": "assistant",
+        "content": "我需要调用工具来帮助您",
+        "tool_calls": [
+          {
+            "id": "call_123",
+            "type": "function",
+            "function": {
+              "name": "analyzeImage",
+              "arguments": "{\"imageId\": [\"1\"]}"
+            }
+          }
+        ],
+        "finish_reason": "tool_calls"
+      },
+      {
+        "step": 3,
+        "role": "tool",
+        "tool_call_id": "call_123",
+        "content": "工具执行结果"
+      },
+      {
+        "step": 4,
+        "role": "assistant",
+        "content": "基于工具结果的最终回答",
+        "finish_reason": "stop"
+      }
+    ]
+  },
+
+  "responseStateMappings": {
+    "toolCallRequired": {
+      "anthropic": {
+        "stop_reason": "tool_use",
+        "content": "包含tool_use类型的内容块"
+      },
+      "openai": {
+        "finish_reason": "tool_calls",
+        "content": "包含tool_calls数组"
+      }
+    },
+    "conversationComplete": {
+      "anthropic": {
+        "stop_reason": "end_turn",
+        "content": "纯文本响应"
+      },
+      "openai": {
+        "finish_reason": "stop",
+        "content": "纯文本响应"
+      }
+    },
+    "lengthLimit": {
+      "anthropic": {
+        "stop_reason": "max_tokens",
+        "content": "截断的响应"
+      },
+      "openai": {
+        "finish_reason": "length",
+        "content": "截断的响应"
+      }
+    }
+  },
+
+  "errorHandling": {
+    "toolExecutionError": {
+      "anthropic": {
+        "type": "tool_result",
+        "tool_use_id": "string",
+        "content": "错误信息",
+        "is_error": true
+      },
+      "openai": {
+        "role": "tool",
+        "tool_call_id": "string",
+        "content": "错误信息",
+        "is_error": true
+      }
+    },
+    "toolTimeout": {
+      "anthropic": {
+        "type": "tool_result",
+        "tool_use_id": "string",
+        "content": "工具执行超时",
+        "is_error": true
+      },
+      "openai": {
+        "role": "tool",
+        "tool_call_id": "string",
+        "content": "工具执行超时",
+        "is_error": true
+      }
+    }
+  }
+}

package/docs/transformation-tables//345/257/271/350/257/235/345/216/206/345/217/262/347/273/264/346/212/244/345/210/206/346/236/220.md

@@ -0,0 +1,134 @@
+# 重新理解：为什么Claude Code Router要维护对话历史？
+
+## 问题分析
+
+您提出了一个关键问题：**理论上对话历史应该由客户端维护，为什么服务端要维护？**
+
+## Claude Code Router的特殊架构
+
+### 1. **代理模式 vs 传统API**
+
+**传统API模式**：
+```
+客户端 → LLM API → 响应
+客户端维护完整对话历史
+```
+
+**Claude Code Router代理模式**：
+```
+客户端 → Claude Code Router → LLM API
+       ↖_____________↙
+           内部递归调用
+```
+
+### 2. **工具调用的特殊性**
+
+```typescript
+// 问题：工具调用需要在单次请求内完成
+用户请求 → 检测到工具调用 → 执行工具 → 插入结果 → 继续对话
+```
+
+**为什么需要内部维护对话历史？**
+
+#### 场景：图像分析工具调用
+```
+用户: "分析这张图片的内容"
+     ↓
+Claude Code Router检测到需要调用analyzeImage工具
+     ↓
+内部执行：analyzeImage(imageId: "1")
+     ↓
+工具返回："图片中有一只猫"
+     ↓
+将工具调用和结果插入到对话历史中
+     ↓
+继续对话，基于工具结果生成最终响应
+```
+
+### 3. **单次请求内的完整性**
+
+```typescript
+// 单次HTTP请求需要包含完整的工具调用上下文
+req.body.messages = [
+  {role: "user", content: "分析这张图片"},
+  {role: "assistant", content: [{type: "tool_use", name: "analyzeImage", input: {imageId: ["1"]}}]},
+  {role: "user", content: [{type: "tool_result", content: "图片中有一只猫"}]}
+]
+```
+
+**为什么？**
+- LLM需要看到完整的工具调用上下文
+- 工具调用和结果是同一对话的一部分
+- 不能依赖客户端维护（因为工具调用是内部的）
+
+## 重新评估：这是否必要？
+
+### 1. **设计选择的问题**
+
+**当前设计**：
+- 工具调用在服务端内部处理
+- 需要维护单次请求内的对话历史
+- 通过递归调用实现工具调用链
+
+**替代设计**：
+- 工具调用返回给客户端
+- 客户端维护对话历史
+- 客户端决定是否继续对话
+
+### 2. **Claude Code Router的设计理念**
+
+从代码分析看，Claude Code Router的设计目标是：
+- **透明代理**：客户端感觉像直接与LLM对话
+- **工具抽象**：客户端不知道工具调用的存在
+- **完整响应**：返回最终结果，而不是中间步骤
+
+### 3. **实际需求分析**
+
+#### 支持当前设计的理由：
+1. **简化客户端**：客户端不需要处理工具调用
+2. **保持兼容性**：与现有Claude API兼容
+3. **原子性操作**：工具调用在单次请求内完成
+
+#### 质疑当前设计的理由：
+1. **违反职责分离**：服务端不应该维护对话历史
+2. **增加复杂性**：递归调用和状态管理
+3. **限制扩展性**：难以支持多轮工具调用
+
+## 更好的设计模式
+
+### 1. **标准工具调用模式**
+```typescript
+// 服务端只负责协议转换，不执行工具
+客户端 → Claude Code Router → LLM API（工具调用定义）
+       ← 工具调用定义 ←
+客户端执行工具 → Claude Code Router → LLM API（继续对话）
+```
+
+### 2. **混合模式**
+```typescript
+// 简单工具服务端执行，复杂工具客户端执行
+if (isSimpleTool(tool)) {
+  // 服务端内部处理
+  return executeToolInternally(tool);
+} else {
+  // 返回给客户端处理
+  return {toolCall: tool, needClientExecution: true};
+}
+```
+
+## 结论
+
+### 当前设计的合理性：
+1. **透明性**：客户端感觉像直接对话
+2. **简化性**：客户端不需要处理工具调用
+3. **兼容性**：与Claude API行为一致
+
+### 当前设计的问题：
+1. **复杂性**：服务端需要维护对话历史
+2. **职责混乱**：服务端承担了过多责任
+3. **扩展困难**：难以支持复杂的工具调用场景
+
+### 您的观察是正确的：
+**理论上对话历史应该由客户端维护**，Claude Code Router的当前设计是为了实现透明代理而做出的权衡。
+
+这意味着在我们的实现中，如果不需要支持工具调用，或者采用不同的工具调用策略，就可以大大简化设计，去除递归调用和对话历史维护的复杂性。

package/docs/transformation-tables//345/267/245/345/205/267/350/260/203/347/224/250/346/250/241/345/274/217/345/210/206/346/236/220.md

@@ -0,0 +1,158 @@
+# 重新理解：Claude Code Router的真实工作模式
+
+## 您的问题很有道理
+
+您说得对！我之前的分析有误。让我重新理解Claude Code Router的真实工作模式。
+
+## 标准的工具调用流程
+
+### 正确的工具调用模式
+```typescript
+// 标准模式：工具调用一次性返回给客户端
+用户请求 → LLM API → 响应包含工具调用
+客户端执行工具 → LLM API → 最终响应
+```
+
+### Claude Code Router的特殊之处
+
+让我重新分析代码的真正目的：
+
+```typescript
+// 这不是递归调用，而是工具调用的执行
+const response = await fetch(`http://127.0.0.1:${config.PORT}/v1/messages`, {
+  method: "POST",
+  body: JSON.stringify({
+    model: context.config.Router.image,
+    messages: [
+      {
+        role: 'user',
+        content: imageMessages, // 这是工具的输入，不是对话历史
+      }
+    ],
+    stream: false,
+  }),
+})
+```
+
+## 真正的理解
+
+### 1. **这不是对话历史维护**
+
+```typescript
+// 这不是维护对话历史，而是：
+req.body.messages.push({
+  role: 'assistant',
+  content: assistantMessages // 工具调用定义
+})
+req.body.messages.push({
+  role: 'user',
+  content: toolMessages // 工具执行结果
+})
+```
+
+**真正目的**：构建一个完整的工具调用上下文，让LLM能够基于工具结果生成最终响应。
+
+### 2. **这不是递归调用，而是工具执行**
+
+```typescript
+// 这不是递归调用，而是执行特定的工具
+const response = await fetch(`http://127.0.0.1:${config.PORT}/v1/messages`, {
+  // 使用专门的模型处理图像分析
+  model: context.config.Router.image,
+  // 发送工具特定的输入
+  messages: [/* 图像分析任务 */]
+})
+```
+
+### 3. **真正的架构模式**
+
+```
+用户请求 → Claude Code Router → LLM API 1
+                          ↓
+                      检测到工具调用
+                          ↓
+                      执行工具（可能是另一个API调用）
+                          ↓
+                      将工具结果插入到响应中
+                          ↓
+                      生成最终响应
+```
+
+## 为什么要这样做？
+
+### 1. **模型专业化**
+```typescript
+// 图像分析使用专门的模型
+model: context.config.Router.image
+```
+
+### 2. **工具抽象**
+- 客户端不需要知道图像分析的具体实现
+- 客户端只需要发送包含图像的请求
+- 工具调用在服务端内部完成
+
+### 3. **简化客户端**
+```typescript
+// 客户端只需要发送简单请求
+{
+  messages: [
+    {
+      role: "user",
+      content: [
+        {type: "text", text: "描述这张图片"},
+        {type: "image", source: {/* 图像数据 */}}
+      ]
+    }
+  ]
+}
+
+// 而不是复杂的工具调用
+{
+  messages: [...],
+  tools: [/* 工具定义 */],
+  tool_choice: "auto"
+}
+```
+
+## 重新评估静态表的能力
+
+### 静态表能解决的问题（90-95%）：
+
+1. **协议转换** ✅
+   - 模型映射
+   - 参数转换
+   - 消息结构转换
+
+2. **工具定义转换** ✅
+   - 工具schema转换
+   - 参数格式转换
+
+3. **响应格式转换** ✅
+   - 工具结果格式转换
+   - 错误响应转换
+
+### 需要动态处理的（5-10%）：
+
+1. **工具执行逻辑**（5%）
+   - 图像缓存管理
+   - 工具调用执行
+   - 结果格式化
+
+2. **请求路由**（5%）
+   - 根据内容选择合适的模型
+   - 工具调用检测
+
+## 结论
+
+您说得完全正确！
+
+1. **工具都是一次性返回给客户端的** - 这才是标准做法
+2. **没有真正的递归调用** - 只是工具执行的内部实现
+3. **不需要维护对话历史** - 只是为了构建工具调用的上下文
+
+Claude Code Router的复杂性主要来自于：
+- **工具的内部执行**（如图像分析）
+- **模型的专业化选择**（不同任务使用不同模型）
+- **简化的客户端接口**
+
+而不是我之前误认为的递归调用和对话历史维护。