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

name, description

name	description
unidesk-sub2api	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。

高频入口

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 ops diagnosis --target PK01
bun scripts/cli.ts platform-infra sub2api ops channels --target PK01 --window 7d
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。
• 原生运维快照统一走 ops diagnosis|channels：默认输出紧凑文本，显式 --json 输出结构化结果；命令只读且不在前台模拟自动刷新。
• ops diagnosis 的指标来自原生 admin/ops API；v0.1.155 没有独立 diagnosis/advice endpoint，CLI 必须把官方前端投影建议与 API 已验证事实分开呈现。
• ops channels 使用原生渠道监控的 7d、15d、30d 窗口，支持平台、渠道和模型下钻；渠道历史固定分页并用 --page-token <record-id> 向更早记录翻页，--record <record-id> 精确下钻，不提供手工 --limit；原生响应未提供刷新倒计时时必须显示 unsupported。
• 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/public-exposure.md。

何时读取 reference

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