Rovo Dev OpenAI API

一个将Atlassian Rovo Dev AI助手包装为OpenAI兼容REST API的Python服务。

功能特性

• 🔌 OpenAI兼容: 支持标准的OpenAI API格式 (/v1/chat/completions)
• 🌊 流式响应: 支持Server-Sent Events (SSE)实时流式输出
• 🔐 安全认证: API密钥验证和权限管理
• 📊 会话管理: 自动会话创建、超时清理
• 🛡️ 错误处理: 完善的错误处理和状态码管理
• 📝 详细日志: 可配置的日志记录
• ⚡ 高性能: 基于FastAPI的异步架构

快速开始

1. 环境要求

• Python 3.8+
• 已安装并配置Atlassian CLI (acli)
• 有效的Rovo Dev访问权限

2. 安装依赖

pip install -r requirements.txt

3. 配置环境

复制配置文件模板：

cp .env.example .env

编辑 .env 文件，设置必要的配置参数：

# 设置API密钥
ROVO_API_API_KEY=your-secret-api-key-here

# 设置ACLI路径（如果不在默认位置）
ROVO_API_ACLI_PATH=/usr/local/bin/acli

# 设置工作空间路径
ROVO_API_WORKSPACE_PATH=/path/to/your/workspace

4. 启动服务

python main.py

或使用uvicorn直接启动：

uvicorn api:app --host 0.0.0.0 --port 8000

服务启动后，访问 http://localhost:8000/docs 查看API文档。

API使用

聊天完成 (Chat Completions)

端点: POST /v1/chat/completions

请求示例:

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rovo-dev",
    "messages": [
      {"role": "user", "content": "帮我分析这个Python函数的复杂度"}
    ],
    "stream": false
  }'

流式请求示例:

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rovo-dev",
    "messages": [
      {"role": "user", "content": "解释一下这段代码"}
    ],
    "stream": true
  }'

支持的参数

• model: 模型名称 (固定为 "rovo-dev")
• messages: 消息数组
• temperature: 温度参数 (0.0-2.0)
• max_tokens: 最大token数
• stream: 是否启用流式响应
• stop: 停止词
• presence_penalty: 存在惩罚
• frequency_penalty: 频率惩罚
• top_p: Top-p采样
• n: 生成响应数量
• user: 用户标识

模型列表

端点: GET /v1/models

curl -X GET "http://localhost:8000/v1/models" \
  -H "Authorization: Bearer your-api-key"

配置说明

环境变量

变量名	默认值	说明
ROVO_API_HOST	0.0.0.0	服务监听地址
ROVO_API_PORT	8000	服务端口
ROVO_API_DEBUG	false	调试模式
ROVO_API_API_KEY	None	API密钥
ROVO_API_REQUIRE_AUTH	true	是否需要认证
ROVO_API_ACLI_PATH	/usr/local/bin/acli	ACLI命令路径
ROVO_API_WORKSPACE_PATH	/Users/admin	工作空间路径
ROVO_API_SESSION_TIMEOUT	3600	会话超时时间(秒)
ROVO_API_MAX_CONCURRENT_SESSIONS	10	最大并发会话数
ROVO_API_LOG_LEVEL	INFO	日志级别
ROVO_API_LOG_FILE	None	日志文件路径

部署

Docker部署

创建 Dockerfile:

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["python", "main.py"]

构建和运行：

docker build -t rovo-api .
docker run -p 8000:8000 --env-file .env rovo-api

生产环境部署

推荐使用Gunicorn + Nginx：

# 安装Gunicorn
pip install gunicorn

# 启动服务
gunicorn api:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

故障排除

常见问题

1. ACLI未找到

   • 确保已安装Atlassian CLI
   • 检查 ROVO_API_ACLI_PATH 配置

2. Rovo Dev连接失败

   • 确保已登录ACLI (acli auth login)
   • 检查Rovo Dev权限

