### Backend setup and test commands (pip install, python main.py, pytest)

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/AGENTS.md

Run these commands in the NameGenerationAgent/ directory. pip install installs dependencies, python main.py starts the local service, and pytest runs the full test suite or a specific test. On Windows, quick_start.bat can be used for a quick start.

```bash
pip install -r requirements.txt
python main.py
python -m pytest tests/ -v
python -m pytest tests/test_basic.py::TestNameGenerator::test_get_available_options -v
```

--------------------------------

### Frontend setup and build commands (npm install, npm run dev, npm run build)

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/AGENTS.md

Run these commands in the 智能姓名生成系统/ directory. npm install installs dependencies, npm run dev starts the local development server, and npm run build generates the production build.

```bash
npm install
npm run dev
npm run build
```

--------------------------------

### GET /options

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取系统选项，用于页面启动时初始化配置。

```APIDOC
## GET /options

### Description
获取系统选项，用于页面启动时初始化配置。

### Method
GET

### Endpoint
/options

### Response
#### Success Response (200)
- 返回选项数据（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /models

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取可用模型列表，支持按平台筛选和强制刷新缓存。

```APIDOC
## GET /models

### Description
获取所有平台或特定平台的模型列表，支持强制刷新缓存。

### Method
GET

### Endpoint
/models

### Parameters
#### Query Parameters
- **api** (string) - Optional - 指定平台，如 aliyun。
- **refresh** (boolean) - Optional - 是否强制刷新缓存，true 表示刷新。

### Request Example
GET /models?api=aliyun&refresh=true

### Response
#### Success Response (200)
- 返回模型列表（具体结构未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /admin

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

管理员后台首页。

```APIDOC
## GET /admin

### Description
管理员后台首页。

### Method
GET

### Endpoint
/admin

### Response
#### Success Response (200)
- 返回后台页面（具体内容未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

返回系统信息和主要端点。

```APIDOC
## GET /

### Description
返回系统信息和主要端点。

### Method
GET

### Endpoint
/
```

--------------------------------

### GET /options

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取风格、性别、年龄、平台等选项。

```APIDOC
## GET /options

### Description
获取风格、性别、年龄、平台等选项。

### Method
GET

### Endpoint
/options
```

--------------------------------

### GET /models

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取所有平台或单个平台的模型列表。

```APIDOC
## GET /models

### Description
获取所有平台或单个平台的模型列表。

### Method
GET

### Endpoint
/models
```

--------------------------------

### GET /auth/me

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取当前登录用户的信息。

```APIDOC
## GET /auth/me

### Description
获取当前登录用户的信息。

### Method
GET

### Endpoint
/auth/me

### Response
#### Success Response (200)
- 返回用户信息（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /history/list

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取当前用户的历史记录，需要用户登录。

```APIDOC
## GET /history/list

### Description
获取当前用户的历史记录，需要用户登录。

### Method
GET

### Endpoint
/history/list

### Response
#### Success Response (200)
- 返回历史记录列表（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /stats

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

返回系统统计信息。

```APIDOC
## GET /stats

### Description
返回系统统计信息。

### Method
GET

### Endpoint
/stats
```

--------------------------------

### GET /favorites

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取当前用户的收藏列表，需要用户登录。

```APIDOC
## GET /favorites

### Description
获取当前用户的收藏列表，需要用户登录。

### Method
GET

### Endpoint
/favorites

### Response
#### Success Response (200)
- 返回收藏列表（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /health

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

健康检查端点，用于检查服务是否正常运行。

```APIDOC
## GET /health

### Description
健康检查端点，用于检查服务是否正常运行。

### Method
GET

### Endpoint
/health
```

--------------------------------

### GET /favorites

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取当前用户收藏。需要 Bearer Token。

```APIDOC
## GET /favorites

### Description
获取当前用户收藏。需要 Bearer Token。

### Method
GET

### Endpoint
/favorites
```

--------------------------------

### GET /history

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取最近一次历史记录。需要 Bearer Token。

