From eea35425a24291fa98956199022dec5043d084c5 Mon Sep 17 00:00:00 2001
From: pikastech <liang6516@outlook.com>
Date: Sat, 18 Jul 2026 16:44:27 +0200
Subject: [PATCH] docs: add SuperAPI L0 L1 runbook

---
 .agents/skills/unidesk-sub2api/SKILL.md | 35 +++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/.agents/skills/unidesk-sub2api/SKILL.md b/.agents/skills/unidesk-sub2api/SKILL.md
index 01fceee8..ac764dd7 100644
--- a/.agents/skills/unidesk-sub2api/SKILL.md
+++ b/.agents/skills/unidesk-sub2api/SKILL.md
@@ -84,6 +84,41 @@ bun scripts/superapi-cli.ts capture validate
 - `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网关混用。
+- 最短验收顺序：
+
+```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)。