api-box/PRD.md

产品需求文档 (PRD)：AI API 配置与对话简易工具

---

1. 背景

随着大模型应用普及，开发者需频繁切换不同厂商的API（如 OpenAI、通义千问、硅基流动）。现有方案操作繁琐（需手动修改代码/环境变量），缺乏统一配置入口。本工具旨在提供轻量级 Web 界面，支持快速配置主流厂商 API 并进行简单对话，提升开发效率。

---

2. 目标

• ✅ 核心目标：用户通过 1 个页面完成所有厂商 API 配置与对话测试
• ✅ 关键指标：
  • 配置操作简易（选厂商 → 输入密钥/接入点 → 保存）
  • 支持主流厂商

---

3. 项目范围

范围	包含	不包含
功能	- 厂商配置管理（密钥/接入点） - 多厂商对话界面 - 安全存储密钥	- 用户认证/权限管理 - 聊天历史记录 - 复杂对话逻辑（如 multi-turn）
支持厂商	OpenAI, Anthropic, Google (Gemini), 阿里云（通义千问）, 百度（文心一言）	本地模型（如 Llama）、定制化厂商 API
安全	密钥加密存储、禁止明文展示	无 Key 管理后台（纯客户端安全）
平台	现代浏览器（Chrome/Firefox/Safari）	移动端适配、桌面应用

✨ 附录：厂商支持列表

厂商	接入点示例	密钥类型
OpenAI	https://api.openai.com/v1/chat/completions	sk-...
Anthropic	https://api.anthropic.com/v1/messages	sk-...
Google	https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent	AIza...
阿里云通义	https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation	sk-...
百度文心	https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/ernie\_bot	your_api_key

---

4. 功能需求

4.1 厂商配置管理（核心功能）

功能	说明	用户操作流
厂商下拉选择	- 预置 5 个厂商（见附录表格），下拉菜单中自动隐藏未启用的厂商	1. 点击下拉框 → 2. 选中目标厂商
密钥/接入点输入	- 动态显示对应字段（OpenAI 需输入 密钥+接入点，通义需输入 API Key）	1. 填写密钥（如 sk-abc123） 2. 填写接入点（默认预填）
保存与验证	- 保存时自动校验密钥格式（如 OpenAI 密钥以 sk- 开头） - 不存储明文，使用 AES-256 加密后存入浏览器 localStorage	1. 点击「保存配置」→ 2. 成功提示 → 3. 即时生效（无需刷新）

⚠️ 安全设计：

• 密钥在客户端加密存储，服务端不接触密钥
• 配置页面关闭后，密钥不可恢复（用户需重新配置）

4.2 AI 对话界面（核心功能）

功能	说明
对话输入框	单行文本输入，支持中文/英文提问（示例：“解释量子计算”）
厂商选择器	对话前必选：从已配置的厂商列表中选（默认显示按配置顺序排序）
发送与响应	- 点击「发送」按钮 → 显示加载状态 → 厂商 API 返回结果显示在底部
错误处理	- 密钥错误 → 提示 “厂商 [X] 密钥无效” - 服务端错误 → 提示 “[厂商] API 调用失败 (错误码: 500)”

🌰 示例流程：

1. 用户在配置页为 OpenAI 保存密钥 sk-test123
2. 进入对话页 → 选 OpenAI → 输入 “写首关于AI的诗” → 点击发送
3. 即时显示 OpenAI 返回的诗句

---

5. 非功能需求

类别	要求
性能	配置保存响应时间 ≤ 500ms；对话响应 ≤ 3s（依赖厂商）
可用性	0 学习成本：所有操作 ≤ 3 步，无复杂菜单
可扩展性	新增厂商仅需修改前端配置表（无需改代码）
安全	100% 避免明文密钥存储，废弃旧配置自动清除
兼容性	支持 Chrome/Firefox/Safari 最新版，不兼容 IE

---

6. 应用流程图

graph TD
    A[访问主页] --> B[配置厂商]
    B --> C{是否选择新厂商}
    C -- 是 --> D[填写厂商/密钥/接入点]
    D --> E[保存加密]
    E --> B
    C -- 否 --> F[对话界面]
    F --> G[选厂商 + 输入提问]
    G --> H[调用厂商 API]
    H --> I{成功}
    I -- 是 --> J[显示结果]
    I -- 否 --> K[显示错误提示]

---

7. 紧急问题处理

问题场景	解决方案
用户误填错误密钥	配置页右侧显示“密钥验证失败”提醒
厂商 API 调用超时	支持重试（1 次），超时后提示“服务不可用”
首次使用无任何厂商配置	顶部显示提示“请先配置厂商：OpenAI/通义千问”

---

8. 附录：厂商配置预设

// 前端配置表（示例，可增加新厂商）
const PLATFORMS = [
  {
    id: 'openai',
    name: 'OpenAI',
    endpoint: 'https://api.openai.com/v1/chat/completions',
    keyPlaceholder: 'sk-...',
    keyType: 'api_key'
  },
  {
    id: 'qwen',
    name: '通义千问（阿里云）',
    endpoint: 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation',
    keyPlaceholder: 'sk-...',
    keyType: 'api_key'
  },
  // 其他厂商...
];