Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

16.5 KB
Raw Blame

供应商设置:统一身份、状态与操作

制定日期:2026-09-09。适用于现有与未来新增供应商,包括本机登录、独立登录、 API 接入、Cindy AI 与本地模型服务。本文定义统一合同;当前实现与验证边界见末节。 视觉正本见 DESIGN §4 Provider detail header。

新增连接根据 URL 识别并进入已有配置步骤的规则见 根据地址识别供应商。

1. 一个连接,一套顶部

供应商品牌与连接实例分开:同品牌的多个账号使用同一品牌图标,允许不同显示名。 改名不改变品牌、模型目录、凭证、限额或调用目标;绑定仍遵守 多连接的身份与隔离。

顶部固定呈现:品牌图标;连接显示名、接入类型;账号或来源说明; 连接状态、至多一个主要操作、一个更多菜单。不得因为 builtin/custom 分类而换一套交互。

  • 名称显示该连接的用户命名;未命名时使用默认名称。同品牌重复添加时默认名称帮助区分账号。
  • 详情顶部不重复显示模型数;数量保留在左侧供应商列表,按统一模型列表去重统计。
  • 接入类型说明实际使用方式,例如 ChatGPT 订阅、API、本地服务;不是程序内部的存储分类。 已取得实际套餐时,订阅标签显示 ChatGPT Pro、ChatGPT Plus 等套餐名;仅在套餐未知时回退到通用订阅名称。
  • 新增官方账号不因为存入自定义配置而显示“自定义”标签;Beta 等产品状态另有明确依据才显示。
  • 副标题优先提供账号识别信息,并说明本机登录或独立登录来源;无账号信息时仅显示来源。 API 连接显示去除凭证、用户信息及敏感查询参数的服务地址。本地服务显示可识别的运行位置。
  • 品牌根据可信品牌资料或已有域名解析规则确定,不从用户可编辑的显示名猜测;兼容 OpenAI 协议的第三方不自动视为 OpenAI 官方。

2. 状态与主要操作

连接状态、是否启用、用量是三个不同维度。用量读取失败不等于账号断开; 停用仍保留连接状态,以独立的停用说明及启用入口呈现。

连接状态 顶部主要操作 规则
未连接/未配置 连接/配置 登录或 API 表单由连接方式决定,入口位置不变
连接中 取消(支持时) 明示进行中;不支持取消时显示进行状态,防止重复提交
已连接 断开(支持时) 状态和动作分开显示;不支持断开的来源不伪造按钮
已配置但未验证 验证(支持时) 保存 API key 成功不能单独证明已连接;无验证能力时如实显示已配置
需要重新登录 重新登录或使用本机账号 本机共享授权可能需要打开来源 App;说明原因与实际影响
状态读取失败 重试(支持时) 保留最后已知状态并注明未更新,不能直接改成未连接

以上为语义名称;实际界面文案沿用术语表和本地化体系,不直接输出状态枚举。 首次读取无历史状态时显示读取中。失败说明、授权码及恢复指引进入顶部下方说明槽, 不能藏在按钮 tooltip 中。后台刷新不得清空已知身份或用量后再重建顶部。

3. 操作位置与影响范围

