Appearance
AI 角色
AI 角色（Character）是系统的核心实体，定义了 AI 助手的行为方式。
概念层次
角色 (Character)
└─ 绑定 LLM 模型、工具集等 AI 配置
└─ 可被多个用户使用
用户角色配置 (UserCharacterConfig)
└─ 用户对某个角色的个性化设置
└─ 一个用户对同一角色只能有一个配置
对话 (Conversation)
└─ 在某个用户角色配置下的聊天会话
└─ 一个配置下可以有多个对话角色端点
| 方法 | 路径 | 说明 | 权限 |
|---|---|---|---|
| GET | /api/v1/characters | 角色列表 | scope=own/public/all |
| POST | /api/v1/characters | 创建角色 | 已认证用户 |
| GET | /api/v1/characters/{id} | 角色详情 | 自有/公开/管理员 |
| PATCH | /api/v1/characters/{id} | 更新角色 | 创建者/管理员 |
| DELETE | /api/v1/characters/{id} | 删除角色 | 创建者/管理员 |
| GET | /api/v1/characters/{id}/user-character-configs | 相关用户配置 | 创建者/管理员 |
角色响应示例
json
{
"id": "a1b2c3d4-...",
"created_at": "2026-01-10T10:00:00Z",
"updated_at": "2026-03-15T14:00:00Z",
"name": "创意助手",
"description": "擅长创意写作和头脑风暴的AI助手",
"system_prompt": "你是一个创意写作助手...",
"visibility": "public",
"reasoning": false,
"max_tool_call_iterations": 5,
"created_by_id": "550e8400-..."
}关键字段
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 角色名称 |
system_prompt | string | 系统提示词（最大 60K 字符） |
visibility | string | 可见性档位（private|public） |
reasoning | bool | 是否启用推理模式（显示思考过程） |
max_tool_call_iterations | int | 单次补全中工具调用最大迭代次数 |
用户角色配置端点
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/user-character-configs | 配置列表 |
| POST | /api/v1/user-character-configs | 创建配置（绑定角色） |
| GET | /api/v1/user-character-configs/{id} | 配置详情 |
| PATCH | /api/v1/user-character-configs/{id} | 更新配置 |
| DELETE | /api/v1/user-character-configs/{id} | 删除配置 |
测试要点
测试建议
- scope 过滤：
scope=own只返回自己创建的角色；scope=public返回所有公开角色；scope=all需管理员 - 创建限额：用户创建角色数量有配额限制，超限返回
413 - 公开角色：公开角色可被所有用户查看，但只有创建者可修改
- 级联删除：删除角色后相关的用户配置和对话应如何处理
- system_prompt 长度：超过 60K 字符应返回 422 验证错误
- reasoning 模式：开启后对话响应应包含
thinking字段