description: "在 Gestaltrun 中管理 CLIProxyAPI 账号和配额观测，并基于固定版本的 DSH 包构建独立产品 bundle。" kind: "package-bundle"

账号池

English | 中文

摘要

@gestaltrun/dsh-account-pool 在设置中管理供应商账号，并通过既有 LLM（大语言模型）服务提供可选择的池内模型。它支持 Claude、Codex、Antigravity、Kimi、xAI 和 GLM Coding Plan 接入。Desktop 产品组合包含此 bundle，Web 安装显式组合 @gestaltrun/dsh-model-center 和本 bundle，以提供完整模型设置体验。账号凭据保存在私有产品存储中，配额刷新不会改变账号调度或消耗 reset credits。

目录

• 使用此包
• 理解实现
• 构建与验证
• 模型体验
• 已知限制与延后工作

使用此包

页头的“账号池设置”为支持同一模型的账号提供“轮流使用”和“用完一个再换”。保存会持久化插件策略并重启所属引擎；成功后更新已生效标签并显示框架级提示。保存失败会保留所选项并在原位显示本地化错误。禁用、登录失效、冷却、优先级和排除模型规则仍限制账号选择。

设置页拥有登录、启停、字段、模型列表、名单读取和配额刷新。每个账号显示为一张卡片，包含可独立查看和复制的文件名、备注与邮箱身份、可调用状态、配额、折叠的请求记录和操作。提供商筛选只列出当前已有账号的提供商。“重新读取账号列表”只重读名单，不查询配额。账号操作完成后，框架级本地化提示会标明目标，离开设置页后仍可见；配额请求即使传输成功，也会按返回的已知、部分、不支持、未观测、失败或账号缺失结果提示，而不会直接当作读取成功。引擎启动中或不可用时，已知账号及其本地身份复制控件仍可查看，依赖引擎的操作保持停用；错误状态只开放“重试”重新读取名单。在 ready 状态打开的账号对话框会在引擎离开 ready 后停用依赖引擎的确认或提交操作，但会保留本地查看、复制、草稿和关闭能力，直至引擎恢复。在引擎返回登录信息之前，对话框会标明这是一个有超时上限的引擎请求，而不会把它显示成等待用户授权。随后，设备登录会显示固定引擎返回的授权 URL、用户码和过期时间。PKCE 登录会在引擎接收粘贴的回调后明确反馈，并继续轮询，直到令牌交换成功或失败。授权状态轮询会容忍 loginStatusErrorLimit 次连续传输错误，任何有效状态响应都会重置计数，因此一次短暂的 Host 或引擎中断不会丢弃提供方会话。用浏览器打开授权页会让 Host 通过系统浏览器打开 HTTPS 授权 URL。账号开关只记录用户是否允许调度。状态徽章另按“已停用、登录失效、整账号冷却或不可用、部分模型不可用、已启用”的顺序选择主状态；状态条保留所有安全的低优先级故障，并用本地化文案显示原因、状态码、重试时间、受影响模型和可选退避详情。本地倒计时归零后只提示可以重新检查，在“重新读取账号列表”返回新快照前不会宣称账号已经恢复。未知、不支持、失败、部分和过期配额观测保持区分。

OAuth 账号的登录失效状态条和更多菜单提供“刷新登录凭证”。Host 结合引擎观测到的真实凭据类型与私有 refresh token 存在性投影能力；API-key 账号没有 token 刷新入口，OAuth 凭据没有 refresh token 时提供重新登录。确认框标明账号，初始焦点位于取消。刷新按已观测文件名和私有引擎索引选择目标，抑制重复提交，并在读取名单后报告结果；HTTP 200 本身不表示账号可调用。凭据被拒绝后进入标明原账号、选择相同提供商的登录流程。网络或引擎失败保留最近数据，并提供重试或重新登录；刷新后的状态无法读取时保持待确认。关闭弹窗或离开设置不能撤销提供商的令牌轮换，也不会重开页面或把晚完成结果改给其他账号。完成结果保留在框架级提示中。

