--- name: unidesk-sub2api description: >- UniDesk Sub2API 平台运维技能。用户提到 Sub2API、platform-infra sub2api、Codex pool、统一 API key、 runtime CRUD、精准批量账号操作、临时不可调度、上游错误率、客户可见错误、换号/failover、 模型映射、可用模型探测、利润核算、售价与账号退役情景、FRP 暴露、管理 UI、配置 master ~/.codex、 SuperAPI 企业 skill 上游加载与全量捕获、上游账号增删或校验 /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`，大结果使用固定分页和精确下钻。 ## 高频入口 ```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 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 bun scripts/cli.ts platform-infra sub2api codex-pool runtime get --target PK01 --account bun scripts/cli.ts platform-infra sub2api codex-pool runtime events --target PK01 --since 8h ``` 先看报表和状态，再做计划或变更。详细规则按职责拆在 `references/` 下；不要新增 `full.md`、`all.md`、`guide.md` 这类变相超级文件。 - `priority` 数值越小优先级越高，`0` 合法且最高： - 这是 Sub2API 调度的稳定合同，后续调优不得为确认方向重复检索源码； - 只有真实调度结果与该合同冲突时，才下钻官方 scheduler 实现。 - 查询账号周限保护统一使用 `runtime get --account `： - 单次展示原生 5h/7d 用量、重置时间、有效自动保护阈值、阈值来源和触发状态； - 账号级 `auto_pause_*_threshold` 优先于全局 Ops 默认值； - 原生 quota probe 失败时明确标记不可用，并保留账号缓存字段，禁止把用户计费额度当成上游账号周限。 ## 边界 - 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 验收； - 成功后再补 TaskTree ExecutionReport 和 commit；遗留 MDTODO 按 `$unidesk-tasktree` 迁移； - 直接 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` 输出结构化结果；命令只读且不在前台模拟自动刷新。 - ApiState 评分 workflow 的状态查询走 `/root/apistate/scripts/apistate-cli.ts workflow status --id `： - 默认文本只披露 workflow 身份、终态、错误、评分窗口和分组/账号计数； - 需要完整 `groups/accounts` 结果时显式增加 `--json`； - 禁止为确认终态先展开完整评分 payload。 - ApiState 周期评分的数据处理边界： - Sub2API 原生 admin/ops API 提供账号、usage、客户错误、可用性和并发事实； - `runtime events` 只在目标侧筛选并归一化 policy marker 及其最终 HTTP 状态，默认表格仅展示有界摘要； - 账号分桶、TTFT、Token、成本、错误归因、failover 恢复和跨组去重统一在 NC01 ApiState worker 聚合； - 禁止周期评分重新调用 `runtime errors --group` 的远端逐账号 Python 聚合。 - `ops diagnosis` 的指标来自原生 admin/ops API；v0.1.155 没有独立 diagnosis/advice endpoint，CLI 必须把官方前端投影建议与 API 已验证事实分开呈现。 - `ops channels` 使用原生渠道监控的 `7d`、`15d`、`30d` 窗口，支持平台、渠道和模型下钻；渠道历史固定分页并用 `--page-token ` 向更早记录翻页，`--record ` 精确下钻，不提供手工 `--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/troubleshooting.md) 和 [references/public-exposure.md](references/public-exposure.md)。 ## SuperAPI 全量捕获验收 SuperAPI 全量捕获由 `/root/superapi/config/superapi.yaml` 控制。普通 Codex 客户端不增加 capture id、header、环境变量或专用配置。存储统一使用 UTC 日期和小时分区；查询时区只影响展示。 ```bash cd /root/superapi bun scripts/superapi-cli.ts config validate bun scripts/superapi-cli.ts l0 probe bun scripts/superapi-cli.ts capture status bun scripts/superapi-cli.ts capture list --kind all --time-zone Asia/Shanghai bun scripts/superapi-cli.ts capture validate ``` - `l0 probe` 必须显示 `PROXY_MODULE true`，在 L1 前覆盖代理模块解析。 - `capture validate` 聚合验证配额、双向 JSONL、UTC 路径、`0700`/`0600` 权限、配置 API Key 脱敏和请求/响应摘要；默认不输出 body。 - `capture list` 只做渐进披露摘要；只有展示需要才显式指定 IANA 时区。 ## SuperAPI 管理面 L0/L1 - 项目和 owning YAML 固定入口： - 仓库为 `/root/superapi`； - 配置为 `/root/superapi/config/superapi.yaml`； - 项目名统一使用 SuperAPI，不与硬件 AI网关混用。 - SuperAPI 共享公网入口由 UniDesk public-edge 唯一 authority 收敛： - `/root/superapi/config/superapi.yaml#publicExposure` 仍是产品 owning YAML； - `config/platform-infra/public-edge.yaml` 的 SuperAPI site 必须 pin 该仓库 40 位 commit； - public-edge renderer 只用 `git show` 读取 pinned YAML，不读取 SuperAPI working tree； - 修改 `publicExposure` 时先提交 SuperAPI，再在 UniDesk PR 更新 `sourceCommit`； - 禁止 SuperAPI L1、CLI 或人工会话执行 public-edge 强写、内部 reconcile 或 Caddyfile 写入。 - 最短验收顺序： ```bash cd /root/superapi bun scripts/superapi-cli.ts management l0-smoke bun scripts/superapi-cli.ts native status bun scripts/superapi-cli.ts public status cd /root/unidesk bun scripts/cli.ts web-probe product-smoke \ --product superapi \ --target NC01 \ --profile management ``` - `management l0-smoke` 一次覆盖 PostgreSQL、skill CRUD、API Key 单向保存、绑定启停、历史导入和快照。 - L1 必须同时满足： - gateway、API、worker、Web 四个 native 进程 ready； - `public status` 的声明、期望配置、DNS 和健康检查 ready； - typed product smoke 的三页 DOM、console、network 和截图通过。 - Basic Auth 的认证 selector 与页面业务 selector 分开声明： - 认证阶段只证明 401/200 边界和页面文档可达； - 页面业务 selector 由 product smoke 独立断言； - `artifact inspect` 用于下钻脱敏 auth 状态，不直接读取原始浏览器报告。 - Vite native proxy 只代理管理 API 前缀，不得使用会误吞 `/api-keys` 页面路由的宽泛 `/api` 前缀。 - 真实 Codex 验收使用标准 provider 配置和已有 API Key： - 不修改 Codex； - 不增加 capture id、header 或 SuperAPI 专用环境变量； - 请求后用 `capture validate` 和历史详情核对同一 request id 的 request/response。 ## 何时读取 reference - 部署、状态、target 边界、PK01 host-Docker、k3s target、egress proxy、镜像升级：读 [references/operations.md](references/operations.md)。 - Codex pool、统一 key、runtime CRUD、精准批量、模型探测、原生公告、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/troubleshooting-accounts.md](references/troubleshooting-accounts.md)。 - 禁止事项和越界判断：读 [references/guardrails.md](references/guardrails.md)。