Skip to content

README.md

Latest commit

 

History

History
400 lines (317 loc) · 14.2 KB

README.md

File metadata and controls

400 lines (317 loc) · 14.2 KB
Raw

CodeBuddy2API

CodeBuddy2API 是一个 FastAPI 代理服务，将 CodeBuddy 官方 API 封装为 OpenAI 兼容 和 Anthropic 兼容 的接口，主要用于在其他 coding agent（如 Codex、Claude Code 等）中接入 CodeBuddy 提供的模型能力。

⚠️ 重要：仅用于 coding agent 场景

CodeBuddy2API 应该用于在其他 coding agent（如 Codex、Claude Code、Cursor 等）中接入 CodeBuddy 提供的模型能力，辅助编程、代码理解、生成与调试。

它 不是通用 LLM API，也 不应该被视为通用 LLM API。禁止在通用任务中使用 CodeBuddy2API，包括但不限于：

  • 通用聊天、问答、内容生成
  • 自动化客服、批量消息处理
  • 数据标注、爬虫、模型中转或对外公开服务
  • 任何非编程辅助的自动化任务

CodeBuddy 官方会对异常使用行为进行检测，一旦检测到违规使用，可能导致你的账号被封禁。

只有在你明确知道自己在做什么，并且清楚会带来什么后果的情况下，才应该启动这个项目。 如果你不清楚上述限制意味着什么，说明你目前不应该使用这个项目。

快速开始

1. 安装依赖

项目使用 uv 管理依赖，没有 requirements.txt。

uv sync --extra dev

2. 配置凭证

首次运行会自动从 config.example.yaml 生成 config/config.yaml，并生成一个随机访问密码。

CodeBuddy 凭证可以通过以下方式获取：

  • Web 管理后台（推荐）：启动服务后访问 http://127.0.0.1:8111/，通过 OAuth2 自动授权获取。
  • 手动放置：将获取到的 CodeBuddy JSON 凭证文件放入 .codebuddy_creds/ 目录。

3. 启动服务

python web.py

启动后默认监听在 http://127.0.0.1:8111。

4. 验证

ruff check .       # 代码检查
mypy src/          # 类型检查
pytest             # 运行测试

部署方式

本地运行（临时测试）

# 仅用于临时测试，直接启动服务
python web.py

注意：python web.py 适合开发调试或临时体验。长期使用或生产环境建议通过 Docker 部署，以获得配置隔离、持久化、日志管理、版本追溯和一键重启能力。详见下方的 Docker 部署。

Docker 部署（推荐生产环境）

使用 run_docker_in_server.sh 脚本直接部署，不依赖 docker-compose。

# 构建并启动（自动按 git hash 打 tag、生成配置、等待 /health 就绪、清理旧镜像）
./run_docker_in_server.sh deploy

首次启动会自动生成随机密码，写入 data/config/config.yaml 并在日志中打印。查看密码：

# 方式一：从日志中获取
docker logs codebuddy2api 2>&1 | grep "Generated random password"

# 方式二：直接查看配置
grep "password:" data/config/config.yaml

如需自定义密码，编辑配置后再次 deploy：

vim data/config/config.yaml
./run_docker_in_server.sh deploy

完整的环境变量、命令子命令与保护版本机制，请参考 docker-deploy.md。

API 使用

认证

所有需要认证的 API 请求，都必须在 HTTP 头中携带 config/config.yaml 里设置的 server.password 作为 Bearer Token：

Authorization: Bearer your_secret_password_for_this_service

Anthropic 格式接口也支持通过 x-api-key 头认证：

x-api-key: your_secret_password_for_this_service

API 端点

根端点

方法 路径 认证 说明
GET / 否 服务信息与端点列表
GET /health 否 健康检查

OpenAI 兼容接口

Base URL：http://127.0.0.1:8111/codebuddy/v1

方法 路径 认证 说明
POST /v1/chat/completions Bearer 核心聊天接口，支持流式与非流式
GET /v1/models Bearer 获取配置的模型列表

Anthropic 兼容接口

Base URL：http://127.0.0.1:8111/codebuddy

