feat(openai): reuse pinned accounts for standard model discovery

openspec/changes/codex-manifest-pinned-accounts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-04

openspec/changes/codex-manifest-pinned-accounts/design.md

@@ -0,0 +1,98 @@
+## Context
+
+动机见 proposal.md。与方案相关的现状：
+
+- Codex Model Manifest 入口是 `OpenAIGatewayHandler.CodexModels`：先尝试用账号模型映射本地生成；否则循环 `SelectAccountForModelWithExclusions` 选账号、`FetchCodexModelsManifest` 拉取、`CompleteAPIKeyCodexModelsManifestForClient` 补全、`MergeGroupConfiguredCodexModels` 做分组过滤与 ETag。
+- `FetchCodexModelsManifest` 对 API Key 账号走 `fetchCachedAPIKeyCodexModelsManifest`（30 秒新鲜、5 分钟乐观、单飞后台刷新），对 OAuth 账号直接请求上游且带 agent identity 任务恢复逻辑，不缓存。
+- 分组配置落地链路：ent schema → SQL 迁移 → `service.Group` → `group_repo` 创建与更新 setter → `api_key_repo` 分组字段投影与 `groupEntityToService` → 认证快照 `api_key_auth_cache.go` 结构体及 impl 两处映射 → 管理端 DTO / mapper → `admin_group.go` 创建与更新 → 分组复制。`models_list_config` 是完整样板。
+- 前端 `GroupsView.vue` 已有 7000 行；模型路由的账号选择用「标签 + 搜索输入 + 下拉」内联实现，`Select.vue` 仅支持单选。`components/admin/group/` 下已有抽出的表单片段组件（如 `ReasoningEffortPolicyFields.vue`）。
+- 后端管理端账号列表接口支持 `platform`、`group`、`search` 过滤。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 固定账号模式的运行时逻辑放在 service 层，handler 只做分支与错误映射。
+- 合并逻辑是纯函数，可独立单测。
+- 缓存策略只有一套实现，OAuth 与 API Key 账号共用；固定账号模式不引入第二层分组级缓存。
+- 新字段在所有分组加载路径上都可见，特别是认证快照与 API Key 投影。
+
+**Non-Goals:**
+- 不改动调度器逻辑与普通请求的账号选择。
+- 不为账号解绑或删除增加对该配置的级联清理，运行时容忍失效 ID。
+- 固定账号关闭时保留本地生成 manifest 的路径；开启时以指定账号上游发现为先，映射在发现后应用。
+- 创建分组对话框不提供该配置。
+
+## Decisions
+
+### D1：配置以单个 JSONB 列存储
+`groups.codex_models_manifest_config`，领域类型 `domain.GroupCodexModelsManifestConfig{Enabled bool; AccountIDs []int64; FallbackToScheduler bool}`，JSON 键为 `enabled`、`account_ids`、`fallback_to_scheduler`。
+- 备选：三个独立列。否决：三个字段语义耦合，JSON 保证原子写入，且与 `models_list_config` 一致。
+- 迁移文件 `234_group_codex_models_manifest_config.sql`：`ADD COLUMN IF NOT EXISTS ... JSONB NOT NULL DEFAULT '{}'::jsonb`。ent schema 使用 `field.JSON(...).Default(domain.GroupCodexModelsManifestConfig{})`。
+
+### D2：校验放在 admin service，创建路径拒绝开启
+- 新文件 `group_codex_models_manifest.go` 提供 `normalizeCodexModelsManifestConfig`（平台非 openai 归零；去重保序；`enabled=false` 时保留列表便于再次启用）与 `validateCodexModelsManifestConfig(ctx, groupID, cfg)`（`enabled=true` 时：非空、≤10、全部属于 `accountRepo.ListByGroup(groupID)` 且平台 openai）。
+- 创建路径：`enabled=true` 直接 400。原因：账号绑定发生在分组创建之后，创建时无法校验成员关系；前端也不展示。
+- 备选：校验放 handler。否决：需要访问账号仓储，且创建与更新两条路径共用，service 是唯一收口。
+
+### D3：运行时入口与回退策略
+- handler 在本地生成分支之前判断 `group.Platform == openai && cfg.Enabled`，调用 `gatewayService.FetchPinnedCodexModelsManifest(ctx, group, clientVersion)`。
+- 返回值：`(*OpenAIModelsResponse, *Account, error)`，`*Account` 为配置顺序中第一个成功账号，用于 `setOpsSelectedAccount`。
+- 「无可用账号」以哨兵错误 `ErrNoPinnedCodexModelsAccounts` 表示；「全部失败」返回最后一个上游错误。handler 根据 `FallbackToScheduler` 决定：true 时跌入现有调度器循环；false 时无可用账号返回 503、全部失败按 `infraerrors.Code(err)` 返回。
+- 可用性判定：`IsActive() && Schedulable && !(AutoPauseOnExpired && 已过期)`。刻意不使用 `IsSchedulable()`，因为它包含限流、过载与临时不可调度窗口。
+- 账号来源：`accountRepo.ListByGroup(group.ID)`（active 成员），按配置顺序筛选并跳过缺失 ID。
+- 备选：复用 `BuildGroupConfiguredCodexModelsManifest` 已加载的账号列表以省一次查询。否决：那两个列表是可调度集合，会漏掉限流中的账号；一次按分组的查询成本可接受。
+
+### D4：并发拉取与纯函数合并
+- 用 `sync.WaitGroup` 对每个可用账号并发执行：`FetchCodexModelsManifest(ctx, acc, clientVersion, "")` → API Key 账号再 `CompleteAPIKeyCodexModelsManifestForClient`。结果写入按配置顺序索引的切片，失败记录到同下标的错误切片；各账号独立完成，不因单账号失败取消其他请求。
+- Codex 合并函数 `mergeCodexModelsManifestBodies(bodies [][]byte) ([]byte, error)`：以第一个 body 的顶层信封为基底，`models` 按 slug 并集，先出现者优先；slug 为空或解析失败的条目按出现顺序保留一次。输出后设置 `ETag = codexModelsManifestBodyETag(body)`，再交给 `MergeGroupConfiguredCodexModels` 做分组过滤与 304 判断。
+- 部分失败：`slog.Warn` 带 group_id 与失败账号 ID 列表。
+- 实现放在新文件 `openai_codex_models_pinned.go`，避免继续膨胀 2300 行的主文件。
+
+### D5：缓存统一并调整时效
+- 将 `fetchCachedAPIKeyCodexModelsManifest` 泛化为 `fetchCachedOpenAIModels(ctx, request, fetch, ifNoneMatch)`，`fetch func(ctx, ifNoneMatch) (*CodexModelsManifest, error)` 由调用方提供：API Key 路径传 `fetchCodexModelsManifestUpstream`；OAuth 路径传一个包含 agent identity 任务恢复逻辑的闭包。`handleCodexModelsManifestAccountAuthError` 在 OAuth 闭包返回错误时照旧调用。
+- 常量：`openAIModelsCacheTTL` 30s → 60s；`openAIModelsCacheStaleTTL` 保持 5 分钟；超过 5 分钟 `get` 删除条目返回 miss，调用方同步等待单飞结果，这与「超期强制等待上游刷新」一致，无需新状态。
+- 缓存键已包含 Authorization 与 Version 头，令牌刷新自然失效旧条目；`client_version` 不同的客户端各占一个条目。
+- 缓存键不含分组信息，多个分组共用同一账号时共享同一条目，新鲜期内零上游请求，乐观期与超期刷新均按键单飞，同一时刻一个账号只发一次上游请求；分组级处理（并集合并、自定义列表过滤、别名合并）都在缓存体的克隆上进行，不写回缓存。
+- `openAIModelsCacheMaxEntries` 64 → 512。OAuth 路径接入后条目数为「账号数 × 客户端版本数」，64 条在大规模部署下会被淘汰导致额外上游请求；单条清单通常几十 KB，最坏情况内存占用为几十 MB 量级。
+- 后台刷新使用 `context.Background()` 加上游 15 秒超时，与现状一致。
+- 备选：为固定账号模式增加分组级合并结果缓存。否决：账号级缓存命中后合并只是内存操作，再加一层会引入两套时效与失效问题。
+
+### D6：前端拆出独立组件
+- 新组件 `components/admin/group/CodexManifestAccountsField.vue`：props 为 `groupId`、`modelValue`（`{enabled, account_ids, fallback_to_scheduler}`）与已选账号名称映射；内部实现开关、标签列表、带防抖的搜索输入与下拉、回退子开关。搜索调用 `adminAPI.accounts.list(1, 20, {search, platform: 'openai', group: String(groupId)})`。
+- `GroupsView.vue` 只在编辑对话框 OpenAI 区块挂载组件，打开编辑时用 `adminAPI.accounts.getById` 解析已存 ID 的名称，失败则显示 `#<id>`。提交时开关打开且列表为空则 toast 报错并阻止。
+- 备选：在 GroupsView 内联复制模型路由的搜索状态。否决：会再引入一套按 key 索引的搜索状态，文件已过大。
+
+## Risks / Trade-offs
+
+- [固定账号模式下每次缓存超期会向 N 个账号并发请求] → 账号数上限 10；账号级缓存 1 分钟新鲜期把稳态请求量压到低于现状。
+- [限流中的账号被强制用于拉取 manifest 可能加重其 429] → 这是需求明确要求的行为；manifest 请求不占并发槽，且被缓存吸收；失败时按部分合并处理。
+- [部分账号失败导致模型列表短暂缺项] → 记录警告日志；下一次超期刷新恢复。用户已确认接受。
+- [OAuth manifest 首次接入缓存，乐观期内令牌已被撤销仍会返回旧内容最多 4 分钟] → manifest 非敏感数据，且撤销后的下一次刷新会失败并按现有 401 处理流程处理账号。
+- [配置引用的账号被解绑或删除后成为脏 ID] → 运行时跳过；编辑对话框显示 `#<id>` 提示管理员清理；全部失效时按回退配置处理。
+- [认证快照漏投影新字段会让开关静默失效] → 仓库已有投影对账集成测试，任务中包含更新该测试。
+
+## Migration Plan
+
+1. 部署包含迁移 234 的后端版本；迁移幂等，默认值 `{}` 反序列化为关闭状态，存量分组行为不变。
+2. 缓存时效变化随部署即时生效，无需数据迁移。
+3. 回滚：回退代码即可，列保留无副作用；如需彻底清理可手工 `DROP COLUMN`。
+
+### D7：普通模型列表共用固定账号来源
+
+- `GatewayHandler.Models` 在 OpenAI 分组开启固定账号时调用 `FetchPinnedOpenAIModelsList`；普通 `/models` 别名共用该入口。
+- 共享原有配置、固定账号成员筛选、并发收集与部分失败规则；标准列表失败且允许回退时用现有 OpenAI 调度器选账，再调用普通目录获取。无账号为 503，全部上游失败保留上游错误语义，不以静态默认列表掩盖失败。
+- API Key 使用标准模型 URL，不添加 Codex `client_version` 或身份请求头；从管理端抽出 API Key 请求构造。OAuth 复用 `FetchCodexModelsManifest` 和规范客户端版本，保留凭据引用、Agent Identity 恢复、401 状态处理。
+- 响应/缓存元数据类型泛化为 `OpenAIModelsResponse`；抽出原始 HTTP 响应获取，Codex 专用转换/元数据补全仅在 manifest 路径执行。两种请求使用同一缓存实现，以响应格式、完整 URL、账号、凭据、代理和请求头区分条目；相同 OAuth 请求共享条目。
+- 标准列表保留上游 `id`、`created`、`owned_by` 等字段。OAuth slug 转成标准条目；无创建时间采用 0。有效空数组是成功结果，缺失或错误的数组结构是上游错误。
+
+### D8：固定账号目录的映射与过滤
+
+- 每个成功账号先基于它的原始目录做公开名称投影，随后按配置顺序取并集。透传或无映射账号保留上游具体 ID；有映射账号仅暴露映射目标存在于该账号目录的具体公开名称。
+- 具体映射键以及分组选择的具体名称可作为别名候选；通配映射可匹配上游/分组提供的具体候选，但通配规则本身不作为模型 ID 返回。复用 `ResolveMappedModel` 的匹配优先级。
+- Codex 别名继承对应上游条目的能力元数据；固定账号开启时不再注入其他分组账号的本地别名。固定账号回退选出的账号也应用相同投影。
+- 分组列表过滤最后执行，遵守配置顺序；过滤后为空返回 200 空数组，不使用静态默认模型。最终响应体计算 ETag 并处理 304。
+- 前端文案说明该配置覆盖普通模型列表和 Codex Model Manifest。持久化配置名称和结构不变。
+
+### D9：扩展验证
+
+新增路由/handler 与 service 测试覆盖普通两条路由、固定账号优先、原始媒体和未知模型、映射与通配别名、部分/全部失败及调度器回退、凭据/请求协议隔离、OAuth 缓存复用、三段缓存时效、分组过滤隔离与空目录、最终 ETag。运行受影响 Go 测试（含 race）、完整 unit 检查及前端类型/组件检查。

