# 模型编辑面板 ## 使用流程 1. 先在 DSH 原生模型设置中配置供应商、协议、地址及凭据。可使用助手的“从上游导入模型”，也可在原生设置中手动添加模型。 2. 打开设置中的独立“模型信息助手”页面，选择供应商与模型。顶部选择区固定，编辑内容独立滚动。 3. 先选已添加供应商，再选该供应商的模型，点击“填入模型信息”自动补全空白参数和可用价格；已有名称、容量和具体推理档通常保留，图片及推理能力的补全例外见下文。来源选择和字段差异放在折叠的“高级比较”内。两级选框支持搜索，下拉最多显示前 200 个匹配项，避免拉长页面。新增供应商／模型通过宿主事件自动刷新列表，未保存草稿保留。 4. 修改最大输出时，需勾选确认其同时更新每次请求的默认输出上限；再次修改数值后需重新确认。 5. 在“编辑价格”中选择币种、数据源和手动单价或倍率模式；可获取参考价格或指定参考来源，倍率模式填写统一倍率。 6. 点击页面底部固定操作栏中的“保存”，统一保存模型参数和定价，并检查保存结果。 参数、单价和保存入口位于主面板；价格编辑、推理档映射、导入及内置覆盖在对应折叠区。最大输出输入框提示其默认请求上限语义。 同币种下手动单价留空表示保持原值，不表示删除。切换价格模式保留同币种的原手动单价；切换币种保存会替换旧币种价格。重新读取会丢弃整个编辑草稿；参数保存不覆盖未保存的价格草稿，定价保存不覆盖参数草稿。 只修改模型参数时不会重复写入定价。重新获取参考报价并保存直接单价后，当前报价仍可用于切换倍率模式；主动重新读取则恢复已保存的倍率参考快照。 倍率留空、数值无效或计算结果超出支持范围时，草稿单价显示“未知”；明确输入 `0` 时，已知参考价预览为零，未知缓存价仍为未知。空倍率不能保存。 ## 推理 / 思考能力与档位的当前限制 “推理 / 思考”复选框与“高级设置”中的推理档配置共用 DSH 的 `reasoningEfforts` 字段。当前不向宿主配置单独保存“支持推理，但档位未知”的能力标记。自动推荐的具体档位仅来自模型官方目录，不参与多供应商投票；普通参数采用官方加权投票，详见 [推荐规则](pi-web-workflow.md)。 - 数据源明确给出 `reasoning: false` 时，转换为 `reasoningEfforts: false`，表示不声明推理能力。 - 数据源提供 `reasoning_options` 中的 `effort` 档位时，读取识别到的档位和请求值。目前识别 `minimal`、`low`、`medium`、`high`、`xhigh`、`max`，以及映射为 `off` 的 `none`；不代表能解析任意供应商自定义的思考开关或预算参数。 - 仅提供 `none` 时保留 `off: none`，不补造可开启的推理档位，也不自动替换已经明确禁用推理的配置。 - 只有 `reasoning: true`、没有可识别档位时，不推断 `reasoningEfforts`，也不会仅凭这个标记自动勾选复选框。档位未配置时复选框显示中间态；参考来源确认支持推理但官方无可用档位时，在已有状态文字的悬停提示中显示“支持推理，档位未知”，不新增提示行、不占用复选框位置。 - 填入模型信息默认保留已有参数；已有具体推理档位不会自动覆盖；false、空对象或仅有 off 的配置会在参考来源提供有效档位时自动补全到草稿，点击保存后写盘，可撤销本次填入。可在“高级比较”中核对差异并主动应用。 - 手动勾选时，已有档位会保留；没有有效档位时默认创建 `medium: medium`。这是插件的默认值，不是查询到的模型能力，不保证该模型或接口支持；保存前应按供应商要求在“高级设置”中核对档位及请求值。 - 手动取消勾选会在保存时写入 `reasoningEfforts: false`。这改变 DSH 声明的能力，不保证关闭上游默认思考；实际请求使用的思考档位还取决于聊天中的选择、适配器与接口支持。 “保留现有配置”表示不写推理字段，不会删除已有配置。参考目录的推理能力标记与具体档位已分开传递；能力标记只用于提示，不会作为未知宿主字段写盘。 ## 上游模型导入 选择已配置供应商 → 获取上游模型 → 勾选新模型 → 核对参考来源 → 预览参数 → 确认导入。 - 使用 `llm.discoverModels` 官方接口；自定义供应商由适配器查询上游，内置供应商可能直接返回已安装目录。支持范围由 DSH 适配器决定，不执行模型生成请求。 - 批量导入的模型 ID 使用精确匹配，不做编辑器推荐路径的前缀归一化。精确候选中优先选择已识别的开发商条目，其次相同供应商，再次唯一来源；仍有歧义时由用户选择，也可仅采用上游信息。自动选择用于参数参考，不自动认定价格为官方价格。 - 上游明确提供的名称和容量默认保留；名称等于 ID 时作为占位，允许参考目录补全。逐字段预览允许主动勾选冲突建议；取消勾选保留上游值。未匹配时不猜容量或推理档，依宿主默认值；导入后可继续编辑。 - 目录请求失败时显示警告，仍可仅导入上游信息。价格不随参数导入自动写入。 - 已配置模型标记为不可选。最多一次导入 500 个模型，后端一次 Settings 写入追加，不覆盖其他模型、凭据或 compat。 - 每次发现只处理上游返回的前 2,000 项，超出时显示截断警告；其余模型可在 DSH 原生设置中添加。超长的参考显示名忽略，不影响按 ID 导入。 - 预览快照有效期 15 分钟。确认保存需要相同配置 revision；期间配置变化必须重新获取。明确确认 maxTokens 的默认请求上限语义。 - 预设识别使用宿主 `listConfigurableProviders().declared`。内置供应商非空显式列表需本次授权；继承目录在单模型覆盖入口处理，不出现在导入目标中。DSH 将未设置的 models 规范化为空数组，内置供应商空数组同样按继承处理。 ## 内置模型单字段覆盖与恢复 在“内置模型参数覆盖与恢复”选择内置供应商，读取目录、选择模型，再读取参数。可从 Models.dev 选择建议应用到草稿，也可手动填写显示名、上下文、最大输出、输入模态与推理档。空白表示不修改，保存前必须允许本次覆盖；最大输出的设置和恢复还需确认默认请求上限变化。 写入路径为 `providers..modelOverrides..`，模型 ID 中的点和斜杠作为路径段整体处理。只写已编辑字段，保留 compat、凭据、其他模型和未编辑字段。显式非空 models 列表、自定义供应商、未知模型 ID 不适用此入口。 “恢复某字段继承”通过 Settings unset 移除该字段的用户覆盖。如果安装包或上层配置已有覆盖，会回到其值；否则继承模型目录。不会为了恢复而把目录值复制为新的固定覆盖。宿主发现接口未暴露的基础字段（例如继承的推理档）标记未知，不猜测。 配置变更后旧 revision 无法保存，需重新读取参数。当前内置覆盖入口只处理参数，不提供内置模型的价格编辑。空的覆盖对象可能由宿主保留，不影响字段继承。 ## 当前边界 - 编辑器只编辑显式 models 列表。导入支持已有显式列表和宿主确认的自定义供应商；尚不提供新建供应商、凭据编辑或继承目录替换。 - 编辑器推荐支持有限的 ID 归一化和开发商条目识别；导入与显式价格查询使用精确 ID。数据库的“官方来源”条目不等于实时官方认证。 - 推理“保留现有配置”表示不写该字段，不是删除已有配置；自定义档位写入 DSH 的 reasoningEfforts。 - 读取、保存失败在面板内提示；内置供应商读取失败可重试。revision 冲突时需要重新读取，不自动覆盖。 - 已保存单价当前用于展示和持久化；费用计算尚未实现，也不会自动接入 DSH 原生统计。 - 当前界面文案为中文，未提供多语言切换。 - 新写入的显示名最多 512 字符，推理请求值最多 128 字符，单价和倍率计算后的生效单价最多为 10 亿／百万 tokens。历史超限值仍可读取并修正。 ## 草稿与撤销 “高级比较”的勾选在编辑当前草稿时保留；切换参考来源或收到不同建议时重新初始化。已经与建议一致的字段不再重复应用。 保存模型只提交编辑字段，不会因为修改显示名而重建未编辑的输入模态或推理值。名称可清空；上下文、最大输出输入留空不删除已有值。普通模型编辑中的“保留现有配置”不等于恢复继承，内置模型使用专门的恢复入口。 内置覆盖的推荐以当前草稿为基础；撤销只恢复本次填入且之后未被修改的参数，保留手动输入及恢复继承的选择。推理覆盖值格式异常会提示修正，不在渲染期间直接抛错。 重新填入模型信息时，若推荐参数含 image，会补回仅文本配置中缺少的图片输入；已有图片能力不因建议缺失而移除。false、空或仅 off 的推理配置同样可能获得具体档位。这些变更先进入草稿，保存后写入。撤销本次参数填入不撤销价格草稿。 保存时后台列表刷新保留草稿与展开状态。切换模型或主动重新读取会使旧参数请求失效，旧请求成功或失败均不能覆盖当前模型。参数与价格分两次写入；参数成功而价格失败时会单独提示，并保留价格草稿供重试。 ## 常见问题 - **插件没有显示**：确认使用 `dsh plugin --profile desktop add dsh-model-kit` 安装到 Desktop profile，或通过插件管理界面安装本地预构建包；单独 `npm install` 不会挂载插件。完整退出并重启 Desktop，再核对宿主版本；不要仅凭“已启用”判断运行成功。 - **供应商没有模型**：自定义供应商可从上游导入；继承目录请使用“内置模型参数覆盖与恢复”。 - **没有参考价格**：核对数据源和币种；来源不足、有分歧或复杂计费时不会自动填入，可核对实际账单后手动填写。 - **保存提示配置变化**：其他操作已经更新配置，重新读取并再次核对修改，不自动覆盖新配置。 - **报价过期**：重新获取参考单价。已保存的价格不受临时报价过期影响。 开发验证方式见 [开发指南](development.md)。 ## 刷新与保存一致性 “重新获取参考单价”绕过目录 TTL，重新下载所选来源；普通填入仍复用缓存。参考价旁显示目录获取时间。切换价格数据源或开始重新查询时，旧报价票据及其未保存填入值失效，手动编辑和已保存单价保留。 模型保存不会更新价格草稿的 revision。发生价格冲突时，重试仍拒绝覆盖外部新价格；应先记下需要保留的草稿，再重新读取并核对。容量留空保留原值，仅清空容量不算有效修改；空显示名在模型列表回退到 ID。