---
name: unidesk-sub2api
description: UniDesk Sub2API 平台运维技能。用户提到 Sub2API、sub2api、platform-infra sub2api、Codex pool、统一 API key、Sub2API FRP 暴露、Sub2API 管理 UI、配置 master ~/.codex 走 Sub2API、添加/删除 Codex 上游账号、校验 Sub2API /v1/models 时使用。
---

# UniDesk Sub2API

UniDesk 通过 `platform-infra sub2api` 运维 YAML 选中的 Sub2API target；当前 active target 以 `config/platform-infra/sub2api.yaml` 为准，可能是 PK01 host-Docker 或 k3s target。日常操作统一使用 UniDesk CLI，不直接写 Kubernetes 资源、不手工调用 Sub2API 管理 API、不打印 Secret。

## 高频入口

```bash
bun scripts/cli.ts platform-infra sub2api report
bun scripts/cli.ts platform-infra sub2api status --target PK01
bun scripts/cli.ts platform-infra sub2api validate --target PK01
bun scripts/cli.ts platform-infra sub2api plan --target PK01
bun scripts/cli.ts platform-infra sub2api image-prepull --target PK01 --confirm
```

先看报表和状态，再做计划或变更。详细规则按职责拆在 `references/` 下；不要新增 `full.md`、`all.md`、`guide.md` 这类变相超级文件。

## 边界

- YAML 是 source of truth；target、public exposure、Secret sourceRef、Codex pool 和 sentinel 配置都从 YAML 进入 CLI。
- Secret 只输出对象名、key 名、presence、fingerprint 或 redacted prefix；禁止打印完整 token/key。
- 默认 active target 以 YAML `defaults.targetId` 和 target role 为准；当前 `api.pikapython.com` 对应 PK01 host-Docker target。
- Codex pool、统一 API key、master `~/.codex` 配置、FRP/Caddy 暴露、账号增删都必须走本技能的受控 CLI。
- `api.pikapython.com` 异常先按 YAML target 区分 PK01 local edge/app、k3s FRP target 和账号池调度；用 `status`、`validate`、受控 apply/sync 以及最小 `/v1/responses` smoke 做分层恢复。完整步骤见 [references/troubleshooting.md](references/troubleshooting.md) 和 [references/public-exposure.md](references/public-exposure.md)。

## 何时读取 reference

- 部署、状态、target 边界、PK01 host-Docker、k3s target、egress proxy、镜像升级：读 [references/operations.md](references/operations.md)。
- Codex pool、统一 key、trace、account temp-unschedulable、`codex-pool sync|validate`：读 [references/codex-pool.md](references/codex-pool.md)。
- Sentinel、marker-only 判定、账号冻结/恢复、`sentinel-report|sentinel-probe|sentinel-image`：读 [references/sentinel.md](references/sentinel.md)。
- 受保护手动账号代理、分组绑定、WebUI account test：读 [references/manual-accounts.md](references/manual-accounts.md)。
- 添加或删除上游 profile/account：读 [references/upstreams.md](references/upstreams.md)。
- FRP/Caddy、PK01 shared Caddy managed block、public URL 暴露：读 [references/public-exposure.md](references/public-exposure.md)。
- master `~/.codex` 统一消费端配置：读 [references/local-codex-consumer.md](references/local-codex-consumer.md)。
- closeout 验收和最小 smoke：读 [references/validation.md](references/validation.md)。
- 排障总入口：先读 [references/troubleshooting.md](references/troubleshooting.md)，再按失败层读取运行面、账号池或公网暴露专题。
- 禁止事项和越界判断：读 [references/guardrails.md](references/guardrails.md)。
