feat(docs): add Skill Proxy Migration Guide for transitioning to gateway-based API calls

- Introduced a new third-party proxy package for handling async task APIs.
- Implemented billing client with reserve and finalize functionalities.
- Created an in-memory ledger to track call states and ensure idempotency.
- Added route classification for submit and query requests.
- Configured third-party provider settings and routes in the application config.
- Updated local backend to support Docker networking for sandbox containers.

backend/app/gateway/app.py

@@ -1,4 +1,5 @@
 import logging
+import os
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
@@ -17,21 +18,39 @@ from app.gateway.routers import (
     runs,
     skills,
     suggestions,
+    third_party,
     thread_runs,
     threads,
     uploads,
 )
 from deerflow.config.app_config import get_app_config
 
-# Configure logging with env override
+# Configure logging (prefer config.yaml log_level, fallback to LOG_LEVEL env)
-import os
+env_log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
-log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
+log_level = env_log_level
+try:
+    configured_log_level = get_app_config().log_level.upper()
+    if configured_log_level:
+        log_level = configured_log_level
+except Exception:
+    # Keep startup resilient even if config is temporarily invalid/unavailable.
+    log_level = env_log_level
+
+resolved_log_level = getattr(logging, log_level, logging.INFO)
 logging.basicConfig(
-    level=getattr(logging, log_level, logging.INFO),
+    level=resolved_log_level,
     format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
     datefmt="%Y-%m-%d %H:%M:%S",
+    # Uvicorn installs logging handlers before app import; force reconfigure so
+    # config.yaml log_level reliably takes effect.
+    force=True,
 )
 
+# Ensure package loggers inherit the intended level even under custom handlers.
+logging.getLogger().setLevel(resolved_log_level)
+logging.getLogger("app").setLevel(resolved_log_level)
+logging.getLogger("deerflow").setLevel(resolved_log_level)
+
 logger = logging.getLogger(__name__)
 
 
@@ -162,6 +181,10 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
                 "name": "health",
                 "description": "Health check and system status endpoints",
             },
+            {
+                "name": "third-party-proxy",
+                "description": "Universal third-party API proxy with billing integration (/api/proxy/{provider}/...)",
+            },
         ],
     )
 
@@ -207,6 +230,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
     # Stateless Runs API (stream/wait without a pre-existing thread)
     app.include_router(runs.router)
 
