---
id: T-681
title: 自定义网关模型名称重命名
phase: 5
deps: [T-677, T-680]
status: TODO
created: 2026-07-21
---

# T-681 自定义网关模型名称重命名

## 问题 / 背景

设置页的「自定义网关」模型清单当前只有「新增」和「删除」。用户发现模型名称写错或希望调整命名时，只能重新新增一条模型并手动复制连接信息；若该模型被选为标题或图片默认模型，还可能留下失效的默认引用。

现有「保存」会连同模型连接参数一起写入，虽然技术上可编辑名称，但不适合作为清晰的名称管理操作，也不会迁移 `ai.default_text_model`、`ai.default_image_model` 对旧名称的引用。

## 方案

- 在自定义网关模型选择框右侧保持「新增」原位置，并在其右边、删除按钮左边新增「重命名」按钮，顺序固定为「新增」「重命名」「删除」。
- 仅在当前选中模型且没有连接测试任务运行时启用「重命名」。点击后用中文输入对话框显示当前名称作为默认值；取消不改动任何文件。
- 新名称去除首尾空白后校验：不能为空、不得与其它模型重名；校验失败以中文提示并保持当前选择和模型数据不变。
- 重命名只改模型 `name`，保留类别、启用状态、URL、模型 ID、API 类型、超时、额外参数和本地 API Key；不得在状态栏、弹窗或日志显示 API Key。
- 成功时立即写入 `ai_models.json`，并同步迁移当前配置中精确匹配旧名称的 `ai.default_text_model`、`ai.default_image_model`，立即写入 `config.json`。两份配置任一写入失败时向用户显示中文错误，不伪报成功。
- 写入成功后刷新模型清单并继续选中新名称；标题/图片默认模型下拉框显示新名称，状态栏显示“AI 模型已重命名：旧名称 → 新名称”。
- 为避免名称管理逻辑散落在 GUI 中，`appconfig` 提供可复用的重命名操作或等价的受控更新接口；其行为必须保留原模型字段并执行唯一性校验。

## 验收要点

- [ ] 自定义网关的模型操作顺序为「新增」「重命名」「删除」，默认网关面板不增加该操作。
- [ ] 选中模型后可重命名；无模型或连接测试运行时按钮不可用；取消输入不产生写入。
- [ ] 空名称、重复名称均不能保存，提示为中文，原模型及默认引用不变。
- [ ] 重命名后原模型的全部非名称字段（含 API Key）保持不变，新名称在模型清单、当前选择和默认模型下拉框中立即可见。
- [ ] 若标题/图片默认模型原先指向旧名称，对应默认引用迁移到新名称并持久化；未指向旧名称的引用不改变。
- [ ] 程序重启后模型名称和默认引用仍一致；状态栏、对话框、测试输出不泄露 API Key。

## 测试与文档

- 在 `tests/test_appconfig.py` 覆盖模型改名、重名/空名称拒绝和字段保留。
- 在 `tests/test_gui.py` 覆盖按钮顺序与状态、确认改名、取消、重名拒绝、默认标题/图片模型引用迁移及持久化回读。
- 更新 `docs/routes.md` 的设置页自定义网关模型管理说明。

## 验证

```bash
py -3.10 -m unittest tests.test_appconfig tests.test_gui
py -3.10 -m unittest discover -s tests
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
```

## 边界（不改什么）

- 不改默认网关、cmhub URL/API Key/别名、模型调用、余额查询或商品套图来源选择逻辑。
- 不改变模型类别、API 类型、连接参数、超时语义或 API Key 的本地保存方式。
- 不新增批量重命名、模型分组、导入导出、在线同步或删除模型时自动替换默认引用。
- 不改 Chrome/CDP、采集、AI 生成、更新蝦皮或打包逻辑。

## 关联

- T-677：生成网关来源选择与自定义网关模型配置。
- T-680：设置页网关来源单选框，保持现有同行布局和保存语义。

## 执行记录

- 待实现。