接入先选择提供商，再进入浏览器授权或 GLM 密钥表单。GLM 支持个人与团队账号；团队账号必填组织 ID，项目 ID 可选。非法 ID 会显示相邻错误并保留草稿。从进行中的授权返回时，先等待 Host 结束该操作，再在同一弹窗显示提供商选择。登录失败可原位重试；打开浏览器或接受回调都不会在最终 Host 状态到达前宣称完成。凭据保存后，弹窗会保留到账号列表读取成功。读取失败会说明凭据已经保存；“重试”只重新读取列表。每次请求发送前都会分配其接入身份。关闭、重新打开或返回会使先前表单的操作退役，因此晚到结果或状态更新不能关闭后续表单，也不能改动其草稿、错误或忙碌状态。结束请求只针对该身份，不会取消另一项当前操作。

账号设置把基本、调度、网络与模型字段分组，操作固定在页脚。对话框不展示认证文件的 JSON。读取和保存失败根据安全错误分类显示本地化提示，不展示 Host 诊断原文。非法整数优先级、正在使用的加权策略权重、代理 URL 或 HTTP 请求头会显示相邻错误并保留草稿，不会保存。只有已读取的生效策略使用权重时，权重才可编辑；只读权重不会进入 patch，可编辑权重接受有限非负数，不新增业务上限。代理与已有请求头保留明确的保留、替换或移除意图；秘密请求头只显示“已配置”。“复制账号信息”只复制经过白名单脱敏的 INFO，即使表单正在草拟替换凭据也相同。不在当前目录中的已选精确排除模型 ID 会保留。“模型列表”弹窗说明这是提供商级目录，不代表账号的认证或模型可用性结果。模型目录搜索在本地筛选 ID、名称与归属，不请求提供商；每行复制该模型 ID。账号写入绑定已观测身份。若同名文件被另一账号替换，旧删除确认或字段草稿会保留并显示警告，不能保存；请关闭后从当前账号重新打开。Host 也会在队列执行写入时再次核对该身份。

存在本地账号或模型冷却记录时，状态条提供“清除冷却”，更多菜单也保留同一入口。确认框标明目标账号，默认聚焦“取消”。操作只清除本地重试状态；上游额度、失效凭据和停用设置保持不变。冷却记录缺失或未知时，更多菜单入口不可点；只有凭据失效时不提供冷却恢复入口。操作结束前会阻止重复提交。失败后保留卡片和确认目标，并显示本地化重试提示。重置确认成功后会先重读引擎，再发出框架级结果提示；可用性以重读为准，上游再次限制时仍会重新进入冷却。

Codex OAuth 账号在刚观测到的正数重置次数旁提供“兑换重置”。次数为 0、未知或过期时，入口禁用并解释原因。确认显示账号、实际次数变化与消费不可撤销提示，默认聚焦取消。只有确认才消耗机会。重置成功或收到已兑换回执后，Host 清除本地冷却并重读次数与配额；账号可用性仍由最新引擎观测决定。消费失败绝不清除冷却。部分成功明确说明机会已消耗，只提供尚未完成的清除或重读步骤。关闭已提交的操作不会取消操作、改变晚到结果的目标或再次消费。

每个引擎 generation 只继承 Host 已解析的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 与 NO_PROXY 变量，包括对应的小写形式。固定管理接口的 api-call 传输会主动忽略环境代理变量，因此未配置账号代理的配额探测会接收 Host 为该提供方 URL 解析出的路由。这样会保留 NO_PROXY 直连规则；账号代理或 direct 设置保持更高优先级。其他环境凭据仍被排除，Host 管理与推理请求保持连接到 generation 的精确 127.0.0.1 origin。