openspec/changes/codex-manifest-pinned-accounts/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+OpenAI 分组在没有账号模型映射时，每次 Codex 客户端请求 Model Manifest 都会经由调度器挑选一个账号向上游拉取。调度结果受优先级、负载因子和限流窗口影响，而分组内账号的模型权限并不一致（例如部分账号拥有 Trusted Access for Cyber 的特殊模型），导致同一个 API Key 前后看到的模型列表不确定。此外 OAuth 账号的 manifest 拉取完全没有缓存，每次客户端刷新都直接打到 chatgpt.com。
+
+## What Changes
+
+- 为平台为 OpenAI 的分组新增「使用特定账号获取 Codex Model Manifest」配置：一个默认关闭的开关、一个必须至少选择一个账号的多选账号列表，以及「选定账号全部不可用时回退调度器」的子选项（默认关闭，即返回 503）。
+- 开关打开后，该分组的 API Key 请求 Codex Model Manifest 时只使用选定账号向上游拉取，忽略优先级、负载因子、限流与过载窗口；多个账号并发请求，`models` 按 slug 取并集后返回。部分账号失败时以成功部分合并；全部失败按配置返回 503 或回退到现有调度器路径。
+- 管理端分组编辑对话框的 OpenAI 区块新增该配置的开关与带搜索的多选账号下拉，账号来源限定为当前分组内的 OpenAI 账号。创建对话框不展示该配置（分组创建时尚无账号绑定）。
+- 分组复制时该配置重置为关闭。
+- 普通 `/v1/models` 与 `/models`（无非空 `client_version`）复用同一固定账号配置；API Key 请求标准上游模型列表，OAuth 从现有 Codex manifest 提取 ID，输出 OpenAI 列表。
+- **BREAKING**：固定账号开启时，普通列表和 Codex manifest 都优先进行指定账号发现，随后按来源账号模型映射生成公开目录并应用分组过滤；显式模型映射不再短路固定账号发现。
+- **BREAKING**（行为层面）：Codex Model Manifest 缓存统一为 1 分钟新鲜（命中即返回，不请求上游）、1 到 5 分钟乐观返回缓存并后台刷新、超过 5 分钟同步等待上游刷新后再返回。缓存覆盖范围从仅 API Key 账号扩展到 OAuth 账号，固定账号模式的每个账号也走同一缓存。
+
+## Capabilities
+
+### New Capabilities
+- `codex-manifest-pinned-accounts`：OpenAI 分组的固定账号 Manifest 配置（数据模型、管理端校验与 UI）、运行时的固定账号并发拉取与合并、不可用时的回退策略。
+- `codex-manifest-cache`：Codex Model Manifest 的按账号缓存策略：新鲜期、乐观期与强制刷新期的行为，以及对所有账号类型生效。
+
+### Modified Capabilities
+<!-- openspec/specs 目前为空，没有既有能力需要修改。 -->
+
+## Impact
+
+- **数据库**：`groups` 新增 JSONB 列 `codex_models_manifest_config`，新增迁移文件；ent schema 与生成代码更新。
+- **后端**：`Group` 领域模型、分组仓储的创建与更新、API Key 加载分组的字段投影、认证快照缓存、管理端分组 DTO 与校验、分组复制逻辑；`openai_codex_models_handler.go` 新增固定账号分支；`openai_codex_models_service.go` 新增固定账号并发拉取与合并、缓存策略调整并扩展到 OAuth 路径。
+- **管理端 API**：`POST/PUT /admin/groups` 请求与响应新增 `codex_models_manifest_config` 字段；`GET /admin/accounts` 已支持按分组过滤，无需改动。
+- **前端**：`GroupsView.vue` 编辑对话框 OpenAI 区块、`types/index.ts`、中英文 i18n。
+- **上游影响**：固定账号模式下每次缓存失效会向 N 个账号并发请求；缓存新鲜期延长到 1 分钟后，稳态上游请求量低于当前。

