# AI 功能 (/docs/use/ai-features)

Mix Space 内置了一套完整的 AI 功能体系，覆盖内容创作、管理、分发全流程。你只需配置一个 LLM 服务商即可启用。

<Callout type="info">
AI 功能需要后台「设置 → AI → AI 设置」中配置至少一个 Provider 并启用对应功能开关。详见下方 [配置 AI Provider](#配置-ai-provider)。
</Callout>

## 功能总览

| 功能 | 说明 | 触发方式 |
|------|------|----------|
| **AI 摘要** | 自动生成文章摘要，支持多语言 | 手动 / 自动（发布/更新时） |
| **AI 精读** | 生成深度阅读伴侣（TL;DR、结构图、Mermaid 图、引用锚点） | 手动 / 自动（发布/更新时） |
| **AI 翻译** | 将文章翻译为多语言版本，保持 Markdown/Lexical 格式完整 | 手动 / 自动（发布/更新时） |
| **写作助手** | 自动生成标题和 SEO slug，批量回填历史文章 slug | 编辑器内手动 |
| **评论审核** | AI 自动识别垃圾评论和有害内容 | 自动（评论提交时） |
| **AI Agent** | 在编辑器中与 AI 对话，辅助写作和修改 | 编辑器内手动 |
| **任务队列** | 统一管理所有 AI 后台任务的创建、进度和重试 | 后台 AI 页面 |

## 配置 AI Provider

<Steps>
<Step>
### 进入设置页面

登录后台，前往「设置 → AI → AI 设置」。
</Step>

<Step>
### 添加 Provider

点击「添加 Provider」，填写以下信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| Provider ID | 唯一标识符 | `openai-main`、`deepseek` |
| 显示名称 | 便于识别的名称 | `OpenAI`、`DeepSeek` |
| Provider 类型 | 服务商类型 | TypeSafe / OpenAI-Compatible / Anthropic / Generic / Google Vertex |
| API Key | 你的 API 密钥 | `sk-...` |
| 自定义 Endpoint | OpenAI-Compatible 类型必填 | `https://api.deepseek.com` |
| 默认模型 | 该 Provider 默认使用的模型 | `gpt-4o`、`deepseek-chat` |
| Project ID | Google Vertex 类型必填，Google Cloud project ID | `my-gcp-project` |
| 能力位 | 该 Provider 支持的能力（决策 / 文本 / 图像 / 语音），决定它能否被图像生成、语音合成复用 | 文本 + 图像 |
| 上下文窗口 | 该模型的上下文长度 | `128000` |
| 最大输出 | 该模型单次最大输出 token 数 | `8192` |
| 模型列表地址 | 覆盖自动获取的模型列表 | — |
| 音色列表地址 | 覆盖自动获取的音色列表 | — |
| 自动补 `/v1` | Endpoint 未带版本号时自动追加 `/v1` | 开 / 关 |

<Callout type="warn">
`OpenAI` 和 `OpenRouter` 是**历史值**，已被统一合并进 `OpenAI-Compatible`（数据库迁移 `0017_ai_provider_type_collapse`）。如果你的旧配置里还是这两个值，升级后会被改写成 `openai-compatible`，属于预期行为。

另外，Endpoint 为 `aiplatform.googleapis.com` 的 OpenAI-Compatible Provider 会被服务端自动识别为 `google-vertex`。
</Callout>
</Step>

<Step>
### 为各功能分配模型（可选）

在 Provider 列表下方，可以为各个功能分别指定使用哪个 Provider 和模型。留空则使用第一个启用的 Provider 及其默认模型。

可分配的槽位共 11 个：决策模型、摘要模型、写作模型、评论审核模型、翻译模型、翻译审校模型、字段翻译模型、精读模型、精读翻译模型，以及图像生成模型、语音合成模型。

<Callout type="info">
`翻译审校模型` 和 `字段翻译模型` 留空时会回落到翻译模型。
</Callout>
</Step>

<Step>
### 测试连接

配置完成后，点击 Provider 旁的「测试」按钮，验证 API Key 和 Endpoint 是否正确。
</Step>
</Steps>

<Callout type="info">
你可以同时配置多个 Provider，并将不同的 AI 功能分配给不同的 Provider。例如用 DeepSeek 做翻译（成本低），用 OpenAI 做精读（效果好）。
</Callout>

## AI 摘要

AI 摘要可以为你的文章自动生成简短的内容概要，支持多语言输出。

### 开启摘要

在「设置 → AI → AI 设置」中：

1. 打开「可调用 AI 摘要」开关
2. 设置「AI 摘要目标语言列表」（使用 [ISO 639-1 语言代码](https://www.w3schools.com/tags/ref_language_codes.asp)，如 `zh`、`en`、`ja`）

<Callout type="info">
当前版本**没有**「文章创建/更新时自动生成摘要」这类开关。摘要是在**发布文章时**勾选要一并生成的 AI 资源来触发的，可以选择同步等待或后台异步执行；也可以随时在「AI → 摘要」页面手动触发。
</Callout>

### 手动生成摘要

进入后台「AI → 摘要」页面，选择文章后点击生成。也可以在文章编辑器中通过侧边栏触发。

### 摘要管理

在「AI → 摘要」页面中，你可以：

- 按文章分组查看所有摘要
- 编辑已生成的摘要文本
- 删除不需要的摘要
- 查看摘要对应的原文信息

## AI 精读（Insights）

AI 精读是比摘要更深入的内容分析功能。它会生成一篇「深度阅读伴侣」，包含 TL;DR、结构化大纲、Mermaid 图表、引用锚点回原文、开放性问题等内容，帮助读者更好地理解文章。

### 开启精读

在「设置 → AI → AI 设置」中：

1. 打开「可调用 AI Insights」开关
2. 可选：设置「Insights 目标语言列表」用于精读内容的多语言翻译
3. 可选：打开「Insights 生成后自动翻译」
4. 可选：设置「Insights 自动生成最小文本长度」

### 精读内容包含什么

精读根据文章类型自动选择 3-7 个组件进行生成，可能包含：

| 组件 | 说明 |
|------|------|
| TL;DR | 1-3 句话概括核心观点 |
| 结构图 / 时间线 | 文章的逻辑结构或事件时序 |
| Mermaid 图表 | 架构图、流程图、因果链等可视化 |
| 关键概念 | 术语表或背景知识卡片 |
| 引用锚点 | 精读中的关键论点锚定回原文位置 |
| 反论与盲点 | 指出作者未涉及的视角 |
| 开放性问题 | 值得读者进一步思考的问题 |

### 精读翻译

精读内容也支持多语言翻译。设置「Insights 目标语言列表」后，可以在精读页面手动触发翻译，或开启自动翻译。

## AI 翻译

AI 翻译可以将你的文章完整翻译为多语言版本，保持 Markdown 格式、代码块、链接等技术元素不变，同时保持翻译一致性。

### 开启翻译

在「设置 → AI → AI 设置」中：

1. 打开「可调用 AI 翻译」开关
2. 设置「AI 翻译目标语言列表」（如 `en`、`ja`、`ko`）

<Callout type="warn">
自 v14.15.1 起，**自动翻译已下线**。服务端不再自动创建翻译条目，也不再自动重新生成过期翻译；`enableAutoGenerateTranslation` 配置项已被移除。翻译改为在发布时勾选，或在后台手动触发。
</Callout>

### 翻译特性

- **双策略支持**：Markdown 文章和 Lexical 富文本文章分别使用对应的翻译策略，确保格式完整保留
- **翻译词表**：系统自动维护分类名称、话题名称、心情、天气等短文本的翻译一致性
- **多语言批量翻译**：可以一次为多篇文章生成多语言翻译
- **全量翻译**：支持一键为所有已有文章生成翻译

### 手动翻译操作

进入后台「AI → 翻译」页面：

- 选择文章，点击「翻译」
- 选择目标语言后开始生成
- 生成完成后可查看、编辑、删除翻译

### 翻译词表

进入「AI → 翻译词表」页面，可以查看和管理系统自动维护的翻译词表。词表用于确保分类、话题、心情、天气等短文本在不同文章间翻译一致。

支持的管理操作：
- 按类型（分类名、话题名、心情、天气）筛选查看
- 手动编辑翻译结果
- 批量重新生成

## 写作助手

写作助手在编辑器中为你提供 AI 辅助。

### 标题和 Slug 生成

在编辑器中撰写完内容后，可以使用 AI 自动生成：
- **标题**：根据文章内容生成一个合适的标题
- **Slug**：生成 SEO 友好的英文 URL 路径

<Callout type="info">
确保在 AI 设定中配置了写作助手模型（Writer Model），或在编辑器的 AI 面板中选择了可用的 Provider。
</Callout>

### Slug 批量回填

如果你有历史文章缺少 slug，可以使用「AI → Slug 回填」功能：

1. 进入后台「AI → Slug 回填」页面
2. 查看缺少 slug 的日记条目数量
3. 点击「开始回填」，系统会为所有缺少 slug 的日记自动生成 SEO slug

## 评论审核

AI 评论审核功能会在读者提交评论时自动进行内容安全检查。

### 配置评论审核

在后台「设置 → 内容 → 评论设置」中：

1. 打开「开启 AI 审核」开关
2. 选择审核方式：
   - **是非模式（Binary）**：AI 判断评论是否为垃圾内容
   - **评分模式（Score）**：AI 给出风险评分（1-10），超过阈值则判定为垃圾
3. 如果使用评分模式，设置阈值（默认 5，范围 1-10）
4. 点击「测试 AI 审核」验证功能

### 检测能力

AI 评论审核可以识别以下类型的违规内容：

- 垃圾评论、广告、诈骗
- 人身攻击、网络霸凌
- 仇恨言论和歧视
- 政治敏感、色情、暴力内容
- 阴阳怪气和隐性攻击
- 无意义测试内容

## AI Agent（编辑器内对话）

AI Agent 允许你在编辑器中直接与 AI 对话，辅助写作和内容修改。

### 使用方式

在文章编辑器中，打开右侧的 AI Agent 面板：

1. 选择一个已配置的 Provider 和模型
2. 在对话框中输入指令，如「帮我润色这段文字」「把这段改成更口语化的风格」
3. AI 的回复可以应用到编辑器中

<Callout type="info">
AI Agent 对话历史会自动保存，你可以在同一篇文章中随时继续之前的对话。
</Callout>

## AI 图像生成

为文章生成封面图和正文配图。服务端提供 `ai/image` 接口，支持草稿提示词（draft-prompt）、生成、预设（presets）和模型列表等能力。

- 编辑器中插入图片前会先弹出审阅面板，可裁剪、标注、打码或模糊敏感区域、缩放长边
- 照片若带 GPS 信息，面板会展示坐标且**默认勾选移除位置**；经过编辑的图片会被重新编码去除元数据
- 若 GPS 剥离失败，图片会被暂扣而不是带着位置信息上传
- 上传对象名冲突时会自动加后缀，**不会静默覆盖已发布的图片**

## AI 语音合成（TTS）

把文章转成音频。服务端提供 `ai/tts` 接口，支持音色列表、任务提交、任务查询和按文章生成。

- TTS 属于付费内容，权益校验会放行站点所有者与有效会员
- 翻译、精读、摘要、TTS 都可以在发布文章时勾选为「发布前同步生成」或「发布后异步生成」
- 若服务商返回 200 但没有音频内容，服务端会自动重试而不是交付空音轨

## AI 总览与生成指标

`ai/overview` 接口提供 AI 能力的全局视图：

- **覆盖率**——多少内容已生成摘要 / 精读 / 翻译
- **活跃任务**——当前正在跑的 AI 任务统计
- 单篇文章的 AI 资源生成情况

## 翻译审校

开启「翻译审校」后，翻译结果会经过一个 agent loop 复核一致性，而不只做词表替换。

## 任务队列

所有 AI 后台任务通过统一的任务队列管理，你可以在「AI → 任务」页面查看和管理。

### 任务类型

| 任务类型 | 说明 |
|----------|------|
| 摘要生成 | 为单篇文章生成摘要 |
| 翻译生成 | 为单篇文章生成翻译 |
| 批量翻译 | 为多篇文章批量生成翻译 |
| 全量翻译 | 为所有文章生成翻译 |
| 摘要翻译 | 为已生成的摘要生成多语言版本 |
| 精读生成 | 为单篇文章生成精读 |
| 精读翻译 | 翻译已生成的精读内容 |
| 图像生成 | 生成封面图 / 配图 |
| 语音合成 | 为文章生成 TTS 音频 |
| Slug 回填 | 为历史日记批量生成 slug |

### 任务状态

| 状态 | 说明 |
|------|------|
| Pending | 等待执行 |
| Running | 正在执行 |
| Completed | 执行完成 |
| Partial Failed | 部分子任务失败 |
| Failed | 执行失败 |
| Cancelled | 已取消 |

### 任务管理

在任务页面中，你可以：

- 按状态和类型筛选任务
- 查看任务详情（进度、日志、耗时）
- 重试失败的任务
- 取消正在运行的任务
- 批量清理历史任务

<Callout type="info">
批量翻译任务会自动分组，你可以在任务列表中展开查看每个子任务的状态。
</Callout>