概述
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:
Authorization: Bearer <your_jwt_token>
通用响应格式
// 成功
{
"code": 200,
"message": "success",
"data": { ... }
}
// 错误
{
"code": 400,
"message": "错误信息"
}
HTTP 状态码
| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未认证或 Token 过期 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
认证 — AuthController
POST /api/auth/register
注册新用户。
请求体
{
"username": "string", // 用户名,必填
"password": "string" // 密码,必填
}
响应
{
"code": 201,
"message": "注册成功",
"data": {
"id": 1,
"username": "testuser"
}
}
POST /api/auth/login
用户登录,返回 JWT Token。
请求体
{
"username": "string",
"password": "string"
}
响应
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": 1,
"username": "testuser",
"nickname": "测试用户",
"avatar": null
}
}
}
GET /api/auth/profile
获取当前登录用户信息(需认证)。
响应
{
"code": 200,
"data": {
"id": 1,
"username": "testuser",
"nickname": "测试用户",
"avatar": null
}
}
AI 配置 — ProviderController
GET /api/providers
获取所有 AI 配置列表(API Key 脱敏显示)。
POST /api/providers
创建新的 AI 配置。
请求体
{
"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 配置的连接是否正常。
响应
{
"code": 200,
"message": "连接成功",
"data": {
"model": "model-name",
"response": "Hello!"
}
}
对话 — ChatController
GET /api/conversations
获取当前用户的对话列表。
POST /api/conversations
创建新对话。
请求体
{
"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 流式响应和普通响应两种模式。
请求体
{
"content": "你好,请帮我分析一下...",
"stream": true // 可选,默认 true
}
流式响应 (SSE)
当 stream: true 时,响应为 Server-Sent Events 格式:
data: {"content": "你"}
data: {"content": "好"}
data: {"content": "!"}
data: [DONE]
非流式响应
当 stream: false 时,返回完整 JSON:
{
"code": 200,
"data": {
"id": 123,
"role": "assistant",
"content": "你好!有什么可以帮助你的吗?",
"tokens_used": 25
}
}
智能上下文注入
发送消息时,系统会自动执行:
- 意图检测 — 正则匹配"笔记/任务/文件/方案"关键词
- 关键词提取 — 中文按单字拆分,英文按单词提取
- 多表搜索 — 从笔记、任务、文件、方案中 LIKE 模糊搜索
- 上下文注入 — 拼接为 system message 注入 AI(上限 4000 字符)
自动操作
- 提到"笔记"时自动创建笔记
- 提到"任务"时自动创建任务(提取优先级、截止日期)
- 提到"方案"时自动创建解决方案
- 首条消息自动截取为对话标题
笔记 — NoteController
GET /api/notes
获取笔记列表(分页,可按分类筛选)。
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| page | int | 页码,默认 1 |
| page_size | int | 每页条数,默认 20 |
| category | string | 分类筛选 |
POST /api/notes
创建笔记。
{
"title": "笔记标题",
"content": "笔记内容...",
"category": "技术",
"tags": "PHP,MySQL",
"is_pinned": false
}
PUT /api/notes/{id}
更新笔记。请求体同创建,字段均为可选。
DELETE /api/notes/{id}
删除笔记。
GET /api/notes/search
全文搜索笔记。
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| q | string | 搜索关键词(必填) |
任务 — TaskController
GET /api/tasks
获取任务列表(可按状态、优先级筛选,含统计数据)。
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| status | string | 筛选状态:pending / in_progress / completed |
| priority | string | 筛选优先级:low / medium / high / urgent |
POST /api/tasks
创建任务。
{
"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
获取文件列表(可按分类筛选,关键词搜索)。
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| category | string | 筛选分类:image / document / video / audio / other |
| keyword | string | 按文件名和描述搜索 |
POST /api/files
上传文件。使用 multipart/form-data 格式。
表单字段
| 字段 | 类型 | 说明 |
|---|---|---|
| file | File | 文件(必填,最大 50MB) |
| description | string | 文件描述(可选) |
| category | string | 分类(可选,不填则按 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 生成解决方案。
{
"title": "方案标题",
"problem": "问题描述...",
"tags": "数据库,性能" // 可选
}
GET /api/solutions
获取解决方案列表。
PUT /api/solutions/{id}/rate
为方案评分。
{
"rating": 4 // 0-5 星
}
记忆 — MemoryController
智能记忆系统,自动从对话中提取用户偏好、项目、习惯等信息,为 AI 提供个性化上下文。
GET /api/memories
获取当前用户的记忆列表。
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| type | string | 筛选类型:preference / project / habit / context / fact |
| limit | int | 返回数量限制 |
POST /api/memories
创建新记忆。
{
"memory_type": "preference", // preference / project / habit / context / fact
"title": "记忆标题",
"content": "记忆内容...",
"importance": 1 // 0=低 1=中 2=高
}
GET /api/memories/stats
获取记忆统计信息,按类型分组。
响应
{
"code": 200,
"data": {
"total": 42,
"by_type": {
"preference": 15,
"project": 8,
"habit": 10,
"context": 5,
"fact": 4
}
}
}
POST /api/memories/search
搜索记忆(关键词匹配)。
{
"keyword": "搜索关键词"
}
POST /api/memories/context
获取与当前对话相关的记忆上下文,用于注入 AI 对话。基于关键词提取和相关性评分。
{
"content": "当前对话内容...",
"limit": 10
}
POST /api/memories/auto-extract
从对话内容中自动提取记忆。使用正则表达式匹配偏好、项目、习惯等模式。
{
"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)。
数据库表
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
获取当前用户的所有设置。
响应
{
"code": 200,
"data": {
"theme": "light",
"language": "zh-CN",
"auto_save": "1",
"stream_response": "1",
"page_size": "20"
}
}
PUT /api/settings
更新设置(key-value upsert,可批量更新)。
{
"theme": "dark",
"stream_response": "0"
}
默认设置
| 键 | 默认值 | 说明 |
|---|---|---|
| theme | light | 主题 |
| language | zh-CN | 语言 |
| auto_save | 1 | 自动保存开关 |
| stream_response | 1 | 流式响应开关 |
| page_size | 20 | 每页条数 |
数据库表
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)
);
