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

name, description

name	description
unidesk-sub2api	UniDesk Sub2API 平台运维技能。用户提到 Sub2API、platform-infra sub2api、Codex pool、统一 API key、 runtime CRUD、精准批量账号操作、临时不可调度、上游错误率、客户可见错误、换号/failover、 模型映射、可用模型探测、利润核算、售价与账号退役情景、FRP 暴露、管理 UI、配置 master ~/.codex、 上游账号增删或校验 /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。

本技能遵循 Skill(cli-spec)。默认输出使用紧凑文本表格，机器处理显式使用 --json，大结果使用固定分页和精确下钻。

高频入口

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 rollout --target PK01 --dry-run
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 这类变相超级文件。

边界

• PK01 默认只允许只读诊断：
  • 只有用户在当前请求中明确要求修改 PK01，才允许变更镜像版本、YAML、Compose、容器、环境变量、Caddy/FRP、账号池、Secret 绑定或其他配置/运行面状态；
  • “修复”“恢复”“部署”或排查 Sub2API/Artificer 不自动构成 PK01 变更授权；
  • 发现根因位于 PK01 时，先保留只读证据并请求明确授权。
• YAML 是 source of truth；target、public exposure、Secret sourceRef、Codex pool 和 sentinel 配置都从 YAML 进入 CLI。
• 单目标纯版本滚动使用运行面优先快速通道：
  • 先完成受控 rollout 和既有消费配置 smoke 验收；
  • 成功后再补 MDTODO、报告和 commit；
  • 直接 push master，不创建 PR；
  • 该通道只允许目标镜像字段和对应记录变更，源码、CLI、runtime、代理、Secret、多 target 或其他配置变更必须走独立分支和 PR。
• 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、runtime CRUD、精准批量、模型探测、原生公告、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/troubleshooting-accounts.md。
• 禁止事项和越界判断：读 references/guardrails.md。