```APIDOC
## GET /history

### Description
获取最近一次历史记录。需要 Bearer Token。

### Method
GET

### Endpoint
/history
```

--------------------------------

### GET /auth/me

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

获取当前登录用户信息。需要 Bearer Token。

```APIDOC
## GET /auth/me

### Description
获取当前登录用户信息。需要 Bearer Token。

### Method
GET

### Endpoint
/auth/me
```

--------------------------------

### GET /admin/users/<id>

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

查看指定用户的信息。

```APIDOC
## GET /admin/users/<id>

### Description
查看指定用户的信息。

### Method
GET

### Endpoint
/admin/users/<id>

### Parameters
#### Path Parameters
- **id** (integer) - Required - 用户 ID。

### Response
#### Success Response (200)
- 返回用户信息（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### GET /history/list

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

分页获取当前用户历史记录。需要 Bearer Token。

```APIDOC
## GET /history/list

### Description
分页获取当前用户历史记录。需要 Bearer Token。

### Method
GET

### Endpoint
/history/list
```

--------------------------------

### 配置后端跨域来源

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

在 .env 文件中设置允许访问的跨域来源。

```env
ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173,http://nameagent.natapp1.cc
```

--------------------------------

### 配置本地开发跨域

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

在后端 .env 文件中配置本地开发环境的跨域来源。

```env
ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
```

--------------------------------

### Commit Baishan provider implementation

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/docs/plans/2026-03-15-baishan-implementation.md

Stage and commit the new Baishan provider files and documentation.

```bash
git add docs/plans/2026-03-15-baishan-design.md docs/plans/2026-03-15-baishan-implementation.md NameGenerationAgent/config/api_config.py NameGenerationAgent/src/api/adapters/__init__.py NameGenerationAgent/src/api/adapters/baishan_adapter.py NameGenerationAgent/src/api/unified_client.py NameGenerationAgent/tests/test_baishan_adapter.py
git commit -m "feat: add baishan provider"
```

--------------------------------

### POST /admin/login

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

管理员登录入口。

```APIDOC
## POST /admin/login

### Description
管理员登录入口。

### Method
POST

### Endpoint
/admin/login

### Response
#### Success Response (200)
- 返回登录结果（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### 前端开发与构建命令

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

使用 npm 执行前端项目的依赖安装、开发模式启动及生产环境构建。

```bash
# 安装依赖
npm install

# H5开发
npm run dev:h5

# 微信小程序开发
npm run dev:mp-weixin

# 构建
npm run build:h5
npm run build:mp-weixin
```

--------------------------------

### Run Baishan adapter tests

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/docs/plans/2026-03-15-baishan-implementation.md

Execute the pytest suite for the Baishan adapter to verify implementation status.

```bash
python -m pytest NameGenerationAgent/tests/test_baishan_adapter.py -q
```

--------------------------------

### Run focused regression tests

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/docs/plans/2026-03-15-baishan-implementation.md

Run both Baishan and OpenAI compatible adapter tests to ensure no regressions.

```bash
python -m pytest NameGenerationAgent/tests/test_baishan_adapter.py NameGenerationAgent/tests/test_openai_compatible_adapter.py -q
```

--------------------------------

### SQLite到MySQL迁移脚本

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

运行Python脚本迁移认证数据从SQLite到MySQL，需指定--sqlite-path和--target-db-url参数。示例中目标数据库为mysql+pymysql连接。

```bash
cd NameGenerationAgent
python scripts/migrate_auth_sqlite_to_mysql.py \
  --sqlite-path data/auth.db \
  --target-db-url mysql+pymysql://name_agent_app:123456@127.0.0.1:3306/name_generation_agent?charset=utf8mb4
```

--------------------------------

### 安装后端依赖

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

在后端目录下安装必要的Python依赖包。

```bash
pip install -r ../NameGenerationAgent/requirements.txt
```

--------------------------------

### 后端服务启动命令

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

在NameGenerationAgent目录下执行的环境配置、依赖安装及服务启动命令。

