Memoh/packages/api/SETTINGS_API.md

Settings API 文档

概述

Settings API 用于管理用户的个性化设置，包括默认模型配置和 Agent 行为设置。

端点

GET /settings 🔒 需要认证

获取当前用户的设置。

请求

Headers:

Authorization: Bearer <your_jwt_token>

成功响应 (200 OK)

{
  "success": true,
  "data": {
    "userId": "user-id",
    "defaultChatModel": "123e4567-e89b-12d3-a456-426614174000",
    "defaultEmbeddingModel": "223e4567-e89b-12d3-a456-426614174001",
    "defaultSummaryModel": "323e4567-e89b-12d3-a456-426614174002",
    "maxContextLoadTime": 60,
    "language": "Chinese"
  }
}

错误响应 (404 Not Found)

{
  "success": false,
  "error": "Settings not found"
}

---

PUT /settings 🔒 需要认证

更新或创建当前用户的设置（Upsert 操作）。

请求

Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Body:

{
  "defaultChatModel": "123e4567-e89b-12d3-a456-426614174000",
  "defaultEmbeddingModel": "223e4567-e89b-12d3-a456-426614174001",
  "defaultSummaryModel": "323e4567-e89b-12d3-a456-426614174002",
  "maxContextLoadTime": 60,
  "language": "Chinese"
}

参数说明:

字段	类型	必需	默认值	说明
defaultChatModel	string (uuid)	否	null	默认聊天模型 ID
defaultEmbeddingModel	string (uuid)	否	null	默认嵌入模型 ID
defaultSummaryModel	string (uuid)	否	null	默认摘要模型 ID
maxContextLoadTime	number	否	60	Agent 加载上下文的时间范围（分钟，1-1440）
language	string	否	"Same as user input"	Agent 回复的首选语言

成功响应 (200 OK)

{
  "success": true,
  "data": {
    "userId": "user-id",
    "defaultChatModel": "123e4567-e89b-12d3-a456-426614174000",
    "defaultEmbeddingModel": "223e4567-e89b-12d3-a456-426614174001",
    "defaultSummaryModel": "323e4567-e89b-12d3-a456-426614174002",
    "maxContextLoadTime": 60,
    "language": "Chinese"
  }
}

---

使用示例

完整工作流

# 1. 登录获取 token
TOKEN=$(curl -X POST http://localhost:7002/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}' \
  | jq -r '.data.token')

# 2. 获取当前设置
curl http://localhost:7002/settings \
  -H "Authorization: Bearer $TOKEN"

# 3. 更新设置
curl -X PUT http://localhost:7002/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultChatModel": "123e4567-e89b-12d3-a456-426614174000",
    "defaultEmbeddingModel": "223e4567-e89b-12d3-a456-426614174001",
    "defaultSummaryModel": "323e4567-e89b-12d3-a456-426614174002",
    "maxContextLoadTime": 120,
    "language": "English"
  }'

# 4. 只更新部分字段
curl -X PUT http://localhost:7002/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maxContextLoadTime": 30,
    "language": "Chinese"
  }'

JavaScript/TypeScript 示例

// 获取设置
async function getSettings(token: string) {
  const response = await fetch('http://localhost:7002/settings', {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  })
  
  const data = await response.json()
  return data
}

// 更新设置
async function updateSettings(token: string, settings: {
  defaultChatModel?: string
  defaultEmbeddingModel?: string
  defaultSummaryModel?: string
  maxContextLoadTime?: number
  language?: string
}) {
  const response = await fetch('http://localhost:7002/settings', {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(settings),
  })
  
  const data = await response.json()
  return data
}

// 使用示例
const token = 'your_jwt_token'

// 获取当前设置
const currentSettings = await getSettings(token)
console.log(currentSettings)

// 更新 Agent 设置
await updateSettings(token, {
  maxContextLoadTime: 90,
  language: 'Chinese',
})

---

Agent 设置说明

maxContextLoadTime

控制 Agent 加载历史对话上下文的时间范围。

• 类型: 整数（分钟）
• 范围: 1-1440（1分钟到24小时）
• 默认值: 60（1小时）
• 说明:
  • 值越大，Agent 能访问更久远的对话历史
  • 但也会增加 token 使用量和响应时间
  • 建议根据实际需求调整

示例:

• 30 - 加载最近30分钟的对话
• 60 - 加载最近1小时的对话（默认）
• 1440 - 加载最近24小时的对话

language

设置 Agent 回复的首选语言。

• 类型: 字符串
• 默认值: "Same as user input"（与用户输入相同）
• 说明:
  • 可以设置为任何语言名称
  • Agent 会尽量使用指定语言回复
  • 特殊值 "Same as user input" 表示跟随用户输入语言

常用值:

• "Same as user input" - 自动匹配用户语言（默认）
• "Chinese" - 中文
• "English" - 英文
• "Japanese" - 日文
• "Spanish" - 西班牙语

---

Agent 使用优先级

当使用 Agent API 时，配置的优先级为：

1. 请求参数 - /agent/stream 请求中直接指定的参数
2. 用户设置 - Settings 中保存的默认值
3. 系统默认 - 内置的默认值

示例:

# 情况1: 使用请求参数（最高优先级）
curl -X POST http://localhost:7002/agent/stream \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "message": "Hello",
    "maxContextLoadTime": 30,
    "language": "English"
  }'
# 使用: maxContextLoadTime=30, language="English"

# 情况2: 使用用户设置（如果请求中未指定）
# 假设用户设置: maxContextLoadTime=60, language="Chinese"
curl -X POST http://localhost:7002/agent/stream \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message": "Hello"}'
# 使用: maxContextLoadTime=60, language="Chinese"

# 情况3: 使用系统默认（如果都未设置）
# 使用: maxContextLoadTime=60, language="Same as user input"

---

数据库 Schema

CREATE TABLE settings (
  user_id TEXT PRIMARY KEY,
  default_chat_model UUID REFERENCES model(id),
  default_embedding_model UUID REFERENCES model(id),
  default_summary_model UUID REFERENCES model(id),
  max_context_load_time INTEGER DEFAULT 60,
  language TEXT DEFAULT 'Same as user input'
);

---

相关文档

• Agent API
• Model API
• 认证系统
• API 变更说明