Kimi 的用量汇总对应提供方的七天配额；响应省略窗口元数据时，时间指针使用该周期。有效的显式元数据优先；元数据无效或缺少重置时间时不显示时间指针，显示标签不用于推断周期。月度额度单独列行，不会与周额度相加。已有 kimi.ai 凭据沿用相同展示，由 Host 私下选择固定的国际站用量接口。

配额解析跟随管理中心 v1.25.6（5aa1ad64），来源及适配差异记录于配额 NOTICE。Codex 分别显示精确十进制 Credit 余额、明确报告的无限标记、重置次数和实时订阅到期时间；Pro 200、Pro 100、Team 与 Business Premium 标签表示套餐，不表示配额重置时间。xAI 显示一个周额度池及其共享产品用量，并单独显示美元账单、按量计费、预付余额和账期结束时间。Claude 根据 profile 的标记显示 Pro/Max/Team，Cloud session credits 与额外用量以美元表达。余额没有已知正上限时以及无限 Credit 均不显示进度条；缺失读数保持未知。额度填充和时间针都表达剩余比例，保留 30/70 阈值，并以用户本地时区显示来源提供的精确重置时刻。刷新失败时保留上次成功值及其采样时间，包括只有余额的结果；本次尝试仍单独标记为失败。GLM 继续使用引擎既有的配额信号。配额错误、标签、组名、说明和套餐标识在展示前剥离 URL 查询串与片段，并隐去参数赋值和凭证形态文本。已知套餐名称由 locale 字典持有。

Bundle 补丁 在隔离 scope 中选择本地 subprocess 实现，并把 Desktop 账号存储在 $DSH_HOME/desktop/account-pool。Web profile 必须选择自己的绝对 stateRoot。并发进程不能共享同一状态根。profile/plugin 安装激活 bundle，仅复制目录不会激活。

账号文件（包括 GLM Coding Plan JSON）存放在引擎 auth-dir。引擎聚合 /v1/models 列表决定模型可用性；提供方 definitions 为匹配行补充能力信息，单个 definitions 端点不可用时仍保留聚合目录，并在后续刷新时重试元数据。发布的容量是模型在列表与各通道 definitions 中的最大能力：上下文窗口取最大的 max_context_window，某行缺少该字段时取其 context_window；输出上限取最大的输出 token 上限。definitions 按固定通道顺序（Claude、Codex、Antigravity、Kimi、xAI、GLM）合并，列表缺失的其他字段由该顺序补齐，因此账号登记顺序不会改变已发布模型。max 思考档位在模型列出 max 时发送 max；仅在未列出 max 时由 ultra 补位。definitions 的默认思考档位仅在属于已发布档位时生效。GLM 卡片标明提供方级模型列表，并把不可用的健康/历史值显示为未知。

理解实现

聊天适配器使用 pi-ai 1.0.2 的公开 models 入口与惰性加载的 OpenAI-completions API；每个引擎 generation 拥有其推理 fetch 与取消操作。

插件 Config 接受 routingStrategy: round-robin 或 fill-first；ConfigEditor 持久化普通 Config，Loader 替换提供方后，supervisor 为下一代引擎写入 routing.strategy。只有不存在先前引擎配置时，省略此字段才默认使用“轮流使用”；否则保留先前实际生效的策略。别名与回退遵循固定引擎的选择器归一化：ff 和 fillfirst 保留“用完一个再换”；wrr 和 weightedroundrobin 保留已有加权策略；其他字符串选择“轮流使用”。保留的加权策略会显示为已有设置，不提供第三个单选项。显式保存新选择会替换该旧策略。持久化配置损坏或不可读取时，解析失败。路由不使用管理 setter，且只在引擎代次 ready 后报告已生效策略。

路由保存重新挂载 Host 条目时，Client 观察保留同一份快照存储。保存结束后，Client 关闭旧 watch 并打开当前 watch；“重试”也能替换已终止的 watch。只有 watch 帧更新账号快照，因此旧命令响应不能替换较新的状态。替换 watch 保留 controller 和账号身份，卸载则等待旧观察与命令停止。

