📡

API 文档

OnlyClaw REST API 完整接口参考,基础地址:http://localhost:8080/api/

概述

OnlyClaw API 是一个 RESTful 风格的 JSON API。所有请求和响应均使用 JSON 格式。

基础信息

项目说明
基础地址http://localhost:8080/api/
认证方式JWT Bearer Token(HS256,7 天过期)
请求格式JSON(Content-Type: application/json)
响应格式JSON
字符编码UTF-8

认证说明

除注册和登录外,所有接口需要在请求头中携带 JWT Token:

HTTP
Authorization: Bearer <your_jwt_token>

通用响应格式

JSON
// 成功
{
    "code": 200,
    "message": "success",
    "data": { ... }
}

// 错误
{
    "code": 400,
    "message": "错误信息"
}

HTTP 状态码

状态码说明
200成功
201创建成功
400请求参数错误
401未认证或 Token 过期
404资源不存在
500服务器内部错误

认证 — AuthController

POST /api/auth/register

注册新用户。

请求体

JSON
{
    "username": "string",    // 用户名,必填
    "password": "string"     // 密码,必填
}

响应

JSON
{
    "code": 201,
    "message": "注册成功",
    "data": {
        "id": 1,
        "username": "testuser"
    }
}

POST /api/auth/login

用户登录,返回 JWT Token。

请求体

JSON
{
    "username": "string",
    "password": "string"
}

响应

JSON
{
    "code": 200,
    "message": "登录成功",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "user": {
            "id": 1,
            "username": "testuser",
            "nickname": "测试用户",
            "avatar": null
        }
    }
}

GET /api/auth/profile

获取当前登录用户信息(需认证)。

响应

JSON
{
    "code": 200,
    "data": {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "avatar": null
    }
}

AI 配置 — ProviderController

GET /api/providers

获取所有 AI 配置列表(API Key 脱敏显示)。

POST /api/providers

创建新的 AI 配置。

请求体

JSON
{
    "provider_type": "mimo | deepseek | openai | custom",
    "api_url": "https://api.example.com/v1",
    "api_key": "sk-xxxxx",
    "model_name": "model-name",
    "is_primary": false
}

PUT /api/providers/{id}

更新指定 AI 配置。请求体同创建,字段均为可选。

DELETE /api/providers/{id}

删除指定 AI 配置。

POST /api/providers/{id}/test

测试指定 AI 配置的连接是否正常。

响应

JSON
{
    "code": 200,
    "message": "连接成功",
    "data": {
        "model": "model-name",
        "response": "Hello!"
    }
}

对话 — ChatController

GET /api/conversations

获取当前用户的对话列表。

POST /api/conversations

创建新对话。

请求体

JSON
{
    "title": "对话标题",          // 可选
    "provider_id": 1,            // 可选,指定 AI 配置
    "system_prompt": "你是..."    // 可选,系统提示词
}

PUT /api/conversations/{id}

更新对话(如修改标题)。

DELETE /api/conversations/{id}

删除对话及其所有消息。

消息 — ChatController

GET /api/conversations/{id}/messages

获取指定对话的消息列表。

POST /api/conversations/{id}/messages

发送消息并获取 AI 回复。支持 SSE 流式响应和普通响应两种模式。

请求体

JSON
{
    "content": "你好,请帮我分析一下...",
    "stream": true               // 可选,默认 true
}

流式响应 (SSE)

stream: true 时,响应为 Server-Sent Events 格式:

Text
data: {"content": "你"}
data: {"content": "好"}
data: {"content": "!"}
data: [DONE]

非流式响应

stream: false 时,返回完整 JSON:

JSON
{
    "code": 200,
    "data": {
        "id": 123,
        "role": "assistant",
        "content": "你好!有什么可以帮助你的吗?",
        "tokens_used": 25
    }
}

智能上下文注入

发送消息时,系统会自动执行:

自动操作

笔记 — NoteController

GET /api/notes

获取笔记列表(分页,可按分类筛选)。

查询参数

参数类型说明
pageint页码,默认 1
page_sizeint每页条数,默认 20
categorystring分类筛选

POST /api/notes

创建笔记。

JSON
{
    "title": "笔记标题",
    "content": "笔记内容...",
    "category": "技术",
    "tags": "PHP,MySQL",
    "is_pinned": false
}

PUT /api/notes/{id}

更新笔记。请求体同创建,字段均为可选。

DELETE /api/notes/{id}

删除笔记。

GET /api/notes/search

全文搜索笔记。

查询参数

参数类型说明
qstring搜索关键词(必填)

任务 — TaskController

GET /api/tasks

获取任务列表(可按状态、优先级筛选,含统计数据)。

查询参数

参数类型说明
statusstring筛选状态:pending / in_progress / completed
prioritystring筛选优先级:low / medium / high / urgent

