docs: finalize sub2api post-task routing notes

.agents/skills/unidesk-sub2api/SKILL.md

@@ -56,17 +56,24 @@ bun scripts/cli.ts platform-infra sub2api codex-pool validate
 - `pool.groupName`: Sub2API group 名称。
 - `pool.apiKeySecretName` / `pool.apiKeySecretKey`: 统一消费 API key 的 k3s Secret 位置，默认 `platform-infra/sub2api-codex-pool-api-key.API_KEY`。
 - `pool.minOwnerBalanceUsd`: pool key owner 最低余额，sync/validate 会补齐。
+- `pool.defaultTempUnschedulable`: 默认账号级临时下线规则；用于在上游返回容量、限流、overload 或认证状态异常时，让 Sub2API 冷却该账号并切换到同组其他账号。
 - `profiles.entries`: 从 master `~/.codex/` 选择上游 profile 并映射到 Sub2API account。
+- `profiles.entries[].capacity`: 可选 per-account concurrency override；不写则使用 `pool.defaultAccountCapacity`。不要因为某 provider 当前看起来更可用就给 HY 或任一账号写容量钉死；容量 override 必须来自明确 YAML 决策和新鲜 runtime 证据。
+- `profiles.entries[].tempUnschedulable`: 可选 per-account 临时下线规则覆盖；字段语义以 `docs/reference/platform-infra.md` 为权威。
 - `profiles.entries[].openaiResponsesWebSocketsV2Mode`: 需要 Responses WebSocket v2 的上游才设置，值为 `off`、`ctx_pool` 或 `passthrough`。
 - `profiles.entries[].upstreamUserAgent`: 少数要求 Codex CLI User-Agent 的上游才设置，不能含换行。
 
 `sync --confirm` 会登录 Sub2API admin、创建/更新 group、创建/更新 YAML 中的 `unidesk-codex-*` accounts、创建/复用统一 API key Secret，并删除 YAML 中已移除且 `extra.unidesk_managed=true` 的 `unidesk-codex-*` account。
 
+不要给 UniDesk-managed Codex accounts 开 Sub2API `pool_mode`。UniDesk 期望的 failover 是把失败账号临时标记为 unschedulable，让同组其他账号接手；`pool_mode` 会重试同一个 account path。
+
+WebSocket v2 是账号能力集合，不是调度 pin。`openaiResponsesWebSocketsV2Mode` 只声明该账号可承担 Codex Responses WSv2 链路；`codex-pool validate` 至少要看到一个 `webSocketsV2.schedulableEnabled` 账号，真实可用性仍以 Codex smoke 和运行日志为准。
+
 ## 添加上游
 
 1. 在 master `~/.codex/` 准备 profile 文件，例如 `config.toml.<profile>` 和 `auth.json.<profile>`。
 2. 在 `config/platform-infra/sub2api-codex-pool.yaml` 添加 `profiles.entries` 项，指定 `profile`、`accountName`、`configFile`、`authFile`。
-3. 如需要，给该项加 `priority`、`openaiResponsesWebSocketsV2Mode` 或 `upstreamUserAgent`。
+3. 如需要，给该项加 `priority`、`capacity`、`tempUnschedulable`、`openaiResponsesWebSocketsV2Mode` 或 `upstreamUserAgent`；不要用 `capacity` 把 HY 或任一账号变成硬编码 fallback。
 4. 跑 `codex-pool plan`，确认 profile 可读、`base_url` 和 API key 来源有效，且 stdout 未泄露完整 key。
 5. 跑 `codex-pool sync --confirm`。
 6. 跑 `codex-pool validate`。
@@ -107,6 +114,7 @@ bun scripts/cli.ts platform-infra sub2api codex-pool configure-local --confirm
 - 从 `platform-infra/<apiKeySecretName>.<apiKeySecretKey>` 读取统一 API key。
 - 把当前 `~/.codex/config.toml` 和 `~/.codex/auth.json` 备份为 `.<backupSuffix>`，默认 `.pre-sub2api`。
 - 重写默认 `~/.codex` 消费端，指向 `publicExposure.masterBaseUrl`，provider 名称和 wire API 来自 `localCodex`。