一个产品包拥有账号服务、引擎 supervisor、管理映射、LLM 适配器、Remote 控制器和 Client。五个 exact optional 资产包为受支持的平台和架构组合携带已审 Go 引擎；它们不是 bundle，也不增加产品版本。每代拥有独立回环 HTTP 凭据和取消能力。关停撤回模型路由、等待请求结束、停止所属进程树，并仅删除代次文件。前序清理失败不会跳过后续静默等待、进程终止、退出确认、传输关闭或满足条件的 generation 删除；清理结束后，supervisor 会报告所有失败。

账号文件仍由引擎拥有，存放在 auth-dir。GLM 身份来自引擎花名册。Host 打开 HTTPS 授权 URL；渲染器不打开。回调 POST 成功后，Host 快照会记录 callbackStatus: submitted，同一操作继续通过 get-auth-status 轮询；设备流程不接收回调。登录失败只以不含凭据的类别进入快照和日志；可操作提示由 Client locale 拥有。名单解码会拒绝非法可用性字段，把 null 冷却列表视为未知观测，并把未识别原因映射为通用类别；原始 status_message、提供方响应正文、URL 参数和凭据绝不会进入 Client 快照。

Host 的 clearCooldown(ref) 只通过已提交名单中的私有 auth_index 映射，并用该索引提交 POST /v0/management/reset-quota。账号名称和下载的凭据元数据不能提供此映射。Host 私下校验重置响应，重读名单、刷新模型目录，并保留既有配额观测。Remote 结果只包含安全快照，不包含返回的索引或模型重置列表。调用方取消和 generation 退役都会撤销操作。若重置成功但名单重读失败，命令报告这一有限结果，在再次读取前保留最后提交的名单。模型目录失败会撤回模型适配器，等待后续刷新；已成功重读的账号状态仍被保留。

Host 通过固定引擎既有的 api-call 传输准备和执行 Codex 重置。每个意图保留一个私有提供方请求 UUID，提交前持久化记录阶段。独占 stateRoot 中的版本 1 codex-reset-operations.json 只存有界身份摘要、关联 ID 和进度，不存凭据或提供方正文；写入先同步私有临时文件，再原子替换。台账不可读取、超限或版本不受支持时，消费被阻止。Remote 只返回独立的不透明操作 ID，调用方显式选择确认、查询、重试清除或重读步骤。重启后，中断的消费仍待核验；中断的清除和重读只恢复对应步骤。响应不明确时先只读查询。固定提供方协议列出可用次数，但没有按请求查询回执的接口，因此次数变化不能确认该意图，也不能授权再次消费。通过协议之外的方式核实结果前，它始终只允许查询。

bundle 在模型中心行上预约 gestalt-account-pool。账号池把目录字段发布到该行 profile 配置的 providers.gestalt-account-pool.models，并拥有对应运行时适配器，因此模型页会列出池内模型及其输入类型和思考档位。来源刷新会替换目录拥有的模型字段手动编辑，同时保留其他提供方和提供方字段。空目录保留可配置提供方条目且 models: []，并撤回运行时路由。新引擎要先加载账号的认证文件，才会列出已启用账号的模型；因此只要有已启用的账号，引擎返回的空目录就不改动已保存的目录，路由等下一次刷新再发布。没有显式输入类型的模型继承提供方的 defaultInput；该列表也缺失时继承文本。引擎凭据不会进入设置。池内模型在入口保留 OpenAI 兼容的 system 角色，因此 GLM Coding Plan 不会收到 developer。

已接受架构拥有替代方案和产品专属修改范围。配额解析器是观测模块，来源声明在 NOTICE。Host 快照是业务状态来源；生命周期和传输测试验证其外部效果。

构建与验证