+    # Third-party API proxy with billing integration
+    app.include_router(third_party.router)
+
     @app.get("/health", tags=["health"])
     async def health_check() -> dict:
         """Health check endpoint.

backend/app/gateway/routers/__init__.py

@@ -1,3 +1,3 @@
-from . import artifacts, assistants_compat, mcp, models, skills, suggestions, thread_runs, threads, uploads
+from . import artifacts, assistants_compat, mcp, models, skills, suggestions, third_party, thread_runs, threads, uploads
 
-__all__ = ["artifacts", "assistants_compat", "mcp", "models", "skills", "suggestions", "threads", "thread_runs", "uploads"]
+__all__ = ["artifacts", "assistants_compat", "mcp", "models", "skills", "suggestions", "third_party", "threads", "thread_runs", "uploads"]

backend/app/gateway/routers/third_party.py

@@ -0,0 +1,403 @@
+"""Universal third-party API proxy router with integrated billing.
+
+Endpoint:  ANY /api/proxy/{provider}/{path...}
+
+The caller (a sandbox skill script) should set:
+  X-Thread-Id: <thread_id>          — used for billing reservation (injected via THREAD_ID env var)
+  X-Idempotency-Key: <uuid>         — optional; deduplicates submit calls
+
+The gateway automatically:
+  1. Injects the provider's API key from the configured env var.
+  2. For *submit* routes: reserves billing, forwards, records task state.
+  3. For *query* routes: forwards, detects terminal status, finalizes billing once.
+  4. For all other routes: transparent passthrough, no billing side-effects.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, Response
+
+from app.gateway.third_party_proxy import billing, proxy
+from app.gateway.third_party_proxy.ledger import CallRecord, get_ledger
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/proxy", tags=["third-party-proxy"])
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+@router.api_route("/{provider}/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH"])
+async def proxy_request(provider: str, path: str, request: Request) -> Response:
+    """Universal proxy endpoint for third-party API calls with billing integration."""
+    provider_config = proxy.get_provider_config(provider)
+    if provider_config is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Provider '{provider}' is not configured or the proxy is disabled.",
+        )
+
+    method = request.method
+    # Normalise: ensure leading slash so patterns like /openapi/v2/** match correctly
+    path = "/" + path.lstrip("/")
+
+    thread_id = request.headers.get("x-thread-id")
+    idempotency_key = request.headers.get("x-idempotency-key")
+
+    body = await request.body()
+    request_json: dict[str, Any] | None = _try_parse_json(body)
+
+    submit_route = proxy.match_submit_route(provider_config, method, path)
+    query_route = proxy.match_query_route(provider_config, method, path)
+    logger.info("[ThirdPartyProxy] route=%s provider=%s method=%s path=%s", "submit" if submit_route else "query" if query_route else "passthrough", provider, method, path)
+
+    if submit_route:
+        return await _handle_submit(
+            provider=provider,
+            provider_config=provider_config,
+            method=method,
+            path=path,
+            request=request,
+            body=body,
+            thread_id=thread_id,
+            idempotency_key=idempotency_key,
+            task_id_jsonpath=submit_route.task_id_jsonpath,
+            route_frozen_amount=submit_route.frozen_amount,
+            route_frozen_type=submit_route.frozen_type,
+        )
+
+    if query_route:
+        return await _handle_query(
+            provider=provider,
+            provider_config=provider_config,
+            method=method,
+            path=path,
+            request=request,
+            body=body,
+            request_json=request_json,
+            query_route=query_route,
+        )
+
+    # Pure passthrough — no billing, no state
+    return await _passthrough(
+        provider_config=provider_config,
+        method=method,
+        path=path,
+        request=request,
+        body=body,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Submit handler
+# ---------------------------------------------------------------------------
+
+
+async def _handle_submit(
+    *,
+    provider: str,
+    provider_config,
+    method: str,
+    path: str,
+    request: Request,
+    body: bytes,
+    thread_id: str | None,
+    idempotency_key: str | None,
+    task_id_jsonpath: str,
+    route_frozen_amount: float | None,
+    route_frozen_type: int | None,
+) -> Response:
+    ledger = get_ledger()
+
+    # Idempotency: if we've already handled this exact submit, return the cached response
+    if idempotency_key:
+        existing = ledger.get_by_idempotency_key(provider, idempotency_key)
+        if existing is not None and existing.last_response is not None:
+            logger.info("[ThirdPartyProxy] idempotent submit: proxy_call_id=%s", existing.proxy_call_id)
+            return _proxy_response(existing.last_response, existing.proxy_call_id)
+
+    record = ledger.create(provider, thread_id, idempotency_key)
+
+    # Reserve billing before touching the provider
+    reserve_frozen_amount = route_frozen_amount if route_frozen_amount is not None else provider_config.frozen_amount
+    reserve_frozen_type = route_frozen_type if route_frozen_type is not None else provider_config.frozen_type
+    frozen_id = await billing.reserve(
+        thread_id=thread_id,
+        call_id=record.call_id,
+        provider=provider,
+        operation=path,
+        frozen_amount=reserve_frozen_amount,
+        frozen_type=reserve_frozen_type,
+    )
+    if frozen_id:
+        ledger.set_reserved(record.proxy_call_id, frozen_id)
+
+    # Forward to provider
+    try:
+        status_code, resp_headers, resp_body = await proxy.forward_request(
+            provider_config=provider_config,
+            method=method,
+            path=path,
+            headers=dict(request.headers),
+            body=body,
+            query_params=str(request.query_params),
+        )
+    except Exception as exc:
+        await _finalize_zero(frozen_id, record.proxy_call_id, "error exception")
+        raise HTTPException(status_code=502, detail=f"Provider unreachable: {exc}") from exc
+
+    resp_json = _try_parse_json(resp_body)
+
+    # HTTP-level failure
+    if status_code >= 400:
+        reason = f"error_http_{status_code}"
+        await _finalize_zero(frozen_id, record.proxy_call_id, reason)
+        if resp_json is not None:
+            ledger.update_response(record.proxy_call_id, resp_json)
+        return Response(content=resp_body, status_code=status_code, headers=resp_headers, media_type="application/json")
+
+    # Extract task_id from response; no task_id means provider rejected at business level
+    provider_task_id: str | None = None
+    if resp_json is not None:
+        raw = proxy.jsonpath_get(resp_json, task_id_jsonpath)
+        if raw is not None:
+            provider_task_id = str(raw)
+
+    if provider_task_id:
+        ledger.set_running(record.proxy_call_id, provider_task_id)
+    else:
+        # No async task ID usually means provider-side business rejection.
+        # Propagate errorCode (if present) into finalize_reason.
+        error_code = None
+        if resp_json is not None:
+            raw_error_code = resp_json.get("errorCode")
+            if raw_error_code is None:
+                raw_error_code = resp_json.get("code")
+            if raw_error_code is not None:
+                error_code = str(raw_error_code)
+
+        finalize_reason = error_code or "no_task_id"
+        await _finalize_zero(frozen_id, record.proxy_call_id, finalize_reason)
+
+    if resp_json is not None:
+        ledger.update_response(record.proxy_call_id, resp_json)
+
+    return _proxy_response(resp_json or {}, record.proxy_call_id, status_code, resp_headers)
+
+
+# ---------------------------------------------------------------------------
+# Query handler
+# ---------------------------------------------------------------------------
+
+
+async def _handle_query(
+    *,
+    provider: str,
+    provider_config,
+    method: str,
+    path: str,
+    request: Request,
+    body: bytes,
+    request_json: dict[str, Any] | None,
+    query_route,
+) -> Response:
+    ledger = get_ledger()
+
+    # Locate the call record by provider_task_id embedded in the request body
+    provider_task_id: str | None = None
+    if request_json:
+        raw = proxy.jsonpath_get(request_json, query_route.request_task_id_jsonpath)
+        if raw is not None:
+            provider_task_id = str(raw)
+
+    record: CallRecord | None = None
+    if provider_task_id:
+        record = ledger.get_by_task_id(provider, provider_task_id)
+
+    # Already at terminal state — return cached result without calling the provider again
+    if record is not None and ledger.is_finalized(record.proxy_call_id) and record.last_response is not None:
+        logger.info("[ThirdPartyProxy] query already finalized, returning cache: proxy_call_id=%s", record.proxy_call_id)
+        return _proxy_response(record.last_response, record.proxy_call_id)
+
+    # Forward query to provider
+    try:
+        status_code, resp_headers, resp_body = await proxy.forward_request(
+            provider_config=provider_config,
+            method=method,
+            path=path,
+            headers=dict(request.headers),
+            body=body,
+            query_params=str(request.query_params),
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"Provider query failed: {exc}") from exc
+
+    resp_json = _try_parse_json(resp_body)
+    if status_code >= 400 or resp_json is None:
+        return Response(content=resp_body, status_code=status_code, headers=resp_headers, media_type="application/json")
+
+    # Detect terminal status in the response
+    status_value = proxy.jsonpath_get(resp_json, query_route.status_jsonpath)
+    status_str = str(status_value) if status_value is not None else None
+    is_success = status_str in query_route.success_values
+    is_failure = status_str in query_route.failure_values
+
+    logger.debug(
+        "[ThirdPartyProxy] query terminal check: provider=%s task_id=%s status=%s is_success=%s is_failure=%s",
+        provider,
+        provider_task_id,
+        status_str,
+        is_success,
+        is_failure,
+    )
+
+    if record is not None and (is_success or is_failure):
+        logger.info(
+            "[ThirdPartyProxy] finalize candidate: proxy_call_id=%s provider_task_id=%s terminal_status=%s",
+            record.proxy_call_id,
+            provider_task_id,
+            status_str,
+        )
+        # Atomically claim finalize rights — only one concurrent query wins
+        if ledger.try_claim_finalize(record.proxy_call_id):
+            logger.info(
+                "[ThirdPartyProxy] finalize claimed: proxy_call_id=%s",
+                record.proxy_call_id,
+            )
+            final_amount: float = 0.0
+            if is_success and query_route.usage_jsonpath:
+                raw_amount = proxy.jsonpath_get(resp_json, query_route.usage_jsonpath)
+                try:
+                    final_amount = float(raw_amount) if raw_amount is not None else 0.0
+                except (TypeError, ValueError):
+                    final_amount = 0.0
+
+            logger.debug(
+                "[ThirdPartyProxy] finalize amount resolved: proxy_call_id=%s final_amount=%s usage_path=%s",
+                record.proxy_call_id,
+                final_amount,
+                query_route.usage_jsonpath,
+            )
+
+            task_state = "SUCCESS" if is_success else "FAILED"
+            finalize_reason = "success" if is_success else "error"
+
+            logger.info(
+                "[ThirdPartyProxy] finalize start: proxy_call_id=%s reason=%s task_state=%s has_frozen_id=%s",
+                record.proxy_call_id,
+                finalize_reason,
+                task_state,
+                bool(record.frozen_id),
+            )
+
+            if record.frozen_id:
+                ok = await billing.finalize(
+                    frozen_id=record.frozen_id,
+                    final_amount=final_amount,
+                    finalize_reason=finalize_reason,
+                )
+                logger.info(
+                    "[ThirdPartyProxy] finalize result: proxy_call_id=%s ok=%s",
+                    record.proxy_call_id,
+                    ok,
+                )
+                if ok:
+                    ledger.set_finalized(record.proxy_call_id, task_state)
+                else:
+                    ledger.set_finalize_failed(record.proxy_call_id, task_state)
+            else:
+                logger.info(
+                    "[ThirdPartyProxy] finalize skipped billing call (no frozen_id): proxy_call_id=%s",
+                    record.proxy_call_id,
+                )
+                ledger.set_finalized(record.proxy_call_id, task_state)
+
+            ledger.update_response(record.proxy_call_id, resp_json)
+        else:
+            logger.info(
+                "[ThirdPartyProxy] finalize claim denied (already processed): proxy_call_id=%s",
+                record.proxy_call_id,
+            )
+
+    proxy_call_id = record.proxy_call_id if record else None
+    return _proxy_response(resp_json, proxy_call_id, status_code, resp_headers)
+
+
+# ---------------------------------------------------------------------------
+# Passthrough handler
+# ---------------------------------------------------------------------------
+
+
+async def _passthrough(*, provider_config, method: str, path: str, request: Request, body: bytes) -> Response:
+    try:
+        status_code, resp_headers, resp_body = await proxy.forward_request(
+            provider_config=provider_config,
+            method=method,
+            path=path,
+            headers=dict(request.headers),
+            body=body,
+            query_params=str(request.query_params),
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"Provider request failed: {exc}") from exc
+
+    return Response(content=resp_body, status_code=status_code, headers=resp_headers)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+async def _finalize_zero(frozen_id: str | None, proxy_call_id: str, reason: str) -> None:
+    """Finalize with amount=0 when billing was reserved but the call failed."""
+    ledger = get_ledger()
+    logger.info(
+        "[ThirdPartyProxy] finalize_zero requested: proxy_call_id=%s reason=%s has_frozen_id=%s",
+        proxy_call_id,
+        reason,
+        bool(frozen_id),
+    )
+    if frozen_id and ledger.try_claim_finalize(proxy_call_id):
+        logger.info("[ThirdPartyProxy] finalize_zero claimed: proxy_call_id=%s", proxy_call_id)
+        ok = await billing.finalize(frozen_id=frozen_id, final_amount=0, finalize_reason=reason)
+        logger.info("[ThirdPartyProxy] finalize_zero result: proxy_call_id=%s ok=%s", proxy_call_id, ok)
+        task_state = "SUCCESS" if reason == "success" else "FAILED"
+        if ok:
+            ledger.set_finalized(proxy_call_id, task_state)
+        else:
+            ledger.set_finalize_failed(proxy_call_id, task_state)
+    elif not frozen_id:
+        logger.debug("[ThirdPartyProxy] finalize_zero skipped: no frozen_id proxy_call_id=%s", proxy_call_id)
+    else:
+        logger.info("[ThirdPartyProxy] finalize_zero claim denied: proxy_call_id=%s", proxy_call_id)
+
+
+def _try_parse_json(data: bytes) -> dict[str, Any] | None:
+    if not data:
+        return None
+    try:
+        parsed = json.loads(data)
+        return parsed if isinstance(parsed, dict) else None
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+def _proxy_response(
+    data: dict[str, Any],
+    proxy_call_id: str | None,
+    status_code: int = 200,
+    extra_headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    headers: dict[str, str] = dict(extra_headers or {})
+    if proxy_call_id:
+        headers["X-Proxy-Call-Id"] = proxy_call_id
+    return JSONResponse(content=data, status_code=status_code, headers=headers)

backend/app/gateway/third_party_proxy/__init__.py

@@ -0,0 +1 @@
+"""Third-party proxy package."""

backend/app/gateway/third_party_proxy/billing.py

@@ -0,0 +1,190 @@
+"""Thin async billing client for the third-party proxy.
+
+Calls the same reserve/finalize HTTP endpoints as BillingMiddleware,
+but with semantics appropriate for third-party task calls:
+- estimatedTokens = 0 (not applicable)
+- finalAmount = actual provider monetary charge (thirdPartyConsumeMoney)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta
+
+import httpx
+
+from deerflow.config.app_config import get_app_config
+
+logger = logging.getLogger(__name__)
+
+_SUCCESS_STATUS_CODES = {200, 1000}
+
+
+async def reserve(
+    *,
+    thread_id: str | None,
+    call_id: str,
+    provider: str,
+    operation: str,
+    frozen_amount: float,
+    frozen_type: int | None,
+) -> str | None:
+    """Reserve billing before forwarding a submit call.
+
+    Returns the frozen_id string on success, or None if billing is disabled
+    or the reserve call fails (non-blocking — proxy continues in that case).
+    """
+    cfg = get_app_config().billing
+    if not cfg.enabled or not cfg.reserve_url:
+        logger.info(
+            "[ThirdPartyProxy][Billing] reserve skipped: enabled=%s reserve_url=%s call_id=%s",
+            cfg.enabled,
+            cfg.reserve_url,
+            call_id,
+        )
+        return None
+
+    expire_at = datetime.now() + timedelta(seconds=cfg.default_expire_seconds)
+    payload = {
+        "sessionId": thread_id,
+        "callId": call_id,
+        "modelName": provider,
+        "question": f"skill invokes {operation.split('/')[-1]}",
+        "frozenAmount": frozen_amount,
+        "frozenType": frozen_type if frozen_type is not None else cfg.frozen_type,
+        "estimatedInputTokens": 0,
+        "estimatedOutputTokens": 0,
+        "expireAt": expire_at.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+
+    logger.info(
+        "[ThirdPartyProxy][Billing] reserve request: url=%s call_id=%s provider=%s thread_id=%s",
+        cfg.reserve_url,
+        call_id,
+        provider,
+        thread_id,
+    )
+    logger.debug("[ThirdPartyProxy][Billing] reserve payload: %s", payload)
+    try:
+        async with httpx.AsyncClient(timeout=cfg.timeout_seconds) as client:
+            resp = await client.post(cfg.reserve_url, headers=cfg.headers, json=payload)
+            resp.raise_for_status()
+            data: dict = resp.json()
+    except Exception as exc:
+        logger.warning("[ThirdPartyProxy][Billing] reserve HTTP error: %s", exc)
+        return None
+
+    logger.info(
+        "[ThirdPartyProxy][Billing] reserve response: call_id=%s status_code=%s",
+        call_id,
+        resp.status_code,
+    )
+    logger.debug("[ThirdPartyProxy][Billing] reserve response body: %s", data)
+
+    if not _is_success(data):
+        logger.warning(
+            "[ThirdPartyProxy][Billing] reserve rejected: call_id=%s status=%s payload=%s",
+            call_id,
+            data.get("status") or data.get("code"),
+            data,
+        )
+        return None
+
+    frozen_id = (data.get("data") or {}).get("frozenId")
+    if not isinstance(frozen_id, str) or not frozen_id:
+        logger.warning(
+            "[ThirdPartyProxy][Billing] reserve response missing frozenId: call_id=%s payload=%s",
+            call_id,
+            data,
+        )
+        return None
+
+    logger.info("[ThirdPartyProxy][Billing] reserve ok: call_id=%s frozen_id=%s", call_id, frozen_id)
+    logger.debug(
+        "[ThirdPartyProxy][Billing] reserve success details: provider=%s operation=%s expire_at=%s",
+        provider,
+        operation,
+        payload["expireAt"],
+    )
+    return frozen_id
+
+
+async def finalize(
+    *,
+    frozen_id: str,
+    final_amount: float,
+    finalize_reason: str,
+) -> bool:
+    """Finalize billing after a third-party call reaches a terminal state.
+
+    final_amount is the actual provider charge (e.g. thirdPartyConsumeMoney from RunningHub).
+    Pass 0 for failed/cancelled calls.
+    Returns True on success.
+    """
+    cfg = get_app_config().billing
+    if not cfg.enabled or not cfg.finalize_url:
+        # Billing not configured — treat as success so the caller marks the record finalized
+        logger.info(
+            "[ThirdPartyProxy][Billing] finalize skipped: enabled=%s finalize_url=%s frozen_id=%s",
+            cfg.enabled,
+            cfg.finalize_url,
+            frozen_id,
+        )
+        return True
+
+    payload = {
+        "frozenId": frozen_id,
+        "finalAmount": final_amount,
+        "usageInputTokens": 0,
+        "usageOutputTokens": 0,
+        "usageTotalTokens": 0,
+        "finalizeReason": finalize_reason,
+    }
+
+    logger.info(
+        "[ThirdPartyProxy][Billing] finalize request: frozen_id=%s amount=%s reason=%s url=%s",
+        frozen_id,
+        final_amount,
+        finalize_reason,
+        cfg.finalize_url,
+    )
+    logger.debug("[ThirdPartyProxy][Billing] finalize payload: %s", payload)
+    try:
+        async with httpx.AsyncClient(timeout=cfg.timeout_seconds) as client:
+            resp = await client.post(cfg.finalize_url, headers=cfg.headers, json=payload)
+            resp.raise_for_status()
+            data: dict = resp.json()
+    except Exception as exc:
+        logger.warning("[ThirdPartyProxy][Billing] finalize HTTP error: frozen_id=%s err=%s", frozen_id, exc)
+        return False
+
+    logger.info(
+        "[ThirdPartyProxy][Billing] finalize response: frozen_id=%s status_code=%s",
+        frozen_id,
+        resp.status_code,
+    )
+    logger.debug("[ThirdPartyProxy][Billing] finalize response body: %s", data)
+
+    if not _is_success(data):
+        logger.warning(
+            "[ThirdPartyProxy][Billing] finalize rejected: frozen_id=%s status=%s payload=%s",
+            frozen_id,
+            data.get("status") or data.get("code"),
+            data,
+        )
+        return False
+
+    logger.info("[ThirdPartyProxy][Billing] finalize ok: frozen_id=%s", frozen_id)
+    logger.debug(
+        "[ThirdPartyProxy][Billing] finalize success details: amount=%s reason=%s",
+        final_amount,
+        finalize_reason,
+    )
+    return True
+
+
+def _is_success(data: dict) -> bool:
+    status = data.get("status") or data.get("code")
+    if isinstance(status, int) and status in _SUCCESS_STATUS_CODES:
+        return True
+    return data.get("success") is True

backend/app/gateway/third_party_proxy/ledger.py

@@ -0,0 +1,289 @@
+"""In-memory call state ledger for the third-party proxy.
+
+Tracks each proxied call from reserve → submit → query → finalize,
+enforcing idempotency and ensuring billing finalize runs exactly once.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Literal
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+BillingState = Literal["UNRESERVED", "RESERVED", "FINALIZED", "FINALIZE_FAILED"]
+TaskState = Literal["PENDING", "RUNNING", "SUCCESS", "FAILED", "UNKNOWN"]
+
+
+@dataclass
+class CallRecord:
+    proxy_call_id: str
+    provider: str
+    thread_id: str | None
+    # call_id is sent to the billing platform (callId in reserve payload)
+    call_id: str
+    frozen_id: str | None = None
+    provider_task_id: str | None = None
+    billing_state: BillingState = "UNRESERVED"
+    task_state: TaskState = "PENDING"
+    created_at: float = field(default_factory=time.time)
+    finalized_at: float | None = None
+    error: str | None = None
+    idempotency_key: str | None = None
+    # Cached last provider response — returned for repeat queries after finalization
+    last_response: dict[str, Any] | None = None
+
+
+class CallLedger:
+    """Thread-safe in-memory ledger for third-party proxy call records."""
+
+    def __init__(self) -> None:
+        self._records: dict[str, CallRecord] = {}  # proxy_call_id → record
+        self._task_index: dict[str, str] = {}  # "{provider}:{provider_task_id}" → proxy_call_id
+        self._idem_index: dict[str, str] = {}  # "{provider}:{idem_key}" → proxy_call_id
+        self._lock = threading.Lock()
+
+    def create(
+        self,
+        provider: str,
+        thread_id: str | None,
+        idempotency_key: str | None = None,
+    ) -> CallRecord:
+        """Create a new call record, or return the existing one if idempotency key matches."""
+        with self._lock:
+            if idempotency_key:
+                existing = self._get_by_idem_key_locked(provider, idempotency_key)
+                if existing is not None:
+                    logger.info(
+                        "[ThirdPartyProxy][Ledger] idempotent hit: provider=%s proxy_call_id=%s idem_key=%s",
+                        provider,
+                        existing.proxy_call_id,
+                        idempotency_key,
+                    )
+                    # logger.debug(
+                    #     "[ThirdPartyProxy][Ledger] existing record reused: call_id=%s task_id=%s billing_state=%s task_state=%s",
+                    #     existing.call_id,
+                    #     existing.provider_task_id,
+                    #     existing.billing_state,
+                    #     existing.task_state,
+                    # )
+                    return existing
+
+            record = CallRecord(
+                proxy_call_id=str(uuid4()),
+                provider=provider,
+                thread_id=thread_id,
+                call_id=str(uuid4()),
+                idempotency_key=idempotency_key,
+            )
+            self._records[record.proxy_call_id] = record
+            if idempotency_key:
+                self._idem_index[f"{provider}:{idempotency_key}"] = record.proxy_call_id
+            logger.info(
+                "[ThirdPartyProxy][Ledger] created record: provider=%s proxy_call_id=%s call_id=%s thread_id=%s",
+                provider,
+                record.proxy_call_id,
+                record.call_id,
+                thread_id,
+            )
+            # logger.debug(
+            #     "[ThirdPartyProxy][Ledger] create details: idem_key=%s billing_state=%s task_state=%s",
+            #     idempotency_key,
+            #     record.billing_state,
+            #     record.task_state,
+            # )
+            return record
+
+    def get(self, proxy_call_id: str) -> CallRecord | None:
+        return self._records.get(proxy_call_id)
+
+    def get_by_task_id(self, provider: str, provider_task_id: str) -> CallRecord | None:
+        key = f"{provider}:{provider_task_id}"
+        proxy_call_id = self._task_index.get(key)
+        return self._records.get(proxy_call_id) if proxy_call_id else None
+
+    def get_by_idempotency_key(self, provider: str, idempotency_key: str) -> CallRecord | None:
+        return self._get_by_idem_key_locked(provider, idempotency_key)
+
+    def set_reserved(self, proxy_call_id: str, frozen_id: str) -> None:
+        with self._lock:
+            record = self._records.get(proxy_call_id)
+            if record:
+                record.frozen_id = frozen_id
+                record.billing_state = "RESERVED"
+                logger.info(
+                    "[ThirdPartyProxy][Ledger] reserved: proxy_call_id=%s frozen_id=%s",
+                    proxy_call_id,
+                    frozen_id,
+                )
+                # logger.debug(
+                #     "[ThirdPartyProxy][Ledger] reserve state: call_id=%s provider=%s task_state=%s",
+                #     record.call_id,
+                #     record.provider,
+                #     record.task_state,
+                # )
+            else:
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] set_reserved ignored for missing record: proxy_call_id=%s",
+                    proxy_call_id,
+                )
+
+    def set_running(self, proxy_call_id: str, provider_task_id: str) -> None:
+        with self._lock:
+            record = self._records.get(proxy_call_id)
+            if record:
+                record.provider_task_id = provider_task_id
+                record.task_state = "RUNNING"
+                self._task_index[f"{record.provider}:{provider_task_id}"] = proxy_call_id
+                logger.info(
+                    "[ThirdPartyProxy][Ledger] running: proxy_call_id=%s provider_task_id=%s",
+                    proxy_call_id,
+                    provider_task_id,
+                )
+                # logger.debug(
+                #     "[ThirdPartyProxy][Ledger] running state: provider=%s call_id=%s billing_state=%s",
+                #     record.provider,
+                #     record.call_id,
+                #     record.billing_state,
+                # )
+            else:
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] set_running ignored for missing record: proxy_call_id=%s provider_task_id=%s",
+                    proxy_call_id,
+                    provider_task_id,
+                )
+
+    def try_claim_finalize(self, proxy_call_id: str) -> bool:
+        """Atomically claim finalization rights. Returns True only once per record."""
+        with self._lock:
+            record = self._records.get(proxy_call_id)
+            if record is None:
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] finalize claim denied: missing record proxy_call_id=%s",
+                    proxy_call_id,
+                )
+                return False
+            if record.billing_state in ("FINALIZED", "FINALIZE_FAILED"):
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] finalize claim denied: proxy_call_id=%s billing_state=%s",
+                    proxy_call_id,
+                    record.billing_state,
+                )
+                return False
+            # Mark as finalized immediately to prevent concurrent finalize
+            record.billing_state = "FINALIZED"
+            logger.info(
+                "[ThirdPartyProxy][Ledger] finalize claimed: proxy_call_id=%s",
+                proxy_call_id,
+            )
+            logger.debug(
+                "[ThirdPartyProxy][Ledger] finalize claim state: call_id=%s provider=%s task_state=%s frozen_id=%s",
+                record.call_id,
+                record.provider,
+                record.task_state,
+                record.frozen_id,
+            )
+            return True
+
+    def set_finalized(self, proxy_call_id: str, task_state: TaskState) -> None:
+        with self._lock:
+            record = self._records.get(proxy_call_id)
+            if record:
+                record.task_state = task_state
+                record.billing_state = "FINALIZED"
+                record.finalized_at = time.time()
+                logger.info(
+                    "[ThirdPartyProxy][Ledger] finalized: proxy_call_id=%s task_state=%s",
+                    proxy_call_id,
+                    task_state,
+                )
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] finalized state: provider=%s call_id=%s frozen_id=%s finalized_at=%s",
+                    record.provider,
+                    record.call_id,
+                    record.frozen_id,
+                    record.finalized_at,
+                )
+            else:
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] set_finalized ignored for missing record: proxy_call_id=%s task_state=%s",
+                    proxy_call_id,
+                    task_state,
+                )
+
+    def set_finalize_failed(self, proxy_call_id: str, task_state: TaskState) -> None:
+        with self._lock:
+            record = self._records.get(proxy_call_id)
+            if record:
+                record.task_state = task_state
+                record.billing_state = "FINALIZE_FAILED"
+                record.finalized_at = time.time()
+                logger.info(
+                    "[ThirdPartyProxy][Ledger] finalize failed: proxy_call_id=%s task_state=%s",
+                    proxy_call_id,
+                    task_state,
+                )
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] finalize failure state: provider=%s call_id=%s frozen_id=%s finalized_at=%s",
+                    record.provider,
+                    record.call_id,
+                    record.frozen_id,
+                    record.finalized_at,
+                )
+            else:
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] set_finalize_failed ignored for missing record: proxy_call_id=%s task_state=%s",
+                    proxy_call_id,
+                    task_state,
+                )
+
+    def update_response(self, proxy_call_id: str, response: dict[str, Any]) -> None:
+        with self._lock:
+            record = self._records.get(proxy_call_id)
+            if record:
+                record.last_response = response
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] cached response: proxy_call_id=%s keys=%s",
+                    proxy_call_id,
+                    sorted(response.keys()),
+                )
+            else:
+                logger.debug(
+                    "[ThirdPartyProxy][Ledger] update_response ignored for missing record: proxy_call_id=%s",
+                    proxy_call_id,
+                )
+
+    def is_finalized(self, proxy_call_id: str) -> bool:
+        record = self._records.get(proxy_call_id)
+        return record is not None and record.billing_state in ("FINALIZED", "FINALIZE_FAILED")
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _get_by_idem_key_locked(self, provider: str, idempotency_key: str) -> CallRecord | None:
+        key = f"{provider}:{idempotency_key}"
+        proxy_call_id = self._idem_index.get(key)
+        return self._records.get(proxy_call_id) if proxy_call_id else None
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+_ledger: CallLedger | None = None
+_ledger_lock = threading.Lock()
+
+
+def get_ledger() -> CallLedger:
+    global _ledger
+    if _ledger is None:
+        with _ledger_lock:
+            if _ledger is None:
+                _ledger = CallLedger()
+                logger.info("[ThirdPartyProxy][Ledger] singleton initialized")
+    return _ledger