更多菜单顺序统一:重命名、编辑连接设置、停用/启用、删除连接;只显示确实支持的动作。 已有供应商特有低频操作仍放同一个菜单,按用途分组;删除位于末尾并与普通动作分隔。 编辑、删除不再作为新增供应商独有的裸图标并排暴露在标题右侧。

  • 重命名只改显示名。编辑连接设置仅出现于有可编辑连接参数的来源。
  • 停用只阻止该连接被用于后续路由,保留凭证与配置;启用恢复该连接,不替换账号。
  • 断开解除当前连接的授权使用,保留供应商条目与可恢复配置;不能将删除条目称为断开。
  • 删除移除可删除的用户连接及其专属配置;不删除历史内容,也不静默转绑其他同品牌账号。
  • 断开、删除的确认规则取决于真实影响,不取决于 builtin/custom。确认说明点名当前连接, 只说明在 Cindy 中不能再使用这份订阅或 API key。Cindy 不提供退出系统 Codex 或 Claude Code 账号的操作。
  • 断开的来源保留原连接 ID 与条目,原位置可以再次登录或配置;删除的来源不被后台发现自动恢复。
  • 独立订阅连接再次登录时允许选择其他账号或工作区,不锁定首次登录身份;成功后沿用连接 ID 与用户配置,后续使用该连接的请求使用新账号。 OpenAI 提交新凭证前退役该连接的旧运行实例并清理用量缓存;登录结果被接纳前取消会回滚凭证,接纳后的名称或模型刷新不再回滚已完成的登录。 自动生成的账号名称随新身份更新,其他自定义名称保留。回归见 codex-account-auth.test.ts 与 providerHandlers.test.ts。
  • OpenAI 独立登录由 Codex CLI 自动打开浏览器,Cindy 不再重复自动打开打印出的授权网址。等待登录时提供「重新打开登录页」手动入口,供浏览器未打开时继续登录;授权链接只在发起窗口的本次登录中临时保留,结束、取消或离开后清除,不写入日志或配置。
  • 改名、断开与删除的确认绑定打开确认框时的 Cindy 账号,账号切换后旧确认不得修改新账号。

4. 用量与扩展区域

供应商身份行固定;下方说明、订阅用量、账户资产与模型列表共用一个滚动区域,模型搜索和筛选工具行滚到顶部后吸顶。切换连接后回到新连接顶部;模型深链仍定位目标行。各供应商只提供数据和必要的专属操作。 配额、余额、重置时间保持各自真实含义,不为外观一致而虚构不存在的数据。 设置页复用用量卡片的紧凑嵌入呈现:各窗口默认以一行显示名称、进度条、剩余百分比与重置倒计时,窄窗口可换行。具体重置日期、趋势和窗口明细通过「用量明细」展开;余额、限额告警与数据过期提示保持可见。套餐在身份行已有展示时不重复占行;只返回周窗口时仍显示该窗口,套餐已知而窗口缺失时保留套餐信息。浮层用量卡片仍保留原有呈现。 OpenAI、Claude 和 Grok 的订阅连接都按连接 ID 读取,不按品牌名共用账号缓存;套餐名称与用量卡片共用格式化规则,不把模型专属促销额度当成整个账号的额度。 所有限额窗口和供应商摘要统一显示剩余百分比(100 减已用,限制在 0–100), 进度条填充及无障碍数值同步显示剩余;告警与节奏仍依据实际消耗计算。 Grok 产品消耗是共享池贡献,不是独立限额,不反算成产品余额,限额卡片仅显示共享池剩余。 历史费用、实际消耗明细继续保持原计量语义。 缓存回显及隔离遵循 统一模型选择与订阅用量规则。 用量刷新不占用连接操作的位置;读取失败保留缓存,断开或账号变化按权威事件清理。

5. 实现与验证边界

ProvidersSection.tsx 的 DetailHeader 统一渲染类型化状态、至多一个主要操作、 编辑菜单动作与末尾删除动作;不再接受任意 trailing 布局。连接状态、主操作和更多菜单 在同一组内布局,长名称压缩或换行时更多按钮不会单独掉到下一行。

  • OpenAI 本机登录与新增账号共用顶部;独立账号和其他 OAuth 复用 GenericOAuthHeader, 各自保留真实登录、取消和恢复适配。所有可改名来源共用名称弹窗,Main 只更新最新配置的名称。
  • Anthropic、xAI、API、本地服务和 Cindy AI 使用同一状态/动作槽位。API key 的存在仅显示 已配置;更换 key 收入菜单。Cindy AI 按既有资产模块合同保留凭据操作在菜单中的位置。
  • 本机 Codex、Claude、旧 Grok、API 连接支持改名和删除;本地模型服务支持改名及已有删除行为。 Cindy AI 仍按托管账号规则管理,不提供改名或删除。显示名在设置、选择器、提示和用量历史中同源。
  • 身份、资产与授权说明保留原适配。没有权威状态来源的读取失败/验证状态不在前端编造, 不通过额外登录探测推断连接是否有效。
  • 回归覆盖原有深链、只读本机凭证、恢复、资产和模型列表,以及新增 OAuth 菜单、 API 已配置、恢复覆盖旧连接状态、取消后的迟到授权结果。真实账号操作与双模式目检 需单独记录,不以组件测试或复用主题样式代替。

