Codex
6.6 KiB
6.6 KiB
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
bun scripts/cli.ts platform-infra sub2api codex-pool runtime get --target PK01 --account <id-or-exact-name>
先看报表和状态，再做计划或变更。详细规则按职责拆在 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 验收； - 成功后再补 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输出结构化结果；命令只读且不在前台模拟自动刷新。 - ApiState 评分 workflow 的状态查询走
/root/apistate/scripts/apistate-cli.ts workflow status --id <workflow-id>：- 默认文本只披露 workflow 身份、终态、错误、评分窗口和分组/账号计数；
- 需要完整
groups/accounts结果时显式增加--json； - 禁止为确认终态先展开完整评分 payload。
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/responsessmoke 做分层恢复。完整步骤见 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。