POST /api/tasks

创建任务。

JSON
{
    "title": "任务标题",
    "description": "任务描述",        // 可选
    "priority": "medium",            // low / medium / high / urgent
    "due_date": "2026-05-15 18:00:00" // 可选
}

PUT /api/tasks/{id}

更新任务。完成时自动记录 completed_at 时间。

DELETE /api/tasks/{id}

删除任务。

GET /api/tasks/upcoming

获取 24 小时内到期和已逾期的任务。用于任务提醒 banner。

文件 — FileController

GET /api/files

获取文件列表(可按分类筛选,关键词搜索)。

查询参数

参数类型说明
categorystring筛选分类:image / document / video / audio / other
keywordstring按文件名和描述搜索

POST /api/files

上传文件。使用 multipart/form-data 格式。

表单字段

字段类型说明
fileFile文件(必填,最大 50MB)
descriptionstring文件描述(可选)
categorystring分类(可选,不填则按 MIME 自动分类)

GET /api/files/{id}/download

下载文件。

GET /api/files/{id}/preview

预览文件(支持图片、PDF、视频、音频、文本)。支持 URL 中携带 token 鉴权。

PUT /api/files/{id}

更新文件元数据(描述、分类)。

DELETE /api/files/{id}

删除文件(同时删除物理文件和数据库记录)。

解决方案 — SolutionController

POST /api/solutions/generate

AI 生成解决方案。

JSON
{
    "title": "方案标题",
    "problem": "问题描述...",
    "tags": "数据库,性能"   // 可选
}

GET /api/solutions

获取解决方案列表。

PUT /api/solutions/{id}/rate

为方案评分。

JSON
{
    "rating": 4    // 0-5 星
}

记忆 — MemoryController

智能记忆系统,自动从对话中提取用户偏好、项目、习惯等信息,为 AI 提供个性化上下文。

GET /api/memories

获取当前用户的记忆列表。

查询参数

参数类型说明
typestring筛选类型:preference / project / habit / context / fact
limitint返回数量限制

POST /api/memories

创建新记忆。

JSON
{
    "memory_type": "preference",   // preference / project / habit / context / fact
    "title": "记忆标题",
    "content": "记忆内容...",
    "importance": 1                // 0=低 1=中 2=高
}

GET /api/memories/stats

获取记忆统计信息,按类型分组。

响应

JSON
{
    "code": 200,
    "data": {
        "total": 42,
        "by_type": {
            "preference": 15,
            "project": 8,
            "habit": 10,
            "context": 5,
            "fact": 4
        }
    }
}

POST /api/memories/search

搜索记忆(关键词匹配)。

JSON
{
    "keyword": "搜索关键词"
}

POST /api/memories/context

获取与当前对话相关的记忆上下文,用于注入 AI 对话。基于关键词提取和相关性评分。

JSON
{
    "content": "当前对话内容...",
    "limit": 10
}

POST /api/memories/auto-extract

从对话内容中自动提取记忆。使用正则表达式匹配偏好、项目、习惯等模式。

JSON
{
    "conversation_id": 123,
    "messages": [
        {"role": "user", "content": "我喜欢用深色主题"},
        {"role": "assistant", "content": "好的,我记住了..."}
    ]
}

POST /api/memories/cleanup

清理过期记忆(将 expires_at 已过期的记忆设为 is_active=0)。

GET /api/memories/{id}

获取单条记忆详情。

PUT /api/memories/{id}

更新记忆。请求体同创建,字段均为可选。

DELETE /api/memories/{id}

删除记忆(软删除,设置 is_active=0)。

数据库表

SQL
CREATE TABLE memories (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    memory_type ENUM('preference','project','habit','context','fact') NOT NULL,
    title VARCHAR(255) NOT NULL,
    content TEXT NOT NULL,
    importance TINYINT DEFAULT 1,
    access_count INT DEFAULT 0,
    last_accessed_at TIMESTAMP NULL,
    expires_at TIMESTAMP NULL,
    is_active TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    FULLTEXT KEY ft_memories (title, content)
);

设置 — SettingsController

GET /api/settings

获取当前用户的所有设置。

响应

JSON
{
    "code": 200,
    "data": {
        "theme": "light",
        "language": "zh-CN",
        "auto_save": "1",
        "stream_response": "1",
        "page_size": "20"
    }
}

PUT /api/settings

更新设置(key-value upsert,可批量更新)。

JSON
{
    "theme": "dark",
    "stream_response": "0"
}

默认设置

默认值说明
themelight主题
languagezh-CN语言
auto_save1自动保存开关
stream_response1流式响应开关
page_size20每页条数

数据库表

SQL
CREATE TABLE settings (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    setting_key VARCHAR(50) NOT NULL,
    setting_value TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    UNIQUE KEY unique_user_setting (user_id, setting_key)
);