方法 路径 认证 说明
POST /v1/messages Bearer / x-api-key Anthropic Messages API，支持流式与非流式、工具调用

凭证管理

方法 路径 认证 说明
GET /codebuddy/v1/credentials Bearer 列出已加载的凭证
POST /codebuddy/v1/credentials/delete Bearer 删除指定凭证

OAuth2 认证

方法 路径 认证 说明
GET /codebuddy/auth/start 否 启动 CodeBuddy OAuth2 授权流程
POST /codebuddy/auth/poll 否 轮询授权状态并保存 token

设置管理

方法 路径 认证 说明
GET /api/settings Bearer 读取当前配置
POST /api/settings Bearer 保存并热加载配置
GET /api/stats Bearer 获取使用统计

客户端集成示例

OpenAI 客户端（Python）

import openai

client = openai.OpenAI(
    api_key="your_secret_password_for_this_service",
    base_url="http://127.0.0.1:8111/codebuddy/v1"
)

# 非流式请求
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "你好，2+2等于几？"}
    ]
)
print(response.choices[0].message.content)

# 流式请求
stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "写一个 Python 的 Hello World 脚本"}
    ],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

curl 示例：OpenAI 格式

# 非流式请求
curl -X POST "http://127.0.0.1:8111/codebuddy/v1/chat/completions" \
  -H "Authorization: Bearer your_secret_password_for_this_service" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Hello, what is 2+2?"}
    ]
  }'

# 流式请求
curl -X POST "http://127.0.0.1:8111/codebuddy/v1/chat/completions" \
  -H "Authorization: Bearer your_secret_password_for_this_service" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Write a Python hello world script"}
    ],
    "stream": true
  }'

curl 示例：Anthropic 格式

# 非流式请求
curl -X POST "http://127.0.0.1:8111/codebuddy/v1/messages" \
  -H "x-api-key: your_secret_password_for_this_service" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Hello, what is 2+2?"}
    ]
  }'

# 带系统提示
curl -X POST "http://127.0.0.1:8111/codebuddy/v1/messages" \
  -H "x-api-key: your_secret_password_for_this_service" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 4096,
    "system": "You are a helpful assistant that speaks concisely.",
    "messages": [
      {"role": "user", "content": "Explain quantum computing in one sentence."}
    ]
  }'

# 流式请求
curl -X POST "http://127.0.0.1:8111/codebuddy/v1/messages" \
  -H "x-api-key: your_secret_password_for_this_service" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 4096,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Write a Python hello world script"}
    ]
  }'

# 工具调用
curl -X POST "http://127.0.0.1:8111/codebuddy/v1/messages" \
  -H "x-api-key: your_secret_password_for_this_service" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 4096,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {"role": "user", "content": "What is the weather in Tokyo?"}
    ]
  }'

项目结构

codebuddy2api/
├── web.py                          # 服务启动入口（Hypercorn）
├── config.py                       # 向后兼容 shim，转发到 src/core/config.py
├── config.example.yaml             # 配置文件模板
├── pyproject.toml                   # Python 依赖与项目配置
├── uv.lock                          # uv 锁定依赖版本
├── Dockerfile                       # Docker 镜像构建文件
├── run_docker_in_server.sh         # Docker 部署脚本
├── docker-deploy.md                # Docker 部署详细说明
├── AGENTS.md                       # 项目架构与开发指南
├── frontend/
│   ├── admin.html                  # Web 管理界面
│   └── assets/                     # 前端静态资源（CSS / JS / 字体）
├── src/                            # 源代码目录
│   ├── main.py                     # FastAPI 应用工厂与 lifespan
│   ├── api/
│   │   ├── deps.py                 # FastAPI 依赖注入
│   │   └── routers/
│   │       ├── codebuddy_openai.py # OpenAI 兼容路由
│   │       ├── anthropic.py        # Anthropic 兼容路由
│   │       ├── frontend.py         # 前端资源路由
│   │       ├── oauth.py            # OAuth2 认证路由
│   │       └── settings.py         # 设置管理路由
│   ├── core/
│   │   ├── config.py               # 配置加载、热加载、保存
│   │   ├── http_client.py          # HTTP 客户端池与生命周期管理
│   │   └── logging.py              # loguru 日志配置
│   ├── providers/
│   │   └── codebuddy/
│   │       ├── api_client.py       # CodeBuddy 官方 API 客户端封装
│   │       └── token_manager.py    # 凭证加载、轮换、状态持久化
│   ├── services/
│   │   ├── auth_flow.py            # OAuth2 PKCE 认证流程
│   │   ├── chat_service.py         # 聊天请求处理与流式响应聚合
│   │   ├── keyword_replacer.py     # 关键词替换
│   │   ├── protocol_converters.py  # 协议转换工具
│   │   ├── sse_stream.py           # SSE 解析与 OpenAI 兼容转换
│   │   └── stats.py                # 使用统计管理器
│   ├── domain/                     # 领域模型（Pydantic 数据类）
│   ├── request_processor.py        # 请求验证与预处理（兼容 shim）
│   └── stream_handler.py           # 流式/非流式响应处理（兼容 shim）
├── tests/                          # 测试目录
├── .codebuddy_creds/               # CodeBuddy 凭证目录（Git 忽略）
├── config/                         # 运行时配置目录
├── data/                           # Docker 持久化数据目录（运行后生成）
└── logs/                           # 日志目录

