# 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-vl-plus"|"minimax-m2.5"`，非法值回落到 `"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 / 默认个性化配置。