API 参考

对照基线：Go 服务端 server-v1.1.5 · 更新日期：2026-10-06 · 本次源码新增 GET /openapi.json 入口

生产后端是 Go 服务端（server-go/）。同一份契约以 OpenAPI 3.1 文档形式提供于 http://localhost:8080/openapi.json；参见 OpenAPI。

基础信息

Base URL：http://localhost:8080

认证方式：Bearer Token

多数接口返回 JSON（application/json）；上传使用 multipart/form-data，下载接口 （/api/resources/:id/download、/api/resources/:id/thumbnail、 /api/avatars/:id/download）返回二进制数据，支持 Range 与 ETag。

认证

POST /api/auth/login

{ "username": "admin", "password": "admin123" }

响应：

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": {
    "id": "uuid",
    "username": "admin",
    "role": "admin",
    "mustChangePassword": false,
    "createdAt": 1700000000000,
    "updatedAt": 1700000000000
  },
  "mustChangePassword": false
}

user.role 为 admin 或 user。当 mustChangePassword 为 true 时，该 token 仅能访问 GET /api/auth/me 和 POST /api/auth/change-password，其余 /api/* 业务接口返回 403。管理 API 单独检查管理员角色。

POST /api/auth/refresh

{ "refreshToken": "eyJ..." }

Memo

GET /api/memos

分页查询。Query：page、pageSize、archived、diaryDate、search

POST /api/memos

{ "content": "# 笔记内容", "tags": ["工作"], "diaryDate": "2026-05-16" }

GET /api/memos/:id

PUT /api/memos/:id

DELETE /api/memos/:id

Bot 系统

GET /api/bots

列出所有 Bot。

POST /api/bots

{ "name": "助手", "provider": "openai", "model": "gpt-4o", "systemPrompt": "你是一个助手" }

创建 Bot。返回 201 Created。

PUT /api/bots/:id

DELETE /api/bots/:id

返回 204 No Content。

POST /api/memos/:id/trigger-replies

手动触发某条 Memo 的自动回复。返回 202 Accepted。

POST /api/bot-replies/:id/reply

在线程中回复某个 Bot。请求体可带 clientRequestId（客户端生成的稳定 UUID），相同 ID 的重试会返回已有回复而不会重复生成。本次生成完成返回 201 Created，生成中返回 202 Accepted，重放已有记录返回 200 OK。

记忆系统

GET /api/memory/stats

Embedding 统计信息。

GET /api/memory/context

调试用，查看检索到的相关 Memo。Query：memo_id（别名 memoId）、bot_id（别名 botId），均为必填，外加 limit。

日记

GET /api/diaries

POST /api/diaries/:date

moodScore 必填，范围为 1–10。

{ "moodKey": "happy", "moodScore": 8, "summary": "今天很开心！" }

资源

GET /api/resources

POST /api/resources/upload

文件上传（multipart/form-data）。

设置

GET /admin/api/settings

获取应用设置（自动标签、自动日记、时区 appTimezone 等）。

PUT /admin/api/settings

更新应用设置。