新增供应商应复用上述入口,仅补连接适配与确有必要的专属说明/资产内容。

6. 同品牌多个订阅账号

OpenAI、Claude 和 Grok 都允许新增独立登录账号。每次新增生成唯一连接 ID,凭证、刷新、模型发现、用量和断开操作始终绑定这份连接;任务不能凭品牌或显示名选择账号。 同品牌连接共用模型定义和已有 Harness 能力,账号发现只约束该连接的可用模型。重命名只修改显示名,断开或删除一份连接不影响同品牌其他账号及历史消息。 已有本机连接继续保留;新增 Claude 和 Grok 登录写入 Cindy 的账号专属凭证存储,不覆盖本机 Claude Code 或旧 Grok 连接。远程执行沿用各 Harness 已有能力边界,Grok 的 Pi 远程请求经主机代理使用所选连接,凭证不写到远端。

本机 Codex 连接的「断开」只停止 Cindy 使用该账号,保留本机登录凭证与历史记录;开发版与正式版一致。断开状态跨重启保留,自动发现不能重新启用。用户再次选择使用本机账号时恢复连接,无需网页授权。Cindy 不提供退出本机 Codex 账号的操作。

本机 Codex 供应商支持改名和删除:名称只用于展示,内部连接 ID 不变;删除先断开 Cindy 对该订阅的使用,再从供应商列表移除。显示名称与删除状态按 Cindy 数据所有者保存。添加供应商仍提供本机账号入口,重新添加后恢复显示;本机凭证与历史消息不删除。

7. 登录与管理文案

  • 新增独立订阅账号:统一「登录独立账号」。已存在的连接用「登录」,失效后用「重新登录」。
  • 复用系统登录:明确「使用本机 Codex 账号」或「使用本机 Claude Code 账号」。
  • API 入口统一「API key 接入」。保存成功表示「已配置」,不能声称已经验证。
  • 「授权」只用于浏览器权限确认、设备授权码和 OAuth 端点等确实涉及授权的步骤。
  • Grok 内置连接及独立账号支持浏览器回调和设备码两种订阅登录;设备码由 Cindy 显示给用户,用户在 xAI 授权页输入,Cindy 在本机完成轮询和凭证保存。Agent 可为当前 Cindy 账号启动内置 Grok 的设备码授权并查询状态,不接收长期凭证。
  • 状态统一「已连接/未连接/连接中」;管理动作统一「重命名/编辑连接设置/停用/启用/断开/删除」。
  • 断开保留连接以便恢复;删除不删除历史,也不承诺自动把原任务改用其他供应商。
  • 本机 Claude 与 Codex 均只撤销 Cindy 的使用许可;重新使用本机账号直接读取现有登录,无需新开浏览器。
  • 本机 Claude 刷新被服务端明确拒绝时,仅在现有绑定文件记录该次凭证的 SHA-256 摘要。 重启或手动断开不清除这个标记;同一凭证不能重新连接,来源工具更新凭证或更换账号后可重新连接。 不删除系统凭证,不新增凭证明文副本,不为正常手动断开后的恢复增加网络验证。

