1

server-rs/crates/api-server/Cargo.toml

@@ -11,6 +11,7 @@ reqwest = { version = "0.12", default-features = false, features = ["json", "rus
 module-ai = { path = "../module-ai" }
 module-assets = { path = "../module-assets" }
 module-auth = { path = "../module-auth" }
+module-big-fish = { path = "../module-big-fish" }
 module-combat = { path = "../module-combat" }
 module-custom-world = { path = "../module-custom-world" }
 module-inventory = { path = "../module-inventory" }

server-rs/crates/api-server/src/app.rs

@@ -24,6 +24,11 @@ use crate::{
     },
     auth_me::auth_me,
     auth_sessions::auth_sessions,
+    big_fish::{
+        create_big_fish_session, execute_big_fish_action, get_big_fish_run, get_big_fish_session,
+        start_big_fish_run, stream_big_fish_message, submit_big_fish_input,
+        submit_big_fish_message,
+    },
     custom_world::{
         create_custom_world_agent_session, execute_custom_world_agent_action,
         get_custom_world_agent_card_detail,
@@ -48,6 +53,13 @@ use crate::{
     logout_all::logout_all,
     password_entry::password_entry,
     phone_auth::{phone_login, send_phone_code},
+    puzzle::{
+        advance_puzzle_next_level, create_puzzle_agent_session, drag_puzzle_piece_or_group,
+        execute_puzzle_agent_action, get_puzzle_agent_session, get_puzzle_gallery_detail,
+        get_puzzle_run, get_puzzle_work_detail, get_puzzle_works, list_puzzle_gallery,
+        put_puzzle_work, start_puzzle_run, stream_puzzle_agent_message,
+        submit_puzzle_agent_message, swap_puzzle_pieces,
+    },
     refresh_session::refresh_session,
     request_context::{attach_request_context, resolve_request_id},
     response_headers::propagate_request_id_header,
@@ -348,6 +360,153 @@ pub fn build_router(state: AppState) -> Router {
                 require_bearer_auth,
             )),
         )
+        .route(
+            "/api/runtime/big-fish/agent/sessions",
+            post(create_big_fish_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/agent/sessions/{session_id}",
+            get(get_big_fish_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/agent/sessions/{session_id}/messages",
+            post(submit_big_fish_message).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/agent/sessions/{session_id}/messages/stream",
+            post(stream_big_fish_message).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/agent/sessions/{session_id}/actions",
+            post(execute_big_fish_action).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/sessions/{session_id}/runs",
+            post(start_big_fish_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/runs/{run_id}",
+            get(get_big_fish_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/big-fish/runs/{run_id}/input",
+            post(submit_big_fish_input).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/agent/sessions",
+            post(create_puzzle_agent_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/agent/sessions/{session_id}",
+            get(get_puzzle_agent_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/agent/sessions/{session_id}/messages",
+            post(submit_puzzle_agent_message).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/agent/sessions/{session_id}/messages/stream",
+            post(stream_puzzle_agent_message).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/agent/sessions/{session_id}/actions",
+            post(execute_puzzle_agent_action).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/works",
+            get(get_puzzle_works).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/works/{profile_id}",
+            get(get_puzzle_work_detail)
+                .put(put_puzzle_work)
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
+        )
+        .route("/api/runtime/puzzle/gallery", get(list_puzzle_gallery))
+        .route(
+            "/api/runtime/puzzle/gallery/{profile_id}",
+            get(get_puzzle_gallery_detail),
+        )
+        .route(
+            "/api/runtime/puzzle/runs",
+            post(start_puzzle_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/runs/{run_id}",
+            get(get_puzzle_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/runs/{run_id}/swap",
+            post(swap_puzzle_pieces).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/runs/{run_id}/drag",
+            post(drag_puzzle_piece_or_group).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/runs/{run_id}/next-level",
+            post(advance_puzzle_next_level).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/custom-world/entity",
             post(generate_custom_world_entity).route_layer(middleware::from_fn_with_state(

server-rs/crates/api-server/src/auth.rs

@@ -8,8 +8,12 @@ use axum::{
     middleware::Next,
     response::Response,
 };
-use platform_auth::{AccessTokenClaims, read_refresh_session_token, verify_access_token};
+use platform_auth::{
+    AccessTokenClaims, AuthProvider, BindingStatus, read_refresh_session_token,
+    verify_access_token,
+};
 use serde_json::{Value, json};
+use time::OffsetDateTime;
 use tracing::warn;
 
 use crate::{
@@ -17,6 +21,9 @@ use crate::{
     state::AppState,
 };
 
+const INTERNAL_AUTH_USER_ID_HEADER: &str = "x-genarrative-authenticated-user-id";
+const INTERNAL_API_SECRET_HEADER: &str = "x-genarrative-internal-api-secret";
+
 // 统一把已校验的 claims 写入 request extensions，避免后续 handler 再次重复解析 Bearer token。
 #[derive(Clone, Debug)]
 pub struct AuthenticatedAccessToken {
@@ -53,6 +60,15 @@ pub async fn require_bearer_auth(
     mut request: Request,
     next: Next,
 ) -> Result<Response, AppError> {
+    if request.uri().path().starts_with("/api/runtime/big-fish/")
+        && let Some(claims) = try_build_internal_forwarded_claims(&state, request.headers())
+    {
+        request
+            .extensions_mut()
+            .insert(AuthenticatedAccessToken::new(claims));
+        return Ok(next.run(request).await);
+    }
+
     let bearer_token = extract_bearer_token(request.headers())?;
     let request_id = request
         .extensions()
@@ -172,13 +188,60 @@ fn extract_bearer_token(headers: &HeaderMap) -> Result<String, AppError> {
     Ok(token.to_string())
 }
 
+fn try_build_internal_forwarded_claims(
+    state: &AppState,
+    headers: &HeaderMap,
+) -> Option<AccessTokenClaims> {
+    let expected_secret = state.config.internal_api_secret.as_ref()?.trim();
+    if expected_secret.is_empty() {
+        return None;
+    }
+
+    let provided_secret = headers
+        .get(INTERNAL_API_SECRET_HEADER)
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())?;
+    if provided_secret != expected_secret {
+        return None;
+    }
+
+    let user_id = headers
+        .get(INTERNAL_AUTH_USER_ID_HEADER)
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())?
+        .to_string();
+
+    // 这里的 claims 只服务于经 Node 已鉴权后的本地内部转发链路，避免在开发态复制整套账号仓储。
+    AccessTokenClaims::from_input(
+        platform_auth::AccessTokenClaimsInput {
+            user_id: user_id.clone(),
+            session_id: format!("internal-forwarded-{user_id}"),
+            provider: AuthProvider::Password,
+            roles: vec!["user".to_string()],
+            token_version: 0,
+            phone_verified: false,
+            binding_status: BindingStatus::Active,
+            display_name: None,
+        },
+        state.auth_jwt_config(),
+        OffsetDateTime::now_utc(),
+    )
+    .ok()
+}
+
 #[cfg(test)]
 mod tests {
-    use super::{RefreshSessionToken, extract_bearer_token};
+    use super::{
+        INTERNAL_API_SECRET_HEADER, INTERNAL_AUTH_USER_ID_HEADER, RefreshSessionToken,
+        extract_bearer_token, try_build_internal_forwarded_claims,
+    };
     use axum::{
         http::{HeaderMap, HeaderValue, StatusCode, header::AUTHORIZATION},
         response::IntoResponse,
     };
+    use crate::{config::AppConfig, state::AppState};
 
     #[test]
     fn extract_bearer_token_accepts_standard_header() {
@@ -209,4 +272,26 @@ mod tests {
 
         assert_eq!(token.token(), "refresh-token-01");
     }
+
+    #[test]
+    fn internal_forwarded_claims_require_matching_secret() {
+        let mut config = AppConfig::default();
+        config.internal_api_secret = Some("bridge-secret".to_string());
+        let state = AppState::new(config).expect("state should build");
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            INTERNAL_AUTH_USER_ID_HEADER,
+            HeaderValue::from_static("user_forwarded_01"),
+        );
+        headers.insert(
+            INTERNAL_API_SECRET_HEADER,
+            HeaderValue::from_static("bridge-secret"),
+        );
+
+        let claims =
+            try_build_internal_forwarded_claims(&state, &headers).expect("claims should resolve");
+
+        assert_eq!(claims.user_id(), "user_forwarded_01");
+        assert_eq!(claims.token_version(), 0);
+    }
 }

server-rs/crates/api-server/src/big_fish.rs

@@ -0,0 +1,653 @@
+use axum::{
+    Json,
+    extract::{Extension, Path, State, rejection::JsonRejection},
+    http::{HeaderName, StatusCode, header},
+    response::{IntoResponse, Response},
+};
+use serde_json::{Value, json};
+use shared_contracts::big_fish::{
+    BigFishActionResponse, BigFishAgentMessageResponse, BigFishAnchorItemResponse,
+    BigFishAnchorPackResponse, BigFishAssetCoverageResponse, BigFishAssetSlotResponse,
+    BigFishBackgroundBlueprintResponse, BigFishGameDraftResponse, BigFishLevelBlueprintResponse,
+    BigFishRuntimeEntityResponse, BigFishRuntimeParamsResponse, BigFishRuntimeSnapshotResponse,
+    BigFishRunResponse, BigFishSessionResponse, BigFishSessionSnapshotResponse,
+    BigFishVector2Response, CreateBigFishSessionRequest, ExecuteBigFishActionRequest,
+    SendBigFishMessageRequest, SubmitBigFishInputRequest,
+};
+use shared_kernel::build_prefixed_uuid_id;
+use spacetime_client::{
+    BigFishAgentMessageRecord, BigFishAnchorItemRecord, BigFishAnchorPackRecord,
+    BigFishAssetCoverageRecord, BigFishAssetGenerateRecordInput, BigFishAssetSlotRecord,
+    BigFishBackgroundBlueprintRecord, BigFishGameDraftRecord, BigFishLevelBlueprintRecord,
+    BigFishMessageSubmitRecordInput, BigFishRunInputSubmitRecordInput, BigFishRunStartRecordInput,
+    BigFishRuntimeEntityRecord, BigFishRuntimeParamsRecord, BigFishRuntimeRecord,
+    BigFishSessionCreateRecordInput, BigFishSessionRecord, BigFishVector2Record,
+    SpacetimeClientError,
+};
+
+use crate::{
+    api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
+    request_context::RequestContext, state::AppState,
+};
+
+pub async fn create_big_fish_session(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<CreateBigFishSessionRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        big_fish_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "big-fish",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let seed_text = payload.seed_text.unwrap_or_default().trim().to_string();
+    let session = state
+        .spacetime_client()
+        .create_big_fish_session(BigFishSessionCreateRecordInput {
+            session_id: build_prefixed_uuid_id("big-fish-session-"),
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            seed_text: seed_text.clone(),
+            welcome_message_id: build_prefixed_uuid_id("big-fish-message-"),
+            welcome_message_text: build_big_fish_welcome_text(&seed_text),
+            created_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishSessionResponse {
+            session: map_big_fish_session_response(session),
+        },
+    ))
+}
+
+pub async fn get_big_fish_session(
+    State(state): State<AppState>,
+    Path(session_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, Response> {
+    ensure_non_empty(&request_context, &session_id, "sessionId")?;
+
+    let session = state
+        .spacetime_client()
+        .get_big_fish_session(session_id, authenticated.claims().user_id().to_string())
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishSessionResponse {
+            session: map_big_fish_session_response(session),
+        },
+    ))
+}
+
+pub async fn submit_big_fish_message(
+    State(state): State<AppState>,
+    Path(session_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<SendBigFishMessageRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        big_fish_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "big-fish",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+    ensure_non_empty(&request_context, &session_id, "sessionId")?;
+
+    let client_message_id = payload.client_message_id.trim().to_string();
+    let message_text = payload.text.trim().to_string();
+    if client_message_id.is_empty() || message_text.is_empty() {
+        return Err(big_fish_bad_request(
+            &request_context,
+            "clientMessageId and text are required",
+        ));
+    }
+
+    let session = state
+        .spacetime_client()
+        .submit_big_fish_message(BigFishMessageSubmitRecordInput {
+            session_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            user_message_id: client_message_id,
+            user_message_text: message_text,
+            assistant_message_id: build_prefixed_uuid_id("big-fish-message-"),
+            submitted_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishSessionResponse {
+            session: map_big_fish_session_response(session),
+        },
+    ))
+}
+
+pub async fn stream_big_fish_message(
+    State(state): State<AppState>,
+    Path(session_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<SendBigFishMessageRequest>, JsonRejection>,
+) -> Result<Response, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        big_fish_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "big-fish",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+    ensure_non_empty(&request_context, &session_id, "sessionId")?;
+
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    let session = state
+        .spacetime_client()
+        .submit_big_fish_message(BigFishMessageSubmitRecordInput {
+            session_id,
+            owner_user_id,
+            user_message_id: payload.client_message_id.trim().to_string(),
+            user_message_text: payload.text.trim().to_string(),
+            assistant_message_id: build_prefixed_uuid_id("big-fish-message-"),
+            submitted_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    let session_response = map_big_fish_session_response(session);
+    let reply_text = session_response
+        .last_assistant_reply
+        .clone()
+        .unwrap_or_else(|| "锚点已更新。".to_string());
+    let mut sse_body = String::new();
+    append_sse_event(&request_context, &mut sse_body, "reply_delta", &json!({ "text": reply_text }))?;
+    append_sse_event(&request_context, &mut sse_body, "session", &json!({ "session": session_response }))?;
+    append_sse_event(&request_context, &mut sse_body, "done", &json!({ "ok": true }))?;
+    Ok(build_event_stream_response(sse_body))
+}
+
+pub async fn execute_big_fish_action(
+    State(state): State<AppState>,
+    Path(session_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<ExecuteBigFishActionRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        big_fish_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "big-fish",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+    ensure_non_empty(&request_context, &session_id, "sessionId")?;
+
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    let now = current_utc_micros();
+    let session = match payload.action.trim() {
+        "big_fish_compile_draft" => {
+            state
+                .spacetime_client()
+                .compile_big_fish_draft(session_id, owner_user_id, now)
+                .await
+        }
+        "big_fish_generate_level_main_image" => {
+            state
+                .spacetime_client()
+                .generate_big_fish_asset(BigFishAssetGenerateRecordInput {
+                    session_id,
+                    owner_user_id,
+                    asset_kind: "level_main_image".to_string(),
+                    level: payload.level,
+                    motion_key: None,
+                    generated_at_micros: now,
+                })
+                .await
+        }
+        "big_fish_generate_level_motion" => {
+            state
+                .spacetime_client()
+                .generate_big_fish_asset(BigFishAssetGenerateRecordInput {
+                    session_id,
+                    owner_user_id,
+                    asset_kind: "level_motion".to_string(),
+                    level: payload.level,
+                    motion_key: payload.motion_key,
+                    generated_at_micros: now,
+                })
+                .await
+        }
+        "big_fish_generate_stage_background" => {
+            state
+                .spacetime_client()
+                .generate_big_fish_asset(BigFishAssetGenerateRecordInput {
+                    session_id,
+                    owner_user_id,
+                    asset_kind: "stage_background".to_string(),
+                    level: None,
+                    motion_key: None,
+                    generated_at_micros: now,
+                })
+                .await
+        }
+        "big_fish_publish_game" => {
+            state
+                .spacetime_client()
+                .publish_big_fish_game(session_id, owner_user_id, now)
+                .await
+        }
+        other => {
+            return Err(big_fish_bad_request(
+                &request_context,
+                format!("action `{other}` is not supported").as_str(),
+            ));
+        }
+    }
+    .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishActionResponse {
+            session: map_big_fish_session_response(session),
+        },
+    ))
+}
+
+pub async fn start_big_fish_run(
+    State(state): State<AppState>,
+    Path(session_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, Response> {
+    ensure_non_empty(&request_context, &session_id, "sessionId")?;
+
+    let run = state
+        .spacetime_client()
+        .start_big_fish_run(BigFishRunStartRecordInput {
+            run_id: build_prefixed_uuid_id("big-fish-run-"),
+            session_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            started_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishRunResponse {
+            run: map_big_fish_runtime_response(run),
+        },
+    ))
+}
+
+pub async fn get_big_fish_run(
+    State(state): State<AppState>,
+    Path(run_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, Response> {
+    ensure_non_empty(&request_context, &run_id, "runId")?;
+
+    let run = state
+        .spacetime_client()
+        .get_big_fish_run(run_id, authenticated.claims().user_id().to_string())
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishRunResponse {
+            run: map_big_fish_runtime_response(run),
+        },
+    ))
+}
+
+pub async fn submit_big_fish_input(
+    State(state): State<AppState>,
+    Path(run_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<SubmitBigFishInputRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        big_fish_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "big-fish",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+    ensure_non_empty(&request_context, &run_id, "runId")?;
+
+    let run = state
+        .spacetime_client()
+        .submit_big_fish_input(BigFishRunInputSubmitRecordInput {
+            run_id,
+            owner_user_id: authenticated.claims().user_id().to_string(),
+            input_x: payload.x,
+            input_y: payload.y,
+            submitted_at_micros: current_utc_micros(),
+        })
+        .await
+        .map_err(|error| big_fish_error_response(&request_context, map_big_fish_client_error(error)))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        BigFishRunResponse {
+            run: map_big_fish_runtime_response(run),
+        },
+    ))
+}
+
+fn map_big_fish_session_response(session: BigFishSessionRecord) -> BigFishSessionSnapshotResponse {
+    BigFishSessionSnapshotResponse {
+        session_id: session.session_id,
+        current_turn: session.current_turn,
+        progress_percent: session.progress_percent,
+        stage: session.stage,
+        anchor_pack: map_big_fish_anchor_pack_response(session.anchor_pack),
+        draft: session.draft.map(map_big_fish_draft_response),
+        asset_slots: session
+            .asset_slots
+            .into_iter()
+            .map(map_big_fish_asset_slot_response)
+            .collect(),
+        asset_coverage: map_big_fish_asset_coverage_response(session.asset_coverage),
+        messages: session
+            .messages
+            .into_iter()
+            .map(map_big_fish_agent_message_response)
+            .collect(),
+        last_assistant_reply: session.last_assistant_reply,
+        publish_ready: session.publish_ready,
+        updated_at: session.updated_at,
+    }
+}
+
+fn map_big_fish_anchor_pack_response(anchor_pack: BigFishAnchorPackRecord) -> BigFishAnchorPackResponse {
+    BigFishAnchorPackResponse {
+        gameplay_promise: map_big_fish_anchor_item_response(anchor_pack.gameplay_promise),
+        ecology_visual_theme: map_big_fish_anchor_item_response(anchor_pack.ecology_visual_theme),
+        growth_ladder: map_big_fish_anchor_item_response(anchor_pack.growth_ladder),
+        risk_tempo: map_big_fish_anchor_item_response(anchor_pack.risk_tempo),
+    }
+}
+
+fn map_big_fish_anchor_item_response(anchor: BigFishAnchorItemRecord) -> BigFishAnchorItemResponse {
+    BigFishAnchorItemResponse {
+        key: anchor.key,
+        label: anchor.label,
+        value: anchor.value,
+        status: anchor.status,
+    }
+}
+
+fn map_big_fish_draft_response(draft: BigFishGameDraftRecord) -> BigFishGameDraftResponse {
+    BigFishGameDraftResponse {
+        title: draft.title,
+        subtitle: draft.subtitle,
+        core_fun: draft.core_fun,
+        ecology_theme: draft.ecology_theme,
+        levels: draft
+            .levels
+            .into_iter()
+            .map(map_big_fish_level_response)
+            .collect(),
+        background: map_big_fish_background_response(draft.background),
+        runtime_params: map_big_fish_runtime_params_response(draft.runtime_params),
+    }
+}
+
+fn map_big_fish_level_response(level: BigFishLevelBlueprintRecord) -> BigFishLevelBlueprintResponse {
+    BigFishLevelBlueprintResponse {
+        level: level.level,
+        name: level.name,
+        one_line_fantasy: level.one_line_fantasy,
+        silhouette_direction: level.silhouette_direction,
+        size_ratio: level.size_ratio,
+        visual_prompt_seed: level.visual_prompt_seed,
+        motion_prompt_seed: level.motion_prompt_seed,
+        merge_source_level: level.merge_source_level,
+        prey_window: level.prey_window,
+        threat_window: level.threat_window,
+        is_final_level: level.is_final_level,
+    }
+}
+
+fn map_big_fish_background_response(
+    background: BigFishBackgroundBlueprintRecord,
+) -> BigFishBackgroundBlueprintResponse {
+    BigFishBackgroundBlueprintResponse {
+        theme: background.theme,
+        color_mood: background.color_mood,
+        foreground_hints: background.foreground_hints,
+        midground_composition: background.midground_composition,
+        background_depth: background.background_depth,
+        safe_play_area_hint: background.safe_play_area_hint,
+        spawn_edge_hint: background.spawn_edge_hint,
+        background_prompt_seed: background.background_prompt_seed,
+    }
+}
+
+fn map_big_fish_runtime_params_response(
+    params: BigFishRuntimeParamsRecord,
+) -> BigFishRuntimeParamsResponse {
+    BigFishRuntimeParamsResponse {
+        level_count: params.level_count,
+        merge_count_per_upgrade: params.merge_count_per_upgrade,
+        spawn_target_count: params.spawn_target_count,
+        leader_move_speed: params.leader_move_speed,
+        follower_catch_up_speed: params.follower_catch_up_speed,
+        offscreen_cull_seconds: params.offscreen_cull_seconds,
+        prey_spawn_delta_levels: params.prey_spawn_delta_levels,
+        threat_spawn_delta_levels: params.threat_spawn_delta_levels,
+        win_level: params.win_level,
+    }
+}
+
+fn map_big_fish_asset_slot_response(slot: BigFishAssetSlotRecord) -> BigFishAssetSlotResponse {
+    BigFishAssetSlotResponse {
+        slot_id: slot.slot_id,
+        asset_kind: slot.asset_kind,
+        level: slot.level,
+        motion_key: slot.motion_key,
+        status: slot.status,
+        asset_url: slot.asset_url,
+        prompt_snapshot: slot.prompt_snapshot,
+        updated_at: slot.updated_at,
+    }
+}
+
+fn map_big_fish_asset_coverage_response(
+    coverage: BigFishAssetCoverageRecord,
+) -> BigFishAssetCoverageResponse {
+    BigFishAssetCoverageResponse {
+        level_main_image_ready_count: coverage.level_main_image_ready_count,
+        level_motion_ready_count: coverage.level_motion_ready_count,
+        background_ready: coverage.background_ready,
+        required_level_count: coverage.required_level_count,
+        publish_ready: coverage.publish_ready,
+        blockers: coverage.blockers,
+    }
+}
+
+fn map_big_fish_agent_message_response(
+    message: BigFishAgentMessageRecord,
+) -> BigFishAgentMessageResponse {
+    BigFishAgentMessageResponse {
+        id: message.message_id,
+        role: message.role,
+        kind: message.kind,
+        text: message.text,
+        created_at: message.created_at,
+    }
+}
+
+fn map_big_fish_runtime_response(run: BigFishRuntimeRecord) -> BigFishRuntimeSnapshotResponse {
+    BigFishRuntimeSnapshotResponse {
+        run_id: run.run_id,
+        session_id: run.session_id,
+        status: run.status,
+        tick: run.tick,
+        player_level: run.player_level,
+        win_level: run.win_level,
+        leader_entity_id: run.leader_entity_id,
+        owned_entities: run
+            .owned_entities
+            .into_iter()
+            .map(map_big_fish_entity_response)
+            .collect(),
+        wild_entities: run
+            .wild_entities
+            .into_iter()
+            .map(map_big_fish_entity_response)
+            .collect(),
+        camera_center: map_big_fish_vector_response(run.camera_center),
+        last_input: map_big_fish_vector_response(run.last_input),
+        event_log: run.event_log,
+        updated_at: run.updated_at,
+    }
+}
+
+fn map_big_fish_entity_response(entity: BigFishRuntimeEntityRecord) -> BigFishRuntimeEntityResponse {
+    BigFishRuntimeEntityResponse {
+        entity_id: entity.entity_id,
+        level: entity.level,
+        position: map_big_fish_vector_response(entity.position),
+        radius: entity.radius,
+        offscreen_seconds: entity.offscreen_seconds,
+    }
+}
+
+fn map_big_fish_vector_response(vector: BigFishVector2Record) -> BigFishVector2Response {
+    BigFishVector2Response {
+        x: vector.x,
+        y: vector.y,
+    }
+}
+
+fn build_big_fish_welcome_text(seed_text: &str) -> String {
+    if seed_text.trim().is_empty() {
+        return "我会先帮你确定大鱼吃小鱼的核心锚点。可以从主题生态、成长阶梯或风险节奏开始。".to_string();
+    }
+    "我已经收到你的玩法起点，会先把它整理成锚点并准备结果页草稿。".to_string()
+}
+
+fn ensure_non_empty(
+    request_context: &RequestContext,
+    value: &str,
+    field_name: &str,
+) -> Result<(), Response> {
+    if value.trim().is_empty() {
+        return Err(big_fish_bad_request(
+            request_context,
+            format!("{field_name} is required").as_str(),
+        ));
+    }
+    Ok(())
+}
+
+fn big_fish_bad_request(request_context: &RequestContext, message: &str) -> Response {
+    big_fish_error_response(
+        request_context,
+        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+            "provider": "big-fish",
+            "message": message,
+        })),
+    )
+}
+
+fn append_sse_event(
+    request_context: &RequestContext,
+    body: &mut String,
+    event: &str,
+    payload: &Value,
+) -> Result<(), Response> {
+    let payload_text = serde_json::to_string(payload).map_err(|error| {
+        big_fish_error_response(
+            request_context,
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+                "provider": "big-fish",
+                "message": format!("SSE payload 序列化失败：{error}"),
+            })),
+        )
+    })?;
+    body.push_str("event: ");
+    body.push_str(event);
+    body.push('\n');
+    body.push_str("data: ");
+    body.push_str(&payload_text);
+    body.push_str("\n\n");
+    Ok(())
+}
+
+fn build_event_stream_response(body: String) -> Response {
+    (
+        [
+            (header::CONTENT_TYPE, "text/event-stream; charset=utf-8"),
+            (header::CACHE_CONTROL, "no-cache"),
+            (HeaderName::from_static("x-accel-buffering"), "no"),
+        ],
+        body,
+    )
+        .into_response()
+}
+
+fn map_big_fish_client_error(error: SpacetimeClientError) -> AppError {
+    let status = match &error {
+        SpacetimeClientError::Procedure(message)
+            if message.contains("big_fish_creation_session 不存在")
+                || message.contains("big_fish_runtime_run 不存在") =>
+        {
+            StatusCode::NOT_FOUND
+        }
+        SpacetimeClientError::Procedure(message)
+            if message.contains("不能为空")
+                || message.contains("尚未编译")
+                || message.contains("不允许")
+                || message.contains("非法")
+                || message.contains("缺少") =>
+        {
+            StatusCode::BAD_REQUEST
+        }
+        SpacetimeClientError::Runtime(_) => StatusCode::BAD_REQUEST,
+        _ => StatusCode::BAD_GATEWAY,
+    };
+
+    AppError::from_status(status).with_details(json!({
+        "provider": "spacetimedb",
+        "message": error.to_string(),
+    }))
+}
+
+fn big_fish_error_response(request_context: &RequestContext, error: AppError) -> Response {
+    error.into_response_with_context(Some(request_context))
+}
+
+fn current_utc_micros() -> i64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    let duration = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("system clock should be after unix epoch");
+    i64::try_from(duration.as_micros()).expect("current unix micros should fit in i64")
+}

server-rs/crates/api-server/src/config.rs

@@ -6,6 +6,7 @@ use platform_llm::{
 };
 
 const DEFAULT_LLM_MODEL: &str = "doubao-1-5-pro-32k-character-250715";
+const DEFAULT_INTERNAL_API_SECRET: &str = "genarrative-dev-internal-bridge";
 
 // 集中管理 api-server 的启动配置，避免入口层直接散落环境变量解析逻辑。
 #[derive(Clone, Debug)]
@@ -13,6 +14,7 @@ pub struct AppConfig {
     pub bind_host: String,
     pub bind_port: u16,
     pub log_filter: String,
+    pub internal_api_secret: Option<String>,
     pub jwt_issuer: String,
     pub jwt_secret: String,
     pub jwt_access_token_ttl_seconds: u64,
@@ -62,6 +64,7 @@ impl Default for AppConfig {
             bind_host: "127.0.0.1".to_string(),
             bind_port: 3000,
             log_filter: "info,tower_http=info".to_string(),
+            internal_api_secret: Some(DEFAULT_INTERNAL_API_SECRET.to_string()),
             jwt_issuer: "https://auth.genarrative.local".to_string(),
             jwt_secret: "genarrative-dev-secret".to_string(),
             jwt_access_token_ttl_seconds: 2 * 60 * 60,
@@ -130,6 +133,9 @@ impl AppConfig {
             config.log_filter = log_filter;
         }
 
+        config.internal_api_secret =
+            read_first_non_empty_env(&["GENARRATIVE_INTERNAL_API_SECRET"]);
+
         if let Some(jwt_issuer) =
             read_first_non_empty_env(&["GENARRATIVE_JWT_ISSUER", "JWT_ISSUER"])
         {

server-rs/crates/api-server/src/main.rs

@@ -6,6 +6,7 @@ mod auth;
 mod auth_me;
 mod auth_session;
 mod auth_sessions;
+mod big_fish;
 mod config;
 mod custom_world;
 mod custom_world_ai;
@@ -18,6 +19,7 @@ mod logout;
 mod logout_all;
 mod password_entry;
 mod phone_auth;
+mod puzzle;
 mod refresh_session;
 mod request_context;
 mod response_headers;

server-rs/crates/api-server/src/runtime_story.rs

@@ -1,6 +1,6 @@
 use axum::{
     Json,
-    extract::{Extension, State},
+    extract::{Extension, Path, State, rejection::JsonRejection},
     http::StatusCode,
     response::Response,
 };
@@ -54,6 +54,91 @@ pub async fn resolve_runtime_story_state(
     ))
 }
 
+pub async fn get_runtime_story_state(
+    State(_state): State<AppState>,
+    Path(session_id): Path<String>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+) -> Result<Json<Value>, Response> {
+    let session_id = normalize_required_string(session_id.as_str()).ok_or_else(|| {
+        runtime_story_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "runtime-story",
+                "field": "sessionId",
+                "message": "sessionId 不能为空",
+            })),
+        )
+    })?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_state_response(&session_id, None, build_runtime_story_empty_snapshot(&session_id)),
+    ))
+}
+
+pub async fn resolve_runtime_story_action(
+    State(_state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<Value>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let payload = optional_runtime_story_payload(payload)?;
+    let session_id = read_payload_session_id(&payload).ok_or_else(|| {
+        runtime_story_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "runtime-story",
+                "field": "sessionId",
+                "message": "sessionId 不能为空",
+            })),
+        )
+    })?;
+    let client_version = read_u32_field(&payload, "clientVersion");
+    let snapshot = read_payload_snapshot(&payload)
+        .unwrap_or_else(|| build_runtime_story_empty_snapshot(&session_id));
+    let mut response = build_runtime_story_state_response(&session_id, client_version, snapshot);
+    response.presentation.action_text = read_runtime_story_action_text(&payload).unwrap_or_default();
+
+    Ok(json_success_body(Some(&request_context), response))
+}
+
+pub async fn generate_runtime_story_initial(
+    State(_state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<Value>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let payload = optional_runtime_story_payload(payload)?;
+    let session_id = read_payload_session_id(&payload).unwrap_or_else(|| "runtime-main".to_string());
+    let client_version = read_u32_field(&payload, "clientVersion");
+    let snapshot = read_payload_snapshot(&payload)
+        .unwrap_or_else(|| build_runtime_story_empty_snapshot(&session_id));
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_state_response(&session_id, client_version, snapshot),
+    ))
+}
+
+pub async fn generate_runtime_story_continue(
+    State(_state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<Value>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let payload = optional_runtime_story_payload(payload)?;
+    let session_id = read_payload_session_id(&payload).unwrap_or_else(|| "runtime-main".to_string());
+    let client_version = read_u32_field(&payload, "clientVersion");
+    let snapshot = read_payload_snapshot(&payload)
+        .unwrap_or_else(|| build_runtime_story_empty_snapshot(&session_id));
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_state_response(&session_id, client_version, snapshot),
+    ))
+}
+
 fn build_runtime_story_state_response(
     requested_session_id: &str,
     client_version: Option<u32>,
@@ -107,6 +192,61 @@ fn build_runtime_story_state_response(
     }
 }
 