```bash
cd NameGenerationAgent

# Windows
..\.venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 初始化环境变量
copy env.example .env

# 启动服务
quick_start.bat
# 或
python main.py

# 基础检查
curl http://127.0.0.1:5000/health
```

--------------------------------

### POST /auth/register

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

手机号注册。

```APIDOC
## POST /auth/register

### Description
手机号注册。

### Method
POST

### Endpoint
/auth/register
```

--------------------------------

### 获取模型列表接口示例

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

使用curl或类似工具请求/models接口，支持获取所有平台模型、特定平台模型（如aliyun）以及强制刷新缓存（refresh=true）。模型列表按平台缓存，默认缓存1小时。

```bash
# 获取所有平台模型
GET /models

# 获取特定平台模型
GET /models?api=aliyun

# 强制刷新缓存
GET /models?api=aliyun&refresh=true
```

--------------------------------

### 确认后端健康状态

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

使用 curl 命令检查后端服务是否正常响应。

```bash
curl http://127.0.0.1:5000/health
```

--------------------------------

### POST /generate

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

生成姓名并持久化记录。需要 Bearer Token。常用参数包括 description（必填）、count（1-20）、cultural_style、gender、age、preferred_api、model、use_cache、preferred_surname、surname_weight、preferred_era、era_weight。

```APIDOC
## POST /generate

### Description
生成姓名并持久化记录。需要 Bearer Token。

### Method
POST

### Endpoint
/generate

### Parameters
#### Request Body
- **description** (string) - Required - 角色描述
- **count** (integer) - Optional - 生成数量，范围 1 到 20
- **cultural_style** (string) - Optional - 文化风格
- **gender** (string) - Optional - 性别
- **age** (string) - Optional - 年龄段
- **preferred_api** (string) - Optional - 首选平台
- **model** (string) - Optional - 指定模型
- **use_cache** (boolean) - Optional - 是否启用缓存
- **preferred_surname** (string) - Optional - 偏好姓氏
- **surname_weight** (number) - Optional - 姓氏权重
- **preferred_era** (string) - Optional - 偏好时代
- **era_weight** (number) - Optional - 时代权重
```

--------------------------------

### 启动后端服务

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

运行后端主程序，默认监听 5000 端口。

```bash
python ../NameGenerationAgent/main.py
```

--------------------------------

### POST /auth/login

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

手机号登录并返回 token 与用户信息。

```APIDOC
## POST /auth/login

### Description
手机号登录并返回 token 与用户信息。

### Method
POST

### Endpoint
/auth/login
```

--------------------------------

### 查看日志（PowerShell）

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

使用 PowerShell 实时查看日志文件，并过滤 ERROR 或 WARNING 级别日志。

```powershell
cd NameGenerationAgent
Get-Content .\logs\app.log -Wait -Tail 50
Get-Content .\logs\app.log -Wait -Tail 50 | Select-String -Pattern "ERROR|WARNING"
```

--------------------------------

### 前端开发命令

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

在智能姓名生成系统目录下执行的前端依赖安装及开发环境启动命令。

```bash
cd 智能姓名生成系统
npm install
npm run dev:h5
npm run dev:mp-weixin
```

--------------------------------

### POST /generate

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

生成姓名，需要用户登录，可通过 model 字段指定模型。

```APIDOC
## POST /generate

### Description
生成姓名，需要用户登录，可通过 model 字段指定模型。

### Method
POST

### Endpoint
/generate

### Parameters
#### Request Body
- **model** (string) - Optional - 指定使用的模型。

### Request Example
{
  "model": "gpt-4"
}

### Response
#### Success Response (200)
- 返回生成结果（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### 后端测试命令

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

在NameGenerationAgent目录下执行的pytest测试命令，用于验证系统功能。

```bash
cd NameGenerationAgent
python -m pytest tests/ -v
python -m pytest tests/test_basic.py::TestNameGenerator::test_get_available_options -v
python -m pytest tests/test_corpus_integration.py -v
python tests/test_model_discovery.py
```

--------------------------------

### POST /admin/users/<id>/enable

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

启用指定用户。

```APIDOC
## POST /admin/users/<id>/enable