语音型号接入

  • 「添加供应商」保持一个入口。API Key 连接沿用选择供应商、连接、选择模型三步;在同一模型页分组展示语音模型、对话与其他模型,语音分组位于普通模型长列表之前。MiniMax、OpenAI API、ElevenLabs、百炼普通 API 提供语音参考型号,在已确认支持的地址默认勾选一个推荐型号,用户可以取消或仅添加语音型号。
  • 两个添加入口共用实际连接地址的推荐规则,不按预设名称或 Cindy 发行区域推断:公共 dashscope.aliyuncs.com / dashscope-intl.aliyuncs.com 推荐 qwen3-tts-flash;北京 workspace 推荐 cosyvoice-v3-flash;新加坡 workspace 推荐公共 Registry 已收录的 qwen-audio-3.0-tts-flash。北京 Token Plan 独立推荐 qwen-audio-3.0-tts-plus,不套用 workspace 的 CosyVoice 推荐;新加坡 Token Plan、美国公共地址及未确认组合不自动推荐或勾选参考型号,目录发现和手动添加仍可用。推荐遵循 #6660 的原生 HTTP 支持范围,不更换 origin、地域或密钥;返回连接步骤编辑地址后重新计算。已有保存型号与用户显示偏好不因新推荐改变。
  • 已有连接不常驻「添加语音模型」按钮。仅已确认支持的厂商 API Key 连接在「管理」菜单保留此入口,空模型列表也可使用;订阅、设备码、未知代理及停用路线不提供该入口。手动追加操作绑定连接 ID,追加用户选择的新型号;不重填密钥,不覆盖已有名称、协议、模型类型、开关和其他 runtime。Main 在原有供应商修改队列内合并最新配置,按当前预设投影后的有效地址校验弹窗快照,实际地址已变更则要求重新打开;预设补充目录地址不会改写存储值,不使用旧快照替换整个连接。
  • 用户手动刷新时,先合并接口目录;仅上述 API Key 连接的目标 runtime 目录获取成功、整个连接没有已保存的语音型号(含隐藏型号)时,按实际地址补一个默认显示的推荐参考型号。接口已返回语音型号、推荐 ID 已存在但被用户或目录声明为其他类型、鉴权或目录请求失败时不补。重复刷新不增加其他参考型号,不改已有开关;打开设置和后台刷新不补参考型号。补充成功提示明确称为「语音参考型号」,不称为接口发现或调用成功。 Main 在同一次保存中,用当前活动 Registry 对合并后的配置重新投影;本轮首次发现且仅由服务端资料识别的语音型号同样阻止补齐。分类默认值不写成接口实报或用户覆盖,界面以保存返回的补齐结果显示提示。
  • 订阅或设备码用户通过「添加供应商」建立独立 API Key 连接,不转换、不覆盖原连接。普通百炼 API 与 Coding Plan / Token Plan 入口分开;Token Plan 的语音建议按其官方型号范围独立维护,参考推荐不证明当前账号已开通或具有额度。
  • 普通厂商没有预置模型且目录获取失败或为空时,同时保留通用型号手填与语音建议;通用手填不强制设为语音。仅明确的语音接入流程或 ElevenLabs 这类语音服务隐藏通用回退。
  • 目录返回、公共参考和用户手填是不同来源。参考清单只描述添加建议,名称与能力仍继承公共 Registry;添加弹窗未选中的参考型号不写入账号连接,手动刷新仅按上述条件补一个推荐型号。目录明确返回非 TTS 能力时,不以参考清单把它恢复成语音。
  • 目录返回但未勾选的语音型号保留在连接目录中,默认隐藏,不出现在伙伴朗读选择器中。模型管理页为语音合成提供显示开关,可重新显示先前未勾选的型号;Main 的媒体可用清单复用伙伴朗读的目录、凭证与停用检查,保留隐藏但有资格的路线供管理。媒体投影保留该显示默认值;后续显式显示偏好按连接与 runtime 生效,显示偏好与停用、账号准入独立。已保存为伙伴朗读偏好的隐藏型号仍可恢复、试听、朗读和开始通话;设置中保留显示当前选择,其他隐藏型号不进入候选,也不自动选作默认。停用、凭证丢失或账号不可用仍阻止调用。
  • 获取目录和保存型号不等于调用成功或已获授权;不自动发起计费合成。音色、试听、逐句朗读属于伙伴语音设置,不进入供应商添加流程。两个添加入口的保存与设置说明统一放在语音模型分组内,对话模型的说明留在对应列表下方。Qwen / CosyVoice 的目录接入不替代各自原生执行器的交付和验证。