119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
# Prompt 与个性化（Personalization）管理 API
|
||
|
||
## Prompt（主提示词）存储位置
|
||
- 路径：`api/users/<user>/shared/prompts/<name>.txt`（用户级共享）
|
||
- 内容格式：纯文本
|
||
|
||
## 个性化存储位置
|
||
- 路径：`api/users/<user>/shared/personalization/<name>.json`（用户级共享）
|
||
- 内容格式：JSON（下面给出完整结构与字段约束）
|
||
|
||
## 个性化 JSON 结构（content）
|
||
|
||
> 该结构与服务端 `modules/personalization_manager.py` 的 `DEFAULT_PERSONALIZATION_CONFIG` / `sanitize_personalization_payload()` 完全一致。
|
||
> 服务端会对你上传的 `content` 做规范化（截断长度、限制条数、过滤非法值/未知分类、回落默认值）。
|
||
|
||
### 完整示例（可直接用）
|
||
|
||
```json
|
||
{
|
||
"enabled": false,
|
||
"self_identify": "",
|
||
"user_name": "",
|
||
"profession": "",
|
||
"tone": "",
|
||
"considerations": [],
|
||
"thinking_interval": null,
|
||
"disabled_tool_categories": [],
|
||
"default_run_mode": null,
|
||
"auto_generate_title": true,
|
||
"tool_intent_enabled": true,
|
||
"default_model": "kimi"
|
||
}
|
||
```
|
||
|
||
### 字段说明与约束
|
||
|
||
| 字段 | 类型 | 默认 | 说明/约束 |
|
||
|---|---|---|---|
|
||
| `enabled` | bool | false | 是否启用个性化注入；为 false 时个性化不会写入 system prompt |
|
||
| `self_identify` | string | "" | 助手自称；会被截断到 20 字符 |
|
||
| `user_name` | string | "" | 对用户称呼；会被截断到 20 字符 |
|
||
| `profession` | string | "" | 用户职业；会被截断到 20 字符 |
|
||
| `tone` | string | "" | 语气风格；会被截断到 20 字符（服务端有推荐列表但不强校验） |
|
||
| `considerations` | string[] | [] | 重要注意事项列表：最多 10 条，每条最多 50 字符，非字符串/空字符串会被丢弃 |
|
||
| `thinking_interval` | int / null | null | 思考内容展示节奏相关：会被钳制到 1~50；非法值会变成 null |
|
||
| `disabled_tool_categories` | string[] | [] | 禁用的工具分类 id 列表：未知分类会被过滤（分类集合来自服务端 TOOL_CATEGORIES） |
|
||
| `default_run_mode` | "fast"/"thinking"/"deep"/null | null | 默认运行模式：非法值会变成 null |
|
||
| `auto_generate_title` | bool | true | 是否自动生成对话标题 |
|
||
| `tool_intent_enabled` | bool | true | 工具意图提示开关（属于配置结构的一部分） |
|
||
| `default_model` | string | "kimi" | 默认模型：仅允许 `"kimi"|"deepseek"|"qwen3-max"|"qwen3-vl-plus"`，非法值回落到 `"kimi"` |
|
||
|
||
### 最小示例（启用 + 2 条注意事项）
|
||
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"user_name": "Jojo",
|
||
"tone": "企业商务",
|
||
"considerations": [
|
||
"优先给出结论，再补充依据",
|
||
"涉及风险时给出可执行的规避方案"
|
||
]
|
||
}
|
||
```
|
||
|
||
## 接口
|
||
|
||
### 列出 Prompt
|
||
`GET /api/v1/prompts`
|
||
|
||
响应：
|
||
```json
|
||
{ "success": true, "items": [ { "name": "default", "size": 123, "updated_at": 1769182550.59 } ] }
|
||
```
|
||
|
||
### 获取 Prompt 内容
|
||
`GET /api/v1/prompts/{name}`
|
||
|
||
响应：
|
||
```json
|
||
{ "success": true, "name": "custom_a", "content": "你的主系统提示..." }
|
||
```
|
||
|
||
### 创建/覆盖 Prompt
|
||
`POST /api/v1/prompts`
|
||
```json
|
||
{ "name": "custom_a", "content": "你的主系统提示内容" }
|
||
```
|
||
成功返回 `{ "success": true, "name": "custom_a" }`
|
||
|
||
---
|
||
|
||
### 列出个性化
|
||
`GET /api/v1/personalizations`
|
||
|
||
### 获取个性化内容
|
||
`GET /api/v1/personalizations/{name}`
|
||
|
||
### 创建/覆盖个性化
|
||
`POST /api/v1/personalizations`
|
||
```json
|
||
{ "name": "biz_mobile", "content": { "enabled": true, "tone": "企业商务" } }
|
||
```
|
||
|
||
说明：
|
||
|
||
- 服务端会对 `content` 做 **规范化/清洗**（截断长度、限制条数、过滤非法值/未知分类、回落默认值），并把清洗后的结果落盘；
|
||
- 返回体里的 `content` 也是 **清洗后的** 版本（建议客户端以返回值为准）。
|
||
|
||
---
|
||
|
||
## 在对话/消息中使用
|
||
|
||
- `POST /api/v1/workspaces/{workspace_id}/conversations` 可选参数：`prompt_name`、`personalization_name`，会写入对话元数据并在后续消息中应用。
|
||
- `POST /api/v1/workspaces/{workspace_id}/messages` 可选参数：`prompt_name`、`personalization_name`，立即应用并写入元数据。
|
||
- 元数据字段：`custom_prompt_name`、`personalization_name`；对话加载时会自动套用对应文件（若不存在则忽略）。
|
||
|
||
优先级：调用时传入 > 对话元数据 > 默认主 prompt / 默认个性化配置。
|