MODEL_SETTINGS.zh-CN.md - DeepSeek-Reasonix

MODEL_SETTINGS.zh-CN.md

1	# 桌面端模型设置
2
3	从设置 → 模型 → 接入进入，也可以在聊天模型菜单中点击管理模型。
4
5	设置中心占满应用窗口。点击返回工作区回到原工作区；本次应用运行期间，再次打开会记住上次的设置栏目。Esc 用于关闭子弹窗或菜单，不会退出设置主页面。
6
7	在左栏选择已保存的供应商，右栏编辑连接和模型。切换供应商会保留表单草稿；点击保存后生效，点击取消放弃修改。关闭设置会丢弃尚未保存的表单。
8
9	## 添加供应商
10
11	- 推荐预设：展开紧凑的供应商选择器，按名称搜索，选择预设并填写 API Key 后添加。已有预设继续显示已安装或冲突状态。同一产品的多个协议连接保留分组，可在高级路由设置中单独管理。
12	- 自定义供应商：填写名称、协议、Base URL 和 API Key，表单会预览最终请求地址。特殊网关路径可在兼容设置中填写覆盖请求地址，它优先于 Base URL。已有完整地址与旧版 Chat URL 保持原来的请求行为。
13
14	编辑已有供应商时，密钥留空会保留原有凭据；删除凭据需要使用单独的清除密钥操作。
15
16	## 保存与生效
17
18	启动尚未完成、启动失败或没有活动会话时，仍可以保存模型设置。保存不会隐式创建会话，也不会发起模型请求。
19
20	\| 设置 \| 生效时机 \|
21	\| --- \| --- \|
22	\| 默认聊天模型 \| 只影响新建会话；已有会话保留自己的模型 \|
23	\| 规划、视觉、搜索、子代理模型及推理偏好 \| 在各个受影响会话的下一次运行前应用 \|
24	\| 服务地址、协议、密钥、模型目录或能力 \| 下一次运行前应用；已接受的工作继续使用原连接 \|
25	\| 删除服务、模型、访问权限或清空密钥 \| 当前工作允许完成；下一次运行使用经过校验的可用替代模型，否则阻止运行并要求配置模型 \|
26	\| 显式切换当前会话模型 \| 只操作指定会话，保留已有的忙碌检查和会话所有权保护 \|
27
28	一次已接受的运行包括所属规划、工具、重试、审批等待和子任务。排队的后续消息、定时任务及新机器人请求属于新运行。项目明确指定的配置继续覆盖全局偏好。
29
30	页面分别显示“已保存，待应用”和“已保存，应用失败”。应用失败时会列出受影响会话，并提供“重试应用”。重试读取最新已保存配置，不会重新保存密钥。应用失败会保留旧控制器和历史，但阻止受影响的新运行。保存期间新增的编辑仍保留为草稿。
31
32	认证条件与配置持久化、runtime 应用分别管理。本地 Ready 只表示具备提交条件，远端仍可能
33	失败。缺少凭据时，在创建用户消息、执行 hook 或发送 provider 请求之前就会阻止该轮。
34	401 会阻止同一连接和凭据的后续自动请求；403 会尽量只阻止失败模型。恢复提示会保留草稿
35	和附件，并提供配置凭据、选择模型、测试连接和一次显式重试。保存或测试成功都不会自动
36	重放失败任务。
37
38	由 Desktop 提供凭据的远程会话使用不可变的隧道令牌。远程网页发送及队列派发在新运行前检查 Desktop 设置；已有请求保留原令牌直至所属工作结束。不支持配置快照的旧版 Serve 需要在当前工作完成后升级或安全重连；Desktop 不会为了应用设置而强停它。独立配置的远程会话继续由远端配置管理。
39
40	## 恢复与旧版本兼容
41
42	配置仍使用 TOML，凭据仍在 `.env` 中，会话历史格式保持不变。修改密钥时，先写入独立凭据引用，再提交使用该引用的配置。配置提交前失败时，旧连接仍可使用，最多留下未引用的新凭据。失败清理仅检查本次创建的引用，不会扫描并删除用户自定义凭据变量。
43
44	保存响应丢失后，页面会先读取请求回执和当前设置，再提供下一次保存。完成回执可跨重启保留，
45	只包含请求身份和 revision，不包含 Key。没有明确持久化证据时返回 `unknown_result`，应先
46	核对已保存值；Reasonix 不会自动重复结果不明的写入。
47
48	进行中的记录位于 Reasonix home 下的私有事务目录。只有旧配置 revision 仍可确认时，恢复
49	流程才会删除记录明确列出的本次新槽位。发布前先记录最终配置内容的 revision，恢复时必须
50	同时匹配该 revision 与凭据引用才能补齐回执；不分配凭据槽位的编辑也遵循此规则。
51	遇到并发修改、路径不可读或清理失败时会保留证据供诊断，不覆盖当前文件。
52
53	请求摘要使用私有、持久化的认证密钥，同一请求在进程重启后仍可识别。旧版本未使用稳定
54	摘要的回执无法验证重放请求的内容，应重新读取设置，不能据此发起一次新的写入。
55
56	凭据修复不会通过重写 `.env` 验证权限，只进行不截断文件的访问检查，并拒绝链接或身份
57	发生变化的目标。访问检查通过不代表已经证明现有文件能够原子替换。
58
59	旧版本仍能读取保存后的 TOML 和 `.env` 引用。降级会失去新的生效语义，并可能重新暴露活动会话依赖和即时刷新运行时的旧缺陷。降级不要求删除配置或会话历史。
60
61	实现与验收证据见[模型设置运行时验证](MODEL_SETTINGS_RUNTIME_VALIDATION.zh-CN.md)。
62
63	## 管理模型
64
65	刷新模型打开可搜索的选择弹窗，已有模型会勾选并锁定。添加所选模型仅将选中的新模型追加到表单，保存供应商后生效。发现失败时仍可手动添加。
66
67	手动添加和每行的编辑按钮会打开模型弹窗，可填写准确的模型 ID、上下文窗口、最大输出 Token 和图片能力。数值留空沿用默认值；输出 `-1` 表示不发送可选的输出限制，协议强制要求该字段时仍使用其兜底值。图片选择自动时使用模型元数据，手动覆盖必须符合端点的实际能力。编辑数值时会保留已有推理参数。
68
69	删除模型只在表单中暂存，取消供应商表单可撤销。原默认模型仍在列表中时会继续保留，否则使用第一个剩余模型。
70
71	测试模型通过当前协议适配器发送短请求，不包含会话历史或工具，可能产生少量供应商费用。测试使用当前表单，也支持尚未保存的 Key。连接测试和模型发现都不会保存凭据或配置；修改连接后旧测试结果失效。成功仅代表请求被接受，不代表已验证全部模型能力。
72
73	聊天菜单按供应商展示已保存、可用的模型，并在数据可用时展示上下文和图片能力。编辑模型设置不会修改系统提示词或工具定义。
74
75	## Windows 窗口行为
76
77	Windows 设置页保留右上角的最小化、最大化/还原和关闭窗口按钮。标题栏与按钮统一为 48 CSS px，按钮区域与设置背景一致，不受原工作区的工作台或创作布局影响。顶部空白区域用于拖动窗口；返回按钮、表单与窗口按钮不属于拖动区域。
78
79	返回工作区只退出设置；右上角关闭窗口继续遵循通用设置中的关闭行为。模型子弹窗内的关闭按钮只关闭该弹窗。
80
81	### Windows 参考调研与验证边界（2026-09-05）
82
83	- 参考对象：ZCode Windows 版本。
84	- 安装包逻辑确认：Windows 使用原生标题栏按钮、透明标题栏覆盖层，基准高度 48px，并随界面缩放更新；设置页为独立整页组件，返回工作区与窗口关闭独立；关闭窗口可按配置隐藏到托盘。
85	- 本项目通过 Electron 壳的窗口控制，将共享标题栏尺寸与颜色用于设置页。
86	- 已验证本项目 Windows 浏览器预览的标题栏尺寸、颜色和工作台/创作布局切换，以及设置导航与子弹窗测试。
87	- Windows 原生拖动、系统缩放、最大化及托盘行为尚未完成验收；源码检查不能替代原生验证。
88

88 lines MARKDOWN