goodbuddy/docs/features/model-connections/ui-design.md

模型连接请求定制 UI 设计

本文件定义模型连接请求定制的界面行为。全局视觉、表单和无障碍规则继续以 UI-DESIGN.md 为准。

信息架构

“自定义请求头”和“自定义请求体”位于当前 LLM 连接详情的最底部、连接兼容性摘要之前。 它们收纳在默认折叠的“高级设置”中，不新增页签或弹窗。只要其中一项无效，保存时自动 展开该区域并保留对应字段错误。每个编辑器使用可纵向调整大小的等宽文本域，默认值为 {}。

编辑与保存

• 请求头接受 JSON 对象，所有值必须是字符串。
• 请求体接受 JSON 对象，值必须是有界、可序列化的 JSON。
• 用户输入在编辑时原样保留。JSON 语法、类型、大小或保留字段无效时，文本域显示 aria-invalid 和就地错误；点击保存时阻止写入，并在现有设置错误区域显示对应连接。
• 保存成功后，编辑器使用两个空格缩进重新格式化已保存对象。
• 新连接从两个空对象开始。
• 保存前校验失败时，页头错误和对应字段错误都显示连接名称；模型接口 URL 同时标记 aria-invalid 并关联就地错误，避免只显示无法定位的“Invalid URL”。
• LLM 模型连接的分类标题和模型类型分段页签在内容滚动时共同粘附在内容区顶部；左侧连接 列表仍可独立滚动。
• 每个已保存或正在编辑的 LLM 连接提供“复制连接”。复制会生成新的连接名称和 ID，保留 地址、模型、协议、请求定制、认证方式及当前草稿 API Key。已保存的 API Key 通过 Main 进程的加密凭据复制路径保存，不回传到 Renderer；原连接和默认连接不改变。

兼容性说明

请求头说明明确列出直连、Continue、OpenCode 和 DeepSeek Harness 在原生支持范围内使用 该值。请求体说明明确列出直连、Continue 和受管远程 OpenCode 支持，并说明本地 OpenCode 与 DeepSeek Harness 不使用该值。

两项说明使用标签同行的 InlineHelp，交互遵循同行帮助规范。下列警告及字段错误保持常显。

同一区域还必须说明：

• Runtime、协议和认证生成的字段优先。
• 请求体只做顶层浅合并，不递归合并对象。
• 自定义值按普通连接设置保存，不能用于保存 API Key 或其他密钥。

无障碍与键盘

• 每个文本域有稳定的可访问名称，并通过 aria-describedby 关联兼容性说明。帮助关闭时保留隐藏说明，展开时替换为同 ID 的浮层，避免关联丢失或 ID 重复。
• 无效状态不能只依赖颜色，必须同时提供错误文字和 aria-invalid。
• 文本域遵循标准键盘编辑、选择、复制和粘贴行为；保存继续使用设置页唯一的主保存操作。
• 焦点边框、字体、间距、颜色和深浅主题全部复用全局语义令牌。

会话与项目 Runtime 选择

会话与项目选择器只提供直连模型和各 Runtime 入口，不再枚举每个 Runtime 与每个模型的 组合；Runtime 模型在系统设置中配置。已保存的固定 Runtime 模型选择继续保留，项目 选择器的选项与帮助文字均显示其固定模型，不能误报为跟随全局设置；用户可选择普通 Runtime 入口恢复跟随。该展示规则不改变模型解析、远程 Agent 协议或执行权限。

Harness 模型来源展示

DeepSeek Harness 的 platform 选项命名为“管理员环境优先，回退 GoodBuddy 兼容连接”， 不能沿用 OpenCode/Continue 的“Runtime 自有配置”标签。来源规则以 Harness 模型配置为准。 帮助文字收进标签同行的 InlineHelp，与选择器通过 aria-describedby 持续关联，并明确此选项不加载用户 profile 或 配置文件；无兼容 GoodBuddy 连接时仍可选择管理员环境来源。

概览使用 Main 提供的平台来源投影， 明确显示实际管理员预置模型，或“未配置完整的管理员预置”及已保存兼容回退的名称与模型； 没有可解析连接时显示明确空状态，但保留 platform 选项。不得从通用模型名称或 credentialSource 猜测管理员来源，也不得显示密钥或读取 Main 环境。

没有管理员覆盖且草稿兼容候选发生变化时，额外显示“草稿兼容候选（未保存）”，保留实际 已保存来源；草稿失去兼容连接时也明确说明。管理员覆盖生效时不把草稿回退显示为实际模型。 保存完成后以 Main 重新解析的投影刷新概览。