backend/app/gateway/third_party_proxy/proxy.py

@@ -0,0 +1,246 @@
+"""HTTP forwarding, route classification, and JSONPath extraction for the third-party proxy."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from deerflow.config.app_config import get_app_config
+from deerflow.config.third_party_proxy_config import (
+    QueryRouteConfig,
+    SubmitRouteConfig,
+    ThirdPartyProviderConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+_SENSITIVE_HEADERS = frozenset(
+    [
+        "authorization",
+        "proxy-authorization",
+        "x-api-key",
+        "api-key",
+        "cookie",
+        "set-cookie",
+    ]
+)
+
+# ---------------------------------------------------------------------------
+# Provider config lookup
+# ---------------------------------------------------------------------------
+
+
+def get_provider_config(provider: str) -> ThirdPartyProviderConfig | None:
+    """Return the provider config for *provider*, or None if not configured/disabled."""
+    cfg = get_app_config().third_party_proxy
+    if not cfg.enabled:
+        return None
+    return cfg.providers.get(provider)
+
+
+# ---------------------------------------------------------------------------
+# Route classification
+# ---------------------------------------------------------------------------
+
+
+def match_submit_route(
+    config: ThirdPartyProviderConfig,
+    method: str,
+    path: str,
+) -> SubmitRouteConfig | None:
+    """Return the first submit route that matches (method, path), or None."""
+    for route in config.submit_routes:
+        if route.method.upper() != method.upper():
+            continue
+        if not _path_matches(path, route.path_pattern):
+            continue
+        if route.exclude_path_pattern and _path_matches(path, route.exclude_path_pattern):
+            continue
+        return route
+    return None
+
+
+def match_query_route(
+    config: ThirdPartyProviderConfig,
+    method: str,
+    path: str,
+) -> QueryRouteConfig | None:
+    """Return the first query route that matches (method, path), or None."""
+    for route in config.query_routes:
+        if route.method.upper() != method.upper():
+            continue
+        if _path_matches(path, route.path_pattern):
+            return route
+    return None
+
+
+def _path_matches(path: str, pattern: str) -> bool:
+    """Match *path* against a glob-ish *pattern*.
+
+    Rules:
+    - Pattern ending in /** matches the prefix and any sub-path.
+    - Otherwise exact match.
+    """
+    # Normalise trailing slashes
+    path = path.rstrip("/") or "/"
+    pattern = pattern.rstrip("/") or "/"
+
+    if pattern.endswith("/**"):
+        prefix = pattern[:-3]
+        return path == prefix or path.startswith(prefix + "/")
+
+    return path == pattern
+
+
+# ---------------------------------------------------------------------------
+# Minimal path evaluator (dot-notation shorthand only)
+# ---------------------------------------------------------------------------
+
+
+def jsonpath_get(data: Any, path: str) -> Any:
+    """Extract a value from *data* using a simple dot-notation shorthand path.
+
+    Supports paths like: taskId   usage.thirdPartyConsumeMoney
+    Paths with a leading '$' are intentionally not supported.
+    Returns None if any segment is missing or the input is not a dict.
+    """
+    if not isinstance(path, str):
+        return None
+
+    remainder = path.strip()
+    if not remainder or remainder.startswith("$"):
+        return None
+
+    current: Any = data
+    for part in remainder.split("."):
+        if not part:
+            return None
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+        if current is None:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# HTTP forwarding
+# ---------------------------------------------------------------------------
+
+# Request headers we never forward (hop-by-hop, sensitive, or proxy-internal)
+_STRIP_REQUEST_HEADERS = frozenset(
+    [
+        "host",
+        "content-length",
+        "transfer-encoding",
+        "connection",
+        "x-thread-id",
+        "x-idempotency-key",
+    ]
+)
+
+# Response headers we strip before returning to the caller
+_STRIP_RESPONSE_HEADERS = frozenset(
+    [
+        "transfer-encoding",
+        "connection",
+        "keep-alive",
+        "content-encoding",
+        "content-length",
+    ]
+)
+
+
+def _sanitize_headers(headers: dict[str, str]) -> dict[str, str]:
+    """Return a copy of headers with sensitive values redacted."""
+    sanitized: dict[str, str] = {}
+    for key, value in headers.items():
+        if key.lower() in _SENSITIVE_HEADERS:
+            sanitized[key] = "***"
+        else:
+            sanitized[key] = value
+    return sanitized
+
+
+def _preview_body(data: bytes, limit: int = 2048) -> str:
+    """Return a safe textual preview of body bytes for debugging logs."""
+    if not data:
+        return ""
+    chunk = data[:limit]
+    text = chunk.decode("utf-8", errors="replace")
+    if len(data) > limit:
+        text += f" ...<truncated {len(data) - limit} bytes>"
+    return text
+
+
+async def forward_request(
+    *,
+    provider_config: ThirdPartyProviderConfig,
+    method: str,
+    path: str,
+    headers: dict[str, str],
+    body: bytes,
+    query_params: str,
+) -> tuple[int, dict[str, str], bytes]:
+    """Forward *method* *path* to the provider and return (status_code, headers, body).
+
+    The provider's API key (read from the environment variable named in
+    ``provider_config.api_key_env``) is injected automatically, replacing
+    any Authorization header the caller might have sent.
+    """
+    target_url = provider_config.base_url.rstrip("/") + "/" + path.lstrip("/")
+    if query_params:
+        target_url += "?" + query_params
+
+    # Build forwarded headers: drop internal/hop-by-hop, then inject API key
+    forward_headers = {
+        k: v for k, v in headers.items() if k.lower() not in _STRIP_REQUEST_HEADERS
+    }
+    if provider_config.api_key_env:
+        api_key = os.getenv(provider_config.api_key_env)
+        if api_key:
+            forward_headers[provider_config.api_key_header] = provider_config.api_key_prefix + api_key
+        else:
+            logger.warning(
+                "[ThirdPartyProxy] api_key_env '%s' is not set for provider",
+                provider_config.api_key_env,
+            )
+
+    logger.info("[ThirdPartyProxy] → %s %s", method, target_url)
+    logger.debug(
+        "[ThirdPartyProxy] request headers=%s",
+        _sanitize_headers(forward_headers)
+    )
+    logger.debug(
+        "[ThirdPartyProxy] request body(%dB)=%s",
+        len(body),
+        _preview_body(body),
+    )
+
+    async with httpx.AsyncClient(timeout=provider_config.timeout_seconds) as client:
+        response = await client.request(
+            method=method,
+            url=target_url,
+            headers=forward_headers,
+            content=body,
+        )
+
+    response_headers = {
+        k: v
+        for k, v in response.headers.items()
+        if k.lower() not in _STRIP_RESPONSE_HEADERS
+    }
+    logger.info("[ThirdPartyProxy] ← %s %s %d", method, target_url, response.status_code)
+    logger.debug(
+        "[ThirdPartyProxy] response headers=%s",
+        _sanitize_headers(response_headers)
+    )
+    logger.debug(
+        "[ThirdPartyProxy] response body(%dB)=%s",
+        len(response.content),
+        _preview_body(response.content),
+    )
+    return response.status_code, response_headers, response.content

backend/packages/harness/deerflow/agents/middlewares/billing_middleware.py

@@ -438,8 +438,8 @@ def _resolve_model_name(model_key: str | None) -> str | None:
     if not model_key:
         return None
     model_cfg = get_app_config().get_model_config(model_key)
-    if model_cfg and model_cfg.display_name:
+    if model_cfg and model_cfg.model:
-        return model_cfg.display_name
+        return model_cfg.model
     return model_key
 
 

backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox_provider.py

@@ -514,7 +514,7 @@ class AioSandboxProvider(SandboxProvider):
                 # that is actively serving a thread.
                 logger.warning(f"All {replicas} replica slots are in active use; creating sandbox {sandbox_id} beyond the soft limit")
 
-        info = self._backend.create(thread_id, sandbox_id, extra_mounts=extra_mounts or None)
+        info = self._backend.create(thread_id, sandbox_id, extra_mounts=extra_mounts or None, extra_env={"THREAD_ID": thread_id} if thread_id else None)
 
         # Wait for sandbox to be ready
         if not wait_for_sandbox_ready(info.sandbox_url, timeout=60):

backend/packages/harness/deerflow/community/aio_sandbox/backend.py

@@ -44,7 +44,7 @@ class SandboxBackend(ABC):
     """
 
     @abstractmethod
-    def create(self, thread_id: str, sandbox_id: str, extra_mounts: list[tuple[str, str, bool]] | None = None) -> SandboxInfo:
+    def create(self, thread_id: str, sandbox_id: str, extra_mounts: list[tuple[str, str, bool]] | None = None, extra_env: dict[str, str] | None = None) -> SandboxInfo:
         """Create/provision a new sandbox.
 
         Args:
@@ -52,6 +52,9 @@ class SandboxBackend(ABC):
             sandbox_id: Deterministic sandbox identifier.
             extra_mounts: Additional volume mounts as (host_path, container_path, read_only) tuples.
                 Ignored by backends that don't manage containers (e.g., remote).
+            extra_env: Additional environment variables to inject at runtime (e.g. THREAD_ID).
+                These are merged after static config env vars, so runtime values override same-key static values.
+                Ignored by backends that don't manage containers (e.g., remote).
 
         Returns:
             SandboxInfo with connection details.

backend/packages/harness/deerflow/community/aio_sandbox/local_backend.py

@@ -110,7 +110,7 @@ class LocalContainerBackend(SandboxBackend):
 
     # ── SandboxBackend interface ──────────────────────────────────────────
 
-    def create(self, thread_id: str, sandbox_id: str, extra_mounts: list[tuple[str, str, bool]] | None = None) -> SandboxInfo:
+    def create(self, thread_id: str, sandbox_id: str, extra_mounts: list[tuple[str, str, bool]] | None = None, extra_env: dict[str, str] | None = None) -> SandboxInfo:
         """Start a new container and return its connection info.
 
         Args:
@@ -137,7 +137,7 @@ class LocalContainerBackend(SandboxBackend):
         for _attempt in range(10):
             port = get_free_port(start_port=_next_start)
             try:
-                container_id = self._start_container(container_name, port, extra_mounts)
+                container_id = self._start_container(container_name, port, extra_mounts, extra_env=extra_env)
                 break
             except RuntimeError as exc:
                 release_port(port)
@@ -229,6 +229,7 @@ class LocalContainerBackend(SandboxBackend):
         container_name: str,
         port: int,
         extra_mounts: list[tuple[str, str, bool]] | None = None,
+        extra_env: dict[str, str] | None = None,
     ) -> str:
         """Start a new container.
 
@@ -260,9 +261,17 @@ class LocalContainerBackend(SandboxBackend):
             ]
         )
 
-        # Environment variables
+        # On Linux, containers started via DooD (Docker-out-of-Docker) do not
+        # automatically resolve host.docker.internal. Add the mapping explicitly
+        # so sandbox containers can call back into the host-exposed gateway.
+        if self._runtime == "docker":
+            cmd.extend(["--add-host", "host.docker.internal:host-gateway"])
+
+        # Environment variables (static config first, runtime overrides last)
         for key, value in self._environment.items():
             cmd.extend(["-e", f"{key}={value}"])
+        for key, value in (extra_env or {}).items():
+            cmd.extend(["-e", f"{key}={value}"])
 
         # Config-level volume mounts
         for mount in self._config_mounts:

backend/packages/harness/deerflow/community/aio_sandbox/remote_backend.py

@@ -60,6 +60,7 @@ class RemoteSandboxBackend(SandboxBackend):
         thread_id: str,
         sandbox_id: str,
         extra_mounts: list[tuple[str, str, bool]] | None = None,
+        extra_env: dict[str, str] | None = None,
     ) -> SandboxInfo:
         """Create a sandbox Pod + Service via the provisioner.
 

backend/packages/harness/deerflow/config/app_config.py

@@ -20,6 +20,7 @@ from deerflow.config.skills_config import SkillsConfig
 from deerflow.config.stream_bridge_config import StreamBridgeConfig, load_stream_bridge_config_from_dict
 from deerflow.config.subagents_config import SubagentsAppConfig, load_subagents_config_from_dict
 from deerflow.config.summarization_config import SummarizationConfig, load_summarization_config_from_dict
+from deerflow.config.third_party_proxy_config import ThirdPartyProxyConfig
 from deerflow.config.title_config import TitleConfig, load_title_config_from_dict
 from deerflow.config.token_usage_config import TokenUsageConfig
 from deerflow.config.tool_config import ToolConfig, ToolGroupConfig
@@ -42,6 +43,7 @@ class AppConfig(BaseModel):
 
     log_level: str = Field(default="info", description="Logging level for deerflow modules (debug/info/warning/error)")
     billing: BillingConfig = Field(default_factory=BillingConfig, description="External billing reservation/finalization configuration")
+    third_party_proxy: ThirdPartyProxyConfig = Field(default_factory=ThirdPartyProxyConfig, description="Third-party API proxy with billing integration")
     token_usage: TokenUsageConfig = Field(default_factory=TokenUsageConfig, description="Token usage tracking configuration")
     models: list[ModelConfig] = Field(default_factory=list, description="Available models")
     sandbox: SandboxConfig = Field(description="Sandbox configuration")

backend/packages/harness/deerflow/config/third_party_proxy_config.py

@@ -0,0 +1,108 @@
+"""Configuration for the third-party API proxy with billing integration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SubmitRouteConfig(BaseModel):
+    """Identifies a submit request — triggers billing reserve + task state tracking."""
+
+    method: str = Field(default="POST", description="HTTP method to match (case-insensitive)")
+    path_pattern: str = Field(
+        description="Glob-style path pattern. Use ** to match any sub-path, e.g. /openapi/v2/**"
+    )
+    exclude_path_pattern: str | None = Field(
+        default=None,
+        description="If set, paths matching this pattern are excluded from submit handling",
+    )
+    task_id_jsonpath: str = Field(
+        description="Dot-path into the *response* body to extract the provider task ID, e.g. taskId"
+    )
+    frozen_amount: float | None = Field(
+        default=None,
+        ge=0,
+        description="Optional route-level override for billing reserve payload frozenAmount",
+    )
+    frozen_type: int | None = Field(
+        default=None,
+        description="Optional route-level override for billing reserve payload frozenType",
+    )
+
+
+class QueryRouteConfig(BaseModel):
+    """Identifies a query/poll request — checks for terminal status + triggers billing finalize."""
+
+    method: str = Field(default="POST", description="HTTP method to match (case-insensitive)")
+    path_pattern: str = Field(description="Glob-style path pattern for the query endpoint")
+    request_task_id_jsonpath: str = Field(
+        description="Dot-path into the *request* body to extract the task ID being queried"
+    )
+    status_jsonpath: str = Field(
+        description="Dot-path into the response body to read the task status value"
+    )
+    success_values: list[str] = Field(
+        default_factory=list,
+        description="Status string values that indicate successful terminal state, e.g. [\"SUCCESS\"]",
+    )
+    failure_values: list[str] = Field(
+        default_factory=list,
+        description="Status string values that indicate failed terminal state, e.g. [\"FAILED\", \"CANCELLED\"]",
+    )
+    usage_jsonpath: str | None = Field(
+        default=None,
+        description=(
+            "Dot-path into the response body for the actual monetary cost to pass to billing finalize. "
+            "E.g. usage.thirdPartyConsumeMoney"
+        ),
+    )
+
+
+class ThirdPartyProviderConfig(BaseModel):
+    """Configuration for a single third-party API platform."""
+
+    base_url: str = Field(description="Base URL of the provider, e.g. https://www.runninghub.cn")
+    api_key_env: str | None = Field(
+        default=None,
+        description="Name of the environment variable holding the API key",
+    )
+    api_key_header: str = Field(
+        default="Authorization",
+        description="Request header name for the API key",
+    )
+    api_key_prefix: str = Field(
+        default="Bearer ",
+        description="String prepended to the API key value in the header",
+    )
+    timeout_seconds: float = Field(
+        default=30.0,
+        gt=0,
+        description="HTTP request timeout when forwarding to the provider",
+    )
+    frozen_amount: float = Field(
+        default=0.0,
+        ge=0,
+        description="Amount to reserve in billing reserve payload (frozenAmount)",
+    )
+    frozen_type: int | None = Field(
+        default=None,
+        description="Billing frozen type for this provider (frozenType). If omitted, falls back to billing.frozen_type",
+    )
+    submit_routes: list[SubmitRouteConfig] = Field(
+        default_factory=list,
+        description="Route patterns that identify submit (task-create) requests",
+    )
+    query_routes: list[QueryRouteConfig] = Field(
+        default_factory=list,
+        description="Route patterns that identify query/poll requests",
+    )
+
+
+class ThirdPartyProxyConfig(BaseModel):
+    """Top-level configuration for the third-party API proxy."""
+
+    enabled: bool = Field(default=False, description="Enable the proxy endpoint")
+    providers: dict[str, ThirdPartyProviderConfig] = Field(
+        default_factory=dict,
+        description="Keyed by provider name (used in the URL path /api/proxy/{provider}/...)",
+    )

backend/tests/test_aio_sandbox_local_backend.py

@@ -1,4 +1,6 @@
-from deerflow.community.aio_sandbox.local_backend import _format_container_mount
+from unittest.mock import MagicMock
+
+from deerflow.community.aio_sandbox.local_backend import LocalContainerBackend, _format_container_mount
 
 
 def test_format_container_mount_uses_mount_syntax_for_docker_windows_paths():
@@ -26,3 +28,90 @@ def test_format_container_mount_keeps_volume_syntax_for_apple_container():
         "-v",
         "/host/path:/mnt/path:ro",
     ]
+
+
+# ── extra_env injection ──────────────────────────────────────────────────────
+
+
+def _make_backend(runtime: str = "docker") -> LocalContainerBackend:
+    """Build a minimal LocalContainerBackend without real config."""
+    backend = LocalContainerBackend.__new__(LocalContainerBackend)
+    backend._runtime = runtime
+    backend._container_prefix = "test"
+    backend._environment = {}
+    backend._config_mounts = []
+    backend._base_port = 9000
+    backend._image = "test-image:latest"
+    return backend
+
+
+def test_start_container_injects_extra_env(monkeypatch):
+    """_start_container must append -e KEY=VALUE for each extra_env entry."""
+    backend = _make_backend()
+
+    captured: list[list[str]] = []
+
+    def fake_run(cmd, **_kwargs):
+        captured.append(list(cmd))
+        result = MagicMock()
+        result.returncode = 0
+        result.stdout = "fake-container-id\n"
+        return result
+
+    monkeypatch.setattr("deerflow.community.aio_sandbox.local_backend.subprocess.run", fake_run)
+
+    backend._start_container("c", 9000, extra_env={"THREAD_ID": "thread-abc", "FOO": "bar"})
+
+    cmd = captured[0]
+    assert "-e" in cmd
+    env_pairs = {cmd[i + 1] for i in range(len(cmd)) if cmd[i] == "-e"}
+    assert "THREAD_ID=thread-abc" in env_pairs
+    assert "FOO=bar" in env_pairs
+
+
+def test_start_container_no_extra_env_does_not_inject(monkeypatch):
+    """_start_container with no extra_env must not add unexpected -e flags."""
+    backend = _make_backend()
+
+    captured: list[list[str]] = []
+
+    def fake_run(cmd, **_kwargs):
+        captured.append(list(cmd))
+        result = MagicMock()
+        result.returncode = 0
+        result.stdout = "fake-container-id\n"
+        return result
+
+    monkeypatch.setattr("deerflow.community.aio_sandbox.local_backend.subprocess.run", fake_run)
+
+    backend._start_container("c", 9000)
+
+    cmd = captured[0]
+    env_pairs = {cmd[i + 1] for i in range(len(cmd)) if cmd[i] == "-e"}
+    assert all("THREAD_ID" not in pair for pair in env_pairs)
+
+
+def test_start_container_extra_env_overrides_static_env(monkeypatch):
+    """Runtime extra_env values must appear after static env, effectively overriding same-key entries."""
+    backend = _make_backend()
+    backend._environment = {"MY_VAR": "static"}
+
+    captured: list[list[str]] = []
+
+    def fake_run(cmd, **_kwargs):
+        captured.append(list(cmd))
+        result = MagicMock()
+        result.returncode = 0
+        result.stdout = "fake-container-id\n"
+        return result
+
+    monkeypatch.setattr("deerflow.community.aio_sandbox.local_backend.subprocess.run", fake_run)
+
+    backend._start_container("c", 9000, extra_env={"MY_VAR": "runtime"})
+
+    cmd = captured[0]
+    env_pairs = [cmd[i + 1] for i in range(len(cmd)) if cmd[i] == "-e"]
+    # Both entries should be present; the runtime one comes after, which Docker respects
+    assert "MY_VAR=static" in env_pairs
+    assert "MY_VAR=runtime" in env_pairs
+    assert env_pairs.index("MY_VAR=runtime") > env_pairs.index("MY_VAR=static")

backend/tests/test_aio_sandbox_provider.py

@@ -134,3 +134,68 @@ def test_discover_or_create_only_unlocks_when_lock_succeeds(tmp_path, monkeypatc
             provider._discover_or_create_with_lock("thread-5", "sandbox-5")
 
     assert unlock_calls == []
+
+
+# ── THREAD_ID env injection ──────────────────────────────────────────────────
+
+
+def test_create_sandbox_passes_thread_id_as_extra_env(tmp_path, monkeypatch):
+    """_create_sandbox must pass extra_env={'THREAD_ID': thread_id} to backend.create."""
+    aio_mod = importlib.import_module("deerflow.community.aio_sandbox.aio_sandbox_provider")
+    monkeypatch.setattr(aio_mod, "get_paths", lambda: MagicMock())
+    monkeypatch.setattr(aio_mod.AioSandboxProvider, "_get_extra_mounts", lambda self, tid: [])
+
+    provider = _make_provider(tmp_path)
+    provider._config = {"replicas": 100}
+    provider._warm_pool = {}
+    provider._sandbox_infos = {}
+    provider._thread_sandboxes = {}
+    provider._thread_locks = {}
+    provider._last_activity = {}
+
+    fake_info = MagicMock()
+    fake_info.sandbox_url = "http://localhost:9999"
+    backend_mock = MagicMock()
+    backend_mock.create.return_value = fake_info
+    provider._backend = backend_mock
+
+    with patch.object(aio_mod, "wait_for_sandbox_ready", return_value=True):
+        provider._create_sandbox("thread-xyz", "sandbox-1")
+
+    backend_mock.create.assert_called_once_with(
+        "thread-xyz",
+        "sandbox-1",
+        extra_mounts=None,
+        extra_env={"THREAD_ID": "thread-xyz"},
+    )
+
+
+def test_create_sandbox_no_thread_id_passes_no_extra_env(tmp_path, monkeypatch):
+    """_create_sandbox with thread_id=None must not inject THREAD_ID."""
+    aio_mod = importlib.import_module("deerflow.community.aio_sandbox.aio_sandbox_provider")
+    monkeypatch.setattr(aio_mod, "get_paths", lambda: MagicMock())
+    monkeypatch.setattr(aio_mod.AioSandboxProvider, "_get_extra_mounts", lambda self, tid: [])
+
+    provider = _make_provider(tmp_path)
+    provider._config = {"replicas": 100}
+    provider._warm_pool = {}
+    provider._sandbox_infos = {}
+    provider._thread_sandboxes = {}
+    provider._thread_locks = {}
+    provider._last_activity = {}
+
+    fake_info = MagicMock()
+    fake_info.sandbox_url = "http://localhost:9999"
+    backend_mock = MagicMock()
+    backend_mock.create.return_value = fake_info
+    provider._backend = backend_mock
+
+    with patch.object(aio_mod, "wait_for_sandbox_ready", return_value=True):
+        provider._create_sandbox(None, "sandbox-2")
+
+    backend_mock.create.assert_called_once_with(
+        None,
+        "sandbox-2",
+        extra_mounts=None,
+        extra_env=None,
+    )

backend/tests/test_third_party_proxy.py

@@ -0,0 +1,192 @@
+"""Unit tests for the third-party proxy module."""
+
+from __future__ import annotations
+
+from app.gateway.third_party_proxy.ledger import CallLedger
+from app.gateway.third_party_proxy.proxy import (
+    _path_matches,
+    jsonpath_get,
+    match_query_route,
+    match_submit_route,
+)
+from deerflow.config.third_party_proxy_config import (
+    QueryRouteConfig,
+    SubmitRouteConfig,
+    ThirdPartyProviderConfig,
+)
+
+
+# ---------------------------------------------------------------------------
+# _path_matches
+# ---------------------------------------------------------------------------
+
+
+class TestPathMatches:
+    def test_exact_match(self):
+        assert _path_matches("/openapi/v2/query", "/openapi/v2/query")
+
+    def test_exact_no_match(self):
+        assert not _path_matches("/openapi/v2/query", "/openapi/v2/submit")
+
+    def test_glob_matches_prefix(self):
+        assert _path_matches("/openapi/v2/vidu/submit", "/openapi/v2/**")
+
+    def test_glob_matches_prefix_itself(self):
+        assert _path_matches("/openapi/v2", "/openapi/v2/**")
+
+    def test_glob_no_match_different_prefix(self):
+        assert not _path_matches("/other/v2/submit", "/openapi/v2/**")
+
+    def test_trailing_slashes_normalised(self):
+        assert _path_matches("/openapi/v2/query/", "/openapi/v2/query")
+
+    def test_glob_excludes_sibling_prefix(self):
+        # /openapi/v2/** should not match /openapi/v2extra/foo
+        assert not _path_matches("/openapi/v2extra/foo", "/openapi/v2/**")
+
+
+# ---------------------------------------------------------------------------
+# jsonpath_get
+# ---------------------------------------------------------------------------
+
+
+class TestJsonpathGet:
+    def test_single_key(self):
+        assert jsonpath_get({"taskId": "abc"}, "taskId") == "abc"
+
+    def test_nested_key(self):
+        data = {"usage": {"thirdPartyConsumeMoney": 1.23}}
+        assert jsonpath_get(data, "usage.thirdPartyConsumeMoney") == 1.23
+
+    def test_missing_key_returns_none(self):
+        assert jsonpath_get({"foo": "bar"}, "taskId") is None
+
+    def test_rejects_dollar_prefixed_path(self):
+        assert jsonpath_get({"taskId": "abc"}, "$.taskId") is None
+
+    def test_short_path_supported(self):
+        assert jsonpath_get({"x": 1}, "x") == 1
+
+    def test_non_dict_intermediate(self):
+        data = {"usage": "not-a-dict"}
+        assert jsonpath_get(data, "usage.something") is None
+
+    def test_none_input(self):
+        assert jsonpath_get(None, "x") is None
+
+
+# ---------------------------------------------------------------------------
+# match_submit_route / match_query_route
+# ---------------------------------------------------------------------------
+
+_PROVIDER_CFG = ThirdPartyProviderConfig(
+    base_url="https://example.com",
+    api_key_env="TEST_API_KEY",
+    submit_routes=[
+        SubmitRouteConfig(
+            method="POST",
+            path_pattern="/openapi/v2/**",
+            exclude_path_pattern="/openapi/v2/query",
+            task_id_jsonpath="taskId",
+        )
+    ],
+    query_routes=[
+        QueryRouteConfig(
+            method="POST",
+            path_pattern="/openapi/v2/query",
+            request_task_id_jsonpath="taskId",
+            status_jsonpath="status",
+            success_values=["SUCCESS"],
+            failure_values=["FAILED", "CANCELLED"],
+            usage_jsonpath="usage.thirdPartyConsumeMoney",
+        )
+    ],
+)
+
+
+class TestMatchRoutes:
+    def test_submit_matches_non_query_path(self):
+        result = match_submit_route(_PROVIDER_CFG, "POST", "/openapi/v2/vidu/submit")
+        assert result is not None
+        assert result.task_id_jsonpath == "taskId"
+
+    def test_submit_excluded_by_exclude_pattern(self):
+        result = match_submit_route(_PROVIDER_CFG, "POST", "/openapi/v2/query")
+        assert result is None
+
+    def test_submit_wrong_method(self):
+        result = match_submit_route(_PROVIDER_CFG, "GET", "/openapi/v2/vidu/submit")
+        assert result is None
+
+    def test_query_matches(self):
+        result = match_query_route(_PROVIDER_CFG, "POST", "/openapi/v2/query")
+        assert result is not None
+        assert result.status_jsonpath == "status"
+
+    def test_query_wrong_method(self):
+        result = match_query_route(_PROVIDER_CFG, "GET", "/openapi/v2/query")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# CallLedger
+# ---------------------------------------------------------------------------
+
+
+class TestCallLedger:
+    def _make_ledger(self) -> CallLedger:
+        return CallLedger()
+
+    def test_create_and_get(self):
+        ledger = self._make_ledger()
+        rec = ledger.create("prov", "tid", None)
+        assert rec.provider == "prov"
+        found = ledger.get(rec.proxy_call_id)
+        assert found is not None
+        assert found.proxy_call_id == rec.proxy_call_id
+
+    def test_set_reserved(self):
+        ledger = self._make_ledger()
+        rec = ledger.create("prov", "tid", None)
+        ledger.set_reserved(rec.proxy_call_id, "frozen-123")
+        found = ledger.get(rec.proxy_call_id)
+        assert found.frozen_id == "frozen-123"
+        assert found.billing_state == "RESERVED"
+
+    def test_set_running(self):
+        ledger = self._make_ledger()
+        rec = ledger.create("prov", "tid", None)
+        ledger.set_running(rec.proxy_call_id, "task-abc")
+        found = ledger.get_by_task_id("prov", "task-abc")
+        assert found is not None
+        assert found.proxy_call_id == rec.proxy_call_id
+
+    def test_try_claim_finalize_once(self):
+        ledger = self._make_ledger()
+        rec = ledger.create("prov", "tid", None)
+        # First claim should succeed
+        assert ledger.try_claim_finalize(rec.proxy_call_id) is True
+        # Second claim should fail — already in progress/done
+        assert ledger.try_claim_finalize(rec.proxy_call_id) is False
+
+    def test_is_finalized(self):
+        ledger = self._make_ledger()
+        rec = ledger.create("prov", "tid", None)
+        assert ledger.is_finalized(rec.proxy_call_id) is False
+        ledger.try_claim_finalize(rec.proxy_call_id)
+        ledger.set_finalized(rec.proxy_call_id, "SUCCESS")
+        assert ledger.is_finalized(rec.proxy_call_id) is True
+
+    def test_idempotency_key_dedup(self):
+        ledger = self._make_ledger()
+        rec1 = ledger.create("prov", "tid", "idem-key-1")
+        rec2 = ledger.get_by_idempotency_key("prov", "idem-key-1")
+        assert rec2 is not None
+        assert rec2.proxy_call_id == rec1.proxy_call_id
+
+    def test_update_response(self):
+        ledger = self._make_ledger()
+        rec = ledger.create("prov", "tid", None)
+        ledger.update_response(rec.proxy_call_id, {"result": "ok"})
+        found = ledger.get(rec.proxy_call_id)
+        assert found.last_response == {"result": "ok"}

config.example.yaml

@@ -49,6 +49,51 @@ billing:
   #   Authorization: "Bearer your-secret-token"
   #   X-App-Id: "deer-flow"
 
+# ============================================================================
+# Third-Party Transparent Proxy
+# ============================================================================
+# Exposes /api/proxy/{provider}/... and handles reserve/finalize around
+# third-party async task APIs such as RunningHub.
+
+third_party_proxy:
+  enabled: false
+  providers:
+    runninghub:
+      base_url: https://www.runninghub.cn
+      api_key_env: RUNNINGHUB_API_KEY
+      api_key_header: Authorization
+      api_key_prefix: "Bearer "
+      timeout_seconds: 30.0
+      frozen_type: 2
+      submit_routes:
+        - path_pattern: "/openapi/v2/**"
+          exclude_path_pattern: "/openapi/v2/query"
+          task_id_jsonpath: "taskId"
+          # Optional per-model billing override examples:
+          # frozen_amount: 10.0
+          # frozen_type: 2
+
+        # Example: model-specific reserve policy
+        # - path_pattern: "/openapi/v2/rhart-image/z-image/turbo-lora"
+        #   task_id_jsonpath: "taskId"
+        #   frozen_amount: 10.0
+        #   frozen_type: 2
+        # - path_pattern: "/openapi/v2/vidu/text-to-video-q3-turbo"
+        #   task_id_jsonpath: "taskId"
+        #   frozen_amount: 50.0
+        #   frozen_type: 2
+        # - path_pattern: "/openapi/v2/wan-2.7/image-edit"
+        #   task_id_jsonpath: "taskId"
+        #   frozen_amount: 20.0
+        #   frozen_type: 2
+      query_routes:
+        - path_pattern: "/openapi/v2/query"
+          request_task_id_jsonpath: "taskId"
+          status_jsonpath: "status"
+          success_values: ["SUCCESS"]
+          failure_values: ["FAILED", "CANCELLED"]
+          usage_jsonpath: "usage.thirdPartyConsumeMoney"
+
 # ============================================================================
 # Token Usage Tracking
 # ============================================================================

docker/docker-compose-dev.yaml

@@ -121,6 +121,10 @@ services:
         UV_INDEX_URL: ${UV_INDEX_URL:-https://pypi.org/simple}
     container_name: deer-flow-gateway
     command: sh -c "cd backend && uv sync && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload --reload-include='*.yaml .env' > /app/logs/gateway.log 2>&1"
+    ports:
+      # Expose to host so DooD-started sandbox containers can reach the gateway
+      # via host.docker.internal:8001
+      - "8001:8001"
     volumes:
       - ../backend/:/app/backend/
       # Preserve the .venv built during Docker image build — mounting the full backend/
@@ -149,6 +153,7 @@ services:
           create_host_path: true
     working_dir: /app
     environment:
+      - TZ=Asia/Shanghai
       - CI=true
       - DEER_FLOW_HOME=/app/backend/.deer-flow
       - DEER_FLOW_CHANNELS_LANGGRAPH_URL=${DEER_FLOW_CHANNELS_LANGGRAPH_URL:-http://langgraph:2024}
@@ -206,6 +211,7 @@ services:
           create_host_path: true
     working_dir: /app
     environment:
+      - TZ=Asia/Shanghai
       - CI=true
       - DEER_FLOW_HOME=/app/backend/.deer-flow
       - DEER_FLOW_HOST_BASE_DIR=${DEER_FLOW_ROOT}/backend/.deer-flow

docker/docker-compose.yaml

@@ -69,7 +69,13 @@ services:
         UV_INDEX_URL: ${UV_INDEX_URL:-https://pypi.org/simple}
     container_name: deer-flow-gateway
     command: sh -c "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --workers 2"
+    ports:
+      # Expose gateway port for direct access (e.g. for API clients or testing tools like Postman).
+      # via host.docker.internal:8001
+       - "8001:8001"
     volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /etc/timezone:/etc/timezone:ro
       - ${DEER_FLOW_CONFIG_PATH}:/app/backend/config.yaml:ro
       - ${DEER_FLOW_EXTENSIONS_CONFIG_PATH}:/app/backend/extensions_config.json:ro
       - ../skills:/app/skills:ro
@@ -91,6 +97,7 @@ services:
           create_host_path: true
     working_dir: /app
     environment:
+      - TZ=Asia/Shanghai
       - CI=true
       - DEER_FLOW_HOME=/app/backend/.deer-flow
       - DEER_FLOW_CHANNELS_LANGGRAPH_URL=${DEER_FLOW_CHANNELS_LANGGRAPH_URL:-http://langgraph:2024}
@@ -119,8 +126,10 @@ services:
         UV_IMAGE: ${UV_IMAGE:-ghcr.io/astral-sh/uv:0.7.20}
         UV_INDEX_URL: ${UV_INDEX_URL:-https://pypi.org/simple}
     container_name: deer-flow-langgraph
-    command: sh -c 'cd /app/backend && allow_blocking_flag="" && if [ "${LANGGRAPH_ALLOW_BLOCKING:-0}" = "1" ]; then allow_blocking_flag="--allow-blocking"; fi && uv run langgraph dev --no-browser ${allow_blocking_flag} --no-reload --host 0.0.0.0 --port 2024 --n-jobs-per-worker ${LANGGRAPH_JOBS_PER_WORKER:-10}'
+    command: sh -c 'cd /app/backend && allow_blocking_flag="" && if [ "${LANGGRAPH_ALLOW_BLOCKING:-0}" = "1" ]; then allow_blocking_flag="--allow-blocking"; fi && uv run langgraph dev --no-browser --allow-blocking --no-reload --host 0.0.0.0 --port 2024 --n-jobs-per-worker ${LANGGRAPH_JOBS_PER_WORKER:-10}'
     volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /etc/timezone:/etc/timezone:ro
       - ${DEER_FLOW_CONFIG_PATH}:/app/backend/config.yaml:ro
       - ${DEER_FLOW_EXTENSIONS_CONFIG_PATH}:/app/backend/extensions_config.json:ro
       - ${DEER_FLOW_HOME}:/app/backend/.deer-flow
@@ -142,6 +151,7 @@ services:
         bind:
           create_host_path: true
     environment:
+      - TZ=Asia/Shanghai
       - CI=true
       - DEER_FLOW_HOME=/app/backend/.deer-flow
       - DEER_FLOW_CONFIG_PATH=/app/backend/config.yaml

docs/SKILL_PROXY_MIGRATION_GUIDE.md

@@ -0,0 +1,203 @@
+# Skill Proxy Migration Guide (via Gateway)
+
+This document explains how to migrate a skill script from directly calling a third-party API to using DeerFlow Gateway's transparent proxy, with unified billing orchestration (reserve/finalize).
+
+Applicable scenarios:
+- Async third-party task skills (image/video/audio generation, etc.)
+- Existing scripts that directly call providers (for example, RunningHub)
+
+## 1. Migration Goals
+
+1. The skill no longer calls third-party domains directly.
+2. The skill no longer manages third-party API keys itself.
+3. All requests go through `/api/proxy/{provider}/...`.
+4. Gateway handles:
+- API key injection
+- Idempotent submit deduplication
+- Billing reserve/finalize orchestration
+- Query terminal-state detection and settlement
+
+## 2. Core Principles
+
+1. Keep provider names stable (for example, `runninghub`); do not encode model paths in provider names.
+2. Only submit requests should carry `X-Idempotency-Key`; query requests should not.
+3. Use `X-Thread-Id` as a common context header whenever available.
+4. Use shorthand dot-paths in config extraction fields:
+- Correct: `taskId`, `status`, `usage.thirdPartyConsumeMoney`
+- Incorrect: `$.taskId`, `'$'.taskId`
+
+## 3. Skill Script Migration Steps
+
+The examples below assume Python + requests.
+
+### Step 1: Add gateway config loaders
+
+Add:
+- `load_skill_env()`: loads skill-local `.env`
+- `get_gateway_config()`: reads
+  - `DEER_FLOW_GATEWAY_URL` (default `http://host.docker.internal:8001`)
+  - `RUNNINGHUB_PROXY_PROVIDER` (default `runninghub`)
+
+### Step 2: Centralize proxy headers
+
+Implement:
+- `build_proxy_headers(include_idempotency: bool = False)`
+  - always sets `Content-Type: application/json`
+  - optionally sets `X-Thread-Id`
+  - sets `X-Idempotency-Key` only when `include_idempotency=True`
+
+### Step 3: Route submit calls through gateway
+
+Replace:
+- `https://www.runninghub.cn/openapi/v2/<model-path>`
+
+With:
+- `{gateway}/api/proxy/{provider}/openapi/v2/<model-path>`
+
+And use:
+- `headers=build_proxy_headers(include_idempotency=True)`
+
+### Step 4: Route query calls through gateway
+
+Replace:
+- `https://www.runninghub.cn/openapi/v2/query`
+
+With:
+- `{gateway}/api/proxy/{provider}/openapi/v2/query`
+
+And use:
+- `headers=build_proxy_headers()`
+
+### Step 5: Remove third-party API key logic from the skill
+
+Remove:
+- Loading `RUNNINGHUB_API_KEY` in the script
+- Building `Authorization: Bearer ...` in the script
+
+Reason: third-party credentials are injected by gateway.
+
+### Step 6: Keep essential error handling
+
+Recommended checks:
+- `response.raise_for_status()`
+- submit fallback when `taskId` is missing
+- query loop timeout/failure handling
+
+## 4. Proxy Config Migration (config.yaml)
+
+Configure submit/query routes under `third_party_proxy.providers.<provider>`.
+
+Example (RunningHub):
+
+```yaml
+third_party_proxy:
+  enabled: true
+  providers:
+    runninghub:
+      base_url: https://www.runninghub.cn
+      api_key_env: RUNNINGHUB_API_KEY
+      api_key_header: Authorization
+      api_key_prefix: "Bearer "
+      timeout_seconds: 30.0
+      frozen_amount: 10.0
+      frozen_type: 2
+      submit_routes:
+        - path_pattern: "/openapi/v2/rhart-image/z-image/turbo-lora"
+          task_id_jsonpath: "taskId"
+          frozen_amount: 0.03
+          frozen_type: 2
+        - path_pattern: "/openapi/v2/vidu/text-to-video-q3-turbo"
+          task_id_jsonpath: "taskId"
+          frozen_amount: 11.2
+          frozen_type: 2
+      query_routes:
+        - path_pattern: "/openapi/v2/query"
+          request_task_id_jsonpath: "taskId"
+          status_jsonpath: "status"
+          success_values: ["SUCCESS"]
+          failure_values: ["FAILED", "CANCELLED"]
+          usage_jsonpath: "usage.thirdPartyConsumeMoney"
+```
+
+Notes:
+- Provider-level `frozen_amount`/`frozen_type` are defaults.
+- Submit-route values can override defaults per model endpoint.
+
+## 5. Reusable Function Template
+
+```python
+import os
+from pathlib import Path
+
+from dotenv import dotenv_values
+
+
+def load_skill_env() -> dict[str, str]:
+    """Load skill-local .env values."""
+    env_path = Path(__file__).parent.parent / ".env"
+    return {
+        key: value
+        for key, value in dotenv_values(env_path).items()
+        if isinstance(key, str) and isinstance(value, str)
+    }
+
+
+def get_gateway_config() -> tuple[str, str]:
+    """Get DeerFlow gateway base URL and proxy provider name."""
+    env_vars = load_skill_env()
+    gateway_url = os.getenv("DEER_FLOW_GATEWAY_URL") or env_vars.get(
+        "DEER_FLOW_GATEWAY_URL",
+        "http://host.docker.internal:8001",
+    )
+    provider = os.getenv("RUNNINGHUB_PROXY_PROVIDER") or env_vars.get(
+        "RUNNINGHUB_PROXY_PROVIDER",
+        "runninghub",
+    )
+    return gateway_url.rstrip("/"), provider
+
+
+def build_proxy_headers(*, include_idempotency: bool = False) -> dict[str, str]:
+    headers = {"Content-Type": "application/json"}
+    thread_id = os.getenv("THREAD_ID")
+    if thread_id:
+        headers["X-Thread-Id"] = thread_id
+    if include_idempotency:
+        from uuid import uuid4
+        headers["X-Idempotency-Key"] = str(uuid4())
+    return headers
+```
+
+## 6. Common Pitfalls
+
+### 6.1 Response contains taskId but extraction fails
+
+Usually caused by wrong config path syntax:
+- Wrong: `$.taskId` or `'$'.taskId`
+- Right: `taskId`
+
+### 6.2 Why query should not include X-Idempotency-Key
+
+Idempotency keys are for submit deduplication (to avoid duplicate task creation). Query requests are polling and should not generate new idempotency keys.
+
+### 6.3 Sandbox cannot reach gateway
+
+For Docker-based sandbox execution, use:
+- `DEER_FLOW_GATEWAY_URL=http://host.docker.internal:8001`
+
+## 7. Validation Checklist
+
+1. No direct third-party domain calls remain in the skill script.
+2. The skill script no longer reads third-party API keys.
+3. Submit uses proxy URL + `include_idempotency=True`.
+4. Query uses proxy URL + `include_idempotency=False`.
+5. Config extraction fields use shorthand dot-paths only.
+6. Submit returns `taskId`, then query reaches `RUNNING/SUCCESS`.
+7. Gateway logs show submit/query route hits and finalize flow.
+
+## 8. Reference Implementations
+
+- `skills/public/image-generation/scripts/generate.py`
+- `skills/public/video-generation/scripts/generate.py`
+- `backend/app/gateway/routers/third_party.py`
+- `backend/app/gateway/third_party_proxy/proxy.py`
+- `third_party_proxy` section in `config.yaml`

scripts/deploy.sh

@@ -135,6 +135,28 @@ detect_sandbox_mode() {
     fi
 }
 
+# ── restart ───────────────────────────────────────────────────────────────────
+
+if [ "$CMD" = "restart" ]; then
+    SERVICE="$2"
+    if [ -z "$SERVICE" ]; then
+        echo -e "${RED}✗ Usage: $0 restart {service}${NC}"
+        exit 1
+    fi
+    # 保证变量和 up 一致
+    export DEER_FLOW_HOME="${DEER_FLOW_HOME:-$REPO_ROOT/backend/.deer-flow}"
+    export DEER_FLOW_CONFIG_PATH="${DEER_FLOW_CONFIG_PATH:-$DEER_FLOW_HOME/config.yaml}"
+    export DEER_FLOW_EXTENSIONS_CONFIG_PATH="${DEER_FLOW_EXTENSIONS_CONFIG_PATH:-$DEER_FLOW_HOME/extensions_config.json}"
+    export DEER_FLOW_DOCKER_SOCKET="${DEER_FLOW_DOCKER_SOCKET:-/var/run/docker.sock}"
+    export DEER_FLOW_REPO_ROOT="${DEER_FLOW_REPO_ROOT:-$REPO_ROOT}"
+    export BETTER_AUTH_SECRET="${BETTER_AUTH_SECRET:-placeholder}"
+    # 检查服务名有效性（可选）
+    # shellcheck disable=SC2086
+    echo -e "${BLUE}Restarting service: $SERVICE${NC}"
+    "${COMPOSE_CMD[@]}" restart "$SERVICE"
+    exit 0
+fi
+
 # ── down ──────────────────────────────────────────────────────────────────────
 
 if [ "$CMD" = "down" ]; then