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

---
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 <id-or-exact-name>
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 <id-or-exact-name>`：
  - 单次展示原生 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-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-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/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)。