独立的 product/ 工作区从打包归档安装 DSH 对等依赖（产品工作区）。产品构建、类型检查和打包命令对照 UPSTREAM.json 中的已核验基线运行范围检查。现有官方 DSH 包清单仅可将版本提升为与仓库根一致且更高的 SemVer；依赖、脚本和源码修改仍须属于已批准范围。范围检查准入账号池 teardown 所需的 LLM 注册实现、两项 owner 测试及配对 README 记录；相邻 LLM 文件仍受保护。客服托管 S0（#179）另以精确文件登记 bundle Workspace/Session 归属与引用保留、公开 UI 组合及其消费者、测试、包文档和生成目录；相邻文件、agent-loop 修改、上游源码导入和依赖覆盖仍不获准。类型检查会先发出模型中心的公开声明，再让本包 Host 编译器读取。产品测试会先构建两个包，因此 Host、Client 和模型中心测试能解析已发布的 lib/ 入口。 资源录入 T0（#225）准入精确的 Session 页签导航与几何实现文件、消费测试及生成目录；相邻源码仍不获准。Session 快照身份中的回执标识符 token 化（#229）仅准入其身份实现、回归测试和配对 README 记录；相邻快照文件仍受保护。

wrapper 使用独立的普通发布版本；exact optional dependencies 选择五个平台引擎资产版本。产品 pack 和 pack:dev 调用 pack:account-pool，构建主包与引擎，显式选择全部六个包，并将归档写入 product/dist。UPSTREAM.json 独立钉住已审引擎 tag 和来源 SHA。

产品构建生成 Host 入口、非空严格 Remote 贡献，并编译 Client factory。引擎安装器下载 UPSTREAM.json 钉住的已审 CLIProxyAPI 发布归档，连接被重置或服务端出错时最多尝试三次，核验每个归档和二进制摘要，并为每个目标写一个资产包。运行时通过该包公开的 package.json 导出解析资产，并在 spawn 前核验精确包版本、操作系统、架构、发布 tag、来源 SHA、文件名和二进制摘要。其他 npm 包元数据不影响引擎身份校验。缺少资产或身份不匹配会停止启动，不会下载、搜索 PATH 或回退到内嵌副本。发布仓库是公开的；product 通道把工作流的 contents: read token 作为 DSH_ENGINE_READ_TOKEN 传入，安装器通过 GitHub API 从钉住的发布元数据按名称定位每个归档，并以 Accept: application/octet-stream 从固定的 API asset endpoint 下载。私有仓库则改传具备 contents: read 的凭证；未设置该变量时使用公开的直接 release URL。community/cliproxyapi 仍是该提交的源码 gitlink。

原生 Desktop 交互、已认证供应商推理和单元 fixture（测试前置数据）属于不同证据路径。fixture 账号文件可以验证重启持久化和管理，不能证明供应商认证或真实密钥接入。

模型体验

通过注册的 gestalt-account-pool LLM 路由间接产生影响。模型选择和 reasoning 默认值在流开始前进入请求元数据。账号凭据及配额观测不会新增模型可见提示词内容，也不改变 Session 格式。

已知限制与延后工作

• 包安装通过 npm optional dependency 规则选择当前平台资产。部分包管理器 metadata 或 tarball 失败仍可能留下主包；此时启动会报告资产缺失。Desktop 目标过滤与签名打包仍是独立发布工作。
• 真实 OAuth 和已认证推理依赖可用供应商账号及网络。空池启动和 fixture key 不能证明这些结果。
• GLM 配额观测来自引擎的 auth-files 信封。Host 只解析该信封，不自行探测 GLM 用量端点。
• 签名 Desktop 发布、公证和更新发布需要各自的发布环境及授权。

开发笔记

在安装及原生验收证据完成前，此包仍是开发候选。遗留的 glm-accounts.json 会在获取锁时一次性迁到 auth-dir。