diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..faa929c --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,109 @@ +name: ci + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + verify: + runs-on: easyai-gateway-ci-unprivileged-v2 + env: + TRIVY_DB_REPOSITORY: ghcr.m.daocloud.io/aquasecurity/trivy-db:2 + steps: + - name: Checkout without external Actions + env: + CI_REPOSITORY: ${{ github.repository }} + CI_SERVER_URL: ${{ github.server_url }} + CI_SHA: ${{ github.sha }} + CI_JOB_TOKEN: ${{ github.token }} + CI_EVENT_BEFORE: ${{ github.event.before }} + CI_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }} + run: | + set -eu + test -n "$CI_JOB_TOKEN" + authorization=$(printf 'x-access-token:%s' "$CI_JOB_TOKEN" | base64 | tr -d '\n') + git init . + git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \ + fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" "$CI_SHA" + for comparison_sha in "$CI_EVENT_BEFORE" "$CI_PR_BASE_SHA"; do + case "$comparison_sha" in + [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*) + if test "${#comparison_sha}" -eq 40 && \ + test "$comparison_sha" != 0000000000000000000000000000000000000000; then + git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \ + fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" "$comparison_sha" + fi + ;; + esac + done + unset authorization CI_JOB_TOKEN + test ! -f .git/shallow + git checkout --detach "$CI_SHA" + test "$(git rev-parse HEAD)" = "$CI_SHA" + - name: Verify pinned host toolchains + run: | + go version + node --version + pnpm --version + docker-compose version + shellcheck --version + trivy --version + govulncheck -version + - name: Verify production migration safety + env: + CI_EVENT_NAME: ${{ github.event_name }} + CI_EVENT_BEFORE: ${{ github.event.before }} + CI_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }} + run: | + production_base=$(cat deploy/ci/production-migration-base) + immutable_base=$CI_EVENT_BEFORE + if test "$CI_EVENT_NAME" = pull_request; then + immutable_base=$CI_PR_BASE_SHA + fi + case "$immutable_base" in + [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*) + test "${#immutable_base}" -eq 40 + test "$immutable_base" != 0000000000000000000000000000000000000000 + ;; + *) exit 1 ;; + esac + git merge-base --is-ancestor "$immutable_base" HEAD + node ./scripts/ci-validate-migrations.mjs \ + "$production_base" "$immutable_base" + - name: Verify Go formatting + run: | + unformatted=$(gofmt -l apps/api) + test -z "$unformatted" || { + printf 'Go files require gofmt:\n%s\n' "$unformatted" >&2 + exit 1 + } + - name: Verify Go code + working-directory: apps/api + run: | + go vet ./... + go test ./... + govulncheck ./... + - run: pnpm install --frozen-lockfile + - run: pnpm lint + - run: pnpm test + - run: pnpm build + - name: Audit JavaScript dependencies + run: pnpm audit --audit-level high + - name: Validate deployment configuration + run: | + docker-compose -f docker-compose.yml config --quiet + shellcheck scripts/ci-build-images.sh scripts/ci-validate-semver.sh \ + scripts/provision-ci-runner.sh tests/ci/ci-build-images-test.sh \ + tests/ci/migrations-test.sh tests/ci/pipeline-test.sh \ + tests/ci/semver-test.sh + ./tests/ci/ci-build-images-test.sh + ./tests/ci/migrations-test.sh + ./tests/ci/pipeline-test.sh + ./tests/ci/semver-test.sh + - name: Scan repository + run: | + trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL \ + --ignore-unfixed --exit-code 1 --timeout 15m --skip-dirs .git \ + --skip-dirs node_modules . diff --git a/.gitea/workflows/release-ci.yml b/.gitea/workflows/release-ci.yml new file mode 100644 index 0000000..c73b2c9 --- /dev/null +++ b/.gitea/workflows/release-ci.yml @@ -0,0 +1,94 @@ +name: release-ci + +on: + push: + tags: ['v*'] + +jobs: + verify-tag: + runs-on: easyai-gateway-ci-unprivileged-v2 + env: + TRIVY_DB_REPOSITORY: ghcr.m.daocloud.io/aquasecurity/trivy-db:2 + steps: + - name: Checkout without external Actions + env: + CI_REPOSITORY: ${{ github.repository }} + CI_SERVER_URL: ${{ github.server_url }} + CI_SHA: ${{ github.sha }} + CI_JOB_TOKEN: ${{ github.token }} + run: | + set -eu + test -n "$CI_JOB_TOKEN" + authorization=$(printf 'x-access-token:%s' "$CI_JOB_TOKEN" | base64 | tr -d '\n') + git init . + git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \ + fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" "$CI_SHA" + unset authorization CI_JOB_TOKEN + test ! -f .git/shallow + git checkout --detach FETCH_HEAD + - name: Verify pinned host toolchains + run: | + go version + node --version + pnpm --version + docker-compose version + shellcheck --version + trivy --version + govulncheck -version + - name: Verify release tag ancestry + env: + CI_REPOSITORY: ${{ github.repository }} + CI_SERVER_URL: ${{ github.server_url }} + CI_SHA: ${{ github.sha }} + CI_JOB_TOKEN: ${{ github.token }} + run: | + set -eu + tag_name=${GITHUB_REF#refs/tags/} + ./scripts/ci-validate-semver.sh "$tag_name" + authorization=$(printf 'x-access-token:%s' "$CI_JOB_TOKEN" | base64 | tr -d '\n') + git -c "http.extraHeader=AUTHORIZATION: basic $authorization" \ + fetch --no-tags "$CI_SERVER_URL/$CI_REPOSITORY.git" \ + +refs/heads/main:refs/remotes/origin/main + unset authorization CI_JOB_TOKEN + test ! -f .git/shallow + test "$(git rev-parse HEAD)" = "$CI_SHA" + git merge-base --is-ancestor "$CI_SHA" refs/remotes/origin/main + - name: Verify production migration safety + run: | + production_base=$(cat deploy/ci/production-migration-base) + node ./scripts/ci-validate-migrations.mjs "$production_base" + - name: Verify Go formatting + run: | + unformatted=$(gofmt -l apps/api) + test -z "$unformatted" || { + printf 'Go files require gofmt:\n%s\n' "$unformatted" >&2 + exit 1 + } + - name: Verify Go code + working-directory: apps/api + run: | + go vet ./... + go test ./... + govulncheck ./... + - run: pnpm install --frozen-lockfile + - run: pnpm lint + - run: pnpm test + - run: pnpm build + - name: Audit JavaScript dependencies + run: pnpm audit --audit-level high + - name: Validate deployment configuration + run: | + docker-compose -f docker-compose.yml config --quiet + shellcheck scripts/ci-build-images.sh scripts/ci-validate-semver.sh \ + scripts/provision-ci-runner.sh tests/ci/ci-build-images-test.sh \ + tests/ci/migrations-test.sh tests/ci/pipeline-test.sh \ + tests/ci/semver-test.sh + ./tests/ci/ci-build-images-test.sh + ./tests/ci/migrations-test.sh + ./tests/ci/pipeline-test.sh + ./tests/ci/semver-test.sh + - name: Scan repository + run: | + trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL \ + --ignore-unfixed --exit-code 1 --timeout 15m --skip-dirs .git \ + --skip-dirs node_modules . diff --git a/.gitignore b/.gitignore index 5121d4a..bbc1ffa 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ node_modules/ *.log apps/api/bin/ +apps/api/gateway apps/api/tmp/ apps/api/data/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..81dd82b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# EasyAI AI Gateway 智能体协作规则 + +本文件是本仓库内 AI 编码智能体的项目级执行约束。开始工作前必须先阅读本文件，并以实际代码、测试和运行结果作为结论依据。 + +## 协作语言 + +1. 面向用户的回复、进度更新、验收报告、代码审查意见、Issue、PR 标题和 PR 描述默认使用中文。 +2. Git 提交信息使用 `(): <中文摘要>` 格式，`scope` 可省略。 +3. `type` 使用小写英文，可选值为 `feat`、`fix`、`docs`、`test`、`refactor`、`perf`、`build`、`ci`、`chore`、`revert`。 +4. 提交摘要和正文必须使用中文；专有名词、协议名称、命令、路径、代码标识符和第三方原始错误可保留原文。 +5. 摘要应简洁明确，末尾不加句号，不得使用“更新代码”“修复问题”等无法说明意图的模糊描述。 +6. 非简单变更应在提交正文或 PR 描述中用中文说明原因、影响、风险和验证结果。 + +## 仓库边界 + +1. 后端位于 `apps/api`，前端位于 `apps/web`，共享 TypeScript 契约位于 `packages/contracts`。 +2. 修改 HTTP 接口、请求或响应类型后，必须执行 `pnpm openapi` 并提交匹配的 OpenAPI 产物。 +3. 数据库迁移只能新增，禁止修改已经进入生产基线的历史迁移；迁移必须通过生产迁移安全检查。 +4. 不得把 `.env`、密码、Secret、Token、授权码、私钥或生产凭据提交到 Git、日志、测试输出或验收证据中。 +5. 当前工作区存在用户改动时必须保留，不得覆盖、清理、重置或混入当前任务提交；需要隔离时使用独立分支、克隆或 worktree。 + +## 验证要求 + +根据改动范围执行最小充分验证；准备合并或发布时执行完整门禁： + +```bash +cd apps/api && go vet ./... && go test ./... && govulncheck ./... +pnpm install --frozen-lockfile +pnpm lint +pnpm test +pnpm build +pnpm audit --audit-level high +docker compose -f docker-compose.yml config --quiet +./tests/ci/ci-build-images-test.sh +./tests/ci/migrations-test.sh +./tests/ci/pipeline-test.sh +./tests/ci/semver-test.sh +``` + +修改 Shell 脚本后还必须执行 `bash -n` 和 ShellCheck。修改 Go 文件后必须确认 `gofmt -l` 没有输出。 + +## Git 与 CI/CD + +1. 一个提交只包含一个逻辑变更，提交前检查暂存差异并确认不含敏感信息。 +2. `main` 只能通过短生命周期分支和 PR 合并，禁止直接推送或强制推送。 +3. PR 必须通过精确的 `ci / verify (pull_request)` 状态后才能合并；合并后还要确认同一 SHA 的 `ci / verify (push)` 成功。 +4. 生产版本仅使用稳定 SemVer `vMAJOR.MINOR.PATCH` 标签，并同时要求 `release-ci / verify-tag (push)` 成功。 +5. 未验证 protected tag、发布账本、数据库备份、健康检查和回滚路径时，不得声称 CI/CD 或生产发布已经完成。 diff --git a/README.md b/README.md index 60fa346..0ba901e 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,10 @@ Web 容器的 Nginx 配置通过 bind mount 挂载自仓库文件 [docker/nginx. docker compose -f docker-compose.yml restart web ``` +## 生产 CI/CD + +Gitea Actions 会在隔离的 rootless DinD Runner 中对 Pull Request、`main` Push 和版本 Tag 执行完整质量门禁；Tag 使用独立的 `release-ci / verify-tag (push)` context，不能复用旧的 `main` 成功状态。源码 Job 没有宿主 Docker、`sudo` 或生产部署权限。部署仓的 root-owned dispatcher 只在相同 SHA 的 `main` 与 Tag context 都成功后，用固定命令构建并扫描镜像，再以 Registry digest 发布 `ai.51easyai.com`。安装 Runner、Fork PR 审批、发布验证和回滚步骤见 [生产 CI/CD 运行手册](docs/runbooks/production-ci-cd.md)，信任边界见 [ADR-001](docs/decisions/001-production-cicd.md)。 + Compose 默认使用独立容器数据库 `postgres:18-alpine`，数据卷会保留在 `postgres_data` 和 `api_data`。为避免本地开发 `.env` 中的 `localhost` 数据库地址污染容器部署，compose 使用 `AI_GATEWAY_COMPOSE_*` 变量作为容器部署专用覆盖，例如： ```bash diff --git a/apps/api/cmd/migrate/identity_pairing_start_reservation_migration_integration_test.go b/apps/api/cmd/migrate/identity_pairing_start_reservation_migration_integration_test.go index 7f68de3..fd303f5 100644 --- a/apps/api/cmd/migrate/identity_pairing_start_reservation_migration_integration_test.go +++ b/apps/api/cmd/migrate/identity_pairing_start_reservation_migration_integration_test.go @@ -10,149 +10,45 @@ import ( "github.com/google/uuid" "github.com/jackc/pgx/v5/pgconn" - "github.com/jackc/pgx/v5/pgxpool" ) -const identityPairingStartReservationUpgradeMigration = "../../migrations/0073_identity_pairing_start_reservation_upgrade.sql" +const identityPairingStartReservationMigration = "../../migrations/0068_identity_pairing_start_reservation.sql" -func TestIdentityPairingStartReservationUpgradeMigrationDefinesCurrentLifecycle(t *testing.T) { - payload, err := os.ReadFile(identityPairingStartReservationUpgradeMigration) +func TestIdentityPairingStartReservationMigrationDefinesCurrentLifecycle(t *testing.T) { + payload, err := os.ReadFile(identityPairingStartReservationMigration) if err != nil { t.Fatal(err) } content := strings.ToLower(string(payload)) for _, required := range []string{ - "add column if not exists state text", - "add column if not exists revision_id uuid", - "add column if not exists updated_at timestamptz", - "alter column state set not null", + "state text not null default 'starting'", + "revision_id uuid unique references gateway_identity_configuration_revisions", + "updated_at timestamptz not null default now()", "gateway_identity_pairing_start_state_check", - "foreign key (revision_id)", - "idx_gateway_identity_pairing_start_revision_unique", "idx_gateway_identity_pairing_start_expiry", - "canonical_pairing", - "on conflict (singleton) do update", + "on conflict do nothing", } { if !strings.Contains(content, required) { - t.Fatalf("identity pairing start reservation upgrade migration is missing %q", required) + t.Fatalf("identity pairing start reservation migration is missing %q", required) } } - for _, forbidden := range []string{"exchange_token text", "client_secret", "machine_secret", "secret_value"} { + for _, forbidden := range []string{"exchange_token text", "client_secret", "machine_secret", "secret_value", "drop ", "do $"} { if strings.Contains(content, forbidden) { - t.Fatalf("identity pairing start reservation upgrade migration stores forbidden value field %q", forbidden) + t.Fatalf("identity pairing start reservation migration contains forbidden content %q", forbidden) } } } -func TestIdentityPairingStartReservationUpgradeMigratesLegacyShapeAndIsIdempotent(t *testing.T) { +func TestIdentityPairingStartReservationMigrationSeedsOutstandingPairing(t *testing.T) { pool := newIdentityMigrationPostgresTestSchema(t) ctx := context.Background() - applyIdentityPairingStartReservationPrerequisites(t, ctx, pool) - - revisionID, pairingID, pairingExpiresAt := seedOutstandingIdentityPairingForReservationMigration(t, ctx, pool) - legacyAttemptID := uuid.NewString() - if _, err := pool.Exec(ctx, ` -CREATE TABLE gateway_identity_pairing_start_reservation ( - singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton), - attempt_id uuid NOT NULL UNIQUE, - expires_at timestamptz NOT NULL, - created_at timestamptz NOT NULL DEFAULT now() -)`); err != nil { - t.Fatalf("create legacy pairing start reservation: %v", err) - } - if _, err := pool.Exec(ctx, ` -INSERT INTO gateway_identity_pairing_start_reservation(singleton,attempt_id,expires_at) -VALUES(true,$1::uuid,now()+interval '2 minutes')`, legacyAttemptID); err != nil { - t.Fatalf("seed legacy pairing start reservation: %v", err) - } - - applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration) - assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt) - assertIdentityPairingStartReservationSchema(t, ctx, pool) - - // Migration runners apply each version once, but a repeat execution proves - // that recovery from an interrupted/manual rollout does not duplicate state. - applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration) - assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt) - assertIdentityPairingStartReservationSchema(t, ctx, pool) -} - -func TestIdentityPairingStartReservationUpgradePreservesLegacyStartingLease(t *testing.T) { - pool := newIdentityMigrationPostgresTestSchema(t) - ctx := context.Background() - applyIdentityPairingStartReservationPrerequisites(t, ctx, pool) - - attemptID := uuid.NewString() - expiresAt := time.Now().UTC().Add(2 * time.Minute).Truncate(time.Microsecond) - if _, err := pool.Exec(ctx, ` -CREATE TABLE gateway_identity_pairing_start_reservation ( - singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton), - attempt_id uuid NOT NULL UNIQUE, - expires_at timestamptz NOT NULL, - created_at timestamptz NOT NULL DEFAULT now() -)`); err != nil { - t.Fatalf("create legacy pairing start reservation: %v", err) - } - if _, err := pool.Exec(ctx, ` -INSERT INTO gateway_identity_pairing_start_reservation(singleton,attempt_id,expires_at) -VALUES(true,$1::uuid,$2)`, attemptID, expiresAt); err != nil { - t.Fatalf("seed legacy starting reservation: %v", err) - } - - applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration) - applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration) - - var gotAttemptID, state string - var revisionID *string - var gotExpiresAt, updatedAt time.Time - if err := pool.QueryRow(ctx, ` -SELECT attempt_id::text,state,revision_id::text,expires_at,updated_at -FROM gateway_identity_pairing_start_reservation`). - Scan(&gotAttemptID, &state, &revisionID, &gotExpiresAt, &updatedAt); err != nil { - t.Fatalf("read upgraded legacy starting reservation: %v", err) - } - if gotAttemptID != attemptID || state != "starting" || revisionID != nil || - !gotExpiresAt.Equal(expiresAt) || updatedAt.IsZero() { - t.Fatalf("unexpected upgraded starting reservation attempt=%q state=%q revision=%v expires=%v updated=%v", - gotAttemptID, state, revisionID, gotExpiresAt, updatedAt) - } - - _, err := pool.Exec(ctx, `UPDATE gateway_identity_pairing_start_reservation SET state='paired'`) - requireIdentityPairingStartReservationMigrationCode(t, err, "23514", "paired reservation without revision") -} - -func TestIdentityPairingStartReservationUpgradeAcceptsFresh0071Schema(t *testing.T) { - pool := newIdentityMigrationPostgresTestSchema(t) - ctx := context.Background() - applyIdentityPairingStartReservationPrerequisites(t, ctx, pool) - - revisionID, pairingID, pairingExpiresAt := seedOutstandingIdentityPairingForReservationMigration(t, ctx, pool) - applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0071_identity_pairing_start_reservation.sql") - assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt) - - applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration) - applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationUpgradeMigration) - assertCurrentIdentityPairingStartReservation(t, ctx, pool, pairingID, revisionID, pairingExpiresAt) - assertIdentityPairingStartReservationSchema(t, ctx, pool) -} - -func applyIdentityPairingStartReservationPrerequisites(t *testing.T, ctx context.Context, pool *pgxpool.Pool) { - t.Helper() for _, migration := range []string{ - "../../migrations/0067_identity_configuration_revisions.sql", - "../../migrations/0068_identity_onboarding_exchanges.sql", - "../../migrations/0069_identity_pairing_cancellation.sql", + "../../migrations/0065_identity_configuration_revisions.sql", + "../../migrations/0066_identity_onboarding_exchanges.sql", } { applyIdentityMigrationTestFile(t, ctx, pool, migration) } -} -func seedOutstandingIdentityPairingForReservationMigration( - t *testing.T, - ctx context.Context, - pool *pgxpool.Pool, -) (string, string, time.Time) { - t.Helper() revisionID := uuid.NewString() pairingID := uuid.NewString() expiresAt := time.Now().UTC().Add(30 * time.Minute).Truncate(time.Microsecond) @@ -170,79 +66,31 @@ INSERT INTO gateway_identity_onboarding_exchanges ( pairingID, revisionID, uuid.NewString(), "identity-exchange-"+pairingID, expiresAt); err != nil { t.Fatalf("seed identity exchange for pairing reservation migration: %v", err) } - return revisionID, pairingID, expiresAt -} -func assertCurrentIdentityPairingStartReservation( - t *testing.T, - ctx context.Context, - pool *pgxpool.Pool, - wantAttemptID string, - wantRevisionID string, - wantExpiresAt time.Time, -) { - t.Helper() - var count int - var attemptID, state, revisionID string - var expiresAt, updatedAt time.Time + applyIdentityMigrationTestFile(t, ctx, pool, identityPairingStartReservationMigration) + + var attemptID, state, reservedRevisionID string + var gotExpiresAt, updatedAt time.Time if err := pool.QueryRow(ctx, ` -SELECT count(*) OVER (),attempt_id::text,state,revision_id::text,expires_at,updated_at -FROM gateway_identity_pairing_start_reservation`). - Scan(&count, &attemptID, &state, &revisionID, &expiresAt, &updatedAt); err != nil { - t.Fatalf("read upgraded pairing start reservation: %v", err) +SELECT attempt_id::text,state,revision_id::text,expires_at,updated_at +FROM gateway_identity_pairing_start_reservation`).Scan( + &attemptID, &state, &reservedRevisionID, &gotExpiresAt, &updatedAt, + ); err != nil { + t.Fatalf("read pairing start reservation: %v", err) } - if count != 1 || attemptID != wantAttemptID || state != "paired" || revisionID != wantRevisionID || - !expiresAt.Equal(wantExpiresAt) || updatedAt.IsZero() { - t.Fatalf("unexpected upgraded pairing reservation count=%d attempt=%q state=%q revision=%q expires=%v updated=%v", - count, attemptID, state, revisionID, expiresAt, updatedAt) - } -} - -func assertIdentityPairingStartReservationSchema(t *testing.T, ctx context.Context, pool *pgxpool.Pool) { - t.Helper() - for _, column := range []struct { - name string - wantDefaultFragment string - }{ - {name: "state", wantDefaultFragment: "starting"}, - {name: "updated_at", wantDefaultFragment: "now()"}, - } { - var nullable, defaultExpression string - if err := pool.QueryRow(ctx, ` -SELECT is_nullable,COALESCE(column_default,'') -FROM information_schema.columns -WHERE table_schema=current_schema() - AND table_name='gateway_identity_pairing_start_reservation' - AND column_name=$1`, column.name).Scan(&nullable, &defaultExpression); err != nil { - t.Fatalf("read upgraded pairing reservation column %s: %v", column.name, err) - } - if nullable != "NO" || !strings.Contains(defaultExpression, column.wantDefaultFragment) { - t.Fatalf("pairing reservation column %s nullable=%q default=%q", column.name, nullable, defaultExpression) - } - } - - var expiryIndex, revisionIndex string - if err := pool.QueryRow(ctx, `SELECT pg_get_indexdef('idx_gateway_identity_pairing_start_expiry'::regclass)`). - Scan(&expiryIndex); err != nil { - t.Fatalf("read pairing reservation expiry index: %v", err) - } - if err := pool.QueryRow(ctx, `SELECT pg_get_indexdef('idx_gateway_identity_pairing_start_revision_unique'::regclass)`). - Scan(&revisionIndex); err != nil { - t.Fatalf("read pairing reservation revision index: %v", err) - } - if !strings.Contains(strings.ToLower(expiryIndex), "(state, expires_at)") || - !strings.Contains(strings.ToLower(revisionIndex), "unique") || - !strings.Contains(strings.ToLower(revisionIndex), "(revision_id)") { - t.Fatalf("unexpected pairing reservation indexes expiry=%q revision=%q", expiryIndex, revisionIndex) + if attemptID != pairingID || state != "paired" || reservedRevisionID != revisionID || + !gotExpiresAt.Equal(expiresAt) || updatedAt.IsZero() { + t.Fatalf("unexpected pairing reservation attempt=%q state=%q revision=%q expires=%v updated=%v", + attemptID, state, reservedRevisionID, gotExpiresAt, updatedAt) } _, err := pool.Exec(ctx, `UPDATE gateway_identity_pairing_start_reservation SET state='starting'`) - requireIdentityPairingStartReservationMigrationCode(t, err, "23514", "starting reservation with revision") + requirePairingReservationMigrationCode(t, err, "23514", "starting reservation with revision") _, err = pool.Exec(ctx, `UPDATE gateway_identity_pairing_start_reservation SET revision_id=$1::uuid`, uuid.NewString()) - requireIdentityPairingStartReservationMigrationCode(t, err, "23503", "reservation with unknown revision") + requirePairingReservationMigrationCode(t, err, "23503", "reservation with unknown revision") } -func requireIdentityPairingStartReservationMigrationCode(t *testing.T, err error, wantCode, operation string) { +func requirePairingReservationMigrationCode(t *testing.T, err error, wantCode, operation string) { t.Helper() if err == nil { t.Fatalf("%s unexpectedly satisfied migration constraints", operation) diff --git a/apps/api/cmd/migrate/main.go b/apps/api/cmd/migrate/main.go index 1a4d4b9..fe5a9f8 100644 --- a/apps/api/cmd/migrate/main.go +++ b/apps/api/cmd/migrate/main.go @@ -24,6 +24,10 @@ func main() { os.Exit(1) } defer conn.Close(ctx) + if _, err := conn.Exec(ctx, "SET standard_conforming_strings = on"); err != nil { + logger.Error("enforce standard SQL string semantics failed", "error", err) + os.Exit(1) + } if _, err := conn.Exec(ctx, ` CREATE TABLE IF NOT EXISTS schema_migrations ( @@ -64,6 +68,14 @@ CREATE TABLE IF NOT EXISTS schema_migrations ( logger.Error("begin migration failed", "version", version, "error", err) os.Exit(1) } + // Pin string parsing semantics inside every migration transaction. A + // previous migration may have changed the session GUC, while each file is + // parsed and executed independently. + if _, err := tx.Exec(ctx, "SET LOCAL standard_conforming_strings = on"); err != nil { + _ = tx.Rollback(ctx) + logger.Error("enforce migration SQL string semantics failed", "version", version, "error", err) + os.Exit(1) + } if _, err := tx.Exec(ctx, string(sqlBytes)); err != nil { _ = tx.Rollback(ctx) logger.Error("execute migration failed", "version", version, "error", err) diff --git a/apps/api/cmd/migrate/main_test.go b/apps/api/cmd/migrate/main_test.go index 868f967..e886f51 100644 --- a/apps/api/cmd/migrate/main_test.go +++ b/apps/api/cmd/migrate/main_test.go @@ -14,42 +14,41 @@ import ( "github.com/jackc/pgx/v5/pgxpool" ) -func TestSecurityEventIdempotencyRepairMigrationExists(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0064_security_event_connection_idempotency_repair.sql") +func TestSecurityEventSchemaMigrationsDefineCurrentLifecycle(t *testing.T) { + streamPayload, err := os.ReadFile("../../migrations/0063_oidc_security_events.sql") if err != nil { - t.Fatalf("read repair migration: %v", err) + t.Fatalf("read security event stream migration: %v", err) } - sql := string(payload) + streamSQL := string(streamPayload) for _, statement := range []string{ - "CREATE TABLE IF NOT EXISTS gateway_security_event_connection_idempotency", - "CREATE INDEX IF NOT EXISTS idx_gateway_security_event_connection_idempotency_created", - } { - if !strings.Contains(sql, statement) { - t.Fatalf("repair migration is missing %q", statement) - } - } -} - -func TestSecurityEventVerificationStateRepairMigrationExists(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0065_security_event_verification_state_repair.sql") - if err != nil { - t.Fatalf("read verification state repair migration: %v", err) - } - sql := string(payload) - for _, statement := range []string{ - "ADD COLUMN IF NOT EXISTS stream_status", - "ADD COLUMN IF NOT EXISTS created_at", + "CREATE TABLE IF NOT EXISTS gateway_security_event_stream_state", "CREATE TABLE IF NOT EXISTS gateway_security_event_verification_challenges", "CREATE INDEX IF NOT EXISTS idx_gateway_security_event_challenges_expiry", } { - if !strings.Contains(sql, statement) { - t.Fatalf("verification state repair migration is missing %q", statement) + if !strings.Contains(streamSQL, statement) { + t.Fatalf("security event stream migration is missing %q", statement) + } + } + + connectionPayload, err := os.ReadFile("../../migrations/0064_security_event_connections.sql") + if err != nil { + t.Fatalf("read security event connection migration: %v", err) + } + connectionSQL := string(connectionPayload) + for _, statement := range []string{ + "CREATE TABLE IF NOT EXISTS gateway_security_event_connections", + "management_client_id text", + "management_credential_ref text", + "CREATE TABLE IF NOT EXISTS gateway_security_event_connection_idempotency", + } { + if !strings.Contains(connectionSQL, statement) { + t.Fatalf("security event connection migration is missing %q", statement) } } } func TestIdentityConfigurationRevisionMigrationDefinesSecretReferencesAndSingleActiveRevision(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0067_identity_configuration_revisions.sql") + payload, err := os.ReadFile("../../migrations/0065_identity_configuration_revisions.sql") if err != nil { t.Fatal(err) } @@ -58,6 +57,7 @@ func TestIdentityConfigurationRevisionMigrationDefinesSecretReferencesAndSingleA "CREATE TABLE IF NOT EXISTS gateway_identity_configuration_revisions", "machine_credential_ref text", "session_encryption_key_ref text", + "security_event_configuration_url text", "WHERE state = 'active'", "CHECK (state IN ('draft','validated','active','superseded','failed'))", } { @@ -73,7 +73,7 @@ func TestIdentityConfigurationRevisionMigrationDefinesSecretReferencesAndSingleA } func TestIdentityOnboardingExchangeMigrationStoresOnlySecretReferences(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0068_identity_onboarding_exchanges.sql") + payload, err := os.ReadFile("../../migrations/0066_identity_onboarding_exchanges.sql") if err != nil { t.Fatal(err) } @@ -81,7 +81,8 @@ func TestIdentityOnboardingExchangeMigrationStoresOnlySecretReferences(t *testin for _, required := range []string{ "create table if not exists gateway_identity_onboarding_exchanges", "exchange_token_ref text not null", - "security_event_configuration_url text", + "cleanup_status text not null default 'none'", + "security_event_credential_handoff_unsafe", } { if !strings.Contains(content, required) { t.Fatalf("identity onboarding migration is missing %q", required) @@ -94,8 +95,8 @@ func TestIdentityOnboardingExchangeMigrationStoresOnlySecretReferences(t *testin } } -func TestIdentityPairingCancellationMigrationSeparatesCleanupLifecycle(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0069_identity_pairing_cancellation.sql") +func TestIdentityOnboardingMigrationDefinesCancellationLifecycle(t *testing.T) { + payload, err := os.ReadFile("../../migrations/0066_identity_onboarding_exchanges.sql") if err != nil { t.Fatal(err) } @@ -106,9 +107,6 @@ func TestIdentityPairingCancellationMigrationSeparatesCleanupLifecycle(t *testin "cleanup_completed_at", "idx_gateway_identity_onboarding_cleanup", "last_error_category", - "set last_error_category = 'pairing_step_failed'", - "set local lock_timeout = '10s'", - "set local statement_timeout = '60s'", } { if !strings.Contains(content, required) { t.Fatalf("identity pairing cancellation migration is missing %q", required) @@ -121,14 +119,14 @@ func TestIdentityPairingCancellationMigrationSeparatesCleanupLifecycle(t *testin } } -func TestIdentityPairingErrorCategoryUpgradeMigrationExists(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0074_identity_pairing_error_categories.sql") +func TestIdentityOnboardingMigrationDefinesFinalErrorCategories(t *testing.T) { + payload, err := os.ReadFile("../../migrations/0066_identity_onboarding_exchanges.sql") if err != nil { t.Fatal(err) } content := strings.ToLower(string(payload)) for _, required := range []string{ - "drop constraint if exists gateway_identity_onboarding_error_category_check", + "gateway_identity_onboarding_error_category_check", "security_event_credential_handoff_unsafe", "security_event_connection_binding_missing", "security_event_connection_binding_unavailable", @@ -142,18 +140,14 @@ func TestIdentityPairingErrorCategoryUpgradeMigrationExists(t *testing.T) { } } -func TestIdentityPairingErrorCategoryUpgradeMigrationExecutesAgainstCurrentSchema(t *testing.T) { +func TestIdentityPairingErrorCategoriesExecuteAgainstCurrentSchema(t *testing.T) { pool := newIdentityMigrationPostgresTestSchema(t) ctx := context.Background() for _, migration := range []string{ - "../../migrations/0067_identity_configuration_revisions.sql", - "../../migrations/0068_identity_onboarding_exchanges.sql", - "../../migrations/0069_identity_pairing_cancellation.sql", - "../../migrations/0070_identity_secret_cleanup_queue.sql", - "../../migrations/0071_identity_pairing_start_reservation.sql", - "../../migrations/0072_identity_secret_cleanup_claim_lifecycle.sql", - "../../migrations/0073_identity_pairing_start_reservation_upgrade.sql", - "../../migrations/0074_identity_pairing_error_categories.sql", + "../../migrations/0065_identity_configuration_revisions.sql", + "../../migrations/0066_identity_onboarding_exchanges.sql", + "../../migrations/0067_identity_secret_cleanup_queue.sql", + "../../migrations/0068_identity_pairing_start_reservation.sql", } { applyIdentityMigrationTestFile(t, ctx, pool, migration) } @@ -193,7 +187,7 @@ SET last_error_category='credential_secret_leaked' WHERE id=$1::uuid`, pairingID } func TestIdentitySecretCleanupQueueMigrationStoresOnlyReferences(t *testing.T) { - payload, err := os.ReadFile("../../migrations/0070_identity_secret_cleanup_queue.sql") + payload, err := os.ReadFile("../../migrations/0067_identity_secret_cleanup_queue.sql") if err != nil { t.Fatal(err) } @@ -219,11 +213,11 @@ func TestIdentitySecretCleanupQueueMigrationStoresOnlyReferences(t *testing.T) { } } -func TestIdentityPairingCancellationMigrationExecutesAgainstLegacyData(t *testing.T) { +func TestIdentityPairingCancellationLifecycleRejectsPartialStates(t *testing.T) { pool := newIdentityMigrationPostgresTestSchema(t) ctx := context.Background() - applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0067_identity_configuration_revisions.sql") - applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0068_identity_onboarding_exchanges.sql") + applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0065_identity_configuration_revisions.sql") + applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0066_identity_onboarding_exchanges.sql") revisionID, pairingID := uuid.NewString(), uuid.NewString() if _, err := pool.Exec(ctx, ` @@ -236,13 +230,11 @@ INSERT INTO gateway_identity_configuration_revisions ( if _, err := pool.Exec(ctx, ` INSERT INTO gateway_identity_onboarding_exchanges ( id,revision_id,remote_exchange_id,exchange_token_ref,status,remote_version,expires_at,last_error_category -) VALUES ($1::uuid,$2::uuid,$3::uuid,$4,'credentials_saved',4,now() + interval '30 minutes','secret_token_abcdef')`, +) VALUES ($1::uuid,$2::uuid,$3::uuid,$4,'credentials_saved',4,now() + interval '30 minutes','pairing_step_failed')`, pairingID, revisionID, uuid.NewString(), "identity-exchange-"+pairingID); err != nil { t.Fatalf("seed legacy onboarding exchange: %v", err) } - applyIdentityMigrationTestFile(t, ctx, pool, "../../migrations/0069_identity_pairing_cancellation.sql") - var status, cleanupStatus, errorCategory string var cancelledAt, cleanupCompletedAt *time.Time if err := pool.QueryRow(ctx, ` diff --git a/apps/api/docs/embed.go b/apps/api/docs/embed.go new file mode 100644 index 0000000..1de7ee1 --- /dev/null +++ b/apps/api/docs/embed.go @@ -0,0 +1,9 @@ +package docs + +import _ "embed" + +//go:embed swagger.json +var SwaggerJSON []byte + +//go:embed swagger.yaml +var SwaggerYAML []byte diff --git a/apps/api/docs/swagger.json b/apps/api/docs/swagger.json index 11d7cd0..0c4f779 100644 --- a/apps/api/docs/swagger.json +++ b/apps/api/docs/swagger.json @@ -12,6 +12,47 @@ }, "basePath": "/", "paths": { + "/api-docs-json": { + "get": { + "description": "返回当前构建内嵌的完整机器可读 Swagger JSON，供 Agent 在 SKILL references 未覆盖接口时查询。", + "produces": [ + "application/json" + ], + "tags": [ + "agent-resources" + ], + "summary": "获取 AI Gateway Swagger JSON", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + } + }, + "/api-docs-yaml": { + "get": { + "description": "返回当前构建内嵌的完整机器可读 Swagger YAML。", + "produces": [ + "application/yaml" + ], + "tags": [ + "agent-resources" + ], + "summary": "获取 AI Gateway Swagger YAML", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "string" + } + } + } + } + }, "/api/admin/access-rules": { "get": { "security": [ @@ -5218,7 +5259,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/httpapi.TaskRequest" + "$ref": "#/definitions/httpapi.ChatCompletionRequest" } } ], @@ -6078,6 +6119,58 @@ } } }, + "/api/v1/public/skills/ai-gateway-ops-management/download": { + "get": { + "description": "下载可交给 Agent 使用的 ai-gateway-ops-management ZIP 包。", + "produces": [ + "application/zip" + ], + "tags": [ + "agent-resources" + ], + "summary": "下载 AI Gateway 运维管理 SKILL", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "file" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httpapi.ErrorEnvelope" + } + } + } + } + }, + "/api/v1/public/skills/ai-gateway-ops-management/metadata": { + "get": { + "description": "返回公开运维管理 SKILL 的名称、版本、模块、下载文件名和机器可读接口文档路径。", + "produces": [ + "application/json" + ], + "tags": [ + "agent-resources" + ], + "summary": "获取 AI Gateway 运维管理 SKILL 元数据", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.SkillBundleMetadataResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/httpapi.ErrorEnvelope" + } + } + } + } + }, "/api/v1/reranks": { "post": { "security": [ @@ -6178,31 +6271,26 @@ "BearerAuth": [] } ], - "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。", + "description": "公开 OpenAI-compatible Responses 入口。模型声明 openai_responses 时原生转发，否则使用 Chat Completions 转换；store 缺省为 true。previous_response_id 严格绑定首次成功的平台模型和上游协议，链路不可用时不跨平台续接。未提供 previous_response_id 时由调用方管理完整状态，Gateway 以本轮 input/messages 为准且不追加本地历史。", "consumes": [ "application/json" ], "produces": [ - "application/json" + "application/json", + "text/event-stream" ], "tags": [ - "tasks" + "responses" ], - "summary": "创建或执行 AI 任务", + "summary": "创建 OpenAI Responses", "parameters": [ { - "type": "boolean", - "description": "true 时异步创建任务并返回 202", - "name": "X-Async", - "in": "header" - }, - { - "description": "AI 任务请求，字段随任务类型变化", + "description": "Responses 请求；Chat 回退只支持自定义 function tools", "name": "input", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/httpapi.TaskRequest" + "$ref": "#/definitions/httpapi.ResponsesRequest" } } ], @@ -6210,17 +6298,17 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/httpapi.CompatibleResponse" - } - }, - "202": { - "description": "Accepted", - "schema": { - "$ref": "#/definitions/httpapi.TaskAcceptedResponse" + "$ref": "#/definitions/httpapi.ResponsesCompatibleResponse" + }, + "headers": { + "X-Gateway-Task-Id": { + "type": "string", + "description": "网关审计任务 ID" + } } }, "400": { - "description": "Bad Request", + "description": "invalid_previous_response_id / unsupported_response_tool / unsupported_response_parameter", "schema": { "$ref": "#/definitions/httpapi.ErrorEnvelope" } @@ -6243,20 +6331,8 @@ "$ref": "#/definitions/httpapi.ErrorEnvelope" } }, - "404": { - "description": "Not Found", - "schema": { - "$ref": "#/definitions/httpapi.ErrorEnvelope" - } - }, - "429": { - "description": "Too Many Requests", - "schema": { - "$ref": "#/definitions/httpapi.ErrorEnvelope" - } - }, - "502": { - "description": "Bad Gateway", + "503": { + "description": "response_chain_unavailable", "schema": { "$ref": "#/definitions/httpapi.ErrorEnvelope" } @@ -7677,31 +7753,26 @@ "BearerAuth": [] } ], - "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。", + "description": "OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 400 invalid_parameter。", "consumes": [ "application/json" ], "produces": [ - "application/json" + "application/json", + "text/event-stream" ], "tags": [ - "tasks" + "chat" ], - "summary": "创建或执行 AI 任务", + "summary": "创建 OpenAI Chat Completions", "parameters": [ { - "type": "boolean", - "description": "true 时异步创建任务并返回 202", - "name": "X-Async", - "in": "header" - }, - { - "description": "AI 任务请求，字段随任务类型变化", + "description": "Chat Completions 请求", "name": "input", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/httpapi.TaskRequest" + "$ref": "#/definitions/httpapi.ChatCompletionRequest" } } ], @@ -7709,17 +7780,11 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/httpapi.CompatibleResponse" - } - }, - "202": { - "description": "Accepted", - "schema": { - "$ref": "#/definitions/httpapi.TaskAcceptedResponse" + "$ref": "#/definitions/httpapi.ChatCompletionCompatibleResponse" } }, "400": { - "description": "Bad Request", + "description": "invalid_parameter", "schema": { "$ref": "#/definitions/httpapi.ErrorEnvelope" } @@ -7742,12 +7807,6 @@ "$ref": "#/definitions/httpapi.ErrorEnvelope" } }, - "404": { - "description": "Not Found", - "schema": { - "$ref": "#/definitions/httpapi.ErrorEnvelope" - } - }, "429": { "description": "Too Many Requests", "schema": { @@ -8959,31 +9018,26 @@ "BearerAuth": [] } ], - "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。", + "description": "OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 400 invalid_parameter。", "consumes": [ "application/json" ], "produces": [ - "application/json" + "application/json", + "text/event-stream" ], "tags": [ - "tasks" + "chat" ], - "summary": "创建或执行 AI 任务", + "summary": "创建 OpenAI Chat Completions", "parameters": [ { - "type": "boolean", - "description": "true 时异步创建任务并返回 202", - "name": "X-Async", - "in": "header" - }, - { - "description": "AI 任务请求，字段随任务类型变化", + "description": "Chat Completions 请求", "name": "input", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/httpapi.TaskRequest" + "$ref": "#/definitions/httpapi.ChatCompletionRequest" } } ], @@ -8991,17 +9045,11 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/httpapi.CompatibleResponse" - } - }, - "202": { - "description": "Accepted", - "schema": { - "$ref": "#/definitions/httpapi.TaskAcceptedResponse" + "$ref": "#/definitions/httpapi.ChatCompletionCompatibleResponse" } }, "400": { - "description": "Bad Request", + "description": "invalid_parameter", "schema": { "$ref": "#/definitions/httpapi.ErrorEnvelope" } @@ -9024,12 +9072,6 @@ "$ref": "#/definitions/httpapi.ErrorEnvelope" } }, - "404": { - "description": "Not Found", - "schema": { - "$ref": "#/definitions/httpapi.ErrorEnvelope" - } - }, "429": { "description": "Too Many Requests", "schema": { @@ -10491,6 +10533,158 @@ } } }, + "httpapi.ChatCompletionRequest": { + "type": "object", + "properties": { + "audio": { + "type": "object", + "additionalProperties": true + }, + "frequency_penalty": { + "type": "number", + "example": 0 + }, + "function_call": {}, + "functions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "logit_bias": { + "type": "object", + "additionalProperties": true + }, + "logprobs": { + "type": "boolean" + }, + "max_completion_tokens": { + "type": "integer", + "example": 512 + }, + "max_tokens": { + "type": "integer", + "example": 512 + }, + "messages": { + "type": "array", + "items": { + "$ref": "#/definitions/httpapi.ChatMessage" + } + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "modalities": { + "type": "array", + "items": { + "type": "string" + } + }, + "model": { + "type": "string", + "example": "gpt-4o-mini" + }, + "moderation": {}, + "n": { + "type": "integer", + "example": 1 + }, + "parallel_tool_calls": { + "type": "boolean" + }, + "prediction": {}, + "presence_penalty": { + "type": "number", + "example": 0 + }, + "prompt_cache_key": { + "type": "string" + }, + "prompt_cache_options": { + "type": "object", + "additionalProperties": true + }, + "prompt_cache_retention": { + "type": "string", + "enum": [ + "in_memory", + "24h" + ] + }, + "reasoning_effort": { + "description": "ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。", + "type": "string", + "enum": [ + "none", + "minimal", + "low", + "medium", + "high", + "xhigh", + "max" + ], + "example": "medium" + }, + "response_format": {}, + "runMode": { + "type": "string", + "example": "simulation" + }, + "safety_identifier": { + "type": "string" + }, + "seed": { + "type": "integer" + }, + "service_tier": { + "type": "string" + }, + "stop": {}, + "store": { + "type": "boolean" + }, + "stream": { + "type": "boolean", + "example": false + }, + "stream_options": { + "type": "object", + "additionalProperties": true + }, + "temperature": { + "type": "number", + "example": 0.7 + }, + "tool_choice": {}, + "tools": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "top_logprobs": { + "type": "integer" + }, + "top_p": { + "type": "number", + "example": 1 + }, + "user": { + "type": "string" + }, + "verbosity": { + "type": "string" + }, + "web_search_options": { + "type": "object", + "additionalProperties": true + } + } + }, "httpapi.ChatCompletionUsage": { "type": "object", "properties": { @@ -10526,14 +10720,19 @@ "httpapi.ChatMessage": { "type": "object", "properties": { - "content": { - "type": "string", - "example": "Hello" + "content": {}, + "function_call": {}, + "name": { + "type": "string" }, "role": { "type": "string", "example": "user" - } + }, + "tool_call_id": { + "type": "string" + }, + "tool_calls": {} } }, "httpapi.ChatPromptTokensDetails": { @@ -10592,9 +10791,14 @@ "type": "string", "example": "invalid json body" }, + "param": {}, "status": { "type": "integer", "example": 400 + }, + "type": { + "type": "string", + "example": "invalid_request_error" } } }, @@ -11136,6 +11340,23 @@ "httpapi.ResponsesRequest": { "type": "object", "properties": { + "background": { + "type": "boolean" + }, + "context_management": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "conversation": {}, + "include": { + "type": "array", + "items": { + "type": "string" + } + }, "input": {}, "instructions": { "type": "string", @@ -11145,10 +11366,18 @@ "type": "integer", "example": 512 }, + "max_tool_calls": { + "type": "integer" + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, "model": { "type": "string", "example": "Doubao Seed 2.0 Pro" }, + "moderation": {}, "parallel_tool_calls": { "type": "boolean", "example": true @@ -11157,10 +11386,31 @@ "type": "string", "example": "resp_0123456789abcdef0123456789abcdef" }, + "prompt": {}, + "prompt_cache_key": { + "type": "string" + }, + "prompt_cache_options": { + "type": "object", + "additionalProperties": true + }, + "prompt_cache_retention": { + "type": "string", + "enum": [ + "in_memory", + "24h" + ] + }, "reasoning": { "type": "object", "additionalProperties": true }, + "safety_identifier": { + "type": "string" + }, + "service_tier": { + "type": "string" + }, "store": { "type": "boolean" }, @@ -11168,6 +11418,10 @@ "type": "boolean", "example": false }, + "stream_options": { + "type": "object", + "additionalProperties": true + }, "temperature": { "type": "number", "example": 0.7 @@ -11184,9 +11438,18 @@ "additionalProperties": true } }, + "top_logprobs": { + "type": "integer" + }, "top_p": { "type": "number", "example": 1 + }, + "truncation": { + "type": "string" + }, + "user": { + "type": "string" } } }, @@ -11201,6 +11464,48 @@ } } }, + "httpapi.SkillBundleMetadataResponse": { + "type": "object", + "properties": { + "apiDocsJsonPath": { + "type": "string", + "example": "/api-docs-json" + }, + "apiDocsYamlPath": { + "type": "string", + "example": "/api-docs-yaml" + }, + "displayName": { + "type": "string", + "example": "AI Gateway 运维管理" + }, + "downloadPath": { + "type": "string", + "example": "/api/v1/public/skills/ai-gateway-ops-management/download" + }, + "fileName": { + "type": "string", + "example": "ai-gateway-ops-management-v1.0.2.zip" + }, + "modules": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "model-runtime" + ] + }, + "name": { + "type": "string", + "example": "ai-gateway-ops-management" + }, + "version": { + "type": "string", + "example": "1.0.2" + } + } + }, "httpapi.TaskAcceptedResponse": { "type": "object", "properties": { @@ -11307,14 +11612,20 @@ "type": "string", "example": "happy" }, - "input": { - "type": "string", - "example": "Tell me a short story" - }, + "input": {}, "makeInstrumental": { "type": "boolean", "example": false }, + "max_completion_tokens": { + "description": "MaxCompletionTokens includes visible output and reasoning tokens.", + "type": "integer", + "example": 512 + }, + "max_output_tokens": { + "type": "integer", + "example": 512 + }, "max_tokens": { "type": "integer", "example": 512 @@ -11342,8 +11653,17 @@ "example": "A watercolor robot reading a book" }, "reasoning_effort": { - "description": "ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。", + "description": "ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。", "type": "string", + "enum": [ + "none", + "minimal", + "low", + "medium", + "high", + "xhigh", + "max" + ], "example": "medium" }, "resolution": { diff --git a/apps/api/docs/swagger.yaml b/apps/api/docs/swagger.yaml index 9f47de3..93e7f6f 100644 --- a/apps/api/docs/swagger.yaml +++ b/apps/api/docs/swagger.yaml @@ -133,6 +133,118 @@ definitions: usage: $ref: '#/definitions/httpapi.ChatCompletionUsage' type: object + httpapi.ChatCompletionRequest: + properties: + audio: + additionalProperties: true + type: object + frequency_penalty: + example: 0 + type: number + function_call: {} + functions: + items: + additionalProperties: true + type: object + type: array + logit_bias: + additionalProperties: true + type: object + logprobs: + type: boolean + max_completion_tokens: + example: 512 + type: integer + max_tokens: + example: 512 + type: integer + messages: + items: + $ref: '#/definitions/httpapi.ChatMessage' + type: array + metadata: + additionalProperties: true + type: object + modalities: + items: + type: string + type: array + model: + example: gpt-4o-mini + type: string + moderation: {} + "n": + example: 1 + type: integer + parallel_tool_calls: + type: boolean + prediction: {} + presence_penalty: + example: 0 + type: number + prompt_cache_key: + type: string + prompt_cache_options: + additionalProperties: true + type: object + prompt_cache_retention: + enum: + - in_memory + - 24h + type: string + reasoning_effort: + description: ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。 + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max + example: medium + type: string + response_format: {} + runMode: + example: simulation + type: string + safety_identifier: + type: string + seed: + type: integer + service_tier: + type: string + stop: {} + store: + type: boolean + stream: + example: false + type: boolean + stream_options: + additionalProperties: true + type: object + temperature: + example: 0.7 + type: number + tool_choice: {} + tools: + items: + additionalProperties: true + type: object + type: array + top_logprobs: + type: integer + top_p: + example: 1 + type: number + user: + type: string + verbosity: + type: string + web_search_options: + additionalProperties: true + type: object + type: object httpapi.ChatCompletionUsage: properties: completion_tokens: @@ -157,12 +269,16 @@ definitions: type: object httpapi.ChatMessage: properties: - content: - example: Hello + content: {} + function_call: {} + name: type: string role: example: user type: string + tool_call_id: + type: string + tool_calls: {} type: object httpapi.ChatPromptTokensDetails: properties: @@ -203,9 +319,13 @@ definitions: message: example: invalid json body type: string + param: {} status: example: 400 type: integer + type: + example: invalid_request_error + type: string type: object httpapi.FileStorageChannelListResponse: properties: @@ -567,6 +687,18 @@ definitions: type: object httpapi.ResponsesRequest: properties: + background: + type: boolean + context_management: + items: + additionalProperties: true + type: object + type: array + conversation: {} + include: + items: + type: string + type: array input: {} instructions: example: Answer concisely @@ -574,23 +706,47 @@ definitions: max_output_tokens: example: 512 type: integer + max_tool_calls: + type: integer + metadata: + additionalProperties: true + type: object model: example: Doubao Seed 2.0 Pro type: string + moderation: {} parallel_tool_calls: example: true type: boolean previous_response_id: example: resp_0123456789abcdef0123456789abcdef type: string + prompt: {} + prompt_cache_key: + type: string + prompt_cache_options: + additionalProperties: true + type: object + prompt_cache_retention: + enum: + - in_memory + - 24h + type: string reasoning: additionalProperties: true type: object + safety_identifier: + type: string + service_tier: + type: string store: type: boolean stream: example: false type: boolean + stream_options: + additionalProperties: true + type: object temperature: example: 0.7 type: number @@ -603,9 +759,15 @@ definitions: additionalProperties: true type: object type: array + top_logprobs: + type: integer top_p: example: 1 type: number + truncation: + type: string + user: + type: string type: object httpapi.RuntimePolicySetListResponse: properties: @@ -614,6 +776,36 @@ definitions: $ref: '#/definitions/store.RuntimePolicySet' type: array type: object + httpapi.SkillBundleMetadataResponse: + properties: + apiDocsJsonPath: + example: /api-docs-json + type: string + apiDocsYamlPath: + example: /api-docs-yaml + type: string + displayName: + example: AI Gateway 运维管理 + type: string + downloadPath: + example: /api/v1/public/skills/ai-gateway-ops-management/download + type: string + fileName: + example: ai-gateway-ops-management-v1.0.2.zip + type: string + modules: + example: + - model-runtime + items: + type: string + type: array + name: + example: ai-gateway-ops-management + type: string + version: + example: 1.0.2 + type: string + type: object httpapi.TaskAcceptedResponse: properties: next: @@ -688,12 +880,17 @@ definitions: emotion: example: happy type: string - input: - example: Tell me a short story - type: string + input: {} makeInstrumental: example: false type: boolean + max_completion_tokens: + description: MaxCompletionTokens includes visible output and reasoning tokens. + example: 512 + type: integer + max_output_tokens: + example: 512 + type: integer max_tokens: example: 512 type: integer @@ -714,7 +911,15 @@ definitions: example: A watercolor robot reading a book type: string reasoning_effort: - description: ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。 + description: ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。 + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max example: medium type: string resolution: @@ -2778,6 +2983,33 @@ info: title: EasyAI AI Gateway API version: 0.1.0 paths: + /api-docs-json: + get: + description: 返回当前构建内嵌的完整机器可读 Swagger JSON，供 Agent 在 SKILL references 未覆盖接口时查询。 + produces: + - application/json + responses: + "200": + description: OK + schema: + additionalProperties: true + type: object + summary: 获取 AI Gateway Swagger JSON + tags: + - agent-resources + /api-docs-yaml: + get: + description: 返回当前构建内嵌的完整机器可读 Swagger YAML。 + produces: + - application/yaml + responses: + "200": + description: OK + schema: + type: string + summary: 获取 AI Gateway Swagger YAML + tags: + - agent-resources /api/admin/access-rules: get: description: 管理端返回用户组、租户、用户或 API Key 到平台、平台模型、基础模型的访问规则。 @@ -6117,7 +6349,7 @@ paths: name: input required: true schema: - $ref: '#/definitions/httpapi.TaskRequest' + $ref: '#/definitions/httpapi.ChatCompletionRequest' produces: - application/json - text/event-stream @@ -6678,6 +6910,40 @@ paths: summary: 获取公开统一认证状态 tags: - identity + /api/v1/public/skills/ai-gateway-ops-management/download: + get: + description: 下载可交给 Agent 使用的 ai-gateway-ops-management ZIP 包。 + produces: + - application/zip + responses: + "200": + description: OK + schema: + type: file + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httpapi.ErrorEnvelope' + summary: 下载 AI Gateway 运维管理 SKILL + tags: + - agent-resources + /api/v1/public/skills/ai-gateway-ops-management/metadata: + get: + description: 返回公开运维管理 SKILL 的名称、版本、模块、下载文件名和机器可读接口文档路径。 + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/httpapi.SkillBundleMetadataResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/httpapi.ErrorEnvelope' + summary: 获取 AI Gateway 运维管理 SKILL 元数据 + tags: + - agent-resources /api/v1/reranks: post: consumes: @@ -6743,32 +7009,31 @@ paths: post: consumes: - application/json - description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible - 路径同步返回兼容响应或 SSE 流。 + description: 公开 OpenAI-compatible Responses 入口。模型声明 openai_responses 时原生转发，否则使用 + Chat Completions 转换；store 缺省为 true。previous_response_id 严格绑定首次成功的平台模型和上游协议，链路不可用时不跨平台续接。未提供 + previous_response_id 时由调用方管理完整状态，Gateway 以本轮 input/messages 为准且不追加本地历史。 parameters: - - description: true 时异步创建任务并返回 202 - in: header - name: X-Async - type: boolean - - description: AI 任务请求，字段随任务类型变化 + - description: Responses 请求；Chat 回退只支持自定义 function tools in: body name: input required: true schema: - $ref: '#/definitions/httpapi.TaskRequest' + $ref: '#/definitions/httpapi.ResponsesRequest' produces: - application/json + - text/event-stream responses: "200": description: OK + headers: + X-Gateway-Task-Id: + description: 网关审计任务 ID + type: string schema: - $ref: '#/definitions/httpapi.CompatibleResponse' - "202": - description: Accepted - schema: - $ref: '#/definitions/httpapi.TaskAcceptedResponse' + $ref: '#/definitions/httpapi.ResponsesCompatibleResponse' "400": - description: Bad Request + description: invalid_previous_response_id / unsupported_response_tool / + unsupported_response_parameter schema: $ref: '#/definitions/httpapi.ErrorEnvelope' "401": @@ -6783,23 +7048,15 @@ paths: description: Forbidden schema: $ref: '#/definitions/httpapi.ErrorEnvelope' - "404": - description: Not Found - schema: - $ref: '#/definitions/httpapi.ErrorEnvelope' - "429": - description: Too Many Requests - schema: - $ref: '#/definitions/httpapi.ErrorEnvelope' - "502": - description: Bad Gateway + "503": + description: response_chain_unavailable schema: $ref: '#/definitions/httpapi.ErrorEnvelope' security: - BearerAuth: [] - summary: 创建或执行 AI 任务 + summary: 创建 OpenAI Responses tags: - - tasks + - responses /api/v1/security-events/ssf: post: consumes: @@ -7714,32 +7971,25 @@ paths: post: consumes: - application/json - description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible - 路径同步返回兼容响应或 SSE 流。 + description: OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 + 400 invalid_parameter。 parameters: - - description: true 时异步创建任务并返回 202 - in: header - name: X-Async - type: boolean - - description: AI 任务请求，字段随任务类型变化 + - description: Chat Completions 请求 in: body name: input required: true schema: - $ref: '#/definitions/httpapi.TaskRequest' + $ref: '#/definitions/httpapi.ChatCompletionRequest' produces: - application/json + - text/event-stream responses: "200": description: OK schema: - $ref: '#/definitions/httpapi.CompatibleResponse' - "202": - description: Accepted - schema: - $ref: '#/definitions/httpapi.TaskAcceptedResponse' + $ref: '#/definitions/httpapi.ChatCompletionCompatibleResponse' "400": - description: Bad Request + description: invalid_parameter schema: $ref: '#/definitions/httpapi.ErrorEnvelope' "401": @@ -7754,10 +8004,6 @@ paths: description: Forbidden schema: $ref: '#/definitions/httpapi.ErrorEnvelope' - "404": - description: Not Found - schema: - $ref: '#/definitions/httpapi.ErrorEnvelope' "429": description: Too Many Requests schema: @@ -7768,9 +8014,9 @@ paths: $ref: '#/definitions/httpapi.ErrorEnvelope' security: - BearerAuth: [] - summary: 创建或执行 AI 任务 + summary: 创建 OpenAI Chat Completions tags: - - tasks + - chat /embeddings: post: consumes: @@ -8553,32 +8799,25 @@ paths: post: consumes: - application/json - description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible - 路径同步返回兼容响应或 SSE 流。 + description: OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 + 400 invalid_parameter。 parameters: - - description: true 时异步创建任务并返回 202 - in: header - name: X-Async - type: boolean - - description: AI 任务请求，字段随任务类型变化 + - description: Chat Completions 请求 in: body name: input required: true schema: - $ref: '#/definitions/httpapi.TaskRequest' + $ref: '#/definitions/httpapi.ChatCompletionRequest' produces: - application/json + - text/event-stream responses: "200": description: OK schema: - $ref: '#/definitions/httpapi.CompatibleResponse' - "202": - description: Accepted - schema: - $ref: '#/definitions/httpapi.TaskAcceptedResponse' + $ref: '#/definitions/httpapi.ChatCompletionCompatibleResponse' "400": - description: Bad Request + description: invalid_parameter schema: $ref: '#/definitions/httpapi.ErrorEnvelope' "401": @@ -8593,10 +8832,6 @@ paths: description: Forbidden schema: $ref: '#/definitions/httpapi.ErrorEnvelope' - "404": - description: Not Found - schema: - $ref: '#/definitions/httpapi.ErrorEnvelope' "429": description: Too Many Requests schema: @@ -8607,9 +8842,9 @@ paths: $ref: '#/definitions/httpapi.ErrorEnvelope' security: - BearerAuth: [] - summary: 创建或执行 AI 任务 + summary: 创建 OpenAI Chat Completions tags: - - tasks + - chat /v1/embeddings: post: consumes: diff --git a/apps/api/go.mod b/apps/api/go.mod index df5bee9..c7a95f7 100644 --- a/apps/api/go.mod +++ b/apps/api/go.mod @@ -14,7 +14,7 @@ require ( github.com/riverqueue/river v0.24.0 github.com/riverqueue/river/riverdriver/riverpgxv5 v0.24.0 github.com/riverqueue/river/rivertype v0.24.0 - golang.org/x/crypto v0.37.0 + golang.org/x/crypto v0.52.0 golang.org/x/oauth2 v0.36.0 ) @@ -37,6 +37,6 @@ require ( github.com/tidwall/sjson v1.2.5 // indirect go.uber.org/goleak v1.3.0 // indirect golang.org/x/sync v0.20.0 // indirect - golang.org/x/text v0.36.0 // indirect + golang.org/x/text v0.37.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/apps/api/go.sum b/apps/api/go.sum index 792b0e9..006bff2 100644 --- a/apps/api/go.sum +++ b/apps/api/go.sum @@ -69,14 +69,14 @@ github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY= github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28= go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= -golang.org/x/crypto v0.37.0 h1:kJNSjF/Xp7kU0iB2Z+9viTPMW4EqqsrywMXLJOOsXSE= -golang.org/x/crypto v0.37.0/go.mod h1:vg+k43peMZ0pUMhYmVAWysMK35e6ioLh3wB8ZCAfbVc= +golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988= +golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc= golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs= golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q= golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4= golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= -golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg= -golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164= +golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc= +golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= diff --git a/apps/api/internal/clients/chat_reasoning.go b/apps/api/internal/clients/chat_reasoning.go index abb2b53..5bb21bc 100644 --- a/apps/api/internal/clients/chat_reasoning.go +++ b/apps/api/internal/clients/chat_reasoning.go @@ -9,7 +9,7 @@ import ( "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" ) -const OpenAIReasoningEffortValidationMessage = "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh" +const OpenAIReasoningEffortValidationMessage = "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh, max" var ( openAIReasoningEfforts = map[string]struct{}{ @@ -19,6 +19,7 @@ var ( "medium": {}, "high": {}, "xhigh": {}, + "max": {}, } volcesChatReasoningEfforts = map[string]struct{}{ "minimal": {}, @@ -212,13 +213,16 @@ func isZhipuReasoningEffortModel(model string) bool { } func highMaxReasoningEffort(effort string) string { - if effort == "xhigh" { + if effort == "xhigh" || effort == "max" { return "max" } return "high" } func zhipuReasoningEffort(effort string) string { + if effort == "max" { + return "xhigh" + } if _, ok := zhipuReasoningEfforts[effort]; ok { return effort } @@ -229,7 +233,7 @@ func volcesChatReasoningEffort(effort string) string { switch effort { case "none": return "minimal" - case "xhigh": + case "xhigh", "max": return "high" default: if _, ok := volcesChatReasoningEfforts[effort]; ok { diff --git a/apps/api/internal/clients/chat_reasoning_max_test.go b/apps/api/internal/clients/chat_reasoning_max_test.go new file mode 100644 index 0000000..efd569d --- /dev/null +++ b/apps/api/internal/clients/chat_reasoning_max_test.go @@ -0,0 +1,29 @@ +package clients + +import ( + "testing" + + "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" +) + +func TestCurrentOpenAIReasoningEffortMaxProviderMapping(t *testing.T) { + tests := []struct { + name string + candidate store.RuntimeModelCandidate + expected string + }{ + {name: "generic", candidate: store.RuntimeModelCandidate{Provider: "openai"}, expected: "max"}, + {name: "deepseek", candidate: store.RuntimeModelCandidate{Provider: "deepseek-openai"}, expected: "max"}, + {name: "zhipu", candidate: store.RuntimeModelCandidate{Provider: "zhipu-openai", ProviderModelName: "glm-5.2"}, expected: "xhigh"}, + {name: "volces", candidate: store.RuntimeModelCandidate{Provider: "volces-openai", ProviderModelName: "doubao-seed-2-0-pro-260215"}, expected: "high"}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + body := map[string]any{"model": test.candidate.ProviderModelName, "reasoning_effort": "max"} + applyOpenAIChatReasoningParams(body, test.candidate) + if body["reasoning_effort"] != test.expected { + t.Fatalf("expected reasoning_effort %q, got %#v", test.expected, body["reasoning_effort"]) + } + }) + } +} diff --git a/apps/api/internal/clients/clients_test.go b/apps/api/internal/clients/clients_test.go index dbd0d9f..0a4421e 100644 --- a/apps/api/internal/clients/clients_test.go +++ b/apps/api/internal/clients/clients_test.go @@ -2294,6 +2294,256 @@ func TestKelingClientVideoSubmitsAndPollsImageTask(t *testing.T) { } } +func TestKelingClient30TurboUsesModelEndpointAndTasksAPI(t *testing.T) { + var submitPath string + var pollPath string + var pollQuery string + var gotAuth string + var submittedPayload map[string]any + var submittedTaskPayload map[string]any + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotAuth = r.Header.Get("Authorization") + switch r.Method + " " + r.URL.Path { + case "POST /text-to-video/kling-3.0-turbo": + submitPath = r.URL.Path + if err := json.NewDecoder(r.Body).Decode(&submittedPayload); err != nil { + t.Fatalf("decode keling 3.0 turbo submit: %v", err) + } + _ = json.NewEncoder(w).Encode(map[string]any{ + "code": 0, + "request_id": "req-turbo-submit", + "data": map[string]any{ + "id": "turbo-task-1", + "status": "submitted", + }, + }) + case "GET /tasks": + pollPath = r.URL.Path + pollQuery = r.URL.RawQuery + _ = json.NewEncoder(w).Encode(map[string]any{ + "code": 0, + "request_id": "req-turbo-poll", + "data": []any{ + map[string]any{ + "id": "turbo-task-1", + "status": "succeeded", + "create_time": 789, + "outputs": []any{ + map[string]any{ + "type": "video", + "url": "https://example.com/turbo.mp4", + "watermark_url": "https://example.com/turbo-watermark.mp4", + "duration": "8", + }, + }, + }, + }, + }) + default: + t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path) + } + })) + defer server.Close() + + response, err := (KelingClient{HTTPClient: server.Client()}).Run(context.Background(), Request{ + Kind: "videos.generations", + ModelType: "video_generate", + Model: "可灵3.0 Turbo", + Body: map[string]any{ + "prompt": "A cinematic city reveal", + "duration": 8, + "resolution": "1080p", + "aspect_ratio": "9:16", + "callback_url": "https://example.com/callback", + "external_task_id": "external-1", + }, + Candidate: store.RuntimeModelCandidate{ + BaseURL: server.URL + "/v1", + Provider: "keling", + AuthType: "APIKey", + ModelName: "可灵3.0 Turbo", + ProviderModelName: "kling-3.0-turbo", + Credentials: map[string]any{"apiKey": "kling-api-key"}, + PlatformConfig: map[string]any{ + "kelingPollIntervalMs": 100, + "kelingPollTimeoutSeconds": 1, + }, + }, + OnRemoteTaskSubmitted: func(remoteTaskID string, payload map[string]any) error { + if remoteTaskID != "turbo-task-1" { + t.Fatalf("unexpected remote task id: %s", remoteTaskID) + } + submittedTaskPayload = payload + return nil + }, + }) + if err != nil { + t.Fatalf("run keling 3.0 turbo video: %v", err) + } + if submitPath != "/text-to-video/kling-3.0-turbo" || + pollPath != "/tasks" || + pollQuery != "task_ids=turbo-task-1" || + gotAuth != "Bearer kling-api-key" { + t.Fatalf("unexpected keling 3.0 turbo paths/auth submit=%s poll=%s?%s auth=%s", submitPath, pollPath, pollQuery, gotAuth) + } + if submittedTaskPayload["endpoint"] != "/text-to-video/kling-3.0-turbo" || + submittedTaskPayload["taskApi"] != "keling_tasks_v2" { + t.Fatalf("unexpected submitted task payload: %+v", submittedTaskPayload) + } + settings, _ := submittedPayload["settings"].(map[string]any) + options, _ := submittedPayload["options"].(map[string]any) + if submittedPayload["prompt"] != "A cinematic city reveal" || + numericValue(settings["duration"], 0) != 8 || + settings["resolution"] != "1080p" || + settings["aspect_ratio"] != "9:16" || + options["callback_url"] != "https://example.com/callback" || + options["external_task_id"] != "external-1" { + t.Fatalf("unexpected keling 3.0 turbo payload: %+v", submittedPayload) + } + data, _ := response.Result["data"].([]any) + item, _ := data[0].(map[string]any) + if response.Result["upstream_task_id"] != "turbo-task-1" || + item["url"] != "https://example.com/turbo.mp4" || + item["watermark_url"] != "https://example.com/turbo-watermark.mp4" { + t.Fatalf("unexpected keling 3.0 turbo response: %+v", response.Result) + } +} + +func TestKelingClient30TurboRejectsLegacyCredentials(t *testing.T) { + _, err := (KelingClient{}).Run(context.Background(), Request{ + Kind: "videos.generations", + Body: map[string]any{"prompt": "A cinematic city reveal"}, + Candidate: store.RuntimeModelCandidate{ + Provider: "keling", + AuthType: "AccessKey-SecretKey", + ProviderModelName: "kling-3.0-turbo", + Credentials: map[string]any{"accessKey": "ak", "secretKey": "sk"}, + }, + }) + if err == nil || !strings.Contains(err.Error(), "new API key") { + t.Fatalf("expected keling 3.0 turbo API key requirement, got %v", err) + } +} + +func TestKelingClient30TurboResumePollsWithoutSubmitting(t *testing.T) { + var submitCalled bool + var pollQuery string + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch r.Method + " " + r.URL.Path { + case "POST /text-to-video/kling-3.0-turbo": + submitCalled = true + t.Fatalf("resume should not submit a new keling 3.0 turbo task") + case "GET /tasks": + pollQuery = r.URL.RawQuery + _ = json.NewEncoder(w).Encode(map[string]any{ + "code": 0, + "request_id": "req-turbo-resume", + "data": []any{ + map[string]any{ + "id": "turbo-existing", + "status": "succeeded", + "outputs": []any{ + map[string]any{"type": "video", "url": "https://example.com/resumed-turbo.mp4"}, + }, + }, + }, + }) + default: + t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path) + } + })) + defer server.Close() + + response, err := (KelingClient{HTTPClient: server.Client()}).Run(context.Background(), Request{ + Kind: "videos.generations", + ModelType: "video_generate", + RemoteTaskID: "turbo-existing", + Body: map[string]any{}, + Candidate: store.RuntimeModelCandidate{ + BaseURL: server.URL + "/v1", + Provider: "keling", + AuthType: "APIKey", + ProviderModelName: "kling-3.0-turbo", + Credentials: map[string]any{"apiKey": "kling-api-key"}, + PlatformConfig: map[string]any{ + "kelingPollIntervalMs": 100, + "kelingPollTimeoutSeconds": 1, + }, + }, + }) + if err != nil { + t.Fatalf("resume keling 3.0 turbo video: %v", err) + } + if submitCalled || pollQuery != "task_ids=turbo-existing" { + t.Fatalf("resume should only poll existing task, submit=%v query=%s", submitCalled, pollQuery) + } + data, _ := response.Result["data"].([]any) + item, _ := data[0].(map[string]any) + if item["url"] != "https://example.com/resumed-turbo.mp4" { + t.Fatalf("unexpected resumed keling 3.0 turbo response: %+v", response.Result) + } +} + +func TestKeling30TurboPayloadBuildsFirstFrameAndMultiShotRequests(t *testing.T) { + imagePayload, endpoint, err := keling30TurboPayload(Request{ + Body: map[string]any{ + "duration": 5, + "resolution": "720p", + "content": []any{ + map[string]any{"type": "text", "text": "The subject looks toward the camera"}, + map[string]any{ + "type": "image_url", + "role": "first_frame", + "image_url": map[string]any{"url": "https://example.com/first.png"}, + }, + }, + }, + }) + if err != nil { + t.Fatalf("build keling 3.0 turbo image payload: %v", err) + } + if endpoint != "/image-to-video/kling-3.0-turbo" { + t.Fatalf("unexpected image endpoint: %s", endpoint) + } + if _, ok := mapFromAny(imagePayload["settings"])["aspect_ratio"]; ok { + t.Fatalf("image-to-video settings should not contain aspect_ratio: %+v", imagePayload) + } + contents, _ := imagePayload["contents"].([]any) + frame := mapFromAny(contents[1]) + if frame["type"] != "first_frame" || frame["url"] != "https://example.com/first.png" { + t.Fatalf("unexpected image contents: %+v", imagePayload["contents"]) + } + + shotPayload, _, err := keling30TurboPayload(Request{ + Body: map[string]any{ + "resolution": "720p", + "content": []any{ + map[string]any{"type": "text", "role": "shot_prompt", "shot_index": 1, "duration": 4, "text": "A car enters the tunnel"}, + map[string]any{"type": "text", "role": "shot_prompt", "shot_index": 2, "duration": 3, "text": "The headlights fill the frame"}, + }, + }, + }) + if err != nil { + t.Fatalf("build keling 3.0 turbo shot payload: %v", err) + } + if shotPayload["prompt"] != "shot 1, 4s, A car enters the tunnel; shot 2, 3s, The headlights fill the frame;" || + numericValue(mapFromAny(shotPayload["settings"])["duration"], 0) != 7 { + t.Fatalf("unexpected shot payload: %+v", shotPayload) + } +} + +func TestKeling30TurboPayloadRejectsLastFrame(t *testing.T) { + _, _, err := keling30TurboPayload(Request{ + Body: map[string]any{ + "prompt": "Move forward", + "last_frame": "https://example.com/last.png", + }, + }) + if err == nil || !strings.Contains(err.Error(), "last frame") { + t.Fatalf("expected unsupported last frame error, got %v", err) + } +} + func TestKelingOmniPayloadConvertsGatewayContent(t *testing.T) { payload, cleanupIDs, err := (KelingClient{}).kelingOmniPayload(context.Background(), Request{ Kind: "videos.generations", diff --git a/apps/api/internal/clients/keling.go b/apps/api/internal/clients/keling.go index dfe1a09..310595b 100644 --- a/apps/api/internal/clients/keling.go +++ b/apps/api/internal/clients/keling.go @@ -9,9 +9,11 @@ import ( "io" "math" "net/http" + "net/url" "sort" "strings" "time" + "unicode/utf8" "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" "github.com/golang-jwt/jwt/v5" @@ -32,14 +34,34 @@ func (c KelingClient) Run(ctx context.Context, request Request) (Response, error if request.Kind != "videos.generations" { return Response{}, &ClientError{Code: "unsupported_kind", Message: "unsupported keling request kind", Retryable: false} } - token, err := kelingAuthToken(request.Candidate) + token, err := kelingAuthTokenForRequest(request) if err != nil { return Response{}, err } return c.runVideo(ctx, request, token) } +func kelingAuthTokenForRequest(request Request) (string, error) { + if kelingIs30TurboRequest(request) { + apiKey := credential(request.Candidate.Credentials, "apiKey", "api_key", "key", "token") + if apiKey == "" { + return "", &ClientError{ + Code: "missing_credentials", + Message: "keling 3.0 turbo requires the new API key; legacy accessKey/secretKey credentials do not support new models", + Retryable: false, + StatusCode: http.StatusBadRequest, + } + } + return apiKey, nil + } + return kelingAuthToken(request.Candidate) +} + func (c KelingClient) runVideo(ctx context.Context, request Request, token string) (Response, error) { + if kelingIs30TurboRequest(request) { + return c.runTaskAPIVideo(ctx, request, token) + } + submitStartedAt := time.Now() submitRequestID := strings.TrimSpace(request.RemoteTaskID) upstreamTaskID := strings.TrimSpace(request.RemoteTaskID) @@ -143,6 +165,105 @@ func (c KelingClient) runVideo(ctx context.Context, request Request, token strin } } +func (c KelingClient) runTaskAPIVideo(ctx context.Context, request Request, token string) (Response, error) { + submitStartedAt := time.Now() + submitRequestID := strings.TrimSpace(request.RemoteTaskID) + upstreamTaskID := strings.TrimSpace(request.RemoteTaskID) + taskAPIBaseURL := kelingTaskAPIBaseURL(request.Candidate.BaseURL) + + if upstreamTaskID == "" { + payload, endpoint, err := keling30TurboPayload(request) + if err != nil { + return Response{}, err + } + submitResult, requestID, err := c.postJSONAt(ctx, request, taskAPIBaseURL, endpoint, token, payload) + submitRequestID = requestID + if err != nil { + return Response{}, annotateResponseError(err, submitRequestID, submitStartedAt, time.Now()) + } + upstreamTaskID = strings.TrimSpace(stringFromAny(kelingData(submitResult)["id"])) + if upstreamTaskID == "" { + return Response{}, &ClientError{Code: "invalid_response", Message: "keling 3.0 turbo task id is missing", RequestID: submitRequestID, Retryable: false} + } + if request.OnRemoteTaskSubmitted != nil { + if err := request.OnRemoteTaskSubmitted(upstreamTaskID, map[string]any{ + "endpoint": endpoint, + "taskApi": "keling_tasks_v2", + "submit": submitResult, + }); err != nil { + return Response{}, err + } + } + } + + interval := kelingPollInterval(request) + timeout := kelingPollTimeout(request) + deadline := time.NewTimer(timeout) + defer deadline.Stop() + ticker := time.NewTicker(interval) + defer ticker.Stop() + + var lastStatus string + for { + select { + case <-ctx.Done(): + return Response{}, &ClientError{Code: "cancelled", Message: ctx.Err().Error(), RequestID: submitRequestID, Retryable: true} + default: + } + + pollStartedAt := time.Now() + pollResult, pollRequestID, err := c.getJSONAt( + ctx, + request, + taskAPIBaseURL, + "/tasks?task_ids="+url.QueryEscape(upstreamTaskID), + token, + ) + pollFinishedAt := time.Now() + requestID := firstNonEmpty(pollRequestID, submitRequestID, upstreamTaskID) + if err != nil { + return Response{}, annotateResponseError(err, requestID, pollStartedAt, pollFinishedAt) + } + + task := kelingTaskAPITask(pollResult, upstreamTaskID) + lastStatus = strings.ToLower(strings.TrimSpace(stringFromAny(task["status"]))) + switch lastStatus { + case "succeeded", "succeed": + return Response{ + Result: kelingTaskAPIVideoSuccessResult(request, upstreamTaskID, task, pollResult), + RequestID: requestID, + Progress: kelingVideoProgress(request, upstreamTaskID), + ResponseStartedAt: submitStartedAt, + ResponseFinishedAt: pollFinishedAt, + ResponseDurationMS: responseDurationMS(submitStartedAt, pollFinishedAt), + }, nil + case "failed": + return Response{}, &ClientError{ + Code: "keling_task_failed", + Message: kelingTaskAPIErrorMessage(request.Candidate, task, pollResult), + RequestID: requestID, + ResponseStartedAt: submitStartedAt, + ResponseFinishedAt: pollFinishedAt, + ResponseDurationMS: responseDurationMS(submitStartedAt, pollFinishedAt), + Retryable: false, + } + } + + select { + case <-ctx.Done(): + return Response{}, &ClientError{Code: "cancelled", Message: ctx.Err().Error(), RequestID: requestID, Retryable: true} + case <-deadline.C: + return Response{}, &ClientError{ + Code: "timeout", + Message: fmt.Sprintf("keling 3.0 turbo task %s did not finish before timeout; last status: %s", upstreamTaskID, lastStatus), + RequestID: requestID, + Retryable: true, + } + case <-ticker.C: + } + } +} + func (c KelingClient) prepareVideoTask(ctx context.Context, request Request, token string) (kelingPreparedTask, error) { if kelingIsOmniRequest(request) { payload, cleanupIDs, err := c.kelingOmniPayload(ctx, request, token) @@ -400,8 +521,12 @@ func (c KelingClient) kelingOmniElementList(ctx context.Context, request Request } func (c KelingClient) postJSON(ctx context.Context, request Request, path string, token string, body map[string]any) (map[string]any, string, error) { + return c.postJSONAt(ctx, request, request.Candidate.BaseURL, path, token, body) +} + +func (c KelingClient) postJSONAt(ctx context.Context, request Request, baseURL string, path string, token string, body map[string]any) (map[string]any, string, error) { raw, _ := json.Marshal(body) - req, err := http.NewRequestWithContext(ctx, http.MethodPost, joinURL(request.Candidate.BaseURL, path), bytes.NewReader(raw)) + req, err := http.NewRequestWithContext(ctx, http.MethodPost, joinURL(baseURL, path), bytes.NewReader(raw)) if err != nil { return nil, "", err } @@ -423,7 +548,11 @@ func (c KelingClient) postJSON(ctx context.Context, request Request, path string } func (c KelingClient) getJSON(ctx context.Context, request Request, path string, token string) (map[string]any, string, error) { - req, err := http.NewRequestWithContext(ctx, http.MethodGet, joinURL(request.Candidate.BaseURL, path), nil) + return c.getJSONAt(ctx, request, request.Candidate.BaseURL, path, token) +} + +func (c KelingClient) getJSONAt(ctx context.Context, request Request, baseURL string, path string, token string) (map[string]any, string, error) { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, joinURL(baseURL, path), nil) if err != nil { return nil, "", err } @@ -560,6 +689,127 @@ func kelingIsOmniRequest(request Request) bool { request.Candidate.Capabilities["omni"] != nil } +func kelingIs30TurboRequest(request Request) bool { + switch strings.ToLower(strings.TrimSpace(upstreamModelName(request.Candidate))) { + case "kling-3.0-turbo", "kling-v3-turbo", "kling-3-0-turbo": + return true + default: + return false + } +} + +func kelingTaskAPIBaseURL(baseURL string) string { + trimmed := strings.TrimRight(strings.TrimSpace(baseURL), "/") + if strings.HasSuffix(strings.ToLower(trimmed), "/v1") { + return trimmed[:len(trimmed)-len("/v1")] + } + return trimmed +} + +func keling30TurboPayload(request Request) (map[string]any, string, error) { + body := cleanProviderBody(request.Body) + content := contentItems(body["content"]) + if len(content) == 0 { + content = buildVolcesContentFromBody(body) + } + + shots := kelingShotPrompts(content) + if len(shots) > 6 { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo supports at most 6 shots", StatusCode: 400, Retryable: false} + } + prompt := firstKelingPrompt(content) + duration := numericValue(body["duration"], 5) + if len(shots) > 0 { + var promptBuilder strings.Builder + duration = 0 + for index, shot := range shots { + if shot.duration < 1 || math.Abs(shot.duration-math.Round(shot.duration)) > 1e-9 { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo shot duration must be an integer of at least 1 second", StatusCode: 400, Retryable: false} + } + duration += shot.duration + fmt.Fprintf(&promptBuilder, "shot %d, %ds, %s; ", index+1, int(math.Round(shot.duration)), shot.text) + } + prompt = strings.TrimSpace(promptBuilder.String()) + } + if prompt == "" { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo video prompt is required", StatusCode: 400, Retryable: false} + } + if math.Abs(duration-math.Round(duration)) > 1e-9 || duration < 3 || duration > 15 { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo duration must be an integer between 3 and 15 seconds", StatusCode: 400, Retryable: false} + } + + firstFrame, lastFrame, referenceImages := kelingImageInputs(content) + if lastFrame != "" { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo image-to-video supports first frame only; last frame is not supported", StatusCode: 400, Retryable: false} + } + imageCount := len(referenceImages) + if firstFrame != "" { + imageCount++ + } + if imageCount > 1 { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo image-to-video supports exactly one first-frame image", StatusCode: 400, Retryable: false} + } + if firstFrame == "" && len(referenceImages) == 1 { + firstFrame = referenceImages[0] + } + isImageToVideo := firstFrame != "" + + resolution := strings.TrimSpace(firstNonEmptyStringValue(body, "resolution", "size")) + if resolution == "" { + resolution = "720p" + } + if resolution != "720p" && resolution != "1080p" { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo resolution must be 720p or 1080p", StatusCode: 400, Retryable: false} + } + + promptLimit := 3072 + if isImageToVideo { + promptLimit = 2500 + } + if utf8.RuneCountInString(prompt) > promptLimit { + return nil, "", &ClientError{Code: "invalid_parameter", Message: fmt.Sprintf("keling 3.0 turbo prompt exceeds %d characters", promptLimit), StatusCode: 400, Retryable: false} + } + + settings := map[string]any{ + "duration": int(math.Round(duration)), + "resolution": resolution, + } + options := map[string]any{ + "watermark_info": map[string]any{"enabled": boolValue(body, "watermark")}, + } + if callbackURL := strings.TrimSpace(firstNonEmptyStringValue(body, "callback_url", "callbackUrl")); callbackURL != "" { + options["callback_url"] = callbackURL + } + if externalTaskID := strings.TrimSpace(firstNonEmptyStringValue(body, "external_task_id", "externalTaskId")); externalTaskID != "" { + options["external_task_id"] = externalTaskID + } + + if isImageToVideo { + return map[string]any{ + "contents": []any{ + map[string]any{"type": "prompt", "text": prompt}, + map[string]any{"type": "first_frame", "url": firstFrame}, + }, + "settings": settings, + "options": options, + }, "/image-to-video/kling-3.0-turbo", nil + } + + aspectRatio := strings.TrimSpace(firstNonEmptyStringValue(body, "aspect_ratio", "aspectRatio", "ratio")) + if aspectRatio == "" || aspectRatio == "adaptive" || aspectRatio == "keep_ratio" { + aspectRatio = "16:9" + } + if aspectRatio != "16:9" && aspectRatio != "9:16" && aspectRatio != "1:1" { + return nil, "", &ClientError{Code: "invalid_parameter", Message: "keling 3.0 turbo aspect_ratio must be 16:9, 9:16, or 1:1", StatusCode: 400, Retryable: false} + } + settings["aspect_ratio"] = aspectRatio + return map[string]any{ + "prompt": prompt, + "settings": settings, + "options": options, + }, "/text-to-video/kling-3.0-turbo", nil +} + func firstKelingPrompt(content []map[string]any) string { for _, item := range content { if stringFromAny(item["type"]) == "text" && stringFromAny(item["role"]) != "shot_prompt" && item["shot_index"] == nil { @@ -822,6 +1072,30 @@ func kelingTaskStatus(result map[string]any) string { return strings.ToLower(strings.TrimSpace(stringFromAny(kelingData(result)["task_status"]))) } +func kelingTaskAPITask(result map[string]any, taskID string) map[string]any { + tasks := mapListFromAny(result["data"]) + for _, task := range tasks { + if strings.TrimSpace(stringFromAny(task["id"])) == taskID { + return task + } + } + if len(tasks) > 0 { + return tasks[0] + } + return map[string]any{} +} + +func kelingTaskAPIErrorMessage(candidate store.RuntimeModelCandidate, task map[string]any, result map[string]any) string { + message := strings.TrimSpace(stringFromAny(task["message"])) + if message == "" { + message = strings.TrimSpace(stringFromAny(result["message"])) + } + if message == "" { + message = "keling 3.0 turbo video task failed" + } + return fmt.Sprintf("Platform:%s,Code:%v,requestId:%s,message:%s", candidate.Provider, result["code"], stringFromAny(result["request_id"]), message) +} + func kelingTaskErrorCode(result map[string]any) string { if code := intFromAny(result["code"]); code != 0 { return fmt.Sprintf("keling_%d", code) @@ -887,6 +1161,42 @@ func kelingVideoSuccessResult(request Request, upstreamTaskID string, raw map[st } } +func kelingTaskAPIVideoSuccessResult(request Request, upstreamTaskID string, task map[string]any, raw map[string]any) map[string]any { + outputs := mapListFromAny(task["outputs"]) + items := make([]any, 0, len(outputs)) + for _, output := range outputs { + if strings.ToLower(strings.TrimSpace(stringFromAny(output["type"]))) != "video" { + continue + } + videoURL := strings.TrimSpace(stringFromAny(output["url"])) + if videoURL == "" { + continue + } + item := map[string]any{"url": videoURL, "video_url": videoURL, "type": "video"} + if duration := numericValue(output["duration"], 0); duration > 0 { + item["duration"] = duration + } + if watermarkURL := strings.TrimSpace(stringFromAny(output["watermark_url"])); watermarkURL != "" { + item["watermark_url"] = watermarkURL + } + items = append(items, item) + } + created := intFromAny(task["create_time"]) + if created == 0 { + created = int(nowUnix()) + } + return map[string]any{ + "id": upstreamTaskID, + "object": "video.generation", + "created": created, + "model": upstreamModelName(request.Candidate), + "status": "succeeded", + "upstream_task_id": upstreamTaskID, + "data": items, + "raw": raw, + } +} + func kelingVideoProgress(request Request, upstreamTaskID string) []Progress { progress := providerProgress(request) progress = append(progress, Progress{ diff --git a/apps/api/internal/clients/openai.go b/apps/api/internal/clients/openai.go index be5c73b..8ee27f5 100644 --- a/apps/api/internal/clients/openai.go +++ b/apps/api/internal/clients/openai.go @@ -43,7 +43,14 @@ func (c OpenAIClient) Run(ctx context.Context, request Request) (Response, error if endpointKind == "chat.completions" { body = NormalizeChatCompletionRequestBody(body) applyOpenAIChatReasoningParams(body, request.Candidate) + body = FilterOpenAIChatRequestBody(body) } else if request.Kind == "responses" { + body = FilterOpenAIResponsesRequestBody(body) + if _, hasInput := body["input"]; !hasInput { + if messages, hasMessages := request.Body["messages"]; hasMessages { + body["input"] = messages + } + } delete(body, "messages") if request.UpstreamPreviousResponseID != "" { body["previous_response_id"] = request.UpstreamPreviousResponseID diff --git a/apps/api/internal/clients/openai_request_params.go b/apps/api/internal/clients/openai_request_params.go new file mode 100644 index 0000000..388a8cb --- /dev/null +++ b/apps/api/internal/clients/openai_request_params.go @@ -0,0 +1,108 @@ +package clients + +import ( + "fmt" + "net/http" + "sort" +) + +// Keep these lists aligned with openai-node 6.47.0 and the public OpenAI API +// reference. The Gateway accepts a small, explicit set of routing extensions at +// ingress, but only protocol fields (plus controlled provider adaptations) are +// allowed across the upstream boundary. +var openAIChatRequestParameters = stringSet( + "messages", "model", "audio", "frequency_penalty", "function_call", "functions", + "logit_bias", "logprobs", "max_completion_tokens", "max_tokens", "metadata", + "modalities", "moderation", "n", "parallel_tool_calls", "prediction", + "presence_penalty", "prompt_cache_key", "prompt_cache_options", "prompt_cache_retention", + "reasoning_effort", "response_format", "safety_identifier", "seed", "service_tier", + "stop", "store", "stream", "stream_options", "temperature", "tool_choice", "tools", + "top_logprobs", "top_p", "user", "verbosity", "web_search_options", +) + +var openAIResponsesRequestParameters = stringSet( + "background", "context_management", "conversation", "include", "input", "instructions", + "max_output_tokens", "max_tool_calls", "metadata", "model", "moderation", + "parallel_tool_calls", "previous_response_id", "prompt", "prompt_cache_key", + "prompt_cache_options", "prompt_cache_retention", "reasoning", "safety_identifier", + "service_tier", "store", "stream", "stream_options", "temperature", "text", + "tool_choice", "tools", "top_logprobs", "top_p", "truncation", "user", +) + +var gatewayOpenAIRequestExtensions = stringSet( + "runMode", "run_mode", "conversationId", "conversation_id", "sessionId", "session_id", + "requestId", "request_id", "signal", "userMessage", "user_message", "platformId", + "platform_id", "options", "enable_thinking", "thinking_budget_tokens", "enable_web_search", + "modelType", "model_type", "capability", "capabilityType", "mode", "simulation", "testMode", +) + +var gatewayResponsesRequestExtensions = stringSet("messages", "presence_penalty", "frequency_penalty") + +var controlledOpenAIChatProviderParameters = stringSet( + "enable_thinking", "thinking_budget", "thinking", "enable_web_search", +) + +var controlledOpenAIResponsesProviderParameters = stringSet("presence_penalty", "frequency_penalty") + +func ValidateOpenAIRequestParameters(kind string, body map[string]any) error { + allowed := openAIChatRequestParameters + if kind == "responses" { + allowed = openAIResponsesRequestParameters + } + unknown := make([]string, 0) + for key := range body { + if _, ok := allowed[key]; ok { + continue + } + if _, ok := gatewayOpenAIRequestExtensions[key]; ok { + continue + } + if kind == "responses" { + if _, ok := gatewayResponsesRequestExtensions[key]; ok { + continue + } + } + unknown = append(unknown, key) + } + if len(unknown) == 0 { + return nil + } + sort.Strings(unknown) + return &ClientError{ + Code: "invalid_parameter", + Message: fmt.Sprintf("Unknown parameter: %s", unknown[0]), + Param: unknown[0], + StatusCode: http.StatusBadRequest, + Retryable: false, + } +} + +func FilterOpenAIChatRequestBody(body map[string]any) map[string]any { + return filterOpenAIRequestBody(body, openAIChatRequestParameters, controlledOpenAIChatProviderParameters) +} + +func FilterOpenAIResponsesRequestBody(body map[string]any) map[string]any { + return filterOpenAIRequestBody(body, openAIResponsesRequestParameters, controlledOpenAIResponsesProviderParameters) +} + +func filterOpenAIRequestBody(body map[string]any, allowed map[string]struct{}, extensions map[string]struct{}) map[string]any { + out := make(map[string]any, len(body)) + for key, value := range body { + if _, ok := allowed[key]; ok { + out[key] = value + continue + } + if _, ok := extensions[key]; ok { + out[key] = value + } + } + return out +} + +func stringSet(values ...string) map[string]struct{} { + out := make(map[string]struct{}, len(values)) + for _, value := range values { + out[value] = struct{}{} + } + return out +} diff --git a/apps/api/internal/clients/openai_request_params_test.go b/apps/api/internal/clients/openai_request_params_test.go new file mode 100644 index 0000000..df4de80 --- /dev/null +++ b/apps/api/internal/clients/openai_request_params_test.go @@ -0,0 +1,89 @@ +package clients + +import ( + "strings" + "testing" +) + +func TestOpenAIChatOfficialParametersSurviveBoundary(t *testing.T) { + body := map[string]any{} + for key := range openAIChatRequestParameters { + body[key] = "sentinel-" + key + } + body["conversationId"] = "internal" + body["unknown"] = "must-not-leak" + + filtered := FilterOpenAIChatRequestBody(body) + for key := range openAIChatRequestParameters { + if _, ok := filtered[key]; !ok { + t.Fatalf("official Chat parameter %q was removed", key) + } + } + for _, key := range []string{"conversationId", "unknown"} { + if _, ok := filtered[key]; ok { + t.Fatalf("internal/unknown parameter %q leaked upstream", key) + } + } +} + +func TestOpenAIResponsesOfficialParametersSurviveBoundary(t *testing.T) { + body := map[string]any{} + for key := range openAIResponsesRequestParameters { + body[key] = "sentinel-" + key + } + body["request_id"] = "internal" + body["unknown"] = "must-not-leak" + + filtered := FilterOpenAIResponsesRequestBody(body) + for key := range openAIResponsesRequestParameters { + if _, ok := filtered[key]; !ok { + t.Fatalf("official Responses parameter %q was removed", key) + } + } + for _, key := range []string{"request_id", "unknown"} { + if _, ok := filtered[key]; ok { + t.Fatalf("internal/unknown parameter %q leaked upstream", key) + } + } +} + +func TestValidateOpenAIRequestParametersRejectsUnknownTopLevelField(t *testing.T) { + err := ValidateOpenAIRequestParameters("responses", map[string]any{"model": "demo", "input": "hello", "rogue": true}) + if err == nil || ErrorCode(err) != "invalid_parameter" || !strings.Contains(err.Error(), "rogue") { + t.Fatalf("expected OpenAI-style invalid_parameter for rogue field, got %v", err) + } + if ErrorParam(err) != "rogue" { + t.Fatalf("expected rogue parameter attribution, got %q", ErrorParam(err)) + } + if err := ValidateOpenAIRequestParameters("responses", map[string]any{"model": "demo", "input": "hello", "messages": []any{}, "request_id": "internal"}); err != nil { + t.Fatalf("expected controlled Responses extensions to remain accepted, got %v", err) + } +} + +func TestResponsesFallbackMapsEquivalentCurrentParameters(t *testing.T) { + body, err := ResponsesRequestToChat(map[string]any{ + "input": "hello", "store": false, "metadata": map[string]any{"trace": "1"}, + "request_id": "internal-request", "platform_id": "internal-platform", + "moderation": map[string]any{"type": "auto"}, "prompt_cache_key": "cache-key", + "prompt_cache_options": map[string]any{"type": "ephemeral"}, "prompt_cache_retention": "in_memory", + "safety_identifier": "safe", "service_tier": "priority", "top_logprobs": 3, + "stream_options": map[string]any{"include_usage": true}, + "text": map[string]any{"format": map[string]any{"type": "text"}, "verbosity": "low"}, + }, nil) + if err != nil { + t.Fatalf("convert Responses request: %v", err) + } + for _, key := range []string{"store", "metadata", "moderation", "prompt_cache_key", "prompt_cache_options", "prompt_cache_retention", "safety_identifier", "service_tier", "top_logprobs", "stream_options", "verbosity"} { + if _, ok := body[key]; !ok { + t.Fatalf("equivalent parameter %q was not mapped", key) + } + } + if body["logprobs"] != true { + t.Fatalf("top_logprobs fallback must enable Chat logprobs: %+v", body) + } + for _, key := range []string{"request_id", "platform_id"} { + if _, ok := body[key]; ok { + t.Fatalf("internal Responses parameter %q leaked into Chat fallback: %+v", key, body) + } + } +} diff --git a/apps/api/internal/clients/responses_compat.go b/apps/api/internal/clients/responses_compat.go index f0cd984..c361890 100644 --- a/apps/api/internal/clients/responses_compat.go +++ b/apps/api/internal/clients/responses_compat.go @@ -21,11 +21,16 @@ var supportedResponseFallbackParameters = map[string]struct{}{ "model": {}, "input": {}, "messages": {}, "instructions": {}, "tools": {}, "tool_choice": {}, "parallel_tool_calls": {}, "max_output_tokens": {}, "temperature": {}, "top_p": {}, "presence_penalty": {}, "frequency_penalty": {}, "reasoning": {}, "text": {}, - "stream": {}, "store": {}, "previous_response_id": {}, "metadata": {}, "user": {}, + "stream": {}, "stream_options": {}, "store": {}, "previous_response_id": {}, "metadata": {}, "user": {}, + "moderation": {}, "prompt_cache_key": {}, "prompt_cache_options": {}, "prompt_cache_retention": {}, + "safety_identifier": {}, "service_tier": {}, "top_logprobs": {}, } func ResponsesRequestToChat(body map[string]any, history []ResponseTurn) (map[string]any, error) { for key := range body { + if _, internal := gatewayOpenAIRequestExtensions[key]; internal { + continue + } if _, ok := supportedResponseFallbackParameters[key]; !ok { return nil, unsupportedResponseParameter(key) } @@ -61,11 +66,19 @@ func ResponsesRequestToChat(body map[string]any, history []ResponseTurn) (map[st return nil, &ClientError{Code: "invalid_parameter", Message: "input is required", StatusCode: http.StatusBadRequest} } out := map[string]any{"messages": messages} - for _, key := range []string{"temperature", "top_p", "presence_penalty", "frequency_penalty", "parallel_tool_calls", "stream", "user"} { + for _, key := range []string{ + "temperature", "top_p", "presence_penalty", "frequency_penalty", "parallel_tool_calls", + "stream", "stream_options", "store", "metadata", "user", "moderation", "prompt_cache_key", + "prompt_cache_options", "prompt_cache_retention", "safety_identifier", "service_tier", + } { if value, ok := body[key]; ok { out[key] = value } } + if value, ok := body["top_logprobs"]; ok { + out["top_logprobs"] = value + out["logprobs"] = true + } if value, ok := body["max_output_tokens"]; ok { out["max_tokens"] = value } @@ -84,13 +97,16 @@ func ResponsesRequestToChat(body map[string]any, history []ResponseTurn) (map[st } } if rawText, ok := body["text"]; ok { - responseFormat, err := responseTextFormat(rawText) + responseFormat, verbosity, err := responseTextParams(rawText) if err != nil { return nil, err } if responseFormat != nil { out["response_format"] = responseFormat } + if verbosity != nil { + out["verbosity"] = verbosity + } } if rawTools, ok := body["tools"]; ok { tools, err := responseToolsToChat(rawTools) @@ -212,31 +228,32 @@ func responseToolChoiceToChat(value any) (any, error) { return map[string]any{"type": "function", "function": map[string]any{"name": choice["name"]}}, nil } -func responseTextFormat(value any) (map[string]any, error) { +func responseTextParams(value any) (map[string]any, any, error) { text, ok := value.(map[string]any) if !ok { - return nil, unsupportedResponseParameter("text") + return nil, nil, unsupportedResponseParameter("text") } for key := range text { - if key != "format" { - return nil, unsupportedResponseParameter("text." + key) + if key != "format" && key != "verbosity" { + return nil, nil, unsupportedResponseParameter("text." + key) } } + verbosity := text["verbosity"] format, ok := text["format"].(map[string]any) if !ok || len(format) == 0 { - return nil, nil + return nil, verbosity, nil } switch stringFromAny(format["type"]) { case "text": - return map[string]any{"type": "text"}, nil + return map[string]any{"type": "text"}, verbosity, nil case "json_object": - return map[string]any{"type": "json_object"}, nil + return map[string]any{"type": "json_object"}, verbosity, nil case "json_schema": return map[string]any{"type": "json_schema", "json_schema": map[string]any{ "name": format["name"], "schema": format["schema"], "strict": format["strict"], - }}, nil + }}, verbosity, nil default: - return nil, unsupportedResponseParameter("text.format.type") + return nil, nil, unsupportedResponseParameter("text.format.type") } } diff --git a/apps/api/internal/clients/responses_compat_test.go b/apps/api/internal/clients/responses_compat_test.go index 8c6b4c4..0adb741 100644 --- a/apps/api/internal/clients/responses_compat_test.go +++ b/apps/api/internal/clients/responses_compat_test.go @@ -23,6 +23,10 @@ func TestOpenAIResponsesNativeUsesResponsesEndpointAndPreservesVendorIDs(t *test if body["messages"] != nil { t.Fatalf("native Responses request must not contain messages: %+v", body) } + input, _ := body["input"].([]any) + if len(input) != 1 { + t.Fatalf("native Responses request must translate controlled messages to input: %+v", body) + } if body["previous_response_id"] != "resp_upstream_parent" { t.Fatalf("expected translated upstream previous id, got %+v", body["previous_response_id"]) } @@ -41,7 +45,7 @@ func TestOpenAIResponsesNativeUsesResponsesEndpointAndPreservesVendorIDs(t *test response, err := (OpenAIClient{}).Run(context.Background(), Request{ Kind: "responses", Model: "Demo", - Body: map[string]any{"input": "hello", "messages": []any{map[string]any{"role": "user", "content": "illegal"}}}, + Body: map[string]any{"messages": []any{map[string]any{"role": "user", "content": "hello"}}}, Candidate: store.RuntimeModelCandidate{BaseURL: server.URL, ProviderModelName: "demo", Credentials: map[string]any{"apiKey": "secret"}}, UpstreamProtocol: ProtocolOpenAIResponses, PublicResponseID: "resp_12345678901234567890123456789012", PublicPreviousResponseID: "resp_abcdefghijklmnopqrstuvwxyz123456", UpstreamPreviousResponseID: "resp_upstream_parent", diff --git a/apps/api/internal/clients/types.go b/apps/api/internal/clients/types.go index 89c1ca4..5462f05 100644 --- a/apps/api/internal/clients/types.go +++ b/apps/api/internal/clients/types.go @@ -103,6 +103,7 @@ type VoiceCloneDeleter interface { type ClientError struct { Code string Message string + Param string StatusCode int RequestID string ResponseStartedAt time.Time @@ -111,6 +112,14 @@ type ClientError struct { Retryable bool } +func ErrorParam(err error) string { + var clientErr *ClientError + if errors.As(err, &clientErr) { + return clientErr.Param + } + return "" +} + func (e *ClientError) Error() string { if e.Message != "" { return e.Message diff --git a/apps/api/internal/clients/volces.go b/apps/api/internal/clients/volces.go index dd01b78..9eefa56 100644 --- a/apps/api/internal/clients/volces.go +++ b/apps/api/internal/clients/volces.go @@ -74,12 +74,13 @@ func (c VolcesClient) runVideo(ctx context.Context, request Request, apiKey stri submitStartedAt := time.Now() submitRequestID := strings.TrimSpace(request.RemoteTaskID) upstreamTaskID := strings.TrimSpace(request.RemoteTaskID) + taskPath := volcesVideoTaskPath(request) if upstreamTaskID == "" { body := volcesVideoBody(request) if err := validateVolcesVideoTaskBody(body); err != nil { return Response{}, err } - submitResult, requestID, err := c.postJSON(ctx, request, request.Candidate.BaseURL, "/contents/generations/tasks", apiKey, body) + submitResult, requestID, err := c.postJSON(ctx, request, request.Candidate.BaseURL, taskPath, apiKey, body) submitRequestID = requestID if err != nil { return Response{}, annotateResponseError(err, submitRequestID, submitStartedAt, time.Now()) @@ -112,7 +113,7 @@ func (c VolcesClient) runVideo(ctx context.Context, request Request, apiKey stri } pollStartedAt := time.Now() - pollResult, pollRequestID, err := c.getJSON(ctx, request, request.Candidate.BaseURL, "/contents/generations/tasks/"+upstreamTaskID, apiKey) + pollResult, pollRequestID, err := c.getJSON(ctx, request, request.Candidate.BaseURL, taskPath+"/"+upstreamTaskID, apiKey) pollFinishedAt := time.Now() requestID := firstNonEmpty(pollRequestID, submitRequestID, upstreamTaskID) if err != nil { @@ -159,6 +160,21 @@ func (c VolcesClient) runVideo(ctx context.Context, request Request, apiKey stri } } +func volcesVideoTaskPath(request Request) string { + path := firstNonEmptyStringValue( + request.Candidate.PlatformConfig, + "volcesVideoTaskPath", + "videoTaskPath", + ) + if path == "" { + return "/contents/generations/tasks" + } + if !strings.HasPrefix(path, "/") { + path = "/" + path + } + return strings.TrimRight(path, "/") +} + func (c VolcesClient) postJSON(ctx context.Context, request Request, baseURL string, path string, apiKey string, body map[string]any) (map[string]any, string, error) { raw, _ := json.Marshal(body) req, err := http.NewRequestWithContext(ctx, http.MethodPost, joinURL(baseURL, path), bytes.NewReader(raw)) @@ -173,7 +189,11 @@ func (c VolcesClient) postJSON(ctx context.Context, request Request, baseURL str } requestID := requestIDFromHTTPResponse(resp) result, err := decodeHTTPResponse(resp) - return result, requestID, err + if err != nil { + return result, requestID, err + } + result, envelopeRequestID, err := normalizeVolcesCompatibleResult(result) + return result, firstNonEmpty(requestID, envelopeRequestID), err } func (c VolcesClient) getJSON(ctx context.Context, request Request, baseURL string, path string, apiKey string) (map[string]any, string, error) { @@ -188,7 +208,64 @@ func (c VolcesClient) getJSON(ctx context.Context, request Request, baseURL stri } requestID := requestIDFromHTTPResponse(resp) result, err := decodeHTTPResponse(resp) - return result, requestID, err + if err != nil { + return result, requestID, err + } + result, envelopeRequestID, err := normalizeVolcesCompatibleResult(result) + return result, firstNonEmpty(requestID, envelopeRequestID), err +} + +func normalizeVolcesCompatibleResult(result map[string]any) (map[string]any, string, error) { + requestID := firstNonEmpty( + stringFromAny(result["request_id"]), + stringFromAny(result["requestId"]), + ) + if errorObject, ok := result["error"].(map[string]any); ok { + code := firstNonEmpty( + stringFromAny(errorObject["code"]), + stringFromAny(errorObject["type"]), + "volces_compatible_error", + ) + message := strings.TrimSpace(stringFromAny(errorObject["message"])) + if message == "" { + message = "volces compatible request failed" + } + return result, requestID, &ClientError{ + Code: code, + Message: message, + RequestID: requestID, + Retryable: false, + } + } + rawCode, hasCode := result["code"] + if !hasCode { + return result, requestID, nil + } + code, validCode := volcesIntFromAny(rawCode) + if !validCode { + return result, requestID, nil + } + if code != 0 { + message := strings.TrimSpace(stringFromAny(result["message"])) + if message == "" { + message = fmt.Sprintf("volces compatible request failed with code %d", code) + } + return result, requestID, &ClientError{ + Code: fmt.Sprintf("volces_%d", code), + Message: message, + RequestID: requestID, + Retryable: false, + } + } + data, ok := result["data"].(map[string]any) + if !ok { + return result, requestID, nil + } + normalized := cloneBody(data) + if requestID != "" && requestIDFromResult(normalized) == "" { + normalized["request_id"] = requestID + } + return normalized, requestID, nil } func volcesImageBody(request Request) map[string]any { diff --git a/apps/api/internal/clients/volces_deyun_test.go b/apps/api/internal/clients/volces_deyun_test.go new file mode 100644 index 0000000..04485a1 --- /dev/null +++ b/apps/api/internal/clients/volces_deyun_test.go @@ -0,0 +1,129 @@ +package clients + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" +) + +func TestVolcesClientSupportsDeyunEnvelope(t *testing.T) { + var submitted bool + var polled bool + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get("Authorization") != "Bearer deyun-secret" { + t.Fatalf("unexpected authorization header: %q", r.Header.Get("Authorization")) + } + switch r.Method + " " + r.URL.Path { + case "POST /c39/api/v3/video/tasks": + submitted = true + _ = json.NewEncoder(w).Encode(map[string]any{ + "code": 0, + "request_id": "deyun-submit-request", + "data": map[string]any{"id": "deyun-task-1"}, + }) + case "GET /c39/api/v3/video/tasks/deyun-task-1": + polled = true + _ = json.NewEncoder(w).Encode(map[string]any{ + "code": 0, + "request_id": "deyun-poll-request", + "data": map[string]any{ + "id": "deyun-task-1", + "status": "succeeded", + "created_at": 123, + "content": map[string]any{ + "video_url": "https://example.com/deyun.mp4", + }, + }, + }) + default: + t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path) + } + })) + defer server.Close() + + response, err := (VolcesClient{HTTPClient: server.Client()}).Run(context.Background(), Request{ + Kind: "videos.generations", + ModelType: "video_generate", + Model: "deyun-seedance-2.0-canary", + Body: map[string]any{ + "prompt": "A red cube rotates on a white table", + "resolution": "480p", + "ratio": "16:9", + "duration": 4, + "generate_audio": false, + }, + Candidate: store.RuntimeModelCandidate{ + BaseURL: server.URL + "/c39/api/v3", + ProviderModelName: "doubao-seedance-2-0", + Credentials: map[string]any{"apiKey": "deyun-secret"}, + PlatformConfig: map[string]any{ + "volcesPollIntervalMs": 100, + "volcesPollTimeoutSeconds": 1, + "volcesVideoTaskPath": "/video/tasks", + }, + }, + }) + if err != nil { + t.Fatalf("run deyun-compatible video task: %v", err) + } + if !submitted || !polled { + t.Fatalf("expected submit and poll, submitted=%v polled=%v", submitted, polled) + } + if response.RequestID != "deyun-poll-request" { + t.Fatalf("unexpected request id: %s", response.RequestID) + } + data, _ := response.Result["data"].([]any) + item, _ := data[0].(map[string]any) + if response.Result["upstream_task_id"] != "deyun-task-1" || item["url"] != "https://example.com/deyun.mp4" { + t.Fatalf("unexpected response: %+v", response.Result) + } +} + +func TestNormalizeVolcesCompatibleResultPreservesNativeResponse(t *testing.T) { + native := map[string]any{"id": "native-task", "status": "queued"} + got, requestID, err := normalizeVolcesCompatibleResult(native) + if err != nil { + t.Fatalf("normalize native response: %v", err) + } + if got["id"] != "native-task" || requestID != "" { + t.Fatalf("native response changed unexpectedly: %+v requestID=%q", got, requestID) + } +} + +func TestNormalizeVolcesCompatibleResultRejectsBusinessError(t *testing.T) { + _, requestID, err := normalizeVolcesCompatibleResult(map[string]any{ + "code": 1004, + "message": "Authorization is expired", + "request_id": "deyun-error-request", + }) + if err == nil { + t.Fatal("expected business error") + } + if requestID != "deyun-error-request" || ErrorCode(err) != "volces_1004" { + t.Fatalf("unexpected error metadata requestID=%q code=%q err=%v", requestID, ErrorCode(err), err) + } + if !strings.Contains(err.Error(), "Authorization is expired") { + t.Fatalf("unexpected error message: %v", err) + } +} + +func TestNormalizeVolcesCompatibleResultRejectsHTTP200ErrorObject(t *testing.T) { + _, _, err := normalizeVolcesCompatibleResult(map[string]any{ + "error": map[string]any{ + "code": "ModelNotOpen", + "message": "model service is not activated", + "type": "Not Found", + }, + }) + if err == nil { + t.Fatal("expected HTTP 200 error object to fail") + } + if ErrorCode(err) != "ModelNotOpen" || !strings.Contains(err.Error(), "not activated") { + t.Fatalf("unexpected error: code=%q err=%v", ErrorCode(err), err) + } +} diff --git a/apps/api/internal/httpapi/agent_resources_handlers.go b/apps/api/internal/httpapi/agent_resources_handlers.go new file mode 100644 index 0000000..9471763 --- /dev/null +++ b/apps/api/internal/httpapi/agent_resources_handlers.go @@ -0,0 +1,98 @@ +package httpapi + +import ( + "net/http" + + gatewaydocs "github.com/easyai/easyai-ai-gateway/apps/api/docs" + "github.com/easyai/easyai-ai-gateway/apps/api/internal/skillbundle" +) + +const ( + opsManagementSkillDownloadPath = "/api/v1/public/skills/ai-gateway-ops-management/download" + apiDocsJSONPath = "/api-docs-json" + apiDocsYAMLPath = "/api-docs-yaml" +) + +// getOpsManagementSkillMetadata godoc +// @Summary 获取 AI Gateway 运维管理 SKILL 元数据 +// @Description 返回公开运维管理 SKILL 的名称、版本、模块、下载文件名和机器可读接口文档路径。 +// @Tags agent-resources +// @Produce json +// @Success 200 {object} SkillBundleMetadataResponse +// @Failure 500 {object} ErrorEnvelope +// @Router /api/v1/public/skills/ai-gateway-ops-management/metadata [get] +func (s *Server) getOpsManagementSkillMetadata(w http.ResponseWriter, _ *http.Request) { + metadata, err := skillbundle.LoadMetadata() + if err != nil { + s.logger.Error("load operations skill metadata failed", "error", err) + writeError(w, http.StatusInternalServerError, "operations skill metadata unavailable") + return + } + writeJSON(w, http.StatusOK, opsManagementSkillMetadataResponse(metadata)) +} + +// downloadOpsManagementSkill godoc +// @Summary 下载 AI Gateway 运维管理 SKILL +// @Description 下载可交给 Agent 使用的 ai-gateway-ops-management ZIP 包。 +// @Tags agent-resources +// @Produce application/zip +// @Success 200 {file} binary +// @Failure 500 {object} ErrorEnvelope +// @Router /api/v1/public/skills/ai-gateway-ops-management/download [get] +func (s *Server) downloadOpsManagementSkill(w http.ResponseWriter, _ *http.Request) { + metadata, err := skillbundle.LoadMetadata() + if err != nil { + s.logger.Error("load operations skill metadata failed", "error", err) + writeError(w, http.StatusInternalServerError, "operations skill metadata unavailable") + return + } + archive, err := skillbundle.BuildArchive() + if err != nil { + s.logger.Error("build operations skill archive failed", "error", err) + writeError(w, http.StatusInternalServerError, "operations skill download unavailable") + return + } + w.Header().Set("Content-Type", "application/zip") + w.Header().Set("Content-Disposition", `attachment; filename="`+skillbundle.FileName(metadata)+`"`) + w.WriteHeader(http.StatusOK) + _, _ = w.Write(archive) +} + +// apiDocsJSON godoc +// @Summary 获取 AI Gateway Swagger JSON +// @Description 返回当前构建内嵌的完整机器可读 Swagger JSON，供 Agent 在 SKILL references 未覆盖接口时查询。 +// @Tags agent-resources +// @Produce json +// @Success 200 {object} map[string]interface{} +// @Router /api-docs-json [get] +func (s *Server) apiDocsJSON(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/json; charset=utf-8") + w.WriteHeader(http.StatusOK) + _, _ = w.Write(gatewaydocs.SwaggerJSON) +} + +// apiDocsYAML godoc +// @Summary 获取 AI Gateway Swagger YAML +// @Description 返回当前构建内嵌的完整机器可读 Swagger YAML。 +// @Tags agent-resources +// @Produce application/yaml +// @Success 200 {string} string +// @Router /api-docs-yaml [get] +func (s *Server) apiDocsYAML(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/yaml; charset=utf-8") + w.WriteHeader(http.StatusOK) + _, _ = w.Write(gatewaydocs.SwaggerYAML) +} + +func opsManagementSkillMetadataResponse(metadata skillbundle.Metadata) SkillBundleMetadataResponse { + return SkillBundleMetadataResponse{ + Name: metadata.Name, + Version: metadata.Version, + DisplayName: skillbundle.DisplayName, + Modules: metadata.Modules, + FileName: skillbundle.FileName(metadata), + DownloadPath: opsManagementSkillDownloadPath, + APIDocsJSONPath: apiDocsJSONPath, + APIDocsYAMLPath: apiDocsYAMLPath, + } +} diff --git a/apps/api/internal/httpapi/agent_resources_handlers_test.go b/apps/api/internal/httpapi/agent_resources_handlers_test.go new file mode 100644 index 0000000..f4426cb --- /dev/null +++ b/apps/api/internal/httpapi/agent_resources_handlers_test.go @@ -0,0 +1,115 @@ +package httpapi + +import ( + "archive/zip" + "bytes" + "encoding/json" + "io" + "log/slog" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +func TestGetOpsManagementSkillMetadata(t *testing.T) { + server := &Server{logger: slog.New(slog.NewTextHandler(io.Discard, nil))} + request := httptest.NewRequest(http.MethodGet, "/api/v1/public/skills/ai-gateway-ops-management/metadata", nil) + response := httptest.NewRecorder() + + server.getOpsManagementSkillMetadata(response, request) + + if response.Code != http.StatusOK { + t.Fatalf("expected metadata status 200, got %d: %s", response.Code, response.Body.String()) + } + var metadata SkillBundleMetadataResponse + if err := json.Unmarshal(response.Body.Bytes(), &metadata); err != nil { + t.Fatalf("decode metadata: %v", err) + } + if metadata.Name != "ai-gateway-ops-management" || metadata.Version != "1.0.2" { + t.Fatalf("unexpected metadata: %+v", metadata) + } + if len(metadata.Modules) != 1 || metadata.Modules[0] != "model-runtime" { + t.Fatalf("unexpected metadata modules: %+v", metadata.Modules) + } + if metadata.APIDocsJSONPath != "/api-docs-json" || metadata.APIDocsYAMLPath != "/api-docs-yaml" { + t.Fatalf("unexpected API docs paths: %+v", metadata) + } +} + +func TestDownloadOpsManagementSkill(t *testing.T) { + server := &Server{logger: slog.New(slog.NewTextHandler(io.Discard, nil))} + request := httptest.NewRequest(http.MethodGet, "/api/v1/public/skills/ai-gateway-ops-management/download", nil) + response := httptest.NewRecorder() + + server.downloadOpsManagementSkill(response, request) + + if response.Code != http.StatusOK { + t.Fatalf("expected download status 200, got %d: %s", response.Code, response.Body.String()) + } + if response.Header().Get("Content-Type") != "application/zip" { + t.Fatalf("unexpected content type: %q", response.Header().Get("Content-Type")) + } + if disposition := response.Header().Get("Content-Disposition"); !strings.Contains(disposition, "ai-gateway-ops-management-v1.0.2.zip") { + t.Fatalf("unexpected content disposition: %q", disposition) + } + raw := response.Body.Bytes() + archive, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw))) + if err != nil { + t.Fatalf("open downloaded archive: %v", err) + } + foundSkill := false + for _, file := range archive.File { + if file.Name == "SKILL.md" { + foundSkill = true + break + } + } + if !foundSkill { + t.Fatalf("downloaded archive does not contain SKILL.md") + } +} + +func TestEmbeddedAPIDocs(t *testing.T) { + server := &Server{} + + jsonResponse := httptest.NewRecorder() + server.apiDocsJSON(jsonResponse, httptest.NewRequest(http.MethodGet, "/api-docs-json", nil)) + if jsonResponse.Code != http.StatusOK { + t.Fatalf("expected JSON docs status 200, got %d", jsonResponse.Code) + } + if jsonResponse.Header().Get("Content-Type") != "application/json; charset=utf-8" { + t.Fatalf("unexpected JSON docs content type: %q", jsonResponse.Header().Get("Content-Type")) + } + var document struct { + Paths map[string]json.RawMessage `json:"paths"` + } + if err := json.Unmarshal(jsonResponse.Body.Bytes(), &document); err != nil { + t.Fatalf("decode embedded Swagger JSON: %v", err) + } + for _, path := range []string{ + "/api-docs-json", + "/api/v1/public/skills/ai-gateway-ops-management/download", + "/api/admin/catalog/providers", + "/api/admin/catalog/base-models", + "/api/admin/platforms", + "/api/admin/runtime/policy-sets", + "/api/admin/pricing/rule-sets", + } { + if document.Paths[path] == nil { + t.Fatalf("embedded Swagger JSON missing %q", path) + } + } + + yamlResponse := httptest.NewRecorder() + server.apiDocsYAML(yamlResponse, httptest.NewRequest(http.MethodGet, "/api-docs-yaml", nil)) + if yamlResponse.Code != http.StatusOK { + t.Fatalf("expected YAML docs status 200, got %d", yamlResponse.Code) + } + if yamlResponse.Header().Get("Content-Type") != "application/yaml; charset=utf-8" { + t.Fatalf("unexpected YAML docs content type: %q", yamlResponse.Header().Get("Content-Type")) + } + if !strings.Contains(yamlResponse.Body.String(), "/api/v1/public/skills/ai-gateway-ops-management/metadata") { + t.Fatalf("embedded Swagger YAML missing operations skill metadata path") + } +} diff --git a/apps/api/internal/httpapi/chat_completions_mode_test.go b/apps/api/internal/httpapi/chat_completions_mode_test.go index d28c873..df744fe 100644 --- a/apps/api/internal/httpapi/chat_completions_mode_test.go +++ b/apps/api/internal/httpapi/chat_completions_mode_test.go @@ -142,7 +142,7 @@ func TestWriteCompatibleTaskResponseMapsInvalidParameterToBadRequest(t *testing. executor := &fakeTaskExecutor{ runErr: &clients.ClientError{ Code: "invalid_parameter", - Message: "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh", + Message: "reasoning_effort must be one of: none, minimal, low, medium, high, xhigh, max", Retryable: false, }, } @@ -157,6 +157,9 @@ func TestWriteCompatibleTaskResponseMapsInvalidParameterToBadRequest(t *testing. if !strings.Contains(recorder.Body.String(), "invalid_parameter") { t.Fatalf("response should include invalid_parameter code: %s", recorder.Body.String()) } + if !strings.Contains(recorder.Body.String(), `"type":"invalid_request_error"`) || !strings.Contains(recorder.Body.String(), `"param":null`) { + t.Fatalf("response should use OpenAI error fields: %s", recorder.Body.String()) + } } func TestWriteCompatibleTaskResponseReturnsSSEWhenStreamIsTrue(t *testing.T) { diff --git a/apps/api/internal/httpapi/handlers.go b/apps/api/internal/httpapi/handlers.go index 52e59ef..82bb8cf 100644 --- a/apps/api/internal/httpapi/handlers.go +++ b/apps/api/internal/httpapi/handlers.go @@ -429,6 +429,10 @@ func (s *Server) createPlatformModel(w http.ResponseWriter, r *http.Request) { } model, err := s.store.CreatePlatformModel(r.Context(), input) if err != nil { + if errors.Is(err, store.ErrInvalidPlatformModelConfiguration) { + writeError(w, http.StatusBadRequest, err.Error(), "invalid_parameter") + return + } if store.IsNotFound(err) { writeError(w, http.StatusNotFound, "base model not found") return @@ -473,6 +477,10 @@ func (s *Server) replacePlatformModels(w http.ResponseWriter, r *http.Request) { models, err := s.store.ReplacePlatformModels(r.Context(), platformID, input.Models) if err != nil { + if errors.Is(err, store.ErrInvalidPlatformModelConfiguration) { + writeError(w, http.StatusBadRequest, err.Error(), "invalid_parameter") + return + } if store.IsNotFound(err) { writeError(w, http.StatusNotFound, "base model not found") return @@ -979,7 +987,6 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque // @Failure 404 {object} ErrorEnvelope // @Failure 429 {object} ErrorEnvelope // @Failure 502 {object} ErrorEnvelope -// @Router /api/v1/responses [post] // @Router /api/v1/embeddings [post] // @Router /api/v1/reranks [post] // @Router /api/v1/images/generations [post] @@ -989,8 +996,6 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque // @Router /api/v1/music/generations [post] // @Router /api/v1/speech/generations [post] // @Router /api/v1/voice_clone [post] -// @Router /chat/completions [post] -// @Router /v1/chat/completions [post] // @Router /embeddings [post] // @Router /v1/embeddings [post] // @Router /reranks [post] @@ -1024,6 +1029,12 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler { writeError(w, status, err.Error(), clients.ErrorCode(err)) return } + if kind == "chat.completions" || kind == "responses" { + if err := clients.ValidateOpenAIRequestParameters(kind, body); err != nil { + writeErrorWithDetails(w, http.StatusBadRequest, err.Error(), map[string]any{"param": clients.ErrorParam(err)}, clients.ErrorCode(err)) + return + } + } model := requestModelName(body) if model == "" { writeError(w, http.StatusBadRequest, "model is required") @@ -1095,7 +1106,7 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler { // @Produce text/event-stream // @Security BearerAuth // @Param X-Async header bool false "该接口忽略此参数" -// @Param input body TaskRequest true "Chat Completions 请求" +// @Param input body ChatCompletionRequest true "Chat Completions 请求" // @Success 200 {object} ChatCompletionCompatibleResponse // @Failure 400 {object} ErrorEnvelope // @Failure 401 {object} ErrorEnvelope @@ -1109,6 +1120,26 @@ func (s *Server) createAPIV1ChatCompletions() http.Handler { return s.createTask("chat.completions", false) } +// openAIChatCompletionsDoc godoc +// @Summary 创建 OpenAI Chat Completions +// @Description OpenAI-compatible Chat Completions 入口；仅接受官方字段及文档声明的 EasyAI 路由扩展，未知顶层字段返回 400 invalid_parameter。 +// @Tags chat +// @Accept json +// @Produce json +// @Produce text/event-stream +// @Security BearerAuth +// @Param input body ChatCompletionRequest true "Chat Completions 请求" +// @Success 200 {object} ChatCompletionCompatibleResponse +// @Failure 400 {object} ErrorEnvelope "invalid_parameter" +// @Failure 401 {object} ErrorEnvelope +// @Failure 402 {object} ErrorEnvelope +// @Failure 403 {object} ErrorEnvelope +// @Failure 429 {object} ErrorEnvelope +// @Failure 502 {object} ErrorEnvelope +// @Router /chat/completions [post] +// @Router /v1/chat/completions [post] +func openAIChatCompletionsDoc() {} + // openAIResponsesDoc godoc // @Summary 创建 OpenAI Responses // @Description 公开 OpenAI-compatible Responses 入口。模型声明 openai_responses 时原生转发，否则使用 Chat Completions 转换；store 缺省为 true。previous_response_id 严格绑定首次成功的平台模型和上游协议，链路不可用时不跨平台续接。未提供 previous_response_id 时由调用方管理完整状态，Gateway 以本轮 input/messages 为准且不追加本地历史。 @@ -1127,6 +1158,7 @@ func (s *Server) createAPIV1ChatCompletions() http.Handler { // @Failure 503 {object} ErrorEnvelope "response_chain_unavailable" // @Router /responses [post] // @Router /v1/responses [post] +// @Router /api/v1/responses [post] func openAIResponsesDoc() {} func (s *Server) requestExecutionContext(r *http.Request) (context.Context, context.CancelFunc) { @@ -1357,6 +1389,10 @@ func statusFromRunError(err error) int { return http.StatusServiceUnavailable case clients.ErrorCode(err) == "bad_request" || clients.ErrorCode(err) == "invalid_parameter" || clients.ErrorCode(err) == "cloned_voice_expired" || clients.ErrorCode(err) == "cloned_voice_unavailable" || clients.ErrorCode(err) == "cloned_voice_platform_unavailable" || clients.ErrorCode(err) == "unsupported_operation" || clients.ErrorCode(err) == "invalid_proxy": return http.StatusBadRequest + case store.ModelCandidateErrorCode(err) == "invalid_parameter": + return http.StatusBadRequest + case store.ModelCandidateErrorCode(err) == "model_capability_configuration_error": + return http.StatusInternalServerError case clients.ErrorCode(err) == "cloned_voice_not_found": return http.StatusNotFound case store.ModelCandidateErrorCode(err) == "platform_cooling_down" || store.ModelCandidateErrorCode(err) == "model_cooling_down": diff --git a/apps/api/internal/httpapi/keling_simulation_integration_test.go b/apps/api/internal/httpapi/keling_simulation_integration_test.go new file mode 100644 index 0000000..421ce32 --- /dev/null +++ b/apps/api/internal/httpapi/keling_simulation_integration_test.go @@ -0,0 +1,194 @@ +package httpapi + +import ( + "context" + "io" + "log/slog" + "net/http" + "net/http/httptest" + "os" + "strconv" + "strings" + "testing" + "time" + + "github.com/easyai/easyai-ai-gateway/apps/api/internal/config" + "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" +) + +func TestKeling30TurboSimulationFlow(t *testing.T) { + databaseURL := strings.TrimSpace(os.Getenv("AI_GATEWAY_TEST_DATABASE_URL")) + if databaseURL == "" { + t.Skip("set AI_GATEWAY_TEST_DATABASE_URL to run the Kling simulation integration flow") + } + + ctx := context.Background() + applyMigration(t, ctx, databaseURL) + db, err := store.Connect(ctx, databaseURL) + if err != nil { + t.Fatalf("connect store: %v", err) + } + defer db.Close() + + serverCtx, cancelServer := context.WithCancel(ctx) + defer cancelServer() + server := httptest.NewServer(NewServerWithContext(serverCtx, config.Config{ + AppEnv: "test", + HTTPAddr: ":0", + DatabaseURL: databaseURL, + IdentityMode: "hybrid", + JWTSecret: "test-secret", + CORSAllowedOrigin: "*", + }, db, slog.New(slog.NewTextHandler(io.Discard, nil)))) + defer server.Close() + + suffix := strconv.FormatInt(time.Now().UnixNano(), 10) + username := "kling_sim_" + suffix + password := "password123" + var registerResponse struct { + AccessToken string `json:"accessToken"` + } + doJSON(t, server.URL, http.MethodPost, "/api/v1/auth/register", "", map[string]any{ + "username": username, + "email": username + "@example.com", + "password": password, + }, http.StatusCreated, ®isterResponse) + + var apiKeyResponse struct { + Secret string `json:"secret"` + } + doJSON(t, server.URL, http.MethodPost, "/api/v1/api-keys", registerResponse.AccessToken, map[string]any{ + "name": "kling simulation key", + }, http.StatusCreated, &apiKeyResponse) + + if _, err := db.Pool().Exec(ctx, ` +UPDATE gateway_users +SET roles = '["admin"]'::jsonb +WHERE username = $1`, username); err != nil { + t.Fatalf("promote Kling simulation user: %v", err) + } + var loginResponse struct { + AccessToken string `json:"accessToken"` + } + doJSON(t, server.URL, http.MethodPost, "/api/v1/auth/login", "", map[string]any{ + "account": username, + "password": password, + }, http.StatusOK, &loginResponse) + + var gatewayUserID string + if err := db.Pool().QueryRow( + ctx, + `SELECT id::text FROM gateway_users WHERE username = $1`, + username, + ).Scan(&gatewayUserID); err != nil { + t.Fatalf("read Kling simulation user id: %v", err) + } + doJSON(t, server.URL, http.MethodPatch, "/api/admin/users/"+gatewayUserID+"/wallet", loginResponse.AccessToken, map[string]any{ + "currency": "resource", + "balance": 1000, + "reason": "seed Kling simulation wallet", + }, http.StatusOK, nil) + + var platform struct { + ID string `json:"id"` + } + doJSON(t, server.URL, http.MethodPost, "/api/admin/platforms", loginResponse.AccessToken, map[string]any{ + "provider": "keling", + "platformKey": "keling-simulation-" + suffix, + "name": "Kling Simulation", + "baseUrl": "https://api-beijing.klingai.com/v1", + "authType": "AccessKey-SecretKey", + "credentials": map[string]any{ + "accessKey": "legacy-ak", + "secretKey": "legacy-sk", + }, + }, http.StatusCreated, &platform) + + doJSON(t, server.URL, http.MethodPost, "/api/admin/platforms/"+platform.ID+"/models", loginResponse.AccessToken, map[string]any{ + "canonicalModelKey": "keling:kling-3.0-turbo", + "modelName": "kling-3.0-turbo", + "providerModelName": "kling-3.0-turbo", + "modelAlias": "可灵3.0 Turbo", + "modelType": []string{"video_generate", "image_to_video"}, + "displayName": "可灵3.0 Turbo", + }, http.StatusCreated, nil) + + assertKeling30TurboSimulationTask := func( + name string, + request map[string]any, + expectedModelType string, + ) { + t.Helper() + t.Run(name, func(t *testing.T) { + var response struct { + Task struct { + ID string `json:"id"` + Status string `json:"status"` + RunMode string `json:"runMode"` + ModelType string `json:"modelType"` + ResolvedModel string `json:"resolvedModel"` + Result map[string]any `json:"result"` + Metrics map[string]any `json:"metrics"` + BillingSummary map[string]any `json:"billingSummary"` + FinalChargeAmount float64 `json:"finalChargeAmount"` + ResponseDurationMS int64 `json:"responseDurationMs"` + } `json:"task"` + } + doJSON( + t, + server.URL, + http.MethodPost, + "/api/v1/videos/generations", + apiKeyResponse.Secret, + request, + http.StatusAccepted, + &response, + ) + + task := response.Task + if task.ID == "" || + task.Status != "succeeded" || + task.RunMode != "simulation" || + task.ModelType != expectedModelType || + task.ResolvedModel != "kling-3.0-turbo" { + t.Fatalf("unexpected Kling simulation task: %+v", task) + } + data, _ := task.Result["data"].([]any) + item, _ := data[0].(map[string]any) + if item["video_url"] != "/static/simulation/video.mp4" || + item["assetSource"] != "simulation" { + t.Fatalf("unexpected Kling simulation result: %+v", task.Result) + } + if task.FinalChargeAmount <= 0 || + task.BillingSummary["finalCharge"] == nil || + task.Metrics["parameterPreprocessingSummary"] == nil || + task.ResponseDurationMS <= 0 { + t.Fatalf("Kling simulation should preserve billing, preprocessing and timing: %+v", task) + } + }) + } + + assertKeling30TurboSimulationTask("text-to-video", map[string]any{ + "model": "可灵3.0 Turbo", + "runMode": "simulation", + "simulation": true, + "simulationDurationMs": 5, + "prompt": "A cinematic city reveal", + "duration": 8, + "resolution": "1080p", + "aspect_ratio": "9:16", + "audio": true, + }, "video_generate") + + assertKeling30TurboSimulationTask("image-to-video", map[string]any{ + "model": "可灵3.0 Turbo", + "runMode": "simulation", + "simulation": true, + "simulationDurationMs": 5, + "prompt": "The subject looks toward the camera", + "image": "https://example.com/first.png", + "duration": 5, + "resolution": "720p", + "audio": true, + }, "image_to_video") +} diff --git a/apps/api/internal/httpapi/openapi_models.go b/apps/api/internal/httpapi/openapi_models.go index f297a03..636b91f 100644 --- a/apps/api/internal/httpapi/openapi_models.go +++ b/apps/api/internal/httpapi/openapi_models.go @@ -16,6 +16,17 @@ type ReadyResponse struct { OK bool `json:"ok" example:"true"` } +type SkillBundleMetadataResponse struct { + Name string `json:"name" example:"ai-gateway-ops-management"` + Version string `json:"version" example:"1.0.2"` + DisplayName string `json:"displayName" example:"AI Gateway 运维管理"` + Modules []string `json:"modules" example:"model-runtime"` + FileName string `json:"fileName" example:"ai-gateway-ops-management-v1.0.2.zip"` + DownloadPath string `json:"downloadPath" example:"/api/v1/public/skills/ai-gateway-ops-management/download"` + APIDocsJSONPath string `json:"apiDocsJsonPath" example:"/api-docs-json"` + APIDocsYAMLPath string `json:"apiDocsYamlPath" example:"/api-docs-yaml"` +} + type ErrorEnvelope struct { Error ErrorPayload `json:"error"` } @@ -24,6 +35,8 @@ type ErrorPayload struct { Message string `json:"message" example:"invalid json body"` Status int `json:"status" example:"400"` Code string `json:"code,omitempty" example:"rate_limit"` + Type string `json:"type,omitempty" example:"invalid_request_error"` + Param any `json:"param,omitempty"` } type AuthResponse struct { @@ -182,16 +195,19 @@ type PricingEstimateResponse struct { type TaskRequest struct { Model string `json:"model" example:"gpt-4o-mini"` Messages []ChatMessage `json:"messages,omitempty"` - Input string `json:"input,omitempty" example:"Tell me a short story"` + Input interface{} `json:"input,omitempty"` Prompt string `json:"prompt,omitempty" example:"A watercolor robot reading a book"` Text string `json:"text,omitempty" example:"Hello from EasyAI audio synthesis."` TextFileID string `json:"text_file_id,omitempty" example:""` VoiceID string `json:"voice_id,omitempty" example:"female-shaonv"` - Stream bool `json:"stream,omitempty" example:"false"` + Stream *bool `json:"stream,omitempty" example:"false"` RunMode string `json:"runMode,omitempty" example:"simulation"` - MaxTokens int `json:"max_tokens,omitempty" example:"512"` - // ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。 - ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium"` + MaxTokens *int `json:"max_tokens,omitempty" example:"512"` + // MaxCompletionTokens includes visible output and reasoning tokens. + MaxCompletionTokens *int `json:"max_completion_tokens,omitempty" example:"512"` + MaxOutputTokens *int `json:"max_output_tokens,omitempty" example:"512"` + // ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。 + ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium" enums:"none,minimal,low,medium,high,xhigh,max"` Size string `json:"size,omitempty" example:"1024x1024"` Duration int `json:"duration,omitempty" example:"5"` Resolution string `json:"resolution,omitempty" example:"720p"` @@ -212,36 +228,88 @@ type TaskRequest struct { } type ChatCompletionRequest struct { - Model string `json:"model" example:"gpt-4o-mini"` - Messages []ChatMessage `json:"messages"` - Temperature float64 `json:"temperature,omitempty" example:"0.7"` - MaxTokens int `json:"max_tokens,omitempty" example:"512"` - // ReasoningEffort 推理强度，OpenAI-compatible 请求字段；仅支持 none、minimal、low、medium、high、xhigh。供应商自定义取值由网关按平台适配。 - ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium"` - Stream bool `json:"stream,omitempty" example:"false"` - RunMode string `json:"runMode,omitempty" example:"simulation"` + Model string `json:"model" example:"gpt-4o-mini"` + Messages []ChatMessage `json:"messages"` + Audio map[string]interface{} `json:"audio,omitempty"` + FrequencyPenalty *float64 `json:"frequency_penalty,omitempty" example:"0"` + FunctionCall interface{} `json:"function_call,omitempty"` + Functions []map[string]interface{} `json:"functions,omitempty"` + LogitBias map[string]interface{} `json:"logit_bias,omitempty"` + Logprobs *bool `json:"logprobs,omitempty"` + MaxCompletionTokens *int `json:"max_completion_tokens,omitempty" example:"512"` + MaxTokens *int `json:"max_tokens,omitempty" example:"512"` + Metadata map[string]interface{} `json:"metadata,omitempty"` + Modalities []string `json:"modalities,omitempty"` + Moderation interface{} `json:"moderation,omitempty"` + N *int `json:"n,omitempty" example:"1"` + ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty"` + Prediction interface{} `json:"prediction,omitempty"` + PresencePenalty *float64 `json:"presence_penalty,omitempty" example:"0"` + PromptCacheKey string `json:"prompt_cache_key,omitempty"` + PromptCacheOptions map[string]interface{} `json:"prompt_cache_options,omitempty"` + PromptCacheRetention string `json:"prompt_cache_retention,omitempty" enums:"in_memory,24h"` + // ReasoningEffort 推理强度，OpenAI-compatible 请求字段；支持 none、minimal、low、medium、high、xhigh、max。供应商自定义取值由网关按平台适配。 + ReasoningEffort string `json:"reasoning_effort,omitempty" example:"medium" enums:"none,minimal,low,medium,high,xhigh,max"` + ResponseFormat interface{} `json:"response_format,omitempty"` + SafetyIdentifier string `json:"safety_identifier,omitempty"` + Seed *int `json:"seed,omitempty"` + ServiceTier string `json:"service_tier,omitempty"` + Stop interface{} `json:"stop,omitempty"` + Store *bool `json:"store,omitempty"` + Stream *bool `json:"stream,omitempty" example:"false"` + StreamOptions map[string]interface{} `json:"stream_options,omitempty"` + Temperature *float64 `json:"temperature,omitempty" example:"0.7"` + ToolChoice interface{} `json:"tool_choice,omitempty"` + Tools []map[string]interface{} `json:"tools,omitempty"` + TopLogprobs *int `json:"top_logprobs,omitempty"` + TopP *float64 `json:"top_p,omitempty" example:"1"` + User string `json:"user,omitempty"` + Verbosity string `json:"verbosity,omitempty"` + WebSearchOptions map[string]interface{} `json:"web_search_options,omitempty"` + RunMode string `json:"runMode,omitempty" example:"simulation"` } type ChatMessage struct { - Role string `json:"role" example:"user"` - Content string `json:"content" example:"Hello"` + Role string `json:"role" example:"user"` + Content interface{} `json:"content,omitempty"` + Name string `json:"name,omitempty"` + ToolCallID string `json:"tool_call_id,omitempty"` + ToolCalls interface{} `json:"tool_calls,omitempty"` + FunctionCall interface{} `json:"function_call,omitempty"` } type ResponsesRequest struct { - Model string `json:"model" example:"Doubao Seed 2.0 Pro"` - Input interface{} `json:"input"` - Instructions string `json:"instructions,omitempty" example:"Answer concisely"` - PreviousResponseID string `json:"previous_response_id,omitempty" example:"resp_0123456789abcdef0123456789abcdef"` - Tools []map[string]interface{} `json:"tools,omitempty"` - ToolChoice interface{} `json:"tool_choice,omitempty"` - ParallelToolCalls bool `json:"parallel_tool_calls,omitempty" example:"true"` - MaxOutputTokens int `json:"max_output_tokens,omitempty" example:"512"` - Reasoning map[string]interface{} `json:"reasoning,omitempty"` - Text map[string]interface{} `json:"text,omitempty"` - Temperature float64 `json:"temperature,omitempty" example:"0.7"` - TopP float64 `json:"top_p,omitempty" example:"1"` - Store *bool `json:"store,omitempty"` - Stream bool `json:"stream,omitempty" example:"false"` + Model string `json:"model" example:"Doubao Seed 2.0 Pro"` + Background *bool `json:"background,omitempty"` + ContextManagement []map[string]interface{} `json:"context_management,omitempty"` + Conversation interface{} `json:"conversation,omitempty"` + Include []string `json:"include,omitempty"` + Input interface{} `json:"input"` + Instructions string `json:"instructions,omitempty" example:"Answer concisely"` + MaxOutputTokens *int `json:"max_output_tokens,omitempty" example:"512"` + MaxToolCalls *int `json:"max_tool_calls,omitempty"` + Metadata map[string]interface{} `json:"metadata,omitempty"` + Moderation interface{} `json:"moderation,omitempty"` + ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty" example:"true"` + PreviousResponseID string `json:"previous_response_id,omitempty" example:"resp_0123456789abcdef0123456789abcdef"` + Prompt interface{} `json:"prompt,omitempty"` + PromptCacheKey string `json:"prompt_cache_key,omitempty"` + PromptCacheOptions map[string]interface{} `json:"prompt_cache_options,omitempty"` + PromptCacheRetention string `json:"prompt_cache_retention,omitempty" enums:"in_memory,24h"` + Reasoning map[string]interface{} `json:"reasoning,omitempty"` + SafetyIdentifier string `json:"safety_identifier,omitempty"` + ServiceTier string `json:"service_tier,omitempty"` + Store *bool `json:"store,omitempty"` + Stream *bool `json:"stream,omitempty" example:"false"` + StreamOptions map[string]interface{} `json:"stream_options,omitempty"` + Temperature *float64 `json:"temperature,omitempty" example:"0.7"` + Text map[string]interface{} `json:"text,omitempty"` + ToolChoice interface{} `json:"tool_choice,omitempty"` + Tools []map[string]interface{} `json:"tools,omitempty"` + TopLogprobs *int `json:"top_logprobs,omitempty"` + TopP *float64 `json:"top_p,omitempty" example:"1"` + Truncation string `json:"truncation,omitempty"` + User string `json:"user,omitempty"` } type ResponsesCompatibleResponse struct { diff --git a/apps/api/internal/httpapi/response.go b/apps/api/internal/httpapi/response.go index 27a144c..504cf57 100644 --- a/apps/api/internal/httpapi/response.go +++ b/apps/api/internal/httpapi/response.go @@ -25,6 +25,12 @@ func writeErrorWithDetails(w http.ResponseWriter, status int, message string, de if len(codes) > 0 { if code := strings.TrimSpace(codes[0]); code != "" { errorPayload["code"] = code + if code == "invalid_parameter" || code == "unsupported_response_parameter" { + errorPayload["type"] = "invalid_request_error" + if _, ok := details["param"]; !ok { + errorPayload["param"] = nil + } + } } } for key, value := range details { diff --git a/apps/api/internal/httpapi/server.go b/apps/api/internal/httpapi/server.go index d6bf1e7..ab2bd16 100644 --- a/apps/api/internal/httpapi/server.go +++ b/apps/api/internal/httpapi/server.go @@ -128,6 +128,10 @@ func NewServerWithContext(ctx context.Context, cfg config.Config, db *store.Stor mux.HandleFunc("GET /static/simulation/{asset}", serveSimulationAsset) mux.HandleFunc("GET /static/generated/{asset}", server.serveGeneratedStaticAsset) mux.HandleFunc("GET /static/uploaded/{asset}", server.serveUploadedStaticAsset) + mux.HandleFunc("GET /api-docs-json", server.apiDocsJSON) + mux.HandleFunc("GET /api-docs-yaml", server.apiDocsYAML) + mux.HandleFunc("GET /api/v1/public/skills/ai-gateway-ops-management/metadata", server.getOpsManagementSkillMetadata) + mux.HandleFunc("GET /api/v1/public/skills/ai-gateway-ops-management/download", server.downloadOpsManagementSkill) mux.Handle("POST /api/v1/auth/register", server.auth.Require(auth.PermissionPublic, http.HandlerFunc(server.register))) mux.Handle("POST /api/v1/auth/login", server.auth.Require(auth.PermissionPublic, http.HandlerFunc(server.login))) diff --git a/apps/api/internal/runner/output_token_limit.go b/apps/api/internal/runner/output_token_limit.go new file mode 100644 index 0000000..329e546 --- /dev/null +++ b/apps/api/internal/runner/output_token_limit.go @@ -0,0 +1,232 @@ +package runner + +import ( + "fmt" + "math" + "strings" + + "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" +) + +const ( + volcesOutputTokenThreshold = 10240 + volcesOutputCapabilityErrorCode = "model_capability_configuration_error" + volcesOutputInvalidParameterCode = "invalid_parameter" +) + +type outputTokenLimitProcessor struct{} + +func (outputTokenLimitProcessor) Name() string { return "OutputTokenLimitProcessor" } + +func (outputTokenLimitProcessor) ShouldProcess(_ map[string]any, modelType string, context *paramProcessContext) bool { + return context != nil && isOpenAITextGenerationKind(context.kind) && isTextOutputModelType(modelType) && isVolcesCandidate(context.candidate) +} + +func (outputTokenLimitProcessor) Process(params map[string]any, modelType string, context *paramProcessContext) bool { + modelMax, sourceType, capabilityValue, ok := candidateMaxOutputTokens(context.candidate, modelType) + path := capabilityPath(sourceType, "max_output_tokens") + if !ok { + return context.reject( + "OutputTokenLimitProcessor", + outputTokenParameter(context.kind), + nil, + "火山引擎文本候选未配置正整数 max_output_tokens，已禁止执行该候选。", + path, + capabilityValue, + ) + } + + if context.kind == "chat.completions" { + if value, explicit := nonNullParameter(params, "max_tokens"); explicit { + if parsed, valid := positiveInteger(value); !valid || parsed > modelMax { + return context.reject("OutputTokenLimitProcessor", "max_tokens", value, fmt.Sprintf("max_tokens must be a positive integer no greater than the selected Volcengine model limit (%d)", modelMax), path, capabilityValue) + } + return true + } + if _, explicit := nonNullParameter(params, "max_completion_tokens"); explicit { + return true + } + value := defaultVolcesOutputTokens(modelMax) + params["max_tokens"] = value + context.recordChange( + "OutputTokenLimitProcessor", "set", "max_tokens", nil, value, + fmt.Sprintf("火山候选未显式设置输出上限：floor(%d/3)=%d，阈值=%d，注入候选级默认值。", modelMax, modelMax/3, volcesOutputTokenThreshold), + path, capabilityValue, + ) + return true + } + + if value, explicit := nonNullParameter(params, "max_output_tokens"); explicit { + if parsed, valid := positiveInteger(value); !valid || parsed > modelMax { + return context.reject("OutputTokenLimitProcessor", "max_output_tokens", value, fmt.Sprintf("max_output_tokens must be a positive integer no greater than the selected Volcengine model limit (%d)", modelMax), path, capabilityValue) + } + return true + } + value := defaultVolcesOutputTokens(modelMax) + params["max_output_tokens"] = value + context.recordChange( + "OutputTokenLimitProcessor", "set", "max_output_tokens", nil, value, + fmt.Sprintf("火山候选未显式设置输出上限：floor(%d/3)=%d，阈值=%d，注入候选级默认值。", modelMax, modelMax/3, volcesOutputTokenThreshold), + path, capabilityValue, + ) + return true +} + +func filterRuntimeCandidatesByOutputTokens(kind string, requestedModel string, modelType string, body map[string]any, candidates []store.RuntimeModelCandidate) ([]store.RuntimeModelCandidate, map[string]any, error) { + if !isOpenAITextGenerationKind(kind) || !isTextOutputModelType(modelType) || len(candidates) == 0 { + return candidates, nil, nil + } + filtered := make([]store.RuntimeModelCandidate, 0, len(candidates)) + rejected := make([]map[string]any, 0) + invalidExplicit := false + for _, candidate := range candidates { + if !isVolcesCandidate(candidate) { + filtered = append(filtered, candidate) + continue + } + modelMax, sourceType, raw, configured := candidateMaxOutputTokens(candidate, modelType) + detail := map[string]any{ + "platformId": candidate.PlatformID, "platformKey": candidate.PlatformKey, "provider": candidate.Provider, + "platformModelId": candidate.PlatformModelID, "providerModelName": candidate.ProviderModelName, + "modelType": modelType, "capabilityPath": capabilityPath(sourceType, "max_output_tokens"), "capabilityValue": raw, + } + if !configured { + detail["reason"] = "max_output_tokens_missing" + rejected = append(rejected, detail) + continue + } + if parameter, value, explicit := explicitOutputTokenParameter(kind, body); explicit { + parsed, valid := positiveInteger(value) + if !valid || (parameter != "max_completion_tokens" && parsed > modelMax) { + detail["reason"] = "requested_output_tokens_exceed_capability" + detail["parameter"] = parameter + detail["requestedValue"] = value + invalidExplicit = true + rejected = append(rejected, detail) + continue + } + } + filtered = append(filtered, candidate) + } + if len(rejected) == 0 { + return filtered, nil, nil + } + summary := map[string]any{ + "filter": "volces_output_token_limit", "kind": kind, "requestedModel": requestedModel, "modelType": modelType, + "candidateCount": len(candidates), "supportedCandidateCount": len(filtered), "filteredCandidateCount": len(rejected), + "threshold": volcesOutputTokenThreshold, "formula": "third=floor(modelMaxOutputTokens/3); default=third>=10240?third:modelMaxOutputTokens", + "rejectedCandidates": rejected, + } + if len(filtered) > 0 { + return filtered, summary, nil + } + code := volcesOutputCapabilityErrorCode + message := "所有火山引擎文本候选都缺少有效的 max_output_tokens 能力配置" + if invalidExplicit { + code = volcesOutputInvalidParameterCode + message = "请求的输出 token 上限超过所有可用火山引擎候选的模型能力" + } + summary["code"] = code + return nil, summary, &store.ModelCandidateUnavailableError{Code: code, Message: message, Details: summary} +} + +func defaultVolcesOutputTokens(modelMax int) int { + third := modelMax / 3 + if third >= volcesOutputTokenThreshold { + return third + } + return modelMax +} + +func isVolcesCandidate(candidate store.RuntimeModelCandidate) bool { + provider := strings.ToLower(strings.TrimSpace(candidate.Provider)) + baseURL := strings.ToLower(strings.TrimSpace(candidate.BaseURL)) + return provider == "volces-openai" || strings.Contains(baseURL, "volces.com") || strings.Contains(baseURL, "byteplus.com") +} + +func candidateMaxOutputTokens(candidate store.RuntimeModelCandidate, modelType string) (int, string, any, bool) { + capabilities := effectiveModelCapability(candidate) + seen := map[string]struct{}{} + for _, candidateType := range []string{candidate.ModelType, modelType, "text_generate"} { + candidateType = strings.TrimSpace(candidateType) + if candidateType == "" { + continue + } + if _, ok := seen[candidateType]; ok { + continue + } + seen[candidateType] = struct{}{} + capability := capabilityForType(capabilities, candidateType) + if capability == nil { + continue + } + raw, exists := capability["max_output_tokens"] + if !exists { + continue + } + value, ok := positiveInteger(raw) + return value, candidateType, raw, ok + } + return 0, firstNonEmptyString(candidate.ModelType, modelType, "text_generate"), nil, false +} + +func positiveInteger(value any) (int, bool) { + number := floatFromAny(value) + if number <= 0 || math.Trunc(number) != number || number > float64(math.MaxInt) { + return 0, false + } + return int(number), true +} + +func nonNullParameter(body map[string]any, key string) (any, bool) { + value, ok := body[key] + return value, ok && value != nil +} + +func explicitOutputTokenParameter(kind string, body map[string]any) (string, any, bool) { + if kind == "responses" { + value, ok := nonNullParameter(body, "max_output_tokens") + return "max_output_tokens", value, ok + } + if value, ok := nonNullParameter(body, "max_tokens"); ok { + return "max_tokens", value, true + } + value, ok := nonNullParameter(body, "max_completion_tokens") + return "max_completion_tokens", value, ok +} + +func outputTokenParameter(kind string) string { + if kind == "responses" { + return "max_output_tokens" + } + return "max_tokens" +} + +func isOpenAITextGenerationKind(kind string) bool { + return kind == "chat.completions" || kind == "responses" +} + +func isTextOutputModelType(modelType string) bool { + switch strings.TrimSpace(modelType) { + case "", "text_generate", "chat", "responses", "text": + return true + default: + return false + } +} + +func mergeCandidateFilterSummaries(summaries ...map[string]any) map[string]any { + nonEmpty := make([]any, 0, len(summaries)) + for _, summary := range summaries { + if len(summary) > 0 { + nonEmpty = append(nonEmpty, summary) + } + } + if len(nonEmpty) == 0 { + return nil + } + if len(nonEmpty) == 1 { + return nonEmpty[0].(map[string]any) + } + return map[string]any{"filters": nonEmpty} +} diff --git a/apps/api/internal/runner/output_token_limit_test.go b/apps/api/internal/runner/output_token_limit_test.go new file mode 100644 index 0000000..37262d4 --- /dev/null +++ b/apps/api/internal/runner/output_token_limit_test.go @@ -0,0 +1,113 @@ +package runner + +import ( + "testing" + + "github.com/easyai/easyai-ai-gateway/apps/api/internal/store" +) + +func volcTextCandidate(maxOutput any) store.RuntimeModelCandidate { + capability := map[string]any{} + if maxOutput != nil { + capability["max_output_tokens"] = maxOutput + } + return store.RuntimeModelCandidate{ + Provider: "volces-openai", BaseURL: "https://ark.cn-beijing.volces.com/api/v3", + ModelType: "text_generate", ProviderModelName: "demo", + Capabilities: map[string]any{"text_generate": capability}, + } +} + +func TestDefaultVolcesOutputTokens(t *testing.T) { + tests := []struct { + name string + max int + want int + }{ + {name: "128K", max: 131072, want: 43690}, + {name: "32K", max: 32768, want: 10922}, + {name: "24K below threshold", max: 24576, want: 24576}, + {name: "threshold exact", max: 30720, want: 10240}, + {name: "threshold minus one", max: 30719, want: 30719}, + {name: "floor", max: 131071, want: 43690}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + if got := defaultVolcesOutputTokens(test.max); got != test.want { + t.Fatalf("defaultVolcesOutputTokens(%d)=%d, want %d", test.max, got, test.want) + } + }) + } +} + +func TestVolcesOutputProcessorInjectsCandidateSpecificDefaults(t *testing.T) { + chat := preprocessRequestWithLog("chat.completions", map[string]any{"messages": []any{}, "max_tokens": nil}, volcTextCandidate(131072)) + if chat.Err != nil || chat.Body["max_tokens"] != 43690 { + t.Fatalf("unexpected Chat preprocessing: body=%+v err=%v", chat.Body, chat.Err) + } + if len(chat.Log.Changes) != 1 || chat.Log.Changes[0].CapabilityPath != "capabilities.text_generate.max_output_tokens" { + t.Fatalf("expected auditable capability source, got %+v", chat.Log.Changes) + } + + responses := preprocessRequestWithLog("responses", map[string]any{"input": "hello", "max_output_tokens": nil}, volcTextCandidate(24576)) + if responses.Err != nil || responses.Body["max_output_tokens"] != 24576 { + t.Fatalf("unexpected Responses preprocessing: body=%+v err=%v", responses.Body, responses.Err) + } +} + +func TestVolcesOutputProcessorPreservesExplicitLimits(t *testing.T) { + for _, body := range []map[string]any{ + {"messages": []any{}, "max_tokens": 1234}, + {"messages": []any{}, "max_completion_tokens": 2345}, + {"messages": []any{}, "max_tokens": 1234, "max_completion_tokens": 2345}, + } { + result := preprocessRequestWithLog("chat.completions", body, volcTextCandidate(32768)) + if result.Err != nil || len(result.Log.Changes) != 0 { + t.Fatalf("explicit Chat limit should remain unchanged: body=%+v err=%v changes=%+v", result.Body, result.Err, result.Log.Changes) + } + } + result := preprocessRequestWithLog("responses", map[string]any{"input": "hello", "max_output_tokens": 3456}, volcTextCandidate(32768)) + if result.Err != nil || result.Body["max_output_tokens"] != 3456 || len(result.Log.Changes) != 0 { + t.Fatalf("explicit Responses limit should remain unchanged: %+v", result) + } +} + +func TestVolcesOutputCandidateFilterSupportsFailover(t *testing.T) { + missing := volcTextCandidate(nil) + missing.PlatformID = "missing" + valid := volcTextCandidate(32768) + valid.PlatformID = "valid" + filtered, summary, err := filterRuntimeCandidatesByOutputTokens("chat.completions", "demo", "text_generate", map[string]any{"messages": []any{}}, []store.RuntimeModelCandidate{missing, valid}) + if err != nil || len(filtered) != 1 || filtered[0].PlatformID != "valid" { + t.Fatalf("expected missing capability candidate to be skipped: filtered=%+v summary=%+v err=%v", filtered, summary, err) + } + result := preprocessRequestWithLog("chat.completions", map[string]any{"messages": []any{}}, filtered[0]) + if result.Body["max_tokens"] != 10922 { + t.Fatalf("failover candidate must recalculate its own default, got %+v", result.Body) + } +} + +func TestVolcesOutputCandidateFilterRejectsMissingAndExceededCapabilities(t *testing.T) { + _, _, err := filterRuntimeCandidatesByOutputTokens("responses", "demo", "text_generate", map[string]any{"input": "hello"}, []store.RuntimeModelCandidate{volcTextCandidate(nil)}) + if store.ModelCandidateErrorCode(err) != volcesOutputCapabilityErrorCode { + t.Fatalf("expected capability configuration error, got %v", err) + } + _, _, err = filterRuntimeCandidatesByOutputTokens("chat.completions", "demo", "text_generate", map[string]any{"messages": []any{}, "max_tokens": 32769}, []store.RuntimeModelCandidate{volcTextCandidate(32768)}) + if store.ModelCandidateErrorCode(err) != volcesOutputInvalidParameterCode { + t.Fatalf("expected invalid_parameter for explicit limit, got %v", err) + } +} + +func TestNonVolcesOutputProcessorDoesNotInject(t *testing.T) { + candidate := volcTextCandidate(131072) + candidate.Provider = "openai" + candidate.BaseURL = "https://api.openai.com/v1" + chat := preprocessRequestWithLog("chat.completions", map[string]any{"messages": []any{}}, candidate) + if _, ok := chat.Body["max_tokens"]; ok { + t.Fatalf("non-Volcengine Chat candidate must remain unchanged: %+v", chat.Body) + } + responses := preprocessRequestWithLog("responses", map[string]any{"input": "hello"}, candidate) + if _, ok := responses.Body["max_output_tokens"]; ok { + t.Fatalf("non-Volcengine Responses candidate must remain unchanged: %+v", responses.Body) + } +} diff --git a/apps/api/internal/runner/param_processor.go b/apps/api/internal/runner/param_processor.go index f1216bf..18a42c1 100644 --- a/apps/api/internal/runner/param_processor.go +++ b/apps/api/internal/runner/param_processor.go @@ -55,6 +55,7 @@ type parameterPreprocessChange struct { func NewParamProcessorChain() ParamProcessorChain { return ParamProcessorChain{ processors: []paramProcessor{ + outputTokenLimitProcessor{}, resolutionNormalizeProcessor{}, aspectRatioProcessor{}, imageSizeProcessor{}, diff --git a/apps/api/internal/runner/pricing.go b/apps/api/internal/runner/pricing.go index f5adbd5..abda6fb 100644 --- a/apps/api/internal/runner/pricing.go +++ b/apps/api/internal/runner/pricing.go @@ -28,6 +28,10 @@ func (s *Service) Estimate(ctx context.Context, kind string, model string, body if err != nil { return EstimateResult{}, err } + candidates, _, err = filterRuntimeCandidatesByOutputTokens(kind, model, modelType, body, candidates) + if err != nil { + return EstimateResult{}, err + } candidate := candidates[0] body = preprocessRequest(kind, body, candidate) items := s.estimatedBillings(ctx, user, kind, body, candidate) diff --git a/apps/api/internal/runner/queue_worker.go b/apps/api/internal/runner/queue_worker.go index 040d3ba..2b3e8b7 100644 --- a/apps/api/internal/runner/queue_worker.go +++ b/apps/api/internal/runner/queue_worker.go @@ -88,7 +88,10 @@ func (s *Service) startRiverQueue(ctx context.Context) error { Queues: map[string]river.QueueConfig{ asyncTaskQueueName: {MaxWorkers: 32}, }, - RescueStuckJobsAfter: 30 * time.Second, + // Provider-backed media jobs commonly poll for 10-20 minutes. River may + // execute a still-running job again once this window elapses, so keep the + // rescue horizon above the longest configured provider poll timeout. + RescueStuckJobsAfter: time.Hour, TestOnly: s.cfg.AppEnv == "test", Workers: workers, }) diff --git a/apps/api/internal/runner/service.go b/apps/api/internal/runner/service.go index fb0409c..6461363 100644 --- a/apps/api/internal/runner/service.go +++ b/apps/api/internal/runner/service.go @@ -230,6 +230,22 @@ func (s *Service) execute(ctx context.Context, task store.GatewayTask, user *aut } return Result{Task: failed, Output: failed.Result}, err } + var outputTokenFilterSummary map[string]any + candidates, outputTokenFilterSummary, err = filterRuntimeCandidatesByOutputTokens(task.Kind, task.Model, modelType, body, candidates) + candidateFilterSummary = mergeCandidateFilterSummaries(candidateFilterSummary, outputTokenFilterSummary) + if err != nil { + candidateFilterMetrics := candidateCapabilityFilterMetrics(candidateFilterSummary) + s.recordFailedAttempt(ctx, failedAttemptRecord{ + Task: task, Body: body, AttemptNo: task.AttemptCount + 1, Code: store.ModelCandidateErrorCode(err), Cause: err, + Simulated: task.RunMode == "simulation", Scope: "candidate_output_token_filter", Reason: store.ModelCandidateErrorCode(err), + ExtraMetrics: []map[string]any{candidateFilterMetrics}, ModelType: modelType, + }) + failed, finishErr := s.failTask(ctx, task.ID, store.ModelCandidateErrorCode(err), err.Error(), task.RunMode == "simulation", err, candidateFilterMetrics) + if finishErr != nil { + return Result{}, finishErr + } + return Result{Task: failed, Output: failed.Result}, err + } if task.Kind == "responses" { candidates, err = prepareResponseCandidates(candidates, responseExecution) if err != nil { @@ -839,7 +855,7 @@ func (s *Service) runCandidate(ctx context.Context, task store.GatewayTask, user } func (s *Service) recordTaskParameterPreprocessing(ctx context.Context, taskID string, attemptID string, attemptNo int, candidate store.RuntimeModelCandidate, log parameterPreprocessingLog) error { - if skipTaskParameterPreprocessingLog(log.ModelType) { + if skipTaskParameterPreprocessingLog(log.ModelType) && !log.Changed { return nil } _, err := s.store.CreateTaskParamPreprocessingLog(ctx, store.CreateTaskParamPreprocessingLogInput{ @@ -1348,10 +1364,22 @@ func validateRequest(kind string, body map[string]any) error { if err := clients.ValidateOpenAIReasoningEffort(body["reasoning_effort"]); err != nil { return err } + for _, key := range []string{"max_tokens", "max_completion_tokens"} { + if value, explicit := nonNullParameter(body, key); explicit { + if _, ok := positiveInteger(value); !ok { + return &clients.ClientError{Code: "invalid_parameter", Message: key + " must be a positive integer", Param: key, StatusCode: 400, Retryable: false} + } + } + } case "responses": if body["input"] == nil && body["messages"] == nil { return errors.New("input or messages is required") } + if value, explicit := nonNullParameter(body, "max_output_tokens"); explicit { + if _, ok := positiveInteger(value); !ok { + return &clients.ClientError{Code: "invalid_parameter", Message: "max_output_tokens must be a positive integer", Param: "max_output_tokens", StatusCode: 400, Retryable: false} + } + } case "embeddings": if body["input"] == nil { return errors.New("input is required") diff --git a/apps/api/internal/runner/service_test.go b/apps/api/internal/runner/service_test.go index db21854..ce99869 100644 --- a/apps/api/internal/runner/service_test.go +++ b/apps/api/internal/runner/service_test.go @@ -16,7 +16,7 @@ func (namedClient) Run(context.Context, clients.Request) (clients.Response, erro } func TestValidateRequestAcceptsOpenAIReasoningEffort(t *testing.T) { - for _, effort := range []string{"none", "minimal", "low", "medium", "high", "xhigh"} { + for _, effort := range []string{"none", "minimal", "low", "medium", "high", "xhigh", "max"} { t.Run(effort, func(t *testing.T) { err := validateRequest("chat.completions", map[string]any{ "messages": []any{map[string]any{"role": "user", "content": "ping"}}, @@ -30,7 +30,7 @@ func TestValidateRequestAcceptsOpenAIReasoningEffort(t *testing.T) { } func TestValidateRequestRejectsNonOpenAIReasoningEffort(t *testing.T) { - for _, effort := range []string{"max", "auto"} { + for _, effort := range []string{"auto"} { t.Run(effort, func(t *testing.T) { err := validateRequest("chat.completions", map[string]any{ "messages": []any{map[string]any{"role": "user", "content": "ping"}}, diff --git a/apps/api/internal/skillbundle/bundle.go b/apps/api/internal/skillbundle/bundle.go new file mode 100644 index 0000000..e87587b --- /dev/null +++ b/apps/api/internal/skillbundle/bundle.go @@ -0,0 +1,122 @@ +package skillbundle + +import ( + "archive/zip" + "bytes" + "embed" + "encoding/json" + "fmt" + "io/fs" + "path" + "regexp" + "sort" + "strings" + "time" +) + +const ( + Name = "ai-gateway-ops-management" + DisplayName = "AI Gateway 运维管理" +) + +const bundleRoot = "content/skills/" + Name + +var semverPattern = regexp.MustCompile(`^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$`) + +//go:embed content/skills/ai-gateway-ops-management +var bundleFS embed.FS + +type Metadata struct { + Name string `json:"name"` + Version string `json:"version"` + Modules []string `json:"modules"` +} + +func LoadMetadata() (Metadata, error) { + raw, err := bundleFS.ReadFile(bundleRoot + "/skill.json") + if err != nil { + return Metadata{}, fmt.Errorf("read bundled skill metadata: %w", err) + } + var metadata Metadata + if err := json.Unmarshal(raw, &metadata); err != nil { + return Metadata{}, fmt.Errorf("parse bundled skill metadata: %w", err) + } + if metadata.Name != Name { + return Metadata{}, fmt.Errorf("bundled skill metadata name must be %q", Name) + } + if !semverPattern.MatchString(metadata.Version) { + return Metadata{}, fmt.Errorf("bundled skill metadata version %q is not semver", metadata.Version) + } + if len(metadata.Modules) == 0 { + return Metadata{}, fmt.Errorf("bundled skill metadata modules must not be empty") + } + seen := make(map[string]struct{}, len(metadata.Modules)) + for _, module := range metadata.Modules { + module = strings.TrimSpace(module) + if module == "" { + return Metadata{}, fmt.Errorf("bundled skill metadata module must not be empty") + } + if _, exists := seen[module]; exists { + return Metadata{}, fmt.Errorf("bundled skill metadata module %q is duplicated", module) + } + seen[module] = struct{}{} + } + if _, err := bundleFS.ReadFile(bundleRoot + "/SKILL.md"); err != nil { + return Metadata{}, fmt.Errorf("read bundled SKILL.md: %w", err) + } + return metadata, nil +} + +func FileName(metadata Metadata) string { + return fmt.Sprintf("%s-v%s.zip", metadata.Name, metadata.Version) +} + +func BuildArchive() ([]byte, error) { + if _, err := LoadMetadata(); err != nil { + return nil, err + } + files := make([]string, 0) + if err := fs.WalkDir(bundleFS, bundleRoot, func(filePath string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if entry.IsDir() { + return nil + } + relativePath := strings.TrimPrefix(filePath, bundleRoot+"/") + if relativePath == "" || path.IsAbs(relativePath) || path.Clean(relativePath) != relativePath || strings.HasPrefix(relativePath, "../") { + return fmt.Errorf("unsafe bundled skill path %q", relativePath) + } + files = append(files, relativePath) + return nil + }); err != nil { + return nil, fmt.Errorf("walk bundled skill: %w", err) + } + sort.Strings(files) + + var output bytes.Buffer + archive := zip.NewWriter(&output) + fixedTime := time.Date(2000, time.January, 1, 0, 0, 0, 0, time.UTC) + for _, relativePath := range files { + raw, err := bundleFS.ReadFile(bundleRoot + "/" + relativePath) + if err != nil { + _ = archive.Close() + return nil, fmt.Errorf("read bundled skill file %q: %w", relativePath, err) + } + header := &zip.FileHeader{Name: relativePath, Method: zip.Deflate} + header.SetModTime(fixedTime) + writer, err := archive.CreateHeader(header) + if err != nil { + _ = archive.Close() + return nil, fmt.Errorf("create bundled skill archive entry %q: %w", relativePath, err) + } + if _, err := writer.Write(raw); err != nil { + _ = archive.Close() + return nil, fmt.Errorf("write bundled skill archive entry %q: %w", relativePath, err) + } + } + if err := archive.Close(); err != nil { + return nil, fmt.Errorf("close bundled skill archive: %w", err) + } + return output.Bytes(), nil +} diff --git a/apps/api/internal/skillbundle/bundle_test.go b/apps/api/internal/skillbundle/bundle_test.go new file mode 100644 index 0000000..9e773b4 --- /dev/null +++ b/apps/api/internal/skillbundle/bundle_test.go @@ -0,0 +1,95 @@ +package skillbundle + +import ( + "archive/zip" + "bytes" + "io" + "slices" + "strings" + "testing" +) + +func TestLoadMetadata(t *testing.T) { + metadata, err := LoadMetadata() + if err != nil { + t.Fatalf("load metadata: %v", err) + } + if metadata.Name != Name || metadata.Version != "1.0.2" { + t.Fatalf("unexpected metadata: %+v", metadata) + } + if !slices.Equal(metadata.Modules, []string{"model-runtime"}) { + t.Fatalf("unexpected modules: %+v", metadata.Modules) + } + if FileName(metadata) != "ai-gateway-ops-management-v1.0.2.zip" { + t.Fatalf("unexpected file name: %s", FileName(metadata)) + } +} + +func TestBuildArchiveContainsOperationsSkill(t *testing.T) { + raw, err := BuildArchive() + if err != nil { + t.Fatalf("build archive: %v", err) + } + archive, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw))) + if err != nil { + t.Fatalf("open archive: %v", err) + } + files := make(map[string]*zip.File, len(archive.File)) + for _, file := range archive.File { + files[file.Name] = file + if strings.HasPrefix(file.Name, "/") || strings.Contains(file.Name, "..") { + t.Fatalf("unsafe archive path: %q", file.Name) + } + } + expected := []string{ + "SKILL.md", + "agents/openai.yaml", + "skill.json", + "references/api-discovery-and-safety.md", + "references/model-providers-and-base-models.md", + "references/model-pricing-and-policies.md", + "references/model-billing-configuration-and-estimation.md", + "references/model-platforms-and-bindings.md", + "references/model-universal-platforms.md", + "references/model-acceptance-runbook.md", + } + for _, name := range expected { + if files[name] == nil { + t.Fatalf("archive missing %q; files=%v", name, archiveFileNames(archive.File)) + } + } + skillFile, err := files["SKILL.md"].Open() + if err != nil { + t.Fatalf("open SKILL.md: %v", err) + } + defer skillFile.Close() + skillContent, err := io.ReadAll(skillFile) + if err != nil { + t.Fatalf("read SKILL.md: %v", err) + } + if !strings.Contains(string(skillContent), "name: "+Name) { + t.Fatalf("SKILL.md frontmatter has unexpected name") + } + billingFile, err := files["references/model-billing-configuration-and-estimation.md"].Open() + if err != nil { + t.Fatalf("open billing reference: %v", err) + } + defer billingFile.Close() + billingContent, err := io.ReadAll(billingFile) + if err != nil { + t.Fatalf("read billing reference: %v", err) + } + for _, required := range []string{"/api/v1/pricing/estimate", "finalChargeAmount", "transactionType=task_billing"} { + if !strings.Contains(string(billingContent), required) { + t.Fatalf("billing reference missing %q", required) + } + } +} + +func archiveFileNames(files []*zip.File) []string { + names := make([]string, 0, len(files)) + for _, file := range files { + names = append(names, file.Name) + } + return names +} diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/SKILL.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/SKILL.md new file mode 100644 index 0000000..169d4c0 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/SKILL.md @@ -0,0 +1,55 @@ +--- +name: ai-gateway-ops-management +description: Operate and verify EasyAI AI Gateway administration capabilities. Use when Codex or an Agent needs to inspect, create, update, disable, restore, or troubleshoot AI Gateway providers, base models, pricing and billing configuration, price estimates and wallet deduction reconciliation, runtime policies, runner policies, integration platforms, platform-model bindings, or universal custom-script platforms; also use this skill as the extensible entry point for future AI Gateway operations modules. +--- + +# AI Gateway Operations Management + +Use this skill to operate AI Gateway administration APIs through documented, evidence-first workflows. + +## Operating Rules + +- Obtain the Gateway API base URL and an administrator JWT before calling management APIs. Admin APIs reject `sk-*` API keys. +- Read `references/api-discovery-and-safety.md` before any write operation. +- Select only the references for the requested module. Do not load unrelated future operations modules. +- Read current state before changing it. Treat PATCH bodies as complete resource configurations unless the reference explicitly says otherwise. +- Never write credentials, tokens, script `authValues`, raw upstream responses, or other secrets into Skill files, logs, commands shown to users, or final summaries. +- Execute ordinary creates and updates only when the user requested the change. Before DELETE, full replacement, bulk reset, platform disablement, or credential clearing, show the current snapshot and impact and obtain explicit confirmation. +- 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 `/api-docs-json`; continue only when path, method, schema, authentication, permission, and side effects are unambiguous. + +## Module Routing + +### Model Runtime + +Use these references for the current v1 module: + +- `references/model-providers-and-base-models.md`: provider catalog and base-model lifecycle. +- `references/model-pricing-and-policies.md`: pricing rule sets, runtime policy sets, runner policy, priority, and recovery. +- `references/model-billing-configuration-and-estimation.md`: effective billing configuration, price-estimate calls, simulation/real charge comparison, and wallet reconciliation. +- `references/model-platforms-and-bindings.md`: integration platforms, credentials, platform-model upsert, replacement, and deletion. +- `references/model-universal-platforms.md`: `universal` custom platform triage, configuration, script contracts, and examples. +- `references/model-acceptance-runbook.md`: read-back, catalog, simulation, runtime, billing, and rollback verification. + +## Standard Workflow + +1. Read `references/api-discovery-and-safety.md` and confirm the API base URL, identity mode, administrator JWT, target documentation, and required credentials. +2. Read the current provider, base-model, pricing, policy, platform, and platform-model records relevant to the request. +3. Reuse an existing pricing rule when its base prices and calculators, combined with the effective platform or platform-model discount, produce the required price. Create a pricing rule only when that combination cannot represent the target. +4. Reuse an existing runtime policy set when its limits, scopes, retry, auto-disable, and degradation behavior match the requirement. Create a policy only for a real semantic difference. +5. Classify the upstream protocol against existing platforms and clients. If compatible, keep the existing `specType` and change only instance configuration such as `baseUrl`, credentials, and bindings. Use `universal` only for an unsupported protocol. +6. Reuse the base model across platforms. Put a platform-specific upstream invocation name in the platform-model `providerModelName`; do not duplicate the base model just because providers use different names. +7. Apply the minimum changes in dependency order: provider, base model, pricing/policy, platform, platform-model binding. +8. Read every changed resource back and verify the effective model catalog. +9. For billing work, read `references/model-billing-configuration-and-estimation.md`, call `/api/v1/pricing/estimate` with the same user identity and request parameters intended for execution, and reconcile the returned candidate, line items, discounts, quantities, and total. +10. Run a simulation or approved real request only after the estimate is accepted. Inspect task billing and wallet transactions; do not assume simulation is free or side-effect-free. +11. Report reused and created resource IDs, effective pricing evidence, protocol-fit evidence, verification results, unresolved risks, and whether the Swagger fallback was used, without exposing secrets. + +## Extending This Skill + +- Add future modules as one-level files under `references/` with stable prefixes such as `storage-`, `runtime-`, `identity-`, or `network-`. +- Add the module to this routing section and to `skill.json`. +- Increment the `skill.json` version whenever downloadable contents change. +- Keep the same skill name and public download route. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/agents/openai.yaml b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/agents/openai.yaml new file mode 100644 index 0000000..ae15f91 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "AI Gateway 运维管理" + short_description: "管理 AI Gateway 模型、平台、定价与运行策略" + default_prompt: "Use $ai-gateway-ops-management to inspect and safely operate the AI Gateway administration APIs." diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/api-discovery-and-safety.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/api-discovery-and-safety.md new file mode 100644 index 0000000..c033f39 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/api-discovery-and-safety.md @@ -0,0 +1,73 @@ +# API Discovery and Safety + +## Required Inputs + +- Gateway API base URL. When using the bundled Web deployment this commonly includes `/gateway-api`; direct API access commonly uses port `8088`. +- Administrator JWT with the `manager` or `admin` role. +- Target provider documentation and authorization material. +- Clear requested outcome and whether real upstream calls are allowed. + +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_ADMIN_TOKEN='' +``` + +## Authentication + +Management endpoints under `/api/admin/*` accept administrator user credentials only. A local or server-main `sk-*` API key is rejected even if it has broad model scopes. + +For standalone or hybrid deployments, local login can return a JWT: + +```bash +curl --fail-with-body \ + -H 'Content-Type: application/json' \ + -d '{"account":"","password":""}' \ + "$GATEWAY_BASE_URL/api/v1/auth/login" +``` + +Do not use local login when the deployment requires OIDC or server-main identity. Obtain the deployment's administrator access token instead. + +Verify identity and role before writes: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/v1/me" +``` + +## Request Pattern + +Use a temporary request file or a carefully quoted inline body without printing secrets: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -X POST \ + -d '' \ + "$GATEWAY_BASE_URL/api/admin/" +``` + +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. + +## High-impact Operations + +Obtain explicit confirmation after showing the current snapshot and impact before: + +- Any DELETE request. +- `POST /api/admin/catalog/base-models/reset-all`. +- `PUT /api/admin/platforms/{platformID}/models`. +- Changing a platform status to `disabled`. +- Sending an empty `credentials` object to clear stored credentials. +- Replacing pricing rules or policy contents in a way that removes existing entries. + +## Full API Fallback + +The live machine-readable documents are: + +- `/api-docs-json` +- `/api-docs-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. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-acceptance-runbook.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-acceptance-runbook.md new file mode 100644 index 0000000..741db4d --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-acceptance-runbook.md @@ -0,0 +1,85 @@ +# Model Runtime Acceptance Runbook + +## Before Changes + +- Record the target deployment and identity mode. +- Confirm administrator identity with `/api/v1/me`. +- Save current provider, base model, pricing rule set, policy set, platform, and platform-model JSON without secrets. +- Confirm whether real upstream calls are allowed; otherwise use simulation. +- Confirm upstream endpoint, auth, model name, capabilities, limits, pricing, and sync/async behavior from documentation. +- Record which existing pricing rule and runtime policy were reused, or the exact semantic mismatch that required a new one. +- For billing changes, save the current effective rule bindings, discounts, user-group policy, wallet balance, and one representative estimate response as described in `model-billing-configuration-and-estimation.md`. +- Record the protocol compatibility decision and why the selected existing `specType` is sufficient, or the concrete gap that requires `universal`. +- When one base model has different upstream names across platforms, confirm each binding resolves the expected `providerModelName`. + +## After Configuration + +Read back: + +- `/api/admin/catalog/providers` +- `/api/admin/catalog/base-models` +- `/api/admin/pricing/rule-sets` +- `/api/admin/runtime/policy-sets` +- `/api/admin/runtime/runner-policy` +- `/api/admin/platforms` +- `/api/admin/models` + +Verify that IDs and bindings resolve as intended and no unrelated record was removed or reset. + +## Catalog Verification + +Use an authorized user JWT: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer " \ + "$GATEWAY_BASE_URL/api/v1/model-catalog" +``` + +Confirm model alias, model types, provider source, effective capabilities, pricing summary, rate limits, permissions, and enabled state. + +For pricing, verify the effective rule source and discount source rather than checking IDs only. Confirm whether the platform-model discount overrides the platform default, and compare the estimated or simulated amount with the intended price. + +Use `/api/v1/pricing/estimate` for the first read-only calculation. A simulation request is a task execution path and may reserve and settle wallet billing; do not treat it as a read-only replacement for the estimate endpoint. + +## Execution Verification + +Start with simulation: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer " \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "", + "messages": [{"role":"user","content":"Reply with OK"}], + "runMode": "simulation", + "simulation": true, + "stream": false + }' \ + "$GATEWAY_BASE_URL/v1/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. + +For media or universal scripts, inspect: + +- `/api/workspace/tasks/{taskID}` +- `/api/workspace/tasks/{taskID}/events` +- `/api/workspace/tasks/{taskID}/param-preprocessing` +- `/api/admin/runtime/model-rate-limits` +- `/api/admin/runtime/rate-limit-windows` + +With explicit approval, run one real minimal request and verify upstream request ID, normalized output, task completion, `billings`, `billingSummary.totalAmount`, `finalChargeAmount`, and the wallet `task_billing` transaction. Explain any expected estimate difference caused by actual token usage, cached input, generated media duration/audio, preprocessing, or failover to another platform. + +## Rollback + +- Restore the prior complete resource body with PATCH. +- Restore an individual platform-model binding through POST. +- Use full platform-model PUT only when the saved list is complete and replacement is intentional. +- Remove newly created resources in reverse dependency order only after explicit confirmation. +- Use runtime restore only after the upstream problem is resolved. + +## 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. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-billing-configuration-and-estimation.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-billing-configuration-and-estimation.md new file mode 100644 index 0000000..8a40fc6 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-billing-configuration-and-estimation.md @@ -0,0 +1,249 @@ +# Model Billing Configuration and Estimate Reconciliation + +## Contents + +- Safety and Identity +- Effective Billing Layers +- Billing Configuration Workflow +- Price Estimate Requests +- Estimate Reconciliation +- Task and Wallet Charge Verification +- Expected Differences and Troubleshooting + +## Safety and Identity + +- Use an administrator JWT with `manager` permission for pricing, base-model, platform, platform-model, or user-group writes. Do not use an `sk-*` API key for management APIs. +- Call `POST /api/v1/pricing/estimate` with the same user JWT or API key that will execute the real request. The subject controls access rules, candidate visibility, API-key scopes, and user-group billing discount. +- The estimate endpoint is read-only for tasks and wallets: it selects and preprocesses a candidate and returns simulated billing lines, but it does not create a task, freeze balance, or debit the wallet. +- A request with `runMode: "simulation"` is different: it enters the task execution and billing path and may create task records, reserve wallet balance, and settle a charge. Use the estimate endpoint first and obtain approval before any task request intended only for billing verification. +- Never expose API keys, administrator JWTs, wallet identifiers, or credentials in reports. + +## Effective Billing Layers + +Read every applicable layer before changing one: + +1. Base model: `pricingRuleSetId` and `baseBillingConfig`. +2. Platform: `pricingRuleSetId`, `defaultPricingMode`, and `defaultDiscountFactor`. +3. Platform model: `pricingRuleSetId`, `billingConfigOverride`, `pricingMode`, and `discountFactor`. +4. User group: `billingDiscountPolicy.discountFactor`. + +The runtime resolves an effective billing configuration, then applies discounts. An explicit platform-model rule and `billingConfigOverride` can replace or merge inherited values. Do not infer the final price from one ID; confirm it with an estimate. + +The current discount behavior is: + +```text +candidate discount = positive platform-model discountFactor + else platform defaultDiscountFactor +effective discount = candidate discount × user-group billingDiscountPolicy.discountFactor +``` + +The platform and platform-model discount factors do not multiply together. The user-group factor, when positive, multiplies the selected candidate discount. + +Pricing rule resource mappings include: + +| `resourceType` | Effective use | +| --- | --- | +| `text_input` | uncached input token price per 1,000 tokens | +| `text_cached_input` | cached input token price per 1,000 tokens | +| `text_output` | output token price per 1,000 tokens | +| `text_total` | text prices from `basePrice` and optional `formulaConfig` | +| `image` | image generation base price and dynamic weights | +| `image_edit` | image-edit price; image pricing is a fallback when absent | +| `video` | price per five-second unit plus dynamic weights | +| other types | generic resource base price and weights, such as music or audio | + +Common `dynamicWeight` dimensions are `qualityWeights`, `sizeWeights`, `resolutionWeights`, `audioWeights`, `referenceVideoWeights`, and `voiceSpecifiedWeights`. Configure only dimensions used by the runtime and proven by the target product pricing. + +## Billing Configuration Workflow + +### 1. Capture the current state + +```bash +curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/pricing/rule-sets" +curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/catalog/base-models" +curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/platforms" +curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/models" +curl --fail-with-body -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/user-groups" +``` + +Use the runtime subject credential to read its effective group policy and wallet snapshot: + +```bash +curl --fail-with-body -H "Authorization: Bearer $RUNTIME_TOKEN" \ + "$GATEWAY_BASE_URL/api/workspace/user-groups" +curl --fail-with-body -H "Authorization: Bearer $RUNTIME_TOKEN" \ + "$GATEWAY_BASE_URL/api/workspace/wallet" +``` + +Save IDs and non-secret fields. Record the wallet balance and frozen balance only when a later task charge will be verified. + +### 2. Reuse or create the pricing rule + +Compare active rules by resource type, unit, base price, `dynamicWeight`, `formulaConfig`, calculator type, currency, and status. Reuse an existing rule when its effective amount can be adjusted with platform or platform-model discounts. Read `model-pricing-and-policies.md` for the rule-set request shape. + +Create a new rule only when no existing rule can express the required unit, formula, dimensions, or undiscounted price. `PATCH /api/admin/pricing/rule-sets/{ruleSetID}` replaces all rules in the set, so preserve every required row. + +### 3. Bind the minimum required layer + +- Put a reusable default rule on the base model with `pricingRuleSetId`. +- Put account-wide pricing on the platform with `pricingRuleSetId` and `defaultDiscountFactor`. +- Put a real per-model exception on the platform model with `pricingRuleSetId`, `discountFactor`, or `billingConfigOverride`. +- Use a user-group `billingDiscountPolicy.discountFactor` only for a subject-wide discount. Read the complete user-group record before PATCH and preserve unrelated rate-limit, quota, recharge, metadata, and status fields. + +Avoid copying the same prices into multiple layers. Read back every changed record before estimating. + +## Price Estimate Requests + +`POST /api/v1/pricing/estimate` accepts a normal request-shaped JSON object plus `kind`. `kind` defaults to `chat.completions`. An API key must have the scope required by the selected kind. + +### Chat estimate + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $RUNTIME_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "kind": "chat.completions", + "model": "", + "messages": [{"role": "user", "content": "Reply with OK"}], + "max_tokens": 256 + }' \ + "$GATEWAY_BASE_URL/api/v1/pricing/estimate" +``` + +Text input tokens are estimated from the request. Output tokens use `max_tokens`; when it is absent or zero, the estimate currently uses 64 output tokens. Use the intended output limit for a meaningful upper-bound comparison. + +### Image estimate + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $RUNTIME_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "kind": "images.generations", + "model": "", + "prompt": "A small orange cat", + "n": 2, + "size": "1024x1024", + "quality": "high" + }' \ + "$GATEWAY_BASE_URL/api/v1/pricing/estimate" +``` + +### Video estimate + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $RUNTIME_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "kind": "videos.generations", + "model": "", + "prompt": "A slow camera move over a lake", + "duration": 12, + "resolution": "1080p", + "audio": true, + "n": 1 + }' \ + "$GATEWAY_BASE_URL/api/v1/pricing/estimate" +``` + +The response has this shape: + +```json +{ + "items": [ + { + "model": "example-model", + "modelAlias": "example-model", + "provider": "example", + "platformId": "", + "platformModelId": "", + "resourceType": "video", + "unit": "5s_video", + "quantity": 3, + "amount": 12.5, + "currency": "resource", + "discountFactor": 0.8, + "simulated": true, + "durationSeconds": 12, + "durationUnitCount": 3 + } + ], + "resolver": "effective-pricing-v1", + "totalAmount": 12.5, + "currency": "resource" +} +``` + +## Estimate Reconciliation + +For every estimate, verify: + +1. `platformId` and `platformModelId` identify the intended first eligible candidate after permissions, capabilities, output-token limits, priority, and runtime availability are applied. +2. `resourceType`, `unit`, `quantity`, and dimension details match the normalized request. +3. `discountFactor` equals the selected platform/platform-model factor multiplied by the effective user-group factor. +4. Each `amount` matches the configured base price, weights, quantity, and discount. +5. `totalAmount` equals the rounded sum of `items[].amount`, and `currency` is expected. + +Useful calculation checks: + +```text +text input = input tokens / 1000 × input price × discount +text output = output tokens / 1000 × output price × discount +image = count × base price × quality/size/resolution weights × discount +video = count × ceil(duration seconds / 5) × base price × applicable weights × discount +speech = Unicode character count × audio price × discount +``` + +Cached input is normally known only after execution. When cached input exists but has no configured price, the runtime currently falls back to one tenth of the normal input price. + +If the estimate selects an unexpected platform, do not edit prices to hide the routing problem. Inspect access rules, enabled state, model type, capabilities, priority, cooldown/load, and output-token limits first. + +## Task and Wallet Charge Verification + +After the read-only estimate is accepted, obtain explicit approval before a simulation or real task if wallet mutation is possible. + +1. Record `GET /api/workspace/wallet` before the request. +2. Submit the exact same `kind`, model, and billing-relevant parameters through the corresponding runtime API. +3. Read `GET /api/workspace/tasks/{taskID}` and capture: + - `billings`; + - `billingSummary.totalAmount` and currency; + - `finalChargeAmount`; + - resolved model and candidate evidence from metrics. +4. Query the final wallet debit: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $RUNTIME_TOKEN" \ + "$GATEWAY_BASE_URL/api/workspace/wallet/transactions?q=$TASK_ID&transactionType=task_billing&pageSize=20" +``` + +5. Read the wallet again and compare: + +```text +task finalChargeAmount == billingSummary.totalAmount +task finalChargeAmount == task_billing transaction amount +wallet balance before - wallet balance after == task_billing transaction amount +``` + +The task may also create `reserve` and `release` transactions. Reservation changes frozen balance, not the spend balance; `task_billing` is the final debit to reconcile. Use the task ID as the reference and never sum `reserve`, `release`, and `task_billing` as three charges. + +## Expected Differences and Troubleshooting + +An estimate and final charge may legitimately differ when: + +- actual text input/output or cached-input usage differs from the estimate; +- the request omitted `max_tokens`, so the estimate used the 64-token default; +- generated video duration or audio presence overrides the requested/preprocessed value; +- preprocessing normalizes duration, resolution, count, or model-specific fields; +- the first candidate fails and execution settles on another platform with different pricing; +- the estimate and task used different users, API keys, scopes, groups, or access rules; +- pricing or discount configuration changed between estimate and execution. + +When the difference is unexplained, compare the estimate line, task `billings`, task preprocessing log, candidate metrics, effective user group, wallet transaction metadata, and configuration timestamps. Do not change wallet balances to make a mismatch disappear. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-platforms-and-bindings.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-platforms-and-bindings.md new file mode 100644 index 0000000..c4f6b6e --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-platforms-and-bindings.md @@ -0,0 +1,123 @@ +# Platforms and Platform-model Bindings + +## Read Current State + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/platforms" + +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/models" +``` + +Platform responses expose masked `credentialsPreview`, not stored secrets. + +## Reuse-compatible Platforms First + +Before creating a platform or selecting `universal`: + +1. Compare the upstream authentication, endpoint paths, content type, request schema, response schema, and sync/async lifecycle with the clients already represented by existing platform `config.specType` values. +2. If the upstream is compatible with an existing OpenAI, Gemini, or provider-specific client, keep that client type. For another compatible endpoint or account, the protocol layer normally needs only a different `baseUrl`; credentials and account-specific settings remain ordinary platform instance configuration. +3. Reuse the existing platform record only when it represents the same logical account/endpoint and changing it will not redirect unrelated models. Otherwise create another standard platform instance with the same compatible `specType`. +4. Use `universal` only when a documented request, authentication, task lifecycle, or response-mapping requirement cannot be expressed by a standard client. + +Do not convert a compatible platform to `universal` merely because the host name, account, or provider-side model name differs. + +## Create a Standard Platform + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "provider": "example-openai", + "platformKey": "example-openai-primary", + "name": "Example OpenAI Primary", + "internalName": "example-openai-primary", + "baseUrl": "https://api.example.com/v1", + "authType": "bearer", + "credentials": {"apiKey": ""}, + "config": {"specType": "openai"}, + "retryPolicy": {}, + "rateLimitPolicy": {}, + "defaultPricingMode": "inherit_discount", + "defaultDiscountFactor": 1, + "pricingRuleSetId": "", + "priority": 100, + "status": "enabled" + }' \ + "$GATEWAY_BASE_URL/api/admin/platforms" +``` + +Use `PATCH /api/admin/platforms/{platformID}` with the complete platform body. Omit `credentials` to preserve existing secrets. A non-empty credentials object is merged into stored credentials. An empty object clears credentials and requires explicit confirmation. + +## Upsert One Platform Model + +`POST /api/admin/platforms/{platformID}/models` inserts or updates the `(platformID, modelName)` binding: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "baseModelId": "", + "canonicalModelKey": "example-openai:example-chat", + "modelName": "example-chat", + "providerModelName": "example-chat", + "modelAlias": "example-chat", + "modelType": ["text_generate"], + "displayName": "Example Chat", + "capabilityOverride": {}, + "pricingMode": "inherit_discount", + "discountFactor": 1, + "pricingRuleSetId": "", + "billingConfigOverride": {}, + "permissionConfig": {}, + "retryPolicy": {}, + "rateLimitPolicy": {}, + "runtimePolicySetId": "", + "runtimePolicyOverride": {}, + "enabled": true + }' \ + "$GATEWAY_BASE_URL/api/admin/platforms//models" +``` + +When fields are omitted, defaults may be derived from the base model. For predictable updates, read the current binding and send the intended complete configuration. + +### Override the real upstream invocation name + +Use the base model as the stable system identity and `providerModelName` as the platform-specific name sent to the upstream API: + +- `modelName` is the platform binding key and participates in the `(platformId, modelName)` upsert identity. +- `providerModelName` is the real model/deployment name used by the selected runtime client. +- Bind the same `baseModelId` on multiple platforms and set a different `providerModelName` on each binding when providers expose different invocation names. +- Do not create duplicate base models solely for aliases such as a vendor deployment ID, endpoint ID, dated model ID, or regional model name. + +Example: + +```json +[ + { + "platform": "platform-a", + "baseModelId": "base-example-chat", + "modelName": "example-chat", + "providerModelName": "example-chat-2026-07" + }, + { + "platform": "platform-b", + "baseModelId": "base-example-chat", + "modelName": "example-chat", + "providerModelName": "deployment-prod-42" + } +] +``` + +The current create/upsert implementation stores the platform-model binding as enabled even when the request contains `"enabled": false`. Do not rely on that input field for canary isolation. Use an isolated test deployment or keep the whole platform disabled until configuration review is complete; enable the platform only for an approved protocol test. + +## Full Replacement and Deletion + +`PUT /api/admin/platforms/{platformID}/models` reconciles the platform to exactly the supplied `models` list. Omitted bindings are deleted together with their platform-model access rules. Never use it for a single-model update. + +Delete one binding with `DELETE /api/admin/platform-models/{modelID}` after confirmation. Delete a platform with `DELETE /api/admin/platforms/{platformID}` only after reviewing all bindings and access-rule impact. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-pricing-and-policies.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-pricing-and-policies.md new file mode 100644 index 0000000..8da4484 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-pricing-and-policies.md @@ -0,0 +1,139 @@ +# Model Pricing and Policies + +## Contents + +- Pricing Rule Sets +- Billing Configuration and Estimate Reconciliation +- Runtime Policy Sets +- Runner Policy and Runtime Recovery + +## Pricing Rule Sets + +Read rule sets and effective rule rows: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/pricing/rule-sets" + +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/pricing/rules" +``` + +### Reuse-first pricing decision + +Do not create a pricing rule until all existing active rule sets have been compared against the target resource types, units, calculator types, base prices, weights, and conditions. + +Evaluate the price that the runtime will actually use: + +1. Identify the inherited pricing source from the base model and platform, then check whether the platform-model has an explicit `pricingRuleSetId` or billing override. +2. Reuse the existing rule when it already describes the required raw unit prices and calculators. +3. Apply the effective discount: + - a positive platform-model `discountFactor` takes precedence; + - otherwise `pricingMode: "inherit_discount"` uses the platform `defaultDiscountFactor`; + - AI Gateway does not multiply the platform and platform-model discount factors together. +4. Verify the resulting amount with `/api/v1/pricing/estimate`, simulation billing lines, or an approved test request. +5. Create a new rule set only when no existing rule plus the available platform/platform-model discount can produce the required price or express the required unit/calculator structure. + +Do not clone an otherwise identical pricing rule merely to represent a provider or account discount. Keep the reusable base price in the rule and express the instance-specific adjustment with `defaultDiscountFactor` or `discountFactor`. + +For the complete binding, estimate, task-charge, and wallet-reconciliation workflow, read `model-billing-configuration-and-estimation.md` before changing billing settings. + +Create an example text pricing rule set: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "ruleSetKey": "example-chat-pricing-v1", + "name": "Example Chat Pricing", + "description": "Input and output token pricing", + "category": "model", + "currency": "resource", + "status": "active", + "metadata": {}, + "rules": [ + { + "ruleKey": "input", + "displayName": "Input tokens", + "resourceType": "text_input", + "unit": "1k_tokens", + "basePrice": 0.001, + "calculatorType": "token_usage", + "priority": 10, + "status": "active" + }, + { + "ruleKey": "output", + "displayName": "Output tokens", + "resourceType": "text_output", + "unit": "1k_tokens", + "basePrice": 0.002, + "calculatorType": "token_usage", + "priority": 20, + "status": "active" + } + ] + }' \ + "$GATEWAY_BASE_URL/api/admin/pricing/rule-sets" +``` + +`PATCH /api/admin/pricing/rule-sets/{ruleSetID}` replaces the stored rules with the supplied list. Preserve every rule that should remain. Delete only non-default rule sets after checking base-model, platform, and platform-model bindings. + +## Runtime Policy Sets + +Read and create policies: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/runtime/policy-sets" +``` + +Compare the existing policy sets before creating one. Reuse a policy when the effective rate-limit metrics, limits, windows, concurrency lease TTL, retry count, auto-disable behavior, degradation behavior, and scope semantics match the target. A different platform name or model name alone is not a reason to duplicate a policy. + +Create a new policy only when at least one required behavior cannot be represented by an existing policy plus the supported platform-model override fields. Record the mismatch that justified the new policy. + +```json +{ + "policyKey": "example-balanced-v1", + "name": "Example Balanced", + "description": "Retry and concurrency policy", + "rateLimitPolicy": { + "rules": [ + {"metric": "rpm", "limit": 60, "windowSeconds": 60}, + {"metric": "concurrent", "limit": 5, "leaseTtlSeconds": 120} + ] + }, + "retryPolicy": {"maxRetries": 2}, + "autoDisablePolicy": {}, + "degradePolicy": {}, + "metadata": {}, + "status": "active" +} +``` + +POST the body to `/api/admin/runtime/policy-sets`. Use PATCH with a complete body. Default policy sets cannot be deleted. + +## Runner Policy and Runtime Recovery + +Read the current global runner policy before changing it: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/runtime/runner-policy" +``` + +PATCH the same endpoint with the complete current fields plus approved changes to `failoverPolicy`, `hardStopPolicy`, `singleSourcePolicy`, or `cacheAffinityPolicy`. + +Operational endpoints: + +- `PATCH /api/admin/platforms/{platformID}/dynamic-priority` +- `GET /api/admin/runtime/rate-limit-windows` +- `GET /api/admin/runtime/model-rate-limits` +- `POST /api/admin/runtime/model-rate-limits/{platformModelID}/restore` + +Use restore only after identifying whether the model, platform cooldown, or platform disablement was automatic and whether the upstream condition has recovered. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-providers-and-base-models.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-providers-and-base-models.md new file mode 100644 index 0000000..384b3bd --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-providers-and-base-models.md @@ -0,0 +1,87 @@ +# Model Providers and Base Models + +## Read Current State + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/catalog/providers" + +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + "$GATEWAY_BASE_URL/api/admin/catalog/base-models" +``` + +Public read-only catalog endpoints also exist at `/api/v1/public/catalog/providers` and `/api/v1/public/catalog/base-models`. + +## Provider Catalog + +Create a provider: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "providerKey": "example-openai", + "code": "example-openai", + "displayName": "Example OpenAI Compatible", + "providerType": "openai", + "defaultBaseUrl": "https://api.example.com/v1", + "defaultAuthType": "APIKey", + "source": "gateway", + "capabilitySchema": {}, + "defaultRateLimitPolicy": {}, + "metadata": {"protocol": "openai-compatible"}, + "status": "active" + }' \ + "$GATEWAY_BASE_URL/api/admin/catalog/providers" +``` + +Use `PATCH /api/admin/catalog/providers/{providerID}` with the complete current provider body to update. `providerType` selects the runtime client through the platform candidate. Common supported values include `openai`, `gemini`, `volces`, `keling`, `minimax`, and `universal`. Unknown types may fall back to the OpenAI client, so never leave a custom integration type ambiguous. + +Delete with `DELETE /api/admin/catalog/providers/{providerID}` only after checking platform references and obtaining confirmation. + +## Base Model + +Create a base model after its provider exists: + +```bash +curl --fail-with-body \ + -H "Authorization: Bearer $GATEWAY_ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{ + "providerKey": "example-openai", + "canonicalModelKey": "example-openai:example-chat", + "providerModelName": "example-chat", + "modelType": ["text_generate"], + "modelAlias": "example-chat", + "displayName": "Example Chat", + "capabilities": { + "text_generate": { + "supportedApiProtocols": ["openai_chat_completions"] + } + }, + "baseBillingConfig": { + "textInputPer1k": 0.001, + "textOutputPer1k": 0.002 + }, + "defaultRateLimitPolicy": {}, + "runtimePolicyOverride": {}, + "metadata": {"description": "Example OpenAI-compatible chat model"}, + "catalogType": "custom", + "defaultSnapshot": {}, + "pricingVersion": 1, + "status": "active" + }' \ + "$GATEWAY_BASE_URL/api/admin/catalog/base-models" +``` + +Use `PATCH /api/admin/catalog/base-models/{baseModelID}` with a complete body to update. Do not omit capabilities, billing, policy bindings, metadata, or status unintentionally. + +Reset endpoints are destructive: + +- `POST /api/admin/catalog/base-models/{baseModelID}/reset` +- `POST /api/admin/catalog/base-models/reset-all` + +Only system-seeded models with default snapshots can be reset. Delete with `DELETE /api/admin/catalog/base-models/{baseModelID}` only after checking platform-model bindings. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-universal-platforms.md b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-universal-platforms.md new file mode 100644 index 0000000..aa19ca5 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/references/model-universal-platforms.md @@ -0,0 +1,92 @@ +# Universal Custom Platforms + +## Selection Rule + +Use `universal` only when documented upstream requirements cannot be represented by an existing standard client. Prefer: + +1. `openai` for OpenAI-compatible chat, Responses, embeddings, reranks, image generation, or image editing. +2. `gemini` for Gemini `generateContent` contracts. +3. A provider-specific client such as `volces`, `keling`, or `minimax` when implemented. +4. `universal` for non-standard auth, submit/poll lifecycles, payload shaping, or response mapping. + +Set the provider catalog `providerType` or platform `config.specType` explicitly to `universal`. An unknown type may fall back to OpenAI behavior. + +Do not assume a new platform-model binding can be staged with `enabled: false`; the current upsert path enables it. Isolate tests with the platform status or a dedicated non-production deployment. + +## Platform Configuration + +Gateway directly recognizes these universal settings in the platform `config` object: + +- `specType` +- `submitPath` +- `getTaskURL` +- `pollIntervalMs` +- `pollTimeoutMs` or `timeoutMs` +- `skipParamNormalization` +- `customPreprocessScript` +- `customGetParamsScript` +- `customSubmitScript` +- `customPollScript` + +Do not invent additional enforcement fields. Other config keys are only exposed as data through `context.env` unless a custom script explicitly reads and enforces them. + +```json +{ + "specType": "universal", + "submitPath": "/video/generations", + "getTaskURL": "https://provider.example/tasks/{upstream_task_id}", + "pollIntervalMs": 2000, + "pollTimeoutMs": 600000, + "skipParamNormalization": false, + "customGetParamsScript": { + "video_generate": "function getGenerateParams(params, context) { return { model: context.options.providerModelName, prompt: params.prompt }; }" + }, + "customSubmitScript": { + "video_generate": "async function submitTask(payload, context) { const response = await got.post(context.createRequestURL('/video/generations'), { json: payload, headers: { Authorization: 'Bearer ' + context.authValues.apiKey } }).json(); const taskId = String(response.id || ''); if (!/^[A-Za-z0-9._:-]{1,200}$/.test(taskId)) return { status: 'failed', code: 'invalid_response', message: 'invalid upstream task id' }; return { status: 'submitted', task_id: taskId }; }" + }, + "customPollScript": { + "video_generate": "async function pollTask(taskId, context) { if (!/^[A-Za-z0-9._:-]{1,200}$/.test(taskId)) return { status: 'failed', code: 'invalid_response', message: 'invalid upstream task id' }; const response = await got.get(context.resolveGetTaskURL(taskId), { headers: { Authorization: 'Bearer ' + context.authValues.apiKey } }).json(); if (response.status === 'done') { const resultUrl = String(response.url || ''); if (!/^https:\\/\\/cdn\\.video\\.example(?:\\/|$)/.test(resultUrl)) return { status: 'failed', code: 'invalid_response', message: 'untrusted result URL' }; return { status: 'succeeded', data: [{ url: resultUrl }] }; } if (response.status === 'failed') return { status: 'failed', code: 'provider_failed', message: String(response.message || 'provider task failed').slice(0, 300) }; if (response.status === 'queued' || response.status === 'processing' || response.status === 'running') return { status: 'processing' }; return { status: 'failed', code: 'invalid_response', message: 'unknown upstream status' }; }" + } +} +``` + +Script values may be a string applied to all model types or an object keyed by model type with optional `common`. + +## Script Contracts + +- Preprocess: `(params, type, context)`; return an object merged into normalized parameters. Preferred names include `preprocessParams`, `preprocess`, `main`, and `handler`. +- Get params: `(params, context)`; return the upstream payload object. Preferred names include `getGenerateParams`, `getParams`, `main`, and `handler`. +- Submit: `(payload, context)`; return final success data or an asynchronous task ID. Preferred names include `submitTask`, `submitParams`, `submit`, `main`, and `handler`. +- Poll: `(upstreamTaskID, context)`; return processing, success, or failure state. Preferred names include `pollTask`, `poll`, `main`, and `handler`. + +The context includes `baseURL`, `getTaskURL`, `authValues`, `headers`, `payload`, `type`, `options`, `env`, `candidate`, `createRequestURL`, and `resolveGetTaskURL`. The runtime also exposes `fetch`, `got`, and `FormData`. + +If a result URL must be restricted, implement the HTTPS and host allowlist check inside the submit or poll script before returning `data`. Merely adding an `allowedResultUrlPrefixes`-style config field has no built-in effect. Do not convert HTTP failures into `processing` unless the upstream documentation proves that retrying the poll is safe. + +Do not assume Node.js or browser globals exist. The runtime does not install `URL`, `Buffer`, `process`, `require`, or Node modules. Use the provided context helpers, `fetch`, `got`, `FormData`, and standard ECMAScript string or regular-expression checks. + +## Result Shapes + +Synchronous success: + +```json +{"status":"succeeded","data":[{"url":"https://provider.example/result.png"}]} +``` + +Asynchronous submit: + +```json +{"status":"submitted","task_id":"remote-task-id"} +``` + +Poll success or failure: + +```json +{"status":"succeeded","data":[{"url":"https://provider.example/result.mp4"}]} +``` + +```json +{"status":"failed","code":"provider_failed","message":"upstream rejected request"} +``` + +Never log, return, or retain `authValues`, full raw responses, base64 media, Buffers, HTTP response objects, or entire request snapshots. Return only the fields required for routing and normalized output. diff --git a/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/skill.json b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/skill.json new file mode 100644 index 0000000..27f2655 --- /dev/null +++ b/apps/api/internal/skillbundle/content/skills/ai-gateway-ops-management/skill.json @@ -0,0 +1,7 @@ +{ + "name": "ai-gateway-ops-management", + "version": "1.0.2", + "modules": [ + "model-runtime" + ] +} diff --git a/apps/api/internal/store/identity_pairing_integration_test.go b/apps/api/internal/store/identity_pairing_integration_test.go index 976cfb2..65c8b16 100644 --- a/apps/api/internal/store/identity_pairing_integration_test.go +++ b/apps/api/internal/store/identity_pairing_integration_test.go @@ -686,14 +686,10 @@ func newIdentityPairingPostgresTestStore(t *testing.T) *Store { for _, migrationName := range []string{ "0001_init.sql", "0061_oidc_server_sessions.sql", - "0067_identity_configuration_revisions.sql", - "0068_identity_onboarding_exchanges.sql", - "0069_identity_pairing_cancellation.sql", - "0070_identity_secret_cleanup_queue.sql", - "0071_identity_pairing_start_reservation.sql", - "0072_identity_secret_cleanup_claim_lifecycle.sql", - "0073_identity_pairing_start_reservation_upgrade.sql", - "0074_identity_pairing_error_categories.sql", + "0065_identity_configuration_revisions.sql", + "0066_identity_onboarding_exchanges.sql", + "0067_identity_secret_cleanup_queue.sql", + "0068_identity_pairing_start_reservation.sql", } { migration, err := os.ReadFile(filepath.Join(migrationDirectory, migrationName)) if err != nil { diff --git a/apps/api/internal/store/identity_secret_cleanup_migration_integration_test.go b/apps/api/internal/store/identity_secret_cleanup_migration_integration_test.go index c750df2..7b0895e 100644 --- a/apps/api/internal/store/identity_secret_cleanup_migration_integration_test.go +++ b/apps/api/internal/store/identity_secret_cleanup_migration_integration_test.go @@ -16,81 +16,53 @@ import ( "github.com/jackc/pgx/v5/pgxpool" ) -func TestIdentitySecretCleanupClaimLifecycleUpgradeMigrationExists(t *testing.T) { - payload, err := os.ReadFile(identitySecretCleanupMigrationPath(t, "0072_identity_secret_cleanup_claim_lifecycle.sql")) +const identitySecretCleanupMigration = "0067_identity_secret_cleanup_queue.sql" + +func TestIdentitySecretCleanupMigrationDefinesClaimLifecycle(t *testing.T) { + payload, err := os.ReadFile(identitySecretCleanupMigrationPath(t, identitySecretCleanupMigration)) if err != nil { t.Fatal(err) } content := strings.ToLower(string(payload)) for _, required := range []string{ - "add column if not exists status text", - "add column if not exists claim_token uuid", - "add column if not exists lease_expires_at timestamptz", - "alter column status set default 'pending'", - "alter column status set not null", - "gateway_identity_secret_cleanup_status_check", + "create table if not exists gateway_identity_secret_cleanup_queue", + "secret_ref text primary key", + "status text not null default 'pending'", + "claim_token uuid", + "lease_expires_at timestamptz", "gateway_identity_secret_cleanup_claim_check", - "drop index if exists idx_gateway_identity_secret_cleanup_due", - "create index idx_gateway_identity_secret_cleanup_due", + "idx_gateway_identity_secret_cleanup_due", } { if !strings.Contains(content, required) { - t.Fatalf("identity Secret cleanup lifecycle migration is missing %q", required) + t.Fatalf("identity Secret cleanup migration is missing %q", required) } } - for _, forbidden := range []string{"secret_value", "client_secret", "machine_secret", "token text"} { + for _, forbidden := range []string{"secret_value", "client_secret", "machine_secret", "token text", "drop ", "set not null"} { if strings.Contains(content, forbidden) { - t.Fatalf("identity Secret cleanup lifecycle migration stores forbidden value field %q", forbidden) + t.Fatalf("identity Secret cleanup migration contains forbidden content %q", forbidden) } } } -func TestIdentitySecretCleanupClaimLifecycleUpgradeMigratesLegacyQueue(t *testing.T) { +func TestIdentitySecretCleanupMigrationSupportsClaimLifecycle(t *testing.T) { db := newIdentitySecretCleanupMigrationPostgresStore(t) ctx := context.Background() - reference := "identity-cleanup-legacy-" + uuid.NewString() + applyIdentitySecretCleanupMigration(t, ctx, db.pool, identitySecretCleanupMigration) + reference := "identity-cleanup-" + uuid.NewString() - if _, err := db.pool.Exec(ctx, ` -CREATE TABLE gateway_identity_secret_cleanup_queue ( - secret_ref text PRIMARY KEY CHECK (secret_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'), - not_before timestamptz NOT NULL, - created_at timestamptz NOT NULL DEFAULT now(), - updated_at timestamptz NOT NULL DEFAULT now() -);`); err != nil { - t.Fatalf("create legacy identity Secret cleanup queue: %v", err) + if err := db.QueueIdentitySecretCleanup(ctx, reference, time.Now().Add(-time.Minute)); err != nil { + t.Fatalf("queue identity Secret cleanup: %v", err) } - if _, err := db.pool.Exec(ctx, `CREATE INDEX idx_gateway_identity_secret_cleanup_due - ON gateway_identity_secret_cleanup_queue(not_before,updated_at)`); err != nil { - t.Fatalf("create legacy identity Secret cleanup due index: %v", err) - } - if _, err := db.pool.Exec(ctx, `INSERT INTO gateway_identity_secret_cleanup_queue(secret_ref,not_before) -VALUES($1,now()-interval '1 minute')`, reference); err != nil { - t.Fatalf("seed legacy identity Secret cleanup row: %v", err) - } - - applyIdentitySecretCleanupMigration(t, ctx, db.pool, "0072_identity_secret_cleanup_claim_lifecycle.sql") - - var status string - var claimToken, leaseExpiresAt *string - if err := db.pool.QueryRow(ctx, ` -SELECT status,claim_token::text,lease_expires_at::text -FROM gateway_identity_secret_cleanup_queue WHERE secret_ref=$1`, reference). - Scan(&status, &claimToken, &leaseExpiresAt); err != nil { - t.Fatalf("read migrated cleanup row: %v", err) - } - if status != "pending" || claimToken != nil || leaseExpiresAt != nil { - t.Fatalf("legacy cleanup row was not backfilled to an unclaimed pending lifecycle") - } - claims, err := db.ClaimIdentitySecretCleanups(ctx, 1, time.Minute) if err != nil { - t.Fatalf("claim migrated cleanup row: %v", err) + t.Fatalf("claim identity Secret cleanup: %v", err) } if len(claims) != 1 || claims[0].Reference != reference || claims[0].ClaimToken == "" { - t.Fatalf("claim migrated cleanup row returned unexpected claim metadata") + t.Fatalf("claim identity Secret cleanup returned unexpected metadata: %#v", claims) } completed, err := db.CompleteIdentitySecretCleanup(ctx, reference, claims[0].ClaimToken) if err != nil || !completed { - t.Fatalf("complete migrated cleanup claim: completed=%t err=%v", completed, err) + t.Fatalf("complete identity Secret cleanup: completed=%t err=%v", completed, err) } invalidReference := "identity-cleanup-invalid-" + uuid.NewString() @@ -105,15 +77,11 @@ INSERT INTO gateway_identity_secret_cleanup_queue( SELECT pg_get_indexdef(indexrelid) FROM pg_index WHERE indexrelid='idx_gateway_identity_secret_cleanup_due'::regclass`).Scan(&indexDefinition); err != nil { - t.Fatalf("read upgraded cleanup due index: %v", err) + t.Fatalf("read cleanup due index: %v", err) } if !strings.Contains(strings.ToLower(indexDefinition), "(status, not_before, lease_expires_at, updated_at)") { - t.Fatalf("cleanup due index does not cover the claim lifecycle") + t.Fatalf("cleanup due index does not cover the claim lifecycle: %q", indexDefinition) } - - // The production migration runner applies each version once. Reapplying here - // proves that the upgrade also accepts the already-current 0070 schema shape. - applyIdentitySecretCleanupMigration(t, ctx, db.pool, "0072_identity_secret_cleanup_claim_lifecycle.sql") } func newIdentitySecretCleanupMigrationPostgresStore(t *testing.T) *Store { @@ -125,12 +93,12 @@ func newIdentitySecretCleanupMigrationPostgresStore(t *testing.T) *Store { ctx := context.Background() admin, err := pgxpool.New(ctx, databaseURL) if err != nil { - t.Fatalf("connect identity Secret cleanup migration test database: %v", err) + t.Fatalf("connect identity migration test database: %v", err) } var databaseName string if err := admin.QueryRow(ctx, `SELECT current_database()`).Scan(&databaseName); err != nil { admin.Close() - t.Fatalf("read identity Secret cleanup migration test database name: %v", err) + t.Fatalf("read identity migration test database name: %v", err) } if !strings.Contains(strings.ToLower(databaseName), "test") { admin.Close() @@ -141,25 +109,25 @@ func newIdentitySecretCleanupMigrationPostgresStore(t *testing.T) *Store { schemaIdentifier := pgx.Identifier{schemaName}.Sanitize() if _, err := admin.Exec(ctx, `CREATE SCHEMA `+schemaIdentifier); err != nil { admin.Close() - t.Fatalf("create identity Secret cleanup migration test schema: %v", err) + t.Fatalf("create identity migration test schema: %v", err) } config, err := pgxpool.ParseConfig(databaseURL) if err != nil { _, _ = admin.Exec(ctx, `DROP SCHEMA IF EXISTS `+schemaIdentifier+` CASCADE`) admin.Close() - t.Fatalf("parse identity Secret cleanup migration test database URL: %v", err) + t.Fatalf("parse identity migration test database URL: %v", err) } config.ConnConfig.RuntimeParams["search_path"] = schemaName pool, err := pgxpool.NewWithConfig(ctx, config) if err != nil { _, _ = admin.Exec(ctx, `DROP SCHEMA IF EXISTS `+schemaIdentifier+` CASCADE`) admin.Close() - t.Fatalf("connect identity Secret cleanup migration test schema: %v", err) + t.Fatalf("connect identity migration test schema: %v", err) } t.Cleanup(func() { pool.Close() if _, err := admin.Exec(context.Background(), `DROP SCHEMA IF EXISTS `+schemaIdentifier+` CASCADE`); err != nil { - t.Errorf("drop identity Secret cleanup migration test schema: %v", err) + t.Errorf("drop identity migration test schema: %v", err) } admin.Close() }) diff --git a/apps/api/internal/store/platform_models.go b/apps/api/internal/store/platform_models.go index 83c284a..6c5f7d4 100644 --- a/apps/api/internal/store/platform_models.go +++ b/apps/api/internal/store/platform_models.go @@ -3,6 +3,8 @@ package store import ( "context" "encoding/json" + "fmt" + "math" "strings" "github.com/jackc/pgx/v5" @@ -116,6 +118,9 @@ func (s *Store) createPlatformModel(ctx context.Context, q platformModelQuerier, if len(capabilities) == 0 { capabilities = EffectivePlatformModelCapabilities(base.Capabilities, input.CapabilityOverride) } + if err := validateEnabledVolcesTextModelCapabilities(ctx, q, input, capabilities); err != nil { + return PlatformModel{}, err + } billingConfig := input.BillingConfig if len(billingConfig) == 0 { billingConfig = mergeObjects(base.BaseBillingConfig, input.BillingConfigOverride) @@ -262,6 +267,76 @@ RETURNING id::text, platform_id::text, COALESCE(base_model_id::text, ''), model_ return model, nil } +func validateEnabledVolcesTextModelCapabilities(ctx context.Context, q platformModelQuerier, input CreatePlatformModelInput, capabilities map[string]any) error { + // createPlatformModel enables/upserts models unconditionally, so every text + // model that reaches this path must already satisfy the Volcengine invariant. + if !containsTextOutputModelType(input.ModelType) { + return nil + } + var provider string + var baseURL string + if err := q.QueryRow(ctx, `SELECT provider, COALESCE(base_url, '') FROM integration_platforms WHERE id = $1::uuid`, input.PlatformID).Scan(&provider, &baseURL); err != nil { + return err + } + provider = strings.ToLower(strings.TrimSpace(provider)) + baseURL = strings.ToLower(strings.TrimSpace(baseURL)) + if provider != "volces-openai" && !strings.Contains(baseURL, "volces.com") && !strings.Contains(baseURL, "byteplus.com") { + return nil + } + seen := map[string]struct{}{} + for _, modelType := range append(append(StringList{}, input.ModelType...), "text_generate") { + modelType = strings.TrimSpace(modelType) + if modelType == "" { + continue + } + if _, ok := seen[modelType]; ok { + continue + } + seen[modelType] = struct{}{} + capability, _ := capabilities[modelType].(map[string]any) + if value, ok := positiveWholeNumber(capability["max_output_tokens"]); ok && value > 0 { + return nil + } + } + return fmt.Errorf("%w: enabled Volcengine text model %q requires a positive integer max_output_tokens capability for its text model type or text_generate fallback", ErrInvalidPlatformModelConfiguration, input.ProviderModelName) +} + +func containsTextOutputModelType(values StringList) bool { + for _, value := range values { + switch strings.ToLower(strings.TrimSpace(value)) { + case "text_generate", "chat", "responses", "text": + return true + } + } + return false +} + +func positiveWholeNumber(value any) (int64, bool) { + var number float64 + switch typed := value.(type) { + case int: + number = float64(typed) + case int32: + number = float64(typed) + case int64: + number = float64(typed) + case float64: + number = typed + case json.Number: + parsed, err := typed.Float64() + if err != nil { + return 0, false + } + number = parsed + default: + return 0, false + } + if number <= 0 || math.Trunc(number) != number || number > math.MaxInt64 { + return 0, false + } + return int64(number), true +} + func (s *Store) DeletePlatformModel(ctx context.Context, id string) error { tx, err := s.pool.Begin(ctx) if err != nil { diff --git a/apps/api/internal/store/runtime_types.go b/apps/api/internal/store/runtime_types.go index 6819ff7..c4c4b5f 100644 --- a/apps/api/internal/store/runtime_types.go +++ b/apps/api/internal/store/runtime_types.go @@ -7,8 +7,9 @@ import ( ) var ( - ErrNoModelCandidate = errors.New("no enabled platform model matches request") - ErrRateLimited = errors.New("rate limit exceeded") + ErrNoModelCandidate = errors.New("no enabled platform model matches request") + ErrRateLimited = errors.New("rate limit exceeded") + ErrInvalidPlatformModelConfiguration = errors.New("invalid platform model configuration") ) type ModelCandidateUnavailableError struct { diff --git a/apps/api/migrations/0062_keling_30_turbo.sql b/apps/api/migrations/0062_keling_30_turbo.sql new file mode 100644 index 0000000..d554634 --- /dev/null +++ b/apps/api/migrations/0062_keling_30_turbo.sql @@ -0,0 +1,216 @@ +UPDATE model_catalog_providers +SET default_auth_type = 'APIKey', + updated_at = now() +WHERE provider_key = 'keling' + OR provider_code = 'keling'; + +UPDATE integration_platforms +SET auth_type = CASE + WHEN COALESCE(NULLIF(trim(credentials->>'accessKey'), ''), NULLIF(trim(credentials->>'secretKey'), '')) IS NULL + THEN 'APIKey' + ELSE auth_type + END, + credentials = CASE + WHEN credentials ? 'apiKey' THEN credentials + ELSE credentials || '{"apiKey": ""}'::jsonb + END, + updated_at = now() +WHERE provider = 'keling' + AND deleted_at IS NULL; + +WITH keling_30_turbo AS ( + SELECT + 'keling:kling-3.0-turbo' AS canonical_model_key, + 'kling-3.0-turbo' AS provider_model_name, + '可灵3.0 Turbo' AS display_name, + '["video_generate","image_to_video"]'::jsonb AS model_type, + '{ + "video_generate": { + "aspect_ratio_allowed": ["16:9", "1:1", "9:16"], + "output_resolutions": ["720p", "1080p"], + "duration_range": [3, 15], + "output_audio": true, + "prompt_length_limit": { + "max": 3072, + "label": "可灵3.0 Turbo" + } + }, + "image_to_video": { + "output_resolutions": ["720p", "1080p"], + "duration_range": [3, 15], + "input_first_frame": true, + "input_last_frame": false, + "input_first_last_frame": false, + "aspect_ratio_allowed": [], + "output_audio": true, + "input_reference_generate_single": false, + "input_reference_generate_multiple": false, + "support_video_effect_template": false, + "prompt_length_limit": { + "max": 2500, + "label": "可灵3.0 Turbo" + } + }, + "originalTypes": ["video_generate", "image_to_video"] + }'::jsonb AS capabilities, + COALESCE( + ( + SELECT base_billing_config + FROM base_model_catalog + WHERE canonical_model_key = 'keling:kling-v3' + LIMIT 1 + ), + '{ + "video": { + "basePrice": 100, + "baseWeight": 1, + "dynamicWeight": { + "720p": 1, + "1080p": 1.5, + "audio-true": 2, + "audio-false": 1 + } + }, + "currency": "resource" + }'::jsonb + ) AS base_billing_config, + COALESCE( + ( + SELECT default_rate_limit_policy + FROM base_model_catalog + WHERE canonical_model_key = 'keling:kling-v3' + LIMIT 1 + ), + '{"platformLimits":{"max_concurrent_requests":5}}'::jsonb + ) AS default_rate_limit_policy, + '{ + "source": "server-main.integration-platform", + "sourceProviderCode": "keling", + "sourceProviderName": "可灵AI", + "sourceSpecType": "keling", + "originalTypes": ["video_generate", "image_to_video"], + "alias": "可灵3.0 Turbo", + "description": "可灵新任务 API 的 3.0 Turbo 文生视频与首帧图生视频模型", + "iconPath": "https://static.51easyai.com/kling-color.webp", + "billingType": "external-api", + "billingMode": "", + "referenceModel": "", + "modelWeight": null, + "selectable": true, + "rawModel": { + "name": "kling-3.0-turbo", + "types": ["video_generate", "image_to_video"], + "alias": "可灵3.0 Turbo", + "icon_path": "https://static.51easyai.com/kling-color.webp" + } + }'::jsonb AS metadata +) +INSERT INTO base_model_catalog ( + provider_id, + provider_key, + canonical_model_key, + provider_model_name, + model_type, + display_name, + capabilities, + base_billing_config, + default_rate_limit_policy, + metadata, + catalog_type, + default_snapshot, + status +) +SELECT + ( + SELECT id + FROM model_catalog_providers + WHERE provider_key = 'keling' OR provider_code = 'keling' + LIMIT 1 + ), + 'keling', + model.canonical_model_key, + model.provider_model_name, + model.model_type, + model.display_name, + model.capabilities, + model.base_billing_config, + model.default_rate_limit_policy, + jsonb_set(model.metadata, '{rawModel,capabilities}', model.capabilities, true), + 'system', + jsonb_build_object( + 'providerKey', 'keling', + 'canonicalModelKey', model.canonical_model_key, + 'providerModelName', model.provider_model_name, + 'modelType', model.model_type, + 'modelAlias', model.display_name, + 'displayName', model.display_name, + 'capabilities', model.capabilities, + 'baseBillingConfig', model.base_billing_config, + 'defaultRateLimitPolicy', model.default_rate_limit_policy, + 'metadata', jsonb_set(model.metadata, '{rawModel,capabilities}', model.capabilities, true), + 'status', 'active' + ), + 'active' +FROM keling_30_turbo model +ON CONFLICT (canonical_model_key) DO UPDATE +SET provider_id = EXCLUDED.provider_id, + provider_key = EXCLUDED.provider_key, + provider_model_name = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.provider_model_name ELSE base_model_catalog.provider_model_name END, + model_type = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.model_type ELSE base_model_catalog.model_type END, + display_name = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.display_name ELSE base_model_catalog.display_name END, + capabilities = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.capabilities ELSE base_model_catalog.capabilities END, + base_billing_config = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.base_billing_config ELSE base_model_catalog.base_billing_config END, + default_rate_limit_policy = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.default_rate_limit_policy ELSE base_model_catalog.default_rate_limit_policy END, + metadata = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.metadata ELSE base_model_catalog.metadata END, + catalog_type = CASE WHEN base_model_catalog.customized_at IS NULL THEN 'system' ELSE base_model_catalog.catalog_type END, + default_snapshot = CASE WHEN base_model_catalog.customized_at IS NULL THEN EXCLUDED.default_snapshot ELSE base_model_catalog.default_snapshot END, + status = CASE WHEN base_model_catalog.customized_at IS NULL THEN 'active' ELSE base_model_catalog.status END, + updated_at = now(); + +INSERT INTO platform_models ( + platform_id, + base_model_id, + model_name, + provider_model_name, + model_alias, + model_type, + display_name, + capabilities, + pricing_mode, + billing_config, + retry_policy, + rate_limit_policy, + enabled +) +SELECT + platform.id, + base_model.id, + base_model.provider_model_name, + base_model.provider_model_name, + base_model.display_name, + base_model.model_type, + base_model.display_name, + base_model.capabilities, + 'inherit_discount', + base_model.base_billing_config, + '{"enabled":true,"maxAttempts":1}'::jsonb, + base_model.default_rate_limit_policy, + true +FROM integration_platforms platform +JOIN base_model_catalog base_model + ON base_model.canonical_model_key = 'keling:kling-3.0-turbo' +WHERE platform.provider = 'keling' + AND platform.deleted_at IS NULL +ON CONFLICT (platform_id, model_name) DO UPDATE +SET base_model_id = EXCLUDED.base_model_id, + provider_model_name = EXCLUDED.provider_model_name, + model_alias = EXCLUDED.model_alias, + display_name = EXCLUDED.display_name, + model_type = EXCLUDED.model_type, + capabilities = EXCLUDED.capabilities, + pricing_mode = EXCLUDED.pricing_mode, + billing_config = EXCLUDED.billing_config, + retry_policy = EXCLUDED.retry_policy, + rate_limit_policy = EXCLUDED.rate_limit_policy, + enabled = EXCLUDED.enabled, + updated_at = now(); diff --git a/apps/api/migrations/0062_oidc_security_events.sql b/apps/api/migrations/0063_oidc_security_events.sql similarity index 100% rename from apps/api/migrations/0062_oidc_security_events.sql rename to apps/api/migrations/0063_oidc_security_events.sql diff --git a/apps/api/migrations/0064_security_event_connection_idempotency_repair.sql b/apps/api/migrations/0064_security_event_connection_idempotency_repair.sql deleted file mode 100644 index f6a5b0c..0000000 --- a/apps/api/migrations/0064_security_event_connection_idempotency_repair.sql +++ /dev/null @@ -1,15 +0,0 @@ --- 0063 was released before its idempotency table was added. Installations that --- already recorded 0063 need a new immutable migration to repair that drift. -CREATE TABLE IF NOT EXISTS gateway_security_event_connection_idempotency ( - operation text NOT NULL, - idempotency_key text NOT NULL, - request_hash text NOT NULL, - response jsonb NOT NULL, - created_at timestamptz NOT NULL DEFAULT now(), - PRIMARY KEY (operation, idempotency_key), - CONSTRAINT gateway_security_event_connection_idempotency_operation - CHECK (operation IN ('connect','verify','rotate','disconnect')) -); - -CREATE INDEX IF NOT EXISTS idx_gateway_security_event_connection_idempotency_created - ON gateway_security_event_connection_idempotency(created_at); diff --git a/apps/api/migrations/0063_security_event_connections.sql b/apps/api/migrations/0064_security_event_connections.sql similarity index 84% rename from apps/api/migrations/0063_security_event_connections.sql rename to apps/api/migrations/0064_security_event_connections.sql index 21171b8..ad653da 100644 --- a/apps/api/migrations/0063_security_event_connections.sql +++ b/apps/api/migrations/0064_security_event_connections.sql @@ -7,6 +7,8 @@ CREATE TABLE IF NOT EXISTS gateway_security_event_connections ( stream_id uuid, credential_ref text NOT NULL, next_credential_ref text, + management_client_id text, + management_credential_ref text, lifecycle_status text NOT NULL, version bigint NOT NULL DEFAULT 1, last_error_category text, @@ -19,6 +21,10 @@ CREATE TABLE IF NOT EXISTS gateway_security_event_connections ( )), CONSTRAINT gateway_security_event_connection_stream_pair CHECK ( (audience IS NULL AND stream_id IS NULL) OR (audience IS NOT NULL AND stream_id IS NOT NULL) + ), + CONSTRAINT gateway_security_event_management_credential_pair CHECK ( + (management_client_id IS NULL AND management_credential_ref IS NULL) OR + (management_client_id IS NOT NULL AND management_credential_ref IS NOT NULL) ) ); diff --git a/apps/api/migrations/0067_identity_configuration_revisions.sql b/apps/api/migrations/0065_identity_configuration_revisions.sql similarity index 96% rename from apps/api/migrations/0067_identity_configuration_revisions.sql rename to apps/api/migrations/0065_identity_configuration_revisions.sql index 12edebc..f8e8ca3 100644 --- a/apps/api/migrations/0067_identity_configuration_revisions.sql +++ b/apps/api/migrations/0065_identity_configuration_revisions.sql @@ -19,6 +19,9 @@ CREATE TABLE IF NOT EXISTS gateway_identity_configuration_revisions ( legacy_jwt_enabled boolean NOT NULL DEFAULT false, token_introspection boolean NOT NULL DEFAULT false, session_revocation boolean NOT NULL DEFAULT false, + security_event_issuer text, + security_event_configuration_url text, + security_event_audience text, machine_credential_ref text, session_encryption_key_ref text, session_idle_seconds integer NOT NULL DEFAULT 1800 CHECK (session_idle_seconds > 0), diff --git a/apps/api/migrations/0065_security_event_verification_state_repair.sql b/apps/api/migrations/0065_security_event_verification_state_repair.sql deleted file mode 100644 index fd9afcf..0000000 --- a/apps/api/migrations/0065_security_event_verification_state_repair.sql +++ /dev/null @@ -1,37 +0,0 @@ --- 0062 was released before the verification challenge table and the complete --- stream-state columns were added. Installations that already recorded 0062 --- need a new immutable migration to repair that drift. -ALTER TABLE gateway_security_event_stream_state - ADD COLUMN IF NOT EXISTS stream_status text NOT NULL DEFAULT 'unknown', - ADD COLUMN IF NOT EXISTS created_at timestamptz NOT NULL DEFAULT now(); - -DO $$ -BEGIN - IF NOT EXISTS ( - SELECT 1 - FROM pg_constraint - WHERE conrelid = 'gateway_security_event_stream_state'::regclass - AND conname = 'gateway_security_event_stream_state_status' - ) THEN - ALTER TABLE gateway_security_event_stream_state - ADD CONSTRAINT gateway_security_event_stream_state_status - CHECK (stream_status IN ('unknown','enabled','paused','disabled')); - END IF; -END -$$; - -CREATE TABLE IF NOT EXISTS gateway_security_event_verification_challenges ( - issuer text NOT NULL, - audience text NOT NULL, - state_hash bytea NOT NULL, - created_at timestamptz NOT NULL, - expires_at timestamptz NOT NULL, - PRIMARY KEY (issuer, audience, state_hash), - FOREIGN KEY (issuer, audience) - REFERENCES gateway_security_event_stream_state(issuer, audience) ON DELETE CASCADE, - CONSTRAINT gateway_security_event_verification_challenge_hash - CHECK (octet_length(state_hash) = 32) -); - -CREATE INDEX IF NOT EXISTS idx_gateway_security_event_challenges_expiry - ON gateway_security_event_verification_challenges(expires_at); diff --git a/apps/api/migrations/0066_identity_onboarding_exchanges.sql b/apps/api/migrations/0066_identity_onboarding_exchanges.sql new file mode 100644 index 0000000..e2d15f6 --- /dev/null +++ b/apps/api/migrations/0066_identity_onboarding_exchanges.sql @@ -0,0 +1,55 @@ +CREATE TABLE IF NOT EXISTS gateway_identity_onboarding_exchanges ( + id uuid PRIMARY KEY, + revision_id uuid NOT NULL UNIQUE REFERENCES gateway_identity_configuration_revisions(id) ON DELETE CASCADE, + remote_exchange_id uuid NOT NULL UNIQUE, + exchange_token_ref text NOT NULL CHECK (exchange_token_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'), + status text NOT NULL CHECK (status IN ( + 'metadata_pending','preparing','ready','credentials_saved','completed','failed','expired','cancelled' + )), + cleanup_status text NOT NULL DEFAULT 'none' CHECK (cleanup_status IN ('none','pending','completed')), + remote_version bigint NOT NULL CHECK (remote_version > 0), + expires_at timestamptz NOT NULL, + version bigint NOT NULL DEFAULT 1 CHECK (version > 0), + last_error_category text, + auth_center_audit_id text, + last_trace_id text, + cancelled_at timestamptz, + cleanup_completed_at timestamptz, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now(), + CONSTRAINT gateway_identity_onboarding_cleanup_lifecycle_check CHECK ( + (status <> 'cancelled' AND cleanup_status = 'none' AND cancelled_at IS NULL AND cleanup_completed_at IS NULL) OR + (status = 'cancelled' AND cancelled_at IS NOT NULL AND ( + (cleanup_status = 'pending' AND cleanup_completed_at IS NULL) OR + (cleanup_status = 'completed' AND cleanup_completed_at IS NOT NULL) + )) + ), + CONSTRAINT gateway_identity_onboarding_error_category_check CHECK ( + last_error_category IS NULL OR last_error_category IN ( + 'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed', + 'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid', + 'security_event_configuration_invalid','security_event_connection_conflict', + 'security_event_discovery_failed','security_event_management_token_failed', + 'security_event_stream_create_failed','security_event_stream_response_invalid', + 'security_event_receiver_activation_failed','security_event_preparation_failed', + 'security_event_retirement_pending','security_event_credential_handoff_unsafe', + 'security_event_connection_binding_missing','security_event_connection_binding_unavailable', + 'security_event_connection_binding_invalid','security_event_connection_binding_mismatch', + 'pairing_step_failed','cleanup_revision_unavailable','cleanup_security_event_unavailable', + 'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict', + 'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed', + 'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid', + 'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed', + 'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed', + 'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_credential_handoff_unsafe', + 'cleanup_security_event_failed','cleanup_secret_store_failed','cleanup_finalize_failed' + ) + ) +); + +CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_status + ON gateway_identity_onboarding_exchanges(status, updated_at DESC); + +CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_cleanup + ON gateway_identity_onboarding_exchanges(cleanup_status, updated_at) + WHERE cleanup_status = 'pending'; diff --git a/apps/api/migrations/0066_security_event_management_credential.sql b/apps/api/migrations/0066_security_event_management_credential.sql deleted file mode 100644 index d6df346..0000000 --- a/apps/api/migrations/0066_security_event_management_credential.sql +++ /dev/null @@ -1,9 +0,0 @@ -ALTER TABLE gateway_security_event_connections - ADD COLUMN IF NOT EXISTS management_client_id text, - ADD COLUMN IF NOT EXISTS management_credential_ref text; - -ALTER TABLE gateway_security_event_connections - ADD CONSTRAINT gateway_security_event_management_credential_pair CHECK ( - (management_client_id IS NULL AND management_credential_ref IS NULL) OR - (management_client_id IS NOT NULL AND management_credential_ref IS NOT NULL) - ); diff --git a/apps/api/migrations/0070_identity_secret_cleanup_queue.sql b/apps/api/migrations/0067_identity_secret_cleanup_queue.sql similarity index 56% rename from apps/api/migrations/0070_identity_secret_cleanup_queue.sql rename to apps/api/migrations/0067_identity_secret_cleanup_queue.sql index b1a8b9b..2ec7890 100644 --- a/apps/api/migrations/0070_identity_secret_cleanup_queue.sql +++ b/apps/api/migrations/0067_identity_secret_cleanup_queue.sql @@ -1,18 +1,15 @@ CREATE TABLE IF NOT EXISTS gateway_identity_secret_cleanup_queue ( secret_ref text PRIMARY KEY CHECK (secret_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'), not_before timestamptz NOT NULL, - status text NOT NULL DEFAULT 'pending', + status text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','claimed')), claim_token uuid, lease_expires_at timestamptz, created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(), - CONSTRAINT gateway_identity_secret_cleanup_status_check - CHECK (status IN ('pending','claimed')), - CONSTRAINT gateway_identity_secret_cleanup_claim_check - CHECK ( - (status = 'pending' AND claim_token IS NULL AND lease_expires_at IS NULL) OR - (status = 'claimed' AND claim_token IS NOT NULL AND lease_expires_at IS NOT NULL) - ) + CONSTRAINT gateway_identity_secret_cleanup_claim_check CHECK ( + (status = 'pending' AND claim_token IS NULL AND lease_expires_at IS NULL) OR + (status = 'claimed' AND claim_token IS NOT NULL AND lease_expires_at IS NOT NULL) + ) ); CREATE INDEX IF NOT EXISTS idx_gateway_identity_secret_cleanup_due diff --git a/apps/api/migrations/0068_identity_onboarding_exchanges.sql b/apps/api/migrations/0068_identity_onboarding_exchanges.sql deleted file mode 100644 index c3168ac..0000000 --- a/apps/api/migrations/0068_identity_onboarding_exchanges.sql +++ /dev/null @@ -1,23 +0,0 @@ -ALTER TABLE gateway_identity_configuration_revisions - ADD COLUMN IF NOT EXISTS security_event_issuer text, - ADD COLUMN IF NOT EXISTS security_event_configuration_url text, - ADD COLUMN IF NOT EXISTS security_event_audience text; - -CREATE TABLE IF NOT EXISTS gateway_identity_onboarding_exchanges ( - id uuid PRIMARY KEY, - revision_id uuid NOT NULL UNIQUE REFERENCES gateway_identity_configuration_revisions(id) ON DELETE CASCADE, - remote_exchange_id uuid NOT NULL UNIQUE, - exchange_token_ref text NOT NULL CHECK (exchange_token_ref ~ '^[a-z0-9][a-z0-9-]{0,127}$'), - status text NOT NULL CHECK (status IN ('metadata_pending','preparing','ready','credentials_saved','completed','failed','expired')), - remote_version bigint NOT NULL CHECK (remote_version > 0), - expires_at timestamptz NOT NULL, - version bigint NOT NULL DEFAULT 1 CHECK (version > 0), - last_error_category text, - auth_center_audit_id text, - last_trace_id text, - created_at timestamptz NOT NULL DEFAULT now(), - updated_at timestamptz NOT NULL DEFAULT now() -); - -CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_status - ON gateway_identity_onboarding_exchanges(status, updated_at DESC); diff --git a/apps/api/migrations/0071_identity_pairing_start_reservation.sql b/apps/api/migrations/0068_identity_pairing_start_reservation.sql similarity index 90% rename from apps/api/migrations/0071_identity_pairing_start_reservation.sql rename to apps/api/migrations/0068_identity_pairing_start_reservation.sql index c7901f9..4732d6b 100644 --- a/apps/api/migrations/0071_identity_pairing_start_reservation.sql +++ b/apps/api/migrations/0068_identity_pairing_start_reservation.sql @@ -1,6 +1,3 @@ -SET LOCAL lock_timeout = '10s'; -SET LOCAL statement_timeout = '60s'; - CREATE TABLE IF NOT EXISTS gateway_identity_pairing_start_reservation ( singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton), attempt_id uuid NOT NULL UNIQUE, @@ -16,7 +13,7 @@ CREATE TABLE IF NOT EXISTS gateway_identity_pairing_start_reservation ( ); CREATE INDEX IF NOT EXISTS idx_gateway_identity_pairing_start_expiry - ON gateway_identity_pairing_start_reservation(state,expires_at); + ON gateway_identity_pairing_start_reservation(state, expires_at); INSERT INTO gateway_identity_pairing_start_reservation(singleton,attempt_id,state,revision_id,expires_at) SELECT true,exchange.id,'paired',revision.id,exchange.expires_at diff --git a/apps/api/migrations/0069_identity_pairing_cancellation.sql b/apps/api/migrations/0069_identity_pairing_cancellation.sql deleted file mode 100644 index dcd691c..0000000 --- a/apps/api/migrations/0069_identity_pairing_cancellation.sql +++ /dev/null @@ -1,69 +0,0 @@ -SET LOCAL lock_timeout = '10s'; -SET LOCAL statement_timeout = '60s'; - -ALTER TABLE gateway_identity_onboarding_exchanges - DROP CONSTRAINT gateway_identity_onboarding_exchanges_status_check; - -ALTER TABLE gateway_identity_onboarding_exchanges - ADD CONSTRAINT gateway_identity_onboarding_exchanges_status_check - CHECK (status IN ('metadata_pending','preparing','ready','credentials_saved','completed','failed','expired','cancelled')), - ADD COLUMN cleanup_status text NOT NULL DEFAULT 'none', - ADD COLUMN cancelled_at timestamptz, - ADD COLUMN cleanup_completed_at timestamptz; - -ALTER TABLE gateway_identity_onboarding_exchanges - ADD CONSTRAINT gateway_identity_onboarding_cleanup_status_check - CHECK (cleanup_status IN ('none','pending','completed')), - ADD CONSTRAINT gateway_identity_onboarding_cleanup_lifecycle_check - CHECK ( - (status <> 'cancelled' AND cleanup_status = 'none' AND cancelled_at IS NULL AND cleanup_completed_at IS NULL) OR - (status = 'cancelled' AND cancelled_at IS NOT NULL AND ( - (cleanup_status = 'pending' AND cleanup_completed_at IS NULL) OR - (cleanup_status = 'completed' AND cleanup_completed_at IS NOT NULL) - )) - ); - -UPDATE gateway_identity_onboarding_exchanges -SET last_error_category = 'pairing_step_failed' -WHERE last_error_category IS NOT NULL - AND last_error_category NOT IN ( - 'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed', - 'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid', - 'security_event_configuration_invalid','security_event_connection_conflict', - 'security_event_discovery_failed','security_event_management_token_failed', - 'security_event_stream_create_failed','security_event_stream_response_invalid', - 'security_event_receiver_activation_failed','security_event_preparation_failed', - 'security_event_retirement_pending','pairing_step_failed', - 'cleanup_revision_unavailable','cleanup_security_event_unavailable', - 'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict', - 'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed', - 'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid', - 'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed', - 'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed', - 'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_failed', - 'cleanup_secret_store_failed','cleanup_finalize_failed' - ); - -ALTER TABLE gateway_identity_onboarding_exchanges - ADD CONSTRAINT gateway_identity_onboarding_error_category_check - CHECK (last_error_category IS NULL OR last_error_category IN ( - 'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed', - 'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid', - 'security_event_configuration_invalid','security_event_connection_conflict', - 'security_event_discovery_failed','security_event_management_token_failed', - 'security_event_stream_create_failed','security_event_stream_response_invalid', - 'security_event_receiver_activation_failed','security_event_preparation_failed', - 'security_event_retirement_pending','pairing_step_failed', - 'cleanup_revision_unavailable','cleanup_security_event_unavailable', - 'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict', - 'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed', - 'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid', - 'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed', - 'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed', - 'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_failed', - 'cleanup_secret_store_failed','cleanup_finalize_failed' - )); - -CREATE INDEX IF NOT EXISTS idx_gateway_identity_onboarding_cleanup - ON gateway_identity_onboarding_exchanges(cleanup_status, updated_at) - WHERE cleanup_status = 'pending'; diff --git a/apps/api/migrations/0072_identity_secret_cleanup_claim_lifecycle.sql b/apps/api/migrations/0072_identity_secret_cleanup_claim_lifecycle.sql deleted file mode 100644 index 3d27f8c..0000000 --- a/apps/api/migrations/0072_identity_secret_cleanup_claim_lifecycle.sql +++ /dev/null @@ -1,34 +0,0 @@ -SET LOCAL lock_timeout = '10s'; -SET LOCAL statement_timeout = '60s'; - -ALTER TABLE gateway_identity_secret_cleanup_queue - ADD COLUMN IF NOT EXISTS status text, - ADD COLUMN IF NOT EXISTS claim_token uuid, - ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz; - -ALTER TABLE gateway_identity_secret_cleanup_queue - DROP CONSTRAINT IF EXISTS gateway_identity_secret_cleanup_status_check, - DROP CONSTRAINT IF EXISTS gateway_identity_secret_cleanup_claim_check; - -UPDATE gateway_identity_secret_cleanup_queue -SET status='pending',claim_token=NULL,lease_expires_at=NULL,updated_at=now() -WHERE status IS NULL - OR status NOT IN ('pending','claimed') - OR (status='pending' AND (claim_token IS NOT NULL OR lease_expires_at IS NOT NULL)) - OR (status='claimed' AND (claim_token IS NULL OR lease_expires_at IS NULL)); - -ALTER TABLE gateway_identity_secret_cleanup_queue - ALTER COLUMN status SET DEFAULT 'pending', - ALTER COLUMN status SET NOT NULL, - ADD CONSTRAINT gateway_identity_secret_cleanup_status_check - CHECK (status IN ('pending','claimed')), - ADD CONSTRAINT gateway_identity_secret_cleanup_claim_check - CHECK ( - (status='pending' AND claim_token IS NULL AND lease_expires_at IS NULL) OR - (status='claimed' AND claim_token IS NOT NULL AND lease_expires_at IS NOT NULL) - ); - -DROP INDEX IF EXISTS idx_gateway_identity_secret_cleanup_due; - -CREATE INDEX idx_gateway_identity_secret_cleanup_due - ON gateway_identity_secret_cleanup_queue(status,not_before,lease_expires_at,updated_at); diff --git a/apps/api/migrations/0073_identity_pairing_start_reservation_upgrade.sql b/apps/api/migrations/0073_identity_pairing_start_reservation_upgrade.sql deleted file mode 100644 index 7903e9d..0000000 --- a/apps/api/migrations/0073_identity_pairing_start_reservation_upgrade.sql +++ /dev/null @@ -1,89 +0,0 @@ -SET LOCAL lock_timeout = '10s'; -SET LOCAL statement_timeout = '60s'; - --- 0071 was briefly released with only the singleton reservation lease fields. --- Add the durable lifecycle columns without rewriting that already-applied --- migration, then reconcile the singleton with the canonical outstanding --- pairing (when one exists). -ALTER TABLE gateway_identity_pairing_start_reservation - ADD COLUMN IF NOT EXISTS state text, - ADD COLUMN IF NOT EXISTS revision_id uuid, - ADD COLUMN IF NOT EXISTS updated_at timestamptz; - -UPDATE gateway_identity_pairing_start_reservation -SET state=CASE WHEN revision_id IS NULL THEN 'starting' ELSE 'paired' END, - updated_at=COALESCE(updated_at,created_at,now()) -WHERE state IS NULL - OR state NOT IN ('starting','paired') - OR (state='starting' AND revision_id IS NOT NULL) - OR (state='paired' AND revision_id IS NULL) - OR updated_at IS NULL; - -WITH canonical_pairing AS ( - SELECT exchange.id AS attempt_id, - revision.id AS revision_id, - exchange.expires_at - FROM gateway_identity_configuration_revisions revision - JOIN gateway_identity_onboarding_exchanges exchange - ON exchange.revision_id=revision.id - WHERE revision.state IN ('draft','validated','failed') - AND NOT (exchange.status='cancelled' AND exchange.cleanup_status='completed') - ORDER BY revision.created_at DESC,exchange.created_at DESC - LIMIT 1 -) -INSERT INTO gateway_identity_pairing_start_reservation( - singleton,attempt_id,state,revision_id,expires_at,updated_at -) -SELECT true,attempt_id,'paired',revision_id,expires_at,now() -FROM canonical_pairing -ON CONFLICT (singleton) DO UPDATE -SET attempt_id=EXCLUDED.attempt_id, - state=EXCLUDED.state, - revision_id=EXCLUDED.revision_id, - expires_at=EXCLUDED.expires_at, - updated_at=now(); - -ALTER TABLE gateway_identity_pairing_start_reservation - ALTER COLUMN state SET DEFAULT 'starting', - ALTER COLUMN state SET NOT NULL, - ALTER COLUMN updated_at SET DEFAULT now(), - ALTER COLUMN updated_at SET NOT NULL; - -ALTER TABLE gateway_identity_pairing_start_reservation - DROP CONSTRAINT IF EXISTS gateway_identity_pairing_start_state_value_check, - DROP CONSTRAINT IF EXISTS gateway_identity_pairing_start_state_check; - -ALTER TABLE gateway_identity_pairing_start_reservation - ADD CONSTRAINT gateway_identity_pairing_start_state_value_check - CHECK (state IN ('starting','paired')), - ADD CONSTRAINT gateway_identity_pairing_start_state_check CHECK ( - (state='starting' AND revision_id IS NULL) OR - (state='paired' AND revision_id IS NOT NULL) - ); - -DO $migration$ -BEGIN - IF NOT EXISTS ( - SELECT 1 - FROM pg_constraint - WHERE conrelid='gateway_identity_pairing_start_reservation'::regclass - AND contype='f' - AND pg_get_constraintdef(oid) LIKE 'FOREIGN KEY (revision_id)%' - ) THEN - ALTER TABLE gateway_identity_pairing_start_reservation - ADD CONSTRAINT gateway_identity_pairing_start_revision_fk - FOREIGN KEY (revision_id) - REFERENCES gateway_identity_configuration_revisions(id) - ON DELETE RESTRICT; - END IF; -END -$migration$; - -CREATE UNIQUE INDEX IF NOT EXISTS idx_gateway_identity_pairing_start_revision_unique - ON gateway_identity_pairing_start_reservation(revision_id) - WHERE revision_id IS NOT NULL; - -DROP INDEX IF EXISTS idx_gateway_identity_pairing_start_expiry; - -CREATE INDEX idx_gateway_identity_pairing_start_expiry - ON gateway_identity_pairing_start_reservation(state,expires_at); diff --git a/apps/api/migrations/0074_identity_pairing_error_categories.sql b/apps/api/migrations/0074_identity_pairing_error_categories.sql deleted file mode 100644 index 5935c99..0000000 --- a/apps/api/migrations/0074_identity_pairing_error_categories.sql +++ /dev/null @@ -1,32 +0,0 @@ -SET LOCAL lock_timeout = '10s'; -SET LOCAL statement_timeout = '60s'; - --- Pairing recovery added explicit, redacted error categories after 0069 was --- released. Keep the database allow-list in lockstep so PostgreSQL can persist --- the reason an administrator must resolve instead of hiding it behind a CHECK --- violation. -ALTER TABLE gateway_identity_onboarding_exchanges - DROP CONSTRAINT IF EXISTS gateway_identity_onboarding_error_category_check; - -ALTER TABLE gateway_identity_onboarding_exchanges - ADD CONSTRAINT gateway_identity_onboarding_error_category_check - CHECK (last_error_category IS NULL OR last_error_category IN ( - 'metadata_submission_failed','exchange_status_unavailable','credential_delivery_failed', - 'exchange_completion_failed','exchange_expired','remote_exchange_failed','remote_state_invalid', - 'security_event_configuration_invalid','security_event_connection_conflict', - 'security_event_discovery_failed','security_event_management_token_failed', - 'security_event_stream_create_failed','security_event_stream_response_invalid', - 'security_event_receiver_activation_failed','security_event_preparation_failed', - 'security_event_retirement_pending','security_event_credential_handoff_unsafe', - 'security_event_connection_binding_missing','security_event_connection_binding_unavailable', - 'security_event_connection_binding_invalid','security_event_connection_binding_mismatch', - 'pairing_step_failed', - 'cleanup_revision_unavailable','cleanup_security_event_unavailable', - 'cleanup_security_event_configuration_invalid','cleanup_security_event_connection_conflict', - 'cleanup_security_event_discovery_failed','cleanup_security_event_management_token_failed', - 'cleanup_security_event_stream_create_failed','cleanup_security_event_stream_response_invalid', - 'cleanup_security_event_receiver_activation_failed','cleanup_security_event_preparation_failed', - 'cleanup_security_event_retirement_pending','cleanup_security_event_connection_cleanup_failed', - 'cleanup_security_event_secret_cleanup_failed','cleanup_security_event_credential_handoff_unsafe', - 'cleanup_security_event_failed','cleanup_secret_store_failed','cleanup_finalize_failed' - )); diff --git a/apps/web/package.json b/apps/web/package.json index 6b0937a..6b7143f 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -44,6 +44,6 @@ "@types/react-dom": "^19.0.0", "tailwindcss": "^4.3.0", "typescript": "^5.8.0", - "vitest": "3.2.4" + "vitest": "3.2.6" } } diff --git a/apps/web/src/api.test.ts b/apps/web/src/api.test.ts index 6b6e3d4..bdf8210 100644 --- a/apps/web/src/api.test.ts +++ b/apps/web/src/api.test.ts @@ -1,15 +1,18 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { - cancelIdentityPairing, + cancelIdentityPairing, connectSecurityEventTransmitter, + createResponse, deleteOIDCBrowserSession, GatewayApiError, gatewayErrorMessage, + getAPITask, getCurrentUser, + getOpsManagementSkillMetadata, OIDC_BROWSER_SESSION_CREDENTIAL, - startIdentityPairing, - retireIdentityPairingSecurityEventConflict, - validateIdentityRevision, + startIdentityPairing, + retireIdentityPairingSecurityEventConflict, + validateIdentityRevision, } from './api'; describe('Gateway provisioning errors', () => { @@ -200,3 +203,69 @@ describe('OIDC browser session transport', () => { expect(new Headers(init.headers).has('Authorization')).toBe(false); }); }); + +describe('Public Agent resources', () => { + afterEach(() => { + vi.unstubAllGlobals(); + }); + + it('loads operations skill metadata without authorization', async () => { + const metadata = { + name: 'ai-gateway-ops-management', + version: '1.0.2', + displayName: 'AI Gateway 运维管理', + modules: ['model-runtime'], + fileName: 'ai-gateway-ops-management-v1.0.2.zip', + downloadPath: '/api/v1/public/skills/ai-gateway-ops-management/download', + apiDocsJsonPath: '/api-docs-json', + apiDocsYamlPath: '/api-docs-yaml', + }; + const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify(metadata), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + })); + vi.stubGlobal('fetch', fetchMock); + + await expect(getOpsManagementSkillMetadata()).resolves.toEqual(metadata); + + const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]; + expect(url).toContain('/api/v1/public/skills/ai-gateway-ops-management/metadata'); + expect(new Headers(init.headers).has('Authorization')).toBe(false); + }); +}); + +describe('API documentation runner transports', () => { + afterEach(() => { + vi.unstubAllGlobals(); + }); + + it('runs Responses against the public OpenAI-compatible endpoint', async () => { + const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'resp-test', object: 'response' }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + })); + vi.stubGlobal('fetch', fetchMock); + + await createResponse('sk-test', { model: 'gpt-test', input: 'hello', store: true, stream: false }); + + const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]; + expect(url).toContain('/v1/responses'); + expect(init.method).toBe('POST'); + expect(new Headers(init.headers).get('Authorization')).toBe('Bearer sk-test'); + expect(JSON.parse(String(init.body))).toMatchObject({ model: 'gpt-test', input: 'hello', store: true, stream: false }); + }); + + it('retrieves a task from the documented API path', async () => { + const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'task-123', status: 'running' }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + })); + vi.stubGlobal('fetch', fetchMock); + + await getAPITask('sk-test', 'task-123'); + + const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]; + expect(url).toContain('/api/v1/tasks/task-123'); + expect(init.method).toBe('GET'); + }); +}); diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts index ea96648..0946295 100644 --- a/apps/web/src/api.ts +++ b/apps/web/src/api.ts @@ -29,6 +29,7 @@ import type { GatewayTenantUpsertRequest, GatewayNetworkProxyConfig, GatewayPricingEstimate, + GatewaySkillBundleMetadata, GatewayTask, GatewayTaskParamPreprocessingLog, GatewayUser, @@ -95,6 +96,10 @@ export async function getHealth(): Promise { return request('/healthz', { auth: false }); } +export async function getOpsManagementSkillMetadata(): Promise { + return request('/api/v1/public/skills/ai-gateway-ops-management/metadata', { auth: false }); +} + export async function registerLocalAccount(input: { username: string; email?: string; @@ -605,6 +610,26 @@ export async function createCompatibleChatCompletion( }); } +export async function createResponse( + token: string, + input: { + model: string; + input: unknown; + instructions?: string; + previous_response_id?: string; + runMode?: string; + simulation?: boolean; + store?: boolean; + stream?: boolean; + }, +): Promise> { + return request>('/v1/responses', { + body: input, + method: 'POST', + token, + }); +} + export async function createEmbedding( token: string, input: { model: string; input: string | string[]; dimensions?: number; runMode?: string; simulation?: boolean }, @@ -818,6 +843,8 @@ export interface VideoGenerationParams { mode?: 'std' | 'pro'; negative_prompt?: string; cfg_scale?: number; + runMode?: string; + simulation?: boolean; } export async function createVideoGenerationTask( @@ -881,6 +908,10 @@ export async function getTask(token: string, taskId: string): Promise(`/api/workspace/tasks/${taskId}`, { token }); } +export async function getAPITask(token: string, taskId: string): Promise { + return request(`/api/v1/tasks/${taskId}`, { token }); +} + export async function listTaskParamPreprocessing( token: string, taskId: string, diff --git a/apps/web/src/lib/run-task.ts b/apps/web/src/lib/run-task.ts index 9cf43c3..a5fd6ea 100644 --- a/apps/web/src/lib/run-task.ts +++ b/apps/web/src/lib/run-task.ts @@ -1,5 +1,14 @@ import type { GatewayTask } from '@easyai-ai-gateway/contracts'; -import { createCompatibleChatCompletion, createEmbedding, createImageEditTask, createImageGenerationTask, createRerank } from '../api'; +import { + createCompatibleChatCompletion, + createEmbedding, + createImageEditTask, + createImageGenerationTask, + createRerank, + createResponse, + createVideoGenerationTask, + getAPITask, +} from '../api'; import type { TaskForm } from '../types'; export interface RunTaskResponse { @@ -19,6 +28,19 @@ export async function runTask(token: string, task: TaskForm): Promise) }; + } throw new Error(`Unsupported task kind: ${task.kind}`); } @@ -83,6 +123,18 @@ function compatibleTask(task: TaskForm, result: Record): Gatewa } function requestSnapshot(task: TaskForm): Record { + if (task.kind === 'responses') { + return { + model: task.model, + input: task.prompt, + instructions: task.instructions, + previous_response_id: task.previousResponseId, + runMode: 'simulation', + simulation: true, + store: true, + stream: false, + }; + } if (task.kind === 'embeddings') { return { model: task.model, @@ -102,6 +154,19 @@ function requestSnapshot(task: TaskForm): Record { simulation: true, }; } + if (task.kind === 'videos.generations') { + return { + model: task.model, + content: [{ type: 'text', text: task.prompt }], + aspect_ratio: task.aspectRatio ?? '16:9', + resolution: task.resolution ?? '720p', + duration: task.duration ?? 5, + audio: task.outputAudio ?? true, + runMode: 'simulation', + simulation: true, + }; + } + if (task.kind === 'tasks.retrieve') return { taskId: task.taskId }; return { model: task.model, messages: [{ role: 'user', content: task.prompt }], @@ -133,5 +198,7 @@ function modelTypeForKind(kind: TaskForm['kind']) { if (kind === 'reranks') return 'text_rerank'; if (kind === 'images.generations') return 'image_generate'; if (kind === 'images.edits') return 'image_edit'; + if (kind === 'videos.generations') return 'video_generate'; + if (kind === 'tasks.retrieve') return 'task'; return 'text_generate'; } diff --git a/apps/web/src/pages/ApiDocsPage.test.tsx b/apps/web/src/pages/ApiDocsPage.test.tsx new file mode 100644 index 0000000..f3550ce --- /dev/null +++ b/apps/web/src/pages/ApiDocsPage.test.tsx @@ -0,0 +1,107 @@ +import { renderToStaticMarkup } from 'react-dom/server'; +import { describe, expect, it, vi } from 'vitest'; +import type { ApiDocSection, TaskForm } from '../types'; +import { ApiDocsPage } from './ApiDocsPage'; + +describe('ApiDocsPage extended task documentation', () => { + it.each([ + ['guideBaseUrl', '前往创建 API Key'], + ['guideWebhook', 'TASK_PROGRESS_CALLBACK_ENABLED'], + ['guideErrors', '400 invalid_parameter'], + ['guideTesting', 'simulated=true'], + ] as const)('renders the clickable guide page %s', (section, expectedContent) => { + const html = renderDocs(section, { kind: 'chat.completions', model: 'gpt-4o-mini', prompt: '你好' }); + + expect(html).toContain('data-active="true"'); + expect(html).toContain(expectedContent); + expect(html).toContain('指南导航'); + expect(html).not.toContain('/v1/chat/completions'); + }); + + it('documents the OpenAI-compatible Responses request and continuity fields', () => { + const html = renderDocs('responses', { kind: 'responses', model: 'gpt-4o-mini', prompt: '你好' }); + + expect(html).toContain('/v1/responses'); + expect(html).toContain('previous_response_id'); + expect(html).toContain('X-Async'); + expect(html).toContain('连续对话与状态归属'); + }); + + it('documents video generation parameters and async retrieval guidance', () => { + const html = renderDocs('videoGeneration', { kind: 'videos.generations', model: '豆包Seedance-2.0', prompt: '雪山日出' }); + + expect(html).toContain('/api/v1/videos/generations'); + expect(html).toContain('aspect_ratio'); + expect(html).toContain('reference_image'); + expect(html).toContain('任务取回接口'); + }); + + it('documents async mode as a body-independent capability', () => { + const html = renderDocs('asyncMode', { kind: 'chat.completions', model: 'gpt-4o-mini', prompt: '你好' }); + + expect(html).toContain('X-Async'); + expect(html).toContain('原请求 Header'); + expect(html).toContain('同步与异步的区别'); + expect(html).toContain('异步受理响应'); + expect(html).not.toContain('/api/v1/videos/generations'); + expect(html).not.toContain('Body 参数'); + expect(html).not.toContain('视频模型 ID'); + }); + + it.each(['chat', 'responses', 'embeddings', 'reranks', 'imageGeneration', 'imageEdit', 'videoGeneration'] as const)( + 'shows the shared X-Async switch on the %s task API', + (section) => { + const html = renderDocs(section, { kind: 'chat.completions', model: 'gpt-4o-mini', prompt: '你好' }); + + expect(html).toContain('X-Async'); + }, + ); + + it('renders nested objects and object arrays recursively', () => { + const html = renderDocs('videoGeneration', { kind: 'videos.generations', model: '豆包Seedance-2.0', prompt: '雪山日出' }); + + expect(html).toContain('array<object>'); + expect(html).toContain('data-depth="1"'); + expect(html).toContain('data-depth="4"'); + expect(html).toContain('inline_element'); + expect(html).toContain('refer_images'); + expect(html).toContain('slot_key'); + }); + + it('renders task retrieval as GET with a path parameter instead of a request body', () => { + const html = renderDocs('taskRetrieve', { kind: 'tasks.retrieve', model: 'task', prompt: '', taskId: 'task-123' }); + + expect(html).toContain('GET'); + expect(html).toContain('/api/v1/tasks/task-123'); + expect(html).toContain('Path 参数'); + expect(html).toContain('响应 Body'); + expect(html).toContain('result'); + expect(html).toContain('billingSummary'); + expect(html).toContain('attempts'); + expect(html).toContain('成功响应示例'); + expect(html).toContain('Task ID'); + expect(html).not.toContain('请求 Body'); + }); +}); + +function renderDocs(activeDocSection: ApiDocSection, taskForm: TaskForm) { + return renderToStaticMarkup( + , + ); +} diff --git a/apps/web/src/pages/ApiDocsPage.tsx b/apps/web/src/pages/ApiDocsPage.tsx index 73bc999..9cb76bd 100644 --- a/apps/web/src/pages/ApiDocsPage.tsx +++ b/apps/web/src/pages/ApiDocsPage.tsx @@ -1,7 +1,8 @@ -import { useEffect, useMemo, type FormEvent } from 'react'; -import type { GatewayApiKey, GatewayTask } from '@easyai-ai-gateway/contracts'; -import { BookOpen, KeyRound, Play, Search, Send } from 'lucide-react'; -import { Badge, Button, Select, Textarea } from '../components/ui'; +import { Fragment, useEffect, useMemo, useState, type CSSProperties, type FormEvent, type ReactNode } from 'react'; +import type { GatewayApiKey, GatewaySkillBundleMetadata, GatewayTask } from '@easyai-ai-gateway/contracts'; +import { BookOpen, Download, ExternalLink, FileJson, KeyRound, Play, Search, Send, Wrench } from 'lucide-react'; +import { Badge, Button, Input, Select, Textarea } from '../components/ui'; +import { getOpsManagementSkillMetadata, resolveApiAssetUrl } from '../api'; import type { ApiDocSection, LoadState, TaskForm, TaskKind } from '../types'; import { ApiKeySelect, apiKeyNoticeText, resolveSelectedApiKeyId } from './playground-shared'; @@ -10,31 +11,71 @@ interface ApiDocItem { key: ApiDocSection; kind?: TaskKind; lead: string; - method: string; - path: string; + method?: 'GET' | 'POST'; + path?: string; title: string; } -const docs: ApiDocItem[] = [ +interface ApiDocParam { + children?: ApiDocParam[]; + name: string; + required?: boolean; + type: string; + value: string; +} + +type ApiGuideSection = Extract; + +interface ApiGuideItem { + group: '指南'; + key: ApiGuideSection; + lead: string; + title: string; +} + +export const apiDocs: ApiDocItem[] = [ { key: 'chat', group: '文本', kind: 'chat.completions', method: 'POST', path: '/v1/chat/completions', title: 'Chat Completions', lead: 'OpenAI 兼容的对话接口，支持本地 API Key 授权、simulation 测试和非流式/流式响应。' }, + { key: 'responses', group: '文本', kind: 'responses', method: 'POST', path: '/v1/responses', title: 'Responses', lead: 'OpenAI 兼容的 Responses 接口，原生支持 input、previous_response_id、工具调用和流式输出；不支持原生 Responses 的模型会由网关转换到 Chat Completions。' }, { key: 'embeddings', group: '文本', kind: 'embeddings', method: 'POST', path: '/v1/embeddings', title: '文本向量 Embeddings', lead: 'OpenAI 兼容的文本向量接口，可直接用 input 数组或字符串生成 embedding，API Key 需要 embedding 权限。' }, { key: 'reranks', group: '文本', kind: 'reranks', method: 'POST', path: '/v1/reranks', title: '文本重排序 Reranks', lead: 'OpenAI 风格的重排序接口，传入 query 和 documents 后返回 relevance_score，API Key 需要 rerank 权限。' }, { key: 'imageGeneration', group: '图片', kind: 'images.generations', method: 'POST', path: '/v1/images/generations', title: '创建图片', lead: 'OpenAI 兼容的图片生成接口，支持 prompt、size、quality 和 simulation 测试。' }, { key: 'imageEdit', group: '图片', kind: 'images.edits', method: 'POST', path: '/v1/images/edits', title: '编辑图片', lead: 'OpenAI 兼容的图片编辑接口，支持 image、mask、prompt 和 simulation 测试。' }, + { key: 'videoGeneration', group: '视频', kind: 'videos.generations', method: 'POST', path: '/api/v1/videos/generations', title: '生成视频', lead: '视频生成任务接口，支持文生视频、首尾帧、图片/视频/音频参考，以及时长、分辨率、画幅和声音等模型能力参数。' }, + { key: 'asyncMode', group: '异步任务', title: '异步模式', lead: '所有 AI 任务创建接口使用同一种异步开启方式：保留原接口和原请求 Body，只需增加 X-Async: true。' }, + { key: 'taskRetrieve', group: '异步任务', kind: 'tasks.retrieve', method: 'GET', path: '/api/v1/tasks/{taskID}', title: '取回任务', lead: '使用异步提交返回的 taskId 查询任务状态、结果、错误、用量、计费和执行尝试；queued、running、submitting 为进行中状态。' }, { key: 'pricing', group: '计费', method: 'POST', path: '/api/v1/pricing/estimate', title: '价格预估', lead: '按请求体估算输入输出 token、模型倍率和折扣后的预估费用。' }, { key: 'files', group: '文件', method: 'POST', path: '/v1/files/upload', title: '上传文件', lead: '上传在线测试所需的图片、音频或视频资源，后续请求可复用返回的文件 URL。' }, ]; -const guideItems = ['获取 Base URL 和 API Key', '通知设置-WebHook 参数介绍', '错误码', '测试模式']; +const guideItems: ApiGuideItem[] = [ + { key: 'guideBaseUrl', group: '指南', title: '获取 Base URL 和 API Key', lead: '确认当前部署环境的网关地址，创建 API Key，并使用 Bearer 鉴权调用公开接口。' }, + { key: 'guideWebhook', group: '指南', title: '通知设置-WebHook 参数介绍', lead: '了解任务进度 WebHook 的启用方式、回调结构、可靠投递机制和公开 API 的状态取回方式。' }, + { key: 'guideErrors', group: '指南', title: '错误码', lead: '根据 HTTP 状态、error.code、requestId 和异步任务错误字段快速定位请求失败原因。' }, + { key: 'guideTesting', group: '指南', title: '测试模式', lead: '使用 simulation 完整验证鉴权、路由、队列、限流、进度和结果归一，而不向真实供应商提交任务。' }, +]; const taskKindOptions = [ ['chat.completions', 'Chat'], + ['responses', 'Responses'], ['embeddings', '文本向量'], ['reranks', '重排序'], ['images.generations', '生图'], ['images.edits', '图像编辑'], + ['videos.generations', '视频生成'], + ['tasks.retrieve', '取回任务'], ] as const; +const defaultOpsSkillMetadata: GatewaySkillBundleMetadata = { + name: 'ai-gateway-ops-management', + version: '', + displayName: 'AI Gateway 运维管理', + modules: ['model-runtime'], + fileName: 'ai-gateway-ops-management.zip', + downloadPath: '/api/v1/public/skills/ai-gateway-ops-management/download', + apiDocsJsonPath: '/api-docs-json', + apiDocsYamlPath: '/api-docs-yaml', +}; + export function ApiDocsPage(props: { activeDocSection: ApiDocSection; apiKeySecretsById: Record; @@ -52,19 +93,51 @@ export function ApiDocsPage(props: { onSubmitTask: (event: FormEvent) => void; onTaskFormChange: (value: TaskForm) => void; }) { - const current = docs.find((item) => item.key === props.activeDocSection) ?? docs[0]; - const isFileDoc = current.key === 'files'; + const activeGuide = guideItems.find((item) => item.key === props.activeDocSection); + const currentApiDoc = apiDocs.find((item) => item.key === props.activeDocSection) ?? (activeGuide ? undefined : apiDocs[0]); + const current = activeGuide ?? currentApiDoc ?? apiDocs[0]; + const [opsSkillMetadata, setOpsSkillMetadata] = useState(defaultOpsSkillMetadata); + const isFileDoc = currentApiDoc?.key === 'files'; + const isTaskRetrieveDoc = currentApiDoc?.key === 'taskRetrieve'; + const isAsyncModeDoc = currentApiDoc?.key === 'asyncMode'; + const runnerAvailable = Boolean(currentApiDoc?.kind && currentApiDoc.method && currentApiDoc.path); const apiKeyNotice = apiKeyNoticeText(props.apiKeys, props.apiKeySecretsById); const activeApiKeyId = resolveSelectedApiKeyId(props.apiKeys, props.apiKeySecretsById, props.selectedApiKeyId); - const bodyExample = useMemo(() => requestBodyExample(props.taskForm), [props.taskForm]); + const bodyExample = useMemo( + () => requestBodyExample(props.taskForm, currentApiDoc?.key ?? 'chat'), + [currentApiDoc?.key, props.taskForm], + ); + const runnerPath = currentApiDoc?.path + ? isTaskRetrieveDoc + ? currentApiDoc.path.replace('{taskID}', props.taskForm.taskId?.trim() || '{taskID}') + : currentApiDoc.path + : ''; useEffect(() => { - if (current.kind && props.taskForm.kind !== current.kind) { - props.onTaskFormChange(defaultTaskForKind(current.kind, props.taskForm)); + if (currentApiDoc?.kind && props.taskForm.kind !== currentApiDoc.kind) { + props.onTaskFormChange(defaultTaskForDoc(currentApiDoc.kind, props.taskForm, props.taskResult)); } - }, [current.kind, props.taskForm.kind]); + }, [currentApiDoc?.kind, props.taskForm.kind, props.taskResult?.id]); + + useEffect(() => { + let active = true; + getOpsManagementSkillMetadata() + .then((metadata) => { + if (active) setOpsSkillMetadata(metadata); + }) + .catch(() => { + // Keep stable public fallback paths visible when metadata is temporarily unavailable. + }); + return () => { + active = false; + }; + }, []); function handleSubmit(event: FormEvent) { + if (!runnerAvailable) { + event.preventDefault(); + return; + } if (!props.canRun) { event.preventDefault(); props.onLogin(); @@ -75,13 +148,17 @@ export function ApiDocsPage(props: { function handleDocClick(item: ApiDocItem) { if (item.kind) { - props.onTaskFormChange(defaultTaskForKind(item.kind, props.taskForm)); + props.onTaskFormChange(defaultTaskForDoc(item.kind, props.taskForm, props.taskResult)); } props.onDocSectionChange(item.key); } + function handleGuideClick(item: ApiGuideItem) { + props.onDocSectionChange(item.key); + } + function handleKindChange(kind: TaskKind) { - props.onTaskFormChange(defaultTaskForKind(kind, props.taskForm)); + props.onTaskFormChange(defaultTaskForDoc(kind, props.taskForm, props.taskResult)); const nextSection = docSectionForKind(kind); if (nextSection !== props.activeDocSection) { props.onDocSectionChange(nextSection); @@ -99,8 +176,15 @@ export function ApiDocsPage(props: { - ({ title }))} /> - {groupDocs(docs).map((group) => ( + ({ + active: item.key === props.activeDocSection, + title: item.title, + onClick: () => handleGuideClick(item), + }))} + /> + {groupDocs(apiDocs).map((group) => (

{current.group}

{current.title}

-
- {current.method} - {current.path} -
+ {currentApiDoc?.method && currentApiDoc.path && ( +
+ + {currentApiDoc.path} +
+ )}

{current.lead}

-
-
-

Header 参数

- -
- - - -
+ {isAsyncModeDoc ? ( + + ) : currentApiDoc ? ( + <> + {!isTaskRetrieveDoc && } -
-
-

Body 参数

- application/json -
- {isFileDoc ? ( - <> - - - - ) : ( - bodyParamRows(current.key).map((row) => ( - - )) - )} -
+
+
+

Header 参数

+ +
+ {currentApiDoc.method !== 'GET' && } + + + {supportsAsyncMode(currentApiDoc.key) && ( + + )} +
+ +
+
+

{isTaskRetrieveDoc ? 'Path 参数' : 'Body 参数'}

+ {!isTaskRetrieveDoc && {isFileDoc ? 'multipart/form-data' : 'application/json'}} +
+ {isTaskRetrieveDoc ? ( + + ) : isFileDoc ? ( + <> + + + + ) : ( + + )} +
+ + {isTaskRetrieveDoc && } + + + ) : activeGuide ? ( + + ) : null}