mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
866afde16b2eb208da7ce5ad21dad584ab70cf52
pikasTech-unidesk/.agents/skills/unidesk-sub2api/SKILL.md
T
pikastech 866afde16b fix(cicd): 收敛 public-edge 单一写入权
2026-07-18 17:59:04 +02:00

10 KiB
Raw Blame History

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 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/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 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

Reference in New Issue View Git Blame Copy Permalink