docs: document sub2api owner concurrency floor

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

@@ -57,7 +57,7 @@ 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.minOwnerConcurrency`: 统一消费 API key owner 的最低并发，sync/validate 会补齐；用于避免共享 key 在用户并发层触发 WS 1013，不要用提高某个 provider capacity 来掩盖。
+- `pool.minOwnerConcurrency`: 统一消费 API key owner 的最低并发，sync/validate 会补齐；必须不小于 YAML 中所有账号声明 capacity 的总和，用于避免共享 key 在用户并发层触发 WS 1013，不要用提高某个 provider capacity 来掩盖。
 - `pool.defaultTempUnschedulable`: 默认账号级临时下线规则；只声明 Sub2API 已支持的错误路径能力，用于在上游返回容量、限流、overload、service unavailable、gateway timeout、稳定模型路由错误或认证状态异常时，让 Sub2API 冷却该账号并切换到同组其他账号。不要用 YAML、UniDesk CLI、k8s 热补或本地 fork 魔改 Sub2API 不支持的行为。
 - `profiles.entries`: 从 master `~/.codex/` 选择上游 profile 并映射到 Sub2API account。
 - `profiles.entries[].capacity`: 可选 per-account concurrency override；不写则使用 `pool.defaultAccountCapacity`。具体数值只以 `config/platform-infra/sub2api-codex-pool.yaml` 为准，skill 和长期参考只描述规则，不重复写当前值。
@@ -80,9 +80,10 @@ Codex 启动时反复出现 WebSocket reconnect、HTTPS fallback、`websocket cl
 1. 在 master `~/.codex/` 准备带后缀的上游 profile 文件，例如 `config.toml.<profile>` 和 `auth.json.<profile>`；禁止覆盖默认 `config.toml` / `auth.json`。
 2. 在 `config/platform-infra/sub2api-codex-pool.yaml` 添加 `profiles.entries` 项，指定 `profile`、`accountName`、`configFile`、`authFile`。
 3. 如需要，给该项加 `priority`、`capacity`、`loadFactor`、`tempUnschedulable`、`openaiResponsesWebSocketsV2Mode` 或 `upstreamUserAgent`；capacity/loadFactor 的具体数值只写在 YAML。
-4. 跑 `codex-pool plan`，确认 profile 可读、`base_url` 和 API key 来源有效，且 stdout 未泄露完整 key。
-5. 跑 `codex-pool sync --confirm`。
-6. 跑 `codex-pool validate`。
+4. 如果新增账号会提高声明 capacity 总和，同步提高 `pool.minOwnerConcurrency`；`codex-pool plan` 会拒绝 owner concurrency 低于总 capacity 的配置。
+5. 跑 `codex-pool plan`，确认 profile 可读、`base_url` 和 API key 来源有效，且 stdout 未泄露完整 key。
+6. 跑 `codex-pool sync --confirm`。
+7. 跑 `codex-pool validate`。
 
 普通新增上游是 YAML 操作，不走 CI/CD，不改代码。只有需要渲染或校验上游 Sub2API 已经存在的可复用能力时才修改 `scripts/src/platform-infra-sub2api-codex.ts`；Sub2API 本身不支持的能力不在 UniDesk 侧魔改实现。
 

docs/reference/platform-infra.md

@@ -25,7 +25,7 @@
 
 - `pool.groupName` names the Sub2API group that represents the pool.
 - `pool.apiKeySecretName` and `pool.apiKeySecretKey` name the k3s Secret that stores the single consumer API key.
-- `pool.minOwnerConcurrency` declares the minimum concurrency for the Sub2API user that owns the unified consumer API key. Keep it high enough to cover the declared account capacity set, so the shared key does not fail WS sessions at the user-concurrency layer. Do not compensate for owner-concurrency 1013 errors by pinning capacity to one provider.
+- `pool.minOwnerConcurrency` declares the minimum concurrency for the Sub2API user that owns the unified consumer API key. It must be at least the sum of all declared account capacities, so the shared key does not fail requests or WS sessions at the user-concurrency layer. Do not compensate for owner-concurrency 1013 errors by pinning capacity to one provider.
 - `pool.defaultTempUnschedulable` declares Sub2API account-level temporary unschedulable rules for capabilities that Sub2API itself already supports. Keep 429/overload/capacity, service-unavailable, gateway timeout, and stable model-routing failures in this YAML policy so the scheduler can cool down a failing account and choose another candidate instead of hard-pinning one provider. Do not declare unsupported Sub2API behavior in YAML as a promise that UniDesk code or runtime patches should emulate.
 - `profiles.entries` selects local Codex profile files from `~/.codex/` and maps them to Sub2API account names.
 - The unsuffixed master `~/.codex/config.toml` and `~/.codex/auth.json` are reserved for the unified Sub2API consumer. `config.toml` must keep `base_url = "https://sub2api.74-48-78-17.nip.io/"`, and `auth.json` must contain the unified pool API key from `pool.apiKeySecretName` / `pool.apiKeySecretKey`. Do not replace these two files with direct upstream account credentials.