+- 写入 Codex Responses WebSocket v2 能力标记：provider section 必须有 `supports_websockets = true`，`[features]` 必须有 `responses_websockets_v2 = true`，否则 auto compact 后续链路会退回 HTTP-only summary context。
 - 用统一 key 做一次 gateway 验证。
 
 防递归规则：`profiles.entries` 中 default 上游应指向 `config.toml.pre-sub2api` / `auth.json.pre-sub2api`，不要把已经改成 Sub2API consumer 的默认文件再导回上游池。
@@ -117,7 +125,7 @@ bun scripts/cli.ts platform-infra sub2api codex-pool configure-local --confirm
 
 - `sub2api status`：Deployment/StatefulSet/Service/Secret 可见，运行镜像与 YAML 一致。
 - `sub2api validate`：app、PostgreSQL、Redis 和 service proxy 基础检查通过。
-- `codex-pool validate`：统一 key 的 `GET /v1/models` 成功，owner balance 已满足 YAML 最小值。
+- `codex-pool validate`：统一 key 的 `GET /v1/models` 成功，owner balance 已满足 YAML 最小值，capacity、WebSocket v2 和 temporary-unschedulable 运行时状态与 YAML 对齐。
 - 若 `publicExposure.enabled=true`，确认 FRP path 可用；`expose --confirm` 会用未带 key 的 public `/v1/models` 401 作为网关可达性探针。
 
 如果要证明真实模型请求可用，使用最小 `/v1/responses` 或等价 Codex smoke。不要把 group-level `/v1/models` 成功解释成每个上游 account 都健康。
@@ -128,8 +136,11 @@ bun scripts/cli.ts platform-infra sub2api codex-pool configure-local --confirm
 - pool key 401：跑 `codex-pool sync --confirm` 重建 Sub2API key 与 k3s Secret 绑定，再跑 `codex-pool validate`。
 - FRP 不通：先看 `codex-pool expose --confirm` 输出的 `masterFrps`、`sub2api-frpc` 和 public 401 probe；需要低层证据时只用 `trans G14:k3s` 做 bounded 查询。
 - default profile 递归：检查 YAML default entry 是否使用 `*.pre-sub2api` 备份文件；必要时恢复备份后重新 `configure-local --confirm`。
-- 上游需要 WebSocket v2：只给该 profile 配 `openaiResponsesWebSocketsV2Mode: ctx_pool|passthrough`，跑 `sync --confirm`。
+- 上游需要 WebSocket v2：只给该 profile 配 `openaiResponsesWebSocketsV2Mode: ctx_pool|passthrough`，跑 `sync --confirm`；把它当 capability candidate，不要同时把它写成唯一/最高容量调度目标。
 - 上游要求 Codex User-Agent：只给该 profile 配 `upstreamUserAgent`，跑 `sync --confirm`。
+- 上游报 capacity/rate-limit/overload 后没有切号：先确认 `codex-pool validate` 里 `tempUnschedulable.ok=true` 且目标 account `runtimeEnabled=true`、规则数符合 YAML；若 mismatch，跑 `codex-pool sync --confirm`，不要手工 patch Sub2API credentials。
+- Codex auto compact 后丢上下文：先确认本机 `~/.codex/config.toml` 是否有 `supports_websockets = true` 和 `responses_websockets_v2 = true`，再看 `codex-pool validate` 的 WSv2 candidate 和 Sub2API 日志里的 `transport=responses_websockets_v2`。
+- Codex smoke 有 reconnect/1013：这是上游并发/可用性问题，和 HTTP-only compact context-loss 分开处理；记录 session/log 证据并关联专项 issue，不要用 HY 容量钉死掩盖。
 
 ## 禁止事项