+fn optional_runtime_story_payload(
+    payload: Result<Json<Value>, JsonRejection>,
+) -> Result<Value, Response> {
+    match payload {
+        Ok(Json(value)) => Ok(value),
+        Err(error) if error.status() == StatusCode::UNSUPPORTED_MEDIA_TYPE => Ok(json!({})),
+        Err(error) if error.status() == StatusCode::BAD_REQUEST => Ok(json!({})),
+        Err(error) => Err(AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_details(json!({
+                "provider": "runtime-story",
+                "message": error.body_text(),
+            }))
+            .into_response_with_context(None)),
+    }
+}
+
+fn read_payload_session_id(payload: &Value) -> Option<String> {
+    read_required_string_field(payload, "sessionId")
+        .or_else(|| read_field(payload, "action").and_then(|action| read_required_string_field(action, "sessionId")))
+        .or_else(|| read_field(payload, "snapshot").and_then(|snapshot| {
+            read_object_field(snapshot, "gameState").and_then(read_runtime_session_id)
+        }))
+}
+
+fn read_payload_snapshot(payload: &Value) -> Option<RuntimeStorySnapshotPayload> {
+    let snapshot = read_field(payload, "snapshot")?.clone();
+    serde_json::from_value(snapshot).ok()
+}
+
+fn read_runtime_story_action_text(payload: &Value) -> Option<String> {
+    let action = read_field(payload, "action")?;
+    read_optional_string_field(action, "functionId")
+        .or_else(|| read_optional_string_field(action, "type"))
+}
+
+fn build_runtime_story_empty_snapshot(session_id: &str) -> RuntimeStorySnapshotPayload {
+    RuntimeStorySnapshotPayload {
+        saved_at: time::OffsetDateTime::now_utc()
+            .format(&time::format_description::well_known::Rfc3339)
+            .unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string()),
+        bottom_tab: "adventure".to_string(),
+        game_state: json!({
+            "runtimeSessionId": session_id,
+            "runtimeActionVersion": 0,
+            "playerHp": 1,
+            "playerMaxHp": 1,
+            "playerMana": 0,
+            "playerMaxMana": 1,
+            "inBattle": false,
+            "npcInteractionActive": false
+        }),
+        current_story: None,
+    }
+}
+
 fn build_runtime_story_companions(game_state: &Value) -> Vec<RuntimeStoryCompanionViewModel> {
     read_array_field(game_state, "companions")
         .into_iter()