AGENT SKILL
cortexcloud-api-category
暂无简介
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-24
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档skill.json368 B
03 SKILL.md 正文
cortexcloud-api-category
Build a new CortexCloud API category
Use when adding a new endpoint group behind x402/MPP on CortexCloud
(e.g. the ML and Automation tiers already built this way). Reuse, don't
rebuild: x402/MPP settlement, X402RateLimitMiddleware,
InputValidationMiddleware, ROUTE_PRICING/ROUTE_DESCRIPTIONS/
FREE_ROUTES, Bazaar _TOOLS, OpenAPI regen, BaseProvider/pricing,
feature flags.
Recipe (minimal diff)
app/core/config.py: masterX_ENABLED(default False) + per-endpoint gatesX_TRANSFORM_ENABLEDetc. (default True) + any secrets.app/x402/pricing.py: addX_FLOORdict +x_price_usd(ep)usingpegged_price(0.0, floor=...); register ROUTE_PRICING / ROUTE_DESCRIPTIONS / FREE_ROUTES entries (incl. a free/v1/x/estimate).app/middleware/x402.py: addelif path.startswith("/v1/x/")branch that (a) returns 503 before the 402 challenge if disabled (see pitfall), (b) setsrequest.state.category="x"+provider_cost_usd.app/api/x.py: router + routes;_disabled(ep)returns 503 when master or per-endpoint flag off; free/estimatemust NOT gate on master flag.app/x402/bazaar.py: add_TOOLSentries (paid + free).app/main.py:include_router(one line, in the additive block).tests/test_x.py+scripts/x_paid_smoke.py(reuse SDKsign_payment).- Branch from
main(NOT a sibling feature branch — keep others frozen).X_ENABLED=false. Do NOT merge/deploy without explicit approval.
Pitfalls (learned the hard way)
- MIDDLEWARE PRE-402 GATE (charge-then-fail trap). The x402 middleware
runs OUTER to your route. If you gate only in the route (
_disabled()), the middleware already emitted a 402 payment challenge → the client pays, then hits your 503. Gate in the middleware branch BEFOREusd_to_usdc_atomic(price_str)/ challenge build:if not settings.X_ENABLED: return JSONResponse(503, {...}). Seereferences/middleware-gate.mdfor the exact snippet. - Free
/estimatemust bypass the master gate. If it calls_disabled()it 503s when the category is disabled, hiding pricing. Gate only paid routes. - JSONB import:
from sqlalchemy.dialects.postgresql import JSONB(NOTfrom sqlalchemy import JSONB— ImportError on SQLAlchemy 2.x). - Self-hosted pricing: provider cost ~$0 →
pegged_price(0.0, floor=X)returns exactly X (max(X, 0*1.35+0.0015)). Use per-endpoint floors. - Provider-funding blocker, don't fake green. If an endpoint can't be validated because the upstream needs credits (OpenRouter 0 credits → paid model 402; free models throttled 429/502; fal TOP_UP-locked; Replicate needs credit — a saved card is NOT credit), report the blocker honestly. Do NOT keep trying free providers or hack code to force a green smoke. Self-hosted endpoints (no external provider) validate immediately via paid smoke. This is a standing user preference, not optional.
- 5xx after x402 settlement charges the customer — there is no refund mechanism in the platform. Keep provider calls behind payment; fail fast on invalid input. This is a platform-wide limitation, not a per-category fix.
Reuse pointers
- Paid smoke:
sdk/python/cortexcloud/signing.py: sign_payment(challenge, key)→ resubmit withpayment-signatureheader. Same pattern as Data/ML smoke. - HMAC webhook signatures:
hmac.new(secret, body, sha256).hexdigest(), headerX-Cortex-Signature: sha256=<sig>. - SSRF guard (for egress endpoints): block private/loopback/link-local/ metadata (169.254.169.254) IPs, re-check resolved IPs (DNS-rebinding), validate redirect targets through the same guard; cap body + timeout.
- Postgres for durable state (e.g. scheduled jobs): define an ORM model in
app/models/, register it inapp/models/__init__.py, create the table withAsyncEngine.begin() -> conn.run_sync(Model.__table__.create, checkfirst=True)(notAsyncEngine.run_sync— that API doesn't exist).