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、 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，大结果使用固定分页和精确下钻。

高频入口

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。
• 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。

SuperAPI 全量捕获验收

SuperAPI 全量捕获由 /root/superapi/config/superapi.yaml 控制。普通 Codex 客户端不增加 capture id、header、环境变量或专用配置。存储统一使用 UTC 日期和小时分区；查询时区只影响展示。

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 写入。
• 最短验收顺序：

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。
• 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。