Skip to content

ai.md

Latest commit

 

History

History
85 lines (84 loc) · 5.29 KB

ai.md

File metadata and controls

85 lines (84 loc) · 5.29 KB
Raw

🐱 BongoCat AI 轻量级多模型接入需求文档

1. 概述

为 BongoCat 桌面宠物增加轻量级的 AI 对话能力。核心原则是“极简与统一”：

  • 统一协议：采用 OpenAI 兼容的 /v1/chat/completions 协议作为唯一标准，通过替换 Base URL 实现对主流大模型（DeepSeek、Kimi、通义千问、Minimax、OpenAI、本地 Ollama 等）的接入。
  • 极简配置：用户只需配置 API Base URL、API Key 和 Model Name 即可使用，无需部署中间网关。
  • 宠物特化：对话需强制注入猫咪人设，并限制回复长度，符合桌面宠物的陪伴定位。

2. 数据模型

用户配置及历史上下文需持久化存储在本地（推荐 Tauri 的 app_data_dir 下的 ai_config.json）。

2.1 配置文件结构 (ai_config.json)

{
  "api_base_url": "https://api.deepseek.com/v1",
  "api_key": "sk-xxxxxxxxxxxxxxxx",
  "model_name": "deepseek-chat",
  "max_history_count": 10,
  "system_prompt": "你是BongoCat，一只生活在用户桌面上的可爱猫咪。你说话简短、傲娇，喜欢用emoji。回复绝对不能超过50个字！",
  "max_tokens": 150
}

2.2 字段说明

字段 类型 必填 说明 默认值
api_base_url string 是 API 根地址，必须包含 /v1。例如 DeepSeek 为 https://api.deepseek.com/v1，本地 Ollama 为 http://localhost:11434/v1 无
api_key string 是 用户在各平台申请的 API Key。本地 Ollama 可填 ollama 或任意字符 无
model_name string 是 模型名称，如 deepseek-chat, moonshot-v1-8k, gpt-3.5-turbo, llama3 无
max_history_count number 否 携带的最近对话轮数（一问一答为1轮），用于短期记忆，防止上下文溢出 10
system_prompt string 否 宠物人设提示词，每次请求强制置于消息列表首位 (内置猫咪人设)
max_tokens number 否 AI 回复的最大 Token 数，限制长篇大论 150

3. 前端 UI 需求 (React)

需要实现一个轻量级的设置面板，可通过点击猫咪或系统托盘的“⚙️设置”打开。

3.1 预设快捷填充 (核心体验优化)

为降低用户配置门槛，前端需提供服务商预设下拉菜单。当用户选择某服务商时，自动填充 api_base_url 和默认 model_name，用户只需填入 Key 即可。 预设列表逻辑：

  • DeepSeek: URL=https://api.deepseek.com/v1, Model=deepseek-chat
  • Kimi (月之暗面): URL=https://api.moonshot.cn/v1, Model=moonshot-v1-8k
  • Minimax: URL=https://api.minimax.chat/v1, Model=abab6.5s-chat
  • OpenAI: URL=https://api.openai.com/v1, Model=gpt-3.5-turbo
  • 本地 Ollama: URL=http://localhost:11434/v1, Model=llama3 (Key框置灰或填入 ollama)

3.2 表单元素

  1. 服务商预设：Select 下拉框（含“自定义”选项）
  2. API Base URL：Input 文本框（选择预设后自动填充，选“自定义”时可手动输入）
  3. API Key：Password 密码输入框（带显示/隐藏开关）
  4. Model Name：Input 文本框
  5. 测试连接：Button 按钮（调用后端测试接口，成功返回 "喵~ 连上了！"，失败返回错误原因）
  6. 保存配置：Button 按钮

4. 后端逻辑需求

4.1 统一请求接口

封装一个 HTTP Client (如 reqwest)，向 ${api_base_url}/chat/completions 发送 POST 请求。 请求头构建规则：

{
  "Content-Type": "application/json",
  "Authorization": "Bearer ${api_key}"
}

请求体构建规则：

{
  "model": "${model_name}",
  "messages": [
    {"role": "system", "content": "${system_prompt}"},
    // ... 从本地内存/文件读取的最近 max_history_count 轮历史对话
    {"role": "user", "content": "当前用户输入"}
  ],
  "max_tokens": ${max_tokens},
  "stream": false // 桌面宠物场景优先保证稳定性，暂不要求流式输出
}

4.2 记忆管理机制 (滑动窗口)

  • 每次发起请求前，从本地读取历史对话记录数组。
  • 截取数组的最后 max_history_count * 2 条消息（包含 user 和 assistant），拼接在 system_prompt 之后。
  • 收到 AI 回复后，将当前的 [用户输入, AI回复] 追加到本地历史记录中，并持久化保存。

4.3 异常处理与宠物化包装

后端捕获所有网络、鉴权、余额不足等错误，不要将原始的 HTTP 错误码抛给前端，而是转换为宠物的口吻返回字符串。

  • 401 鉴权失败："喵？钥匙不对劲，不让我说话！"
  • 402 余额不足："铲屎官，好像没钱买猫粮了..."
  • 网络超时："喵...信号不好，我先睡会儿"
  • 未知错误："遇到了奇怪的虫子，抓不到！"

5. Agent (Minimax) 实现指引

请作为全栈工程师，根据上述需求完成以下任务：

  1. Rust 后端：在 src-tauri/src/ 下创建 ai.rs，实现读取配置、构建 HTTP 请求、滑动窗口记忆、错误宠物化包装的逻辑。并在 main.rs 中注册 chat_with_ai 和 test_ai_connection 两个 Tauri Command。
  2. React 前端：在 src/components/ 下创建 AiSettings.tsx，实现包含预设下拉、表单输入、测试连接的设置面板。
  3. 类型定义：提供必要的 TypeScript 接口定义。