openspec/changes/codex-manifest-pinned-accounts/specs/codex-manifest-cache/spec.md

@@ -0,0 +1,71 @@
+## Purpose
+
+规定 Codex Model Manifest 按账号缓存的时效策略，使所有账号类型的 manifest 拉取在新鲜期内不打上游、乐观期内先返回缓存再后台刷新、超期后同步刷新。
+
+## ADDED Requirements
+
+### Requirement: 所有账号类型的 manifest 拉取都经过缓存
+系统 MUST 对 OAuth 账号与 API Key 账号的 Codex Model Manifest 上游拉取统一使用同一套按账号缓存。缓存键 MUST 区分账号、凭据账号、代理与请求头（含授权头与客户端版本），凭据变化后 MUST 视为新的缓存项。缓存键 MUST NOT 包含分组信息，多个分组共用同一账号时 MUST 共享同一缓存项；固定账号模式下每个选定账号的拉取 MUST 同样经过该缓存。缓存 MUST 至少容纳 512 个条目。
+
+#### Scenario: OAuth 账号命中缓存
+- **WHEN** 同一 OAuth 账号在新鲜期内被再次用于获取 manifest
+- **THEN** 系统 MUST 直接返回缓存内容，MUST NOT 向 chatgpt.com 发起请求
+
+#### Scenario: 多个分组共用同一账号
+- **WHEN** 两个分组在同一时刻通过同一账号请求 manifest 且缓存已超期
+- **THEN** 系统 MUST 只向上游发起一次请求，两个分组 MUST 各自基于该结果做分组级处理
+- **THEN** 一个分组的过滤结果 MUST NOT 影响另一个分组收到的内容
+
+#### Scenario: 凭据刷新后
+- **WHEN** 账号的访问令牌被刷新
+- **THEN** 下一次拉取 MUST 视为缓存未命中并同步请求上游
+
+### Requirement: 新鲜期 1 分钟内强制使用缓存
+缓存项写入后 1 分钟内 MUST 视为新鲜：系统 MUST 直接返回缓存内容且 MUST NOT 触发任何上游请求（包括后台刷新）。
+
+#### Scenario: 新鲜期内并发请求
+- **WHEN** 缓存写入后 30 秒内收到 10 个同账号 manifest 请求
+- **THEN** 上游请求次数 MUST 为 0
+
+### Requirement: 1 到 5 分钟乐观返回并后台刷新
+缓存项写入后超过 1 分钟且不超过 5 分钟时 MUST 视为过期但可用：系统 MUST 立即返回缓存内容，并在后台对同一缓存键做单飞刷新。后台刷新 MUST 携带上游 ETag，上游返回 304 时 MUST 续期现有缓存项。
+
+#### Scenario: 乐观期返回旧值
+- **WHEN** 缓存写入后 3 分钟收到请求
+- **THEN** 系统 MUST 立即返回缓存内容
+- **THEN** 系统 MUST 触发一次后台上游刷新，同一时刻多个请求 MUST 只触发一次
+
+#### Scenario: 后台刷新失败
+- **WHEN** 乐观期后台刷新失败
+- **THEN** 已返回给客户端的响应 MUST 不受影响
+- **THEN** 缓存项 MUST 保持不变直到超期
+
+### Requirement: 超过 5 分钟强制同步刷新
+缓存项写入后超过 5 分钟 MUST 视为失效：系统 MUST 丢弃该缓存项，同步等待上游响应后再返回；上游失败时 MUST 向客户端返回错误而不是旧缓存。
+
+#### Scenario: 超期后同步等待
+- **WHEN** 缓存写入后 6 分钟收到请求
+- **THEN** 系统 MUST 等待上游响应后返回新内容
+- **THEN** 新内容 MUST 写入缓存并重新开始 1 分钟新鲜期
+
+#### Scenario: 超期后上游失败
+- **WHEN** 缓存已超期且上游请求失败
+- **THEN** 系统 MUST 返回上游错误，MUST NOT 返回旧缓存
+
+### Requirement: 条件请求基于缓存内容的 ETag
+客户端携带的 `If-None-Match` MUST 与返回给客户端的最终响应体 ETag 比较，而不是透传给上游。缓存命中且 ETag 匹配时 MUST 返回 304。
+
+#### Scenario: 缓存命中且 ETag 匹配
+- **WHEN** 客户端 `If-None-Match` 等于当前缓存内容的 ETag
+- **THEN** 系统 MUST 返回 304 且不请求上游
+
+### Requirement: 普通模型发现使用相同缓存策略
+普通固定账号模型列表的上游获取 MUST 使用本规范的同一套按账号缓存与单飞实现。完整请求 URL MUST 参与缓存键；API Key 的普通请求与 Codex 协议请求 MUST 分离。OAuth 普通列表使用规范版本获取的 manifest MUST 与相同请求条件的 Codex manifest 共享缓存。分组后处理 MUST NOT 修改缓存。
+
+#### Scenario: OAuth 两种列表共用缓存
+- **WHEN** 相同 OAuth 账号的普通列表与相同版本 Codex manifest 在新鲜期内连续请求
+- **THEN** 系统 MUST 仅发起一次上游请求，并输出各自正确的响应结构
+
+#### Scenario: API Key 两种协议分离
+- **WHEN** 相同 API Key 账号先后被用于普通列表和带 client_version 的 Codex manifest
+- **THEN** 各请求 MUST 获取并缓存自己的上游响应，MUST NOT 复用另一协议已转换的内容