### Description
启用指定用户。

### Method
POST

### Endpoint
/admin/users/<id>/enable

### Parameters
#### Path Parameters
- **id** (integer) - Required - 用户 ID。

### Response
#### Success Response (200)
- 返回操作结果（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### 项目目录结构

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

展示了项目根目录及各子模块的组织结构。

```text
.
├── README.md
├── NameGenerationAgent/
│   ├── config/
│   ├── src/
│   │   ├── api/
│   │   ├── core/
│   │   ├── db/
│   │   ├── data/
│   │   ├── utils/
│   │   └── web/
│   ├── data/
│   ├── deploy/
│   ├── logs/
│   ├── scripts/
│   ├── tests/
│   ├── env.example
│   ├── main.py
│   ├── quick_start.bat
│   ├── setup_domain.bat
│   └── start_natapp.bat
├── 智能姓名生成系统/
│   ├── common/api.ts
│   ├── pages/Generate/Generate.vue
│   └── package.json
└── docs/plans/
```

--------------------------------

### POST /admin/users/<id>/reset-password

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

重置指定用户的密码。

```APIDOC
## POST /admin/users/<id>/reset-password

### Description
重置指定用户的密码。

### Method
POST

### Endpoint
/admin/users/<id>/reset-password

### Parameters
#### Path Parameters
- **id** (integer) - Required - 用户 ID。

### Response
#### Success Response (200)
- 返回操作结果（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### POST /admin/users/<id>/disable

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

禁用指定用户。

```APIDOC
## POST /admin/users/<id>/disable

### Description
禁用指定用户。

### Method
POST

### Endpoint
/admin/users/<id>/disable

### Parameters
#### Path Parameters
- **id** (integer) - Required - 用户 ID。

### Response
#### Success Response (200)
- 返回操作结果（具体字段未在文档中说明）

#### Response Example
（未提供）
```

--------------------------------

### POST /favorites

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

写入当前用户收藏。需要 Bearer Token。

```APIDOC
## POST /favorites

### Description
写入当前用户收藏。需要 Bearer Token。

### Method
POST

### Endpoint
/favorites
```

--------------------------------

### 配置前端 API 地址

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/智能姓名生成系统/README.md

在 common/api.ts 中修改 BASE_URL 以切换本地或公网环境。

```typescript
// 固定服务器地址
const BASE_URL = 'http://127.0.0.1:5000';  // 本地开发
// const BASE_URL = 'http://nameagent.natapp1.cc';  // 公网访问
```

--------------------------------

### POST /auth/logout

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

注销当前 token。需要 Bearer Token。

```APIDOC
## POST /auth/logout

### Description
注销当前 token。需要 Bearer Token。

### Method
POST

### Endpoint
/auth/logout
```

--------------------------------

### POST /auth/change-password

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

修改当前用户密码。需要 Bearer Token。

```APIDOC
## POST /auth/change-password

### Description
修改当前用户密码。需要 Bearer Token。

### Method
POST

### Endpoint
/auth/change-password
```

--------------------------------

### DELETE /favorites

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

删除当前用户收藏。需要 Bearer Token。

```APIDOC
## DELETE /favorites

### Description
删除当前用户收藏。需要 Bearer Token。

### Method
DELETE

### Endpoint
/favorites
```

--------------------------------

### DELETE /admin/records/<id>/delete

Source: https://github.com/yunmuhe/yunmuhecode/blob/master/README.md

删除指定记录。

```APIDOC
## DELETE /admin/records/<id>/delete

### Description
删除指定记录。

### Method
DELETE

### Endpoint
/admin/records/<id>/delete

### Parameters
#### Path Parameters
- **id** (integer) - Required - 记录 ID。

### Response
#### Success Response (200)
- 返回操作结果（具体字段未在文档中说明）

#### Response Example
（未提供）
```