交互与设计约定
本文维护公开版当前有效要求。 功能验证见 测试清单。 开发过程见 开发与测试流程。 公开范围以 产品定义 和 公开边界 为准。
共同规则
- 保留用户最后一次选择的服务、模型、账号、开关和草稿。
- 目录失败、离线、迟到结果和切页不得撤销新选择。
- 保存、客户端写入、运行时生效和真实生成分别反馈。
- 本地保存不依赖目录、额度或能力探测。
- 服务切换后的目录等待最多占用 2 秒前台时间。
- 到期恢复操作，并保留真实后台进度。
- 保存失败保留意图和草稿，提供对应重试。
- 取消不继续执行，返回恢复原上下文和滚动位置。
- 不自动关闭或启动正常客户端。
- 外部文件变化不强写，提供明确处理入口。
配置与客户端
- API、Coding Plan 和订阅按实际身份分别管理。
- 同类或同名连接使用稳定 ID 隔离，显示用户名称。
- 新安装没有连接，选预设和预填表单不创建连接。
- API 配置只显示名称、URL 和 Key 等必要字段。
- Key 默认隐藏，有内容才显示一个可临时查看的入口。
- 关闭或切页重新遮住 Key，保留草稿与光标。
- 保存成功关闭对应编辑卡片，并显示具名通知。
- 已保存配置不依赖 Key 是否为空。
- 确认未安装、未保存或未登录时，卡片文字和图标略微淡化。
- 读取失败和未知状态保持中性，卡片仍可操作。
- 自定义和导入入口保持正常颜色。
- 添加页面共用 API 服务、订阅账号、我的配置和客户端管理。
- 检测、下载、添加、接入和真实代理支持分别说明。
- Desktop 与 CLI 按产品归并，Pi 与 oh-my-pi 分开。
- 客户端移除只隐藏入口，保留模型配置，不卸载客户端。
- 一个 Trace 来源显示名称，多个来源显示 Tabs。
- API、Coding Plan 和订阅共用卡片状态样式。
- 官网和安装链接对应真实产品、平台与架构。
- WorkBuddy 和 Qwen 等入口优先使用官方说明。
- 导入任务统一称为“导入配置”。
- 预览不显示 Key；用户确认后才写入目标。
- Magpie、CC Switch 和客户端来源保持只读。
- 不导入订阅刷新令牌；导入不激活服务。
- 来源或目标在预览后变化时，提示重新检查。
- 已有连接与外部字段保留，同名项目可编辑名称。
模型与协议
模型菜单只列实际目录，不提供手工输入型号入口。
已有目录外、自定义或下线型号保留并标记。
不自动替换型号，也不把下线型号重新加入菜单。
服务商有效声明逐字段优先，明确 false 和空推理等级保留。
普通能力缺项由 models.dev 补充，并记录来源。
旧内建表和 LiteLLM 不补造普通能力或参考价格。
已核验官方资料和 LiteLLM 只补必要协议。
明确 Responses 时优先直通，否则使用连接实际协议。
不按品牌或型号名称猜测协议。
Claude 原生 Messages 不标为协议转换。
Desktop 别名转发按实际路由显示“需 Trace”。
标签、保存提示和实际路由共用判定。
刷新失败保留成功缓存和选择，并提供重试。
迟到目录不覆盖新连接、模型或输入。
目录、地址、Key 和型号属于同一连接。
明确非对话用途不列入聊天菜单，视觉对话保留。
普通 404、鉴权或额度错误不冒充下线。
Qoder 使用当前账号的官方自定义模型向导。
手动接入显示 Gateway 地址和非秘密占位密钥。
不复制服务商 Key，也不把下载目录当作自动接管能力。
不按服务品牌禁用生图或过滤客户端生图命名空间。用户开关保持有效，服务返回实际能力和错误。协议无法无损转换时明确报错，不静默删除工具。
账号与自动服务切换
- ChatGPT 分官方账号登录和 API 授权。
- 官方渠道统一称为“ChatGPT 官方登录”。
- 显示姓名或邮箱，不添加头像、套餐或当前账号标签。
- 来源客户端负责续期，导入保存身份引用。
- 不克隆刷新令牌，不复用其他账号的旧额度。
- 添加账号不自动切换服务或模型。
- API 授权退出后移除展示行，失效授权仍可重新登录。
- 同一授权组只添加一次，保留顺序和账号选择。
- Deck 自有凭据使用权限受限的私有文件和原子写入。
- 未知额度不显示为零，重置时间以真实返回为准。
- 身份改变或失效时清理旧读数。
- API 没有额度来源时，不显示订阅额度或依赖它的策略。
- 官方和 API 两组独立保存，策略只新提供用完再换、剩余额度最多。
- 会话亲和不因页面排序改变，已有明确暂停需用户恢复。
- 服务切换位于我的配置的增强功能，默认关闭。
- 关闭隐藏顺序和添加入口，保留内容；开启恢复。
- Codex 与 Claude 独立保存，型号沿用模型页。
- 全部可用账号确定耗尽后，才按已开启策略换服务。
- 普通限流、身份或网络错误不跨服务重放。
- 已有输出、工具执行或不确定结果不盲目重放。
- 保存失败保留最新顺序和型号，并提供重试。
- 登录由已实现的正式客户端或官方授权完成。
- Grok、Copilot、Claude 和 Cursor 分别保持各自身份。
- 授权取消和错账号不能覆盖原凭据。
Trace、记录与阅读
- Trace 开关、受管路由和 Gateway 状态保持一致。
- 开启后用新对话验证，旧绑定单列。
- 切服务续接同一测试线程，不能另开成功对话代验。
- 同一原生线程不拆分，同首句的不同线程不合并。
- 标题、预测、预热和辅助请求不冒充主回合。
- 侧边聊天和 btw 跟随客户端真实线程与父子证据。
- 淡色命名标记仍为设计要求，当前不声明已实现。
- 客户端原请求、转换后上游请求和两侧响应分开。
- 工具 ID、顺序、可携带历史与不完整流真实保留。
- 不补造前史、完成事件或未知用量。
- 首次进入会话打开最新请求。
- 阅读中新增请求不改变位置，用户可以从头查看。
- 返回和刷新恢复选中请求与滚动位置。
- 关闭仪表盘窗口后清空阅读记录。
- 首批加载 200 条摘要，接近边缘提前加载邻页。
- 详情按选中请求读取，字节预算下分页仍连续。
- 会话列表保持单行，日期与时间同行，不显示 LIVE。
- 长标题和型号省略，悬停可查看完整内容。
- 失败主回合在标题同行显示 ERR。
- 费用和操作固定右侧；模型栏紧凑，会话栏优先留宽。
- 返回入口位于左上，右上可打开对应日志文件夹。
- 已知金额与 Token 正常显示，包括已知 0。
- 小额金额精度一致，不加星号、部分或未计价说明。
- 完全未知显示“—”，失败缺少计费用量时不产生已知金额。
- 原始用量和失败原因保留在请求详情。
- 价格与汇率按捕获冻结，缓存和推理不重复计算。
- 命中率按可靠请求的输入 Token 加权，缺项数量保留在数据中。
- 订阅参考费用与真实账户扣款分别说明。
- 新配置默认 1 GB 自动清理，已有明确容量保留。
- Trace 正文与 Token、费用统计独立保留。自动清理只删正文。
- 仪表盘手动删除默认保留统计，确认框可额外勾选删除对应统计，默认不勾选。
- 四个配置页签共用固定弹窗位置与尺寸；订阅项较少时保留空白。
- 0 GB 清完成正文并保留用量，后续请求继续累计。
- 额外清历史统计需要明确选择，默认不勾选。
- 在途旧请求不能回填已经清掉的统计。
- 手动索引修复先备份，不改原 JSONL。
- 预览后索引变化、文件占用和缺失分别反馈。
界面与窗口
- 全局叠层只用样式变量，Toast 高于所有应用弹窗和菜单。
- 通知共用单槽，显示后计时，重复合并。
- 错误提供可执行入口，退出动画不阻塞队列。
- 最近失败与当前问题、Toast 分开，普通成功不清除较新的失败。
- 页面卸载后的迟到结果不新增无关失败。
- 主窗、仪表盘与 Viewer 的语言和主题同步。
- 深色、浅色、跟随系统保持全应用一致。
- 手动选择优先于系统变化，快速操作保留最后意图。
- 使用留白、网格和文字层级，不增加中点或装饰分隔线。
- 控件轮廓、焦点反馈、数据标记和调宽把手保留。
- 窄窗口和长表单可滚到底，按钮不被遮挡。
- 键盘和鼠标均可操作，关闭弹层恢复焦点。
- 尊重减少动效，不增加阻挡连续操作的整页动画。
- 主窗托盘行为与仪表盘关闭分开。
- 仪表盘关闭释放窗口，全屏不留下空白 Space。
- Trace 外观面板的内部操作不触发页面波浪。
- 首次引导检测只读，用户选择后才导入。
- 导览依次讲配置、模型、按需 Trace 和仪表盘。
停止、修复与交付
- 普通切换保留活动请求，工具等待提供继续等待和明确强停。
- 停止恢复直连、清理受管账本并关闭代理监听。
- 设置保存冲突不应阻止先恢复安全路由。
- 修复保护外部代理与外部修改，不自动切换用户选择。
- 改目录按暂停、更改和恢复执行，失败保留目标和重试入口。
- 仅重置 Deck 时不关闭其他客户端。
- 涉及核心配置时先确认具体程序和范围。
- 当前公开版没有旧发行版本兼容需求。
- 不添加内部旧数据、旧凭据或旧更新源迁移。
- 正常重启保留本版数据，未来原生更新另行验收。
- 构建、推送、安装和发布分别记录。
- 更新只用独立 GitHub Releases，不回退到其他渠道。
- Windows 替换后启动失败保留新版和手动入口。
- macOS 人工 DMG、签名、公证和实际更新分别验证。
- 所有结果绑定源码、包哈希、平台和客户端版本。
- 未验场景如实保留，不以合成服务或旧包成功代验。