openspec/changes/codex-manifest-pinned-accounts/specs/codex-manifest-pinned-accounts/spec.md

@@ -0,0 +1,138 @@
+## Purpose
+
+让 OpenAI 分组管理员指定一组固定账号来获取普通模型列表与 Codex Model Manifest，使同一分组的 API Key 始终看到确定且合并后的模型列表，而不受调度器选账结果影响。
+
+## ADDED Requirements
+
+### Requirement: OpenAI 分组可配置固定账号获取 Codex Model Manifest
+系统 SHALL 为平台为 `openai` 的分组提供 `codex_models_manifest_config` 配置，包含 `enabled`（默认 false）、`account_ids`（账号 ID 列表）和 `fallback_to_scheduler`（默认 false）。`enabled=false` 时系统 MUST 保持现有的本地目录优先、无本地目录时调度器获取 manifest 的行为；普通列表保持本地映射/默认列表行为。
+
+#### Scenario: 默认关闭
+- **WHEN** 分组未设置或 `enabled=false`
+- **THEN** Codex Model Manifest 请求 MUST 走现有本地生成或调度器选账路径
+- **THEN** `account_ids` 与 `fallback_to_scheduler` MUST 不影响任何运行时行为
+
+#### Scenario: 非 OpenAI 平台分组
+- **WHEN** 分组平台不是 `openai` 且请求携带 `enabled=true` 的配置
+- **THEN** 系统 MUST 将该配置归一化为关闭状态后落库，而不是返回错误
+
+### Requirement: 开启时必须至少选择一个分组内的 OpenAI 账号
+当 `enabled=true` 时，管理端更新接口 MUST 校验 `account_ids` 去重后至少包含一个账号，且每个账号 MUST 是当前分组内状态为 active、平台为 `openai` 的账号；账号数量 MUST NOT 超过 10 个。校验失败 MUST 返回 400，不落库。
+
+#### Scenario: 开启但未选择账号
+- **WHEN** 管理员保存 `enabled=true` 且 `account_ids` 为空
+- **THEN** 系统 MUST 返回 400，错误码为 `INVALID_CODEX_MODELS_MANIFEST_CONFIG`
+
+#### Scenario: 选择了不属于当前分组的账号
+- **WHEN** `account_ids` 包含未绑定到该分组、已停用或平台不是 `openai` 的账号
+- **THEN** 系统 MUST 返回 400，错误信息指出无效账号 ID
+
+#### Scenario: 创建分组时开启
+- **WHEN** 创建分组请求携带 `enabled=true`
+- **THEN** 系统 MUST 返回 400，提示创建后再在编辑中配置
+
+#### Scenario: 重复账号 ID
+- **WHEN** `account_ids` 含重复 ID
+- **THEN** 系统 MUST 去重后保存，保持首次出现的顺序
+
+### Requirement: 固定账号模式只使用选定账号获取 manifest
+当 `enabled=true` 时，该分组 API Key 的 Codex Model Manifest 请求 MUST 只向选定账号发起上游请求，MUST NOT 调用调度器。选定账号的可用性判定 MUST 只考虑账号状态为 active、可调度开关打开、未因过期自动暂停；MUST 忽略优先级、负载因子、限流窗口与过载窗口。已从分组移除或已删除的账号 MUST 被跳过。
+
+#### Scenario: 限流中的选定账号仍被使用
+- **WHEN** 某个选定账号处于限流或过载窗口内
+- **THEN** 系统 MUST 仍然使用该账号请求 manifest
+
+#### Scenario: 停用的选定账号被跳过
+- **WHEN** 某个选定账号状态为 inactive 或可调度开关关闭
+- **THEN** 系统 MUST 跳过该账号，不向其发起请求
+
+#### Scenario: 选定账号已不在分组内
+- **WHEN** 配置中的账号 ID 已从分组解绑或已删除
+- **THEN** 系统 MUST 跳过该 ID，并继续处理其余账号
+
+### Requirement: 多个选定账号并发请求并合并模型列表
+系统 MUST 对所有可用的选定账号并发发起 manifest 请求，并把各账号响应的 `models` 按 `slug` 取并集：同一 slug 以配置顺序中靠前账号的条目为准；顶层其余字段取配置顺序中第一个成功账号的响应。合并结果 MUST 继续应用分组自定义模型列表过滤；别名 MUST 仅来自成功拉取账号的映射投影，并基于最终响应体计算 ETag。
+
+#### Scenario: 并集合并
+- **WHEN** 账号 1 返回模型 A、B，账号 2 返回模型 A、C
+- **THEN** 客户端 MUST 收到模型 A、B、C，且 A 的条目来自账号 1
+
+#### Scenario: 部分账号失败
+- **WHEN** 一个选定账号上游返回错误而其他账号成功
+- **THEN** 系统 MUST 以成功账号的响应合并并返回 200
+- **THEN** 系统 MUST 记录包含失败账号 ID 的警告日志
+
+#### Scenario: 分组自定义模型列表仍然生效
+- **WHEN** 分组启用了自定义 `/v1/models` 列表
+- **THEN** 合并后的 manifest MUST 只保留列表中允许的模型
+
+#### Scenario: ETag 条件请求
+- **WHEN** 客户端 `If-None-Match` 与合并后最终响应体的 ETag 匹配
+- **THEN** 系统 MUST 返回 304 且响应体为空
+
+### Requirement: 选定账号全部不可用或全部失败时按配置回退
+当没有任何可用的选定账号，或所有可用账号的上游请求全部失败时：`fallback_to_scheduler=false` 时系统 MUST 返回上游错误（全部失败时）或 503（无可用账号时）；`fallback_to_scheduler=true` 时系统 MUST 回退到现有调度器选账路径。
+
+#### Scenario: 默认不回退
+- **WHEN** `fallback_to_scheduler=false` 且所有选定账号都不可用
+- **THEN** 系统 MUST 返回 503，错误类型为 `upstream_error`
+
+#### Scenario: 全部失败且不回退
+- **WHEN** `fallback_to_scheduler=false` 且所有可用选定账号的上游请求均失败
+- **THEN** 系统 MUST 返回最后一个上游错误对应的状态码与信息
+
+#### Scenario: 开启回退
+- **WHEN** `fallback_to_scheduler=true` 且所有选定账号不可用或全部失败
+- **THEN** 系统 MUST 使用调度器选择账号并按现有流程返回 manifest
+
+### Requirement: 管理端展示与编辑固定账号配置
+分组编辑对话框在平台为 `openai` 时 MUST 展示该配置：一个开关；开关打开后展示带搜索的多选账号下拉与「全部不可用时回退调度器」子开关。账号下拉 MUST 只列出当前分组内平台为 `openai` 的账号，并支持按名称搜索。分组创建对话框 MUST NOT 展示该配置。
+
+#### Scenario: 开启后未选账号即提交
+- **WHEN** 管理员打开开关但未选择任何账号并点击保存
+- **THEN** 前端 MUST 阻止提交并提示至少选择一个账号
+
+#### Scenario: 回显已保存账号
+- **WHEN** 打开一个已配置固定账号的分组编辑对话框
+- **THEN** 已选账号 MUST 以名称标签展示；无法解析名称的账号 MUST 以 `#<id>` 展示
+
+#### Scenario: 分组复制
+- **WHEN** 管理员复制一个开启了固定账号配置的分组
+- **THEN** 新分组的该配置 MUST 为关闭且账号列表为空
+
+### Requirement: 普通模型列表复用固定账号配置
+当 OpenAI 分组开启固定账号时，普通 `/v1/models` 与 `/models` 请求 MUST 使用同一组指定账号向上游发现模型，并输出 `{object:"list",data:[...]}`。API Key 请求 MUST 使用标准模型列表端点，不添加 `client_version`；OAuth MUST 使用已有 Codex manifest 链路，将 slug 转为标准 ID。普通列表 MUST 保留上游媒体模型与未知具体模型。
+
+#### Scenario: 普通客户端发现特殊模型
+- **WHEN** 不带 `client_version` 的请求使用开启固定账号的分组，所选账号返回非内置的模型
+- **THEN** 普通列表 MUST 包含该模型且 MUST NOT 请求未选账号
+
+#### Scenario: API Key 与 OAuth 账号混合
+- **WHEN** 所选账号包含 API Key 与 OAuth
+- **THEN** 系统 MUST 按各自协议获取目录并按 ID 合并，重复 ID MUST 取配置顺序靠前账号的条目
+
+#### Scenario: 普通请求回退
+- **WHEN** 固定账号全不可用或全失败且开启回退
+- **THEN** 系统 MUST 经由调度器选账号获取普通模型目录，而不是返回本地默认列表
+
+### Requirement: 固定账号发现先于本地目录生成
+固定账号开启时，普通列表与 Codex manifest MUST 先获取指定账号目录，再按照来源账号的模型映射生成公开名称，最后应用分组列表过滤。MUST NOT 因为存在显式模型映射而跳过上游发现。透传账号 MUST 忽略残留模型映射；普通模式的具体别名仅在映射目标存在于来源账号目录时可见。MUST NOT 注入未成功拉取账号的别名或把通配模式作为模型 ID 返回。
+
+#### Scenario: 有映射的固定账号
+- **WHEN** 所选账号配置 public-name 到 upstream-name 的映射且上游返回 upstream-name
+- **THEN** 系统 MUST 请求该账号上游并以 public-name 返回该模型，Codex 条目 MUST 继承上游能力元数据
+
+#### Scenario: 固定账号开启但列表为空
+- **WHEN** 运行时配置开启但账号 ID 列表为空
+- **THEN** 系统 MUST 按无可用固定账号的失败/回退规则处理，MUST NOT 静默使用本地目录
+
+#### Scenario: 成功空目录或过滤为空
+- **WHEN** 上游返回有效空数组或分组过滤排除了全部模型
+- **THEN** 普通模型列表 MUST 返回 200 且 data 为空数组，MUST NOT 返回默认模型或触发失败回退
+
+### Requirement: 普通模型列表的条件请求
+普通固定账号列表 MUST 基于映射、合并和过滤后的最终响应体计算 ETag。
+
+#### Scenario: 普通列表 ETag 匹配
+- **WHEN** 客户端 If-None-Match 与最终普通列表响应的 ETag 匹配
+- **THEN** 系统 MUST 返回 304 且无响应体