3. 会话超时

   • 调整 ROVO_API_SESSION_TIMEOUT 参数
   • 检查网络连接稳定性

日志查看

启用日志文件：

export ROVO_API_LOG_FILE=rovo_api.log
python main.py

查看日志：

tail -f rovo_api.log

开发

开发环境设置

# 克隆项目
git clone <repository-url>
cd rovo-dev-openai-api

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
export ROVO_API_DEBUG=true
python main.py

项目结构

rovo-dev-openai-api/
├── main.py              # 主启动文件
├── api.py               # FastAPI应用
├── config.py            # 配置管理
├── models.py            # 数据模型
├── rovo_client.py       # Rovo Dev客户端
├── auth.py              # 认证模块
├── exceptions.py        # 异常处理
├── requirements.txt     # 依赖列表
├── .env.example         # 配置模板
└── README.md           # 说明文档

项目结构

rovo-dev-openai-api/
├── 核心应用文件
│   ├── main.py              # 主启动文件
│   ├── api.py               # FastAPI应用和路由
│   ├── config.py            # 配置管理
│   └── models.py            # 数据模型定义
├── 功能模块
│   ├── simple_rovo_client.py # Rovo Dev通信客户端
│   ├── session_manager.py   # 智能会话管理器
│   ├── auth.py              # 认证和安全模块
│   ├── exceptions.py        # 异常处理
│   └── middleware.py        # 中间件（性能监控、限流等）
├── 配置和部署
│   ├── requirements.txt     # Python依赖列表
│   ├── .env.example         # 配置文件模板
│   ├── start.sh             # 快速启动脚本
│   ├── deploy.sh            # 自动化部署脚本
│   ├── Dockerfile           # Docker镜像配置
│   └── docker-compose.yml   # Docker Compose配置
├── 测试和示例
│   ├── test_client.py       # 主要测试客户端
│   └── examples/            # 多语言使用示例
│       ├── python_client.py    # Python客户端示例
│       ├── javascript_client.js # JavaScript客户端示例
│       ├── curl_examples.sh     # cURL命令示例
│       └── package.json         # Node.js项目配置
└── 文档
    ├── README.md            # 项目主文档
    ├── API_SPEC.md          # API接口规范
    ├── PROJECT_SUMMARY.md   # 项目总结
    └── TROUBLESHOOTING.md   # 故障排除指南

API文档

基础信息

• Base URL: http://localhost:8000
• 认证方式: Bearer Token (可选)
• 内容类型: application/json

端点列表

1. 健康检查

GET /health

返回服务健康状态和运行时间。

2. 性能统计

GET /stats

返回API性能统计信息。

3. 模型列表

GET /v1/models

返回可用的AI模型列表。

4. 聊天完成

POST /v1/chat/completions

主要的聊天完成端点，支持流式和非流式响应。

详细的API文档请参考：http://localhost:8000/docs（调试模式下可用）

使用示例

Python示例

import asyncio
from examples.python_client import RovoDevClient

async def main():
    client = RovoDevClient()

    messages = [
        {"role": "user", "content": "解释一下什么是API"}
    ]

    response = await client.chat_completion(messages)
    print(response['choices'][0]['message']['content'])

asyncio.run(main())

JavaScript示例

const RovoDevClient = require('./examples/javascript_client');

async function main() {
    const client = new RovoDevClient();

    const messages = [
        { role: 'user', content: '解释一下什么是API' }
    ];

    const response = await client.chatCompletion(messages);
    console.log(response.choices[0].message.content);
}

main().catch(console.error);

cURL示例

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rovo-dev",
    "messages": [
      {"role": "user", "content": "解释一下什么是API"}
    ],
    "stream": false
  }'

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.0.0

• ✅ 实现OpenAI兼容的API接口
• ✅ 支持流式和非流式响应
• ✅ 添加认证和错误处理
• ✅ 性能监控和限流功能
• ✅ 完整的文档和示例
• ✅ Docker支持