API 文档

Aeio Dev Agent 提供完整的 RESTful API，支持通过编程方式管理会话、消息和沙箱文件。所有 API 端点都需要 JWT 认证。

认证方式

除了注册和登录端点外，所有 API 请求都需要在 HTTP Header 中包含 JWT 令牌：

Authorization: Bearer <your_access_token>

基础 URL

https://your-domain.com/api

1. 认证相关

POST /auth/register

注册新用户账号

参数	类型	说明
username	string	用户名（3-50 字符）
email	string	邮箱地址
password	string	密码（至少 6 字符）

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securepass123"
}

响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com"
  }
}

POST /auth/login

用户登录，获取访问令牌

参数	类型	说明
username	string	用户名或邮箱
password	string	密码

响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com"
  }
}

GET /auth/me

获取当前用户信息（需要认证）

响应：

{
  "id": 1,
  "username": "johndoe",
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

2. 会话管理

GET /sessions

获取当前用户的所有会话列表

响应：

[
  {
    "id": "12db3c516aae14608a5013905b8c189f",
    "title": "个人网站",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  },
  {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "title": "登录页面",
    "created_at": "2024-01-14T08:00:00Z",
    "updated_at": "2024-01-14T09:30:00Z"
  }
]

POST /sessions

创建新会话

参数	类型	说明
title	string	会话标题

响应：

{
  "id": "12db3c516aae14608a5013905b8c189f",
  "title": "新项目",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

GET /sessions/{id}

获取指定会话的详细信息

路径参数：

id - 会话 ID（UUID hex 字符串）

响应：

{
  "id": "12db3c516aae14608a5013905b8c189f",
  "title": "个人网站",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

DELETE /sessions/{id}

删除指定会话及其所有数据

响应：

{"message": "Session deleted successfully"}

3. 消息相关

GET /sessions/{id}/messages

获取会话的消息历史

响应：

[
  {
    "id": 1,
    "session_id": "12db3c516aae14608a5013905b8c189f",
    "content": "创建一个登录表单",
    "role": "user",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "session_id": "12db3c516aae14608a5013905b8c189f",
    "content": "好的，我来为您创建...",
    "role": "assistant",
    "created_at": "2024-01-15T10:30:05Z"
  }
]

POST /sessions/{id}/messages

发送新消息并获取 AI 响应

参数	类型	说明
content	string	消息内容
stream	boolean	是否使用流式响应（可选，默认 false）

响应：

{
  "id": 3,
  "session_id": "12db3c516aae14608a5013905b8c189f",
  "content": "我已经为您创建了登录表单...",
  "role": "assistant",
  "created_at": "2024-01-15T10:31:00Z"
}

GET /sessions/{id}/messages/latest/execution-steps

获取最新消息的执行步骤（实时进度）

响应：

[
  {
    "id": 1,
    "session_id": "12db3c516aae14608a5013905b8c189f",
    "message_id": 3,
    "iteration": 1,
    "status": "completed",
    "tool_name": "write_file",
    "tool_arguments": {"filename": "index.html"},
    "progress": 100
  }
]

4. 沙箱文件

GET /sessions/{id}/sandbox/files

列出沙箱中的所有文件

响应：

{
  "files": [
    {"name": "index.html", "size": 1234},
    {"name": "style.css", "size": 567},
    {"name": "script.js", "size": 890}
  ],
  "total_size": 2691
}

GET /sessions/{id}/sandbox/files/{filename}

读取指定文件的内容

响应：

{
  "filename": "index.html",
  "content": "<!DOCTYPE html>\n<html>...",
  "size": 1234
}

POST /sessions/{id}/sandbox/files/{filename}

创建或覆盖文件

参数	类型	说明
content	string	文件内容

响应：

{
  "filename": "index.html",
  "size": 1234,
  "message": "File saved successfully"
}

DELETE /sessions/{id}/sandbox/files/{filename}

删除指定文件

响应：

{"message": "File deleted successfully"}

GET /sessions/{id}/sandbox/preview

获取沙箱预览（返回 HTML）

响应：HTML Content（text/html）

GET /sessions/{id}/sandbox/static/{filename}

获取沙箱中的静态资源（CSS、JS、图片等）

响应：文件内容（根据文件类型返回相应的 Content-Type）

5. 错误响应

所有 API 端点在发生错误时返回统一的错误格式：

{
  "detail": "Error message description"
}

HTTP 状态码

200 - 请求成功
201 - 创建成功
400 - 请求参数错误
401 - 未认证或令牌无效
403 - 无权限访问
404 - 资源不存在
422 - 请求体验证失败
500 - 服务器内部错误

6. 限制说明

令牌有效期：30 分钟
沙箱大小限制：每个会话最大 100MB
单个文件大小：最大 1MB
请求速率限制：根据用户等级动态调整

需要更多帮助？请查看常见问题或联系我们。