openspec/changes/codex-manifest-pinned-accounts/tasks.md

@@ -0,0 +1,57 @@
+## 1. 数据模型与持久化
+
+- [x] 1.1 在 `backend/internal/domain` 新增 `GroupCodexModelsManifestConfig{Enabled, AccountIDs, FallbackToScheduler}`，JSON 键为 `enabled`、`account_ids`、`fallback_to_scheduler`
+- [x] 1.2 在 `backend/ent/schema/group.go` 新增 JSONB 字段 `codex_models_manifest_config`（默认空结构体），执行 `go generate ./ent`
+- [x] 1.3 新增迁移 `backend/migrations/234_group_codex_models_manifest_config.sql`（`ADD COLUMN IF NOT EXISTS ... JSONB NOT NULL DEFAULT '{}'::jsonb`）
+- [x] 1.4 `service.Group` 新增 `CodexModelsManifestConfig` 字段并添加类型别名；`group_repo.go` 创建与更新两处 setter 写入该字段
+- [x] 1.5 `api_key_repo.go`：分组字段投影列表与 `groupEntityToService` 加入新字段
+- [x] 1.6 `api_key_auth_cache.go` 快照结构体与 `api_key_auth_cache_impl.go` 两处映射加入新字段
+- [x] 1.7 `admin_group_duplicate.go` 复制分组时将该配置重置为关闭且账号列表为空
+- [x] 1.8 更新 API Key 分组投影对账集成测试，覆盖新字段
+
+## 2. 管理端配置接口与校验
+
+- [x] 2.1 新增 `backend/internal/service/group_codex_models_manifest.go`：`normalizeCodexModelsManifestConfig`（非 openai 平台归零、去重保序）与 `validateCodexModelsManifestConfig`（开启时非空、≤10、全部为分组内 active 的 openai 账号），错误码 `INVALID_CODEX_MODELS_MANIFEST_CONFIG`
+- [x] 2.2 `admin_service.go` 的 `CreateGroupInput`/`UpdateGroupInput` 与 `admin_group.go` 创建、更新路径接入归一化与校验；创建路径 `enabled=true` 返回 400
+- [x] 2.3 `handler/admin/group_handler.go` 的创建与更新请求结构体、`dto/types.go` 响应结构体、`dto/mappers.go` 增加 `codex_models_manifest_config`
+- [x] 2.4 在 `admin_service_group_test.go` 增加测试：开启但空列表被拒、非成员或非 openai 账号被拒、超过 10 个被拒、非 openai 平台被归零、重复 ID 去重保序、创建时开启被拒
+
+## 3. 缓存策略统一
+
+- [x] 3.1 将 `codexModelsManifestCacheTTL` 调整为 60 秒，保持 `codexModelsManifestCacheStaleTTL` 为 5 分钟，将 `codexModelsManifestCacheMaxEntries` 提高到 512，并更新常量注释说明三段时效与容量依据
+- [x] 3.2 将 `fetchCachedAPIKeyCodexModelsManifest`/`refreshCachedAPIKeyCodexModelsManifest` 泛化为接受 `fetch` 闭包的 `fetchCachedCodexModelsManifest`/`refreshCachedCodexModelsManifest`
+- [x] 3.3 `FetchCodexModelsManifest` 的 OAuth 分支改为经缓存调用，闭包内保留 agent identity 任务恢复逻辑，错误时仍调用 `handleCodexModelsManifestAccountAuthError`
+- [x] 3.4 在 `openai_codex_models_service_test.go` 增加或调整测试：OAuth 账号新鲜期内零上游请求、乐观期返回旧值且单飞后台刷新、超期后同步等待并写回、超期上游失败返回错误、令牌变化后缓存未命中、If-None-Match 基于缓存 ETag 返回 304、同一账号被两个分组同时请求时只发一次上游请求且各分组过滤互不影响
+- [x] 3.5 检查现有测试对 30 秒 TTL 或 OAuth 不缓存的隐含假设并修正
+
+## 4. 固定账号模式运行时
+
+- [x] 4.1 新增 `backend/internal/service/openai_codex_models_pinned.go`：`mergeCodexModelsManifestBodies` 纯函数（第一个信封为基底、`models` 按 slug 并集且先出现者优先）
+- [x] 4.2 同文件实现 `FetchPinnedCodexModelsManifest(ctx, group, clientVersion)`：`ListByGroup` 取成员、按配置顺序筛选可用账号（active、Schedulable、未过期；忽略限流与过载）、errgroup 并发拉取与补全、按下标收集结果、部分失败记录 `slog.Warn`、全部不可用返回 `ErrNoPinnedCodexModelsAccounts`、全部失败返回最后一个错误、成功时设置合并体 ETag 并返回首个成功账号
+- [x] 4.3 `openai_codex_models_handler.go`：本地生成分支之后加入固定账号分支，成功时 `setOpsSelectedAccount` 后调用 `MergeGroupConfiguredCodexModels` 并写响应；按 `FallbackToScheduler` 决定回退调度器循环或返回 503 / 上游错误
+- [x] 4.4 为合并函数编写单元测试：并集与顺序、重复 slug 取靠前账号条目、信封字段来源、无 slug 条目处理
+- [x] 4.5 在 `openai_codex_models_handler_test.go` 增加测试：两个账号返回不同模型时客户端收到并集且未调用调度器、限流账号仍被使用、停用账号被跳过、不在分组的 ID 被跳过、部分失败仍 200、全部不可用时默认 503、开启回退时走调度器、自定义模型列表过滤仍生效、ETag 匹配返回 304
+
+## 5. 前端
+
+- [x] 5.1 `frontend/src/types/index.ts` 新增 `CodexModelsManifestConfig` 类型，并加入 `AdminGroup`、创建与更新请求类型
+- [x] 5.2 新增 `frontend/src/components/admin/group/CodexManifestAccountsField.vue`：开关、已选账号标签、带防抖的搜索下拉（`adminAPI.accounts.list` 按 `platform=openai` 与 `group` 过滤）、回退子开关
+- [x] 5.3 `GroupsView.vue` 编辑对话框 OpenAI 区块挂载组件；打开编辑时解析已存账号名称（失败显示 `#<id>`）；提交时开关打开且列表为空则提示并阻止；更新请求携带该字段；创建请求固定发送关闭状态
+- [x] 5.4 中英文 i18n（`overview.ts` 的 `admin.groups.codexModelsManifest.*`）：标题、开关文案、启用与未启用提示、账号标签、搜索占位、回退开关文案、至少选择一个账号的错误提示
+- [x] 5.5 为新组件编写 Vitest 测试：开关切换显示、选择与移除账号、开启后空列表触发校验
+
+## 6. 验证
+
+- [x] 6.1 `cd backend && go test -tags=unit ./...` 与 `golangci-lint run ./...` 通过
+- [x] 6.2 `cd backend && go test -tags=integration ./internal/repository/...` 通过（含投影对账测试）
+- [x] 6.3 `cd frontend && pnpm test` 与类型检查通过
+- [ ] 6.4 本地启动后手动验证：编辑 OpenAI 分组开启固定账号并选择两个权限不同的账号，Codex 客户端拉取 manifest 得到并集；1 分钟内重复请求不打上游
+
+## 7. 普通模型列表扩展
+
+- [x] 7.1 泛化模型响应/缓存基础，抽出原始上游传输和 API Key 标准请求构造，OAuth 复用现有认证与缓存
+- [x] 7.2 固定账号筛选与并发获取共用，新增普通模型目录聚合及调度器回退
+- [x] 7.3 实现来源账号映射投影、分组最终过滤、空目录与 ETag；Codex 固定账号优先于本地生成
+- [x] 7.4 普通 `/v1/models` 与 `/models` 接入固定账号逻辑，中英文 UI 文案覆盖两个入口
+- [x] 7.5 添加两种上游、映射优先级、失败回退、跨分组及跨协议缓存、三段时效和 ETag 回归测试
+- [x] 7.6 完成受影响测试、race、unit/lint、前端类型与组件验证及 OpenSpec 校验，记录验证范围

