# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## ⚠️ 重要注意事项 - 2025-09-24 更新 ### Git Diff 单文件约束 **重要**: 使用 `git diff` 或类似命令查看文件更改时，**必须每次只检查一个文件**，避免执行问题。 ✅ **正确示例**: ```bash git diff file1.py git diff file2.py ``` ❌ **错误示例**: ```bash git diff file1.py file2.py # 这会导致执行失败！ ``` ### 已知问题和解决方案 - **空 content 错误**: 已修复 - 工具调用展开时使用空字符串而非 None - **工具调用序列不完整**: 已添加自动清理逻辑 - **长文本响应中断**: 已实现智能分段（每段 1000 字符） - **上下文重置**: 会自动提供任务延续提示 详细故障排查请参考：[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) ## 执行原则（强制） - 读→改→再读验证（Read→Edit→Read）：进行任何文件修改前，必须先 Read 获取最新内容；完成 Edit 后，必须再次 Read 验证变更已生效且未误伤其它位置。 - 单点精确替换：使用唯一且完整的旧片段作为锚点进行替换，避免大范围模糊替换导致串改。 - 失败即复核：遇到 Edit 失败或不匹配，先 Read 核对真实文件内容，再调整旧片段后重试，直至验证通过。 ### 文件更新操作提示词与规范（强制） - 工具约束与常见原因 - Edit 失败的常见原因： 1) old_string 与文件内容不完全一致（换行/空格/缩进/标点差异） 2) old_string 在文件中出现多处（非唯一），需要提供更大上下文或启用 replace_all 3) 先前未 Read，导致基于过期上下文构造的 old_string - Edit 工具要求： - old_string 必须与文件中目标文本逐字符匹配（不含行号前缀） - 默认只替换首个匹配；若匹配不唯一且需全部替换，应设置 replace_all=true - 推荐操作流程 1) Read 目标文件，定位精确锚点（尽量包含上下文以确保唯一性） 2) 构造 Edit： - old_string：粘贴文件中“完整且唯一”的原始文本片段（保持缩进与空白） - new_string：仅替换需要的内容，其余保持不动 - 如需多处同样替换，使用 replace_all=true 3) Read 再次验证变更：对目标行前后各读取若干行，确认已生效且未误伤 - 提示词模板 - 单点替换（推荐）： 「我将先 Read 文件，随后用 Edit 以‘唯一锚点片段’进行精确替换，完成后再 Read 验证。」 - 批量替换： 「该文本在文件中出现 N 处，需要全量替换，我将使用 replace_all=true，并在完成后 Read 检查所有位置。」 - 失败处理： 「Edit 失败/不匹配。我将重新 Read 获取最新内容，调整 old_string 的上下文后重试，直至验证通过。」 ## 项目概述 Warp2Api 是一个基于 Python 的桥接服务，为 Warp AI 服务提供多种 API 兼容性。该项目采用双服务器架构，通过 protobuf 与 Warp AI 服务通信，同时为客户端提供多种兼容的 API 接口。 **核心特点**： - 无需预填 token，程序自动获取匿名访问令牌（50次调用额度） - **双 API 支持**：同时支持 OpenAI Chat Completions API 和 Anthropic Messages API - 支持 system prompt 和 function calling（通过 MCP 兼容） - 采用"偷梁换柱"方式处理历史消息和工具调用 - **完整格式转换**：支持 OpenAI ↔ Anthropic 格式双向转换 - 支持多模态数据包（可进一步开发） - **流式响应兼容**：支持两种 API 格式的流式响应 ## 常用命令 ### 开发环境启动 ```bash # 安装依赖（推荐使用 uv） uv sync # 启动 Protobuf 桥接服务器 (端口 8000) - 必须先启动 python server.py # 或使用项目脚本 warp-server # 启动 API 服务器 (端口 8010) - 支持 OpenAI 和 Anthropic 格式 - 需要等待"热身"完成 python openai_compat.py # 注意：pyproject.toml 中的 warp-test 脚本配置有误，应该指向 openai_compat:main ``` ### 健康检查 ```bash # 检查 Protobuf 桥接服务器 curl http://localhost:8000/healthz # 检查 API 服务器 curl http://localhost:8010/healthz ``` ### 测试 API ```bash # 测试 OpenAI Chat Completions 端点 curl -X POST http://localhost:8010/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-sonnet", "messages": [{"role": "user", "content": "Hello"}], "stream": true }' # 测试 Anthropic Messages 端点 curl -X POST http://localhost:8010/v1/messages \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-sonnet-20241022", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}], "stream": true }' ``` ### 代码质量检查 ```bash # 项目使用 uv 管理依赖，暂无配置的 lint 或 test 命令 # 可以手动运行基本的 Python 语法检查 python -m py_compile server.py openai_compat.py # 检查项目依赖 uv tree ``` ## 架构概览 ### 双服务器架构 项目采用分层架构设计，包含两个主要服务器： 1. **Protobuf 桥接服务器** (`server.py`, 端口 8000) - 处理与 Warp AI 服务的 protobuf 通信 - 提供 JSON ↔ Protobuf 编解码服务 - 包含 WebSocket 监控功能 - 管理 JWT 认证和令牌刷新 - 解析 `server_message_data` 字段（Base64URL → 结构化对象） 2. **多格式 API 服务器** (`openai_compat.py`, 端口 8010) - 提供 OpenAI Chat Completions API 兼容接口 - **新增 Anthropic Messages API 兼容接口** - 处理客户端请求并转换为 protobuf 格式 - 支持两种格式的流式响应 (SSE) - 实现消息重排序和格式转换 - **双向格式转换**：OpenAI ↔ Anthropic 自动转换 - 启动时需要"热身"请求 ### 核心模块结构 #### `protobuf2openai/` - 多格式 API 兼容层 - `app.py` - FastAPI 应用主入口，包含启动健康检查 - `router.py` - API 路由定义，处理 `/v1/chat/completions` 和 `/v1/messages` 端点 - `models.py` - Pydantic 数据模型，定义 OpenAI 和 Anthropic API 兼容的数据结构 - **`anthropic_converter.py` - Anthropic ↔ OpenAI 格式转换器** - **`anthropic_sse_transform.py` - Anthropic 格式流式响应处理器** - `bridge.py` - 桥接逻辑，连接多格式 API 和 Protobuf 服务 - `sse_transform.py` - OpenAI 格式服务器发送事件 (SSE) 流式响应处理 - `reorder.py` - 消息重排序逻辑，适配 Anthropic 风格对话 - `config.py` - 配置管理，读取环境变量和设置 - `packets.py` - 核心转换逻辑，处理消息格式转换 - `helpers.py` - 辅助函数，处理内容格式化 #### `warp2protobuf/` - Warp Protobuf 通信层 - `api/` - API 路由和处理逻辑 - `core/` - 核心功能模块 - `auth.py` - JWT 认证管理，包括匿名令牌获取、刷新和验证 - `protobuf_utils.py` - Protobuf 编解码工具函数 - `logging.py` - 日志配置和管理 - `schema_sanitizer.py` - 输入模式清理和验证 - `session.py` - 会话管理 - `protobuf.py` - Protobuf 运行时管理 - `server_message_data.py` - server_message_data 字段解析 - `config/` - 配置文件和设置 - `warp/` - Warp 特定的通信逻辑 ### 数据流架构 ``` 客户端应用 → 多格式 API 服务器 → Protobuf 桥接服务器 → Warp AI 服务 (8010端口) (FastAPI) (Protobuf处理) (Warp服务) ↓ ↓ OpenAI/Anthropic 格式 ←→ Protobuf JSON格式 ←→ Protobuf二进制 ↕ 格式自动转换层 ``` ## 关键技术细节 ### 认证机制 - **匿名访问**: 程序自动获取匿名账号令牌（50次调用额度） - **JWT 管理**: 自动令牌验证和刷新 - **令牌获取**: 通过匿名接口获取鉴权 token 和 refresh_token - **配置**: 可选环境变量 `WARP_JWT` 和 `WARP_REFRESH_TOKEN` - **实现**: 认证逻辑在 `warp2protobuf/core/auth.py` 中实现 ### 消息处理流程 1. **客户端请求**: 发送 OpenAI 格式请求到 API 服务器 2. **消息重排序**: 验证请求格式并进行消息重排序（适配 Anthropic 风格） 3. **格式转换**: 请求转换为 protobuf JSON 格式 4. **Protobuf 编码**: 转换为 protobuf 二进制发送到桥接服务器 5. **Warp 通信**: 桥接服务器与 Warp AI 服务通信 6. **响应返回**: 通过相同路径返回给客户端 ### Server Tool Call 处理 - **问题**: Warp 要求 task_context 中的消息必须以 server tool call 开头 - **解决方案**: 1. 发送初始请求获取 task_id 和 server tool call id 2. 将 server tool call 塞到消息历史最前面 3. 实现"偷梁换柱"，可以添加任意 task context - **实现**: 在 `protobuf2openai/packets.py` 中的 `map_history_to_warp_messages` 函数 ### Tool Call 支持 - **实现方式**: 通过 MCP (Model Context Protocol) 包装工具调用 - **转换**: 将 OpenAI tools 转换为 Warp mcp_context.tools - **注意事项**: - 清理空的工具字段（如 `{}`），避免 Warp 忽略工具 - 避免与自带工具重叠，防止服务端卡 bug - 添加约束禁止调用内部工具（如 read_files 等） ### System Message 支持 - **实现方式**: 在最后一个 user input 中作为附件文本添加 - **原因**: Warp 的 Rule 实现较为复杂，需要上传到服务器作为 memory - **优势**: 利用注意力机制，实现效果良好 - **实现**: 在 `protobuf2openai/packets.py` 中的 `attach_user_and_tools_to_inputs` 函数 ### 流式响应 - **协议**: 使用 Server-Sent Events (SSE) 实现流式响应 - **双格式兼容**: 完全兼容 OpenAI 和 Anthropic 的流式响应格式 - **OpenAI 处理**: 在 `protobuf2openai/sse_transform.py` 中处理转换逻辑 - **Anthropic 处理**: 在 `protobuf2openai/anthropic_sse_transform.py` 中处理转换逻辑 - **特性**: 支持两种格式的工具调用流式响应 - **自动转换**: 根据请求格式自动选择对应的响应格式 ## 环境配置 ### 必需环境变量 - 无需预填，程序自动获取匿名令牌 ### 可选配置 - `WARP_JWT` - Warp 认证 JWT 令牌（可选） - `WARP_REFRESH_TOKEN` - JWT 刷新令牌（可选） - `HOST` - 服务器主机地址 (默认: `127.0.0.1`) - `PORT` - OpenAI API 服务器端口 (默认: `8010`) - `BRIDGE_BASE_URL` - Protobuf 桥接服务器 URL (默认: `http://localhost:8000`) ### 依赖管理 项目使用 `uv` 进行依赖管理，主要依赖包括： - FastAPI - Web 框架 - Uvicorn - ASGI 服务器 - HTTPx - HTTP 客户端 - Protobuf - Protocol buffer 支持 - WebSockets - WebSocket 通信 - OpenAI - 类型兼容性 ## 开发注意事项 ### 服务器启动顺序 1. **必须先启动** Protobuf 桥接服务器 (`server.py`) 2. **再启动** OpenAI API 服务器 (`openai_compat.py`) 3. **等待热身**: OpenAI 服务器启动后需要等待"热身"请求完成 4. **依赖关系**: 后者依赖前者的健康检查 ### 调试和开发 - **研究模式**: 可以连接 server.py 的 8000 端点进行编解码研究 - **日志记录**: 两个服务器都提供详细的日志记录 - **WebSocket 监控**: Protobuf 桥接服务器包含 WebSocket 监控端点 (`/ws`) - **健康检查**: 使用 `/healthz` 端点检查服务状态 ### 已知问题和限制 - **令牌刷新**: 刷新后可能出现 internal error，但通常很快恢复 - **工具重叠**: 与自带工具重叠时可能卡 bug - **上下文限制**: 输入上下文过多时可能出现异常响应 - **上游限制**: 无法完全自定义工具，上游可能有预填提示词 ### 错误处理 - **认证错误**: 触发自动令牌刷新 - **网络错误**: 包含重试逻辑 - **工具验证**: 清理无效工具字段 - **详细日志**: 错误日志记录在各自模块中 ## 扩展潜力 ### 多模态支持 - **现状**: Warp 数据包支持多模态，但当前实现未包含 - **开发**: 可通过扩展 protobuf 定义添加图片输入支持 - **实现**: 参考 `proto/` 目录下的 protobuf 定义 ### 功能增强 - **更多工具类型**: 支持 Warp 的其他工具类型 - **自定义工具**: 改进工具自定义能力 - **性能优化**: 优化大上下文处理 - **部署版本**: 可考虑 Deno、Cloudflare 等多平台部署 ### API 格式支持 - **OpenAI 兼容**: 完全支持 OpenAI Chat Completions API 格式和行为 - **Anthropic 兼容**: 完全支持 Anthropic Messages API 格式和行为 - **自动转换**: 内部自动处理两种格式之间的转换 - **流式响应**: 两种格式都支持标准的 SSE 流式响应 - **工具调用**: 两种格式都支持 function calling/tool use ### MCP 集成 - **通用方案**: 此 MCP 包装工具调用的方法可应用于其他项目 - **适用场景**: 如 claude2api、cursor2api 等代码助手的工具调用支持 - **优势**: 为免费账号提供 function calling 能力 - **双格式支持**: OpenAI tools 和 Anthropic tools 都通过 MCP 实现 ## 相关文档 - **Function Call 转换机制**: `docs/function-call-tool-use-conversion.md` - **Protobuf 定义**: `proto/` 目录 - **API 格式转换**: 详见 `protobuf2openai/anthropic_converter.py` 和相关转换器 - **使用示例**: 参考 README.md 中的使用说明 - **测试文件**: `test_anthropic_endpoint.py` 和 `test_anthropic_streaming.py`