docs/zh/ai-settings.md

Rama main · réplica de lectura del repositorio original.

# AI 与界面设置

[English](../en/ai-settings.md) | 简体中文

设置侧栏按**模型与 AI、连接与集成、安全与隐私、通用**排列。
通用页面把界面语言、语音朗读与识别、DF Agent、系统维护合在同一个界面，
不再为语音、Agent 和维护设置单独的侧栏页。游戏、外观主题与关于是通用分组中的独立页面。
旧的 `section=voice`、`section=agent`、`section=system` 链接会进入通用并定位到对应区域；
搜索也直接定位页面内的设置。
界面语言与右上角同步，保存在当前浏览器；模型与 AI 包含服务商和模型配置。
搜索位于电脑和手机设置侧栏的最顶部，提示文字为“搜索”，
按名称、同义词定位并展开详情，
切换分类会保留未保存的输入，不会索引密钥或提示词正文。

打开**管理 → 设置**，从侧栏选择对应页面：

| 分组 | 页面与常用操作 |
| --- | --- |
| 模型与 AI | **模型接口**保存服务商与凭据；**模型配置**为各项能力分配服务商/模型，展开“高级生成设置”可调采样和上下文。 |
| 连接与集成 | 网络代理、分享地址、Bot API；独立前端另有“后端连接”。 |
| 安全与隐私 | 访问密码；**安全**页面包含“DiceFrame Hub 与隐私”。 |
| 通用 | **通用**设置系统语言、语音、DF Agent 和系统维护；**游戏**设置新对局默认值；**外观主题**设置主题和背景；**关于**保留版本更新、项目链接与重启操作。 |

通用、游戏、外观主题、关于是并列页面，不是“通用”页面里的下级菜单。
内容区只显示当前分类，
其他分类不占位；菜单和编辑区分别成框、保留间距。电脑目录高度受视口约束，
在目录内滚动可到达最后一项，不随右侧内容拉长；手机目录可收起在搜索框下方。
管理页的日志目录也采用独立纵向菜单，矮窗口可滚动到处理日志和导出入口。

## 服务商与检定模型

先保存共享服务商，再为各项能力选择服务商引用与模型，不提供能力级直填
地址、密钥的旧配置回退。删除服务商时，同步清理凭据与引用。

**模型配置 → 独立检定模型**关闭时跟随主模型；开启后，由
`check_provider_ref`、`check_model` 单独选择检定和世界意图规划模型。
掷骰和结算仍由服务端执行。已启用但缺少有效引用的配置不会静默改用主模型
或残留密钥，需要补齐配置或关闭独立模型。离线、手动检定本身不需要 AI；
服务商失败时仍保留已有的确定性离线恢复策略。

## 上下文与采样

在**模型配置 → 高级生成设置**中展开采样、上下文、生成预算与请求超时。
这些设置与模型卡片使用相同的布局，默认折叠；一处保存当前高级生成设置，
不会保存 DF Agent 的独立预算。搜索任一参数会自动展开并定位，旧深链接仍可使用。

`context_recent_rounds` 默认 `0`，沿用自动上下文预算；`1`–`100` 表示直接携带
的最近 GM/玩家历史轮数上限。它不删除存档、不关闭长期记忆、不突破上下文
预算，也不扩大查看者权限。重新生成时只从目标分支之前的历史截取。

`llm_generation_options` 是可选对象，未设置的字段沿用各功能默认值：

| 字段 | 范围 |
| --- | --- |
| `temperature` | 0–2 |
| `top_p` | 0–1 |
| `frequency_penalty` | −2–2 |
| `presence_penalty` | −2–2 |

自定义值应用于主模型和备用模型，包括文本、Agent 请求；独立检定客户端
保留检定专用默认值。清空输入即可取消覆盖。服务商或模型不支持的显式值会
报错，不会被悄悄丢弃。当前原生 Anthropic Messages 客户端不支持频率/主题
惩罚参数；设置前应核对所用服务商的 API 契约。

Chat 请求只根据明确的 API 拒绝协商兼容参数：`max_tokens` 可以转换为同数值
的 `max_completion_tokens`；不受支持的功能默认温度可以省略，用户显式设置
的值受到保护。这与既有的输出截断重试策略是两回事。

## DF Agent 预算

**通用页面的 DF Agent 区域**可调整显示、恢复悬浮球位置，以及独立的单次请求输出预算
（`assistant_agent_max_tokens`，默认 4096）。它不是整个任务的总费用上限；
生成工具保留各自的预算，服务商上下文和账号限制仍然生效。

## 模型能决定什么

主模型收到当前游戏指令、可见状态、所选资料，以及预算允许的近期记录。
检定规划模型收到当前规则、服务端角色技能和行动；它提出检定建议，服务端校验对象、
计算加值和骰面。单独更换检定模型只改变该请求的服务商，不改变游戏规则。

不同模型提出场景与记忆更新的频率会不同。这些更新是应用解析的结构化建议，
不是每轮都必须出现的正文标题。强制输出 `SCENE:`、`MEMORY:` 不会取得状态写入权限，
也不能公开秘密或覆盖冒险当前场景。支持的协议与修复行为以安装版本的
`prompts/check_planner_zh.md`、`src/llm/protocol.py`、`src/commands/protocol_repair.py`
为准。战役的文风指令放在世界风格设置，检定模型通过独立检定路由配置。