openspec/changes/codex-manifest-pinned-accounts/verification.md

@@ -0,0 +1,23 @@
+# 普通模型列表扩展验证（2026-09-05）
+
+## 已实现
+
+普通 `/v1/models` 与 `/models` 共用分组固定账号配置。API Key 使用标准模型端点；OAuth/Agent Identity 继续使用现有 Codex 上游认证链路。两种目录共享固定账号筛选、并发、部分失败处理和缓存策略；固定账号发现先于本地目录，映射、分组过滤和 ETag 在缓存之后应用。
+
+普通列表保留上游未知模型、媒体模型及模型元数据。有效空目录/过滤为空不会触发静态默认或调度器回退。无可用账号返回 503，上游失败遵守回退配置；客户端错误使用 OpenAI 错误信封。
+
+## 自动验证
+
+- `GOCACHE=/tmp/sub2api-go-cache go test -tags=unit ./... -timeout=5m`：通过，55 个含测试的包成功。
+- 最后补充响应格式缓存隔离和冷缓存 304 错误处理后，执行 `GOCACHE=/tmp/sub2api-go-cache go test -race -tags=unit -p 2 ./internal/service ./internal/handler ./internal/server/routes -run 'Test.*(OpenAIModels|CodexModels|OrdinaryPinned|PinnedModels|ProjectAccountModels)' -count=1 -timeout=3m`：三个包全部通过。
+- 最终代码执行 `GOCACHE=/tmp/sub2api-go-cache GOLANGCI_LINT_CACHE=/tmp/sub2api-models-lint-cache golangci-lint run ./... --timeout=5m`：0 issues。
+- 前端使用已安装依赖执行 `./node_modules/.bin/vitest run src/components/admin/group/__tests__/CodexManifestAccountsField.spec.ts src/views/admin/__tests__/GroupsView.duplicate.spec.ts`：2 个文件、10 个测试通过。
+- `./node_modules/.bin/vue-tsc --noEmit`：通过。
+- 两个修改的 i18n 文件 ESLint：通过。
+- `openspec validate codex-manifest-pinned-accounts --strict`、`git diff --check`：通过。
+
+回归覆盖普通两条路由（含空 client_version）、三个 Codex 入口、API Key/OAuth 混合账号、影子账号凭据解析、优先级/临时限流、停用/过期/非成员跳过、部分失败/全部失败/调度器回退、映射别名和通配规则、跨分组并发缓存隔离、OAuth 跨入口缓存复用、API Key 协议隔离、三段时效/单飞/ETag 续期、最终响应 304、空目录、媒体别名不能绕过 Codex 专用过滤。
+
+## 验证边界
+
+测试使用本地模拟上游和仓储，没有访问真实 OpenAI/ChatGPT 账号或部署服务。原任务 6.4 的真实客户端手动联调仍未勾选；本次新增 7.1—7.6 已完成。