---
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 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 rollout --target PK01 --confirm
bun scripts/cli.ts job status <rollout-job-id> --tail-bytes 12000
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 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` 这类变相超级文件。

- 多 target 概要以 `config/platform-infra/sub2api.yaml` 的 target 列表为准：
  - 不使用不存在的 `platform-infra sub2api report`；
  - 单 target 运行面先用 `status --target <id>`；
  - 代理、数据库和公网路径的完整判定用 `validate --target <id>`。

- `priority` 数值越小优先级越高，`0` 合法且最高：
  - 这是 Sub2API 调度的稳定合同，后续调优不得为确认方向重复检索源码；
  - 只有真实调度结果与该合同冲突时，才下钻官方 scheduler 实现。
- 查询账号周限保护统一使用 `runtime get --account <id-or-exact-name>`：
  - 单次展示原生 5h/7d 用量、重置时间、有效自动保护阈值、阈值来源和触发状态；
  - 账号级 `auto_pause_*_threshold` 优先于全局 Ops 默认值；
  - 原生 quota probe 失败时明确标记不可用，并保留账号缓存字段，禁止把用户计费额度当成上游账号周限。
- 多节点共享同一 Sub2API 数据库时，版本升级顺序固定为 NC01 先行：
  - 每个节点都使用一次 `rollout --dry-run`、一次 `rollout --confirm` 和返回的唯一 `job status`；
  - 先在 NC01 完成共享数据、API 和公网入口验收，验收通过后再以同一流程升级 PK01；
  - 禁止用 `apply --wait` 代替版本滚动，或在外部手工串联 image-prepull、apply、status 和 validate；
  - 两个节点的目标版本都必须写入 `config/platform-infra/sub2api.yaml`，禁止从运行面反向推导或手工形成长期版本漂移。

## 边界

- 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、public-edge 或其他配置变更必须走独立分支和 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。
- NC01 共享 public-edge 的流式错误：
  - 必须先区分 Caddy response-header timeout、下游 `context canceled` 和主机资源压力；
  - 具体证据链、全站 timeout owning YAML 与非核心进程处置规则见 [references/troubleshooting-public.md](references/troubleshooting-public.md)。
- `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 <target> \
  --profile management
```

- `management l0-smoke` 一次覆盖 PostgreSQL、skill CRUD、API Key 单向保存、绑定启停、绑定级强制全文、历史导入和快照。
- 修改 Native 组件后统一使用
  `native restart --component <gateway|api|worker|web|all>`：
  - 命令按 YAML `runtime.native.stopTimeoutMs` 等待旧 PID 和固定端口释放；
  - 启动后按 `runtime.native.startTimeoutMs` 等待组件恢复 `ready`；
  - 禁止再手工紧接 `stop` 与 `start`，也不因退出延迟改用临时端口；
  - 重启返回后只需一次 `native status` 完成就绪验收。
- 绑定级强制全文必须满足：
  - `forceEnabled` 默认关闭，并与普通 `enabled` 分别保存；
  - 关闭时保持 `name + description + SKILL.md URL` 注入；
  - 开启时把标准化后的完整 `SKILL.md` 注入 instructions；
  - `enabled=false` 时不进入 Gateway 快照；
  - 没有完整 `SKILL.md` 的摘要 Skill 必须由服务端拒绝开启；
  - 配置只影响当前 API Key 与当前 Skill 的绑定，不得变成 Skill 全局开关。
- 普通 Sub2API 用户权限变更使用独立最短链：
  - 先用 `codex-pool users ensure` 创建隔离普通测试用户和 Key；
  - 用户、目标和 Key 名通过参数输入，凭据只使用命令输出的 owner-only
    `sourceRef`；
  - 禁止把一次性用户 ID、邮箱或凭据路径写成通用默认值；
  - 创建 fixture 后先运行 `auth l0-smoke`；
  - 只有 L0 PASS 才运行 `native status`、`auth l1-user-smoke` 和 typed
    `ordinary-user` Web smoke；
  - `auth l1-user-smoke` 一次覆盖自己的 Key 同步、别名和绑定 round-trip、
    历史 403、跨用户 403、Key 注册 403 和 Secret 脱敏；
  - typed `ordinary-user` Web smoke 一次覆盖历史导航隐藏、`/history` 深链
    回退、同会话历史 API 403、注册按钮隐藏和绑定弹框；
  - 请求历史只对管理员开放；
  - 普通用户不得看到历史导航，且后端 `history.list|get` 必须返回 403；
  - 浏览器内验证预期 403 时使用 BrowserContext API request；
  - 禁止使用页面 `fetch`，避免把预期拒绝误记为 console failure。
- 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。
  - 强制全文验收分成两个独立证据：
    - L0 使用一次性本地 Responses helper 和正式注入函数；
    - 真实 `codex exec` 必须完整接收并回显测试正文；
    - 以正文完整字节数和逐字一致性判定，不使用短 marker 代替。
    - L1 从捕获记录的 `upstream.body.instructions` 逐字核对完整 `SKILL.md`；
    - 同轮 Codex 输出按固定标签覆盖 Skill 的全部章节和规则。
  - 模型可能拒绝逐字复述隐藏 instructions：
    - 该拒绝不能判定为注入失败；
    - 不重复诱导模型泄露隐藏提示词；
    - 全文到达由上游请求捕获的逐字比对证明；
    - Codex 侧改用详细、非逐字的结构化回显证明可用性。
  - 临时开启绑定级 `forceEnabled` 时：
    - 先读取原值；
    - 测试驱动必须在 `finally` 中恢复；
    - 收口再次查询绑定状态，不能只相信清理代码已执行。
- 多 Remote Skill 加载验收：
  - gateway catalog 为当前 Key 的多个公开 Skill 生成一个批量文档 URL；
  - Agent 按当前 OS 执行 catalog 中的一条命令，一次读取全部完整
    `SKILL.md`；
  - 禁止先试网页搜索、浏览器或索引型 URL reader；
  - 禁止再逐个请求 catalog 中的单 Skill URL；
  - `l0 probe` 的 `REMOTE_SKILL_BATCH=true` 证明批量边界和加载指令成立；
  - 真实 Codex 验收必须看到一条批量命令成功和全部 Skill 的内容级概述。
- SuperAPI 公网状态：
  - 项目 CLI 内部使用
    `platform-infra public-edge status --site <site-id>`；
  - 专站查询只投影该站点 DNS 与 health failure；
  - 容器、监听器、Caddy、provenance 和配置一致性仍使用全局事实；
  - 禁止让全站列表体积或其他站点 failure 造成当前站点误报。

## 何时读取 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)。