配置选项

所有配置集中在 config/config.yaml（首次启动时自动从 config.example.yaml 拷贝生成）。

配置路径 默认值 说明
server.host 127.0.0.1 服务监听地址。本地开发用 127.0.0.1，容器内需 0.0.0.0
server.port 8111 服务监听端口
server.password 自动生成 API 访问密码（Bearer Token）。首次启动自动生成随机密码，可在日志或配置中查看
codebuddy.api_endpoint https://www.codebuddy.cn CodeBuddy 官方 API 端点，一般无需修改
codebuddy.creds_dir .codebuddy_creds 存放 CodeBuddy 凭证 JSON 的目录
codebuddy.cli_version 1.0.8 CLI 版本号（User-Agent 等请求头使用）
codebuddy.default_user_id b5be3a67-... 默认 X-User-Id（请求头中使用）
codebuddy.models （列表） 向客户端报告的可用模型列表
codebuddy.credential_rotation_count 1 凭证轮换频率，每 N 次请求切换一次凭证，设为 0 关闭
http.ssl_verify false SSL 证书验证开关
http.request_timeout 300 请求总超时（秒）
http.connect_timeout 30 连接超时（秒）
logging.level INFO 日志级别：DEBUG/INFO/WARNING/ERROR/CRITICAL
logging.rotation 10 MB 单文件大小上限，达到后轮转
logging.retention 3 days 日志保留时长，超期自动删除（含已压缩的 .gz）
logging.compression gz 轮转后压缩格式：gz/zip/bz2/xz，留空不压缩

提示：通过 Web 管理后台（Settings 页）修改配置后会自动写回 config/config.yaml（会覆盖手动编辑的注释）。如需保留注释，请编辑 config.example.yaml 后重新拷贝。

故障排除

问题 可能原因 解决方法
No valid CodeBuddy credentials found 尚未添加 CodeBuddy 凭证 通过 Web UI 完成 OAuth2 授权，或手动在 .codebuddy_creds/ 放置有效凭证 JSON
API error: 401 / 403（来自 CodeBuddy） CodeBuddy 凭证无效或已过期 重新获取 CodeBuddy Token 并更新
Invalid password 请求头中的 Bearer Token 与 server.password 不匹配 检查 config/config.yaml 中的密码，或查看启动日志中的随机密码
服务无法从外部访问 容器内监听地址仍为 127.0.0.1 Docker 部署时会自动改写为 0.0.0.0；手动部署时请检查 server.host
需要查看详细日志 日志级别不够详细 在 config/config.yaml 中设置 logging.level: DEBUG，或通过 Web 后台 Settings 页热更新

开发指南

开发前建议阅读 AGENTS.md，其中包含：

  • 项目架构与关键模块说明
  • 配置热加载与日志机制
  • Docker 部署与镜像版本管理
  • 常见坑点（如 uv 用法、循环导入、SSE 聚合等）