pikasTech-unidesk/.agents/skills/unidesk-sub2api/references/upstreams.md

添加上游

1. 在 master ~/.codex/ 准备带后缀的上游 profile 文件，例如 config.toml.<profile> 和 auth.json.<profile>；禁止覆盖默认 config.toml / auth.json。codex-pool configure-local 只重写默认消费端，不用于新增上游 profile。
2. 在 config/platform-infra/sub2api-codex-pool.yaml 添加 profiles.entries 项，指定 profile、accountName、configFile、authFile。
3. 如需要，给该项加 priority、capacity、loadFactor、trustUpstream、sentinelProtect、openaiResponsesWebSocketsV2Mode 或 upstreamUserAgent；capacity/loadFactor/信任退避/保护阈值的具体数值只写在 YAML。只有显式恢复 Sub2API 内置临时不可调度时才添加 per-account tempUnschedulable。
4. 如果新增账号会提高声明 capacity 总和，默认让省略的 pool.minOwnerConcurrency 继续按 capacity 总和自动解析；只有 YAML 已经显式写了该 override 时，才同步提高到不低于总 capacity，或删除 override 回到自动解析。
5. 跑 codex-pool plan，确认 profile 可读、base_url 和 API key 来源有效，且 stdout 未泄露完整 key。
6. 跑 codex-pool sync --confirm。
7. 跑 codex-pool validate。如果整体 validate 只被既有 manualAccounts.protected 缺失或未对齐卡成 false，不能把它归因到新上游；对新增 YAML-managed account 用 sentinel-probe --account <accountName> --confirm 和 sentinel-report 做窄验证，同时把手动账号漂移单独登记处理。

普通新增上游是 YAML 操作，不走 CI/CD，不改代码。只有需要渲染或校验上游 Sub2API 已经存在的可复用能力时才修改 scripts/src/platform-infra-sub2api-codex.ts；Sub2API 本身不支持的能力不在 UniDesk 侧魔改实现。

删除上游

删除上游只用于明确退役、凭据所有权变更或用户明确要求移除 provider；不能作为上游 5xx、compact 失败、限流、模型路由失败或哨兵隔离/恢复问题的处理手段。

1. 从 config/platform-infra/sub2api-codex-pool.yaml 删除对应 profiles.entries 项。
2. 跑 codex-pool plan 检查 desired 列表。
3. 跑 codex-pool sync --confirm --prune-removed。
4. 确认输出 accounts.pruned 只包含期望删除项。
5. 跑 codex-pool validate。

CLI 默认保留缺席账号，避免把可用性问题误处理成删除；只有显式 --prune-removed 才会 prune name 以 unidesk-codex- 开头且 extra.unidesk_managed=true 的缺席账号。