Compare commits
5 Commits
aea360bce8
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
| f3a207fa16 | |||
| 56ecc73d1b | |||
| 1ae9336cbe | |||
| 3fa5827de3 | |||
| cfb0edf802 |
81
.gitignore
vendored
81
.gitignore
vendored
@@ -317,6 +317,87 @@ Network Trash Folder
|
||||
Temporary Items
|
||||
.apdisk
|
||||
|
||||
### Python.gitignore ###
|
||||
# Byte-compiled / optimized / DLL files
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
|
||||
# C extensions
|
||||
*.so
|
||||
|
||||
# Distribution / packaging
|
||||
.Python
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
|
||||
# PyInstaller
|
||||
*.manifest
|
||||
*.spec
|
||||
|
||||
# Installer logs
|
||||
pip-log.txt
|
||||
pip-delete-this-directory.txt
|
||||
|
||||
# Unit test / coverage reports
|
||||
htmlcov/
|
||||
.tox/
|
||||
.nox/
|
||||
.coverage
|
||||
.coverage.*
|
||||
nosetests.xml
|
||||
coverage.xml
|
||||
*.cover
|
||||
*.py,cover
|
||||
.hypothesis/
|
||||
.pytest_cache/
|
||||
|
||||
# Translations
|
||||
*.mo
|
||||
*.pot
|
||||
|
||||
# Environments
|
||||
.venv/
|
||||
venv/
|
||||
ENV/
|
||||
env/
|
||||
.python-version
|
||||
|
||||
# Spyder project settings
|
||||
.spyderproject
|
||||
.spyproject
|
||||
|
||||
# Rope project settings
|
||||
.ropeproject
|
||||
|
||||
# mkdocs documentation
|
||||
/site
|
||||
|
||||
# mypy
|
||||
.mypy_cache/
|
||||
|
||||
# Pyre
|
||||
.pyre/
|
||||
|
||||
# pytype
|
||||
.pytype/
|
||||
|
||||
# Cython debug symbols
|
||||
cython_debug/
|
||||
|
||||
# Custom
|
||||
.claude
|
||||
.opencode
|
||||
|
||||
@@ -26,7 +26,7 @@ AI 网关后端服务，提供统一的大模型 API 代理接口。
|
||||
- **ORM**: GORM
|
||||
- **数据库**: SQLite
|
||||
- **日志**: zap + lumberjack
|
||||
- **配置**: gopkg.in/yaml.v3
|
||||
- **配置**: Viper + pflag（多层配置：CLI > 环境变量 > 配置文件 > 默认值）
|
||||
- **验证**: go-playground/validator/v10
|
||||
- **迁移**: goose
|
||||
|
||||
@@ -39,7 +39,7 @@ backend/
|
||||
│ └── main.go # 主程序入口（依赖注入）
|
||||
├── internal/
|
||||
│ ├── config/ # 配置管理
|
||||
│ │ ├── config.go # 配置加载/保存/验证
|
||||
│ │ ├── config.go # Viper 多层配置加载/验证
|
||||
│ │ └── models.go # GORM 数据模型
|
||||
│ ├── domain/ # 领域模型
|
||||
│ │ ├── provider.go
|
||||
@@ -47,17 +47,17 @@ backend/
|
||||
│ │ ├── stats.go
|
||||
│ │ └── route.go
|
||||
│ ├── handler/ # HTTP 处理器
|
||||
│ │ ├── middleware/ # 中间件
|
||||
│ │ ├── middleware/ # 中间件
|
||||
│ │ │ ├── request_id.go
|
||||
│ │ │ ├── logging.go
|
||||
│ │ │ ├── recovery.go
|
||||
│ │ │ └── cors.go
|
||||
│ │ ├── proxy_handler.go # 统一代理处理器
|
||||
│ │ ├── proxy_handler.go # 统一代理处理器
|
||||
│ │ ├── provider_handler.go
|
||||
│ │ ├── model_handler.go
|
||||
│ │ └── stats_handler.go
|
||||
│ ├── conversion/ # 协议转换引擎
|
||||
│ │ ├── canonical/ # Canonical Model
|
||||
│ ├── conversion/ # 协议转换引擎
|
||||
│ │ ├── canonical/ # Canonical Model
|
||||
│ │ │ ├── types.go # 核心请求/响应类型
|
||||
│ │ │ ├── stream.go # 流式事件类型
|
||||
│ │ │ └── extended.go # 扩展层 Models
|
||||
@@ -111,13 +111,12 @@ backend/
|
||||
│ └── validator/ # 验证器
|
||||
│ └── validator.go
|
||||
├── migrations/ # 数据库迁移
|
||||
│ ├── 001_initial_schema.sql
|
||||
│ └── 002_add_indexes.sql
|
||||
├── tests/ # 测试
|
||||
│ ├── 20260401000001_initial_schema.sql
|
||||
│ ├── 20260401000002_add_indexes.sql
|
||||
│ └── 20260419000001_add_provider_protocol.sql
|
||||
├── tests/ # 集成测试
|
||||
│ ├── helpers.go
|
||||
│ ├── integration/
|
||||
│ ├── unit/
|
||||
│ └── testdata/
|
||||
│ └── integration/
|
||||
├── Makefile
|
||||
├── go.mod
|
||||
└── README.md
|
||||
@@ -133,6 +132,19 @@ handler（HTTP 请求处理）
|
||||
→ repository（数据访问）
|
||||
```
|
||||
|
||||
代理请求通过 ConversionEngine 进行协议转换：
|
||||
|
||||
```
|
||||
Client Request (clientProtocol)
|
||||
→ ProxyHandler 路由到上游 provider
|
||||
→ ConversionEngine 请求转换 (clientProtocol → providerProtocol)
|
||||
→ ProviderClient 发送请求
|
||||
→ ConversionEngine 响应转换 (providerProtocol → clientProtocol)
|
||||
→ Client Response
|
||||
```
|
||||
|
||||
同协议时自动透传，跳过序列化开销。
|
||||
|
||||
## 运行方式
|
||||
|
||||
### 安装依赖
|
||||
@@ -151,6 +163,10 @@ go run cmd/server/main.go
|
||||
|
||||
## 配置
|
||||
|
||||
配置支持多种方式：配置文件、环境变量、命令行参数，优先级为：**CLI 参数 > 环境变量 > 配置文件 > 默认值**
|
||||
|
||||
### 配置文件
|
||||
|
||||
配置文件位于 `~/.nex/config.yaml`，首次启动自动生成。
|
||||
|
||||
```yaml
|
||||
@@ -174,6 +190,54 @@ log:
|
||||
compress: true
|
||||
```
|
||||
|
||||
### 环境变量
|
||||
|
||||
所有配置项都支持环境变量，使用 `NEX_` 前缀：
|
||||
|
||||
```bash
|
||||
export NEX_SERVER_PORT=9000
|
||||
export NEX_DATABASE_PATH=/data/nex.db
|
||||
export NEX_LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
命名规则：配置路径转大写 + 下划线 + `NEX_` 前缀（如 `server.port` → `NEX_SERVER_PORT`）。
|
||||
|
||||
### 命令行参数
|
||||
|
||||
```bash
|
||||
./server --server-port 9000 --log-level debug --database-path /tmp/test.db
|
||||
```
|
||||
|
||||
命名规则：配置路径转 kebab-case + `--` 前缀（如 `server.port` → `--server-port`）。
|
||||
|
||||
完整参数列表：
|
||||
|
||||
```
|
||||
服务器: --server-port, --server-read-timeout, --server-write-timeout
|
||||
数据库: --database-path, --database-max-idle-conns, --database-max-open-conns, --database-conn-max-lifetime
|
||||
日志: --log-level, --log-path, --log-max-size, --log-max-backups, --log-max-age, --log-compress
|
||||
通用: --config (指定配置文件路径)
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
|
||||
```bash
|
||||
# 默认配置
|
||||
./server
|
||||
|
||||
# 临时修改端口
|
||||
./server --server-port 9000
|
||||
|
||||
# 测试场景
|
||||
./server --database-path /tmp/test.db --log-level debug
|
||||
|
||||
# Docker 部署
|
||||
docker run -d -e NEX_SERVER_PORT=9000 -e NEX_LOG_LEVEL=info nex-server
|
||||
|
||||
# 自定义配置文件
|
||||
./server --config /path/to/custom.yaml
|
||||
```
|
||||
|
||||
数据文件：
|
||||
- `~/.nex/config.yaml` - 配置文件
|
||||
- `~/.nex/config.db` - SQLite 数据库
|
||||
@@ -197,6 +261,9 @@ make migrate-up DB_PATH=~/.nex/config.db
|
||||
make migrate-down DB_PATH=~/.nex/config.db
|
||||
make migrate-status DB_PATH=~/.nex/config.db
|
||||
|
||||
# 创建新迁移
|
||||
make migrate-create
|
||||
|
||||
# 或直接使用 goose
|
||||
goose -dir migrations sqlite3 ~/.nex/config.db up
|
||||
```
|
||||
@@ -207,7 +274,7 @@ goose -dir migrations sqlite3 ~/.nex/config.db up
|
||||
|
||||
使用 `/{protocol}/v1/{path}` URL 前缀路由：
|
||||
|
||||
#### OpenAI 协议代理
|
||||
#### OpenAI 协议
|
||||
|
||||
```
|
||||
POST /openai/v1/chat/completions
|
||||
@@ -216,37 +283,13 @@ POST /openai/v1/embeddings
|
||||
POST /openai/v1/rerank
|
||||
```
|
||||
|
||||
请求示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-4",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello"}
|
||||
],
|
||||
"stream": false
|
||||
}
|
||||
```
|
||||
|
||||
#### Anthropic 协议代理
|
||||
#### Anthropic 协议
|
||||
|
||||
```
|
||||
POST /anthropic/v1/messages
|
||||
GET /anthropic/v1/models
|
||||
```
|
||||
|
||||
请求示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "claude-3-opus",
|
||||
"max_tokens": 1024,
|
||||
"messages": [
|
||||
{"role": "user", "content": [{"type": "text", "text": "Hello"}]}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**协议转换**：网关支持任意协议间的双向转换。客户端使用 OpenAI 协议请求，上游供应商可以是 Anthropic 协议（反之亦然）。同协议时自动透传，零序列化开销。
|
||||
|
||||
### 管理接口
|
||||
@@ -259,8 +302,6 @@ GET /anthropic/v1/models
|
||||
- `PUT /api/providers/:id` - 更新供应商
|
||||
- `DELETE /api/providers/:id` - 删除供应商
|
||||
|
||||
创建供应商示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "openai",
|
||||
@@ -271,15 +312,9 @@ GET /anthropic/v1/models
|
||||
}
|
||||
```
|
||||
|
||||
**Protocol 字段说明：**
|
||||
- `protocol` 标识上游供应商使用的协议类型，可选值：`"openai"`（默认）、`"anthropic"`
|
||||
- 同协议透传时，请求体和响应体原样转发，零序列化开销
|
||||
**Protocol 字段**：标识上游供应商使用的协议类型，可选值 `"openai"`（默认）、`"anthropic"`。
|
||||
|
||||
**重要说明：**
|
||||
- `base_url` 应配置到 API 版本路径，不包含具体端点
|
||||
- OpenAI: `https://api.openai.com/v1`
|
||||
- GLM: `https://open.bigmodel.cn/api/paas/v4`
|
||||
- 其他 OpenAI 兼容供应商根据其文档配置版本路径
|
||||
**base_url 说明**：应配置到 API 版本路径，不包含具体端点（如 OpenAI: `https://api.openai.com/v1`，GLM: `https://open.bigmodel.cn/api/paas/v4`）。
|
||||
|
||||
#### 模型管理
|
||||
|
||||
@@ -289,8 +324,6 @@ GET /anthropic/v1/models
|
||||
- `PUT /api/models/:id` - 更新模型
|
||||
- `DELETE /api/models/:id` - 删除模型
|
||||
|
||||
创建模型示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "gpt-4",
|
||||
@@ -304,61 +337,43 @@ GET /anthropic/v1/models
|
||||
- `GET /api/stats` - 查询统计
|
||||
- `GET /api/stats/aggregate` - 聚合统计
|
||||
|
||||
查询参数：
|
||||
查询参数：`provider_id`、`model_name`、`start_date`（YYYY-MM-DD）、`end_date`、`group_by`（provider/model/date）
|
||||
|
||||
- `provider_id` - 供应商 ID
|
||||
- `model_name` - 模型名称
|
||||
- `start_date` - 开始日期（YYYY-MM-DD）
|
||||
- `end_date` - 结束日期（YYYY-MM-DD）
|
||||
- `group_by` - 聚合维度（provider/model/date）
|
||||
#### 健康检查
|
||||
|
||||
- `GET /health` - 返回 `{"status": "ok"}`
|
||||
|
||||
## 开发
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
make build
|
||||
make build # 构建
|
||||
make lint # 代码检查
|
||||
make deps # 整理依赖
|
||||
```
|
||||
|
||||
### 代码检查
|
||||
|
||||
```bash
|
||||
make lint
|
||||
```
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Go 1.26 或更高版本
|
||||
环境要求：Go 1.26 或更高版本
|
||||
|
||||
## 公共库使用指南
|
||||
|
||||
### pkg/errors — 结构化错误
|
||||
|
||||
使用预定义的错误类型，配合 `errors.Is` / `errors.As` 判断错误：
|
||||
|
||||
```go
|
||||
import (
|
||||
"errors"
|
||||
pkgErrors "nex/backend/pkg/errors"
|
||||
)
|
||||
|
||||
// 使用预定义错误
|
||||
return pkgErrors.ErrRequestSend.WithCause(err)
|
||||
|
||||
// 判断错误类型
|
||||
var appErr *pkgErrors.AppError
|
||||
if errors.As(err, &appErr) {
|
||||
// appErr.Code, appErr.HTTPStatus, appErr.Message
|
||||
}
|
||||
```
|
||||
|
||||
可用函数：`NewAppError`、`Wrap`、`WithContext`、`WithMessage`、`AsAppError`
|
||||
|
||||
预定义错误：`ErrModelNotFound`、`ErrProviderNotFound`、`ErrInvalidRequest`、`ErrRequestCreate`、`ErrRequestSend`、`ErrResponseRead` 等
|
||||
|
||||
### pkg/logger — 日志系统
|
||||
|
||||
使用依赖注入模式，构造函数接受 `*zap.Logger` 参数，nil 时回退到 `zap.L()`：
|
||||
构造函数接受 `*zap.Logger` 参数，nil 时回退到 `zap.L()`：
|
||||
|
||||
```go
|
||||
func NewMyService(repo Repository, logger *zap.Logger) *MyService {
|
||||
@@ -369,8 +384,6 @@ func NewMyService(repo Repository, logger *zap.Logger) *MyService {
|
||||
}
|
||||
```
|
||||
|
||||
禁止直接在业务代码中使用 `zap.L()` 全局 logger，应通过构造函数注入。
|
||||
|
||||
### pkg/validator — 请求验证
|
||||
|
||||
```go
|
||||
@@ -382,8 +395,8 @@ err := v.Validate(myStruct)
|
||||
|
||||
## 编码规范
|
||||
|
||||
- **JSON 解析**：使用 `encoding/json` 标准库（`json.Unmarshal` / `json.Marshal`），不手动扫描字节
|
||||
- **JSON 解析**：使用 `encoding/json` 标准库，不手动扫描字节
|
||||
- **字符串拼接**：使用 `strings.Join`，不手写循环拼接
|
||||
- **错误判断**：使用 `errors.Is` / `errors.As`，不使用字符串匹配（`strings.Contains(err.Error(), ...)`）
|
||||
- **错误判断**：使用 `errors.Is` / `errors.As`，不使用字符串匹配
|
||||
- **日志使用**：通过依赖注入 `*zap.Logger`，不直接调用 `zap.L()`
|
||||
- **字符串分割**：使用 `strings.SplitN(key, "/", 2)` 等精确分割，不使用索引切片
|
||||
- **字符串分割**：使用 `strings.SplitN` 等精确分割，不使用索引切片
|
||||
|
||||
@@ -32,16 +32,16 @@ import (
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 1. 加载配置
|
||||
// 1. 加载配置（已包含 CLI 参数解析、环境变量绑定、配置文件读取和验证）
|
||||
cfg, err := config.LoadConfig()
|
||||
if err != nil {
|
||||
log.Fatalf("加载配置失败: %v", err)
|
||||
}
|
||||
if err := cfg.Validate(); err != nil {
|
||||
log.Fatalf("配置验证失败: %v", err)
|
||||
}
|
||||
|
||||
// 2. 初始化日志
|
||||
// 2. 打印配置摘要
|
||||
cfg.PrintSummary()
|
||||
|
||||
// 3. 初始化日志
|
||||
zapLogger, err := pkgLogger.New(pkgLogger.Config{
|
||||
Level: cfg.Log.Level,
|
||||
Path: cfg.Log.Path,
|
||||
|
||||
@@ -4,8 +4,12 @@ go 1.26.2
|
||||
|
||||
require (
|
||||
github.com/gin-gonic/gin v1.12.0
|
||||
github.com/go-playground/validator/v10 v10.30.2
|
||||
github.com/google/uuid v1.6.0
|
||||
github.com/mitchellh/mapstructure v1.5.0
|
||||
github.com/pressly/goose/v3 v3.27.0
|
||||
github.com/spf13/pflag v1.0.10
|
||||
github.com/spf13/viper v1.21.0
|
||||
github.com/stretchr/testify v1.11.1
|
||||
go.uber.org/zap v1.27.1
|
||||
gopkg.in/lumberjack.v2 v2.0.0
|
||||
@@ -20,12 +24,13 @@ require (
|
||||
github.com/bytedance/sonic v1.15.0 // indirect
|
||||
github.com/bytedance/sonic/loader v0.5.0 // indirect
|
||||
github.com/cloudwego/base64x v0.1.6 // indirect
|
||||
github.com/davecgh/go-spew v1.1.1 // indirect
|
||||
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
|
||||
github.com/fsnotify/fsnotify v1.9.0 // indirect
|
||||
github.com/gabriel-vasile/mimetype v1.4.13 // indirect
|
||||
github.com/gin-contrib/sse v1.1.0 // indirect
|
||||
github.com/go-playground/locales v0.14.1 // indirect
|
||||
github.com/go-playground/universal-translator v0.18.1 // indirect
|
||||
github.com/go-playground/validator/v10 v10.30.2 // indirect
|
||||
github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
|
||||
github.com/goccy/go-json v0.10.5 // indirect
|
||||
github.com/goccy/go-yaml v1.19.2 // indirect
|
||||
github.com/jinzhu/inflection v1.0.0 // indirect
|
||||
@@ -39,14 +44,20 @@ require (
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
|
||||
github.com/modern-go/reflect2 v1.0.2 // indirect
|
||||
github.com/pelletier/go-toml/v2 v2.2.4 // indirect
|
||||
github.com/pmezard/go-difflib v1.0.0 // indirect
|
||||
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
|
||||
github.com/quic-go/qpack v0.6.0 // indirect
|
||||
github.com/quic-go/quic-go v0.59.0 // indirect
|
||||
github.com/sagikazarmark/locafero v0.11.0 // indirect
|
||||
github.com/sethvargo/go-retry v0.3.0 // indirect
|
||||
github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
|
||||
github.com/spf13/afero v1.15.0 // indirect
|
||||
github.com/spf13/cast v1.10.0 // indirect
|
||||
github.com/subosito/gotenv v1.6.0 // indirect
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
|
||||
github.com/ugorji/go/codec v1.3.1 // indirect
|
||||
go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
|
||||
go.uber.org/multierr v1.11.0 // indirect
|
||||
go.yaml.in/yaml/v3 v3.0.4 // indirect
|
||||
golang.org/x/arch v0.22.0 // indirect
|
||||
golang.org/x/crypto v0.49.0 // indirect
|
||||
golang.org/x/net v0.51.0 // indirect
|
||||
|
||||
@@ -9,12 +9,15 @@ github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCc
|
||||
github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
|
||||
github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
|
||||
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
|
||||
github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
|
||||
github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
|
||||
github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
|
||||
github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
|
||||
github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
|
||||
github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
|
||||
github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
|
||||
github.com/gabriel-vasile/mimetype v1.4.13 h1:46nXokslUBsAJE/wMsp5gtO500a4F3Nkz9Ufpk2AcUM=
|
||||
github.com/gabriel-vasile/mimetype v1.4.13/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
|
||||
github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
|
||||
@@ -27,10 +30,10 @@ github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/o
|
||||
github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
|
||||
github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
|
||||
github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
|
||||
github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
|
||||
github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
|
||||
github.com/go-playground/validator/v10 v10.30.2 h1:JiFIMtSSHb2/XBUbWM4i/MpeQm9ZK2xqPNk8vgvu5JQ=
|
||||
github.com/go-playground/validator/v10 v10.30.2/go.mod h1:mAf2pIOVXjTEBrwUMGKkCWKKPs9NheYGabeB04txQSc=
|
||||
github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
|
||||
github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
|
||||
github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
|
||||
github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
|
||||
github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
|
||||
@@ -60,6 +63,8 @@ github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o
|
||||
github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
|
||||
github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
|
||||
github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
|
||||
github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
|
||||
github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
|
||||
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
|
||||
@@ -69,8 +74,9 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
|
||||
github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
|
||||
github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
|
||||
github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
|
||||
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/pressly/goose/v3 v3.27.0 h1:/D30gVTuQhu0WsNZYbJi4DMOsx1lNq+6SkLe+Wp59BM=
|
||||
github.com/pressly/goose/v3 v3.27.0/go.mod h1:3ZBeCXqzkgIRvrEMDkYh1guvtoJTU5oMMuDdkutoM78=
|
||||
github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
|
||||
@@ -81,8 +87,20 @@ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94
|
||||
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
|
||||
github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
|
||||
github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
|
||||
github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
|
||||
github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
|
||||
github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
|
||||
github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
|
||||
github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
|
||||
github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8/go.mod h1:3n1Cwaq1E1/1lhQhtRK2ts/ZwZEhjcQeJQ1RuC6Q/8U=
|
||||
github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
|
||||
github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
|
||||
github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
|
||||
github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
|
||||
github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
|
||||
github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
||||
github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
|
||||
github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
|
||||
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
|
||||
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
|
||||
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
|
||||
@@ -94,6 +112,8 @@ github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXl
|
||||
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
|
||||
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
|
||||
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
|
||||
github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
|
||||
github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
|
||||
github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
|
||||
@@ -108,27 +128,21 @@ go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
|
||||
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
|
||||
go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
|
||||
go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
|
||||
go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
|
||||
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
|
||||
golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
|
||||
golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
|
||||
golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
|
||||
golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
|
||||
golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
|
||||
golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
|
||||
golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa h1:Zt3DZoOFFYkKhDT3v7Lm9FDMEV06GpzjG2jrqW+QTE0=
|
||||
golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
|
||||
golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
|
||||
golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
|
||||
golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
|
||||
golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
|
||||
golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
|
||||
golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
|
||||
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
|
||||
golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
|
||||
golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
|
||||
golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
|
||||
golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
|
||||
golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
|
||||
golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
|
||||
golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
|
||||
golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
|
||||
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
|
||||
|
||||
@@ -4,8 +4,13 @@ import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/go-playground/validator/v10"
|
||||
"github.com/mitchellh/mapstructure"
|
||||
"github.com/spf13/pflag"
|
||||
"github.com/spf13/viper"
|
||||
"gopkg.in/yaml.v3"
|
||||
|
||||
appErrors "nex/backend/pkg/errors"
|
||||
@@ -13,34 +18,34 @@ import (
|
||||
|
||||
// Config 应用配置
|
||||
type Config struct {
|
||||
Server ServerConfig `yaml:"server"`
|
||||
Database DatabaseConfig `yaml:"database"`
|
||||
Log LogConfig `yaml:"log"`
|
||||
Server ServerConfig `yaml:"server" mapstructure:"server" validate:"required"`
|
||||
Database DatabaseConfig `yaml:"database" mapstructure:"database" validate:"required"`
|
||||
Log LogConfig `yaml:"log" mapstructure:"log" validate:"required"`
|
||||
}
|
||||
|
||||
// ServerConfig 服务器配置
|
||||
type ServerConfig struct {
|
||||
Port int `yaml:"port"`
|
||||
ReadTimeout time.Duration `yaml:"read_timeout"`
|
||||
WriteTimeout time.Duration `yaml:"write_timeout"`
|
||||
Port int `yaml:"port" mapstructure:"port" validate:"required,min=1,max=65535"`
|
||||
ReadTimeout time.Duration `yaml:"read_timeout" mapstructure:"read_timeout" validate:"required"`
|
||||
WriteTimeout time.Duration `yaml:"write_timeout" mapstructure:"write_timeout" validate:"required"`
|
||||
}
|
||||
|
||||
// DatabaseConfig 数据库配置
|
||||
type DatabaseConfig struct {
|
||||
Path string `yaml:"path"`
|
||||
MaxIdleConns int `yaml:"max_idle_conns"`
|
||||
MaxOpenConns int `yaml:"max_open_conns"`
|
||||
ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime"`
|
||||
Path string `yaml:"path" mapstructure:"path" validate:"required"`
|
||||
MaxIdleConns int `yaml:"max_idle_conns" mapstructure:"max_idle_conns" validate:"required,min=1"`
|
||||
MaxOpenConns int `yaml:"max_open_conns" mapstructure:"max_open_conns" validate:"required,min=1"`
|
||||
ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime" mapstructure:"conn_max_lifetime" validate:"required"`
|
||||
}
|
||||
|
||||
// LogConfig 日志配置
|
||||
type LogConfig struct {
|
||||
Level string `yaml:"level"`
|
||||
Path string `yaml:"path"`
|
||||
MaxSize int `yaml:"max_size"`
|
||||
MaxBackups int `yaml:"max_backups"`
|
||||
MaxAge int `yaml:"max_age"`
|
||||
Compress bool `yaml:"compress"`
|
||||
Level string `yaml:"level" mapstructure:"level" validate:"required,oneof=debug info warn error"`
|
||||
Path string `yaml:"path" mapstructure:"path" validate:"required"`
|
||||
MaxSize int `yaml:"max_size" mapstructure:"max_size" validate:"required,min=1"`
|
||||
MaxBackups int `yaml:"max_backups" mapstructure:"max_backups" validate:"required,min=0"`
|
||||
MaxAge int `yaml:"max_age" mapstructure:"max_age" validate:"required,min=0"`
|
||||
Compress bool `yaml:"compress" mapstructure:"compress"`
|
||||
}
|
||||
|
||||
// DefaultConfig returns default config values
|
||||
@@ -103,29 +108,143 @@ func GetConfigPath() (string, error) {
|
||||
return filepath.Join(configDir, "config.yaml"), nil
|
||||
}
|
||||
|
||||
// setupDefaults 设置默认配置值
|
||||
func setupDefaults(v *viper.Viper) {
|
||||
homeDir, _ := os.UserHomeDir()
|
||||
nexDir := filepath.Join(homeDir, ".nex")
|
||||
|
||||
v.SetDefault("server.port", 9826)
|
||||
v.SetDefault("server.read_timeout", "30s")
|
||||
v.SetDefault("server.write_timeout", "30s")
|
||||
|
||||
v.SetDefault("database.path", filepath.Join(nexDir, "config.db"))
|
||||
v.SetDefault("database.max_idle_conns", 10)
|
||||
v.SetDefault("database.max_open_conns", 100)
|
||||
v.SetDefault("database.conn_max_lifetime", "1h")
|
||||
|
||||
v.SetDefault("log.level", "info")
|
||||
v.SetDefault("log.path", filepath.Join(nexDir, "log"))
|
||||
v.SetDefault("log.max_size", 100)
|
||||
v.SetDefault("log.max_backups", 10)
|
||||
v.SetDefault("log.max_age", 30)
|
||||
v.SetDefault("log.compress", true)
|
||||
}
|
||||
|
||||
// setupFlags 定义和绑定 CLI 参数
|
||||
func setupFlags(v *viper.Viper, flagSet *pflag.FlagSet) {
|
||||
// 定义所有配置项的 CLI 参数
|
||||
// 注意：这里不设置默认值，让 viper 的默认值生效
|
||||
flagSet.Int("server-port", 0, "服务器端口")
|
||||
flagSet.Duration("server-read-timeout", 0, "读超时")
|
||||
flagSet.Duration("server-write-timeout", 0, "写超时")
|
||||
|
||||
flagSet.String("database-path", "", "数据库文件路径")
|
||||
flagSet.Int("database-max-idle-conns", 0, "最大空闲连接数")
|
||||
flagSet.Int("database-max-open-conns", 0, "最大打开连接数")
|
||||
flagSet.Duration("database-conn-max-lifetime", 0, "连接最大生命周期")
|
||||
|
||||
flagSet.String("log-level", "", "日志级别：debug/info/warn/error")
|
||||
flagSet.String("log-path", "", "日志文件目录")
|
||||
flagSet.Int("log-max-size", 0, "单个日志文件最大大小 MB")
|
||||
flagSet.Int("log-max-backups", 0, "保留的旧日志文件最大数量")
|
||||
flagSet.Int("log-max-age", 0, "保留旧日志文件的最大天数")
|
||||
flagSet.Bool("log-compress", false, "是否压缩旧日志文件")
|
||||
|
||||
// 绑定所有 flag 到 viper
|
||||
// 注意：必须在设置默认值之后绑定
|
||||
v.BindPFlag("server.port", flagSet.Lookup("server-port"))
|
||||
v.BindPFlag("server.read_timeout", flagSet.Lookup("server-read-timeout"))
|
||||
v.BindPFlag("server.write_timeout", flagSet.Lookup("server-write-timeout"))
|
||||
|
||||
v.BindPFlag("database.path", flagSet.Lookup("database-path"))
|
||||
v.BindPFlag("database.max_idle_conns", flagSet.Lookup("database-max-idle-conns"))
|
||||
v.BindPFlag("database.max_open_conns", flagSet.Lookup("database-max-open-conns"))
|
||||
v.BindPFlag("database.conn_max_lifetime", flagSet.Lookup("database-conn-max-lifetime"))
|
||||
|
||||
v.BindPFlag("log.level", flagSet.Lookup("log-level"))
|
||||
v.BindPFlag("log.path", flagSet.Lookup("log-path"))
|
||||
v.BindPFlag("log.max_size", flagSet.Lookup("log-max-size"))
|
||||
v.BindPFlag("log.max_backups", flagSet.Lookup("log-max-backups"))
|
||||
v.BindPFlag("log.max_age", flagSet.Lookup("log-max-age"))
|
||||
v.BindPFlag("log.compress", flagSet.Lookup("log-compress"))
|
||||
}
|
||||
|
||||
// setupEnv 绑定环境变量
|
||||
func setupEnv(v *viper.Viper) {
|
||||
v.SetEnvPrefix("NEX")
|
||||
v.AutomaticEnv()
|
||||
v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
|
||||
}
|
||||
|
||||
// setupConfigFile 读取配置文件
|
||||
func setupConfigFile(v *viper.Viper, configPath string) error {
|
||||
v.SetConfigFile(configPath)
|
||||
v.SetConfigType("yaml")
|
||||
|
||||
// 尝试读取配置文件，如果不存在则忽略
|
||||
if err := v.ReadInConfig(); err != nil {
|
||||
if !os.IsNotExist(err) {
|
||||
return appErrors.Wrap(appErrors.ErrInternal, err)
|
||||
}
|
||||
// 配置文件不存在，创建默认配置文件
|
||||
if err := v.SafeWriteConfig(); err != nil {
|
||||
// 忽略写入错误（可能目录已存在等）
|
||||
return nil
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// LoadConfig loads config from YAML file, creates default if not exists
|
||||
func LoadConfig() (*Config, error) {
|
||||
configPath, err := GetConfigPath()
|
||||
if err != nil {
|
||||
return nil, appErrors.Wrap(appErrors.ErrInternal, err)
|
||||
}
|
||||
return LoadConfigFromPath(configPath)
|
||||
}
|
||||
|
||||
cfg := DefaultConfig()
|
||||
// LoadConfigFromPath 从指定路径加载配置
|
||||
func LoadConfigFromPath(configPath string) (*Config, error) {
|
||||
// 1. 创建 Viper 实例
|
||||
v := viper.New()
|
||||
|
||||
data, err := os.ReadFile(configPath)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
// Create default config file
|
||||
if saveErr := SaveConfig(cfg); saveErr != nil {
|
||||
return nil, appErrors.WithMessage(appErrors.ErrInternal, "创建默认配置失败")
|
||||
}
|
||||
return cfg, nil
|
||||
}
|
||||
// 2. 定义 CLI 参数
|
||||
flagSet := pflag.NewFlagSet("config", pflag.ContinueOnError)
|
||||
flagSet.String("config", configPath, "配置文件路径")
|
||||
setupFlags(v, flagSet)
|
||||
|
||||
// 3. 解析 CLI 参数（忽略错误，因为可能没有参数）
|
||||
flagSet.Parse(os.Args[1:])
|
||||
|
||||
// 4. 获取配置文件路径（可能被 --config 参数覆盖）
|
||||
if configPathFlag, err := flagSet.GetString("config"); err == nil && configPathFlag != "" {
|
||||
configPath = configPathFlag
|
||||
}
|
||||
|
||||
// 5. 设置默认值
|
||||
setupDefaults(v)
|
||||
|
||||
// 6. 绑定环境变量
|
||||
setupEnv(v)
|
||||
|
||||
// 7. 读取配置文件
|
||||
if err := setupConfigFile(v, configPath); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// 8. 反序列化到结构体
|
||||
cfg := &Config{}
|
||||
if err := v.Unmarshal(cfg, viper.DecodeHook(mapstructure.ComposeDecodeHookFunc(
|
||||
mapstructure.StringToTimeDurationHookFunc(),
|
||||
mapstructure.StringToSliceHookFunc(","),
|
||||
))); err != nil {
|
||||
return nil, appErrors.Wrap(appErrors.ErrInternal, err)
|
||||
}
|
||||
|
||||
if err := yaml.Unmarshal(data, cfg); err != nil {
|
||||
return nil, appErrors.Wrap(appErrors.ErrInternal, err)
|
||||
// 9. 验证配置
|
||||
if err := cfg.Validate(); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
return cfg, nil
|
||||
@@ -154,18 +273,24 @@ func SaveConfig(cfg *Config) error {
|
||||
|
||||
// Validate validates the config
|
||||
func (c *Config) Validate() error {
|
||||
if c.Server.Port < 1 || c.Server.Port > 65535 {
|
||||
return appErrors.WithMessage(appErrors.ErrInvalidRequest, fmt.Sprintf("无效的端口号: %d", c.Server.Port))
|
||||
validate := validator.New()
|
||||
if err := validate.Struct(c); err != nil {
|
||||
return appErrors.WithMessage(appErrors.ErrInvalidRequest, fmt.Sprintf("配置验证失败: %v", err))
|
||||
}
|
||||
|
||||
validLevels := map[string]bool{"debug": true, "info": true, "warn": true, "error": true}
|
||||
if !validLevels[c.Log.Level] {
|
||||
return appErrors.WithMessage(appErrors.ErrInvalidRequest, fmt.Sprintf("无效的日志级别: %s", c.Log.Level))
|
||||
}
|
||||
|
||||
if c.Database.Path == "" {
|
||||
return appErrors.WithMessage(appErrors.ErrInvalidRequest, "数据库路径不能为空")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// PrintSummary 打印配置摘要
|
||||
func (c *Config) PrintSummary() {
|
||||
fmt.Println("\nAI Gateway 启动配置")
|
||||
fmt.Println("==================")
|
||||
fmt.Printf("服务器端口: %d\n", c.Server.Port)
|
||||
fmt.Printf("数据库路径: %s\n", c.Database.Path)
|
||||
fmt.Printf("日志级别: %s\n", c.Log.Level)
|
||||
fmt.Println("\n配置来源:")
|
||||
configPath, _ := GetConfigPath()
|
||||
fmt.Printf(" 配置文件: %s\n", configPath)
|
||||
fmt.Println(" 环境变量: 待统计")
|
||||
fmt.Println(" CLI 参数: 待统计")
|
||||
fmt.Println()
|
||||
}
|
||||
|
||||
@@ -46,13 +46,13 @@ func TestConfig_Validate(t *testing.T) {
|
||||
name: "端口号为0无效",
|
||||
modify: func(c *Config) { c.Server.Port = 0 },
|
||||
wantErr: true,
|
||||
errMsg: "无效的端口号",
|
||||
errMsg: "配置验证失败",
|
||||
},
|
||||
{
|
||||
name: "端口号超出范围无效",
|
||||
modify: func(c *Config) { c.Server.Port = 70000 },
|
||||
wantErr: true,
|
||||
errMsg: "无效的端口号",
|
||||
errMsg: "配置验证失败",
|
||||
},
|
||||
{
|
||||
name: "端口号为1有效",
|
||||
@@ -68,7 +68,7 @@ func TestConfig_Validate(t *testing.T) {
|
||||
name: "无效日志级别",
|
||||
modify: func(c *Config) { c.Log.Level = "invalid" },
|
||||
wantErr: true,
|
||||
errMsg: "无效的日志级别",
|
||||
errMsg: "配置验证失败",
|
||||
},
|
||||
{
|
||||
name: "debug级别有效",
|
||||
@@ -89,7 +89,7 @@ func TestConfig_Validate(t *testing.T) {
|
||||
name: "数据库路径为空无效",
|
||||
modify: func(c *Config) { c.Database.Path = "" },
|
||||
wantErr: true,
|
||||
errMsg: "数据库路径不能为空",
|
||||
errMsg: "配置验证失败",
|
||||
},
|
||||
}
|
||||
|
||||
@@ -174,3 +174,61 @@ func TestSaveAndLoadConfig(t *testing.T) {
|
||||
assert.Equal(t, cfg.Database.MaxIdleConns, loaded.Database.MaxIdleConns)
|
||||
assert.Equal(t, cfg.Log.Compress, loaded.Log.Compress)
|
||||
}
|
||||
|
||||
func TestCLIConfig(t *testing.T) {
|
||||
// 测试 CLI 参数配置（简化版本）
|
||||
// 注意：由于 flag.Parse 只能调用一次，这里只测试配置加载流程
|
||||
t.Run("配置加载流程", func(t *testing.T) {
|
||||
// 使用默认配置路径测试
|
||||
cfg := DefaultConfig()
|
||||
require.NotNil(t, cfg)
|
||||
|
||||
// 验证默认值正确
|
||||
assert.Equal(t, 9826, cfg.Server.Port)
|
||||
assert.Equal(t, "info", cfg.Log.Level)
|
||||
})
|
||||
}
|
||||
|
||||
func TestEnvConfig(t *testing.T) {
|
||||
// 测试环境变量配置（简化版本）
|
||||
t.Run("环境变量前缀", func(t *testing.T) {
|
||||
// 验证环境变量前缀设置正确
|
||||
// 实际的环境变量测试需要独立的进程，这里只验证配置结构
|
||||
cfg := DefaultConfig()
|
||||
require.NotNil(t, cfg)
|
||||
assert.Equal(t, 9826, cfg.Server.Port)
|
||||
})
|
||||
}
|
||||
|
||||
func TestConfigPriority(t *testing.T) {
|
||||
// 测试配置优先级（简化版本）
|
||||
t.Run("默认值设置", func(t *testing.T) {
|
||||
cfg := DefaultConfig()
|
||||
require.NotNil(t, cfg)
|
||||
|
||||
// 验证所有默认值
|
||||
assert.Equal(t, 9826, cfg.Server.Port)
|
||||
assert.Equal(t, 30*time.Second, cfg.Server.ReadTimeout)
|
||||
assert.Equal(t, 30*time.Second, cfg.Server.WriteTimeout)
|
||||
assert.Equal(t, 10, cfg.Database.MaxIdleConns)
|
||||
assert.Equal(t, 100, cfg.Database.MaxOpenConns)
|
||||
assert.Equal(t, 1*time.Hour, cfg.Database.ConnMaxLifetime)
|
||||
assert.Equal(t, "info", cfg.Log.Level)
|
||||
assert.Equal(t, 100, cfg.Log.MaxSize)
|
||||
assert.Equal(t, 10, cfg.Log.MaxBackups)
|
||||
assert.Equal(t, 30, cfg.Log.MaxAge)
|
||||
assert.Equal(t, true, cfg.Log.Compress)
|
||||
})
|
||||
}
|
||||
|
||||
func TestPrintSummary(t *testing.T) {
|
||||
// 测试配置摘要输出
|
||||
t.Run("打印配置摘要", func(t *testing.T) {
|
||||
cfg := DefaultConfig()
|
||||
// PrintSummary 只是打印，不会返回错误
|
||||
// 这里主要验证不会 panic
|
||||
assert.NotPanics(t, func() {
|
||||
cfg.PrintSummary()
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
106
docs/prompts/规范整理.md
Normal file
106
docs/prompts/规范整理.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# 规范文件整理流程
|
||||
|
||||
## 使用方式
|
||||
|
||||
将下方提示词完整复制给 AI 工具，即可启动一次规范文件的全面审查和整理。
|
||||
|
||||
---
|
||||
|
||||
## 提示词
|
||||
|
||||
```
|
||||
请对 openspec/specs/ 下的所有规范文件进行审查和整理，按以下流程执行：
|
||||
|
||||
## 第一步：全面阅读
|
||||
|
||||
1. 逐个读取 openspec/specs/ 下每个子目录的 spec.md，理解每个规范的覆盖范围
|
||||
2. 读取项目源码，理解实际代码实现
|
||||
3. 读取 openspec/config.yaml，了解项目约束和规范
|
||||
|
||||
## 第二步：对比分析
|
||||
|
||||
将每个规范与实际代码对比，按以下维度逐项检查：
|
||||
|
||||
### A. 过时检查
|
||||
- 规范描述的功能/组件/样式是否在当前代码中仍然存在
|
||||
- 规范引用的文件路径、类名、API 接口是否与代码一致
|
||||
- 规范描述的交互流程是否仍是当前的实现方式
|
||||
|
||||
### B. 重复检查
|
||||
- 不同规范是否描述了相同的组件/功能/场景
|
||||
- 场景级别的重复（A 规范的 Scenario 与 B 规范的 Scenario 重复）
|
||||
- 概念级别的重复（A 规范整体描述的就是 B 规范已覆盖的内容）
|
||||
|
||||
### C. 错位检查
|
||||
- A 规范中是否有场景应该属于 B 规范
|
||||
- 某个 Requirement 是否放在了错误的功能域下
|
||||
|
||||
### D. 合并检查
|
||||
- 描述同一类主题的规范是否分散在多个文件中
|
||||
- 某个规范是否可以作为子集被另一个更大的规范吸收
|
||||
|
||||
### E. 命名检查
|
||||
- 规范名称是否准确反映其实际内容
|
||||
- 命名是否遵循统一的前缀约定（平台前缀：admin- / developer- / console-）
|
||||
- 名称是否便于 AI 工具搜索匹配（暴露关键业务词和组件名）
|
||||
|
||||
### F. 格式检查
|
||||
- 是否使用标准的 SHALL/WHEN/THEN 规范格式
|
||||
- 是否混入了变更记录（如"移除以下列"、"ADDED Requirements"）而非功能规范
|
||||
- 是否存在空目录
|
||||
|
||||
## 第三步：输出分析报告
|
||||
|
||||
按以下结构输出：
|
||||
|
||||
1. 问题总览表（问题类型 × 涉及规范数）
|
||||
2. 逐项分析（每个有问题的规范，说明具体问题和建议）
|
||||
3. 重构方案（删除/合并/重命名/内容调整的具体操作）
|
||||
4. 重构后的规范目录结构
|
||||
|
||||
## 第四步：执行重构
|
||||
|
||||
按优先级分批执行：
|
||||
- P0：删除空目录和完全冗余的规范
|
||||
- P1：合并重复/子集规范到主规范中
|
||||
- P2：重命名不精准的规范、拆分错位的内容
|
||||
- P3：修正与代码不匹配的细节描述
|
||||
|
||||
每步执行后确认目录结构完整。
|
||||
|
||||
## 命名约定
|
||||
|
||||
规范目录命名遵循以下规则，确保 AI 工具搜索时能精准匹配：
|
||||
|
||||
| 类型 | 命名模式 | 示例 |
|
||||
|------|---------|------|
|
||||
| 平台专属功能 | `{平台}-{功能}` | `admin-platform`、`console-my-skills`、`developer-platform` |
|
||||
| 跨平台组件/架构 | `{类别}` | `component-library`、`layout-system`、`design-tokens` |
|
||||
| 技能领域 | `skill-{方面}` | `skill-market`、`skill-status-rules`、`skill-version-management` |
|
||||
| 业务功能 | `{业务名词}` | `account-management`、`chat-scenarios` |
|
||||
|
||||
命名原则（提升 AI 检索命中率）：
|
||||
- 名称中暴露可搜索的业务关键词（如 skill、modal、toast、account）
|
||||
- 同一平台的功能使用统一前缀（admin- / console- / developer-）
|
||||
- 同一领域的功能使用统一领域词前缀（skill-）
|
||||
- 避免泛化词（display → rules/behavior，basic → 删掉，general → 删掉）
|
||||
- 避免实现模式词（crud、list、table）而使用业务领域词
|
||||
- 避免同一关键词在不同规范中重复出现导致歧义（如 layout 只出现在一个规范名中）
|
||||
- 长度控制在 2-3 个词，去掉不影响检索的冗余词（info、data 等）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 补充说明
|
||||
|
||||
### 审查时的判断边界
|
||||
|
||||
- **规范 vs 代码**：规范描述"应该是什么"，不描述"代码怎么写"。如果规范中出现了具体文件路径（如 `src/data/adminData.js`），通常是实现细节而非规范，应该清理
|
||||
- **规范 vs 变更记录**：规范用 SHALL/WHEN/THEN 格式描述功能需求。如果出现"移除以下列"、"保持现有样式"、"ADDED/MODIFIED Requirements"等措辞，说明混入了变更指令，需要改写
|
||||
- **规范 vs 文档**：规范不替代 README 或开发文档，不需要描述项目背景、技术选型等宏观信息
|
||||
|
||||
### 建议的定期审查节奏
|
||||
|
||||
- 每完成一批功能变更后，对照新代码检查相关规范是否需要更新
|
||||
- 规范数量超过 30 个时，建议做一次全面审查
|
||||
- 新增规范前，先搜索现有规范名称和内容，确认是否有可复用/扩展的规范
|
||||
@@ -1,233 +0,0 @@
|
||||
## Context
|
||||
|
||||
当前配置管理使用自定义的 YAML 加载逻辑，仅支持单一配置文件源。配置加载流程为：
|
||||
|
||||
```
|
||||
main.go → LoadConfig() → 读取 ~/.nex/config.yaml → yaml.Unmarshal → Validate()
|
||||
```
|
||||
|
||||
存在的问题：
|
||||
- 配置源单一，无法满足测试、容器化、临时调试等场景
|
||||
- 无配置优先级管理，无法实现配置覆盖
|
||||
- 命名不规范，不同配置源的命名规则不统一
|
||||
|
||||
本设计采用 **Viper** 作为配置管理框架，这是 Go 社区最流行的配置管理库，支持多种配置源和优先级管理。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 实现多层配置源支持：CLI 参数、环境变量、配置文件、默认值
|
||||
- 实现配置优先级：CLI > ENV > File > Default
|
||||
- 规范化命名：保持配置文件、环境变量、CLI 参数命名一致性
|
||||
- 保持向后兼容：现有配置文件格式不变，API 签名基本不变
|
||||
- 提升开发体验：测试时无需创建临时配置文件，调试时可快速修改配置
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不实现配置热重载（hot reload）：当前版本仅支持启动时加载配置
|
||||
- 不实现远程配置源（etcd、Consul）：当前版本仅支持本地配置
|
||||
- 不实现配置加密：敏感信息通过环境变量传递，不在配置文件中存储
|
||||
- 不改变配置文件格式：继续使用 YAML，不引入 TOML、JSON 等格式
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 配置管理框架选择：Viper
|
||||
|
||||
**决策**：使用 `github.com/spf13/viper` 作为配置管理框架
|
||||
|
||||
**理由**：
|
||||
- **社区标准**：Go 社区最流行的配置管理库，GitHub 26k+ stars
|
||||
- **功能完整**：支持多种配置源（文件、环境变量、CLI 参数）、多种格式（YAML、JSON、TOML）、优先级管理
|
||||
- **生态成熟**：与 Cobra、pflag 等无缝集成，文档完善
|
||||
- **生产验证**：被众多知名项目使用（Hugo、Docker Notary 等）
|
||||
|
||||
**替代方案**：
|
||||
- **koanf**：更轻量，但生态不如 Viper 成熟
|
||||
- **自研方案**：灵活度最高，但需要重复造轮子，维护成本高
|
||||
|
||||
### 2. CLI 参数解析：pflag
|
||||
|
||||
**决策**：使用 `github.com/spf13/pflag` 解析命令行参数
|
||||
|
||||
**理由**：
|
||||
- **POSIX 兼容**：支持 GNU 风格的参数（`--flag value` 和 `--flag=value`）
|
||||
- **Viper 集成**：通过 `BindPFlag` 直接绑定到 Viper
|
||||
- **类型安全**：支持 Int、String、Duration 等类型，自动类型转换
|
||||
|
||||
**替代方案**：
|
||||
- **标准 flag 包**：功能有限，不支持 GNU 风格
|
||||
- **Cobra**：功能过于强大，当前项目不需要子命令
|
||||
|
||||
### 3. 配置验证：go-playground/validator
|
||||
|
||||
**决策**：使用 `github.com/go-playground/validator` 进行结构体验证
|
||||
|
||||
**理由**：
|
||||
- **声明式验证**：通过 struct tag 定义验证规则，代码简洁
|
||||
- **功能丰富**：支持 required、min、max、oneof 等丰富的验证规则
|
||||
- **错误友好**：提供详细的验证错误信息
|
||||
|
||||
**替代方案**：
|
||||
- **手动验证**：当前方案，代码冗长，不易维护
|
||||
- **go-validator**：功能不如 validator 丰富
|
||||
|
||||
### 4. 配置优先级设计
|
||||
|
||||
**决策**：采用 Viper 默认优先级：CLI > ENV > File > Default
|
||||
|
||||
**理由**：
|
||||
- **业界标准**：符合 12-Factor App 原则，环境变量优先级高于配置文件
|
||||
- **灵活性**：CLI 参数可临时覆盖任何配置，适合调试和测试
|
||||
- **可预测性**：优先级固定，行为明确，不易出错
|
||||
|
||||
### 5. 命名规范化策略
|
||||
|
||||
**决策**：完整层次结构命名，保持 CLI、ENV、配置文件命名一致
|
||||
|
||||
**转换规则**：
|
||||
```
|
||||
配置文件：server.port
|
||||
环境变量：NEX_SERVER_PORT (前缀 + 大写 + 下划线)
|
||||
CLI 参数：--server-port (连字符 + kebab-case)
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- **一致性**：三种配置源命名规则统一，易于理解和记忆
|
||||
- **可预测性**：知道配置文件路径，就能推导出 CLI 参数和环境变量
|
||||
- **无歧义**：完整层次结构，不会产生命名冲突
|
||||
|
||||
**替代方案**：
|
||||
- **简写前缀**：如 `--port`、`--db-path`，简洁但易产生歧义
|
||||
- **智能前缀**：常用参数不加前缀，易混淆
|
||||
|
||||
### 6. 配置加载流程设计
|
||||
|
||||
**决策**：采用以下流程加载配置
|
||||
|
||||
```
|
||||
1. 解析 CLI 参数（获取 --config 路径）
|
||||
2. 初始化 Viper
|
||||
3. 设置默认值（SetDefault）
|
||||
4. 绑定 CLI 参数（BindPFlag）
|
||||
5. 绑定环境变量（AutomaticEnv + SetEnvPrefix）
|
||||
6. 读取配置文件（ReadInConfig）
|
||||
7. 反序列化到结构体（Unmarshal）
|
||||
8. 验证配置（Validate）
|
||||
9. 打印配置摘要（PrintSummary）
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- **顺序重要**：必须先解析 CLI 参数，才能获取 `--config` 路径
|
||||
- **优先级保证**：Viper 按绑定顺序处理优先级，CLI 参数绑定在前
|
||||
- **错误友好**：每一步都有明确的错误处理
|
||||
|
||||
### 7. 配置摘要输出设计
|
||||
|
||||
**决策**：启动时打印配置摘要，显示关键配置和配置来源
|
||||
|
||||
**示例**：
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ AI Gateway 启动配置 │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 服务器端口: 9826 │
|
||||
│ 数据库路径: ~/.nex/config.db │
|
||||
│ 日志级别: info │
|
||||
│ │
|
||||
│ 配置来源: │
|
||||
│ 配置文件: ~/.nex/config.yaml │
|
||||
│ 环境变量: 2 个 │
|
||||
│ CLI 参数: 1 个 │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- **可观测性**：快速确认实际生效的配置
|
||||
- **调试友好**：配置问题时可快速定位
|
||||
- **来源追踪**：知道配置来自哪个源，便于排查
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1：依赖增加
|
||||
|
||||
**风险**：引入 3 个新依赖，增加项目复杂度和依赖管理成本
|
||||
|
||||
**缓解**：
|
||||
- Viper、pflag、validator 都是成熟稳定的库，维护活跃
|
||||
- 这些库被广泛使用，供应链风险低
|
||||
- 依赖树增加约 10 个间接依赖，但都在可控范围内
|
||||
|
||||
### 风险 2：向后兼容性
|
||||
|
||||
**风险**：`LoadConfig()` 内部实现完全重构，可能影响现有代码
|
||||
|
||||
**缓解**：
|
||||
- 保持 `LoadConfig()` 签名不变：`func LoadConfig() (*Config, error)`
|
||||
- 保持配置文件格式不变：继续使用 YAML，字段名不变
|
||||
- 保持默认值不变：所有默认值与当前实现一致
|
||||
- 充分的测试覆盖：确保行为一致性
|
||||
|
||||
### 风险 3：性能影响
|
||||
|
||||
**风险**：Viper 配置加载比直接读取 YAML 文件稍慢
|
||||
|
||||
**缓解**：
|
||||
- 配置加载仅在启动时执行一次，性能影响可忽略
|
||||
- Viper 内部有缓存机制，不会重复解析
|
||||
- 实测：配置加载耗时 < 10ms，不影响启动性能
|
||||
|
||||
### 风险 4：学习曲线
|
||||
|
||||
**风险**：团队需要学习 Viper 的使用方式
|
||||
|
||||
**缓解**：
|
||||
- Viper API 简单直观，学习成本低
|
||||
- 提供详细的使用示例和文档
|
||||
- 封装配置加载逻辑，对外暴露简单的 API
|
||||
|
||||
### 权衡 1：CLI 参数数量
|
||||
|
||||
**权衡**：所有 13 个配置项都支持 CLI 参数，参数较多
|
||||
|
||||
**选择理由**：
|
||||
- 灵活性优先：测试和调试时需要覆盖所有配置
|
||||
- 分组展示：帮助文档按功能分组，易于理解
|
||||
- 可选使用：大多数场景只需少量参数，不需要全部指定
|
||||
|
||||
### 权衡 2：环境变量前缀
|
||||
|
||||
**权衡**：环境变量使用 `NEX_` 前缀，名称较长
|
||||
|
||||
**选择理由**：
|
||||
- 避免冲突：与其他系统的环境变量区分
|
||||
- 明确归属：一眼看出是本应用的配置
|
||||
- 业界惯例：大多数应用都使用前缀（如 `AWS_`、`GITHUB_`）
|
||||
|
||||
## Migration Plan
|
||||
|
||||
本变更不涉及数据迁移，仅需代码部署：
|
||||
|
||||
### 部署步骤
|
||||
|
||||
1. **代码合并**：将变更合并到主分支
|
||||
2. **重新编译**：编译新版本二进制文件
|
||||
3. **部署验证**：在测试环境验证配置加载正常
|
||||
4. **生产部署**：部署新版本
|
||||
|
||||
### 回滚策略
|
||||
|
||||
如需回滚：
|
||||
1. 回退到旧版本代码
|
||||
2. 重新编译部署
|
||||
3. 配置文件无需修改，格式兼容
|
||||
|
||||
### 兼容性保证
|
||||
|
||||
- 现有配置文件 `~/.nex/config.yaml` 无需修改
|
||||
- 现有启动方式 `./server` 继续有效
|
||||
- 新功能（CLI 参数、环境变量）为可选功能
|
||||
|
||||
## Open Questions
|
||||
|
||||
无待解决问题。设计方案已明确，可直接进入实现阶段。
|
||||
@@ -1,66 +0,0 @@
|
||||
## Why
|
||||
|
||||
当前配置方案仅支持 YAML 配置文件，存在以下问题：
|
||||
- **测试不便**：每次测试都需要创建临时配置文件
|
||||
- **临时调试困难**：无法快速修改单个配置参数进行调试
|
||||
- **容器化不友好**：不支持环境变量配置，不符合 12-Factor App 原则
|
||||
- **配置切换繁琐**：无法通过命令行参数临时覆盖配置
|
||||
|
||||
需要实现多层配置管理，支持 CLI 参数、环境变量、配置文件和默认值四种配置方式，并采用社区标准方案（Viper）实现。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **引入 Viper 配置管理框架**：使用社区标准的配置管理库，支持多种配置源
|
||||
- **实现配置优先级**：CLI 参数 > 环境变量 > 配置文件 > 默认值
|
||||
- **支持命令行参数**：所有 13 个配置项都支持 CLI 参数覆盖
|
||||
- **支持环境变量**：所有配置项都支持环境变量配置（NEX_ 前缀）
|
||||
- **规范化命名**：CLI 参数、环境变量、配置文件命名完全一致，保持层次结构
|
||||
- 配置文件：`server.port`
|
||||
- 环境变量：`NEX_SERVER_PORT`
|
||||
- CLI 参数：`--server-port`
|
||||
- **使用结构体验证**：采用 `go-playground/validator` 进行配置验证
|
||||
- **配置摘要输出**：启动时打印配置摘要，显示配置来源
|
||||
- **BREAKING**：重构配置加载逻辑，现有 `LoadConfig()` API 发生变化
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `cli-config`: 命令行参数配置支持，所有配置项都可通过 CLI 参数设置
|
||||
- `env-config`: 环境变量配置支持，符合 12-Factor App 原则
|
||||
- `config-priority`: 配置优先级管理，支持 CLI > ENV > File > Default 的优先级
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `config-management`: 扩展现有配置管理能力，从单一配置文件支持扩展为多层配置源支持
|
||||
|
||||
## Impact
|
||||
|
||||
### 代码影响
|
||||
|
||||
- `backend/internal/config/config.go`：重构配置加载逻辑，引入 Viper
|
||||
- `backend/cmd/server/main.go`：修改配置加载流程，添加 CLI 参数解析
|
||||
- `backend/internal/config/config_test.go`：更新测试以适应新的配置加载方式
|
||||
|
||||
### 依赖变更
|
||||
|
||||
新增依赖：
|
||||
- `github.com/spf13/viper v1.18.2`：配置管理
|
||||
- `github.com/spf13/pflag v1.0.5`：命令行参数解析
|
||||
- `github.com/go-playground/validator/v10 v10.22.0`：结构体验证
|
||||
|
||||
移除依赖：
|
||||
- `gopkg.in/yaml.v3`：Viper 内置 YAML 支持
|
||||
|
||||
### API 变更
|
||||
|
||||
- `config.LoadConfig()` 签名保持不变，但内部实现完全重构
|
||||
- 新增 `config.LoadConfigFromPath(path string)` 支持自定义配置文件路径
|
||||
- 新增 `config.PrintSummary()` 打印配置摘要
|
||||
|
||||
### 使用场景影响
|
||||
|
||||
- **生产环境**：继续使用配置文件，无影响
|
||||
- **测试环境**：可通过 CLI 参数或环境变量配置，无需创建临时配置文件
|
||||
- **容器化部署**：可通过环境变量配置，符合 12-Factor App
|
||||
- **本地开发**：可通过 CLI 参数临时修改配置，无需修改配置文件
|
||||
@@ -1,102 +0,0 @@
|
||||
# CLI Config
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 命令行参数配置支持
|
||||
|
||||
系统 SHALL 支持通过命令行参数设置所有配置项。
|
||||
|
||||
#### Scenario: 基本参数解析
|
||||
|
||||
- **WHEN** 应用启动时传入命令行参数
|
||||
- **THEN** SHALL 解析所有 CLI 参数
|
||||
- **THEN** SHALL 将参数值应用到对应配置项
|
||||
|
||||
#### Scenario: 参数命名规范
|
||||
|
||||
- **WHEN** 使用命令行参数
|
||||
- **THEN** SHALL 使用 kebab-case 命名（如 `--server-port`）
|
||||
- **THEN** SHALL 保持完整的层次结构（如 `--database-max-idle-conns`）
|
||||
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `--database-max-idle-conns`）
|
||||
|
||||
#### Scenario: 参数类型支持
|
||||
|
||||
- **WHEN** 解析不同类型的参数
|
||||
- **THEN** SHALL 支持 int 类型（如 `--server-port 9000`）
|
||||
- **THEN** SHALL 支持 string 类型（如 `--database-path /data/nex.db`）
|
||||
- **THEN** SHALL 支持 duration 类型（如 `--server-read-timeout 60s`）
|
||||
- **THEN** SHALL 支持 bool 类型（如 `--log-compress`）
|
||||
|
||||
### Requirement: 配置文件路径参数
|
||||
|
||||
系统 SHALL 支持通过 CLI 参数指定配置文件路径。
|
||||
|
||||
#### Scenario: 自定义配置文件路径
|
||||
|
||||
- **WHEN** 启动时指定 `--config /path/to/custom.yaml`
|
||||
- **THEN** SHALL 从指定路径加载配置文件
|
||||
- **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`
|
||||
|
||||
#### Scenario: 未指定配置文件路径
|
||||
|
||||
- **WHEN** 启动时未指定 `--config` 参数
|
||||
- **THEN** SHALL 使用默认路径 `~/.nex/config.yaml`
|
||||
|
||||
### Requirement: 完整配置覆盖
|
||||
|
||||
系统 SHALL 支持通过 CLI 参数覆盖所有配置项。
|
||||
|
||||
#### Scenario: 服务器配置参数
|
||||
|
||||
- **WHEN** 使用服务器相关参数
|
||||
- **THEN** SHALL 支持 `--server-port`
|
||||
- **THEN** SHALL 支持 `--server-read-timeout`
|
||||
- **THEN** SHALL 支持 `--server-write-timeout`
|
||||
|
||||
#### Scenario: 数据库配置参数
|
||||
|
||||
- **WHEN** 使用数据库相关参数
|
||||
- **THEN** SHALL 支持 `--database-path`
|
||||
- **THEN** SHALL 支持 `--database-max-idle-conns`
|
||||
- **THEN** SHALL 支持 `--database-max-open-conns`
|
||||
- **THEN** SHALL 支持 `--database-conn-max-lifetime`
|
||||
|
||||
#### Scenario: 日志配置参数
|
||||
|
||||
- **WHEN** 使用日志相关参数
|
||||
- **THEN** SHALL 支持 `--log-level`
|
||||
- **THEN** SHALL 支持 `--log-path`
|
||||
- **THEN** SHALL 支持 `--log-max-size`
|
||||
- **THEN** SHALL 支持 `--log-max-backups`
|
||||
- **THEN** SHALL 支持 `--log-max-age`
|
||||
- **THEN** SHALL 支持 `--log-compress`
|
||||
|
||||
### Requirement: 参数帮助信息
|
||||
|
||||
系统 SHALL 提供完整的参数帮助信息。
|
||||
|
||||
#### Scenario: 帮助文档生成
|
||||
|
||||
- **WHEN** 使用 `--help` 参数
|
||||
- **THEN** SHALL 显示所有支持的参数
|
||||
- **THEN** SHALL 按功能分组展示参数（服务器、数据库、日志）
|
||||
- **THEN** SHALL 显示每个参数的默认值
|
||||
- **THEN** SHALL 显示每个参数的说明
|
||||
|
||||
### Requirement: 参数错误处理
|
||||
|
||||
系统 SHALL 正确处理参数错误。
|
||||
|
||||
#### Scenario: 无效参数值
|
||||
|
||||
- **WHEN** 传入无效的参数值（如 `--server-port abc`）
|
||||
- **THEN** SHALL 返回明确的错误信息
|
||||
- **THEN** SHALL 指示参数名称和期望类型
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
|
||||
#### Scenario: 未知参数
|
||||
|
||||
- **WHEN** 传入未定义的参数（如 `--unknown-param value`）
|
||||
- **THEN** SHALL 返回错误信息
|
||||
- **THEN** SHALL 指示未知参数名称
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
@@ -1,151 +0,0 @@
|
||||
# Config Management
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 使用 YAML 配置文件
|
||||
|
||||
系统 SHALL 使用 YAML 格式的配置文件。
|
||||
|
||||
#### Scenario: 配置文件路径
|
||||
|
||||
- **WHEN** 应用启动且未指定 `--config` 参数
|
||||
- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
|
||||
- **THEN** SHALL 解析 YAML 格式
|
||||
|
||||
#### Scenario: 自定义配置文件路径
|
||||
|
||||
- **WHEN** 应用启动且指定 `--config /path/to/custom.yaml`
|
||||
- **THEN** SHALL 从指定路径加载配置文件
|
||||
- **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`
|
||||
|
||||
#### Scenario: 配置文件结构
|
||||
|
||||
- **WHEN** 加载配置文件
|
||||
- **THEN** SHALL 包含 server、database、log 等配置节
|
||||
- **THEN** SHALL 支持嵌套配置结构
|
||||
|
||||
### Requirement: 自动生成默认配置
|
||||
|
||||
系统 SHALL 在首次使用时自动生成默认配置。
|
||||
|
||||
#### Scenario: 配置文件不存在
|
||||
|
||||
- **WHEN** 应用启动且配置文件不存在
|
||||
- **THEN** SHALL 自动创建配置文件
|
||||
- **THEN** SHALL 写入默认配置值
|
||||
- **THEN** SHALL 记录日志提示已创建
|
||||
|
||||
#### Scenario: 配置文件已存在
|
||||
|
||||
- **WHEN** 应用启动且配置文件已存在
|
||||
- **THEN** SHALL 直接加载配置文件
|
||||
- **THEN** SHALL NOT 覆盖现有配置
|
||||
|
||||
### Requirement: 配置验证
|
||||
|
||||
系统 SHALL 验证配置的有效性。
|
||||
|
||||
#### Scenario: 必需字段验证
|
||||
|
||||
- **WHEN** 加载配置
|
||||
- **THEN** SHALL 验证必需字段存在
|
||||
- **THEN** SHALL 在字段缺失时返回错误
|
||||
|
||||
#### Scenario: 字段值验证
|
||||
|
||||
- **WHEN** 加载配置
|
||||
- **THEN** SHALL 验证端口号范围（1-65535）
|
||||
- **THEN** SHALL 验证日志级别有效性（debug/info/warn/error）
|
||||
- **THEN** SHALL 验证路径有效性
|
||||
- **THEN** SHALL 验证数值范围（如 max_idle_conns ≥ 1）
|
||||
|
||||
#### Scenario: 配置错误处理
|
||||
|
||||
- **WHEN** 配置验证失败
|
||||
- **THEN** SHALL 返回详细的错误信息
|
||||
- **THEN** SHALL 指示哪些字段无效
|
||||
- **THEN** SHALL 应用 SHALL NOT 启动
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 多层配置源支持
|
||||
|
||||
系统 SHALL 支持多种配置源。
|
||||
|
||||
#### Scenario: 配置源类型
|
||||
|
||||
- **WHEN** 加载配置
|
||||
- **THEN** SHALL 支持命令行参数配置源
|
||||
- **THEN** SHALL 支持环境变量配置源
|
||||
- **THEN** SHALL 支持配置文件配置源
|
||||
- **THEN** SHALL 支持默认值配置源
|
||||
|
||||
#### Scenario: 配置源合并
|
||||
|
||||
- **WHEN** 多个配置源同时存在
|
||||
- **THEN** SHALL 合并所有配置源
|
||||
- **THEN** SHALL 按优先级处理冲突
|
||||
- **THEN** SHALL 生成最终配置
|
||||
|
||||
### Requirement: 配置加载流程
|
||||
|
||||
系统 SHALL 实现标准化的配置加载流程。
|
||||
|
||||
#### Scenario: 加载步骤
|
||||
|
||||
- **WHEN** 应用启动
|
||||
- **THEN** SHALL 按以下顺序加载配置：
|
||||
1. 解析 CLI 参数（获取 --config 路径）
|
||||
2. 初始化配置管理器
|
||||
3. 设置默认值
|
||||
4. 绑定 CLI 参数
|
||||
5. 绑定环境变量
|
||||
6. 读取配置文件
|
||||
7. 反序列化到结构体
|
||||
8. 验证配置
|
||||
9. 打印配置摘要
|
||||
|
||||
#### Scenario: 加载失败处理
|
||||
|
||||
- **WHEN** 配置加载过程中发生错误
|
||||
- **THEN** SHALL 返回明确的错误信息
|
||||
- **THEN** SHALL 指示失败步骤
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
|
||||
### Requirement: 配置摘要输出
|
||||
|
||||
系统 SHALL 在启动时输出配置摘要。
|
||||
|
||||
#### Scenario: 摘要内容
|
||||
|
||||
- **WHEN** 配置加载完成
|
||||
- **THEN** SHALL 打印关键配置项（端口、数据库路径、日志级别等）
|
||||
- **THEN** SHALL 打印配置文件路径
|
||||
- **THEN** SHALL 打印环境变量数量
|
||||
- **THEN** SHALL 打印 CLI 参数数量
|
||||
|
||||
#### Scenario: 摘要格式
|
||||
|
||||
- **WHEN** 打印配置摘要
|
||||
- **THEN** SHALL 使用清晰的格式化输出
|
||||
- **THEN** SHALL 使用分隔线和分组
|
||||
- **THEN** SHALL 易于阅读和理解
|
||||
|
||||
### Requirement: 配置结构体验证
|
||||
|
||||
系统 SHALL 使用结构体 tag 进行配置验证。
|
||||
|
||||
#### Scenario: 验证规则定义
|
||||
|
||||
- **WHEN** 定义配置结构体
|
||||
- **THEN** SHALL 使用 `validate` tag 定义验证规则
|
||||
- **THEN** SHALL 支持 `required` 规则
|
||||
- **THEN** SHALL 支持 `min`、`max` 规则
|
||||
- **THEN** SHALL 支持 `oneof` 规则
|
||||
|
||||
#### Scenario: 验证执行
|
||||
|
||||
- **WHEN** 加载配置后
|
||||
- **THEN** SHALL 自动执行结构体验证
|
||||
- **THEN** SHALL 返回验证错误
|
||||
- **THEN** SHALL NOT 启动应用（如果验证失败）
|
||||
@@ -1,113 +0,0 @@
|
||||
# Config Priority
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 配置优先级管理
|
||||
|
||||
系统 SHALL 实现明确的配置优先级机制。
|
||||
|
||||
#### Scenario: 优先级顺序
|
||||
|
||||
- **WHEN** 同一配置项在多个配置源中设置
|
||||
- **THEN** SHALL 按以下优先级顺序（从高到低）：
|
||||
1. CLI 参数
|
||||
2. 环境变量
|
||||
3. 配置文件
|
||||
4. 默认值
|
||||
|
||||
#### Scenario: CLI 参数最高优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **AND** CLI 参数设置 `--server-port 8080`
|
||||
- **THEN** SHALL 使用 CLI 参数值 8080
|
||||
|
||||
#### Scenario: 环境变量次高优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用环境变量值 9000
|
||||
|
||||
#### Scenario: 配置文件次低优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 未设置环境变量
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用配置文件值 9826
|
||||
|
||||
#### Scenario: 默认值最低优先级
|
||||
|
||||
- **WHEN** 配置文件中未设置某配置项
|
||||
- **AND** 未设置环境变量
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用默认值
|
||||
|
||||
### Requirement: 配置来源追踪
|
||||
|
||||
系统 SHALL 追踪每个配置值的来源。
|
||||
|
||||
#### Scenario: 来源记录
|
||||
|
||||
- **WHEN** 加载配置完成
|
||||
- **THEN** SHALL 记录每个配置项的来源（CLI/ENV/File/Default）
|
||||
- **THEN** SHALL 在配置摘要中显示来源信息
|
||||
|
||||
#### Scenario: 来源统计
|
||||
|
||||
- **WHEN** 打印配置摘要
|
||||
- **THEN** SHALL 统计来自 CLI 参数的配置项数量
|
||||
- **THEN** SHALL 统计来自环境变量的配置项数量
|
||||
- **THEN** SHALL 统计来自配置文件的配置项数量
|
||||
- **THEN** SHALL 统计使用默认值的配置项数量
|
||||
|
||||
### Requirement: 配置覆盖透明性
|
||||
|
||||
系统 SHALL 提供配置覆盖的透明信息。
|
||||
|
||||
#### Scenario: 覆盖提示
|
||||
|
||||
- **WHEN** CLI 参数覆盖配置文件值
|
||||
- **THEN** SHALL 在日志中记录覆盖信息
|
||||
- **THEN** SHALL 显示被覆盖的配置项名称
|
||||
|
||||
#### Scenario: 配置摘要展示
|
||||
|
||||
- **WHEN** 应用启动完成
|
||||
- **THEN** SHALL 打印配置摘要
|
||||
- **THEN** SHALL 显示关键配置项的最终值
|
||||
- **THEN** SHALL 显示配置文件路径
|
||||
- **THEN** SHALL 显示环境变量数量
|
||||
- **THEN** SHALL 显示 CLI 参数数量
|
||||
|
||||
### Requirement: 部分配置覆盖
|
||||
|
||||
系统 SHALL 支持部分配置覆盖。
|
||||
|
||||
#### Scenario: 混合配置源
|
||||
|
||||
- **WHEN** 配置文件设置完整配置
|
||||
- **AND** CLI 参数仅覆盖部分配置项
|
||||
- **THEN** SHALL 合并所有配置源
|
||||
- **THEN** SHALL 使用 CLI 参数覆盖指定项
|
||||
- **THEN** SHALL 保留配置文件中的其他配置项
|
||||
|
||||
#### Scenario: 配置项独立覆盖
|
||||
|
||||
- **WHEN** 仅通过 CLI 参数设置 `--server-port 9000`
|
||||
- **THEN** SHALL 仅覆盖 server.port 配置项
|
||||
- **THEN** SHALL NOT 影响其他配置项
|
||||
- **THEN** SHALL 其他配置项使用配置文件或默认值
|
||||
|
||||
### Requirement: 配置优先级不可变性
|
||||
|
||||
系统 SHALL 确保配置优先级在运行时不可变。
|
||||
|
||||
#### Scenario: 启动后配置锁定
|
||||
|
||||
- **WHEN** 应用启动完成
|
||||
- **THEN** SHALL 锁定配置值
|
||||
- **THEN** SHALL NOT 支持运行时修改配置优先级
|
||||
- **THEN** SHALL NOT 支持运行时添加新配置源
|
||||
|
||||
注：配置热重载为未来扩展功能，当前版本不支持。
|
||||
@@ -1,107 +0,0 @@
|
||||
# Env Config
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 环境变量配置支持
|
||||
|
||||
系统 SHALL 支持通过环境变量设置所有配置项。
|
||||
|
||||
#### Scenario: 环境变量读取
|
||||
|
||||
- **WHEN** 应用启动时存在环境变量
|
||||
- **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
|
||||
- **THEN** SHALL 将环境变量值应用到对应配置项
|
||||
|
||||
#### Scenario: 环境变量命名规范
|
||||
|
||||
- **WHEN** 使用环境变量配置
|
||||
- **THEN** SHALL 使用 `NEX_` 前缀
|
||||
- **THEN** SHALL 使用大写字母和下划线分隔（如 `NEX_SERVER_PORT`）
|
||||
- **THEN** SHALL 保持完整层次结构（如 `NEX_DATABASE_MAX_IDLE_CONNS`）
|
||||
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `NEX_DATABASE_MAX_IDLE_CONNS`）
|
||||
|
||||
#### Scenario: 环境变量类型转换
|
||||
|
||||
- **WHEN** 解析不同类型的环境变量
|
||||
- **THEN** SHALL 支持 int 类型（如 `NEX_SERVER_PORT=9000`）
|
||||
- **THEN** SHALL 支持 string 类型（如 `NEX_DATABASE_PATH=/data/nex.db`）
|
||||
- **THEN** SHALL 支持 duration 类型（如 `NEX_SERVER_READ_TIMEOUT=60s`）
|
||||
- **THEN** SHALL 支持 bool 类型（如 `NEX_LOG_COMPRESS=true`）
|
||||
|
||||
### Requirement: 完整配置覆盖
|
||||
|
||||
系统 SHALL 支持通过环境变量覆盖所有配置项。
|
||||
|
||||
#### Scenario: 服务器配置环境变量
|
||||
|
||||
- **WHEN** 设置服务器相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_SERVER_PORT`
|
||||
- **THEN** SHALL 支持 `NEX_SERVER_READ_TIMEOUT`
|
||||
- **THEN** SHALL 支持 `NEX_SERVER_WRITE_TIMEOUT`
|
||||
|
||||
#### Scenario: 数据库配置环境变量
|
||||
|
||||
- **WHEN** 设置数据库相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_DATABASE_PATH`
|
||||
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_IDLE_CONNS`
|
||||
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_OPEN_CONNS`
|
||||
- **THEN** SHALL 支持 `NEX_DATABASE_CONN_MAX_LIFETIME`
|
||||
|
||||
#### Scenario: 日志配置环境变量
|
||||
|
||||
- **WHEN** 设置日志相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_LOG_LEVEL`
|
||||
- **THEN** SHALL 支持 `NEX_LOG_PATH`
|
||||
- **THEN** SHALL 支持 `NEX_LOG_MAX_SIZE`
|
||||
- **THEN** SHALL 支持 `NEX_LOG_MAX_BACKUPS`
|
||||
- **THEN** SHALL 支持 `NEX_LOG_MAX_AGE`
|
||||
- **THEN** SHALL 支持 `NEX_LOG_COMPRESS`
|
||||
|
||||
### Requirement: 环境变量优先级
|
||||
|
||||
系统 SHALL 确保环境变量优先级高于配置文件但低于 CLI 参数。
|
||||
|
||||
#### Scenario: 环境变量覆盖配置文件
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **THEN** SHALL 使用环境变量值 9000
|
||||
|
||||
#### Scenario: CLI 参数覆盖环境变量
|
||||
|
||||
- **WHEN** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **AND** CLI 参数设置 `--server-port 8080`
|
||||
- **THEN** SHALL 使用 CLI 参数值 8080
|
||||
|
||||
### Requirement: 12-Factor App 合规
|
||||
|
||||
系统 SHALL 符合 12-Factor App 配置原则。
|
||||
|
||||
#### Scenario: 配置与代码分离
|
||||
|
||||
- **WHEN** 应用部署到不同环境
|
||||
- **THEN** SHALL 通过环境变量区分环境配置
|
||||
- **THEN** SHALL NOT 修改代码或配置文件
|
||||
|
||||
#### Scenario: 敏感信息保护
|
||||
|
||||
- **WHEN** 配置包含敏感信息（如密钥、密码）
|
||||
- **THEN** SHALL 通过环境变量传递
|
||||
- **THEN** SHALL NOT 存储在配置文件中
|
||||
|
||||
### Requirement: 环境变量错误处理
|
||||
|
||||
系统 SHALL 正确处理环境变量错误。
|
||||
|
||||
#### Scenario: 无效环境变量值
|
||||
|
||||
- **WHEN** 环境变量值格式无效（如 `NEX_SERVER_PORT=abc`）
|
||||
- **THEN** SHALL 返回明确的错误信息
|
||||
- **THEN** SHALL 指示环境变量名称和期望类型
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
|
||||
#### Scenario: 环境变量缺失
|
||||
|
||||
- **WHEN** 必需配置项既无配置文件也无环境变量
|
||||
- **THEN** SHALL 使用默认值
|
||||
- **THEN** SHALL 正常启动应用
|
||||
@@ -1,52 +0,0 @@
|
||||
## 1. 依赖管理
|
||||
|
||||
- [ ] 1.1 在 go.mod 中添加 Viper、pflag、validator 依赖
|
||||
- [ ] 1.2 移除 gopkg.in/yaml.v3 依赖（Viper 内置 YAML 支持）
|
||||
- [ ] 1.3 运行 go mod tidy 更新依赖树
|
||||
|
||||
## 2. 配置结构体重构
|
||||
|
||||
- [ ] 2.1 为 Config 结构体添加 validate tag 验证规则
|
||||
- [ ] 2.2 更新 Validate() 方法使用 validator 库进行验证
|
||||
- [ ] 2.3 添加配置摘要打印方法 PrintSummary()
|
||||
|
||||
## 3. 配置加载逻辑重构
|
||||
|
||||
- [ ] 3.1 创建 setupDefaults() 函数设置默认配置值
|
||||
- [ ] 3.2 创建 setupFlags() 函数定义和绑定 CLI 参数
|
||||
- [ ] 3.3 创建 setupEnv() 函数绑定环境变量
|
||||
- [ ] 3.4 创建 setupConfigFile() 函数读取配置文件
|
||||
- [ ] 3.5 重构 LoadConfig() 函数，按顺序调用上述函数
|
||||
- [ ] 3.6 添加 LoadConfigFromPath() 函数支持自定义配置文件路径
|
||||
|
||||
## 4. 主程序修改
|
||||
|
||||
- [ ] 4.1 在 main.go 中添加 CLI 参数解析逻辑
|
||||
- [ ] 4.2 修改配置加载流程，使用新的 LoadConfig()
|
||||
- [ ] 4.3 添加配置摘要打印调用
|
||||
|
||||
## 5. 测试更新
|
||||
|
||||
- [ ] 5.1 更新 TestDefaultConfig 测试新的默认值设置方式
|
||||
- [ ] 5.2 更新 TestConfig_Validate 测试新的验证规则
|
||||
- [ ] 5.3 添加 CLI 参数配置测试
|
||||
- [ ] 5.4 添加环境变量配置测试
|
||||
- [ ] 5.5 添加配置优先级测试
|
||||
- [ ] 5.6 添加配置摘要输出测试
|
||||
- [ ] 5.7 确保所有测试通过
|
||||
|
||||
## 6. 文档更新
|
||||
|
||||
- [ ] 6.1 更新 README.md 配置说明部分
|
||||
- [ ] 6.2 添加 CLI 参数使用示例
|
||||
- [ ] 6.3 添加环境变量配置示例
|
||||
- [ ] 6.4 添加配置优先级说明
|
||||
|
||||
## 7. 验证与清理
|
||||
|
||||
- [ ] 7.1 运行完整测试套件，确保所有测试通过
|
||||
- [ ] 7.2 本地测试：使用 CLI 参数启动应用
|
||||
- [ ] 7.3 本地测试：使用环境变量启动应用
|
||||
- [ ] 7.4 本地测试：混合使用 CLI 参数和环境变量
|
||||
- [ ] 7.5 验证配置摘要输出正确
|
||||
- [ ] 7.6 清理代码，移除不再使用的函数和导入
|
||||
137
openspec/changes/unified-model-id/design.md
Normal file
137
openspec/changes/unified-model-id/design.md
Normal file
@@ -0,0 +1,137 @@
|
||||
## Context
|
||||
|
||||
Nex 是一个 AI 网关，屏蔽多个 AI 供应商（OpenAI、Anthropic 等）的差异，提供统一的 API 接口。当前后端直接透传上游供应商的原始模型名称（如 `gpt-4`），通过 `models` 表的 `model_name` 字段路由。`models` 表的 `id` 字段当前语义是用户自定义标识符，与上游模型名 `model_name` 之间没有明确的职责分离。
|
||||
|
||||
当前架构：
|
||||
- `ProxyHandler` 从请求体中提取 `model` 字段 → `RoutingService.Route(modelName)` 按 `model_name` 查询
|
||||
- `GET /v1/models` 直接透传到第一个供应商的上游接口
|
||||
- `GET /v1/models/{id}` 直接透传到上游
|
||||
- `TargetProvider.ModelName` 在 encoder 中覆盖请求体的 `model` 字段
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 定义统一模型 ID 格式 `provider_id/model_name`，全局唯一标识一个模型
|
||||
- 拦截 `/v1/models` 和 `/v1/models/{unified_id}` 接口，从数据库聚合返回，不再透传上游
|
||||
- 所有代理接口（Chat、Embeddings、Rerank）使用统一模型 ID 路由，响应中 `model` 字段覆写为统一 ID
|
||||
- `models.id` 改为 UUID（内部标识），`models.model_name` 存储上游供应商的模型名称
|
||||
- `provider_id` 约束为 `[a-zA-Z0-9_]+`，防止特殊字符影响 URL 和 JSON 交互
|
||||
- 保持协议无关、供应商无关的设计
|
||||
|
||||
**Non-Goals:**
|
||||
- 不支持供应商别名或模型别名
|
||||
- 不做上游模型列表自动同步（管理员手动配置可见模型）
|
||||
- 不适配前端（后续统一适配）
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: 统一模型 ID 格式 — `provider_id/model_name`
|
||||
|
||||
格式: `{provider_id}/{model_name}`，例如 `openai/gpt-4`、`anthropic/claude-3-opus-20240229`。
|
||||
|
||||
- 使用 `strings.SplitN(id, "/", 2)` 解析，只在第一个 `/` 处分割
|
||||
- `provider_id` 约束为 `[a-zA-Z0-9_]+`，保证不含 `/`，解析安全
|
||||
- `model_name`（上游模型名）不受字符约束，因为它不出现在管理 API 的 URL 主键中
|
||||
|
||||
选择此格式而非 `provider_id:model_name`（冒号分隔）的原因：斜杠在 JSON 字符串中天然安全，且在 URL 路径中语义清晰（`/v1/models/openai/gpt-4`），更符合 REST 风格。
|
||||
|
||||
### D2: models 表 schema 变更
|
||||
|
||||
```
|
||||
旧: id(TEXT PK, 用户自定义), provider_id, model_name(上游模型名), enabled, created_at
|
||||
新: id(UUID PK, 自动生成), provider_id, model_name(上游模型名), enabled, created_at
|
||||
UNIQUE(provider_id, model_name)
|
||||
```
|
||||
|
||||
关键语义变化：
|
||||
- `id` 从用户自定义标识符变为 UUID 内部主键（自动生成），用于管理接口 CRUD
|
||||
- `model_name` 语义不变，始终存储上游供应商的模型名称，发给上游的实际值
|
||||
- 新增联合唯一约束 `UNIQUE(provider_id, model_name)` 保证同一供应商内模型不重复
|
||||
|
||||
选择保留 `id` 作为 PK 而非使用 `(provider_id, model_name)` 联合主键的原因：上游模型名可能含 `/` 等特殊字符（如 Azure OpenAI 的 deployment 路径），不适合作为管理接口的 URL 参数。`id` 为 UUID 可以避免所有特殊字符问题。
|
||||
|
||||
### D3: Models/ModelInfo 接口本地聚合
|
||||
|
||||
`GET /v1/models` 从数据库查询所有 `enabled` 的模型（JOIN providers），组装为 `CanonicalModelList`，`ID` 字段使用统一模型 ID，通过客户端协议的 adapter 编码返回。不请求上游。
|
||||
|
||||
`GET /v1/models/{provider_id}/{model_name}` 从 URL 提取统一模型 ID，解析后查询数据库，组装为 `CanonicalModelInfo` 返回。不请求上游。
|
||||
|
||||
选择纯 DB 聚合而非实时查询上游的原因：
|
||||
1. 管理员通过 `/api/models` 控制哪些模型对用户可见，网关的意义在于控制可见性
|
||||
2. 响应速度快，不依赖上游可用性
|
||||
3. 符合当前架构中管理员手动配置 provider 和 model 的设计哲学
|
||||
|
||||
### D4: 跨协议响应 model 字段覆写
|
||||
|
||||
跨协议场景下，上游返回的响应经过 decode → encode 全量转换。上游响应中的 `model` 字段是原生模型名（如 `gpt-4`），需要在返回给客户端前覆写为统一模型 ID。
|
||||
|
||||
实现位置：`ConversionEngine.ConvertHttpResponse` 新增 `modelOverride string` 参数。在解码上游响应到 canonical 后、编码客户端响应前，将 `canonical.Model` 设为 `modelOverride`。流式场景同理，`CreateStreamConverter` 同样接收 `modelOverride` 参数。
|
||||
|
||||
此方案仅在跨协议转换路径使用。选择在 canonical 层面处理的原因：
|
||||
1. 跨协议必须全量 decode → encode，canonical 的 Model 字段天然可覆写
|
||||
2. 不侵入各协议 adapter 的实现
|
||||
3. 与 Smart Passthrough 互补——跨协议不可保真，canonical 覆写是自然的
|
||||
|
||||
### D5: ProtocolAdapter 接口扩展
|
||||
|
||||
在 `ProtocolAdapter` 接口新增四个方法，将所有协议相关的 model 字段知识归属到 adapter：
|
||||
|
||||
1. `ExtractUnifiedModelID(nativePath string) (string, error)` — 从路径中提取统一模型 ID
|
||||
2. `ExtractModelName(body []byte, ifaceType InterfaceType) (string, error)` — 从请求体中提取 model 值（所有流程复用，替代 handler 层硬编码的 `extractModelName`）
|
||||
3. `RewriteRequestModelName(body []byte, newModel string, ifaceType InterfaceType) ([]byte, error)` — 最小化 JSON 改写请求体中的 model 字段（Smart Passthrough 请求方向）
|
||||
4. `RewriteResponseModelName(body []byte, newModel string, ifaceType InterfaceType) ([]byte, error)` — 最小化 JSON 改写响应体中的 model 字段（Smart Passthrough 响应方向）
|
||||
|
||||
拆分请求/响应方向的原因：请求体和响应体的 JSON 结构可能不同，model 字段的位置可能不同（当前 OpenAI/Anthropic 协议碰巧都在顶层 `"model"`，但未来协议不一定）。拆分后 adapter 各自独立实现，各自按 ifaceType 分派。
|
||||
|
||||
`ExtractModelName` 和两个 `Rewrite*` 方法均接收 `InterfaceType` 参数，因为不同接口类型的请求体/响应体结构可能不同，adapter 按 ifaceType 分派具体的定位和改写逻辑。
|
||||
|
||||
对于 `isModelInfoPath` 的调整：允许 suffix 中包含 `/`，因为统一模型 ID 格式为 `provider_id/model_name`。
|
||||
|
||||
将此方法放在适配器接口而非 handler 中通用实现的原因：不同协议的模型详情路径格式和请求体结构可能不同，各自拥有独立演进能力。
|
||||
|
||||
### D6: provider_id 字符集约束
|
||||
|
||||
创建供应商时校验 `id` 字段必须匹配 `^[a-zA-Z0-9_]+$`，长度 1-64。
|
||||
|
||||
选择严格限制而非仅排除 `/` 的原因：统一模型 ID 出现在 URL 路径和 JSON 中，`?`、`#`、`&`、`=` 等字符会在 URL 中引起解析问题。限制为字母数字下划线后，URL 中永远安全，不需要编码。
|
||||
|
||||
### D7: pkg/modelid 工具包
|
||||
|
||||
新增 `pkg/modelid` 包，提供：
|
||||
- `ParseUnifiedModelID(id string) (providerID, modelName string, error)` — 解析
|
||||
- `FormatUnifiedModelID(providerID, modelName string) string` — 格式化
|
||||
- `ValidateProviderID(id string) error` — 校验供应商 ID
|
||||
- `IsValidUnifiedModelID(id string) bool` — 校验统一模型 ID
|
||||
|
||||
使用标准库 `strings.SplitN` 和 `regexp` 实现，不引入新依赖。
|
||||
|
||||
### D8: 同协议 Smart Passthrough
|
||||
|
||||
当前同协议透传将请求体原样转发，跳过 decode → encode，保持参数完全保真。但统一模型 ID 要求改写 model 字段，原样透传无法满足。
|
||||
|
||||
**Smart Passthrough**：保留同协议透传的保真优势，通过 `json.RawMessage` 做最小化改写。
|
||||
|
||||
实现方式：adapter 的 `RewriteRequestModelName` 和 `RewriteResponseModelName` 方法各自解析 JSON 为 `map[string]json.RawMessage`，只替换 model 字段的 value，其余字段保留原始 bytes，不经过任何类型转换。参数保真、不丢精度、不改字段顺序。
|
||||
|
||||
各接口类型策略：
|
||||
- Chat/Embedding/Rerank（同协议）：Smart Passthrough — 请求改写 model（统一 ID → 上游名），响应改写 model（上游名 → 统一 ID）
|
||||
- Chat/Embedding/Rerank（跨协议）：全量 decode → encode + modelOverride
|
||||
- Models/ModelInfo：本地数据库聚合，不请求上游
|
||||
- Passthrough（未知路径）：原样透传，不改写 model
|
||||
|
||||
选择让 adapter 拥有完整协议知识（而非通用 json hack）的原因：
|
||||
1. 不同协议的 model 字段位置可能不同，adapter 按 InterfaceType 分派
|
||||
2. 请求和响应的 model 字段位置可能不同，拆分 RewriteRequestModelName/RewriteResponseModelName 各自独立实现
|
||||
3. adapter 内部实现 `ExtractModelName` 和两个 `Rewrite*` 方法可共享同一份"model 在哪"的定位逻辑
|
||||
4. 所有流程复用 `ExtractModelName`，同协议额外复用 `RewriteRequestModelName` + `RewriteResponseModelName`
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[BREAKING CHANGE]** 代理接口 model 字段格式变更，现有客户端必须适配 → 统一 ID 格式简单直观，服务尚未上线无旧客户端
|
||||
- **[联合唯一约束]** 同一供应商下相同 model_name 不允许重复 → 这是正确的行为，语义上就不应该重复
|
||||
- **[model_name 含特殊字符]** 上游模型名可能含 `/`（如 Azure deployment 路径）→ 解析用 `SplitN("/", 2)` 安全，管理接口用 `id` 定位不受影响，代理接口中统一 ID 出现在 JSON body 和 URL 路径中均安全
|
||||
- **[流式响应覆写]** 同协议流式场景需逐 SSE chunk 调用 RewriteResponseModelName → 每个 chunk 多一次轻量 JSON 解析，用 json.RawMessage 保证开销极小
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。所有关键决策已在探索阶段确认。
|
||||
41
openspec/changes/unified-model-id/proposal.md
Normal file
41
openspec/changes/unified-model-id/proposal.md
Normal file
@@ -0,0 +1,41 @@
|
||||
## Why
|
||||
|
||||
当前网关直接透传上游供应商的原始模型名称（如 `gpt-4`、`claude-3-opus`），无法在多供应商场景下唯一标识一个模型。不同供应商可能存在同名模型，客户端无法区分应路由到哪个供应商。网关作为屏蔽供应商差异的统一入口，需要定义自有的模型标识体系，让客户端通过统一的 model ID 访问任意供应商的模型，同时拦截 `/v1/models` 等模型查询接口，聚合所有供应商的模型信息返回。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**: 引入统一模型 ID 格式 `provider_id/model_name`（如 `openai/gpt-4`），所有代理接口（Chat、Embeddings、Rerank）的 `model` 字段必须使用此格式
|
||||
- **BREAKING**: `models` 表主键 `id` 改为 UUID 自动生成（不再由用户提供），`model_name` 字段语义保持不变（存储上游供应商模型名称），新增 `UNIQUE(provider_id, model_name)` 联合唯一约束
|
||||
- **BREAKING**: `provider_id` 限制为 `[a-zA-Z0-9_]+` 字符集，禁止特殊字符
|
||||
- `GET /v1/models` 改为从数据库聚合返回所有已启用模型，不再透传到上游供应商
|
||||
- `GET /v1/models/{unified_id}` 改为从数据库查询返回模型详情，不再透传到上游供应商
|
||||
- 同协议透传改为 Smart Passthrough：通过 `json.RawMessage` 最小化改写 model 字段，保持其余参数完全保真
|
||||
- 跨协议转换路径：通过 canonical 层面 modelOverride 参数覆写响应 model 字段
|
||||
- 管理 API (`/api/models`) 请求体字段适配，响应中新增 `unified_id` 字段
|
||||
- 新增 `pkg/modelid` 工具包，提供统一模型 ID 的解析、格式化、校验
|
||||
- ProtocolAdapter 接口新增 `ExtractUnifiedModelID`、`ExtractModelName`、`RewriteRequestModelName`、`RewriteResponseModelName` 方法，协议无关地处理 model 字段
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `unified-model-id`: 统一模型 ID 的解析、格式化、校验工具包，以及 `provider_id` 字符集约束
|
||||
|
||||
### Modified Capabilities
|
||||
- `model-management`: 模型表结构调整（id 改 UUID 自动生成、新增联合唯一约束），CRUD 接口字段变更（创建不再提供 id）
|
||||
- `provider-management`: provider_id 创建时增加字符集校验（`[a-zA-Z0-9_]+`）
|
||||
- `unified-proxy-handler`: 统一模型 ID 解析路由、Models/ModelInfo 接口改为本地聚合、同协议 Smart Passthrough、跨协议 modelOverride 覆写
|
||||
- `conversion-engine`: 跨协议场景下 ConvertHttpResponse 支持 model 覆写参数
|
||||
- `protocol-adapter-openai`: isModelInfoPath 适配含 `/` 路径、新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName
|
||||
- `protocol-adapter-anthropic`: isModelInfoPath 适配含 `/` 路径、新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName
|
||||
- `request-validation`: provider_id 字符集校验规则、模型创建校验适配
|
||||
- `database-migration`: models 表 schema 变更迁移（DROP + CREATE 重建）
|
||||
- `usage-statistics`: 明确统计记录使用 providerID + modelName 的上游模型名
|
||||
|
||||
## Impact
|
||||
|
||||
- **数据库**: models 表 schema 变更（DROP + CREATE 重建）
|
||||
- **API 兼容性**: 代理接口 model 字段格式为 BREAKING CHANGE，需客户端适配
|
||||
- **管理 API**: `/api/models` 请求体变更（创建不再提供 id，自动生成 UUID），响应新增 unified_id 字段
|
||||
- **代码模块**: domain、repository、service、handler、conversion、adapter 层均有改动
|
||||
- **测试**: routing service、proxy handler、adapter、model handler 需要新增/更新测试
|
||||
- **前端**: 本次变更不涉及前端适配，前端后续统一适配
|
||||
@@ -0,0 +1,49 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 跨协议响应转换支持 model 覆写
|
||||
|
||||
ConversionEngine SHALL 在跨协议响应转换时支持 model 字段覆写。
|
||||
|
||||
#### Scenario: ConvertHttpResponse 接收 modelOverride 参数
|
||||
|
||||
- **WHEN** 调用 `ConvertHttpResponse` 时传入 `modelOverride` 参数（跨协议场景，非空字符串）
|
||||
- **THEN** SHALL 在解码上游响应到 canonical 后，将 `Model` 字段设为 `modelOverride`
|
||||
- **THEN** SHALL 使用覆写后的 canonical 编码为客户端协议格式
|
||||
|
||||
#### Scenario: modelOverride 为空
|
||||
|
||||
- **WHEN** 调用 `ConvertHttpResponse` 时 `modelOverride` 为空字符串
|
||||
- **THEN** SHALL NOT 覆写 canonical 的 Model 字段，保持上游原始值
|
||||
|
||||
#### Scenario: Chat 响应 model 覆写
|
||||
|
||||
- **WHEN** 跨协议转换 Chat 类型响应且 `modelOverride` 非空
|
||||
- **THEN** `CanonicalResponse.Model` SHALL 被设为 `modelOverride`
|
||||
|
||||
#### Scenario: Embedding 响应 model 覆写
|
||||
|
||||
- **WHEN** 跨协议转换 Embedding 类型响应且 `modelOverride` 非空
|
||||
- **THEN** `CanonicalEmbeddingResponse.Model` SHALL 被设为 `modelOverride`
|
||||
|
||||
#### Scenario: Rerank 响应 model 覆写
|
||||
|
||||
- **WHEN** 跨协议转换 Rerank 类型响应且 `modelOverride` 非空
|
||||
- **THEN** `CanonicalRerankResponse.Model` SHALL 被设为 `modelOverride`
|
||||
|
||||
### Requirement: 跨协议流式转换支持 model 覆写
|
||||
|
||||
ConversionEngine SHALL 在跨协议流式转换时支持 model 字段覆写。
|
||||
|
||||
#### Scenario: CreateStreamConverter 接收 modelOverride 参数
|
||||
|
||||
- **WHEN** 调用 `CreateStreamConverter` 时传入 `modelOverride` 参数（跨协议场景）
|
||||
- **THEN** SHALL 在流式 canonical 事件中将 `Model` 字段设为 `modelOverride`
|
||||
|
||||
### Requirement: TargetProvider 字段语义
|
||||
|
||||
TargetProvider 的 ModelName 字段 SHALL 存储上游供应商的模型名称（即 `model_name` 字段值），语义保持不变。
|
||||
|
||||
#### Scenario: encoder 使用 TargetProvider.ModelName
|
||||
|
||||
- **WHEN** 协议适配器编码请求时
|
||||
- **THEN** SHALL 使用 `TargetProvider.ModelName` 作为发给上游的 `model` 字段值（值为路由结果中的 model_name）
|
||||
@@ -0,0 +1,13 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: models 表 schema 变更
|
||||
|
||||
系统 SHALL 通过迁移脚本重建 models 表结构（服务未上线，无需考虑数据迁移）。
|
||||
|
||||
#### Scenario: 迁移后 models 表结构
|
||||
|
||||
- **WHEN** 执行迁移
|
||||
- **THEN** SHALL 先 DROP 已有的 models 表（无旧数据）
|
||||
- **THEN** SHALL CREATE 新的 models 表，包含字段：id（TEXT PRIMARY KEY）、provider_id（TEXT NOT NULL）、model_name（TEXT NOT NULL）、enabled（INTEGER DEFAULT 1）、created_at（DATETIME）
|
||||
- **THEN** SHALL 存在 UNIQUE(provider_id, model_name) 约束
|
||||
- **THEN** SHALL 存在 FOREIGN KEY (provider_id) REFERENCES providers(id) ON DELETE CASCADE
|
||||
105
openspec/changes/unified-model-id/specs/model-management/spec.md
Normal file
105
openspec/changes/unified-model-id/specs/model-management/spec.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 创建模型配置
|
||||
|
||||
网关 SHALL 允许为供应商创建新的模型配置。
|
||||
|
||||
#### Scenario: 使用有效数据创建模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 POST 请求，携带有效的模型数据（provider_id, model_name），不提供 id 字段
|
||||
- **THEN** 网关 SHALL 自动生成 UUID 作为模型 id
|
||||
- **THEN** 网关 SHALL 在数据库中创建新的模型记录
|
||||
- **THEN** 网关 SHALL 返回创建的模型，状态码为 201
|
||||
- **THEN** 模型 SHALL 默认启用
|
||||
- **THEN** 返回的模型 SHALL 包含 `unified_id` 字段，值为 `{provider_id}/{model_name}`
|
||||
|
||||
#### Scenario: 使用不存在的供应商创建模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 POST 请求，携带不存在的 provider_id
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
- **THEN** 错误 SHALL 指示供应商不存在
|
||||
|
||||
#### Scenario: 创建重复模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 POST 请求，携带已存在的 provider_id + model_name 组合
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||||
- **THEN** 错误 SHALL 指示该供应商下已存在相同模型
|
||||
|
||||
### Requirement: 列出所有模型
|
||||
|
||||
网关 SHALL 允许获取所有模型配置。
|
||||
|
||||
#### Scenario: 成功列出模型
|
||||
|
||||
- **WHEN** 向 `/api/models` 发送 GET 请求
|
||||
- **THEN** 网关 SHALL 返回所有模型的列表
|
||||
- **THEN** 每个模型 SHALL 包含 id, provider_id, model_name, unified_id, enabled, created_at
|
||||
|
||||
**变更说明：** 响应新增 unified_id 字段，移除旧语义的 id 自定义输入。
|
||||
|
||||
### Requirement: 按供应商列出模型
|
||||
|
||||
网关 SHALL 允许获取特定供应商的模型。
|
||||
|
||||
#### Scenario: 列出存在供应商的模型
|
||||
|
||||
- **WHEN** 向 `/api/models?provider_id=<provider_id>` 发送 GET 请求
|
||||
- **THEN** 网关 SHALL 返回指定供应商的模型列表
|
||||
- **THEN** 每个模型 SHALL 包含 unified_id 字段
|
||||
|
||||
### Requirement: 更新模型配置
|
||||
|
||||
网关 SHALL 允许更新现有模型配置。
|
||||
|
||||
#### Scenario: 使用有效数据更新模型
|
||||
|
||||
- **WHEN** 向 `/api/models/:id` 发送 PUT 请求，携带有效的模型数据
|
||||
- **THEN** 网关 SHALL 更新数据库中的模型记录
|
||||
- **THEN** 网关 SHALL 返回更新后的模型
|
||||
- **THEN** 返回的模型 SHALL 包含更新后的 unified_id
|
||||
|
||||
#### Scenario: 更新模型为重复组合
|
||||
|
||||
- **WHEN** 向 `/api/models/:id` 发送 PUT 请求，更新 provider_id 或 model_name 导致与已有记录重复
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||||
|
||||
### Requirement: 删除模型配置
|
||||
|
||||
网关 SHALL 允许删除模型配置。
|
||||
|
||||
#### Scenario: 删除存在的模型
|
||||
|
||||
- **WHEN** 向 `/api/models/:id` 发送 DELETE 请求，携带有效的模型 ID
|
||||
- **THEN** 网关 SHALL 删除模型记录
|
||||
- **THEN** 网关 SHALL 返回状态码 204 (No Content)
|
||||
|
||||
### Requirement: 使用 service 层处理业务逻辑
|
||||
|
||||
Handler SHALL 通过 ModelService 处理业务逻辑。
|
||||
|
||||
#### Scenario: 调用 service 方法
|
||||
|
||||
- **WHEN** handler 收到请求
|
||||
- **THEN** SHALL 调用对应的 ModelService 方法（Create、Get、List、Update、Delete）
|
||||
- **THEN** SHALL 使用 domain.Model 类型
|
||||
- **THEN** Create 时 SHALL 调用 `uuid.New()` 生成 id
|
||||
|
||||
#### Scenario: 供应商验证和唯一性校验
|
||||
|
||||
- **WHEN** 创建或更新模型
|
||||
- **THEN** SHALL 在 service 层验证供应商存在
|
||||
- **THEN** SHALL 在 service 层验证 provider_id + model_name 联合唯一
|
||||
|
||||
### Requirement: 使用 repository 层访问数据
|
||||
|
||||
Service SHALL 通过 ModelRepository 访问数据。
|
||||
|
||||
#### Scenario: 联合查询
|
||||
|
||||
- **WHEN** service 需要按 provider 和 model_name 查询模型
|
||||
- **THEN** SHALL 调用 `FindByProviderAndModelName(providerID, modelName)` 方法
|
||||
|
||||
#### Scenario: 查询所有启用模型
|
||||
|
||||
- **WHEN** proxy handler 需要聚合模型列表
|
||||
- **THEN** SHALL 调用 `ListEnabled()` 方法，返回所有 enabled 的模型（关联 enabled 的供应商）
|
||||
@@ -0,0 +1,71 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 模型详情路径识别
|
||||
|
||||
Anthropic 适配器 SHALL 正确识别包含统一模型 ID 的模型详情路径。
|
||||
|
||||
#### Scenario: 含斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/anthropic/claude-3-opus`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 含多段斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/azure/deployments/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 模型列表路径不受影响
|
||||
|
||||
- **WHEN** 路径为 `/v1/models`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModels`
|
||||
|
||||
### Requirement: 提取统一模型 ID
|
||||
|
||||
Anthropic 适配器 SHALL 从路径中提取统一模型 ID。
|
||||
|
||||
#### Scenario: 标准路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/anthropic/claude-3-opus")`
|
||||
- **THEN** SHALL 返回 `"anthropic/claude-3-opus"`
|
||||
|
||||
#### Scenario: 复杂路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/azure/accounts/org/models/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"azure/accounts/org/models/gpt-4"`
|
||||
|
||||
#### Scenario: 非模型详情路径
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models")`
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 从请求体提取 model
|
||||
|
||||
Anthropic 适配器 SHALL 按 InterfaceType 从请求体中提取 model 值。
|
||||
|
||||
#### Scenario: Chat 请求提取 model
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, InterfaceTypeChat)`，body 为 `{"model":"anthropic/claude-3-opus","messages":[...]}`
|
||||
- **THEN** SHALL 返回 `"anthropic/claude-3-opus"`
|
||||
|
||||
#### Scenario: 无 model 字段
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, ifaceType)`，body 中不含 model 字段
|
||||
- **THEN** SHALL 返回空字符串，不返回错误
|
||||
|
||||
### Requirement: 最小化改写请求体 model 字段
|
||||
|
||||
Anthropic 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写请求体中的 model 字段，其余字段保持原始 bytes。
|
||||
|
||||
#### Scenario: 请求体 model 改写（统一 ID → 上游名）
|
||||
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "claude-3-opus-20240229", InterfaceTypeChat)`
|
||||
- **THEN** SHALL 将请求体中 model 字段替换为 `"claude-3-opus-20240229"`，其余字段原样保留
|
||||
|
||||
### Requirement: 最小化改写响应体 model 字段
|
||||
|
||||
Anthropic 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写响应体中的 model 字段，其余字段保持原始 bytes。请求体和响应体的 model 字段位置可能不同，各自独立实现。
|
||||
|
||||
#### Scenario: 响应体 model 改写（上游名 → 统一 ID）
|
||||
|
||||
- **WHEN** 调用 `RewriteResponseModelName(body, "anthropic/claude-3-opus", InterfaceTypeChat)`
|
||||
- **THEN** SHALL 将响应体中 model 字段替换为 `"anthropic/claude-3-opus"`，其余字段原样保留
|
||||
@@ -0,0 +1,89 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 模型详情路径识别
|
||||
|
||||
OpenAI 适配器 SHALL 正确识别包含统一模型 ID 的模型详情路径。
|
||||
|
||||
#### Scenario: 含斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/openai/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 含多段斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/v1/models/azure/accounts/org-123/models/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 模型列表路径不受影响
|
||||
|
||||
- **WHEN** 路径为 `/v1/models`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModels`
|
||||
|
||||
### Requirement: 提取统一模型 ID
|
||||
|
||||
OpenAI 适配器 SHALL 从路径中提取统一模型 ID。
|
||||
|
||||
#### Scenario: 标准路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/openai/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"openai/gpt-4"`
|
||||
|
||||
#### Scenario: 复杂路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/azure/accounts/org/models/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"azure/accounts/org/models/gpt-4"`
|
||||
|
||||
#### Scenario: 非模型详情路径
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models")`
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 从请求体提取 model
|
||||
|
||||
OpenAI 适配器 SHALL 按 InterfaceType 从请求体中提取 model 值。
|
||||
|
||||
#### Scenario: Chat 请求提取 model
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, InterfaceTypeChat)`，body 为 `{"model":"openai/gpt-4","messages":[...]}`
|
||||
- **THEN** SHALL 返回 `"openai/gpt-4"`
|
||||
|
||||
#### Scenario: Embedding 请求提取 model
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, InterfaceTypeEmbeddings)`，body 为 `{"model":"openai/text-embedding-3","input":"text"}`
|
||||
- **THEN** SHALL 返回 `"openai/text-embedding-3"`
|
||||
|
||||
#### Scenario: 无 model 字段
|
||||
|
||||
- **WHEN** 调用 `ExtractModelName(body, ifaceType)`，body 中不含 model 字段
|
||||
- **THEN** SHALL 返回空字符串，不返回错误
|
||||
|
||||
### Requirement: 最小化改写请求体 model 字段
|
||||
|
||||
OpenAI 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写请求体中的 model 字段，其余字段保持原始 bytes。
|
||||
|
||||
#### Scenario: 请求体 model 改写（统一 ID → 上游名）
|
||||
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "gpt-4", InterfaceTypeChat)`，body 为 `{"model":"openai/gpt-4","messages":[...],"some_param":"value"}`
|
||||
- **THEN** SHALL 返回 `{"model":"gpt-4","messages":[...],"some_param":"value"}`
|
||||
- **THEN** 除 model 外的字段 SHALL 保持原始 bytes 不变
|
||||
|
||||
#### Scenario: 不同 InterfaceType 的请求改写
|
||||
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "gpt-4", InterfaceTypeEmbeddings)`
|
||||
- **THEN** SHALL 按 Embedding 接口的请求体 model 字段位置进行改写
|
||||
- **WHEN** 调用 `RewriteRequestModelName(body, "gpt-4", InterfaceTypeRerank)`
|
||||
- **THEN** SHALL 按 Rerank 接口的请求体 model 字段位置进行改写
|
||||
|
||||
### Requirement: 最小化改写响应体 model 字段
|
||||
|
||||
OpenAI 适配器 SHALL 按 InterfaceType 用 `json.RawMessage` 最小化改写响应体中的 model 字段，其余字段保持原始 bytes。请求体和响应体的 model 字段位置可能不同，各自独立实现。
|
||||
|
||||
#### Scenario: 响应体 model 改写（上游名 → 统一 ID）
|
||||
|
||||
- **WHEN** 调用 `RewriteResponseModelName(body, "openai/gpt-4", InterfaceTypeChat)`，body 为上游 Chat 响应
|
||||
- **THEN** SHALL 将 model 字段替换为 `"openai/gpt-4"`，其余字段原样保留
|
||||
|
||||
#### Scenario: 不同 InterfaceType 的响应改写
|
||||
|
||||
- **WHEN** 调用 `RewriteResponseModelName(body, "openai/gpt-4", InterfaceTypeEmbeddings)`
|
||||
- **THEN** SHALL 按 Embedding 接口的响应体 model 字段位置进行改写
|
||||
@@ -0,0 +1,35 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 创建供应商配置
|
||||
|
||||
网关 SHALL 允许通过管理 API 创建新的供应商配置。
|
||||
|
||||
#### Scenario: 使用有效数据创建供应商
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，携带有效的供应商数据（id, name, api_key, base_url, protocol）
|
||||
- **THEN** 网关 SHALL 在数据库中创建新的供应商记录
|
||||
- **THEN** 网关 SHALL 返回创建的供应商，状态码为 201
|
||||
- **THEN** 供应商 SHALL 默认启用
|
||||
- **THEN** protocol 字段 SHALL 默认为 "openai"
|
||||
|
||||
#### Scenario: 使用重复 ID 创建供应商
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，携带已存在的 ID
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 409 (Conflict)
|
||||
|
||||
#### Scenario: 创建供应商时缺少必需字段
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，缺少必需字段（id, name, api_key 或 base_url）
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
- **THEN** 错误 SHALL 指示缺少哪些字段
|
||||
|
||||
#### Scenario: 创建供应商时 ID 包含非法字符
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，id 包含非 `[a-zA-Z0-9_]` 字符
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
- **THEN** 错误 SHALL 指示 id 仅允许字母、数字、下划线
|
||||
|
||||
#### Scenario: 创建供应商时 ID 过长
|
||||
|
||||
- **WHEN** 向 `/api/providers` 发送 POST 请求，id 长度超过 64
|
||||
- **THEN** 网关 SHALL 返回错误，状态码为 400 (Bad Request)
|
||||
@@ -0,0 +1,39 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 供应商 ID 校验
|
||||
|
||||
创建供应商时，SHALL 对 `id` 字段进行字符集校验。
|
||||
|
||||
#### Scenario: 合法字符集
|
||||
|
||||
- **WHEN** 创建供应商，id 仅包含 `[a-zA-Z0-9_]` 字符
|
||||
- **THEN** SHALL 校验通过
|
||||
|
||||
#### Scenario: 非法字符
|
||||
|
||||
- **WHEN** 创建供应商，id 包含 `-`、`.`、`/`、空格、中文等非 `[a-zA-Z0-9_]` 字符
|
||||
- **THEN** SHALL 返回 400 错误
|
||||
|
||||
#### Scenario: 长度限制
|
||||
|
||||
- **WHEN** 创建供应商，id 长度超过 64
|
||||
- **THEN** SHALL 返回 400 错误
|
||||
|
||||
### Requirement: 模型创建校验
|
||||
|
||||
创建模型时，SHALL 对 `provider_id` + `model_name` 进行联合唯一性校验。
|
||||
|
||||
#### Scenario: 正常创建
|
||||
|
||||
- **WHEN** 创建模型，provider_id 存在且 provider_id + model_name 组合唯一
|
||||
- **THEN** SHALL 校验通过
|
||||
|
||||
#### Scenario: 联合唯一冲突
|
||||
|
||||
- **WHEN** 创建模型，provider_id + model_name 组合已存在
|
||||
- **THEN** SHALL 返回 409 错误
|
||||
|
||||
#### Scenario: model_name 为空
|
||||
|
||||
- **WHEN** 创建模型，未提供 model_name
|
||||
- **THEN** SHALL 返回 400 错误
|
||||
@@ -0,0 +1,79 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 解析统一模型 ID
|
||||
|
||||
系统 SHALL 提供 `ParseUnifiedModelID` 函数，将 `provider_id/model_name` 格式的字符串解析为独立的 providerID 和 modelName。
|
||||
|
||||
#### Scenario: 标准格式解析
|
||||
|
||||
- **WHEN** 传入 `"openai/gpt-4"`
|
||||
- **THEN** SHALL 返回 providerID=`"openai"`, modelName=`"gpt-4"`
|
||||
|
||||
#### Scenario: model_name 含斜杠的解析
|
||||
|
||||
- **WHEN** 传入 `"azure/accounts/org-123/models/gpt-4"`
|
||||
- **THEN** SHALL 在第一个 `/` 处分割，返回 providerID=`"azure"`, modelName=`"accounts/org-123/models/gpt-4"`
|
||||
|
||||
#### Scenario: 缺少分隔符
|
||||
|
||||
- **WHEN** 传入不含 `/` 的字符串（如 `"gpt-4"`）
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
#### Scenario: 空字符串
|
||||
|
||||
- **WHEN** 传入空字符串
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
#### Scenario: 只有分隔符
|
||||
|
||||
- **WHEN** 传入 `"/model"` 或 `"provider/"` 或 `"/"`
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
#### Scenario: providerID 不符合字符集
|
||||
|
||||
- **WHEN** 传入 `"open-ai/gpt-4"` 或 `"open.ai/gpt-4"` 或 `"供应商/gpt-4"`（providerID 含非 `[a-zA-Z0-9_]` 字符）
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 格式化统一模型 ID
|
||||
|
||||
系统 SHALL 提供 `FormatUnifiedModelID` 函数，将 providerID 和 modelName 组合格式化为统一模型 ID。
|
||||
|
||||
#### Scenario: 格式化
|
||||
|
||||
- **WHEN** 传入 providerID=`"openai"`, modelName=`"gpt-4"`
|
||||
- **THEN** SHALL 返回 `"openai/gpt-4"`
|
||||
|
||||
### Requirement: 校验供应商 ID
|
||||
|
||||
系统 SHALL 提供 `ValidateProviderID` 函数，校验 providerID 仅包含字母、数字、下划线。
|
||||
|
||||
#### Scenario: 合法 ID
|
||||
|
||||
- **WHEN** 传入 `"openai"`, `"deep_seek"`, `"provider01"`, `"OpenAI"`
|
||||
- **THEN** SHALL 校验通过
|
||||
|
||||
#### Scenario: 含非法字符
|
||||
|
||||
- **WHEN** 传入含 `-`、`.`、`/`、空格、中文等非 `[a-zA-Z0-9_]` 字符的 ID
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
#### Scenario: 空字符串或过长
|
||||
|
||||
- **WHEN** 传入空字符串
|
||||
- **THEN** SHALL 返回错误
|
||||
- **WHEN** 传入超过 64 个字符的 ID
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 校验统一模型 ID
|
||||
|
||||
系统 SHALL 提供 `IsValidUnifiedModelID` 函数，判断字符串是否为合法的统一模型 ID 格式。
|
||||
|
||||
#### Scenario: 合法 ID
|
||||
|
||||
- **WHEN** 传入 `"openai/gpt-4"`
|
||||
- **THEN** SHALL 返回 `true`
|
||||
|
||||
#### Scenario: 非法 ID
|
||||
|
||||
- **WHEN** 传入不含 `/` 的字符串、空字符串、providerID 不符合 `[a-zA-Z0-9_]+` 的字符串
|
||||
- **THEN** SHALL 返回 `false`
|
||||
@@ -0,0 +1,123 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 代理请求路由
|
||||
|
||||
ProxyHandler SHALL 使用统一模型 ID 路由所有代理请求。
|
||||
|
||||
#### Scenario: 提取统一模型 ID
|
||||
|
||||
- **WHEN** 收到 Chat、Embeddings 或 Rerank 接口的 POST 请求（含请求体）
|
||||
- **THEN** SHALL 调用客户端协议 adapter 的 `ExtractModelName(body, ifaceType)` 提取 model 值
|
||||
- **THEN** SHALL 调用 `ParseUnifiedModelID` 解析得到 providerID 和 modelName
|
||||
- **THEN** SHALL 调用 `RoutingService.RouteByModelName(providerID, modelName)` 路由
|
||||
|
||||
#### Scenario: GET 请求或无请求体
|
||||
|
||||
- **WHEN** 收到 GET 请求或请求体为空
|
||||
- **THEN** SHALL 返回错误响应，状态码为 400，提示缺少 model 字段
|
||||
|
||||
#### Scenario: 无效的统一模型 ID
|
||||
|
||||
- **WHEN** 请求体中 `model` 字段不是有效的统一模型 ID 格式
|
||||
- **THEN** SHALL 返回错误响应，状态码为 400
|
||||
|
||||
#### Scenario: 模型不存在
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，数据库中找不到对应的 provider_id + model_name 组合
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 模型已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的模型 enabled 为 false
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 供应商已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的供应商 enabled 为 false
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
### Requirement: 同协议 Smart Passthrough
|
||||
|
||||
当客户端协议与供应商协议相同时，ProxyHandler SHALL 使用 Smart Passthrough 处理 Chat、Embedding、Rerank 请求。
|
||||
|
||||
#### Scenario: 同协议非流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为非流式请求
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteRequestModelName(body, modelName, ifaceType)` 将请求体中 model 从统一 ID 改写为上游模型名
|
||||
- **THEN** SHALL 构建 URL 和 Headers（同当前透传逻辑）
|
||||
- **THEN** SHALL 发送改写后的请求体到上游
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteResponseModelName(resp.Body, unifiedModelID, ifaceType)` 将响应中 model 从上游名改写为统一 ID
|
||||
- **THEN** SHALL NOT 对 body 做全量 decode → encode，保持未改写字段的原始 bytes
|
||||
|
||||
#### Scenario: 同协议流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为流式请求
|
||||
- **THEN** SHALL 对请求体做 `RewriteRequestModelName` 改写 model 字段
|
||||
- **THEN** SHALL 逐 SSE chunk 调用 `RewriteResponseModelName` 改写响应中 model 字段
|
||||
- **THEN** SHALL NOT 对 chunk 做全量 decode → encode
|
||||
|
||||
#### Scenario: Smart Passthrough 保真性
|
||||
|
||||
- **WHEN** 客户端发送含未知参数的请求（如 `{"model":"openai/gpt-4","some_new_param":"value"}`）
|
||||
- **THEN** 上游 SHALL 收到 `{"model":"gpt-4","some_new_param":"value"}`
|
||||
- **THEN** `some_new_param` SHALL 保持原始值不变，不丢失、不改变类型
|
||||
|
||||
### Requirement: 跨协议完整转换
|
||||
|
||||
当客户端协议与供应商协议不同时，ProxyHandler SHALL 使用全量转换路径。
|
||||
|
||||
#### Scenario: 跨协议非流式请求
|
||||
|
||||
- **WHEN** 客户端协议 != 供应商协议
|
||||
- **THEN** SHALL 走 `ConvertHttpRequest` 全量转换，encoder 中 provider.ModelName 覆盖 model
|
||||
- **THEN** SHALL 走 `ConvertHttpResponse` 全量转换，modelOverride 参数覆写 canonical.Model
|
||||
|
||||
#### Scenario: 跨协议流式请求
|
||||
|
||||
- **WHEN** 客户端协议 != 供应商协议，且为流式请求
|
||||
- **THEN** SHALL 走 `CreateStreamConverter` 全量转换，modelOverride 参数覆写流式 canonical 事件中的 Model
|
||||
|
||||
### Requirement: 模型列表本地聚合
|
||||
|
||||
ProxyHandler SHALL 从数据库聚合返回模型列表，不再透传上游。
|
||||
|
||||
#### Scenario: GET /v1/models
|
||||
|
||||
- **WHEN** 收到 `GET /{protocol}/v1/models` 请求
|
||||
- **THEN** SHALL 从数据库查询所有 enabled 的模型（关联 enabled 的供应商）
|
||||
- **THEN** SHALL 组装 `CanonicalModelList`，每个模型的 ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 无可用模型
|
||||
|
||||
- **WHEN** 数据库中没有 enabled 的模型
|
||||
- **THEN** SHALL 返回空列表
|
||||
|
||||
### Requirement: 模型详情本地查询
|
||||
|
||||
ProxyHandler SHALL 从数据库查询返回模型详情，不再透传上游。
|
||||
|
||||
#### Scenario: GET /v1/models/{unified_id}
|
||||
|
||||
- **WHEN** 收到 `GET /{protocol}/v1/models/{provider_id}/{model_name}` 请求
|
||||
- **THEN** SHALL 调用 adapter 的 `ExtractUnifiedModelID` 提取统一模型 ID
|
||||
- **THEN** SHALL 解析统一模型 ID 得到 providerID 和 modelName
|
||||
- **THEN** SHALL 从数据库查询对应的模型和供应商
|
||||
- **THEN** SHALL 组装 `CanonicalModelInfo`，ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 模型详情不存在
|
||||
|
||||
- **WHEN** 统一模型 ID 对应的模型不存在或已禁用
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
|
||||
### Requirement: 统计记录
|
||||
|
||||
ProxyHandler SHALL 使用 providerID 和 modelName 记录使用统计。
|
||||
|
||||
#### Scenario: 异步记录统计
|
||||
|
||||
- **WHEN** 代理请求成功完成
|
||||
- **THEN** SHALL 异步调用 `StatsService.Record(providerID, modelName)`
|
||||
@@ -0,0 +1,16 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用统计记录统一模型标识
|
||||
|
||||
系统 SHALL 使用 providerID 和 modelName（上游模型名）记录使用统计。
|
||||
|
||||
#### Scenario: 代理请求统计记录
|
||||
|
||||
- **WHEN** 代理请求成功完成
|
||||
- **THEN** SHALL 记录 provider_id 和 model_name 到 usage_stats 表（参数来自路由结果）
|
||||
- **THEN** SHALL 异步执行，不阻塞响应
|
||||
|
||||
#### Scenario: 查询统计
|
||||
|
||||
- **WHEN** 查询统计数据
|
||||
- **THEN** 支持按 provider_id 和 model_name 过滤
|
||||
53
openspec/changes/unified-model-id/tasks.md
Normal file
53
openspec/changes/unified-model-id/tasks.md
Normal file
@@ -0,0 +1,53 @@
|
||||
## 1. 数据库迁移
|
||||
|
||||
- [ ] 1.1 新增迁移脚本：DROP 旧 models 表 + CREATE 新 models 表（id UUID PK, provider_id, model_name, enabled, created_at），UNIQUE(provider_id, model_name)
|
||||
- [ ] 1.2 更新 config/models.go：Model 结构体适配（id 改为 UUID 自动生成，model_name 保持不变）
|
||||
- [ ] 1.3 编写迁移脚本测试
|
||||
|
||||
## 2. 统一模型 ID 工具包
|
||||
|
||||
- [ ] 2.1 新增 pkg/modelid/model_id.go：实现 ParseUnifiedModelID、FormatUnifiedModelID、ValidateProviderID、IsValidUnifiedModelID
|
||||
- [ ] 2.2 新增 pkg/modelid/model_id_test.go：覆盖标准格式、含斜杠 model_name、空字符串、非法字符等边界情况
|
||||
|
||||
## 3. Domain 层适配
|
||||
|
||||
- [ ] 3.1 修改 domain/model.go：Model 结构体字段适配，新增 UnifiedModelID() 方法
|
||||
- [ ] 3.2 修改 domain/route.go：RouteResult 适配新字段
|
||||
|
||||
## 4. Repository 层适配
|
||||
|
||||
- [ ] 4.1 修改 repository/model_repo.go：接口变更 — GetByModelName 改为 FindByProviderAndModelName，新增 ListEnabled
|
||||
- [ ] 4.2 修改 repository/model_repo_impl.go：实现 FindByProviderAndModelName（WHERE provider_id=? AND model_name=?）、ListEnabled（JOIN providers WHERE enabled）
|
||||
- [ ] 4.3 编写 repository 层测试
|
||||
|
||||
## 5. Service 层适配
|
||||
|
||||
- [ ] 5.1 修改 service/routing_service.go：Route 接口改为 RouteByModelName(providerID, modelName string)
|
||||
- [ ] 5.2 修改 service/routing_service_impl.go：调用 FindByProviderAndModelName 替代 GetByModelName
|
||||
- [ ] 5.3 修改 service/model_service.go：Create 生成 UUID、新增联合唯一校验方法
|
||||
- [ ] 5.4 修改 service/model_service_impl.go：实现联合唯一校验、UUID 生成
|
||||
- [ ] 5.5 修改 service/provider_service_impl.go：Create 时调用 ValidateProviderID 校验 ID 字符集
|
||||
- [ ] 5.6 编写 service 层测试
|
||||
|
||||
## 6. Conversion 层适配
|
||||
|
||||
- [ ] 6.1 修改 conversion/adapter.go：ProtocolAdapter 接口新增 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName 四个方法
|
||||
- [ ] 6.2 修改 conversion/engine.go：ConvertHttpResponse 新增 modelOverride 参数（跨协议场景），各 convert*ResponseBody 中覆写 canonical Model；CreateStreamConverter 新增 modelOverride 参数
|
||||
- [ ] 6.3 修改 conversion/openai/adapter.go：实现 ExtractUnifiedModelID、ExtractModelName（按 ifaceType 提取 model）、RewriteRequestModelName 和 RewriteResponseModelName（json.RawMessage 最小化改写，按 ifaceType 定位 model 字段，请求/响应独立实现），修改 isModelInfoPath 允许 suffix 含 "/"
|
||||
- [ ] 6.4 修改 conversion/anthropic/adapter.go：实现 ExtractUnifiedModelID、ExtractModelName、RewriteRequestModelName、RewriteResponseModelName，修改 isModelInfoPath 允许 suffix 含 "/"
|
||||
- [ ] 6.5 编写 conversion 层测试：ExtractUnifiedModelID、ExtractModelName 各 ifaceType、RewriteRequestModelName/RewriteResponseModelName 保真性（含未知参数不丢失）、isModelInfoPath 含斜杠路径、modelOverride 覆写
|
||||
|
||||
## 7. Handler 层改造
|
||||
|
||||
- [ ] 7.1 修改 handler/proxy_handler.go：HandleProxy 按接口类型分发 — Models/ModelInfo 本地聚合；Chat/Embed/Rerank 用 adapter.ExtractModelName 提取统一 ID 路由，同协议走 Smart Passthrough（adapter.RewriteRequestModelName 改写请求、adapter.RewriteResponseModelName 改写响应），跨协议走全量转换（modelOverride）；删除 forwardPassthrough 和硬编码的 extractModelName
|
||||
- [ ] 7.2 修改 handler/model_handler.go：请求体字段适配（移除 id 输入、保留 provider_id 和 model_name），响应新增 unified_id，Create 使用 UUID
|
||||
- [ ] 7.3 修改 handler/provider_handler.go：CreateProvider 校验 ID 字符集
|
||||
- [ ] 7.4 编写 handler 层测试：统一模型 ID 路由、同协议 Smart Passthrough 保真性、跨协议 modelOverride、Models 聚合、ModelInfo 查询、流式场景 model 覆写、provider ID 校验
|
||||
|
||||
## 8. 路由注册适配
|
||||
|
||||
- [ ] 8.1 修改 cmd/server/main.go：setupRoutes 适配 handler 签名变更，传递新增依赖
|
||||
|
||||
## 9. 文档更新
|
||||
|
||||
- [ ] 9.1 按需更新 README.md：同步 models 表结构、API 接口字段、统一模型 ID 格式、Smart Passthrough 策略等变更说明
|
||||
@@ -1,6 +1,10 @@
|
||||
# Anthropic Protocol Proxy
|
||||
|
||||
## MODIFIED Requirements
|
||||
## Purpose
|
||||
|
||||
定义 Anthropic Messages API 端点的协议代理行为，包括请求处理流程、同协议透传和双向协议转换。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 支持 Anthropic Messages API 端点
|
||||
|
||||
@@ -38,50 +42,10 @@
|
||||
- **THEN** SHALL 将 OpenAI ChatCompletionResponse 解码为 CanonicalResponse
|
||||
- **THEN** SHALL 将 CanonicalResponse 编码为 Anthropic MessagesResponse
|
||||
|
||||
#### Scenario: OpenAI 客户端 → Anthropic 供应<EFBFBD><EFBFBD>
|
||||
#### Scenario: OpenAI 客户端 → Anthropic 供应商
|
||||
|
||||
- **WHEN** 客户端使用 OpenAI 协议且供应商使用 Anthropic 协议
|
||||
- **THEN** SHALL 将 OpenAI ChatCompletionRequest 解码为 CanonicalRequest
|
||||
- **THEN** SHALL 将 CanonicalRequest 编码为 Anthropic MessagesRequest
|
||||
- **THEN** SHALL 将 Anthropic MessagesResponse 解码为 CanonicalResponse
|
||||
- **THEN** SHALL 将 CanonicalResponse 编码为 OpenAI ChatCompletionResponse
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用 service 层处理请求
|
||||
|
||||
Handler SHALL 通过 service 层处理业务逻辑。
|
||||
|
||||
#### Scenario: 调用 routing service
|
||||
|
||||
- **WHEN** ProxyHandler 收到 Anthropic 协议请求
|
||||
- **THEN** SHALL 调用 RoutingService.Route() 获取路由结果
|
||||
- **THEN** SHALL 从路由结果获取 Provider（含 protocol 字段）
|
||||
|
||||
#### Scenario: 调用 stats service
|
||||
|
||||
- **WHEN** 请求成功完成
|
||||
- **THEN** SHALL 调用 StatsService.Record() 记录统计
|
||||
- **THEN** SHALL 异步记录统计（不阻塞响应）
|
||||
|
||||
### Requirement: 使用结构化错误处理
|
||||
|
||||
ProxyHandler SHALL 使用 ConversionError 和 Anthropic 的 encodeError 处理错误。
|
||||
|
||||
#### Scenario: 协议转换错误
|
||||
|
||||
- **WHEN** ConversionEngine 返回 ConversionError
|
||||
- **THEN** SHALL 使用 Anthropic 的 Adapter.encodeError 编码错误响应
|
||||
- **THEN** SHALL 使用 Anthropic 错误格式（`{type: "error", error: {type, message}}`）
|
||||
|
||||
#### Scenario: 路由错误处理
|
||||
|
||||
- **WHEN** RoutingService 返回错误
|
||||
- **THEN** SHALL 转换为 ConversionError
|
||||
- **THEN** SHALL 使用 Anthropic 错误格式返回
|
||||
|
||||
#### Scenario: 供应商错误处理
|
||||
|
||||
- **WHEN** ProviderClient 返回错误
|
||||
- **THEN** SHALL 包装为 ConversionError
|
||||
- **THEN** SHALL 使用 Anthropic 错误格式返回
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
# Config Management
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
统一配置管理系统，支持 YAML 配置文件、CLI 参数、环境变量和默认值四种配置源，提供优先级管理、来源追踪和配置验证。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 使用 YAML 配置文件
|
||||
|
||||
@@ -8,10 +12,16 @@
|
||||
|
||||
#### Scenario: 配置文件路径
|
||||
|
||||
- **WHEN** 应用启动
|
||||
- **WHEN** 应用启动且未指定 `--config` 参数
|
||||
- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
|
||||
- **THEN** SHALL 解析 YAML 格式
|
||||
|
||||
#### Scenario: 自定义配置文件路径
|
||||
|
||||
- **WHEN** 应用启动且指定 `--config /path/to/custom.yaml`
|
||||
- **THEN** SHALL 从指定路径加载配置文件
|
||||
- **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`
|
||||
|
||||
#### Scenario: 配置文件结构
|
||||
|
||||
- **WHEN** 加载配置文件
|
||||
@@ -24,14 +34,14 @@
|
||||
|
||||
#### Scenario: 配置文件不存在
|
||||
|
||||
- **WHEN** 应用启动且 `~/.nex/config.yaml` 不存在
|
||||
- **WHEN** 应用启动且配置文件不存在
|
||||
- **THEN** SHALL 自动创建配置文件
|
||||
- **THEN** SHALL 写入默认配置值
|
||||
- **THEN** SHALL 记录日志提示已创建
|
||||
|
||||
#### Scenario: 配置文件已存在
|
||||
|
||||
- **WHEN** 应用启动且 `~/.nex/config.yaml` 已存在
|
||||
- **WHEN** 应用启动且配置文件已存在
|
||||
- **THEN** SHALL 直接加载配置文件
|
||||
- **THEN** SHALL NOT 覆盖现有配置
|
||||
|
||||
@@ -49,8 +59,9 @@
|
||||
|
||||
- **WHEN** 加载配置
|
||||
- **THEN** SHALL 验证端口号范围（1-65535）
|
||||
- **THEN** SHALL 验证日志级别有效性
|
||||
- **THEN** SHALL 验证日志级别有效性（debug/info/warn/error）
|
||||
- **THEN** SHALL 验证路径有效性
|
||||
- **THEN** SHALL 验证数值范围（如 max_idle_conns ≥ 1）
|
||||
|
||||
#### Scenario: 配置错误处理
|
||||
|
||||
@@ -59,6 +70,21 @@
|
||||
- **THEN** SHALL 指示哪些字段无效
|
||||
- **THEN** SHALL 应用 SHALL NOT 启动
|
||||
|
||||
#### Scenario: 验证规则定义
|
||||
|
||||
- **WHEN** 定义配置结构体
|
||||
- **THEN** SHALL 使用 `validate` tag 定义验证规则
|
||||
- **THEN** SHALL 支持 `required` 规则
|
||||
- **THEN** SHALL 支持 `min`、`max` 规则
|
||||
- **THEN** SHALL 支持 `oneof` 规则
|
||||
|
||||
#### Scenario: 验证执行
|
||||
|
||||
- **WHEN** 加载配置后
|
||||
- **THEN** SHALL 自动执行结构体验证
|
||||
- **THEN** SHALL 返回验证错误
|
||||
- **THEN** SHALL NOT 启动应用（如果验证失败）
|
||||
|
||||
### Requirement: 配置结构定义
|
||||
|
||||
系统 SHALL 定义清晰的配置结构。
|
||||
@@ -110,14 +136,236 @@
|
||||
- **THEN** log.max_age SHALL 为 30 (days)
|
||||
- **THEN** log.compress SHALL 为 true
|
||||
|
||||
### Requirement: 配置重载支持
|
||||
### Requirement: 配置加载流程
|
||||
|
||||
系统 SHALL 支持配置重载（未来扩展）。
|
||||
系统 SHALL 实现标准化的配置加载流程。
|
||||
|
||||
#### Scenario: 配置热重载
|
||||
#### Scenario: 加载步骤
|
||||
|
||||
- **WHEN** 配置文件修改（未来功能）
|
||||
- **THEN** SHALL 支持重新加载配置
|
||||
- **THEN** SHALL 应用新配置到可动态调整的参数
|
||||
- **WHEN** 应用启动
|
||||
- **THEN** SHALL 按以下顺序加载配置：
|
||||
1. 解析 CLI 参数（获取 --config 路径）
|
||||
2. 初始化配置管理器
|
||||
3. 设置默认值
|
||||
4. 绑定 CLI 参数
|
||||
5. 绑定环境变量
|
||||
6. 读取配置文件
|
||||
7. 反序列化到结构体
|
||||
8. 验证配置
|
||||
9. 打印配置摘要
|
||||
|
||||
注：当前版本不支持，仅为未来扩展预留接口。
|
||||
#### Scenario: 加载失败处理
|
||||
|
||||
- **WHEN** 配置加载过程中发生错误
|
||||
- **THEN** SHALL 返回明确的错误信息
|
||||
- **THEN** SHALL 指示失败步骤
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
|
||||
### Requirement: 配置优先级管理
|
||||
|
||||
系统 SHALL 实现明确的配置优先级机制。
|
||||
|
||||
#### Scenario: 优先级顺序
|
||||
|
||||
- **WHEN** 同一配置项在多个配置源中设置
|
||||
- **THEN** SHALL 按以下优先级顺序（从高到低）：
|
||||
1. CLI 参数
|
||||
2. 环境变量
|
||||
3. 配置文件
|
||||
4. 默认值
|
||||
|
||||
#### Scenario: CLI 参数最高优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **AND** CLI 参数设置 `--server-port 8080`
|
||||
- **THEN** SHALL 使用 CLI 参数值 8080
|
||||
|
||||
#### Scenario: 环境变量次高优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用环境变量值 9000
|
||||
|
||||
#### Scenario: 配置文件次低优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 未设置环境变量
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用配置文件值 9826
|
||||
|
||||
#### Scenario: 默认值最低优先级
|
||||
|
||||
- **WHEN** 配置文件中未设置某配置项
|
||||
- **AND** 未设置环境变量
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用默认值
|
||||
|
||||
#### Scenario: 部分配置覆盖
|
||||
|
||||
- **WHEN** 配置文件设置完整配置
|
||||
- **AND** CLI 参数仅覆盖部分配置项
|
||||
- **THEN** SHALL 合并所有配置源
|
||||
- **THEN** SHALL 使用高优先级源覆盖指定项
|
||||
- **THEN** SHALL 保留其他配置源中的未覆盖项
|
||||
|
||||
#### Scenario: 配置项独立覆盖
|
||||
|
||||
- **WHEN** 仅通过 CLI 参数设置 `--server-port 9000`
|
||||
- **THEN** SHALL 仅覆盖 server.port 配置项
|
||||
- **THEN** SHALL NOT 影响其他配置项
|
||||
- **THEN** SHALL 其他配置项使用配置文件或默认值
|
||||
|
||||
#### Scenario: 启动后配置锁定
|
||||
|
||||
- **WHEN** 应用启动完成
|
||||
- **THEN** SHALL 锁定配置值
|
||||
- **THEN** SHALL NOT 支持运行时修改配置优先级
|
||||
- **THEN** SHALL NOT 支持运行时添加新配置源
|
||||
|
||||
### Requirement: 配置来源追踪
|
||||
|
||||
系统 SHALL 追踪每个配置值的来源，提供配置覆盖的透明信息。
|
||||
|
||||
#### Scenario: 来源记录
|
||||
|
||||
- **WHEN** 加载配置完成
|
||||
- **THEN** SHALL 记录每个配置项的来源（CLI/ENV/File/Default）
|
||||
- **THEN** SHALL 在配置摘要中显示来源信息
|
||||
|
||||
#### Scenario: 来源统计
|
||||
|
||||
- **WHEN** 打印配置摘要
|
||||
- **THEN** SHALL 统计来自 CLI 参数的配置项数量
|
||||
- **THEN** SHALL 统计来自环境变量的配置项数量
|
||||
- **THEN** SHALL 统计来自配置文件的配置项数量
|
||||
- **THEN** SHALL 统计使用默认值的配置项数量
|
||||
|
||||
#### Scenario: 覆盖提示
|
||||
|
||||
- **WHEN** CLI 参数覆盖配置文件值
|
||||
- **THEN** SHALL 在日志中记录覆盖信息
|
||||
- **THEN** SHALL 显示被覆盖的配置项名称
|
||||
|
||||
### Requirement: 配置摘要输出
|
||||
|
||||
系统 SHALL 在启动时输出配置摘要。
|
||||
|
||||
#### Scenario: 摘要内容
|
||||
|
||||
- **WHEN** 配置加载完成
|
||||
- **THEN** SHALL 打印关键配置项（端口、数据库路径、日志级别等）
|
||||
- **THEN** SHALL 打印配置文件路径
|
||||
- **THEN** SHALL 打印环境变量数量
|
||||
- **THEN** SHALL 打印 CLI 参数数量
|
||||
|
||||
#### Scenario: 摘要格式
|
||||
|
||||
- **WHEN** 打印配置摘要
|
||||
- **THEN** SHALL 使用清晰的格式化输出
|
||||
- **THEN** SHALL 使用分隔线和分组
|
||||
- **THEN** SHALL 易于阅读和理解
|
||||
|
||||
### Requirement: CLI 参数配置支持
|
||||
|
||||
系统 SHALL 支持通过命令行参数设置所有配置项。
|
||||
|
||||
#### Scenario: 基本参数解析
|
||||
|
||||
- **WHEN** 应用启动时传入命令行参数
|
||||
- **THEN** SHALL 解析所有 CLI 参数
|
||||
- **THEN** SHALL 将参数值应用到对应配置项
|
||||
|
||||
#### Scenario: 参数命名规范
|
||||
|
||||
- **WHEN** 使用命令行参数
|
||||
- **THEN** SHALL 使用 kebab-case 命名（如 `--server-port`）
|
||||
- **THEN** SHALL 保持完整的层次结构（如 `--database-max-idle-conns`）
|
||||
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `--database-max-idle-conns`）
|
||||
|
||||
#### Scenario: 参数类型支持
|
||||
|
||||
- **WHEN** 解析不同类型的参数
|
||||
- **THEN** SHALL 支持 int 类型（如 `--server-port 9000`）
|
||||
- **THEN** SHALL 支持 string 类型（如 `--database-path /data/nex.db`）
|
||||
- **THEN** SHALL 支持 duration 类型（如 `--server-read-timeout 60s`）
|
||||
- **THEN** SHALL 支持 bool 类型（如 `--log-compress`）
|
||||
|
||||
#### Scenario: 完整配置覆盖
|
||||
|
||||
- **WHEN** 使用服务器相关参数
|
||||
- **THEN** SHALL 支持 `--server-port`、`--server-read-timeout`、`--server-write-timeout`
|
||||
- **WHEN** 使用数据库相关参数
|
||||
- **THEN** SHALL 支持 `--database-path`、`--database-max-idle-conns`、`--database-max-open-conns`、`--database-conn-max-lifetime`
|
||||
- **WHEN** 使用日志相关参数
|
||||
- **THEN** SHALL 支持 `--log-level`、`--log-path`、`--log-max-size`、`--log-max-backups`、`--log-max-age`、`--log-compress`
|
||||
|
||||
#### Scenario: 参数帮助信息
|
||||
|
||||
- **WHEN** 使用 `--help` 参数
|
||||
- **THEN** SHALL 显示所有支持的参数
|
||||
- **THEN** SHALL 按功能分组展示参数（服务器、数据库、日志）
|
||||
- **THEN** SHALL 显示每个参数的默认值和说明
|
||||
|
||||
#### Scenario: 参数错误处理
|
||||
|
||||
- **WHEN** 传入无效的参数值（如 `--server-port abc`）
|
||||
- **THEN** SHALL 返回明确的错误信息，指示参数名称和期望类型
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
- **WHEN** 传入未定义的参数（如 `--unknown-param value`）
|
||||
- **THEN** SHALL 返回错误信息，指示未知参数名称
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
|
||||
### Requirement: 环境变量配置支持
|
||||
|
||||
系统 SHALL 支持通过环境变量设置所有配置项，符合 12-Factor App 原则。
|
||||
|
||||
#### Scenario: 环境变量读取
|
||||
|
||||
- **WHEN** 应用启动时存在环境变量
|
||||
- **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
|
||||
- **THEN** SHALL 将环境变量值应用到对应配置项
|
||||
|
||||
#### Scenario: 环境变量命名规范
|
||||
|
||||
- **WHEN** 使用环境变量配置
|
||||
- **THEN** SHALL 使用 `NEX_` 前缀
|
||||
- **THEN** SHALL 使用大写字母和下划线分隔（如 `NEX_SERVER_PORT`）
|
||||
- **THEN** SHALL 保持完整层次结构（如 `NEX_DATABASE_MAX_IDLE_CONNS`）
|
||||
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `NEX_DATABASE_MAX_IDLE_CONNS`）
|
||||
|
||||
#### Scenario: 环境变量类型转换
|
||||
|
||||
- **WHEN** 解析不同类型的环境变量
|
||||
- **THEN** SHALL 支持 int 类型（如 `NEX_SERVER_PORT=9000`）
|
||||
- **THEN** SHALL 支持 string 类型（如 `NEX_DATABASE_PATH=/data/nex.db`）
|
||||
- **THEN** SHALL 支持 duration 类型（如 `NEX_SERVER_READ_TIMEOUT=60s`）
|
||||
- **THEN** SHALL 支持 bool 类型（如 `NEX_LOG_COMPRESS=true`）
|
||||
|
||||
#### Scenario: 完整环境变量覆盖
|
||||
|
||||
- **WHEN** 设置服务器相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_SERVER_PORT`、`NEX_SERVER_READ_TIMEOUT`、`NEX_SERVER_WRITE_TIMEOUT`
|
||||
- **WHEN** 设置数据库相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_DATABASE_PATH`、`NEX_DATABASE_MAX_IDLE_CONNS`、`NEX_DATABASE_MAX_OPEN_CONNS`、`NEX_DATABASE_CONN_MAX_LIFETIME`
|
||||
- **WHEN** 设置日志相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_LOG_LEVEL`、`NEX_LOG_PATH`、`NEX_LOG_MAX_SIZE`、`NEX_LOG_MAX_BACKUPS`、`NEX_LOG_MAX_AGE`、`NEX_LOG_COMPRESS`
|
||||
|
||||
#### Scenario: 12-Factor App 合规
|
||||
|
||||
- **WHEN** 应用部署到不同环境
|
||||
- **THEN** SHALL 通过环境变量区分环境配置
|
||||
- **THEN** SHALL NOT 修改代码或配置文件
|
||||
- **WHEN** 配置包含敏感信息（如密钥、密码）
|
||||
- **THEN** SHALL 通过环境变量传递
|
||||
- **THEN** SHALL NOT 存储在配置文件中
|
||||
|
||||
#### Scenario: 环境变量错误处理
|
||||
|
||||
- **WHEN** 环境变量值格式无效（如 `NEX_SERVER_PORT=abc`）
|
||||
- **THEN** SHALL 返回明确的错误信息，指示环境变量名称和期望类型
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
- **WHEN** 必需配置项既无配置文件也无环境变量
|
||||
- **THEN** SHALL 使用默认值
|
||||
- **THEN** SHALL 正常启动应用
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Conversion Engine
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
定义协议无关的 Canonical Model 和 ConversionEngine 转换引擎，作为所有协议间请求/响应转换的统一枢纽。
|
||||
|
||||
### Requirement: 定义 CanonicalRequest 规范模型
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Database Migration
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
使用 goose 管理数据库迁移，支持自动执行、回滚和版本化管理。
|
||||
|
||||
### Requirement: 使用 goose 迁移工具
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Error Handling
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
定义结构化错误类型和统一错误响应机制，支持错误包装、类型安全判断和协议级错误编码，确保全链路错误处理的一致性和可追踪性。
|
||||
|
||||
### Requirement: 定义结构化错误类型
|
||||
|
||||
@@ -169,8 +171,6 @@
|
||||
- **THEN** SHALL 使用 errors.Is 进行链式判断
|
||||
- **THEN** SHALL 使用 errors.As 提取特定类型错误
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 定义 ConversionError 错误类型
|
||||
|
||||
系统 SHALL 定义 ConversionError 结构体和 ErrorCode 枚举。
|
||||
|
||||
@@ -1,213 +0,0 @@
|
||||
# 前端测试体系
|
||||
|
||||
## Purpose
|
||||
|
||||
建立前端测试体系，覆盖单元测试、组件测试和 E2E 测试，确保前端代码质量和功能正确性。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 建立前端单元测试体系
|
||||
|
||||
前端 SHALL 使用 Vitest 建立单元测试体系，覆盖 API 层和自定义 Hooks。
|
||||
|
||||
#### Scenario: API 客户端单测
|
||||
|
||||
- **WHEN** 运行 api/client.ts 的单元测试
|
||||
- **THEN** SHALL 覆盖 request<T>() 的正常响应解析
|
||||
- **THEN** SHALL 覆盖 HTTP 错误状态码（4xx、5xx）的 ApiError 抛出
|
||||
- **THEN** SHALL 覆盖网络错误的错误处理
|
||||
- **THEN** SHALL 覆盖 snake_case → camelCase 响应字段转换
|
||||
- **THEN** SHALL 覆盖 camelCase → snake_case 请求字段转换
|
||||
|
||||
#### Scenario: API 模块单测
|
||||
|
||||
- **WHEN** 运行 api/providers.ts、api/models.ts、api/stats.ts 的单元测试
|
||||
- **THEN** SHALL 覆盖所有 CRUD 函数的正确调用
|
||||
- **THEN** SHALL 覆盖参数传递和返回值类型
|
||||
|
||||
#### Scenario: 自定义 Hooks 单测
|
||||
|
||||
- **WHEN** 运行 hooks/ 目录下的单元测试
|
||||
- **THEN** SHALL 使用 @tanstack/react-query 的 renderHook 测试工具
|
||||
- **THEN** SHALL 覆盖 useQuery 数据获取（成功和失败）
|
||||
- **THEN** SHALL 覆盖 useMutation 写操作后的缓存失效
|
||||
- **THEN** SHALL 使用独立的测试 QueryClient（关闭 retry 和缓存）
|
||||
|
||||
### Requirement: 建立前端组件测试体系
|
||||
|
||||
前端 SHALL 使用 React Testing Library 建立组件测试体系。
|
||||
|
||||
#### Scenario: ProviderTable 组件测试
|
||||
|
||||
- **WHEN** 运行 ProviderTable 组件测试
|
||||
- **THEN** SHALL 验证供应商列表正确渲染
|
||||
- **THEN** SHALL 验证点击"添加"按钮弹出 Modal
|
||||
- **THEN** SHALL 验证点击"编辑"按钮弹出预填充的 Modal
|
||||
- **THEN** SHALL 验证删除操作触发 Popconfirm 确认
|
||||
|
||||
#### Scenario: ProviderForm 组件测试
|
||||
|
||||
- **WHEN** 运行 ProviderForm 组件测试
|
||||
- **THEN** SHALL 验证表单校验规则（必填字段、URL 格式）
|
||||
- **THEN** SHALL 验证提交成功后调用 onSave 回调
|
||||
- **THEN** SHALL 验证编辑模式下字段预填充
|
||||
|
||||
#### Scenario: StatsTable 组件测试
|
||||
|
||||
- **WHEN** 运行 StatsTable 组件测试
|
||||
- **THEN** SHALL 验证筛选条件交互（供应商选择、日期范围）
|
||||
- **THEN** SHALL 验证统计数据正确展示
|
||||
|
||||
### Requirement: 建立 E2E 测试体系
|
||||
|
||||
前端 SHALL 使用 Playwright 建立端到端测试体系。
|
||||
|
||||
#### Scenario: 供应商管理 E2E 测试
|
||||
|
||||
- **WHEN** 运行供应商管理的 E2E 测试
|
||||
- **THEN** SHALL 测试完整的供应商创建流程
|
||||
- **THEN** SHALL 测试供应商编辑流程
|
||||
- **THEN** SHALL 测试供应商删除流程（含确认弹窗）
|
||||
- **THEN** SHALL 测试供应商展开后的模型管理
|
||||
|
||||
#### Scenario: 统计查询 E2E 测试
|
||||
|
||||
- **WHEN** 运行统计查询的 E2E 测试
|
||||
- **THEN** SHALL 测试页面加载和默认数据展示
|
||||
- **THEN** SHALL 测试按供应商筛选
|
||||
- **THEN** SHALL 测试按日期范围筛选
|
||||
|
||||
### Requirement: 使用 MSW 进行 API Mock
|
||||
|
||||
前端测试 SHALL 使用 MSW (Mock Service Worker) 模拟后端 API 响应。
|
||||
|
||||
#### Scenario: 测试环境 MSW 配置
|
||||
|
||||
- **WHEN** 初始化测试环境
|
||||
- **THEN** SHALL 配置 MSW server 处理所有 /api/* 请求
|
||||
- **THEN** SHALL 在 setup.ts 中全局启动和清理 MSW server
|
||||
|
||||
#### Scenario: Mock 响应定义
|
||||
|
||||
- **WHEN** 编写需要 API 交互的测试
|
||||
- **THEN** SHALL 使用 MSW handler 定义期望的 API 响应
|
||||
- **THEN** SHALL 支持成功和失败两种响应场景
|
||||
- **THEN** SHALL 在每个测试用例后重置 handler
|
||||
|
||||
### Requirement: 测试文件组织
|
||||
|
||||
前端测试文件 SHALL 按层级组织在 src/__tests__/ 目录下。
|
||||
|
||||
#### Scenario: 目录结构
|
||||
|
||||
- **WHEN** 组织测试文件
|
||||
- **THEN** src/__tests__/setup.ts SHALL 包含全局测试配置
|
||||
- **THEN** src/__tests__/api/ SHALL 包含 API 层单测
|
||||
- **THEN** src/__tests__/hooks/ SHALL 包含 Hooks 单测
|
||||
- **THEN** src/__tests__/components/ SHALL 包含组件测试
|
||||
- **THEN** e2e/ 目录（项目根目录下）SHALL 包含 Playwright E2E 测试
|
||||
|
||||
### Requirement: Vitest 配置
|
||||
|
||||
前端 SHALL 配置 Vitest 作为测试运行器。
|
||||
|
||||
#### Scenario: 测试环境配置
|
||||
|
||||
- **WHEN** 运行 vitest
|
||||
- **THEN** SHALL 使用 jsdom 作为测试环境
|
||||
- **THEN** SHALL 配置 setupFiles 指向 src/__tests__/setup.ts
|
||||
- **THEN** SHALL 配置路径别名 @/ 与 tsconfig 一致
|
||||
- **THEN** SHALL 配置 @testing-library/jest-dom 匹配器
|
||||
|
||||
#### Scenario: 覆盖率配置
|
||||
|
||||
- **WHEN** 运行覆盖率报告
|
||||
- **THEN** SHALL 使用 @vitest/coverage-v8 提供者
|
||||
- **THEN** SHALL 覆盖 src/ 下的所有源文件
|
||||
|
||||
### Requirement: 建立前端单元测试覆盖
|
||||
|
||||
前端代码 SHALL 建立单元测试覆盖，纳入整体测试覆盖率统计。
|
||||
|
||||
#### Scenario: API 层测试覆盖
|
||||
|
||||
- **WHEN** 运行前端 API 层的单元测试
|
||||
- **THEN** SHALL 覆盖 api/client.ts 的请求封装和字段转换逻辑
|
||||
- **THEN** SHALL 覆盖 api/providers.ts、api/models.ts、api/stats.ts 的所有函数
|
||||
- **THEN** SHALL 使用 MSW mock API 响应
|
||||
|
||||
#### Scenario: Hooks 测试覆盖
|
||||
|
||||
- **WHEN** 运行前端 Hooks 的单元测试
|
||||
- **THEN** SHALL 覆盖 useProviders、useModels、useStats 的查询和变更逻辑
|
||||
- **THEN** SHALL 验证缓存失效和自动刷新行为
|
||||
|
||||
### Requirement: 统计仪表盘组件测试
|
||||
|
||||
前端 SHALL 为统计仪表盘的新增组件建立测试覆盖。
|
||||
|
||||
#### Scenario: StatCards 组件测试
|
||||
|
||||
- **WHEN** 运行 StatCards 组件测试
|
||||
- **THEN** SHALL 验证统计数据正确渲染（总请求量、活跃模型数、活跃供应商数、今日请求量）
|
||||
- **THEN** SHALL 验证空数据时的渲染行为
|
||||
|
||||
#### Scenario: UsageChart 组件测试
|
||||
|
||||
- **WHEN** 运行 UsageChart 组件测试
|
||||
- **THEN** SHALL 验证图表组件正确渲染
|
||||
- **THEN** SHALL 验证空数据时的渲染行为
|
||||
|
||||
### Requirement: 建立前端组件测试覆盖
|
||||
|
||||
前端 SHALL 使用 React Testing Library 建立组件测试覆盖。
|
||||
|
||||
#### Scenario: 页面组件测试覆盖
|
||||
|
||||
- **WHEN** 运行前端组件测试
|
||||
- **THEN** SHALL 覆盖 ProviderTable 的列表渲染和交互操作
|
||||
- **THEN** SHALL 覆盖 ProviderForm 的表单校验和提交
|
||||
- **THEN** SHALL 覆盖 ModelForm 的表单校验和提交
|
||||
- **THEN** SHALL 覆盖 StatsTable 的筛选和数据展示
|
||||
- **THEN** SHALL 覆盖 StatCards 的统计摘要渲染
|
||||
- **THEN** SHALL 覆盖 UsageChart 的趋势图表渲染
|
||||
|
||||
### Requirement: 建立前端 E2E 测试覆盖
|
||||
|
||||
前端 SHALL 使用 Playwright 建立 E2E 测试覆盖。
|
||||
|
||||
#### Scenario: 供应商管理 E2E 覆盖
|
||||
|
||||
- **WHEN** 运行 E2E 测试
|
||||
- **THEN** SHALL 覆盖供应商创建、编辑、删除的完整用户流程
|
||||
- **THEN** SHALL 覆盖模型创建、编辑、删除的完整用户流程
|
||||
|
||||
#### Scenario: 统计查询 E2E 覆盖
|
||||
|
||||
- **WHEN** 运行 E2E 测试
|
||||
- **THEN** SHALL 覆盖统计页面的加载和筛选查询流程
|
||||
- **THEN** SHALL 覆盖页面间的导航切换
|
||||
- **THEN** SHALL 覆盖统计摘要卡片的展示
|
||||
|
||||
#### Scenario: 侧边栏导航 E2E 覆盖
|
||||
|
||||
- **WHEN** 运行 E2E 测试
|
||||
- **THEN** SHALL 覆盖侧边栏菜单导航的页面切换
|
||||
- **THEN** SHALL 覆盖侧边栏折叠和展开操作
|
||||
|
||||
### Requirement: 前端测试集成到构建流程
|
||||
|
||||
前端测试 SHALL 集成到项目的构建和验证流程中。
|
||||
|
||||
#### Scenario: 运行前端测试命令
|
||||
|
||||
- **WHEN** 在 frontend/ 目录执行测试命令
|
||||
- **THEN** SHALL 运行所有 Vitest 单元测试和组件测试
|
||||
- **THEN** SHALL 显示测试结果
|
||||
- **THEN** SHALL 在测试失败时返回非零退出码
|
||||
|
||||
#### Scenario: 运行前端 E2E 测试命令
|
||||
|
||||
- **WHEN** 在 frontend/ 目录执行 E2E 测试命令
|
||||
- **THEN** SHALL 启动 Playwright 运行 E2E 测试
|
||||
- **THEN** SHALL 在测试失败时返回非零退出码
|
||||
@@ -138,6 +138,20 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
|
||||
- **THEN** 前端 SHALL 自动查询并过滤统计
|
||||
- **THEN** 统计摘要卡片和趋势图表 SHALL 同步更新
|
||||
|
||||
#### Scenario: 仪表盘区域排列
|
||||
|
||||
- **WHEN** 渲染统计页面
|
||||
- **THEN** 页面 SHALL 按以下顺序从上到下排列：统计摘要卡片、趋势图表、筛选栏和数据表格
|
||||
- **THEN** 各区域之间 SHALL 有合理的垂直间距
|
||||
- **THEN** 筛选栏和数据表格 SHALL 保持在同一个卡片中
|
||||
|
||||
#### Scenario: 数据联动
|
||||
|
||||
- **WHEN** 用户通过筛选栏修改筛选条件
|
||||
- **THEN** 统计摘要卡片和趋势图表 SHALL 随筛选条件变化更新
|
||||
- **THEN** 数据表格 SHALL 同步更新
|
||||
- **THEN** 所有区域 SHALL 共享同一份筛选后的数据
|
||||
|
||||
### Requirement: 优雅处理 API 错误
|
||||
|
||||
前端 SHALL 处理 API 错误并显示用户友好的消息。
|
||||
@@ -224,13 +238,6 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
|
||||
- **WHEN** 用户点击导航中的"设置"
|
||||
- **THEN** 前端 SHALL 导航到 `/settings` 并高亮当前菜单项
|
||||
|
||||
#### Scenario: 导航菜单交互
|
||||
|
||||
- **WHEN** 用户点击导航中的"供应商管理"
|
||||
- **THEN** 前端 SHALL 导航到 `/providers` 并高亮当前菜单项
|
||||
- **WHEN** 用户点击导航中的"用量统计"
|
||||
- **THEN** 前端 SHALL 导航到 `/stats` 并高亮当前菜单项
|
||||
|
||||
### Requirement: 提供导航
|
||||
|
||||
前端 SHALL 使用 React Router v7 提供导航。
|
||||
@@ -1,6 +1,8 @@
|
||||
# Layered Architecture
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
实现 handler → service → repository 三层架构，并在 handler 和 provider 之间新增 conversion 层，通过依赖注入和清晰的接口边界提高代码可维护性和可测试性。
|
||||
|
||||
### Requirement: 实现三层架构
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Middleware System
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
实现 HTTP 中间件体系，包括请求 ID、日志记录、错误恢复和 CORS 处理，确保请求的可追踪性、稳定性和跨域支持。
|
||||
|
||||
### Requirement: 实现请求 ID 中间件
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Model Management
|
||||
|
||||
## MODIFIED Requirements
|
||||
## Purpose
|
||||
|
||||
管理模型的增删改查，通过 handler → service → repository 分层实现业务逻辑和数据访问，支持供应商关联验证。
|
||||
|
||||
### Requirement: 创建模型配置
|
||||
|
||||
@@ -74,8 +76,6 @@
|
||||
|
||||
**变更说明：** 通过 ModelService 和 ModelRepository 实现。API 接口保持不变。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用 service 层处理业务逻辑
|
||||
|
||||
Handler SHALL 通过 ModelService 处理业务逻辑。
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
# OpenAI Protocol Proxy
|
||||
|
||||
## MODIFIED Requirements
|
||||
## Purpose
|
||||
|
||||
定义 OpenAI Chat Completions API 端点的协议代理行为，包括请求处理流程、模型路由、同协议透传和跨协议转换。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 支持 OpenAI Chat Completions API 端点
|
||||
|
||||
@@ -47,9 +51,9 @@
|
||||
- **WHEN** 请求包含已禁用模型的 `model` 字段
|
||||
- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
|
||||
|
||||
### Requirement: 对 OpenAI 兼容供应商透明代理
|
||||
### Requirement: 跨协议请求转换
|
||||
|
||||
网关 SHALL 对 OpenAI 兼容供应商的请求和响应通过 ConversionEngine 进行转换处理。
|
||||
网关 SHALL 对非 OpenAI 兼容供应商的请求和响应通过 ConversionEngine 进行转换处理。
|
||||
|
||||
#### Scenario: 跨协议请求转发
|
||||
|
||||
@@ -61,59 +65,3 @@
|
||||
|
||||
- **WHEN** 网关收到 `/openai/v1/models` 等 GET 请求
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 转换扩展层接口的响应格式
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用 service 层处理请求
|
||||
|
||||
Handler SHALL 通过 service 层处理业务逻辑。
|
||||
|
||||
#### Scenario: 调用 routing service
|
||||
|
||||
- **WHEN** handler 收到请求
|
||||
- **THEN** SHALL 调用 RoutingService.Route() 获取路由结果
|
||||
- **THEN** SHALL 使用路由结果中的供应商信息
|
||||
|
||||
#### Scenario: 调用 stats service
|
||||
|
||||
- **WHEN** 请求成功完成
|
||||
- **THEN** SHALL 调用 StatsService.Record() 记录统计
|
||||
- **THEN** SHALL 异步记录统计（不阻塞响应）
|
||||
|
||||
### Requirement: 使用 service 层处理请求
|
||||
|
||||
Handler SHALL 通过 service 层处理业务逻辑。
|
||||
|
||||
#### Scenario: 调用 routing service
|
||||
|
||||
- **WHEN** ProxyHandler 收到请求
|
||||
- **THEN** SHALL 调用 RoutingService.Route() 获取路由结果
|
||||
- **THEN** SHALL 从路由结果获取 Provider（含 protocol 字段）
|
||||
|
||||
#### Scenario: 调用 stats service
|
||||
|
||||
- **WHEN** 请求成功完成
|
||||
- **THEN** SHALL 调用 StatsService.Record() 记录统计
|
||||
- **THEN** SHALL 异步记录统计（不阻塞响应）
|
||||
|
||||
### Requirement: 使用结构化错误处理
|
||||
|
||||
ProxyHandler SHALL 使用 ConversionError 和协议对应的 encodeError 处理错误。
|
||||
|
||||
#### Scenario: 转换错误
|
||||
|
||||
- **WHEN** ConversionEngine 返回 ConversionError
|
||||
- **THEN** SHALL 使用 clientProtocol 的 Adapter.encodeError 编码错误响应
|
||||
- **THEN** SHALL 使用 OpenAI 错误格式（`{error: {message, type, code}}`）
|
||||
|
||||
#### Scenario: 路由错误处理
|
||||
|
||||
- **WHEN** RoutingService 返回错误
|
||||
- **THEN** SHALL 转换为 ConversionError
|
||||
- **THEN** SHALL 使用 OpenAI 错误格式返回
|
||||
|
||||
#### Scenario: 供应商错误处理
|
||||
|
||||
- **WHEN** ProviderClient 返回错误
|
||||
- **THEN** SHALL 包装为 ConversionError
|
||||
- **THEN** SHALL 使用 OpenAI 错误格式返回
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Protocol Adapter - Anthropic
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
实现 Anthropic 协议的完整 ProtocolAdapter，支持请求/响应编解码、流式转换和错误处理，遵循 Anthropic Messages API 规范。
|
||||
|
||||
### Requirement: 实现 Anthropic ProtocolAdapter
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Protocol Adapter - OpenAI
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
实现 OpenAI 协议的完整 ProtocolAdapter，支持请求/响应编解码、流式转换和错误处理，遵循 OpenAI Chat Completions API 规范。
|
||||
|
||||
### Requirement: 实现 OpenAI ProtocolAdapter
|
||||
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
# Provider Management
|
||||
|
||||
## MODIFIED Requirements
|
||||
## Purpose
|
||||
|
||||
管理 AI 供应商的完整生命周期，包括创建、查询、更新、删除供应商配置，通过分层架构（Handler -> Service -> Repository）处理业务逻辑和数据访问。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 创建供应商配置
|
||||
|
||||
@@ -84,8 +88,6 @@
|
||||
|
||||
**变更说明：** 通过 ProviderService 和 ProviderRepository 实现。API 接口保持不变。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用 service 层处理业务逻辑
|
||||
|
||||
Handler SHALL 通过 ProviderService 处理业务逻辑。
|
||||
|
||||
@@ -1,114 +0,0 @@
|
||||
# Recharts Integration
|
||||
|
||||
## Purpose
|
||||
|
||||
TBD - 集成Recharts图表库，实现数据可视化功能，替代@ant-design/charts。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Recharts依赖集成
|
||||
系统SHALL正确集成Recharts图表库，作为数据可视化的基础依赖。
|
||||
|
||||
#### Scenario: 安装Recharts依赖
|
||||
- **WHEN** 依赖安装完成
|
||||
- **THEN** package.json中SHALL存在recharts依赖
|
||||
- **AND** recharts版本SHALL为2.x最新稳定版
|
||||
- **AND** Recharts组件SHALL可正常导入使用
|
||||
|
||||
### Requirement: UsageChart图表重写
|
||||
系统SHALL使用Recharts重新实现UsageChart组件，保持原有功能。
|
||||
|
||||
#### Scenario: 折线图渲染
|
||||
- **WHEN** UsageChart组件接收统计数据
|
||||
- **THEN** SHALL使用Recharts的LineChart组件渲染
|
||||
- **AND** X轴SHALL显示日期数据
|
||||
- **AND** Y轴SHALL显示请求数据
|
||||
- **AND** 图表SHALL支持鼠标悬停显示详情（Tooltip）
|
||||
- **AND** 图表SHALL包含网格线（CartesianGrid）
|
||||
|
||||
#### Scenario: 响应式图表容器
|
||||
- **WHEN** 图表渲染
|
||||
- **THEN** SHALL使用ResponsiveContainer包裹
|
||||
- **AND** 图表宽度SHALL自适应容器宽度
|
||||
- **AND** 图表高度SHALL为固定300px
|
||||
|
||||
#### Scenario: 空数据状态处理
|
||||
- **WHEN** 统计数据为空数组
|
||||
- **THEN** SHALL显示"暂无数据"提示
|
||||
- **AND** 不SHALL渲染图表组件
|
||||
|
||||
#### Scenario: 数据格式转换
|
||||
- **WHEN** 接收UsageStats数组数据
|
||||
- **THEN** SHALL按日期聚合计数
|
||||
- **AND** 数据SHALL按日期升序排序
|
||||
- **AND** 数据格式SHALL适配Recharts要求
|
||||
|
||||
### Requirement: 图表样式配置
|
||||
系统SHALL配置Recharts图表样式，确保视觉一致性。
|
||||
|
||||
#### Scenario: 图表颜色配置
|
||||
- **WHEN** 图表渲染
|
||||
- **THEN** 折线颜色SHALL为TDesign主色（#0052D9）
|
||||
- **AND** 线条宽度SHALL为2px
|
||||
- **AND** 数据点样式SHALL正常显示
|
||||
|
||||
#### Scenario: 网格线配置
|
||||
- **WHEN** 图表渲染
|
||||
- **THEN** 网格线SHALL使用虚线样式（strokeDasharray="3 3"）
|
||||
- **AND** 网格线SHALL不遮挡数据线
|
||||
|
||||
### Requirement: 移除Ant Design Charts
|
||||
系统SHALL完全移除@ant-design/charts的使用。
|
||||
|
||||
#### Scenario: 移除Line组件
|
||||
- **WHEN** 迁移完成
|
||||
- **THEN** UsageChart中SHALL不存在@ant-design/charts的Line组件
|
||||
- **AND** UsageChart中SHALL不存在任何@ant-design/charts导入
|
||||
|
||||
#### Scenario: 移除配置对象模式
|
||||
- **WHEN** 图表实现
|
||||
- **THEN** SHALL使用Recharts声明式组件模式
|
||||
- **AND** 不SHALL使用Ant Design Charts的配置对象模式（xField、yField等）
|
||||
|
||||
### Requirement: 图表交互功能
|
||||
系统SHALL保持图表的基本交互功能。
|
||||
|
||||
#### Scenario: 鼠标悬停提示
|
||||
- **WHEN** 用户鼠标悬停在数据点上
|
||||
- **THEN** SHALL显示Tooltip提示框
|
||||
- **AND** 提示框SHALL显示日期和请求数
|
||||
- **AND** 提示框SHALL不遮挡图表内容
|
||||
|
||||
#### Scenario: 平滑曲线效果
|
||||
- **WHEN** 折线渲染
|
||||
- **THEN** SHALL使用monotone类型平滑曲线
|
||||
- **AND** 曲线SHALL自然流畅
|
||||
- **AND** 数据点SHALL准确对应
|
||||
|
||||
### Requirement: 图表性能
|
||||
系统SHALL确保图表渲染性能满足要求。
|
||||
|
||||
#### Scenario: 大数据量渲染
|
||||
- **WHEN** 统计数据包含大量数据点（>100）
|
||||
- **THEN** 图表SHALL在1秒内完成渲染
|
||||
- **AND** 交互响应SHALL流畅无卡顿
|
||||
|
||||
#### Scenario: 组件重渲染优化
|
||||
- **WHEN** 父组件重新渲染
|
||||
- **THEN** 图表组件SHALL避免不必要的重渲染
|
||||
- **AND** 数据未变化时SHALL保持稳定
|
||||
|
||||
### Requirement: 图表测试覆盖
|
||||
系统SHALL为Recharts图表组件提供完整的测试覆盖。
|
||||
|
||||
#### Scenario: 组件渲染测试
|
||||
- **WHEN** 运行单元测试
|
||||
- **THEN** UsageChart测试SHALL验证正常渲染
|
||||
- **AND** UsageChart测试SHALL验证空数据状态
|
||||
- **AND** UsageChart测试SHALL验证数据格式转换
|
||||
|
||||
#### Scenario: 数据处理测试
|
||||
- **WHEN** 运行单元测试
|
||||
- **THEN** 测试SHALL覆盖日期聚合逻辑
|
||||
- **AND** 测试SHALL覆盖数据排序逻辑
|
||||
- **AND** 测试SHALL验证边界情况
|
||||
@@ -1,6 +1,10 @@
|
||||
# Request Validation
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
定义请求验证规范，覆盖 AI 协议请求（OpenAI、Anthropic）和管理 API 请求的验证规则，确保输入数据的合法性和安全性。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 使用 validator 库
|
||||
|
||||
|
||||
@@ -1,77 +0,0 @@
|
||||
# 统计仪表盘
|
||||
|
||||
## Purpose
|
||||
|
||||
TBD - 提供统计仪表盘页面，展示统计摘要卡片、请求趋势图表和详细数据表格
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 提供统计摘要卡片
|
||||
|
||||
前端 SHALL 在统计页面顶部展示统计摘要卡片行，展示关键指标的聚合数据。
|
||||
|
||||
#### Scenario: 显示统计摘要
|
||||
|
||||
- **WHEN** 加载统计页面
|
||||
- **THEN** 前端 SHALL 在页面顶部使用 Ant Design `Row` + `Col` 栅格布局展示统计卡片
|
||||
- **THEN** 每个卡片 SHALL 使用 Ant Design `Card` + `Statistic` 组件
|
||||
- **THEN** 卡片 SHALL 展示以下指标：总请求量、活跃模型数、活跃供应商数、今日请求量
|
||||
- **THEN** 指标数据 SHALL 从 `useStats` 返回的 `UsageStats[]` 数据中前端聚合计算
|
||||
|
||||
#### Scenario: 统计数据聚合计算
|
||||
|
||||
- **WHEN** 前端接收到 stats 数据
|
||||
- **THEN** 总请求量 SHALL 为所有记录的 requestCount 之和
|
||||
- **THEN** 活跃模型数 SHALL 为去重后不同 modelName 的数量
|
||||
- **THEN** 活跃供应商数 SHALL 为去重后不同 providerId 的数量
|
||||
- **THEN** 今日请求量 SHALL 为 date 等于当日日期的记录的 requestCount 之和
|
||||
|
||||
#### Scenario: 统计卡片响应式布局
|
||||
|
||||
- **WHEN** 在不同屏幕宽度下查看统计卡片
|
||||
- **THEN** 卡片 SHALL 使用 Ant Design `Col` 的响应式 span 适配不同宽度
|
||||
- **THEN** 卡片之间 SHALL 有合理的间距（Row 的 gutter）
|
||||
|
||||
### Requirement: 提供请求趋势图表
|
||||
|
||||
前端 SHALL 在统计页面展示请求量随时间变化的趋势图表。
|
||||
|
||||
#### Scenario: 显示趋势图表
|
||||
|
||||
- **WHEN** 加载统计页面
|
||||
- **THEN** 前端 SHALL 在统计摘要卡片下方展示趋势图表
|
||||
- **THEN** 图表 SHALL 使用 `@ant-design/charts` 的 `Line` 组件
|
||||
- **THEN** 图表 SHALL 包裹在 Ant Design `Card` 组件中
|
||||
- **THEN** 图表 SHALL 展示请求量随日期的变化趋势
|
||||
|
||||
#### Scenario: 图表数据格式
|
||||
|
||||
- **WHEN** 准备图表数据
|
||||
- **THEN** X 轴 SHALL 为日期（date 字段）
|
||||
- **THEN** Y 轴 SHALL 为请求计数（requestCount）
|
||||
- **THEN** 数据 SHALL 按日期聚合，同一天的请求量求和
|
||||
- **THEN** 数据 SHALL 按日期升序排列
|
||||
|
||||
#### Scenario: 图表主题适配
|
||||
|
||||
- **WHEN** 用户切换亮色/暗色主题
|
||||
- **THEN** 图表 SHALL 自动适配当前主题
|
||||
- **THEN** 图表文字和背景 SHALL 与当前主题协调
|
||||
|
||||
### Requirement: 仪表盘页面布局
|
||||
|
||||
前端 SHALL 将统计页面组织为仪表盘布局，按从上到下的顺序排列各区域。
|
||||
|
||||
#### Scenario: 仪表盘区域排列
|
||||
|
||||
- **WHEN** 渲染统计页面
|
||||
- **THEN** 页面 SHALL 按以下顺序从上到下排列：统计摘要卡片、趋势图表、筛选栏和数据表格
|
||||
- **THEN** 各区域之间 SHALL 有合理的垂直间距
|
||||
- **THEN** 筛选栏和数据表格 SHALL 保持在同一个 `Card` 中
|
||||
|
||||
#### Scenario: 数据联动
|
||||
|
||||
- **WHEN** 用户通过筛选栏修改筛选条件
|
||||
- **THEN** 统计摘要卡片和趋势图表 SHALL 随筛选条件变化更新
|
||||
- **THEN** 数据表格 SHALL 同步更新
|
||||
- **THEN** 所有区域 SHALL 共享同一份筛选后的数据
|
||||
@@ -1,6 +1,10 @@
|
||||
# Structured Logging
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
定义结构化日志规范，使用 zap 日志库提供 JSON 格式日志输出、日志文件滚动、请求 ID 追踪和多级别日志控制。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 使用 zap 结构化日志
|
||||
|
||||
|
||||
@@ -1,122 +0,0 @@
|
||||
# TDesign Integration
|
||||
|
||||
## Purpose
|
||||
|
||||
TBD - 集成TDesign React组件库，提供统一的UI设计系统和组件支持，替代Ant Design。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: TDesign全局配置
|
||||
系统SHALL正确配置TDesign ConfigProvider作为全局配置容器，确保所有TDesign组件使用统一的配置。
|
||||
|
||||
#### Scenario: 应用启动时加载TDesign配置
|
||||
- **WHEN** 应用初始化启动
|
||||
- **THEN** ConfigProvider组件SHALL包裹整个应用
|
||||
- **AND** TDesign全局样式SHALL被正确引入
|
||||
- **AND** 所有TDesign组件SHALL使用统一配置
|
||||
|
||||
#### Scenario: 移除Ant Design配置
|
||||
- **WHEN** 迁移完成
|
||||
- **THEN** 应用中SHALL不存在Ant Design的ConfigProvider
|
||||
- **AND** 应用中SHALL不存在ThemeProvider
|
||||
- **AND** 应用中SHALL不存在任何Ant Design全局配置
|
||||
|
||||
### Requirement: TDesign组件替换
|
||||
系统SHALL将所有Ant Design组件替换为对应的TDesign组件，保持功能完整性。
|
||||
|
||||
#### Scenario: 布局组件替换
|
||||
- **WHEN** 使用Layout组件
|
||||
- **THEN** SHALL使用TDesign的Layout组件
|
||||
- **AND** Layout.Sider SHALL替换为Layout.Aside
|
||||
- **AND** Layout.Header SHALL保持不变
|
||||
- **AND** Layout.Content SHALL保持不变
|
||||
|
||||
#### Scenario: 表单组件替换
|
||||
- **WHEN** 使用表单相关组件
|
||||
- **THEN** Modal SHALL替换为Dialog
|
||||
- **AND** Form.Item SHALL替换为Form.FormItem
|
||||
- **AND** Input、Select、Switch SHALL使用TDesign版本
|
||||
- **AND** 表单验证功能SHALL保持完整
|
||||
|
||||
#### Scenario: 数据展示组件替换
|
||||
- **WHEN** 使用数据展示组件
|
||||
- **THEN** Table、Card、Statistic、Tag SHALL使用TDesign版本
|
||||
- **AND** 组件功能SHALL保持不变
|
||||
- **AND** 组件API SHALL兼容原有使用方式
|
||||
|
||||
#### Scenario: 导航组件替换
|
||||
- **WHEN** 使用导航组件
|
||||
- **THEN** Menu SHALL使用TDesign版本
|
||||
- **AND** 菜单项配置SHALL正确映射
|
||||
- **AND** 路由导航功能SHALL保持正常
|
||||
|
||||
### Requirement: TDesign图标系统
|
||||
系统SHALL使用tdesign-icons-react作为图标库，替换@ant-design/icons。
|
||||
|
||||
#### Scenario: 图标导入替换
|
||||
- **WHEN** 使用图标组件
|
||||
- **THEN** SHALL从tdesign-icons-react导入
|
||||
- **AND** SHALL不从@ant-design/icons导入任何图标
|
||||
- **AND** 图标显示SHALL正常
|
||||
|
||||
#### Scenario: 图标语义匹配
|
||||
- **WHEN** 替换图标
|
||||
- **THEN** 新图标SHALL与原图标语义相近
|
||||
- **AND** CloudServerOutlined SHALL替换为语义相近的TDesign图标
|
||||
- **AND** BarChartOutlined SHALL替换为语义相近的TDesign图标
|
||||
- **AND** SettingOutlined SHALL替换为语义相近的TDesign图标
|
||||
|
||||
### Requirement: 栅格系统兼容
|
||||
系统SHALL保持Row/Col栅格系统的使用，确保响应式布局功能正常。
|
||||
|
||||
#### Scenario: 栅格组件替换
|
||||
- **WHEN** 使用Row和Col组件
|
||||
- **THEN** SHALL使用TDesign的Row和Col组件
|
||||
- **AND** 响应式配置（xs、sm、md、lg、xl）SHALL保持有效
|
||||
- **AND** gutter配置SHALL正常工作
|
||||
- **AND** 布局效果SHALL与迁移前一致
|
||||
|
||||
### Requirement: 主题系统移除
|
||||
系统SHALL完全移除多主题系统，使用TDesign默认主题。
|
||||
|
||||
#### Scenario: 删除主题相关代码
|
||||
- **WHEN** 迁移完成
|
||||
- **THEN** ThemeContext SHALL被删除
|
||||
- **AND** themes目录 SHALL被删除
|
||||
- **AND** 所有主题相关导入SHALL被移除
|
||||
|
||||
#### Scenario: 使用TDesign默认主题
|
||||
- **WHEN** 应用运行
|
||||
- **THEN** SHALL使用TDesign默认视觉风格
|
||||
- **AND** 不SHALL提供主题切换功能
|
||||
- **AND** UI风格SHALL统一一致
|
||||
|
||||
### Requirement: 依赖管理
|
||||
系统SHALL正确管理npm依赖，确保无冗余依赖。
|
||||
|
||||
#### Scenario: 移除Ant Design依赖
|
||||
- **WHEN** 依赖安装完成
|
||||
- **THEN** package.json中SHALL不存在antd
|
||||
- **AND** package.json中SHALL不存在@ant-design/icons
|
||||
- **AND** package.json中SHALL不存在@ant-design/charts
|
||||
- **AND** package.json中SHALL不存在antd-style
|
||||
|
||||
#### Scenario: 添加TDesign依赖
|
||||
- **WHEN** 依赖安装完成
|
||||
- **THEN** package.json中SHALL存在tdesign-react
|
||||
- **AND** package.json中SHALL存在tdesign-icons-react
|
||||
- **AND** 依赖版本SHALL为最新稳定版
|
||||
|
||||
### Requirement: Settings页面简化
|
||||
系统SHALL保留Settings页面路由，但简化页面内容为空状态。
|
||||
|
||||
#### Scenario: Settings页面访问
|
||||
- **WHEN** 用户访问/settings路由
|
||||
- **THEN** 页面SHALL正常加载
|
||||
- **AND** 页面SHALL显示空状态提示
|
||||
- **AND** 不SHALL显示主题设置相关内容
|
||||
|
||||
#### Scenario: Settings路由保留
|
||||
- **WHEN** 应用路由配置
|
||||
- **THEN** /settings路由SHALL存在
|
||||
- **AND** Settings页面组件SHALL存在
|
||||
@@ -1,6 +1,10 @@
|
||||
# Test Coverage
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
定义测试覆盖规范，建立后端和前端的单元测试、集成测试及 E2E 测试体系，确保核心业务逻辑的测试覆盖率达到目标水平。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 建立单元测试体系
|
||||
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
# Unified Proxy Handler
|
||||
|
||||
## ADDED Requirements
|
||||
## Purpose
|
||||
|
||||
实现统一的代理处理器（ProxyHandler），替代独立的 OpenAI 和 Anthropic Handler，通过 ConversionEngine 和 RoutingService 支持多协议的请求转换与转发。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 实现统一代理 Handler
|
||||
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
# Usage Statistics
|
||||
|
||||
## MODIFIED Requirements
|
||||
## Purpose
|
||||
|
||||
定义 API 使用统计规范，支持请求统计记录、按供应商/模型/日期范围查询统计、统计聚合以及并发安全的统计记录。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 记录请求统计
|
||||
|
||||
@@ -78,8 +82,6 @@
|
||||
|
||||
**变更说明：** 并发控制在 StatsRepository 中通过数据库事务实现。API 接口保持不变。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 使用 service 层处理业务逻辑
|
||||
|
||||
Handler SHALL 通过 StatsService 处理业务逻辑。
|
||||
|
||||
715
scripts/anthropic_detect.py
Normal file
715
scripts/anthropic_detect.py
Normal file
@@ -0,0 +1,715 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Anthropic 兼容性接口测试脚本
|
||||
|
||||
用法:
|
||||
python3 scripts/anthropic_detect.py --base_url <url> [options]
|
||||
|
||||
示例:
|
||||
python3 scripts/anthropic_detect.py --base_url https://api.example.com
|
||||
python3 scripts/anthropic_detect.py --base_url https://api.example.com --api_key sk-xxx --model claude-sonnet-4-5
|
||||
python3 scripts/anthropic_detect.py --base_url https://api.example.com --stream --tools --vision
|
||||
"""
|
||||
|
||||
import json
|
||||
import time
|
||||
import ssl
|
||||
import argparse
|
||||
import urllib.request
|
||||
import urllib.error
|
||||
|
||||
TIMEOUT = 30
|
||||
ANTHROPIC_VERSION = "2023-06-01"
|
||||
|
||||
|
||||
def create_ssl_context():
|
||||
ctx = ssl.create_default_context()
|
||||
ctx.check_hostname = False
|
||||
ctx.verify_mode = ssl.CERT_NONE
|
||||
return ctx
|
||||
|
||||
|
||||
def http_request(url, method="GET", headers=None, body=None, ssl_ctx=None):
|
||||
req = urllib.request.Request(url, method=method)
|
||||
if headers:
|
||||
for k, v in headers.items():
|
||||
req.add_header(k, v)
|
||||
if body is not None:
|
||||
if isinstance(body, str):
|
||||
req.data = body.encode("utf-8")
|
||||
else:
|
||||
req.data = json.dumps(body).encode("utf-8")
|
||||
|
||||
start = time.time()
|
||||
try:
|
||||
resp = urllib.request.urlopen(req, timeout=TIMEOUT, context=ssl_ctx)
|
||||
elapsed = time.time() - start
|
||||
return resp.getcode(), resp.read().decode("utf-8"), elapsed
|
||||
except urllib.error.HTTPError as e:
|
||||
elapsed = time.time() - start
|
||||
return e.code, e.read().decode("utf-8"), elapsed
|
||||
except Exception as e:
|
||||
elapsed = time.time() - start
|
||||
return None, str(e), elapsed
|
||||
|
||||
|
||||
def http_stream_request(url, headers=None, body=None, ssl_ctx=None):
|
||||
req = urllib.request.Request(url, method="POST")
|
||||
if headers:
|
||||
for k, v in headers.items():
|
||||
req.add_header(k, v)
|
||||
if body is not None:
|
||||
req.data = json.dumps(body).encode("utf-8")
|
||||
|
||||
start = time.time()
|
||||
try:
|
||||
resp = urllib.request.urlopen(req, timeout=TIMEOUT, context=ssl_ctx)
|
||||
status = resp.getcode()
|
||||
lines = []
|
||||
for raw_line in resp:
|
||||
line = raw_line.decode("utf-8").rstrip("\n\r")
|
||||
if line:
|
||||
lines.append(line)
|
||||
elapsed = time.time() - start
|
||||
return status, "\n".join(lines), elapsed
|
||||
except urllib.error.HTTPError as e:
|
||||
elapsed = time.time() - start
|
||||
return e.code, e.read().decode("utf-8"), elapsed
|
||||
except Exception as e:
|
||||
elapsed = time.time() - start
|
||||
return None, str(e), elapsed
|
||||
|
||||
|
||||
def format_json(text):
|
||||
try:
|
||||
parsed = json.loads(text)
|
||||
return json.dumps(parsed, ensure_ascii=False, indent=2)
|
||||
except (json.JSONDecodeError, TypeError):
|
||||
return text
|
||||
|
||||
|
||||
def build_headers(api_key):
|
||||
h = {
|
||||
"Content-Type": "application/json",
|
||||
"anthropic-version": ANTHROPIC_VERSION,
|
||||
}
|
||||
if api_key:
|
||||
h["x-api-key"] = api_key
|
||||
return h
|
||||
|
||||
|
||||
def run_test(index, total, desc, url, method, headers, body, stream, ssl_ctx):
|
||||
print(f"\n[{index}/{total}] {desc}")
|
||||
print(f">>> {method} {url}")
|
||||
if body is not None:
|
||||
if isinstance(body, str):
|
||||
print(body)
|
||||
else:
|
||||
print(format_json(json.dumps(body, ensure_ascii=False)))
|
||||
|
||||
if stream:
|
||||
status, data, elapsed = http_stream_request(url, headers, body, ssl_ctx)
|
||||
else:
|
||||
status, data, elapsed = http_request(url, method, headers, body, ssl_ctx)
|
||||
|
||||
if status is not None:
|
||||
print(f"状态码: {status} | 耗时: {elapsed:.2f}s")
|
||||
else:
|
||||
print(f"请求失败 | 耗时: {elapsed:.2f}s")
|
||||
|
||||
if stream and status and status < 300:
|
||||
for line in data.split("\n"):
|
||||
print(line)
|
||||
else:
|
||||
print(format_json(data))
|
||||
|
||||
return status
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Anthropic 兼容性接口测试",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
parser.add_argument("--base_url", required=True, help="API 基础地址 (如 https://api.example.com)")
|
||||
parser.add_argument("--api_key", default="", help="API 密钥 (默认空)")
|
||||
parser.add_argument("--model", default="claude-sonnet-4-5", help="模型名称 (默认 claude-sonnet-4-5)")
|
||||
parser.add_argument("--vision", action="store_true", help="执行视觉相关测试")
|
||||
parser.add_argument("--stream", action="store_true", help="执行流式响应测试")
|
||||
parser.add_argument("--tools", action="store_true", help="执行工具调用测试")
|
||||
parser.add_argument("--thinking", action="store_true", help="执行扩展思维测试")
|
||||
parser.add_argument("--all", action="store_true", help="开启所有扩展测试")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.all:
|
||||
args.vision = True
|
||||
args.stream = True
|
||||
args.tools = True
|
||||
args.thinking = True
|
||||
|
||||
base_url = args.base_url.rstrip("/")
|
||||
api_key = args.api_key
|
||||
model = args.model
|
||||
ssl_ctx = create_ssl_context()
|
||||
headers = build_headers(api_key)
|
||||
headers_bad_auth = build_headers("invalid-key-xxx")
|
||||
|
||||
messages_url = f"{base_url}/v1/messages"
|
||||
models_url = f"{base_url}/v1/models"
|
||||
count_tokens_url = f"{base_url}/v1/messages/count_tokens"
|
||||
|
||||
# --- 收集用例: (描述, 方法, URL, 请求头, 请求体, 是否流式) ---
|
||||
cases = []
|
||||
|
||||
# ==== Models API ====
|
||||
cases.append((
|
||||
"获取模型列表 (GET /v1/models)",
|
||||
"GET", models_url, headers, None, False
|
||||
))
|
||||
cases.append((
|
||||
"获取模型列表（分页 limit=3）(GET /v1/models?limit=3)",
|
||||
"GET", f"{models_url}?limit=3", headers, None, False
|
||||
))
|
||||
cases.append((
|
||||
"获取指定模型详情 (GET /v1/models/{model})",
|
||||
"GET", f"{models_url}/{model}", headers, None, False
|
||||
))
|
||||
cases.append((
|
||||
"获取不存在的模型 (GET /v1/models/nonexistent-model-xxx)",
|
||||
"GET", f"{models_url}/nonexistent-model-xxx", headers, None, False
|
||||
))
|
||||
|
||||
# ==== Messages API: 正面用例 ====
|
||||
cases.append((
|
||||
"基本对话（仅 user）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"system prompt + user 对话",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"system": "You are a helpful assistant.",
|
||||
"messages": [{"role": "user", "content": "1+1="}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"system prompt 数组格式（带缓存控制）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"system": [
|
||||
{"type": "text", "text": "You are a helpful assistant.", "cache_control": {"type": "ephemeral"}}
|
||||
],
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"多轮对话（含 assistant 历史）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hi"},
|
||||
{"role": "assistant", "content": "Hello!"},
|
||||
{"role": "user", "content": "1+1="}
|
||||
]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"assistant prefill（部分回复填充）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 1,
|
||||
"messages": [
|
||||
{"role": "user", "content": "What is latin for Ant? (A) Apoidea (B) Rhopalocera (C) Formicidae"},
|
||||
{"role": "assistant", "content": "The answer is ("}
|
||||
]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"content 数组格式（多个 text block）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": [
|
||||
{"type": "text", "text": "Hello"},
|
||||
{"type": "text", "text": "1+1=?"}
|
||||
]}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"temperature + top_p",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"temperature": 0.5,
|
||||
"top_p": 0.9,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"temperature = 0（类确定性输出）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"temperature": 0,
|
||||
"messages": [{"role": "user", "content": "1+1="}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"top_k 参数",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"top_k": 40,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"max_tokens 限制",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 10,
|
||||
"messages": [{"role": "user", "content": "讲一个故事"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"stop_sequences",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 20,
|
||||
"stop_sequences": ["5"],
|
||||
"messages": [{"role": "user", "content": "数数: 1,2,3,"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"metadata 参数（user_id）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"metadata": {"user_id": "test-user-001"},
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"assistant content 数组格式（text + tool_use 块）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 20,
|
||||
"messages": [
|
||||
{"role": "user", "content": "帮我查一下北京的天气"},
|
||||
{"role": "assistant", "content": [
|
||||
{"type": "text", "text": "好的，让我查一下。"},
|
||||
{"type": "tool_use", "id": "toolu_prev_001", "name": "get_weather", "input": {"location": "Beijing"}}
|
||||
]},
|
||||
{"role": "user", "content": [
|
||||
{"type": "tool_result", "tool_use_id": "toolu_prev_001", "content": [
|
||||
{"type": "text", "text": "{\"temperature\": 22, \"condition\": \"晴\"}"}
|
||||
]}
|
||||
]}
|
||||
]
|
||||
}, False
|
||||
))
|
||||
|
||||
# ==== Count Tokens API ====
|
||||
cases.append((
|
||||
"计数 Token (POST /v1/messages/count_tokens)",
|
||||
"POST", count_tokens_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hello, how are you?"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"计数 Token（带 system + tools）",
|
||||
"POST", count_tokens_url, headers, {
|
||||
"model": model,
|
||||
"system": "You are a helpful assistant.",
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"tools": [{
|
||||
"name": "get_weather",
|
||||
"description": "获取天气",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {"location": {"type": "string"}},
|
||||
"required": ["location"]
|
||||
}
|
||||
}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"计数 Token 缺少 model（负面）",
|
||||
"POST", count_tokens_url, headers, {
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
|
||||
# ==== Messages API: 负面用例 ====
|
||||
cases.append((
|
||||
"缺少 x-api-key header（无认证）",
|
||||
"POST", messages_url, {
|
||||
"Content-Type": "application/json",
|
||||
"anthropic-version": ANTHROPIC_VERSION,
|
||||
}, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"错误的 anthropic-version header",
|
||||
"POST", messages_url, {
|
||||
"Content-Type": "application/json",
|
||||
"anthropic-version": "0000-00-00",
|
||||
"x-api-key": api_key,
|
||||
} if api_key else {
|
||||
"Content-Type": "application/json",
|
||||
"anthropic-version": "0000-00-00",
|
||||
}, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"缺少 model 参数",
|
||||
"POST", messages_url, headers, {
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"缺少 messages 参数",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"缺少 max_tokens 参数",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"messages 为空数组",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": []
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"无效 API key",
|
||||
"POST", messages_url, headers_bad_auth, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"不存在的模型",
|
||||
"POST", messages_url, headers, {
|
||||
"model": "nonexistent-model-xxx",
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"畸形 JSON body",
|
||||
"POST", messages_url, headers, "invalid json{", False
|
||||
))
|
||||
cases.append((
|
||||
"无效 role（非法消息角色）",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"messages": [{"role": "system", "content": "You are helpful"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"max_tokens 为负数",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": -1,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"max_tokens = 0",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 0,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"temperature 超出范围 (2.0)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"temperature": 2.0,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, False
|
||||
))
|
||||
|
||||
# ==== --vision ====
|
||||
if args.vision:
|
||||
cases.append((
|
||||
"图片 URL 输入 (--vision)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 10,
|
||||
"messages": [{"role": "user", "content": [
|
||||
{"type": "text", "text": "用一个词描述这张图"},
|
||||
{"type": "image", "source": {
|
||||
"type": "url",
|
||||
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/"
|
||||
"Gfp-wisconsin-madison-the-nature-boardwalk.jpg/"
|
||||
"2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
|
||||
}}
|
||||
]}]
|
||||
}, False
|
||||
))
|
||||
|
||||
# ==== --stream ====
|
||||
if args.stream:
|
||||
cases.append((
|
||||
"基本流式 (--stream)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"stream": True,
|
||||
"messages": [{"role": "user", "content": "Hi"}]
|
||||
}, True
|
||||
))
|
||||
cases.append((
|
||||
"流式 + system prompt (--stream)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5,
|
||||
"stream": True,
|
||||
"system": "Reply in one word.",
|
||||
"messages": [{"role": "user", "content": "1+1="}]
|
||||
}, True
|
||||
))
|
||||
cases.append((
|
||||
"流式 + stop_sequences (--stream)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 20,
|
||||
"stream": True,
|
||||
"stop_sequences": ["5"],
|
||||
"messages": [{"role": "user", "content": "数数: 1,2,3,"}]
|
||||
}, True
|
||||
))
|
||||
|
||||
# ==== --tools ====
|
||||
if args.tools:
|
||||
tool_weather = {
|
||||
"name": "get_weather",
|
||||
"description": "获取指定城市的天气",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "城市名称"}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
cases.append((
|
||||
"工具调用 tool_choice: auto (--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": {"type": "auto"},
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"工具调用 tool_choice: any (--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": {"type": "any"},
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"指定工具调用 tool_choice: {name} (--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": {"type": "tool", "name": "get_weather"},
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"tool_choice: none (--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 20,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": {"type": "none"},
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"多轮工具调用（tool_result 返回）(--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 20,
|
||||
"tools": [tool_weather],
|
||||
"messages": [
|
||||
{"role": "user", "content": "北京天气怎么样？"},
|
||||
{"role": "assistant", "content": [
|
||||
{"type": "text", "text": "让我查一下。"},
|
||||
{"type": "tool_use", "id": "toolu_001", "name": "get_weather", "input": {"location": "Beijing"}}
|
||||
]},
|
||||
{"role": "user", "content": [
|
||||
{"type": "tool_result", "tool_use_id": "toolu_001", "content": "{\"temperature\": 22, \"condition\": \"晴\"}"}
|
||||
]}
|
||||
]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"多轮工具调用（tool_result 带 is_error）(--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 20,
|
||||
"tools": [tool_weather],
|
||||
"messages": [
|
||||
{"role": "user", "content": "北京天气怎么样？"},
|
||||
{"role": "assistant", "content": [
|
||||
{"type": "tool_use", "id": "toolu_002", "name": "get_weather", "input": {"location": "Beijing"}}
|
||||
]},
|
||||
{"role": "user", "content": [
|
||||
{"type": "tool_result", "tool_use_id": "toolu_002", "is_error": True, "content": "天气服务不可用"}
|
||||
]}
|
||||
]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"tool_choice 指向不存在的工具（负面）(--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": {"type": "tool", "name": "nonexistent_tool_xxx"},
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"多工具定义 (--tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 50,
|
||||
"tools": [
|
||||
tool_weather,
|
||||
{
|
||||
"name": "get_time",
|
||||
"description": "获取指定城市的当前时间",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "城市名称"}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
],
|
||||
"tool_choice": {"type": "auto"},
|
||||
"messages": [{"role": "user", "content": "北京现在几点了？天气怎么样？"}]
|
||||
}, False
|
||||
))
|
||||
|
||||
# ==== --thinking ====
|
||||
if args.thinking:
|
||||
cases.append((
|
||||
"扩展思维 enabled (--thinking)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 200,
|
||||
"thinking": {"type": "enabled", "budget_tokens": 100},
|
||||
"messages": [{"role": "user", "content": "1+1=?"}]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"扩展思维 adaptive (--thinking)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 200,
|
||||
"thinking": {"type": "adaptive", "budget_tokens": 100},
|
||||
"messages": [{"role": "user", "content": "1+1=?"}]
|
||||
}, False
|
||||
))
|
||||
|
||||
# ==== --stream + --tools 组合 ====
|
||||
if args.stream and args.tools:
|
||||
tool_weather_stream = {
|
||||
"name": "get_weather",
|
||||
"description": "获取指定城市的天气",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "城市名称"}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
cases.append((
|
||||
"流式工具调用 (--stream --tools)",
|
||||
"POST", messages_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 50,
|
||||
"stream": True,
|
||||
"tools": [tool_weather_stream],
|
||||
"tool_choice": {"type": "auto"},
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
|
||||
}, True
|
||||
))
|
||||
|
||||
# ==== 执行测试 ====
|
||||
total = len(cases)
|
||||
count_2xx = 0
|
||||
count_other = 0
|
||||
|
||||
print("=" * 60)
|
||||
print("Anthropic 兼容性测试")
|
||||
print(f"目标: {base_url}")
|
||||
print(f"模型: {model}")
|
||||
print(f"时间: {time.strftime('%Y-%m-%d %H:%M:%S')}")
|
||||
flags = []
|
||||
if args.vision:
|
||||
flags.append("vision")
|
||||
if args.stream:
|
||||
flags.append("stream")
|
||||
if args.tools:
|
||||
flags.append("tools")
|
||||
if args.thinking:
|
||||
flags.append("thinking")
|
||||
print(f"用例: {total} 个" + (f" | 扩展: {', '.join(flags)}" if flags else ""))
|
||||
print("=" * 60)
|
||||
|
||||
for i, (desc, method, url, hdrs, body, stream) in enumerate(cases, 1):
|
||||
status = run_test(i, total, desc, url, method, hdrs, body, stream, ssl_ctx)
|
||||
if status is not None and 200 <= status < 300:
|
||||
count_2xx += 1
|
||||
else:
|
||||
count_other += 1
|
||||
|
||||
print()
|
||||
print("=" * 60)
|
||||
print(f"测试完成 | 总计: {total} | HTTP 2xx: {count_2xx} | 非 2xx: {count_other}")
|
||||
print("=" * 60)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
552
scripts/openai_detect.py
Executable file
552
scripts/openai_detect.py
Executable file
@@ -0,0 +1,552 @@
|
||||
#!/usr/bin/env python3
|
||||
"""OpenAI 兼容性接口测试脚本
|
||||
|
||||
用法:
|
||||
python3 scripts/openai_compat_test.py --base_url <url> [options]
|
||||
|
||||
示例:
|
||||
python3 scripts/openai_compat_test.py --base_url https://api.example.com/v1
|
||||
python3 scripts/openai_compat_test.py --base_url https://api.example.com/v1 --api_key sk-xxx --model gpt-4o
|
||||
python3 scripts/openai_compat_test.py --base_url https://api.example.com/v1 --stream --tools
|
||||
"""
|
||||
|
||||
import json
|
||||
import time
|
||||
import ssl
|
||||
import argparse
|
||||
import urllib.request
|
||||
import urllib.error
|
||||
|
||||
TIMEOUT = 30
|
||||
|
||||
|
||||
def create_ssl_context():
|
||||
ctx = ssl.create_default_context()
|
||||
ctx.check_hostname = False
|
||||
ctx.verify_mode = ssl.CERT_NONE
|
||||
return ctx
|
||||
|
||||
|
||||
def http_request(url, method="GET", headers=None, body=None, ssl_ctx=None):
|
||||
req = urllib.request.Request(url, method=method)
|
||||
if headers:
|
||||
for k, v in headers.items():
|
||||
req.add_header(k, v)
|
||||
if body is not None:
|
||||
if isinstance(body, str):
|
||||
req.data = body.encode("utf-8")
|
||||
else:
|
||||
req.data = json.dumps(body).encode("utf-8")
|
||||
|
||||
start = time.time()
|
||||
try:
|
||||
resp = urllib.request.urlopen(req, timeout=TIMEOUT, context=ssl_ctx)
|
||||
elapsed = time.time() - start
|
||||
return resp.getcode(), resp.read().decode("utf-8"), elapsed
|
||||
except urllib.error.HTTPError as e:
|
||||
elapsed = time.time() - start
|
||||
return e.code, e.read().decode("utf-8"), elapsed
|
||||
except Exception as e:
|
||||
elapsed = time.time() - start
|
||||
return None, str(e), elapsed
|
||||
|
||||
|
||||
def http_stream_request(url, headers=None, body=None, ssl_ctx=None):
|
||||
req = urllib.request.Request(url, method="POST")
|
||||
if headers:
|
||||
for k, v in headers.items():
|
||||
req.add_header(k, v)
|
||||
if body is not None:
|
||||
req.data = json.dumps(body).encode("utf-8")
|
||||
|
||||
start = time.time()
|
||||
try:
|
||||
resp = urllib.request.urlopen(req, timeout=TIMEOUT, context=ssl_ctx)
|
||||
status = resp.getcode()
|
||||
lines = []
|
||||
for raw_line in resp:
|
||||
line = raw_line.decode("utf-8").rstrip("\n\r")
|
||||
if line:
|
||||
lines.append(line)
|
||||
elapsed = time.time() - start
|
||||
return status, "\n".join(lines), elapsed
|
||||
except urllib.error.HTTPError as e:
|
||||
elapsed = time.time() - start
|
||||
return e.code, e.read().decode("utf-8"), elapsed
|
||||
except Exception as e:
|
||||
elapsed = time.time() - start
|
||||
return None, str(e), elapsed
|
||||
|
||||
|
||||
def format_json(text):
|
||||
try:
|
||||
parsed = json.loads(text)
|
||||
return json.dumps(parsed, ensure_ascii=False, indent=2)
|
||||
except (json.JSONDecodeError, TypeError):
|
||||
return text
|
||||
|
||||
|
||||
def build_headers(api_key):
|
||||
h = {"Content-Type": "application/json"}
|
||||
if api_key:
|
||||
h["Authorization"] = f"Bearer {api_key}"
|
||||
return h
|
||||
|
||||
|
||||
def run_test(index, total, desc, url, method, headers, body, stream, ssl_ctx):
|
||||
print(f"\n[{index}/{total}] {desc}")
|
||||
print(f">>> {method} {url}")
|
||||
if body is not None:
|
||||
if isinstance(body, str):
|
||||
print(body)
|
||||
else:
|
||||
print(format_json(json.dumps(body, ensure_ascii=False)))
|
||||
|
||||
if stream:
|
||||
status, data, elapsed = http_stream_request(url, headers, body, ssl_ctx)
|
||||
else:
|
||||
status, data, elapsed = http_request(url, method, headers, body, ssl_ctx)
|
||||
|
||||
if status is not None:
|
||||
print(f"状态码: {status} | 耗时: {elapsed:.2f}s")
|
||||
else:
|
||||
print(f"请求失败 | 耗时: {elapsed:.2f}s")
|
||||
|
||||
if stream and status and status < 300:
|
||||
# 流式响应按 SSE 行逐行输出
|
||||
for line in data.split("\n"):
|
||||
print(line)
|
||||
else:
|
||||
print(format_json(data))
|
||||
|
||||
return status
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="OpenAI 兼容性接口测试",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
parser.add_argument("--base_url", required=True, help="API 基础地址 (如 https://api.example.com/v1)")
|
||||
parser.add_argument("--api_key", default="", help="API 密钥 (默认空)")
|
||||
parser.add_argument("--model", default="gpt-4o", help="模型名称 (默认 gpt-4o)")
|
||||
parser.add_argument("--vision", action="store_true", help="执行视觉相关测试")
|
||||
parser.add_argument("--stream", action="store_true", help="执行流式响应测试")
|
||||
parser.add_argument("--tools", action="store_true", help="执行工具调用测试")
|
||||
parser.add_argument("--logprobs", action="store_true", help="执行 logprobs 测试")
|
||||
parser.add_argument("--json_schema", action="store_true", help="执行 Structured Output 测试")
|
||||
parser.add_argument("--all", action="store_true", help="开启所有扩展测试")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.all:
|
||||
args.vision = True
|
||||
args.stream = True
|
||||
args.tools = True
|
||||
args.logprobs = True
|
||||
args.json_schema = True
|
||||
|
||||
base_url = args.base_url.rstrip("/")
|
||||
api_key = args.api_key
|
||||
model = args.model
|
||||
ssl_ctx = create_ssl_context()
|
||||
headers = build_headers(api_key)
|
||||
headers_bad_auth = build_headers("invalid-key-xxx")
|
||||
|
||||
chat_url = f"{base_url}/chat/completions"
|
||||
|
||||
# --- 收集用例: (描述, 方法, URL, 请求头, 请求体, 是否流式) ---
|
||||
cases = []
|
||||
|
||||
# ---- Models API ----
|
||||
cases.append((
|
||||
"获取模型列表 (GET /models)",
|
||||
"GET", f"{base_url}/models", headers, None, False
|
||||
))
|
||||
cases.append((
|
||||
"获取指定模型详情 (GET /models/{model})",
|
||||
"GET", f"{base_url}/models/{model}", headers, None, False
|
||||
))
|
||||
cases.append((
|
||||
"获取不存在的模型 (GET /models/nonexistent-model-xxx)",
|
||||
"GET", f"{base_url}/models/nonexistent-model-xxx", headers, None, False
|
||||
))
|
||||
|
||||
# ---- Chat Completions: 正面用例 ----
|
||||
cases.append((
|
||||
"基本对话（仅 user）",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"system + user 对话",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "1+1="}
|
||||
],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"developer + user 对话",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [
|
||||
{"role": "developer", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "1+1="}
|
||||
],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"多轮对话（含 assistant 历史）",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hi"},
|
||||
{"role": "assistant", "content": "Hello!"},
|
||||
{"role": "user", "content": "1+1="}
|
||||
],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"temperature + top_p",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"temperature": 0.5,
|
||||
"top_p": 0.9
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"max_tokens 限制",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "讲一个故事"}],
|
||||
"max_tokens": 10
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"stop sequences",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "数数: 1,2,3,"}],
|
||||
"max_tokens": 20,
|
||||
"stop": ["5"]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"n=2 多候选",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"n": 2
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"seed 参数",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"seed": 42
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"frequency_penalty + presence_penalty",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"frequency_penalty": 0.5,
|
||||
"presence_penalty": 0.5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"max_completion_tokens 参数",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "讲一个故事"}],
|
||||
"max_completion_tokens": 10
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"JSON mode (response_format: json_object)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [
|
||||
{"role": "system", "content": "以 JSON 格式回复: {\"answer\": \"ok\"}"},
|
||||
{"role": "user", "content": "test"}
|
||||
],
|
||||
"max_tokens": 10,
|
||||
"response_format": {"type": "json_object"}
|
||||
}, False
|
||||
))
|
||||
|
||||
# ---- Chat Completions: 负面用例 ----
|
||||
cases.append((
|
||||
"缺少 model 参数",
|
||||
"POST", chat_url, headers, {
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"缺少 messages 参数",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"messages 为空数组",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"无效 API key",
|
||||
"POST", chat_url, headers_bad_auth, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"不存在的模型 (chat)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": "nonexistent-model-xxx",
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"畸形 JSON body",
|
||||
"POST", chat_url, headers, "invalid json{", False
|
||||
))
|
||||
|
||||
# ---- --vision ----
|
||||
if args.vision:
|
||||
image_url = (
|
||||
"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/"
|
||||
"Gfp-wisconsin-madison-the-nature-boardwalk.jpg/"
|
||||
"2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
|
||||
)
|
||||
cases.append((
|
||||
"图片 URL 输入 + detail 参数 (--vision)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [
|
||||
{"role": "system", "content": "简短描述图片"},
|
||||
{"role": "user", "content": [
|
||||
{"type": "text", "text": "用一个词描述这张图"},
|
||||
{"type": "image_url", "image_url": {
|
||||
"url": image_url, "detail": "low"
|
||||
}}
|
||||
]}
|
||||
],
|
||||
"max_tokens": 10
|
||||
}, False
|
||||
))
|
||||
|
||||
# ---- --stream ----
|
||||
if args.stream:
|
||||
cases.append((
|
||||
"基本流式 (--stream)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"stream": True
|
||||
}, True
|
||||
))
|
||||
cases.append((
|
||||
"流式 + include_usage (--stream)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"stream": True,
|
||||
"stream_options": {"include_usage": True}
|
||||
}, True
|
||||
))
|
||||
cases.append((
|
||||
"流式 + stop sequences (--stream)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "数数: 1,2,3,"}],
|
||||
"max_tokens": 20,
|
||||
"stream": True,
|
||||
"stop": ["5"]
|
||||
}, True
|
||||
))
|
||||
|
||||
# ---- --tools ----
|
||||
if args.tools:
|
||||
tool_weather = {
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "get_weather",
|
||||
"description": "获取指定城市的天气",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string", "description": "城市名称"}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
}
|
||||
cases.append((
|
||||
"工具调用 tool_choice: auto (--tools)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}],
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": "auto"
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"工具调用 tool_choice: required (--tools)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}],
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": "required"
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"指定函数调用 tool_choice: {name} (--tools)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "北京天气怎么样？"}],
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": {
|
||||
"type": "function",
|
||||
"function": {"name": "get_weather"}
|
||||
}
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"多轮工具调用（构造 tool 结果）(--tools)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [
|
||||
{"role": "user", "content": "北京天气怎么样？"},
|
||||
{"role": "assistant", "content": None, "tool_calls": [{
|
||||
"id": "call_001", "type": "function",
|
||||
"function": {
|
||||
"name": "get_weather",
|
||||
"arguments": "{\"location\": \"Beijing\"}"
|
||||
}
|
||||
}]},
|
||||
{"role": "tool", "tool_call_id": "call_001",
|
||||
"content": "{\"temperature\": 22, \"condition\": \"晴\"}"}
|
||||
],
|
||||
"max_tokens": 20,
|
||||
"tools": [tool_weather]
|
||||
}, False
|
||||
))
|
||||
cases.append((
|
||||
"parallel_tool_calls: false (--tools)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "北京和上海的天气怎么样？"}],
|
||||
"max_tokens": 50,
|
||||
"tools": [tool_weather],
|
||||
"tool_choice": "auto",
|
||||
"parallel_tool_calls": False
|
||||
}, False
|
||||
))
|
||||
|
||||
# ---- --logprobs ----
|
||||
if args.logprobs:
|
||||
cases.append((
|
||||
"logprobs + top_logprobs (--logprobs)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "Hi"}],
|
||||
"max_tokens": 5,
|
||||
"logprobs": True,
|
||||
"top_logprobs": 2
|
||||
}, False
|
||||
))
|
||||
|
||||
# ---- --json-schema ----
|
||||
if args.json_schema:
|
||||
cases.append((
|
||||
"Structured Output json_schema (--json_schema)",
|
||||
"POST", chat_url, headers, {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "1+1等于几？"}],
|
||||
"max_tokens": 20,
|
||||
"response_format": {
|
||||
"type": "json_schema",
|
||||
"json_schema": {
|
||||
"name": "math_answer",
|
||||
"strict": True,
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"answer": {"type": "number"},
|
||||
"explanation": {"type": "string"}
|
||||
},
|
||||
"required": ["answer", "explanation"],
|
||||
"additionalProperties": False
|
||||
}
|
||||
}
|
||||
}
|
||||
}, False
|
||||
))
|
||||
|
||||
# ---- 执行测试 ----
|
||||
total = len(cases)
|
||||
count_2xx = 0
|
||||
count_other = 0
|
||||
|
||||
print("=" * 60)
|
||||
print("OpenAI 兼容性测试")
|
||||
print(f"目标: {base_url}")
|
||||
print(f"模型: {model}")
|
||||
print(f"时间: {time.strftime('%Y-%m-%d %H:%M:%S')}")
|
||||
flags = []
|
||||
if args.vision:
|
||||
flags.append("vision")
|
||||
if args.stream:
|
||||
flags.append("stream")
|
||||
if args.tools:
|
||||
flags.append("tools")
|
||||
if args.logprobs:
|
||||
flags.append("logprobs")
|
||||
if args.json_schema:
|
||||
flags.append("json-schema")
|
||||
print(f"用例: {total} 个" + (f" | 扩展: {', '.join(flags)}" if flags else ""))
|
||||
print("=" * 60)
|
||||
|
||||
for i, (desc, method, url, hdrs, body, stream) in enumerate(cases, 1):
|
||||
status = run_test(i, total, desc, url, method, hdrs, body, stream, ssl_ctx)
|
||||
if status is not None and 200 <= status < 300:
|
||||
count_2xx += 1
|
||||
else:
|
||||
count_other += 1
|
||||
|
||||
print()
|
||||
print("=" * 60)
|
||||
print(f"测试完成 | 总计: {total} | HTTP 2xx: {count_2xx} | 非 2xx: {count_other}")
|
||||
print("=" * 60)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user