feat(api): 统一公开接口为 /api/v1 前缀

将通用生成、Gemini、可灵、火山、健康检查与 OpenAPI 的推荐入口统一到 /api/v1，并保留历史路径作为兼容别名。同步更新代理配置、接入文档、接口清单和前缀回归测试。\n\n验证：go vet ./...；go test ./...；pnpm openapi；pnpm lint；pnpm test；pnpm build；公开 OpenAPI 71 个方法与接口清单机器比对一致。
2026-07-22 08:48:32 +08:00
parent f7a5f2e808
commit 7c5a999e32
38 changed files with 2294 additions and 5169 deletions
@@ -18,7 +18,7 @@ Use this skill to operate AI Gateway administration APIs through documented, evi
 - Reuse existing pricing rules, runtime policy sets, providers, protocol clients, base models, and platforms whenever their effective behavior satisfies the target. Do not create a near-duplicate resource merely because the upstream account, base URL, or provider-side model name differs.
 - Prefer a supported standard client before using `universal` scripts. Use custom scripts only when the upstream contract cannot be represented by the existing OpenAI, Gemini, or provider-specific clients.
 - Do not invent platform config fields or assume an arbitrary config key is enforced. For `universal`, use only the recognized keys documented in `references/model-universal-platforms.md`; treat any extra key as script-owned data available through `context.env`.
- Use the module references as the primary API source. Only when the required API is absent, inspect `<gateway-api-base-url>/api-docs-json`; continue only when path, method, schema, authentication, permission, and side effects are unambiguous.
+- Use the module references as the primary API source. Only when the required API is absent, inspect `<gateway-origin>/api/v1/openapi.json`; continue only when path, method, schema, authentication, permission, and side effects are unambiguous.

 ## Module Routing

@@ -2,7 +2,7 @@

 ## Required Inputs

- Gateway API base URL. When using the bundled Web deployment this commonly includes `/gateway-api`; direct API access commonly uses port `8088`.
+- Gateway origin and public API base URL. Public API access always ends with `/api/v1`; direct local access commonly uses `http://127.0.0.1:8088/api/v1`.
 - Administrator JWT with the `manager` or `admin` role.
 - Target provider documentation and authorization material.
 - Clear requested outcome and whether real upstream calls are allowed.
@@ -10,7 +10,8 @@
 Do not place credentials in files or reusable commands. Use shell environment variables:

 ```bash
-export GATEWAY_BASE_URL='https://gateway.example.com/gateway-api'
+export GATEWAY_ORIGIN='https://gateway.example.com'
+export GATEWAY_PUBLIC_API_BASE="$GATEWAY_ORIGIN/api/v1"
 export GATEWAY_ADMIN_TOKEN='<administrator-jwt>'
 ```

@@ -24,7 +25,7 @@ For standalone or hybrid deployments, local login can return a JWT:
 curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -d '{"account":"<admin-account>","password":"<admin-password>"}' \
-  "$GATEWAY_BASE_URL/api/v1/auth/login"
+  "$GATEWAY_PUBLIC_API_BASE/auth/login"
 ```

 Do not use local login when the deployment requires OIDC or server-main identity. Obtain the deployment's administrator access token instead.
@@ -34,7 +35,7 @@ Verify identity and role before writes:
 ```bash
 curl --fail-with-body \
  -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \
-  "$GATEWAY_BASE_URL/api/v1/me"
+  "$GATEWAY_PUBLIC_API_BASE/me"
 ```

 ## Request Pattern
@@ -47,7 +48,7 @@ curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '<json-body>' \
-  "$GATEWAY_BASE_URL/api/admin/<resource>"
+  "$GATEWAY_ORIGIN/api/admin/<resource>"
 ```

 Always read current state before PATCH, DELETE, reset, disable, or full replacement. PATCH handlers for providers, base models, pricing rule sets, runtime policy sets, runner policy, and platforms write complete resource shapes rather than merging every omitted field.
@@ -67,7 +68,7 @@ Obtain explicit confirmation after showing the current snapshot and impact befor

 The live machine-readable documents are:

- `<gateway-api-base-url>/api-docs-json`
- `<gateway-api-base-url>/api-docs-yaml`
+- `<gateway-origin>/api/v1/openapi.json`
+- `<gateway-origin>/api/v1/openapi.yaml`

 Use them only when this Skill does not document the required operation. Before acting, confirm the exact path, method, body, authentication, permission, response, and side effect. Do not infer a write operation from a similarly named endpoint.
@@ -33,7 +33,7 @@ Use an authorized user JWT:
 ```bash
 curl --fail-with-body \
  -H "Authorization: Bearer <user-jwt>" \
-  "$GATEWAY_BASE_URL/api/v1/model-catalog"
+  "$GATEWAY_PUBLIC_API_BASE/model-catalog"
 ```

 Confirm model alias, model types, provider source, effective capabilities, pricing summary, rate limits, permissions, and enabled state.
@@ -57,7 +57,7 @@ curl --fail-with-body \
    "simulation": true,
    "stream": false
  }' \
-  "$GATEWAY_BASE_URL/v1/chat/completions"
+  "$GATEWAY_PUBLIC_API_BASE/chat/completions"
 ```

 Simulation verifies Gateway routing, permissions, parameter normalization, pricing, and task behavior, but it does not execute the real universal submit or poll scripts. Validate universal scripts separately against a local mock or approved provider test environment before enabling production traffic.
@@ -82,4 +82,4 @@ With explicit approval, run one real minimal request and verify upstream request

 ## Final Report

-Report resource IDs, before/after behavior, requests used for verification, simulation or real mode, billing evidence, remaining risks, rollback readiness, and whether `/api-docs-json` was used. Never include credentials or raw secret-bearing payloads.
+Report resource IDs, before/after behavior, requests used for verification, simulation or real mode, billing evidence, remaining risks, rollback readiness, and whether `/api/v1/openapi.json` was used. Never include credentials or raw secret-bearing payloads.