fix：解决使用claude code发起请求是422问题

[Echoxiawan]

Claude Code 接入问题修复说明

问题1：Claude Code 发起请求返回 422

根本原因

AnthropicMessage.role 字段被定义为：

Literal["user", "assistant"]

但 Claude Code 实际发送的请求中，messages 数组包含：

{
  "role": "system",
  "content": "..."
}

由于 system 不在允许范围内，触发 FastAPI + Pydantic 参数校验失败，返回：

422 Unprocessable Entity

---

修复内容

1. models_anthropic.py

文件位置：

kiro/models_anthropic.py:190

修改前：

role: Literal["user", "assistant"]

修改后：

role: str

允许接收任意角色值（包括 system）。

---

2. converters_anthropic.py

文件位置：

kiro/converters_anthropic.py:453-478

在 anthropic_to_kiro() 中增加预处理逻辑：

• 遍历 messages
• 提取所有 role == "system" 的消息
• 将其内容追加到最终的 System Prompt
• 其余消息继续按原逻辑转换

伪代码：

system_messages = []
normal_messages = []

for msg in messages:
    if msg.role == "system":
        system_messages.append(msg.content)
    else:
        normal_messages.append(msg)

system_prompt += "\n".join(system_messages)

---

修复效果

• Claude Code 的 system 消息不再触发 422
• system 内容能够正确合并到系统提示词中
• 不会破坏 Kiro API 对消息格式的要求
• 对现有客户端完全兼容

---

问题2：Claude Code Web Search 历史导致 422

问题描述

当 Claude Code 对话历史中包含 Anthropic 服务端工具（Web Search）的调用记录时，网关返回：

422 Unprocessable Entity

请求无法继续处理。

---

根本原因

Claude Code 会在：

messages[].content

中携带服务端工具相关内容块。

典型类型包括：

1. server_tool_use

助手发起 Web Search：

{
  "type": "server_tool_use",
  "name": "web_search",
  ...
}

2. web_search_tool_result

搜索结果返回：

{
  "type": "web_search_tool_result",
  ...
}

---

而当前模型定义：

ContentBlock

仅支持以下类型：

text
thinking
image
tool_use
tool_result
tool_reference

即：

Union[
    TextContentBlock,
    ThinkingContentBlock,
    ImageContentBlock,
    ToolUseContentBlock,
    ToolResultContentBlock,
    ToolReferenceContentBlock
]

对于：

server_tool_use
web_search_tool_result

完全无法识别。

因此 Pydantic 在解析 ContentBlock Union 时直接失败，最终返回：

422

---

修复内容

1. 新增服务端工具内容块模型

文件：

kiro/models_anthropic.py

新增：

ServerToolUseContentBlock

用于支持：

{
  "type": "server_tool_use"
}

---

新增：

WebSearchToolResultContentBlock

用于支持：

{
  "type": "web_search_tool_result"
}

---

2. 增加未知类型兜底模型

新增：

UnknownContentBlock

定义：

class UnknownContentBlock(BaseModel):
    type: str

    class Config:
        extra = "allow"

特点：

• 接受任意未知 type
• 保留原始字段
• 不阻断请求处理

---

3. 更新 ContentBlock Union

修改后：

ContentBlock = Union[
    TextContentBlock,
    ThinkingContentBlock,
    ImageContentBlock,
    ToolUseContentBlock,
    ToolResultContentBlock,
    ToolReferenceContentBlock,
    ServerToolUseContentBlock,
    WebSearchToolResultContentBlock,
    UnknownContentBlock
]

其中：

UnknownContentBlock

放在最后。

---

为什么不会丢失信息

转换逻辑：

converters_anthropic.py

本身采用：

content.type

进行显式匹配处理。

当前仅消费：

text
tool_use
tool_result
image

对于无法识别的类型：

continue

直接忽略。

---

Claude Code 的特殊行为

在每个：

{
  "type": "web_search_tool_result"
}

之后，Claude Code 还会附带：

{
  "type": "text",
  "text": "搜索结果内容..."
}

因此：

• 搜索结果实际上已被序列化为文本块
• 下游真正消费的是 text
• 即使忽略服务端工具块本身，也不会丢失搜索内容

---

最终效果

修复后：

server_tool_use
web_search_tool_result

能够通过模型校验。

转换器继续读取后续：

text

内容。

因此：

• 不再出现 422
• 搜索结果仍然完整保留
• 下游行为与 Claude 原生一致

---

测试覆盖

新增测试类：

TestServerToolContentBlocks

覆盖内容：

1. 服务端工具块解析

验证：

server_tool_use
web_search_tool_result

能够正确通过校验。

---

2. UnknownContentBlock 兜底能力

验证未来新增类型，例如：

code_execution
computer_use
memory_tool

不会再次导致：

422

---

3. 端到端验证

构造与 Claude Code 实际请求一致的 Payload：

{
  "messages": [
    ...
  ]
}

验证：

• Union 能解析到正确具体类型
• 不会落入错误分支
• 请求能够正常通过模型校验

---

测试结果

通过：

test_models_anthropic.py

共：

95 项测试

全部通过。

同时：

test_converters_anthropic.py

全部通过。

无新增失败用例。

---

注意事项

本次修复属于 Claude Code Payload 兼容性增强。

修复目标：

1. 支持 role: "system" 消息
2. 支持 Anthropic 服务端工具内容块
3. 为未来新增内容块提供兜底能力
4. 避免因 Pydantic 严格校验导致的 422 错误

兼容性：

• 向后兼容现有客户端
• 不影响 Kiro 下游消息转换逻辑
• 不改变模型实际推理行为
• 提升 Claude Code 与 Anthropic 官方协议的兼容性

[cla-bot]

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: ryan.liu.
This is most likely caused by a git client misconfiguration; please make sure to:

1. check if your git client is configured with an email to sign commits git config --list | grep email
2. If not, set it up using git config --global user.email email@example.com
3. Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

[Echoxiawan]

解决bug #190

[cla-bot]

Thanks for the PR! 🎉

Before merge, we need a one-time CLA confirmation.
It confirms that you have the right to contribute this code and allow the project to use it.

Full CLA text:
https://github.com/jwadow/kiro-gateway/blob/main/CLA.md

Please reply once with:

I have read the CLA and I accept its terms

You need to write once, all further messages from me can be ignored.

[Echoxiawan]

I have read the CLA and I accept its terms

[Echoxiawan]

Thanks for the PR! 🎉

Before merge, we need a one-time CLA confirmation. It confirms that you have the right to contribute this code and allow the project to use it.

Full CLA text: https://github.com/jwadow/kiro-gateway/blob/main/CLA.md

Please reply once with:

I have read the CLA and I accept its terms

You need to write once, all further messages from me can be ignored.

I have read the CLA and I accept its terms

[cla-bot]

Thanks for the PR! 🎉

Before merge, we need a one-time CLA confirmation.
It confirms that you have the right to contribute this code and allow the project to use it.

Full CLA text:
https://github.com/jwadow/kiro-gateway/blob/main/CLA.md

Please reply once with:

I have read the CLA and I accept its terms

You need to write once, all further messages from me can be ignored.