Merge branch 'codex/backend-rewrite-spacetimedb' of http://82.157.175.59:3000/GenarrativeAI/Genarrative into codex/backend-rewrite-spacetimedb

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

@@ -6,8 +6,11 @@ use axum::{
     middleware,
     routing::{get, post},
 };
-use tower_http::trace::{DefaultOnFailure, DefaultOnRequest, DefaultOnResponse, TraceLayer};
-use tracing::{Level, info_span};
+use tower_http::{
+    classify::ServerErrorsFailureClass,
+    trace::{DefaultOnRequest, TraceLayer},
+};
+use tracing::{Level, Span, error, info, info_span, warn};
 
 use crate::{
     ai_tasks::{
@@ -29,13 +32,19 @@ use crate::{
         start_big_fish_run, stream_big_fish_message, submit_big_fish_input,
         submit_big_fish_message,
     },
+    character_animation_assets::{
+        generate_character_animation, get_character_animation_job, get_character_workflow_cache,
+        import_character_animation_video, list_character_animation_templates,
+        publish_character_animation, save_character_workflow_cache,
+    },
+    character_visual_assets::{
+        generate_character_visual, get_character_visual_job, publish_character_visual,
+    },
     custom_world::{
         create_custom_world_agent_session, execute_custom_world_agent_action,
-        get_custom_world_agent_card_detail,
-        get_custom_world_agent_operation, get_custom_world_agent_session,
-        get_custom_world_works,
-        get_custom_world_gallery_detail, get_custom_world_library,
-        get_custom_world_library_detail, list_custom_world_gallery,
+        get_custom_world_agent_card_detail, get_custom_world_agent_operation,
+        get_custom_world_agent_session, get_custom_world_gallery_detail, get_custom_world_library,
+        get_custom_world_library_detail, get_custom_world_works, list_custom_world_gallery,
         publish_custom_world_library_profile, put_custom_world_library_profile,
         stream_custom_world_agent_message, submit_custom_world_agent_message,
         unpublish_custom_world_library_profile,
@@ -47,6 +56,11 @@ use crate::{
     },
     error_middleware::normalize_error_response,
     health::health_check,
+    legacy_generated_assets::{
+        proxy_generated_animations, proxy_generated_character_drafts, proxy_generated_characters,
+        proxy_generated_custom_world_covers, proxy_generated_custom_world_scenes,
+        proxy_generated_qwen_sprites,
+    },
     llm::proxy_llm_chat_completions,
     login_options::auth_login_options,
     logout::logout,
@@ -74,8 +88,8 @@ use crate::{
     },
     runtime_settings::{get_runtime_settings, put_runtime_settings},
     runtime_story::{
-        generate_runtime_story_continue, generate_runtime_story_initial,
-        get_runtime_story_state, resolve_runtime_story_action, resolve_runtime_story_state,
+        generate_runtime_story_continue, generate_runtime_story_initial, get_runtime_story_state,
+        resolve_runtime_story_action, resolve_runtime_story_state,
     },
     state::AppState,
     story_battles::{
@@ -87,6 +101,8 @@ use crate::{
 
 // 统一由这里构造 Axum 路由树，后续再逐项挂接中间件与业务路由。
 pub fn build_router(state: AppState) -> Router {
+    let slow_request_threshold_ms = state.config.slow_request_threshold_ms;
+
     Router::new()
         .route(
             "/healthz",
@@ -109,6 +125,30 @@ pub fn build_router(state: AppState) -> Router {
             )),
         )
         .route("/api/auth/login-options", get(auth_login_options))
+        .route(
+            "/generated-character-drafts/{*path}",
+            get(proxy_generated_character_drafts),
+        )
+        .route(
+            "/generated-characters/{*path}",
+            get(proxy_generated_characters),
+        )
+        .route(
+            "/generated-animations/{*path}",
+            get(proxy_generated_animations),
+        )
+        .route(
+            "/generated-custom-world-scenes/{*path}",
+            get(proxy_generated_custom_world_scenes),
+        )
+        .route(
+            "/generated-custom-world-covers/{*path}",
+            get(proxy_generated_custom_world_covers),
+        )
+        .route(
+            "/generated-qwen-sprites/{*path}",
+            get(proxy_generated_qwen_sprites),
+        )
         .route(
             "/api/auth/me",
             get(auth_me).route_layer(middleware::from_fn_with_state(
@@ -248,15 +288,55 @@ pub fn build_router(state: AppState) -> Router {
             "/api/assets/objects/bind",
             post(bind_asset_object_to_entity),
         )
+        .route(
+            "/api/assets/character-visual/generate",
+            post(generate_character_visual),
+        )
+        .route(
+            "/api/assets/character-visual/jobs/{task_id}",
+            get(get_character_visual_job),
+        )
+        .route(
+            "/api/assets/character-visual/publish",
+            post(publish_character_visual),
+        )
+        .route(
+            "/api/assets/character-animation/generate",
+            post(generate_character_animation),
+        )
+        .route(
+            "/api/assets/character-animation/jobs/{task_id}",
+            get(get_character_animation_job),
+        )
+        .route(
+            "/api/assets/character-animation/publish",
+            post(publish_character_animation),
+        )
+        .route(
+            "/api/assets/character-animation/import-video",
+            post(import_character_animation_video),
+        )
+        .route(
+            "/api/assets/character-animation/templates",
+            get(list_character_animation_templates),
+        )
+        .route(
+            "/api/assets/character-workflow-cache",
+            post(save_character_workflow_cache),
+        )
+        .route(
+            "/api/assets/character-workflow-cache/{character_id}",
+            get(get_character_workflow_cache),
+        )
         .route("/api/assets/read-url", get(get_asset_read_url))
         .route(
             "/api/runtime/settings",
             get(get_runtime_settings)
                 .put(put_runtime_settings)
                 .route_layer(middleware::from_fn_with_state(
-                state.clone(),
-                require_bearer_auth,
-            )),
+                    state.clone(),
+                    require_bearer_auth,
+                )),
         )
         .route(
             "/api/runtime/save/snapshot",
@@ -328,9 +408,10 @@ pub fn build_router(state: AppState) -> Router {
         )
         .route(
             "/api/runtime/custom-world/agent/sessions/{session_id}/cards/{card_id}",
-            get(get_custom_world_agent_card_detail).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            get(get_custom_world_agent_card_detail).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/runtime/custom-world/agent/sessions/{session_id}/messages",
@@ -523,45 +604,52 @@ pub fn build_router(state: AppState) -> Router {
         )
         .route(
             "/api/custom-world/scene-npc",
-            post(generate_custom_world_scene_npc).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(generate_custom_world_scene_npc).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/runtime/custom-world/scene-npc",
-            post(generate_custom_world_scene_npc).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(generate_custom_world_scene_npc).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/custom-world/scene-image",
-            post(generate_custom_world_scene_image).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(generate_custom_world_scene_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/custom-world/cover-image",
-            post(generate_custom_world_cover_image).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(generate_custom_world_cover_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/runtime/custom-world/cover-image",
-            post(generate_custom_world_cover_image).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(generate_custom_world_cover_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/custom-world/cover-upload",
-            post(upload_custom_world_cover_image).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(upload_custom_world_cover_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/runtime/custom-world/cover-upload",
-            post(upload_custom_world_cover_image).route_layer(
-                middleware::from_fn_with_state(state.clone(), require_bearer_auth),
-            ),
+            post(upload_custom_world_cover_image).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
         )
         .route(
             "/api/runtime/profile/browse-history",
@@ -764,8 +852,47 @@ pub fn build_router(state: AppState) -> Router {
                     )
                 })
                 .on_request(DefaultOnRequest::new().level(Level::INFO))
-                .on_response(DefaultOnResponse::new().level(Level::INFO))
-                .on_failure(DefaultOnFailure::new().level(Level::ERROR)),
+                .on_response(
+                    move |response: &axum::response::Response,
+                          latency: std::time::Duration,
+                          span: &Span| {
+                        let latency_ms = latency.as_millis().min(u64::MAX as u128) as u64;
+                        let status = response.status().as_u16();
+                        let slow_request = latency_ms >= slow_request_threshold_ms;
+                        span.record("status", status);
+                        span.record("latency_ms", latency_ms);
+                        if slow_request {
+                            warn!(
+                                parent: span,
+                                status,
+                                latency_ms,
+                                slow_request = true,
+                                "http request completed slowly"
+                            );
+                        } else {
+                            info!(
+                                parent: span,
+                                status,
+                                latency_ms,
+                                slow_request = false,
+                                "http request completed"
+                            );
+                        }
+                    },
+                )
+                .on_failure(
+                    |failure: ServerErrorsFailureClass,
+                     latency: std::time::Duration,
+                     span: &Span| {
+                        let latency_ms = latency.as_millis().min(u64::MAX as u128) as u64;
+                        error!(
+                            parent: span,
+                            latency_ms,
+                            failure = %failure,
+                            "http request failed"
+                        );
+                    },
+                ),
         )
         // request_id 中间件先进入请求链，确保后续 tracing、错误处理和响应头层都能复用同一份请求标识。
         .layer(middleware::from_fn(attach_request_context))

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

@@ -0,0 +1,938 @@
+use std::collections::BTreeMap;
+
+use axum::{
+    Json,
+    extract::{Extension, Path, State, rejection::JsonRejection},
+    http::StatusCode,
+    response::Response,
+};
+use module_ai::{
+    AiResultReferenceKind, AiStageCompletionInput, AiTaskCreateInput, AiTaskKind,
+    AiTaskServiceError, AiTaskSnapshot, AiTaskStageKind, AiTaskStatus, generate_ai_task_id,
+};
+use module_assets::{
+    AssetObjectAccessPolicy, AssetObjectFieldError, build_asset_entity_binding_input,
+    build_asset_object_upsert_input, generate_asset_binding_id, generate_asset_object_id,
+};
+use platform_llm::{LlmMessage, LlmTextRequest};
+use platform_oss::{
+    LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess, OssPutObjectRequest,
+    OssSignedGetObjectUrlRequest,
+};
+use serde_json::{Value, json};
+use shared_contracts::assets::{
+    CharacterAssetJobStatusPayload, CharacterAssetJobStatusText, CharacterVisualDraftPayload,
+    CharacterVisualGenerateRequest, CharacterVisualGenerateResponse, CharacterVisualPublishRequest,
+    CharacterVisualPublishResponse,
+};
+use spacetime_client::SpacetimeClientError;
+
+use crate::{
+    api_response::json_success_body, http_error::AppError, request_context::RequestContext,
+    state::AppState,
+};
+
+const CHARACTER_VISUAL_MODEL: &str = "rust-svg-character-visual";
+const CHARACTER_VISUAL_ASSET_KIND: &str = "character_visual";
+const CHARACTER_VISUAL_ENTITY_KIND: &str = "character";
+const CHARACTER_VISUAL_SLOT: &str = "primary_visual";
+
+pub async fn generate_character_visual(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    payload: Result<Json<CharacterVisualGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        character_visual_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "character-visual",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    // 旧资产工坊接口没有显式 Bearer 头，Rust 兼容层先使用工具用户归属，避免破坏现有前端调用。
+    let owner_user_id = "asset-tool".to_string();
+    let task_id = generate_ai_task_id(current_utc_micros());
+    let prompt = build_character_visual_prompt(
+        payload.prompt_text.as_str(),
+        payload.character_brief_text.as_deref(),
+    );
+    let character_id = normalize_required_text(payload.character_id.as_str(), "character");
+    let model = normalize_required_text(payload.image_model.as_str(), CHARACTER_VISUAL_MODEL);
+    let size = normalize_required_text(payload.size.as_str(), "1024*1024");
+    let candidate_count = payload.candidate_count.clamp(1, 4);
+
+    let created = create_visual_task(
+        &state,
+        &task_id,
+        &owner_user_id,
+        &character_id,
+        &model,
+        &prompt,
+    )
+    .map_err(|error| character_visual_error_response(&request_context, error))?;
+
+    let result = async {
+        state
+            .ai_task_service()
+            .start_task(task_id.as_str(), current_utc_micros())
+            .map_err(map_ai_task_error)?;
+        state
+            .ai_task_service()
+            .start_stage(
+                task_id.as_str(),
+                AiTaskStageKind::PreparePrompt,
+                current_utc_micros(),
+            )
+            .map_err(map_ai_task_error)?;
+        state
+            .ai_task_service()
+            .complete_stage(AiStageCompletionInput {
+                task_id: task_id.clone(),
+                stage_kind: AiTaskStageKind::PreparePrompt,
+                text_output: Some(prompt.clone()),
+                structured_payload_json: Some(
+                    json!({
+                        "characterId": character_id,
+                        "sourceMode": payload.source_mode,
+                        "size": size,
+                        "referenceImageCount": payload.reference_image_data_urls.len(),
+                    })
+                    .to_string(),
+                ),
+                warning_messages: Vec::new(),
+                completed_at_micros: current_utc_micros(),
+            })
+            .map_err(map_ai_task_error)?;
+
+        let visual_seed = generate_visual_seed_with_llm(&state, &prompt, &character_id).await;
+
+        state
+            .ai_task_service()
+            .start_stage(
+                task_id.as_str(),
+                AiTaskStageKind::RequestModel,
+                current_utc_micros(),
+            )
+            .map_err(map_ai_task_error)?;
+        state
+            .ai_task_service()
+            .complete_stage(AiStageCompletionInput {
+                task_id: task_id.clone(),
+                stage_kind: AiTaskStageKind::RequestModel,
+                text_output: Some(visual_seed.clone()),
+                structured_payload_json: None,
+                warning_messages: Vec::new(),
+                completed_at_micros: current_utc_micros(),
+            })
+            .map_err(map_ai_task_error)?;
+
+        let drafts = persist_visual_drafts(
+            &state,
+            &owner_user_id,
+            &character_id,
+            &task_id,
+            &visual_seed,
+            &size,
+            candidate_count,
+        )
+        .await?;
+
+        let result_payload = json!({
+            "drafts": drafts,
+            "draftRelativeDir": format!(
+                "generated-character-drafts/{}/visual/{}",
+                sanitize_storage_segment(character_id.as_str(), "character"),
+                task_id
+            ),
+        });
+
+        state
+            .ai_task_service()
+            .start_stage(
+                task_id.as_str(),
+                AiTaskStageKind::NormalizeResult,
+                current_utc_micros(),
+            )
+            .map_err(map_ai_task_error)?;
+        state
+            .ai_task_service()
+            .complete_stage(AiStageCompletionInput {
+                task_id: task_id.clone(),
+                stage_kind: AiTaskStageKind::NormalizeResult,
+                text_output: None,
+                structured_payload_json: Some(result_payload.to_string()),
+                warning_messages: Vec::new(),
+                completed_at_micros: current_utc_micros(),
+            })
+            .map_err(map_ai_task_error)?;
+        state
+            .ai_task_service()
+            .complete_stage(AiStageCompletionInput {
+                task_id: task_id.clone(),
+                stage_kind: AiTaskStageKind::PersistResult,
+                text_output: Some("角色主形象候选草稿已写入 OSS。".to_string()),
+                structured_payload_json: Some(result_payload.to_string()),
+                warning_messages: Vec::new(),
+                completed_at_micros: current_utc_micros(),
+            })
+            .map_err(map_ai_task_error)?;
+        state
+            .ai_task_service()
+            .complete_task(task_id.as_str(), current_utc_micros())
+            .map_err(map_ai_task_error)?;
+
+        Ok::<_, AppError>(drafts)
+    }
+    .await;
+
+    let drafts = match result {
+        Ok(drafts) => drafts,
+        Err(error) => {
+            let _ = state.ai_task_service().fail_task(
+                created.task_id.as_str(),
+                error.message().to_string(),
+                current_utc_micros(),
+            );
+            return Err(character_visual_error_response(&request_context, error));
+        }
+    };
+
+    Ok(json_success_body(
+        Some(&request_context),
+        CharacterVisualGenerateResponse {
+            ok: true,
+            task_id,
+            model,
+            prompt,
+            drafts,
+        },
+    ))
+}
+
+pub async fn get_character_visual_job(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Path(task_id): Path<String>,
+) -> Result<Json<Value>, Response> {
+    let task = state
+        .ai_task_service()
+        .get_task(task_id.as_str())
+        .map_err(map_ai_task_error)
+        .map_err(|error| character_visual_error_response(&request_context, error))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_character_visual_job_payload(task),
+    ))
+}
+
+pub async fn publish_character_visual(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    payload: Result<Json<CharacterVisualPublishRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        character_visual_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "character-visual",
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    // 旧资产工坊接口没有显式 Bearer 头，Rust 兼容层先使用工具用户归属，避免破坏现有前端调用。
+    let owner_user_id = "asset-tool".to_string();
+    let character_id = normalize_required_text(payload.character_id.as_str(), "character");
+    if payload.selected_preview_source.trim().is_empty() {
+        return Err(character_visual_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "character-visual",
+                "message": "selectedPreviewSource is required.",
+            })),
+        ));
+    }
+
+    let asset_id = format!("visual-{}", current_utc_millis());
+    let published = persist_published_visual(
+        &state,
+        &owner_user_id,
+        &character_id,
+        asset_id.as_str(),
+        payload.selected_preview_source.as_str(),
+        payload.prompt_text.as_deref(),
+    )
+    .await
+    .map_err(|error| character_visual_error_response(&request_context, error))?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        CharacterVisualPublishResponse {
+            ok: true,
+            asset_id,
+            portrait_path: published,
+            override_map: json!({}),
+            save_message: if payload.update_character_override == Some(false) {
+                "主形象已写入 OSS 并绑定当前角色，可直接写回当前自定义世界角色。".to_string()
+            } else {
+                "主形象已写入 OSS 并绑定当前角色；Rust 后端不再写本地角色覆盖文件。".to_string()
+            },
+        },
+    ))
+}
+
+fn create_visual_task(
+    state: &AppState,
+    task_id: &str,
+    owner_user_id: &str,
+    character_id: &str,
+    model: &str,
+    prompt: &str,
+) -> Result<AiTaskSnapshot, AppError> {
+    state
+        .ai_task_service()
+        .create_task(AiTaskCreateInput {
+            task_id: task_id.to_string(),
+            task_kind: AiTaskKind::CustomWorldGeneration,
+            owner_user_id: owner_user_id.to_string(),
+            request_label: "生成角色主形象".to_string(),
+            source_module: "assets.character_visual".to_string(),
+            source_entity_id: Some(character_id.to_string()),
+            request_payload_json: Some(
+                json!({
+                    "characterId": character_id,
+                    "model": model,
+                    "prompt": prompt,
+                })
+                .to_string(),
+            ),
+            stages: AiTaskKind::CustomWorldGeneration.default_stage_blueprints(),
+            created_at_micros: current_utc_micros(),
+        })
+        .map_err(map_ai_task_error)
+}
+
+async fn generate_visual_seed_with_llm(
+    state: &AppState,
+    prompt: &str,
+    character_id: &str,
+) -> String {
+    let fallback = format!("{character_id}：{prompt}");
+    let Some(llm_client) = state.llm_client() else {
+        return fallback;
+    };
+
+    let request = LlmTextRequest::new(vec![
+        LlmMessage::system(
+            "你是游戏角色主形象草稿描述器。只输出一句中文视觉摘要，不要输出 Markdown。",
+        ),
+        LlmMessage::user(
+            json!({
+                "task": "summarize_character_visual_seed",
+                "characterId": character_id,
+                "prompt": prompt,
+            })
+            .to_string(),
+        ),
+    ])
+    .with_max_tokens(96);
+
+    llm_client
+        .request_text(request)
+        .await
+        .ok()
+        .map(|response| response.content.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .unwrap_or(fallback)
+}
+
+async fn persist_visual_drafts(
+    state: &AppState,
+    owner_user_id: &str,
+    character_id: &str,
+    task_id: &str,
+    visual_seed: &str,
+    size: &str,
+    candidate_count: u32,
+) -> Result<Vec<CharacterVisualDraftPayload>, AppError> {
+    let mut drafts = Vec::with_capacity(candidate_count as usize);
+    for index in 0..candidate_count {
+        let file_name = format!("candidate-{:02}.svg", index + 1);
+        let body =
+            build_character_visual_svg(size, visual_seed, format!("候选 {}", index + 1).as_str())
+                .into_bytes();
+        let put_result = put_character_visual_object(
+            state,
+            LegacyAssetPrefix::CharacterDrafts,
+            vec![
+                sanitize_storage_segment(character_id, "character"),
+                "visual".to_string(),
+                task_id.to_string(),
+            ],
+            file_name,
+            "image/svg+xml".to_string(),
+            body,
+            build_asset_metadata(
+                CHARACTER_VISUAL_ASSET_KIND,
+                owner_user_id,
+                CHARACTER_VISUAL_ENTITY_KIND,
+                character_id,
+                "draft",
+            ),
+        )
+        .await?;
+
+        drafts.push(CharacterVisualDraftPayload {
+            id: format!("candidate-{}", index + 1),
+            label: format!("候选 {}", index + 1),
+            image_src: put_result.legacy_public_path,
+            width: parse_size(size).0,
+            height: parse_size(size).1,
+        });
+    }
+
+    Ok(drafts)
+}
+
+async fn persist_published_visual(
+    state: &AppState,
+    owner_user_id: &str,
+    character_id: &str,
+    asset_id: &str,
+    selected_preview_source: &str,
+    prompt_text: Option<&str>,
+) -> Result<String, AppError> {
+    let oss_client = require_oss_client(state)?;
+    let http_client = reqwest::Client::new();
+    let source_object_key = resolve_object_key_from_legacy_path(selected_preview_source)?;
+    let head = oss_client
+        .head_object(
+            &http_client,
+            OssHeadObjectRequest {
+                object_key: source_object_key.clone(),
+            },
+        )
+        .await
+        .map_err(map_character_visual_oss_error)?;
+    let signed = oss_client
+        .sign_get_object_url(OssSignedGetObjectUrlRequest {
+            object_key: source_object_key,
+            expire_seconds: Some(60),
+        })
+        .map_err(map_character_visual_oss_error)?;
+    let source_body = http_client
+        .get(signed.signed_url)
+        .send()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取候选主形象失败：{error}"),
+            }))
+        })?
+        .error_for_status()
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取候选主形象失败：{error}"),
+            }))
+        })?
+        .bytes()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取候选主形象内容失败：{error}"),
+            }))
+        })?
+        .to_vec();
+
+    let content_type = head
+        .content_type
+        .clone()
+        .unwrap_or_else(|| "image/svg+xml".to_string());
+    let file_name = match content_type.as_str() {
+        "image/png" => "master.png",
+        "image/jpeg" => "master.jpg",
+        "image/webp" => "master.webp",
+        _ => "master.svg",
+    }
+    .to_string();
+    let put_result = put_character_visual_object(
+        state,
+        LegacyAssetPrefix::Characters,
+        vec![
+            sanitize_storage_segment(character_id, "character"),
+            "visual".to_string(),
+            asset_id.to_string(),
+        ],
+        file_name,
+        content_type.clone(),
+        source_body,
+        build_asset_metadata(
+            CHARACTER_VISUAL_ASSET_KIND,
+            owner_user_id,
+            CHARACTER_VISUAL_ENTITY_KIND,
+            character_id,
+            CHARACTER_VISUAL_SLOT,
+        ),
+    )
+    .await?;
+    let confirmed = confirm_character_visual_asset_object(
+        state,
+        owner_user_id,
+        character_id,
+        asset_id,
+        put_result.object_key.clone(),
+        content_type,
+        prompt_text.map(str::to_string),
+    )
+    .await?;
+    bind_character_visual_asset(
+        state,
+        owner_user_id,
+        character_id,
+        confirmed.record.asset_object_id,
+    )
+    .await?;
+
+    Ok(put_result.legacy_public_path)
+}
+
+async fn put_character_visual_object(
+    state: &AppState,
+    prefix: LegacyAssetPrefix,
+    path_segments: Vec<String>,
+    file_name: String,
+    content_type: String,
+    body: Vec<u8>,
+    metadata: BTreeMap<String, String>,
+) -> Result<platform_oss::OssPutObjectResponse, AppError> {
+    let oss_client = require_oss_client(state)?;
+    oss_client
+        .put_object(
+            &reqwest::Client::new(),
+            OssPutObjectRequest {
+                prefix,
+                path_segments,
+                file_name,
+                content_type: Some(content_type),
+                access: OssObjectAccess::Private,
+                metadata,
+                body,
+            },
+        )
+        .await
+        .map_err(map_character_visual_oss_error)
+}
+
+async fn confirm_character_visual_asset_object(
+    state: &AppState,
+    owner_user_id: &str,
+    character_id: &str,
+    source_job_id: &str,
+    object_key: String,
+    content_type: String,
+    prompt_text: Option<String>,
+) -> Result<module_assets::ConfirmAssetObjectResult, AppError> {
+    let oss_client = require_oss_client(state)?;
+    let head = oss_client
+        .head_object(&reqwest::Client::new(), OssHeadObjectRequest { object_key })
+        .await
+        .map_err(map_character_visual_oss_error)?;
+    let now_micros = current_utc_micros();
+    let record = state
+        .spacetime_client()
+        .confirm_asset_object(
+            build_asset_object_upsert_input(
+                generate_asset_object_id(now_micros),
+                head.bucket,
+                head.object_key,
+                AssetObjectAccessPolicy::Private,
+                head.content_type.or(Some(content_type)),
+                head.content_length,
+                prompt_text.or(head.etag),
+                CHARACTER_VISUAL_ASSET_KIND.to_string(),
+                Some(source_job_id.to_string()),
+                Some(owner_user_id.to_string()),
+                None,
+                Some(character_id.to_string()),
+                now_micros,
+            )
+            .map_err(map_asset_object_prepare_error)?,
+        )
+        .await
+        .map_err(map_character_visual_spacetime_error)?;
+    let _ = state.ai_task_service().attach_result_reference(
+        source_job_id,
+        AiResultReferenceKind::AssetObject,
+        record.asset_object_id.clone(),
+        Some("角色主形象正式对象".to_string()),
+        now_micros,
+    );
+    Ok(module_assets::ConfirmAssetObjectResult { record })
+}
+
+async fn bind_character_visual_asset(
+    state: &AppState,
+    owner_user_id: &str,
+    character_id: &str,
+    asset_object_id: String,
+) -> Result<(), AppError> {
+    let now_micros = current_utc_micros();
+    state
+        .spacetime_client()
+        .bind_asset_object_to_entity(
+            build_asset_entity_binding_input(
+                generate_asset_binding_id(now_micros),
+                asset_object_id,
+                CHARACTER_VISUAL_ENTITY_KIND.to_string(),
+                character_id.to_string(),
+                CHARACTER_VISUAL_SLOT.to_string(),
+                CHARACTER_VISUAL_ASSET_KIND.to_string(),
+                Some(owner_user_id.to_string()),
+                None,
+                now_micros,
+            )
+            .map_err(map_asset_binding_prepare_error)?,
+        )
+        .await
+        .map_err(map_character_visual_spacetime_error)?;
+    Ok(())
+}
+
+fn build_character_visual_job_payload(task: AiTaskSnapshot) -> CharacterAssetJobStatusPayload {
+    let request_payload = task
+        .request_payload_json
+        .as_deref()
+        .and_then(|value| serde_json::from_str::<Value>(value).ok())
+        .unwrap_or_else(|| json!({}));
+    let result = task
+        .latest_structured_payload_json
+        .as_deref()
+        .and_then(|value| serde_json::from_str::<Value>(value).ok());
+
+    CharacterAssetJobStatusPayload {
+        task_id: task.task_id,
+        kind: "visual".to_string(),
+        status: match task.status {
+            AiTaskStatus::Pending => CharacterAssetJobStatusText::Queued,
+            AiTaskStatus::Running => CharacterAssetJobStatusText::Running,
+            AiTaskStatus::Completed => CharacterAssetJobStatusText::Completed,
+            AiTaskStatus::Failed | AiTaskStatus::Cancelled => CharacterAssetJobStatusText::Failed,
+        },
+        character_id: request_payload
+            .get("characterId")
+            .and_then(Value::as_str)
+            .unwrap_or_default()
+            .to_string(),
+        animation: None,
+        strategy: None,
+        model: request_payload
+            .get("model")
+            .and_then(Value::as_str)
+            .unwrap_or(CHARACTER_VISUAL_MODEL)
+            .to_string(),
+        prompt: request_payload
+            .get("prompt")
+            .and_then(Value::as_str)
+            .unwrap_or_default()
+            .to_string(),
+        created_at: format_utc_micros(task.created_at_micros),
+        updated_at: format_utc_micros(task.updated_at_micros),
+        result,
+        error_message: task.failure_message,
+    }
+}
+
+fn build_character_visual_prompt(prompt_text: &str, character_brief_text: Option<&str>) -> String {
+    let merged = [character_brief_text.unwrap_or_default(), prompt_text]
+        .into_iter()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    format!(
+        "{}\n单人全身，右向斜侧身，3 到 4 头身，像素动作角色，纯绿色背景，服装完整，轮廓清晰，不要复杂背景。",
+        if merged.is_empty() {
+            "自定义世界角色，服装完整，姿态自然。"
+        } else {
+            merged.as_str()
+        }
+    )
+}
+
+fn build_character_visual_svg(size: &str, label: &str, candidate_label: &str) -> String {
+    let (width, height) = parse_size(size);
+    format!(
+        r##"<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
+<rect width="100%" height="100%" fill="#00ff00"/>
+<ellipse cx="{shadow_x}" cy="{shadow_y}" rx="{shadow_rx}" ry="{shadow_ry}" fill="rgba(0,0,0,0.18)"/>
+<path d="M {body_x} {body_y} C {body_c1x} {body_c1y}, {body_c2x} {body_c2y}, {body_x2} {body_y2} L {leg_x} {leg_y} L {leg2_x} {leg_y} Z" fill="#1f2937"/>
+<circle cx="{head_x}" cy="{head_y}" r="{head_r}" fill="#f8d7b0"/>
+<path d="M {weapon_x} {weapon_y} L {weapon_x2} {weapon_y2}" stroke="#e5e7eb" stroke-width="{weapon_w}" stroke-linecap="round"/>
+<text x="50%" y="{text_y}" text-anchor="middle" fill="#0f172a" font-size="{font_main}" font-family="Microsoft YaHei, PingFang SC, sans-serif">{title}</text>
+<text x="50%" y="{sub_y}" text-anchor="middle" fill="#0f172a" font-size="{font_sub}" font-family="Microsoft YaHei, PingFang SC, sans-serif">{candidate}</text>
+</svg>"##,
+        width = width,
+        height = height,
+        shadow_x = width / 2,
+        shadow_y = height * 5 / 6,
+        shadow_rx = width / 5,
+        shadow_ry = height / 28,
+        body_x = width * 45 / 100,
+        body_y = height * 34 / 100,
+        body_c1x = width * 34 / 100,
+        body_c1y = height * 50 / 100,
+        body_c2x = width * 43 / 100,
+        body_c2y = height * 72 / 100,
+        body_x2 = width * 56 / 100,
+        body_y2 = height * 72 / 100,
+        leg_x = width * 48 / 100,
+        leg_y = height * 84 / 100,
+        leg2_x = width * 62 / 100,
+        head_x = width * 53 / 100,
+        head_y = height * 25 / 100,
+        head_r = (width.min(height) / 12).max(18),
+        weapon_x = width * 57 / 100,
+        weapon_y = height * 42 / 100,
+        weapon_x2 = width * 76 / 100,
+        weapon_y2 = height * 34 / 100,
+        weapon_w = (width.min(height) / 90).max(4),
+        text_y = height * 91 / 100,
+        sub_y = height * 96 / 100,
+        font_main = (width.min(height) / 28).max(14),
+        font_sub = (width.min(height) / 36).max(11),
+        title = escape_svg_text(label),
+        candidate = escape_svg_text(candidate_label),
+    )
+}
+
+fn resolve_object_key_from_legacy_path(value: &str) -> Result<String, AppError> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "character-visual",
+                "message": "selectedPreviewSource is required.",
+            })),
+        );
+    }
+    if trimmed.starts_with("data:") {
+        return Err(AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+            "provider": "character-visual",
+            "message": "Rust 版 publish 当前要求 selectedPreviewSource 为已写入 OSS 的 /generated-* 路径。",
+        })));
+    }
+    Ok(trimmed.trim_start_matches('/').to_string())
+}
+
+fn build_asset_metadata(
+    asset_kind: &str,
+    owner_user_id: &str,
+    entity_kind: &str,
+    entity_id: &str,
+    slot: &str,
+) -> BTreeMap<String, String> {
+    BTreeMap::from([
+        ("asset_kind".to_string(), asset_kind.to_string()),
+        ("owner_user_id".to_string(), owner_user_id.to_string()),
+        ("entity_kind".to_string(), entity_kind.to_string()),
+        ("entity_id".to_string(), entity_id.to_string()),
+        ("slot".to_string(), slot.to_string()),
+    ])
+}
+
+fn require_oss_client(state: &AppState) -> Result<&platform_oss::OssClient, AppError> {
+    state.oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-oss",
+            "reason": "OSS 未完成环境变量配置",
+        }))
+    })
+}
+
+fn normalize_required_text(value: &str, fallback: &str) -> String {
+    value
+        .trim()
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ")
+        .chars()
+        .take(180)
+        .collect::<String>()
+        .trim()
+        .to_string()
+        .if_empty_then(fallback)
+}
+
+fn sanitize_storage_segment(value: &str, fallback: &str) -> String {
+    let normalized = value
+        .trim()
+        .chars()
+        .map(|character| match character {
+            'a'..='z' | '0'..='9' | '-' | '_' => character,
+            'A'..='Z' => character.to_ascii_lowercase(),
+            _ => '-',
+        })
+        .collect::<String>();
+    let normalized = collapse_dashes(&normalized);
+    if normalized.is_empty() {
+        fallback.to_string()
+    } else {
+        normalized
+    }
+}
+
+fn collapse_dashes(value: &str) -> String {
+    value
+        .chars()
+        .fold(
+            (String::new(), false),
+            |(mut output, last_is_dash), character| {
+                let is_dash = character == '-';
+                if is_dash && last_is_dash {
+                    return (output, true);
+                }
+                output.push(character);
+                (output, is_dash)
+            },
+        )
+        .0
+        .trim_matches('-')
+        .to_string()
+}
+
+fn parse_size(size: &str) -> (u32, u32) {
+    let mut parts = size.split('*');
+    let width = parts
+        .next()
+        .and_then(|value| value.trim().parse::<u32>().ok())
+        .filter(|value| *value > 0)
+        .unwrap_or(1024);
+    let height = parts
+        .next()
+        .and_then(|value| value.trim().parse::<u32>().ok())
+        .filter(|value| *value > 0)
+        .unwrap_or(1024);
+    (width, height)
+}
+
+fn escape_svg_text(value: &str) -> String {
+    value
+        .replace('&', "&amp;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+}
+
+fn format_utc_micros(micros: i64) -> String {
+    module_runtime::format_utc_micros(micros)
+}
+
+fn current_utc_millis() -> i64 {
+    current_utc_micros() / 1_000
+}
+
+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")
+}
+
+fn map_ai_task_error(error: AiTaskServiceError) -> AppError {
+    let status = match error {
+        AiTaskServiceError::TaskNotFound => StatusCode::NOT_FOUND,
+        AiTaskServiceError::TaskAlreadyExists => StatusCode::CONFLICT,
+        AiTaskServiceError::Field(_) | AiTaskServiceError::StageNotFound => StatusCode::BAD_REQUEST,
+        AiTaskServiceError::Store(_) => StatusCode::INTERNAL_SERVER_ERROR,
+    };
+    AppError::from_status(status).with_details(json!({
+        "provider": "ai-task",
+        "message": error.to_string(),
+    }))
+}
+
+fn map_asset_object_prepare_error(error: AssetObjectFieldError) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "asset-object",
+        "message": error.to_string(),
+    }))
+}
+
+fn map_asset_binding_prepare_error(error: AssetObjectFieldError) -> AppError {
+    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+        "provider": "asset-entity-binding",
+        "message": error.to_string(),
+    }))
+}
+
+fn map_character_visual_spacetime_error(error: SpacetimeClientError) -> AppError {
+    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+        "provider": "spacetimedb",
+        "message": error.to_string(),
+    }))
+}
+
+fn map_character_visual_oss_error(error: platform_oss::OssError) -> AppError {
+    let status = match error {
+        platform_oss::OssError::InvalidConfig(_) | platform_oss::OssError::InvalidRequest(_) => {
+            StatusCode::BAD_REQUEST
+        }
+        platform_oss::OssError::ObjectNotFound(_) => StatusCode::NOT_FOUND,
+        platform_oss::OssError::Request(_)
+        | platform_oss::OssError::SerializePolicy(_)
+        | platform_oss::OssError::Sign(_) => StatusCode::BAD_GATEWAY,
+    };
+    AppError::from_status(status).with_details(json!({
+        "provider": "aliyun-oss",
+        "message": error.to_string(),
+    }))
+}
+
+fn character_visual_error_response(request_context: &RequestContext, error: AppError) -> Response {
+    error.into_response_with_context(Some(request_context))
+}
+
+trait EmptyFallback {
+    fn if_empty_then(self, fallback: &str) -> String;
+}
+
+impl EmptyFallback for String {
+    fn if_empty_then(self, fallback: &str) -> String {
+        if self.is_empty() {
+            fallback.to_string()
+        } else {
+            self
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_character_visual_prompt_keeps_generation_constraints() {
+        let prompt = build_character_visual_prompt("潮雾港向导", Some("旧港守望者"));
+
+        assert!(prompt.contains("潮雾港向导"));
+        assert!(prompt.contains("右向斜侧身"));
+        assert!(prompt.contains("纯绿色背景"));
+    }
+
+    #[test]
+    fn sanitize_storage_segment_keeps_legacy_safe_shape() {
+        assert_eq!(
+            sanitize_storage_segment("Harbor Guide/潮雾", "character"),
+            "harbor-guide"
+        );
+    }
+}

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

@@ -56,6 +56,10 @@ pub struct AppConfig {
     pub llm_request_timeout_ms: u64,
     pub llm_max_retries: u32,
     pub llm_retry_backoff_ms: u64,
+    pub dashscope_base_url: String,
+    pub dashscope_api_key: Option<String>,
+    pub dashscope_image_request_timeout_ms: u64,
+    pub slow_request_threshold_ms: u64,
 }
 
 impl Default for AppConfig {
@@ -107,6 +111,10 @@ impl Default for AppConfig {
             llm_request_timeout_ms: DEFAULT_REQUEST_TIMEOUT_MS,
             llm_max_retries: DEFAULT_MAX_RETRIES,
             llm_retry_backoff_ms: DEFAULT_RETRY_BACKOFF_MS,
+            dashscope_base_url: "https://dashscope.aliyuncs.com/api/v1".to_string(),
+            dashscope_api_key: None,
+            dashscope_image_request_timeout_ms: 150_000,
+            slow_request_threshold_ms: 1_000,
         }
     }
 }
@@ -311,6 +319,24 @@ impl AppConfig {
             config.llm_retry_backoff_ms = llm_retry_backoff_ms;
         }
 
+        if let Some(dashscope_base_url) = read_first_non_empty_env(&["DASHSCOPE_BASE_URL"]) {
+            config.dashscope_base_url = dashscope_base_url;
+        }
+
+        config.dashscope_api_key = read_first_non_empty_env(&["DASHSCOPE_API_KEY"]);
+
+        if let Some(dashscope_image_request_timeout_ms) =
+            read_first_positive_u64_env(&["DASHSCOPE_IMAGE_REQUEST_TIMEOUT_MS"])
+        {
+            config.dashscope_image_request_timeout_ms = dashscope_image_request_timeout_ms;
+        }
+
+        if let Some(slow_request_threshold_ms) =
+            read_first_positive_u64_env(&["GENARRATIVE_SLOW_REQUEST_THRESHOLD_MS"])
+        {
+            config.slow_request_threshold_ms = slow_request_threshold_ms;
+        }
+
         config
     }
 

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

@@ -1,8 +1,11 @@
 use axum::{
     Json,
     extract::{Extension, Path, State, rejection::JsonRejection},
-    http::{HeaderName, StatusCode, header},
-    response::{IntoResponse, Response},
+    http::StatusCode,
+    response::{
+        IntoResponse, Response,
+        sse::{Event, Sse},
+    },
 };
 use module_custom_world::{
     CustomWorldThemeMode, empty_agent_anchor_content_json, empty_agent_asset_coverage_json,
@@ -10,31 +13,31 @@ use module_custom_world::{
 };
 use serde_json::{Map, Value, json};
 use shared_contracts::runtime::{
-    CreateCustomWorldAgentSessionRequest, CustomWorldAgentCheckpointResponse,
-    CustomWorldAgentCardDetailResponse,
-    CustomWorldAgentMessageResponse, CustomWorldAgentOperationResponse,
-    CustomWorldAgentSessionResponse, CustomWorldAgentSessionSnapshotResponse,
-    CustomWorldDraftCardDetailResponse, CustomWorldDraftCardDetailSectionResponse,
-    CustomWorldDraftCardSummaryResponse, CustomWorldGalleryCardResponse,
-    CustomWorldGalleryDetailResponse, CustomWorldGalleryResponse, CustomWorldLibraryEntryResponse,
-    CustomWorldLibraryMutationResponse, CustomWorldLibraryResponse,
-    CustomWorldProfileUpsertRequest, CustomWorldSupportedActionResponse,
-    CustomWorldPublishGateResponse, CustomWorldResultPreviewBlockerResponse,
-    CustomWorldWorkSummaryResponse, CustomWorldWorksResponse,
-    ExecuteCustomWorldAgentActionRequest, SendCustomWorldAgentMessageRequest,
+    CreateCustomWorldAgentSessionRequest, CustomWorldAgentCardDetailResponse,
+    CustomWorldAgentCheckpointResponse, CustomWorldAgentMessageResponse,
+    CustomWorldAgentOperationResponse, CustomWorldAgentSessionResponse,
+    CustomWorldAgentSessionSnapshotResponse, CustomWorldDraftCardDetailResponse,
+    CustomWorldDraftCardDetailSectionResponse, CustomWorldDraftCardSummaryResponse,
+    CustomWorldGalleryCardResponse, CustomWorldGalleryDetailResponse, CustomWorldGalleryResponse,
+    CustomWorldLibraryEntryResponse, CustomWorldLibraryMutationResponse,
+    CustomWorldLibraryResponse, CustomWorldProfileUpsertRequest, CustomWorldPublishGateResponse,
+    CustomWorldResultPreviewBlockerResponse, CustomWorldSupportedActionResponse,
+    CustomWorldWorkSummaryResponse, CustomWorldWorksResponse, ExecuteCustomWorldAgentActionRequest,
+    SendCustomWorldAgentMessageRequest,
 };
 use shared_kernel::build_prefixed_uuid_id;
 use spacetime_client::{
-    CustomWorldAgentActionExecuteRecordInput,
-    CustomWorldAgentCheckpointRecord, CustomWorldAgentMessageRecord,
-    CustomWorldAgentMessageSubmitRecordInput, CustomWorldAgentOperationRecord,
-    CustomWorldAgentSessionCreateRecordInput, CustomWorldAgentSessionRecord,
-    CustomWorldDraftCardDetailRecord, CustomWorldDraftCardDetailSectionRecord,
-    CustomWorldDraftCardRecord, CustomWorldGalleryEntryRecord, CustomWorldLibraryEntryRecord,
+    CustomWorldAgentActionExecuteRecordInput, CustomWorldAgentCheckpointRecord,
+    CustomWorldAgentMessageRecord, CustomWorldAgentMessageSubmitRecordInput,
+    CustomWorldAgentOperationRecord, CustomWorldAgentSessionCreateRecordInput,
+    CustomWorldAgentSessionRecord, CustomWorldDraftCardDetailRecord,
+    CustomWorldDraftCardDetailSectionRecord, CustomWorldDraftCardRecord,
+    CustomWorldGalleryEntryRecord, CustomWorldLibraryEntryRecord,
     CustomWorldProfileUpsertRecordInput, CustomWorldPublishGateRecord,
-    CustomWorldResultPreviewBlockerRecord, CustomWorldWorkSummaryRecord,
-    CustomWorldSupportedActionRecord, SpacetimeClientError,
+    CustomWorldResultPreviewBlockerRecord, CustomWorldSupportedActionRecord,
+    CustomWorldWorkSummaryRecord, SpacetimeClientError,
 };
+use std::convert::Infallible;
 
 use crate::{
     api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
@@ -84,10 +87,7 @@ pub async fn get_custom_world_library_detail(
 
     let detail = state
         .spacetime_client()
-        .get_custom_world_library_detail(
-            authenticated.claims().user_id().to_string(),
-            profile_id,
-        )
+        .get_custom_world_library_detail(authenticated.claims().user_id().to_string(), profile_id)
         .await
         .map_err(|error| {
             custom_world_error_response(&request_context, map_custom_world_client_error(error))
@@ -580,21 +580,23 @@ pub async fn stream_custom_world_agent_message(
     let session_response = map_custom_world_agent_session_response(session);
     let reply_text = resolve_stream_reply_text(&session_response);
 
-    // 这里先用“一次性构造完整 SSE 文本”的最小兼容方案，
-    // 复用 Stage 7 的同步 deterministic 写表逻辑，保证前端当前的 reader 协议可直接消费。
-    let mut sse_body = String::new();
-    append_sse_event(&mut sse_body, "reply_delta", &json!({ "text": reply_text }))
-        .map_err(|error| custom_world_error_response(&request_context, error))?;
-    append_sse_event(
-        &mut sse_body,
-        "session",
-        &json!({ "session": session_response }),
-    )
-    .map_err(|error| custom_world_error_response(&request_context, error))?;
-    append_sse_event(&mut sse_body, "done", &json!({ "ok": true }))
-        .map_err(|error| custom_world_error_response(&request_context, error))?;
+    // 这里仍保持“一次性返回完整事件序列”的兼容语义；
+    // SSE 编码、标准响应头与 body frame 交给 Axum 内建实现维护。
+    let events = vec![
+        custom_world_sse_json_event("reply_delta", json!({ "text": reply_text }))
+            .map_err(|error| custom_world_error_response(&request_context, error))?,
+        custom_world_sse_json_event("session", json!({ "session": session_response }))
+            .map_err(|error| custom_world_error_response(&request_context, error))?,
+        custom_world_sse_json_event("done", json!({ "ok": true }))
+            .map_err(|error| custom_world_error_response(&request_context, error))?,
+    ];
+    let stream = tokio_stream::iter(
+        events
+            .into_iter()
+            .map(|event| Ok::<Event, Infallible>(event)),
+    );
 
-    Ok(build_event_stream_response(sse_body))
+    Ok(Sse::new(stream).into_response())
 }
 
 pub async fn get_custom_world_agent_operation(
@@ -815,7 +817,9 @@ fn map_custom_world_agent_session_response(
             .into_iter()
             .map(map_custom_world_supported_action_response)
             .collect(),
-        publish_gate: session.publish_gate.map(map_custom_world_publish_gate_response),
+        publish_gate: session
+            .publish_gate
+            .map(map_custom_world_publish_gate_response),
         result_preview: session.result_preview,
         updated_at: session.updated_at,
     }
@@ -958,40 +962,11 @@ fn resolve_stream_reply_text(session: &CustomWorldAgentSessionSnapshotResponse)
         .unwrap_or_default()
 }
 
-fn append_sse_event(body: &mut String, event: &str, payload: &Value) -> Result<(), AppError> {
-    let payload_text = serde_json::to_string(payload).map_err(|error| {
-        AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
-            "provider": "custom-world-agent",
-            "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"),
-            // 反向代理场景下显式关闭缓冲，避免 SSE 事件被聚合后才下发。
-            (HeaderName::from_static("x-accel-buffering"), "no"),
-        ],
-        body,
-    )
-        .into_response()
-}
-
 fn map_custom_world_client_error(error: SpacetimeClientError) -> AppError {
     let status = match &error {
-        SpacetimeClientError::Procedure(message) if message.contains("custom_world_profile 不存在") => {
+        SpacetimeClientError::Procedure(message)
+            if message.contains("custom_world_profile 不存在") =>
+        {
             StatusCode::NOT_FOUND
         }
         SpacetimeClientError::Procedure(message)
@@ -1018,6 +993,18 @@ fn custom_world_error_response(request_context: &RequestContext, error: AppError
     error.into_response_with_context(Some(request_context))
 }
 
+fn custom_world_sse_json_event(event_name: &str, payload: Value) -> Result<Event, AppError> {
+    Event::default()
+        .event(event_name)
+        .json_data(payload)
+        .map_err(|error| {
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+                "provider": "sse",
+                "message": format!("SSE payload 序列化失败：{error}"),
+            }))
+        })
+}
+
 fn resolve_author_display_name(_authenticated: &AuthenticatedAccessToken) -> String {
     "玩家".to_string()
 }

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

@@ -0,0 +1,209 @@
+use axum::{
+    body::Body,
+    extract::{Path, State},
+    http::{HeaderName, HeaderValue, StatusCode, header},
+    response::{IntoResponse, Response},
+};
+use platform_oss::{LegacyAssetPrefix, OssSignedGetObjectUrlRequest};
+use serde_json::json;
+
+use crate::{http_error::AppError, state::AppState};
+
+const CACHE_CONTROL_VALUE: &str = "private, max-age=60";
+const ASSET_OBJECT_KEY_HEADER: &str = "x-genarrative-asset-object-key";
+
+pub async fn proxy_generated_character_drafts(
+    State(state): State<AppState>,
+    Path(path): Path<String>,
+) -> Response {
+    proxy_legacy_generated_asset(state, LegacyAssetPrefix::CharacterDrafts, path).await
+}
+
+pub async fn proxy_generated_characters(
+    State(state): State<AppState>,
+    Path(path): Path<String>,
+) -> Response {
+    proxy_legacy_generated_asset(state, LegacyAssetPrefix::Characters, path).await
+}
+
+pub async fn proxy_generated_animations(
+    State(state): State<AppState>,
+    Path(path): Path<String>,
+) -> Response {
+    proxy_legacy_generated_asset(state, LegacyAssetPrefix::Animations, path).await
+}
+
+pub async fn proxy_generated_custom_world_scenes(
+    State(state): State<AppState>,
+    Path(path): Path<String>,
+) -> Response {
+    proxy_legacy_generated_asset(state, LegacyAssetPrefix::CustomWorldScenes, path).await
+}
+
+pub async fn proxy_generated_custom_world_covers(
+    State(state): State<AppState>,
+    Path(path): Path<String>,
+) -> Response {
+    proxy_legacy_generated_asset(state, LegacyAssetPrefix::CustomWorldCovers, path).await
+}
+
+pub async fn proxy_generated_qwen_sprites(
+    State(state): State<AppState>,
+    Path(path): Path<String>,
+) -> Response {
+    proxy_legacy_generated_asset(state, LegacyAssetPrefix::QwenSprites, path).await
+}
+
+async fn proxy_legacy_generated_asset(
+    state: AppState,
+    prefix: LegacyAssetPrefix,
+    path: String,
+) -> Response {
+    match read_legacy_generated_asset(&state, prefix, path).await {
+        Ok(response) => response,
+        Err(error) => error.into_response(),
+    }
+}
+
+async fn read_legacy_generated_asset(
+    state: &AppState,
+    prefix: LegacyAssetPrefix,
+    path: String,
+) -> Result<Response, AppError> {
+    let oss_client = state.oss_client().ok_or_else(|| {
+        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
+            "provider": "aliyun-oss",
+            "reason": "OSS 未完成环境变量配置",
+        }))
+    })?;
+    let object_key = build_generated_object_key(prefix, path.as_str())?;
+    let signed = oss_client
+        .sign_get_object_url(OssSignedGetObjectUrlRequest {
+            object_key: object_key.clone(),
+            expire_seconds: Some(60),
+        })
+        .map_err(map_legacy_generated_oss_error)?;
+    let upstream_response = reqwest::Client::new()
+        .get(signed.signed_url)
+        .send()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取 OSS 旧 generated 资源失败：{error}"),
+            }))
+        })?;
+
+    if upstream_response.status() == reqwest::StatusCode::NOT_FOUND {
+        return Err(
+            AppError::from_status(StatusCode::NOT_FOUND).with_details(json!({
+                "provider": "aliyun-oss",
+                "objectKey": object_key,
+            })),
+        );
+    }
+
+    let status = upstream_response.status();
+    let content_type = upstream_response
+        .headers()
+        .get(header::CONTENT_TYPE)
+        .cloned();
+    let bytes = upstream_response
+        .error_for_status()
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取 OSS 旧 generated 资源失败：{error}"),
+            }))
+        })?
+        .bytes()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": "aliyun-oss",
+                "message": format!("读取 OSS 旧 generated 资源内容失败：{error}"),
+            }))
+        })?;
+    let mut response = Response::builder()
+        .status(status)
+        .header(header::CACHE_CONTROL, CACHE_CONTROL_VALUE)
+        .header(
+            HeaderName::from_static(ASSET_OBJECT_KEY_HEADER),
+            HeaderValue::from_str(object_key.as_str()).map_err(|error| {
+                AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+                    "provider": "legacy-generated-assets",
+                    "message": format!("构造资源响应头失败：{error}"),
+                }))
+            })?,
+        );
+    if let Some(content_type) = content_type {
+        response = response.header(header::CONTENT_TYPE, content_type);
+    }
+
+    response.body(Body::from(bytes)).map_err(|error| {
+        AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+            "provider": "legacy-generated-assets",
+            "message": format!("构造资源响应失败：{error}"),
+        }))
+    })
+}
+
+fn build_generated_object_key(prefix: LegacyAssetPrefix, path: &str) -> Result<String, AppError> {
+    let path = path.trim().trim_matches('/');
+    if path.is_empty() || path.split('/').any(is_invalid_path_segment) {
+        return Err(
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "legacy-generated-assets",
+                "message": "generated 资源路径不合法。",
+            })),
+        );
+    }
+
+    Ok(format!("{}/{}", prefix.as_str(), path))
+}
+
+fn is_invalid_path_segment(segment: &str) -> bool {
+    segment.is_empty() || segment == "." || segment == ".." || segment.contains('\\')
+}
+
+fn map_legacy_generated_oss_error(error: platform_oss::OssError) -> AppError {
+    let status = match error {
+        platform_oss::OssError::InvalidConfig(_) | platform_oss::OssError::InvalidRequest(_) => {
+            StatusCode::BAD_REQUEST
+        }
+        platform_oss::OssError::ObjectNotFound(_) => StatusCode::NOT_FOUND,
+        platform_oss::OssError::Request(_)
+        | platform_oss::OssError::SerializePolicy(_)
+        | platform_oss::OssError::Sign(_) => StatusCode::BAD_GATEWAY,
+    };
+    AppError::from_status(status).with_details(json!({
+        "provider": "aliyun-oss",
+        "message": error.to_string(),
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_generated_object_key_keeps_supported_prefix() {
+        let object_key = build_generated_object_key(
+            LegacyAssetPrefix::Animations,
+            "hero/animation-set-1/idle/frame01.png",
+        )
+        .expect("object key should build");
+
+        assert_eq!(
+            object_key,
+            "generated-animations/hero/animation-set-1/idle/frame01.png"
+        );
+    }
+
+    #[test]
+    fn build_generated_object_key_rejects_parent_segment() {
+        assert!(
+            build_generated_object_key(LegacyAssetPrefix::Characters, "../secret.png").is_err()
+        );
+    }
+}

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

@@ -7,12 +7,15 @@ mod auth_me;
 mod auth_session;
 mod auth_sessions;
 mod big_fish;
+mod character_animation_assets;
+mod character_visual_assets;
 mod config;
 mod custom_world;
 mod custom_world_ai;
 mod error_middleware;
 mod health;
 mod http_error;
+mod legacy_generated_assets;
 mod llm;
 mod login_options;
 mod logout;

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

@@ -32,10 +32,11 @@ pub async fn get_runtime_snapshot(
 ) -> Result<Json<Value>, Response> {
     let user_id = authenticated.claims().user_id().to_string();
     let record = state
-        .spacetime_client()
-        .get_runtime_snapshot(user_id)
+        .get_runtime_snapshot_record(user_id)
         .await
-        .map_err(|error| runtime_save_error_response(&request_context, map_runtime_save_client_error(error)))?;
+        .map_err(|error| {
+            runtime_save_error_response(&request_context, map_runtime_save_client_error(error))
+        })?;
 
     Ok(json_success_body(
         Some(&request_context),
@@ -70,8 +71,7 @@ pub async fn put_runtime_snapshot(
     let saved_at_micros = offset_datetime_to_unix_micros(saved_at);
 
     let record = state
-        .spacetime_client()
-        .put_runtime_snapshot(
+        .put_runtime_snapshot_record(
             user_id,
             saved_at_micros,
             payload.bottom_tab,
@@ -80,7 +80,9 @@ pub async fn put_runtime_snapshot(
             updated_at_micros,
         )
         .await
-        .map_err(|error| runtime_save_error_response(&request_context, map_runtime_save_client_error(error)))?;
+        .map_err(|error| {
+            runtime_save_error_response(&request_context, map_runtime_save_client_error(error))
+        })?;
 
     Ok(json_success_body(
         Some(&request_context),
@@ -95,10 +97,11 @@ pub async fn delete_runtime_snapshot(
 ) -> Result<Json<Value>, Response> {
     let user_id = authenticated.claims().user_id().to_string();
     state
-        .spacetime_client()
-        .delete_runtime_snapshot(user_id)
+        .delete_runtime_snapshot_record(user_id)
         .await
-        .map_err(|error| runtime_save_error_response(&request_context, map_runtime_save_client_error(error)))?;
+        .map_err(|error| {
+            runtime_save_error_response(&request_context, map_runtime_save_client_error(error))
+        })?;
 
     Ok(json_success_body(
         Some(&request_context),
@@ -116,7 +119,9 @@ pub async fn list_profile_save_archives(
         .spacetime_client()
         .list_profile_save_archives(user_id)
         .await
-        .map_err(|error| runtime_save_error_response(&request_context, map_runtime_save_client_error(error)))?;
+        .map_err(|error| {
+            runtime_save_error_response(&request_context, map_runtime_save_client_error(error))
+        })?;
 
     Ok(json_success_body(
         Some(&request_context),
@@ -151,7 +156,12 @@ pub async fn resume_profile_save_archive(
         .spacetime_client()
         .resume_profile_save_archive(user_id, world_key)
         .await
-        .map_err(|error| runtime_save_error_response(&request_context, map_runtime_save_resume_client_error(error)))?;
+        .map_err(|error| {
+            runtime_save_error_response(
+                &request_context,
+                map_runtime_save_resume_client_error(error),
+            )
+        })?;
 
     Ok(json_success_body(
         Some(&request_context),
@@ -205,7 +215,8 @@ fn map_runtime_save_client_error(error: SpacetimeClientError) -> AppError {
 fn map_runtime_save_resume_client_error(error: SpacetimeClientError) -> AppError {
     let (status, provider) = match &error {
         SpacetimeClientError::Procedure(message)
-            if message.contains("world_key 不存在") || message.contains("对应 world_key 不存在") =>
+            if message.contains("world_key 不存在")
+                || message.contains("对应 world_key 不存在") =>
         {
             (StatusCode::NOT_FOUND, "runtime-save")
         }

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

@@ -1,733 +1,6 @@
-use axum::{
-    Json,
-    extract::{Extension, Path, State, rejection::JsonRejection},
-    http::StatusCode,
-    response::Response,
+mod compat;
+
+pub use compat::{
+    generate_runtime_story_continue, generate_runtime_story_initial, get_runtime_story_state,
+    resolve_runtime_story_action, resolve_runtime_story_state,
 };
-use serde_json::{Value, json};
-use shared_contracts::runtime_story::{
-    RuntimeStoryActionResponse, RuntimeStoryCompanionViewModel, RuntimeStoryEncounterViewModel,
-    RuntimeStoryOptionInteraction, RuntimeStoryOptionView, RuntimeStoryPlayerViewModel,
-    RuntimeStoryPresentation, RuntimeStorySnapshotPayload, RuntimeStoryStateResolveRequest,
-    RuntimeStoryStatusViewModel, RuntimeStoryViewModel,
-};
-
-use crate::{
-    api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
-    request_context::RequestContext, state::AppState,
-};
-
-pub async fn resolve_runtime_story_state(
-    State(_state): State<AppState>,
-    Extension(request_context): Extension<RequestContext>,
-    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
-    Json(payload): Json<RuntimeStoryStateResolveRequest>,
-) -> Result<Json<Value>, Response> {
-    let session_id = normalize_required_string(payload.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 不能为空",
-            })),
-        )
-    })?;
-    let snapshot = payload.snapshot.ok_or_else(|| {
-        runtime_story_error_response(
-            &request_context,
-            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
-                "provider": "runtime-story",
-                "field": "snapshot",
-                "message": "当前首版兼容状态桥要求随请求提交 snapshot",
-            })),
-        )
-    })?;
-
-    Ok(json_success_body(
-        Some(&request_context),
-        build_runtime_story_state_response(
-            &session_id,
-            payload.client_version,
-            snapshot,
-        ),
-    ))
-}
-
-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>,
-    snapshot: RuntimeStorySnapshotPayload,
-) -> RuntimeStoryActionResponse {
-    let session_id = read_runtime_session_id(&snapshot.game_state)
-        .unwrap_or_else(|| requested_session_id.to_string());
-    let options = build_runtime_story_options(snapshot.current_story.as_ref(), &snapshot.game_state);
-    let story_text =
-        read_story_text(snapshot.current_story.as_ref()).unwrap_or_else(|| build_fallback_story_text(&snapshot.game_state));
-    let server_version =
-        read_u32_field(&snapshot.game_state, "runtimeActionVersion").or(client_version).unwrap_or(0);
-
-    RuntimeStoryActionResponse {
-        session_id,
-        server_version,
-        view_model: RuntimeStoryViewModel {
-            player: RuntimeStoryPlayerViewModel {
-                hp: read_i32_field(&snapshot.game_state, "playerHp").unwrap_or(0),
-                max_hp: read_i32_field(&snapshot.game_state, "playerMaxHp").unwrap_or(1),
-                mana: read_i32_field(&snapshot.game_state, "playerMana").unwrap_or(0),
-                max_mana: read_i32_field(&snapshot.game_state, "playerMaxMana").unwrap_or(1),
-            },
-            encounter: build_runtime_story_encounter(&snapshot.game_state),
-            companions: build_runtime_story_companions(&snapshot.game_state),
-            available_options: options.clone(),
-            status: RuntimeStoryStatusViewModel {
-                in_battle: read_bool_field(&snapshot.game_state, "inBattle").unwrap_or(false),
-                npc_interaction_active: read_bool_field(&snapshot.game_state, "npcInteractionActive")
-                    .unwrap_or(false),
-                current_npc_battle_mode: read_optional_string_field(
-                    &snapshot.game_state,
-                    "currentNpcBattleMode",
-                ),
-                current_npc_battle_outcome: read_optional_string_field(
-                    &snapshot.game_state,
-                    "currentNpcBattleOutcome",
-                ),
-            },
-        },
-        presentation: RuntimeStoryPresentation {
-            action_text: String::new(),
-            result_text: String::new(),
-            story_text,
-            options,
-            toast: None,
-            battle: None,
-        },
-        patches: Vec::new(),
-        snapshot,
-    }
-}
-
-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()
-        .filter_map(|entry| {
-            let npc_id = read_required_string_field(entry, "npcId")?;
-            Some(RuntimeStoryCompanionViewModel {
-                npc_id,
-                character_id: read_optional_string_field(entry, "characterId"),
-                joined_at_affinity: read_i32_field(entry, "joinedAtAffinity").unwrap_or(0),
-            })
-        })
-        .collect()
-}
-
-fn build_runtime_story_encounter(game_state: &Value) -> Option<RuntimeStoryEncounterViewModel> {
-    let encounter = read_object_field(game_state, "currentEncounter")?;
-    let npc_name = read_required_string_field(encounter, "npcName")?;
-    let encounter_id = read_required_string_field(encounter, "id").unwrap_or_else(|| npc_name.clone());
-    let npc_state = resolve_current_encounter_npc_state(game_state, &encounter_id, &npc_name);
-
-    Some(RuntimeStoryEncounterViewModel {
-        id: encounter_id,
-        kind: read_required_string_field(encounter, "kind").unwrap_or_else(|| "npc".to_string()),
-        npc_name,
-        hostile: read_bool_field(encounter, "hostile").unwrap_or(false),
-        affinity: npc_state.and_then(|state| read_i32_field(state, "affinity")),
-        recruited: npc_state.and_then(|state| read_bool_field(state, "recruited")),
-        interaction_active: read_bool_field(game_state, "npcInteractionActive").unwrap_or(false),
-        battle_mode: read_optional_string_field(game_state, "currentNpcBattleMode"),
-    })
-}
-
-fn resolve_current_encounter_npc_state<'a>(
-    game_state: &'a Value,
-    encounter_id: &str,
-    npc_name: &str,
-) -> Option<&'a Value> {
-    let npc_states = read_object_field(game_state, "npcStates")?;
-
-    npc_states
-        .get(encounter_id)
-        .or_else(|| npc_states.get(npc_name))
-}
-
-fn build_runtime_story_options(
-    current_story: Option<&Value>,
-    game_state: &Value,
-) -> Vec<RuntimeStoryOptionView> {
-    if let Some(story) = current_story {
-        let prefers_deferred = read_required_string_field(story, "displayMode")
-            .is_some_and(|value| value == "dialogue")
-            && !read_array_field(story, "deferredOptions").is_empty();
-
-        let source = if prefers_deferred {
-            read_array_field(story, "deferredOptions")
-        } else {
-            read_array_field(story, "options")
-        };
-
-        let compiled = source
-            .into_iter()
-            .filter_map(build_runtime_story_option_from_story_option)
-            .collect::<Vec<_>>();
-
-        if !compiled.is_empty() {
-            return compiled;
-        }
-    }
-
-    build_fallback_runtime_story_options(game_state)
-}
-
-fn build_runtime_story_option_from_story_option(value: &Value) -> Option<RuntimeStoryOptionView> {
-    let function_id = read_required_string_field(value, "functionId")?;
-    let action_text = read_required_string_field(value, "actionText")
-        .or_else(|| read_required_string_field(value, "text"))
-        .unwrap_or_else(|| function_id.clone());
-
-    Some(RuntimeStoryOptionView {
-        scope: infer_option_scope(function_id.as_str()).to_string(),
-        detail_text: read_optional_string_field(value, "detailText"),
-        interaction: build_runtime_story_option_interaction(read_field(value, "interaction")),
-        payload: read_field(value, "runtimePayload").cloned(),
-        disabled: read_bool_field(value, "disabled"),
-        reason: read_optional_string_field(value, "disabledReason")
-            .or_else(|| read_optional_string_field(value, "reason")),
-        function_id,
-        action_text,
-    })
-}
-
-fn build_runtime_story_option_interaction(
-    value: Option<&Value>,
-) -> Option<RuntimeStoryOptionInteraction> {
-    let interaction = value?;
-    match read_required_string_field(interaction, "kind")?.as_str() {
-        "npc" => Some(RuntimeStoryOptionInteraction::Npc {
-            npc_id: read_required_string_field(interaction, "npcId")?,
-            action: read_required_string_field(interaction, "action")?,
-            quest_id: read_optional_string_field(interaction, "questId"),
-        }),
-        "treasure" => Some(RuntimeStoryOptionInteraction::Treasure {
-            action: read_required_string_field(interaction, "action")?,
-        }),
-        _ => None,
-    }
-}
-
-fn build_fallback_runtime_story_options(game_state: &Value) -> Vec<RuntimeStoryOptionView> {
-    if read_bool_field(game_state, "inBattle").unwrap_or(false) {
-        return vec![
-            build_static_runtime_story_option("battle_attack_basic", "普通攻击", "combat"),
-            build_static_runtime_story_option("battle_recover_breath", "恢复", "combat"),
-            build_static_runtime_story_option("battle_escape_breakout", "强行脱离战斗", "combat"),
-        ];
-    }
-
-    let encounter = read_object_field(game_state, "currentEncounter");
-    if let Some(encounter) = encounter {
-        match read_required_string_field(encounter, "kind").as_deref() {
-            Some("npc") => {
-                let interaction_active =
-                    read_bool_field(game_state, "npcInteractionActive").unwrap_or(false);
-                if interaction_active {
-                    return vec![
-                        build_static_runtime_story_option("npc_chat", "继续交谈", "npc"),
-                        build_static_runtime_story_option("npc_help", "请求援手", "npc"),
-                        build_static_runtime_story_option("npc_spar", "点到为止切磋", "npc"),
-                        build_static_runtime_story_option("npc_fight", "与对方战斗", "npc"),
-                        build_static_runtime_story_option("npc_leave", "离开当前角色", "npc"),
-                    ];
-                }
-
-                return vec![
-                    build_static_runtime_story_option("npc_preview_talk", "转向眼前角色", "npc"),
-                    build_static_runtime_story_option("npc_fight", "与对方战斗", "npc"),
-                    build_static_runtime_story_option("npc_leave", "离开当前角色", "npc"),
-                ];
-            }
-            Some("treasure") => {
-                return vec![
-                    build_static_runtime_story_option("treasure_secure", "直接收取", "story"),
-                    build_static_runtime_story_option("treasure_inspect", "仔细检查", "story"),
-                    build_static_runtime_story_option("treasure_leave", "先记下位置", "story"),
-                ];
-            }
-            _ => {}
-        }
-    }
-
-    vec![
-        build_static_runtime_story_option("idle_observe_signs", "观察周围迹象", "story"),
-        build_static_runtime_story_option("idle_call_out", "主动出声试探", "story"),
-        build_static_runtime_story_option("idle_rest_focus", "原地调息", "story"),
-        build_static_runtime_story_option("idle_explore_forward", "继续向前探索", "story"),
-        build_static_runtime_story_option("idle_travel_next_scene", "前往相邻场景", "story"),
-        build_static_runtime_story_option("story_continue_adventure", "继续推进冒险", "story"),
-    ]
-}
-
-fn build_static_runtime_story_option(
-    function_id: &str,
-    action_text: &str,
-    scope: &str,
-) -> RuntimeStoryOptionView {
-    RuntimeStoryOptionView {
-        function_id: function_id.to_string(),
-        action_text: action_text.to_string(),
-        detail_text: None,
-        scope: scope.to_string(),
-        interaction: None,
-        payload: None,
-        disabled: None,
-        reason: None,
-    }
-}
-
-fn infer_option_scope(function_id: &str) -> &'static str {
-    if function_id.starts_with("battle_") || function_id == "inventory_use" {
-        "combat"
-    } else if function_id.starts_with("npc_") {
-        "npc"
-    } else {
-        "story"
-    }
-}
-
-fn read_story_text(current_story: Option<&Value>) -> Option<String> {
-    current_story.and_then(|story| read_optional_string_field(story, "text"))
-}
-
-fn build_fallback_story_text(game_state: &Value) -> String {
-    if read_bool_field(game_state, "inBattle").unwrap_or(false) {
-        let encounter_name = read_object_field(game_state, "currentEncounter")
-            .and_then(|encounter| read_optional_string_field(encounter, "npcName"))
-            .unwrap_or_else(|| "眼前的敌人".to_string());
-        return format!("战斗还没有结束，{encounter_name} 仍在逼你立刻做出下一步判断。");
-    }
-
-    if let Some(encounter) = read_object_field(game_state, "currentEncounter")
-        && let Some(npc_name) = read_optional_string_field(encounter, "npcName")
-    {
-        return format!("{npc_name} 正在等你表态，当前局势已经可以继续推进。");
-    }
-
-    "当前故事状态已经同步到兼容状态桥，可以继续推进这一轮运行时动作。".to_string()
-}
-
-fn read_runtime_session_id(game_state: &Value) -> Option<String> {
-    read_optional_string_field(game_state, "runtimeSessionId")
-}
-
-fn read_field<'a>(value: &'a Value, key: &str) -> Option<&'a Value> {
-    value.as_object()?.get(key)
-}
-
-fn read_object_field<'a>(value: &'a Value, key: &str) -> Option<&'a Value> {
-    let field = read_field(value, key)?;
-    field.is_object().then_some(field)
-}
-
-fn read_array_field<'a>(value: &'a Value, key: &str) -> Vec<&'a Value> {
-    read_field(value, key)
-        .and_then(Value::as_array)
-        .map(|items| items.iter().collect())
-        .unwrap_or_default()
-}
-
-fn read_required_string_field(value: &Value, key: &str) -> Option<String> {
-    normalize_required_string(read_field(value, key)?.as_str()?)
-}
-
-fn read_optional_string_field(value: &Value, key: &str) -> Option<String> {
-    normalize_optional_string(read_field(value, key).and_then(Value::as_str))
-}
-
-fn read_bool_field(value: &Value, key: &str) -> Option<bool> {
-    read_field(value, key).and_then(Value::as_bool)
-}
-
-fn read_i32_field(value: &Value, key: &str) -> Option<i32> {
-    read_field(value, key)
-        .and_then(Value::as_i64)
-        .and_then(|number| i32::try_from(number).ok())
-}
-
-fn read_u32_field(value: &Value, key: &str) -> Option<u32> {
-    read_field(value, key)
-        .and_then(Value::as_u64)
-        .and_then(|number| u32::try_from(number).ok())
-}
-
-fn normalize_required_string(value: &str) -> Option<String> {
-    let trimmed = value.trim();
-    (!trimmed.is_empty()).then(|| trimmed.to_string())
-}
-
-fn normalize_optional_string(value: Option<&str>) -> Option<String> {
-    value.and_then(normalize_required_string)
-}
-
-fn runtime_story_error_response(request_context: &RequestContext, error: AppError) -> Response {
-    error.into_response_with_context(Some(request_context))
-}
-
-#[cfg(test)]
-mod tests {
-    use axum::{
-        body::Body,
-        http::{Request, StatusCode},
-    };
-    use http_body_util::BodyExt;
-    use platform_auth::{
-        AccessTokenClaims, AccessTokenClaimsInput, AuthProvider, BindingStatus, sign_access_token,
-    };
-    use serde_json::{Value, json};
-    use time::OffsetDateTime;
-    use tower::ServiceExt;
-
-    use crate::{app::build_router, config::AppConfig, state::AppState};
-
-    #[tokio::test]
-    async fn runtime_story_state_resolve_requires_authentication() {
-        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
-
-        let response = app
-            .oneshot(
-                Request::builder()
-                    .method("POST")
-                    .uri("/api/runtime/story/state/resolve")
-                    .header("content-type", "application/json")
-                    .body(Body::from(
-                        json!({
-                            "sessionId": "runtime-main",
-                            "snapshot": {
-                                "savedAt": "2026-04-22T12:00:00.000Z",
-                                "bottomTab": "adventure",
-                                "gameState": {
-                                    "runtimeSessionId": "runtime-main"
-                                },
-                                "currentStory": null
-                            }
-                        })
-                        .to_string(),
-                    ))
-                    .expect("request should build"),
-            )
-            .await
-            .expect("request should succeed");
-
-        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
-    }
-
-    #[tokio::test]
-    async fn runtime_story_state_resolve_rejects_missing_snapshot() {
-        let state = seed_authenticated_state().await;
-        let token = issue_access_token(&state);
-        let app = build_router(state);
-
-        let response = app
-            .oneshot(
-                Request::builder()
-                    .method("POST")
-                    .uri("/api/runtime/story/state/resolve")
-                    .header("authorization", format!("Bearer {token}"))
-                    .header("content-type", "application/json")
-                    .header("x-genarrative-response-envelope", "v1")
-                    .body(Body::from(
-                        json!({
-                            "sessionId": "runtime-main"
-                        })
-                        .to_string(),
-                    ))
-                    .expect("request should build"),
-            )
-            .await
-            .expect("request should succeed");
-
-        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
-    }
-
-    #[tokio::test]
-    async fn runtime_story_state_resolve_returns_compiled_snapshot_response() {
-        let state = seed_authenticated_state().await;
-        let token = issue_access_token(&state);
-        let app = build_router(state);
-
-        let response = app
-            .oneshot(
-                Request::builder()
-                    .method("POST")
-                    .uri("/api/runtime/story/state/resolve")
-                    .header("authorization", format!("Bearer {token}"))
-                    .header("content-type", "application/json")
-                    .header("x-genarrative-response-envelope", "v1")
-                    .body(Body::from(
-                        json!({
-                            "sessionId": "runtime-main",
-                            "clientVersion": 7,
-                            "snapshot": {
-                                "savedAt": "2026-04-22T12:00:00.000Z",
-                                "bottomTab": "adventure",
-                                "gameState": {
-                                    "runtimeSessionId": "runtime-main",
-                                    "runtimeActionVersion": 7,
-                                    "playerHp": 32,
-                                    "playerMaxHp": 40,
-                                    "playerMana": 18,
-                                    "playerMaxMana": 20,
-                                    "inBattle": false,
-                                    "npcInteractionActive": true,
-                                    "currentEncounter": {
-                                        "id": "npc_camp_firekeeper",
-                                        "kind": "npc",
-                                        "npcName": "守火人",
-                                        "hostile": false
-                                    },
-                                    "npcStates": {
-                                        "npc_camp_firekeeper": {
-                                            "affinity": 12,
-                                            "recruited": false
-                                        }
-                                    },
-                                    "companions": [{
-                                        "npcId": "npc_companion_001",
-                                        "characterId": "char_companion_001",
-                                        "joinedAtAffinity": 64
-                                    }]
-                                },
-                                "currentStory": {
-                                    "text": "守火人抬眼看了你一瞬，示意你把想问的话继续说完。",
-                                    "displayMode": "dialogue",
-                                    "options": [{
-                                        "functionId": "story_continue_adventure",
-                                        "actionText": "继续冒险"
-                                    }],
-                                    "deferredOptions": [{
-                                        "functionId": "npc_chat",
-                                        "actionText": "继续交谈",
-                                        "detailText": "围绕当前话题继续推进关系判断。",
-                                        "interaction": {
-                                            "kind": "npc",
-                                            "npcId": "npc_camp_firekeeper",
-                                            "action": "chat"
-                                        },
-                                        "runtimePayload": {
-                                            "note": "server-runtime-test"
-                                        }
-                                    }]
-                                }
-                            }
-                        })
-                        .to_string(),
-                    ))
-                    .expect("request should build"),
-            )
-            .await
-            .expect("request should succeed");
-
-        assert_eq!(response.status(), StatusCode::OK);
-
-        let body = response
-            .into_body()
-            .collect()
-            .await
-            .expect("body should collect")
-            .to_bytes();
-        let payload: Value =
-            serde_json::from_slice(&body).expect("response body should be valid json");
-
-        assert_eq!(payload["ok"], Value::Bool(true));
-        assert_eq!(payload["data"]["sessionId"], json!("runtime-main"));
-        assert_eq!(payload["data"]["serverVersion"], json!(7));
-        assert_eq!(
-            payload["data"]["viewModel"]["encounter"]["npcName"],
-            json!("守火人")
-        );
-        assert_eq!(
-            payload["data"]["viewModel"]["availableOptions"][0]["functionId"],
-            json!("npc_chat")
-        );
-        assert_eq!(
-            payload["data"]["presentation"]["options"][0]["interaction"]["npcId"],
-            json!("npc_camp_firekeeper")
-        );
-        assert_eq!(
-            payload["data"]["snapshot"]["currentStory"]["deferredOptions"][0]["functionId"],
-            json!("npc_chat")
-        );
-    }
-
-    async fn seed_authenticated_state() -> AppState {
-        let state = AppState::new(AppConfig::default()).expect("state should build");
-        state
-            .password_entry_service()
-            .execute(module_auth::PasswordEntryInput {
-                username: "runtime_story_state_user".to_string(),
-                password: "secret123".to_string(),
-            })
-            .await
-            .expect("seed login should succeed");
-        state
-    }
-
-    fn issue_access_token(state: &AppState) -> String {
-        let claims = AccessTokenClaims::from_input(
-            AccessTokenClaimsInput {
-                user_id: "user_00000001".to_string(),
-                session_id: "sess_runtime_story_state".to_string(),
-                provider: AuthProvider::Password,
-                roles: vec!["user".to_string()],
-                token_version: 1,
-                phone_verified: true,
-                binding_status: BindingStatus::Active,
-                display_name: Some("运行时剧情状态用户".to_string()),
-            },
-            state.auth_jwt_config(),
-            OffsetDateTime::now_utc(),
-        )
-        .expect("claims should build");
-
-        sign_access_token(&claims, state.auth_jwt_config()).expect("token should sign")
-    }
-}

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

@@ -0,0 +1,635 @@
+use axum::{
+    Json,
+    extract::{Extension, Path, State},
+    http::StatusCode,
+    response::Response,
+};
+use module_npc::{
+    NpcRelationStance, build_initial_stance_profile as build_module_npc_initial_stance_profile,
+    build_relation_state as build_module_npc_relation_state,
+};
+use module_runtime::RuntimeSnapshotRecord;
+use module_runtime_story_compat::{
+    CONTINUE_ADVENTURE_FUNCTION_ID, CurrentEncounterNpcQuestContext, GeneratedStoryPayload,
+    PendingQuestOfferContext, RuntimeStoryActionResponseParts,
+    StoryResolution, add_player_currency, add_player_inventory_items,
+    append_story_history, apply_equipment_loadout_to_state,
+    battle_mode_text, build_battle_runtime_story_options, build_current_build_toast,
+    build_status_patch,
+    build_npc_gift_result_text,
+    build_runtime_story_view_model,
+    clear_encounter_only, clear_encounter_state, clone_inventory_item_with_quantity,
+    current_encounter_id, current_encounter_name, current_world_type,
+    ensure_inventory_action_available, ensure_json_object, equipment_slot_label,
+    find_player_inventory_entry,
+    format_now_rfc3339, grant_player_progression_experience, has_giftable_player_inventory,
+    format_currency_text,
+    increment_runtime_stat, normalize_equipped_item,
+    normalize_equipment_slot_id, normalize_required_string, npc_buyback_price,
+    npc_purchase_price, read_array_field, read_bool_field, read_field, read_i32_field,
+    read_inventory_item_name, read_object_field, read_optional_string_field,
+    read_player_equipment_item, read_required_string_field, read_runtime_session_id,
+    read_u32_field, recruit_companion_to_party, remove_player_inventory_item,
+    restore_player_resource,
+    resolve_action_text, resolve_battle_action, resolve_equipment_slot_for_item,
+    resolve_forge_craft_action,
+    resolve_forge_dismantle_action, resolve_forge_reforge_action,
+    resolve_npc_gift_affinity_gain, simple_story_resolution, trade_quantity_suffix,
+    resolve_current_encounter_npc_state,
+    build_disabled_runtime_story_option, build_runtime_story_option_from_story_option,
+    build_static_runtime_story_option, build_story_option_from_runtime_option,
+    write_bool_field, write_i32_field, write_null_field, write_player_equipment_item,
+    write_string_field, write_u32_field,
+};
+use platform_llm::{LlmClient, LlmMessage, LlmTextRequest};
+use serde_json::{Map, Value, json};
+use shared_contracts::runtime_story::{
+    RuntimeBattlePresentation, RuntimeStoryActionRequest, RuntimeStoryActionResponse,
+    RuntimeStoryAiRequest, RuntimeStoryAiResponse, RuntimeStoryOptionInteraction,
+    RuntimeStoryOptionView, RuntimeStoryPatch, RuntimeStoryPresentation,
+    RuntimeStorySnapshotPayload, RuntimeStoryStateResolveRequest,
+};
+use shared_kernel::{offset_datetime_to_unix_micros, parse_rfc3339};
+use spacetime_client::SpacetimeClientError;
+use time::OffsetDateTime;
+
+use crate::{
+    api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
+    request_context::RequestContext, state::AppState,
+};
+
+#[path = "compat/ai.rs"]
+mod ai;
+#[path = "compat/equipment_actions.rs"]
+mod equipment_actions;
+#[path = "compat/game_state.rs"]
+mod game_state;
+#[path = "compat/npc_actions.rs"]
+mod npc_actions;
+#[path = "compat/presentation.rs"]
+mod presentation;
+#[path = "compat/quest_actions.rs"]
+mod quest_actions;
+
+use self::{
+    ai::*, equipment_actions::*, game_state::*, npc_actions::*, presentation::*, quest_actions::*,
+};
+
+#[cfg(test)]
+#[path = "compat/tests.rs"]
+mod tests;
+
+pub async fn resolve_runtime_story_state(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<RuntimeStoryStateResolveRequest>,
+) -> Result<Json<Value>, Response> {
+    let session_id = normalize_required_string(payload.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 不能为空",
+            })),
+        )
+    })?;
+    let snapshot = resolve_snapshot_for_request(
+        &state,
+        &request_context,
+        authenticated.claims().user_id().to_string(),
+        payload.snapshot,
+    )
+    .await?;
+
+    validate_client_version(
+        &request_context,
+        payload.client_version,
+        &snapshot.game_state,
+        "运行时版本已变化，请先同步最新快照后再读取状态",
+    )?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_state_response(&session_id, payload.client_version, snapshot),
+    ))
+}
+
+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 不能为空",
+            })),
+        )
+    })?;
+    let snapshot = resolve_snapshot_for_request(
+        &state,
+        &request_context,
+        authenticated.claims().user_id().to_string(),
+        None,
+    )
+    .await?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_state_response(&session_id, None, snapshot),
+    ))
+}
+
+pub async fn resolve_runtime_story_action(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<RuntimeStoryActionRequest>,
+) -> Result<Json<Value>, Response> {
+    let requested_session_id =
+        normalize_required_string(payload.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 不能为空",
+                })),
+            )
+        })?;
+    let function_id =
+        normalize_required_string(payload.action.function_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": "action.functionId",
+                    "message": "functionId 不能为空",
+                })),
+            )
+        })?;
+    if payload.action.action_type.trim() != "story_choice" {
+        return Err(runtime_story_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "runtime-story",
+                "field": "action.type",
+                "message": "runtime story 当前只支持 story_choice 动作",
+            })),
+        ));
+    }
+
+    let mut snapshot = resolve_snapshot_for_request(
+        &state,
+        &request_context,
+        authenticated.claims().user_id().to_string(),
+        payload.snapshot.clone(),
+    )
+    .await?;
+    validate_client_version(
+        &request_context,
+        payload.client_version,
+        &snapshot.game_state,
+        "运行时版本已变化，请先同步最新快照后再提交动作",
+    )?;
+
+    let current_story_before = snapshot.current_story.clone();
+    let mut game_state = snapshot.game_state.clone();
+    let mut resolution = resolve_runtime_story_choice_action(
+        &mut game_state,
+        current_story_before.as_ref(),
+        &payload,
+        &function_id,
+    )
+    .map_err(|message| {
+        runtime_story_error_response(
+            &request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "runtime-story",
+                "message": message,
+            })),
+        )
+    })?;
+
+    let server_version = read_u32_field(&game_state, "runtimeActionVersion")
+        .unwrap_or(0)
+        .saturating_add(1);
+    write_u32_field(&mut game_state, "runtimeActionVersion", server_version);
+    write_string_field(
+        &mut game_state,
+        "runtimeSessionId",
+        requested_session_id.as_str(),
+    );
+
+    let mut options = resolution
+        .presentation_options
+        .take()
+        .unwrap_or_else(|| build_fallback_runtime_story_options(&game_state));
+    if options.is_empty() {
+        options = build_fallback_runtime_story_options(&game_state);
+    }
+
+    let mut story_text = resolution
+        .story_text
+        .clone()
+        .unwrap_or_else(|| resolution.result_text.clone());
+    let mut history_result_text = resolution.result_text.clone();
+    let mut saved_current_story = resolution
+        .saved_current_story
+        .take()
+        .unwrap_or_else(|| build_legacy_current_story(story_text.as_str(), &options));
+    if let Some(generated_payload) = generate_action_story_payload(
+        &state,
+        &game_state,
+        &payload,
+        &function_id,
+        resolution.action_text.as_str(),
+        resolution.result_text.as_str(),
+        &options,
+        resolution.battle.as_ref(),
+    )
+    .await
+    {
+        story_text = generated_payload.story_text;
+        history_result_text = generated_payload.history_result_text;
+        options = generated_payload.presentation_options;
+        saved_current_story = generated_payload.saved_current_story;
+    }
+    append_story_history(
+        &mut game_state,
+        resolution.action_text.as_str(),
+        history_result_text.as_str(),
+    );
+
+    let mut patches = vec![RuntimeStoryPatch::StoryHistoryAppend {
+        action_text: resolution.action_text.clone(),
+        result_text: history_result_text,
+    }];
+    patches.extend(resolution.patches);
+
+    snapshot.saved_at = Some(format_now_rfc3339());
+    snapshot.game_state = game_state;
+    snapshot.current_story = Some(saved_current_story);
+    let persisted = persist_runtime_story_snapshot(
+        &state,
+        &request_context,
+        authenticated.claims().user_id().to_string(),
+        snapshot,
+    )
+    .await?;
+    let persisted_snapshot = runtime_snapshot_payload_from_record(&persisted);
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_action_response(RuntimeStoryActionResponseParts {
+            requested_session_id,
+            server_version,
+            snapshot: persisted_snapshot,
+            action_text: resolution.action_text,
+            result_text: resolution.result_text,
+            story_text,
+            options,
+            patches,
+            toast: resolution.toast,
+            battle: resolution.battle,
+        }),
+    ))
+}
+
+pub async fn generate_runtime_story_initial(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<RuntimeStoryAiRequest>,
+) -> Result<Json<Value>, Response> {
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_ai_response(&state, payload, true).await,
+    ))
+}
+
+pub async fn generate_runtime_story_continue(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
+    Json(payload): Json<RuntimeStoryAiRequest>,
+) -> Result<Json<Value>, Response> {
+    Ok(json_success_body(
+        Some(&request_context),
+        build_runtime_story_ai_response(&state, payload, false).await,
+    ))
+}
+
+async fn resolve_snapshot_for_request(
+    state: &AppState,
+    request_context: &RequestContext,
+    user_id: String,
+    snapshot: Option<RuntimeStorySnapshotPayload>,
+) -> Result<RuntimeStorySnapshotPayload, Response> {
+    if let Some(snapshot) = snapshot {
+        let record =
+            persist_runtime_story_snapshot(state, request_context, user_id, snapshot).await?;
+        return Ok(runtime_snapshot_payload_from_record(&record));
+    }
+
+    let record = state
+        .get_runtime_snapshot_record(user_id)
+        .await
+        .map_err(|error| {
+            runtime_story_error_response(request_context, map_runtime_story_client_error(error))
+        })?
+        .ok_or_else(|| {
+            runtime_story_error_response(
+                request_context,
+                AppError::from_status(StatusCode::CONFLICT).with_details(json!({
+                    "provider": "runtime-story",
+                    "message": "运行时快照不存在，请先初始化并保存一次游戏",
+                })),
+            )
+        })?;
+
+    Ok(runtime_snapshot_payload_from_record(&record))
+}
+
+async fn persist_runtime_story_snapshot(
+    state: &AppState,
+    request_context: &RequestContext,
+    user_id: String,
+    snapshot: RuntimeStorySnapshotPayload,
+) -> Result<RuntimeSnapshotRecord, Response> {
+    validate_snapshot_payload(&snapshot).map_err(|message| {
+        runtime_story_error_response(
+            request_context,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": "runtime-story",
+                "message": message,
+            })),
+        )
+    })?;
+
+    let now = OffsetDateTime::now_utc();
+    let saved_at = snapshot
+        .saved_at
+        .as_deref()
+        .and_then(|value| normalize_required_string(value))
+        .map(|value| parse_rfc3339(value.as_str()))
+        .transpose()
+        .map_err(|error| {
+            runtime_story_error_response(
+                request_context,
+                AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                    "provider": "runtime-story",
+                    "field": "snapshot.savedAt",
+                    "message": format!("savedAt 非法: {error}"),
+                })),
+            )
+        })?
+        .unwrap_or(now);
+
+    state
+        .put_runtime_snapshot_record(
+            user_id,
+            offset_datetime_to_unix_micros(saved_at),
+            snapshot.bottom_tab,
+            snapshot.game_state,
+            snapshot.current_story,
+            offset_datetime_to_unix_micros(now),
+        )
+        .await
+        .map_err(|error| {
+            runtime_story_error_response(request_context, map_runtime_story_client_error(error))
+        })
+}
+
+fn validate_snapshot_payload(snapshot: &RuntimeStorySnapshotPayload) -> Result<(), String> {
+    if normalize_required_string(snapshot.bottom_tab.as_str()).is_none() {
+        return Err("snapshot.bottomTab 不能为空".to_string());
+    }
+    if !snapshot.game_state.is_object() {
+        return Err("snapshot.gameState 必须是 JSON object".to_string());
+    }
+    if snapshot
+        .current_story
+        .as_ref()
+        .is_some_and(|current_story| !current_story.is_object())
+    {
+        return Err("snapshot.currentStory 必须是 JSON object 或 null".to_string());
+    }
+
+    Ok(())
+}
+
+fn runtime_snapshot_payload_from_record(
+    record: &RuntimeSnapshotRecord,
+) -> RuntimeStorySnapshotPayload {
+    RuntimeStorySnapshotPayload {
+        saved_at: Some(record.saved_at.clone()),
+        bottom_tab: record.bottom_tab.clone(),
+        game_state: record.game_state.clone(),
+        current_story: record.current_story.clone(),
+    }
+}
+
+fn validate_client_version(
+    request_context: &RequestContext,
+    client_version: Option<u32>,
+    game_state: &Value,
+    message: &str,
+) -> Result<(), Response> {
+    let Some(client_version) = client_version else {
+        return Ok(());
+    };
+    let Some(server_version) = read_u32_field(game_state, "runtimeActionVersion") else {
+        return Ok(());
+    };
+    if client_version == server_version {
+        return Ok(());
+    }
+
+    Err(runtime_story_error_response(
+        request_context,
+        AppError::from_status(StatusCode::CONFLICT).with_details(json!({
+            "provider": "runtime-story",
+            "message": message,
+            "clientVersion": client_version,
+            "serverVersion": server_version,
+        })),
+    ))
+}
+
+fn resolve_runtime_story_choice_action(
+    game_state: &mut Value,
+    current_story: Option<&Value>,
+    request: &RuntimeStoryActionRequest,
+    function_id: &str,
+) -> Result<StoryResolution, String> {
+    ensure_runtime_story_bridge_state(game_state);
+    match function_id {
+        CONTINUE_ADVENTURE_FUNCTION_ID => resolve_continue_adventure_action(current_story),
+        "story_opening_camp_dialogue" => resolve_npc_affinity_action(
+            game_state,
+            request,
+            "交换开场判断",
+            2,
+            "你把眼前局势先讲清楚，对方终于愿意把第一轮判断说出口。",
+        ),
+        "camp_travel_home_scene" => {
+            clear_encounter_state(game_state);
+            Ok(StoryResolution {
+                action_text: resolve_action_text("返回营地", request),
+                result_text: "你主动结束了当前遭遇，把节奏带回了更安全的营地。".to_string(),
+                story_text: None,
+                presentation_options: None,
+                saved_current_story: None,
+                patches: vec![
+                    build_status_patch(game_state),
+                    RuntimeStoryPatch::EncounterChanged { encounter_id: None },
+                ],
+                battle: None,
+                toast: None,
+            })
+        }
+        "idle_call_out" => Ok(simple_story_resolution(
+            game_state,
+            resolve_action_text("主动出声试探", request),
+            "你的喊话打破了当前静场，周围潜着的动静也更难继续藏住。",
+        )),
+        "idle_explore_forward" => Ok(simple_story_resolution(
+            game_state,
+            resolve_action_text("继续向前探索", request),
+            "你没有停在原地，而是继续向前压，把下一段遭遇主动推到自己面前。",
+        )),
+        "idle_observe_signs" => Ok(simple_story_resolution(
+            game_state,
+            resolve_action_text("观察周围迹象", request),
+            "你先压住动作，把风向、脚印和气味这些细节重新读了一遍。",
+        )),
+        "idle_rest_focus" => {
+            restore_player_resource(game_state, 8, 6);
+            Ok(simple_story_resolution(
+                game_state,
+                resolve_action_text("原地调息", request),
+                "你把呼吸慢下来重新稳住节奏，生命和灵力都回上来一点。",
+            ))
+        }
+        "idle_travel_next_scene" => {
+            clear_encounter_state(game_state);
+            increment_runtime_stat(game_state, "scenesTraveled", 1);
+            Ok(StoryResolution {
+                action_text: resolve_action_text("前往相邻场景", request),
+                result_text: "你收束了这一段遭遇，顺着路线把故事推进到新的场景段落。".to_string(),
+                story_text: None,
+                presentation_options: None,
+                saved_current_story: None,
+                patches: vec![
+                    build_status_patch(game_state),
+                    RuntimeStoryPatch::EncounterChanged { encounter_id: None },
+                ],
+                battle: None,
+                toast: None,
+            })
+        }
+        "npc_preview_talk" => resolve_npc_preview_action(game_state, request),
+        "npc_chat" => resolve_npc_chat_action(game_state, request),
+        "npc_help" => resolve_npc_help_action(game_state, request),
+        "npc_chat_quest_offer_view" => {
+            resolve_pending_quest_offer_view_action(game_state, current_story, request)
+        }
+        "npc_chat_quest_offer_replace" => {
+            resolve_pending_quest_offer_replace_action(game_state, current_story, request)
+        }
+        "npc_chat_quest_offer_abandon" => {
+            resolve_pending_quest_offer_abandon_action(game_state, current_story, request)
+        }
+        "npc_quest_accept" => {
+            resolve_pending_quest_accept_action(game_state, current_story, request)
+        }
+        "npc_quest_turn_in" => resolve_pending_quest_turn_in_action(game_state, request),
+        "npc_leave" => {
+            let npc_name = current_encounter_name(game_state);
+            clear_encounter_state(game_state);
+            Ok(StoryResolution {
+                action_text: resolve_action_text("离开当前角色", request),
+                result_text: format!("你结束了与 {npc_name} 的这一轮接触，把注意力重新放回旅途。"),
+                story_text: None,
+                presentation_options: None,
+                saved_current_story: None,
+                patches: vec![
+                    build_status_patch(game_state),
+                    RuntimeStoryPatch::EncounterChanged { encounter_id: None },
+                ],
+                battle: None,
+                toast: None,
+            })
+        }
+        "npc_fight" | "npc_spar" => {
+            resolve_npc_battle_entry_action(game_state, request, function_id)
+        }
+        "npc_trade" => resolve_npc_trade_action(game_state, request),
+        "npc_gift" => resolve_npc_gift_action(game_state, request),
+        "npc_recruit" => resolve_npc_recruit_action(game_state, request),
+        "equipment_equip" => resolve_equipment_equip_action(game_state, request),
+        "equipment_unequip" => resolve_equipment_unequip_action(game_state, request),
+        "forge_craft" => resolve_forge_craft_action(game_state, request),
+        "forge_dismantle" => resolve_forge_dismantle_action(game_state, request),
+        "forge_reforge" => resolve_forge_reforge_action(game_state, request),
+        "battle_attack_basic"
+        | "battle_use_skill"
+        | "battle_all_in_crush"
+        | "battle_escape_breakout"
+        | "battle_feint_step"
+        | "battle_finisher_window"
+        | "battle_guard_break"
+        | "battle_probe_pressure"
+        | "battle_recover_breath"
+        | "inventory_use" => resolve_battle_action(game_state, request, function_id),
+        _ => Err(format!("暂不支持的 runtime action：{function_id}")),
+    }
+}
+
+fn resolve_continue_adventure_action(
+    current_story: Option<&Value>,
+) -> Result<StoryResolution, String> {
+    let deferred_options = current_story
+        .map(|story| {
+            read_array_field(story, "deferredOptions")
+                .into_iter()
+                .filter_map(build_runtime_story_option_from_story_option)
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    let options = (!deferred_options.is_empty()).then_some(deferred_options);
+
+    Ok(StoryResolution {
+        action_text: "继续推进冒险".to_string(),
+        result_text: "你没有把节奏停下来，而是顺着当前局势继续向前推进了这一段故事。".to_string(),
+        story_text: None,
+        presentation_options: options,
+        saved_current_story: None,
+        patches: Vec::new(),
+        battle: None,
+        toast: None,
+    })
+}
+
+fn map_runtime_story_client_error(error: SpacetimeClientError) -> AppError {
+    let (status, provider) = match error {
+        SpacetimeClientError::Runtime(_) => (StatusCode::BAD_REQUEST, "runtime-story"),
+        _ => (StatusCode::BAD_GATEWAY, "spacetimedb"),
+    };
+
+    AppError::from_status(status).with_details(json!({
+        "provider": provider,
+        "message": error.to_string(),
+    }))
+}
+
+fn runtime_story_error_response(request_context: &RequestContext, error: AppError) -> Response {
+    error.into_response_with_context(Some(request_context))
+}

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

@@ -0,0 +1,358 @@
+use super::*;
+
+pub(super) async fn build_runtime_story_ai_response(
+    state: &AppState,
+    payload: RuntimeStoryAiRequest,
+    initial: bool,
+) -> RuntimeStoryAiResponse {
+    let options = build_ai_response_options(&payload);
+    let fallback = build_ai_fallback_story_text(&payload, initial);
+    let story_text = generate_ai_story_text(state, &payload, initial)
+        .await
+        .filter(|text| !text.trim().is_empty())
+        .unwrap_or(fallback);
+
+    RuntimeStoryAiResponse {
+        story_text,
+        options,
+        encounter: None,
+    }
+}
+
+pub(super) async fn generate_ai_story_text(
+    state: &AppState,
+    payload: &RuntimeStoryAiRequest,
+    initial: bool,
+) -> Option<String> {
+    let llm_client = state.llm_client()?;
+    let system_prompt = if initial {
+        "你是游戏运行时剧情导演。请用中文输出一段可直接展示给玩家的开局剧情，不要输出 JSON。"
+    } else {
+        "你是游戏运行时剧情导演。请用中文根据玩家选择续写一段剧情，不要输出 JSON。"
+    };
+    let user_prompt = json!({
+        "worldType": payload.world_type,
+        "character": payload.character,
+        "monsters": payload.monsters,
+        "history": payload.history,
+        "choice": payload.choice,
+        "context": payload.context,
+        "availableOptions": payload.request_options.available_options,
+    })
+    .to_string();
+    let mut request = LlmTextRequest::new(vec![
+        LlmMessage::system(system_prompt),
+        LlmMessage::user(user_prompt),
+    ]);
+    request.max_tokens = Some(700);
+
+    llm_client
+        .request_text(request)
+        .await
+        .ok()
+        .map(|response| response.content.trim().to_string())
+        .filter(|text| !text.is_empty())
+}
+
+pub(super) async fn generate_action_story_payload(
+    state: &AppState,
+    game_state: &Value,
+    request: &RuntimeStoryActionRequest,
+    function_id: &str,
+    action_text: &str,
+    result_text: &str,
+    options: &[RuntimeStoryOptionView],
+    battle: Option<&RuntimeBattlePresentation>,
+) -> Option<GeneratedStoryPayload> {
+    let llm_client = state.llm_client()?;
+    // 动作结算仍由确定性规则完成；LLM 只负责把已结算结果改写为可展示文本，失败时不影响主链。
+    if function_id == "npc_chat" || function_id == "story_opening_camp_dialogue" {
+        return generate_npc_dialogue_payload(
+            llm_client,
+            game_state,
+            request,
+            action_text,
+            result_text,
+            options,
+        )
+        .await;
+    }
+
+    if should_generate_reasoned_combat_story(battle) {
+        return generate_reasoned_story_payload(
+            llm_client,
+            game_state,
+            request,
+            action_text,
+            result_text,
+            options,
+            battle,
+        )
+        .await;
+    }
+
+    None
+}
+
+pub(super) async fn generate_npc_dialogue_payload(
+    llm_client: &LlmClient,
+    game_state: &Value,
+    request: &RuntimeStoryActionRequest,
+    action_text: &str,
+    result_text: &str,
+    deferred_options: &[RuntimeStoryOptionView],
+) -> Option<GeneratedStoryPayload> {
+    let world_type = current_world_type(game_state)?;
+    let character = read_object_field(game_state, "playerCharacter")?.clone();
+    let encounter = read_object_field(game_state, "currentEncounter")?;
+    if read_required_string_field(encounter, "kind").as_deref() != Some("npc") {
+        return None;
+    }
+    let npc_name = read_optional_string_field(encounter, "npcName")
+        .or_else(|| read_optional_string_field(encounter, "name"))
+        .unwrap_or_else(|| "对方".to_string());
+    let user_prompt = json!({
+        "worldType": world_type,
+        "character": character,
+        "encounter": encounter,
+        "monsters": read_array_field(game_state, "sceneHostileNpcs").into_iter().cloned().collect::<Vec<_>>(),
+        "history": build_action_story_history(game_state, action_text, result_text),
+        "context": build_action_story_prompt_context(game_state, None),
+        "topic": action_text,
+        "resultSummary": result_text,
+        "requestedOption": request.action.payload,
+        "availableOptions": build_action_prompt_options(deferred_options),
+    })
+    .to_string();
+    let mut llm_request = LlmTextRequest::new(vec![
+        LlmMessage::system(
+            "你是游戏运行时 NPC 对话导演。只输出中文正文，不要输出 JSON、Markdown 或规则说明；不要新增系统尚未结算的奖励、任务结果或战斗结果。",
+        ),
+        LlmMessage::user(format!(
+            "请基于以下运行时状态，把玩家这一轮选择改写成 2 到 5 行可直接展示的 NPC 对话。可以使用“你：”和“{npc_name}：”格式，必须保留既有结算含义。\n{user_prompt}"
+        )),
+    ]);
+    llm_request.max_tokens = Some(700);
+
+    let dialogue_text = llm_client
+        .request_text(llm_request)
+        .await
+        .ok()
+        .map(|response| response.content.trim().to_string())
+        .filter(|text| !text.is_empty())?;
+    let presentation_options = vec![build_continue_adventure_runtime_story_option()];
+    let saved_current_story =
+        build_dialogue_current_story(npc_name.as_str(), dialogue_text.as_str(), deferred_options);
+
+    Some(GeneratedStoryPayload {
+        story_text: dialogue_text.clone(),
+        history_result_text: dialogue_text,
+        presentation_options,
+        saved_current_story,
+    })
+}
+
+pub(super) async fn generate_reasoned_story_payload(
+    llm_client: &LlmClient,
+    game_state: &Value,
+    request: &RuntimeStoryActionRequest,
+    action_text: &str,
+    result_text: &str,
+    options: &[RuntimeStoryOptionView],
+    battle: Option<&RuntimeBattlePresentation>,
+) -> Option<GeneratedStoryPayload> {
+    let world_type = current_world_type(game_state)?;
+    let character = read_object_field(game_state, "playerCharacter")?.clone();
+    let user_prompt = json!({
+        "worldType": world_type,
+        "character": character,
+        "monsters": read_array_field(game_state, "sceneHostileNpcs").into_iter().cloned().collect::<Vec<_>>(),
+        "history": build_action_story_history(game_state, action_text, result_text),
+        "context": build_action_story_prompt_context(game_state, battle),
+        "choice": action_text,
+        "resultSummary": result_text,
+        "requestedOption": request.action.payload,
+        "availableOptions": build_action_prompt_options(options),
+    })
+    .to_string();
+    let mut llm_request = LlmTextRequest::new(vec![
+        LlmMessage::system(
+            "你是游戏运行时剧情导演。只输出中文剧情正文，不要输出 JSON、Markdown 或规则说明；必须尊重已结算的战斗 outcome、伤害和状态，不要发明额外奖励。",
+        ),
+        LlmMessage::user(format!(
+            "请基于以下运行时状态，为这一轮战斗结算生成一段 120 字以内的结果叙事，并自然引出下一组选项。\n{user_prompt}"
+        )),
+    ]);
+    llm_request.max_tokens = Some(700);
+
+    let story_text = llm_client
+        .request_text(llm_request)
+        .await
+        .ok()
+        .map(|response| response.content.trim().to_string())
+        .filter(|text| !text.is_empty())?;
+
+    Some(GeneratedStoryPayload {
+        story_text: story_text.clone(),
+        history_result_text: story_text.clone(),
+        presentation_options: options.to_vec(),
+        saved_current_story: build_legacy_current_story(story_text.as_str(), options),
+    })
+}
+
+pub(super) fn should_generate_reasoned_combat_story(
+    battle: Option<&RuntimeBattlePresentation>,
+) -> bool {
+    battle
+        .and_then(|presentation| presentation.outcome.as_deref())
+        .is_some_and(|outcome| matches!(outcome, "victory" | "spar_complete" | "escaped"))
+}
+
+pub(super) fn build_action_story_history(
+    game_state: &Value,
+    action_text: &str,
+    result_text: &str,
+) -> Vec<Value> {
+    let mut history = read_array_field(game_state, "storyHistory")
+        .into_iter()
+        .filter_map(|entry| {
+            let text = read_optional_string_field(entry, "text")?;
+            let history_role = read_optional_string_field(entry, "historyRole")
+                .unwrap_or_else(|| "result".to_string());
+            Some(json!({
+                "text": text,
+                "historyRole": history_role,
+            }))
+        })
+        .collect::<Vec<_>>();
+    history.push(json!({
+        "text": action_text,
+        "historyRole": "action",
+    }));
+    history.push(json!({
+        "text": result_text,
+        "historyRole": "result",
+    }));
+    let keep_from = history.len().saturating_sub(12);
+    history.into_iter().skip(keep_from).collect()
+}
+
+pub(super) fn build_action_story_prompt_context(
+    game_state: &Value,
+    battle: Option<&RuntimeBattlePresentation>,
+) -> Value {
+    let scene_preset = read_object_field(game_state, "currentScenePreset");
+    let battle_value = battle
+        .and_then(|presentation| serde_json::to_value(presentation).ok())
+        .unwrap_or(Value::Null);
+
+    json!({
+        "sceneName": scene_preset
+            .and_then(|scene| read_optional_string_field(scene, "name"))
+            .or_else(|| read_optional_string_field(game_state, "currentScene"))
+            .unwrap_or_else(|| "当前区域".to_string()),
+        "sceneDescription": scene_preset
+            .and_then(|scene| read_optional_string_field(scene, "description"))
+            .or_else(|| read_optional_string_field(game_state, "sceneDescription"))
+            .unwrap_or_else(|| "周围气氛仍在继续变化。".to_string()),
+        "encounterName": read_object_field(game_state, "currentEncounter")
+            .and_then(|encounter| {
+                read_optional_string_field(encounter, "npcName")
+                    .or_else(|| read_optional_string_field(encounter, "name"))
+            }),
+        "encounterId": current_encounter_id(game_state),
+        "playerHp": read_i32_field(game_state, "playerHp").unwrap_or(0),
+        "playerMaxHp": read_i32_field(game_state, "playerMaxHp").unwrap_or(1),
+        "playerMana": read_i32_field(game_state, "playerMana").unwrap_or(0),
+        "playerMaxMana": read_i32_field(game_state, "playerMaxMana").unwrap_or(1),
+        "inBattle": read_bool_field(game_state, "inBattle").unwrap_or(false),
+        "currentNpcBattleOutcome": read_optional_string_field(game_state, "currentNpcBattleOutcome"),
+        "battle": battle_value,
+    })
+}
+
+pub(super) fn build_action_prompt_options(options: &[RuntimeStoryOptionView]) -> Vec<Value> {
+    options
+        .iter()
+        .filter(|option| !option.disabled.unwrap_or(false))
+        .map(|option| {
+            json!({
+                "functionId": option.function_id,
+                "actionText": option.action_text,
+                "text": option.action_text,
+            })
+        })
+        .collect()
+}
+
+pub(super) fn build_ai_response_options(payload: &RuntimeStoryAiRequest) -> Vec<Value> {
+    let source = if payload.request_options.available_options.is_empty() {
+        &payload.request_options.option_catalog
+    } else {
+        &payload.request_options.available_options
+    };
+    let options = source
+        .iter()
+        .filter_map(normalize_ai_story_option)
+        .collect::<Vec<_>>();
+    if !options.is_empty() {
+        return options;
+    }
+
+    vec![
+        build_ai_story_option_value("idle_observe_signs", "观察周围迹象"),
+        build_ai_story_option_value("idle_explore_forward", "继续向前探索"),
+        build_ai_story_option_value("idle_rest_focus", "原地调息"),
+    ]
+}
+
+pub(super) fn normalize_ai_story_option(value: &Value) -> Option<Value> {
+    let function_id = read_required_string_field(value, "functionId")?;
+    let action_text = read_required_string_field(value, "actionText")
+        .or_else(|| read_required_string_field(value, "text"))
+        .unwrap_or_else(|| function_id.clone());
+    let mut option = value.as_object()?.clone();
+    option.insert("functionId".to_string(), Value::String(function_id));
+    option.insert("actionText".to_string(), Value::String(action_text.clone()));
+    option
+        .entry("text".to_string())
+        .or_insert_with(|| Value::String(action_text));
+
+    Some(Value::Object(option))
+}
+
+pub(super) fn build_ai_story_option_value(function_id: &str, action_text: &str) -> Value {
+    json!({
+        "functionId": function_id,
+        "actionText": action_text,
+        "text": action_text,
+        "visuals": {
+            "playerAnimation": "idle",
+            "playerMoveMeters": 0,
+            "playerOffsetY": 0,
+            "playerFacing": "right",
+            "scrollWorld": false,
+            "monsterChanges": []
+        }
+    })
+}
+
+pub(super) fn build_ai_fallback_story_text(
+    payload: &RuntimeStoryAiRequest,
+    initial: bool,
+) -> String {
+    let character_name =
+        read_optional_string_field(&payload.character, "name").unwrap_or_else(|| "你".to_string());
+    let scene_name = read_optional_string_field(&payload.context, "sceneName")
+        .or_else(|| read_optional_string_field(&payload.context, "scene"))
+        .unwrap_or_else(|| "当前区域".to_string());
+    if initial {
+        return format!(
+            "{character_name} 在 {scene_name} 稳住脚步，周围的气息正在变化，第一轮选择已经摆到眼前。"
+        );
+    }
+
+    let choice = normalize_required_string(payload.choice.as_str())
+        .unwrap_or_else(|| "继续推进".to_string());
+    format!("{character_name} 选择了「{choice}」，{scene_name} 的局势随之向下一步展开。")
+}

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

@@ -0,0 +1,106 @@
+use super::*;
+
+/// 对齐 Node 旧 inventory compat，先按装备位把物品从背包切到 playerEquipment，
+/// 再把基础面板属性回算到快照上。
+pub(super) fn resolve_equipment_equip_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    if read_field(game_state, "playerCharacter").is_none() {
+        return Err("缺少玩家角色，无法调整装备。".to_string());
+    }
+    if read_bool_field(game_state, "inBattle").unwrap_or(false) {
+        return Err("战斗中无法调整装备。".to_string());
+    }
+    let item_id = request
+        .action
+        .payload
+        .as_ref()
+        .and_then(|payload| read_optional_string_field(payload, "itemId"))
+        .or_else(|| request.action.target_id.clone())
+        .ok_or_else(|| "equipment_equip 缺少 itemId".to_string())?;
+    let item = find_player_inventory_entry(game_state, item_id.as_str())
+        .cloned()
+        .ok_or_else(|| "背包里没有这件装备。".to_string())?;
+    let slot_id = resolve_equipment_slot_for_item(&item)
+        .ok_or_else(|| format!("{} 不是可装备物品。", read_inventory_item_name(&item)))?;
+    let previous_equipment = read_player_equipment_item(game_state, slot_id);
+    let next_equipment_item = normalize_equipped_item(&item);
+
+    remove_player_inventory_item(game_state, item_id.as_str(), 1);
+    if let Some(previous_equipment) = previous_equipment.as_ref() {
+        add_player_inventory_items(game_state, vec![previous_equipment.clone()]);
+    }
+    write_player_equipment_item(game_state, slot_id, Some(next_equipment_item));
+    apply_equipment_loadout_to_state(game_state);
+
+    let item_name = read_inventory_item_name(&item);
+    let result_text = if let Some(previous_equipment) = previous_equipment.as_ref() {
+        format!(
+            "你将{}从{}位上换下，改为装备{}。",
+            read_inventory_item_name(previous_equipment),
+            equipment_slot_label(slot_id),
+            item_name
+        )
+    } else {
+        format!(
+            "你将{}装备在{}位上。",
+            item_name,
+            equipment_slot_label(slot_id)
+        )
+    };
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("装备{}", item_name), request),
+        result_text,
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: Vec::new(),
+        battle: None,
+        toast: Some(build_current_build_toast(game_state)),
+    })
+}
+
+pub(super) fn resolve_equipment_unequip_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    ensure_inventory_action_available(
+        game_state,
+        "缺少玩家角色，无法卸下装备。",
+        "战斗中无法卸下装备。",
+    )?;
+    let slot_id = request
+        .action
+        .payload
+        .as_ref()
+        .and_then(|payload| read_optional_string_field(payload, "slotId"))
+        .or_else(|| request.action.target_id.clone())
+        .ok_or_else(|| "equipment_unequip 缺少合法 slotId".to_string())?;
+    let slot_id = normalize_equipment_slot_id(slot_id.as_str())
+        .ok_or_else(|| "equipment_unequip 缺少合法 slotId".to_string())?;
+    let equipped_item = read_player_equipment_item(game_state, slot_id)
+        .ok_or_else(|| format!("{}位当前没有装备。", equipment_slot_label(slot_id)))?;
+
+    write_player_equipment_item(game_state, slot_id, None);
+    add_player_inventory_items(game_state, vec![equipped_item.clone()]);
+    apply_equipment_loadout_to_state(game_state);
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(
+            &format!("卸下{}", read_inventory_item_name(&equipped_item)),
+            request,
+        ),
+        result_text: format!(
+            "你卸下了{}，暂时收回背包。",
+            read_inventory_item_name(&equipped_item)
+        ),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: Vec::new(),
+        battle: None,
+        toast: Some(build_current_build_toast(game_state)),
+    })
+}

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

@@ -0,0 +1,5 @@
+use super::*;
+
+pub(super) use module_runtime_story_compat::{
+    build_runtime_equipment_item, build_runtime_material_item,
+};

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

@@ -0,0 +1,699 @@
+use super::*;
+use module_runtime_story_compat::{build_runtime_equipment_item, build_runtime_material_item};
+
+pub(super) fn current_npc_trade_context(game_state: &Value) -> Result<(String, String), String> {
+    let encounter = read_object_field(game_state, "currentEncounter")
+        .ok_or_else(|| "当前不在可结算的 NPC 交互态，无法执行交易或赠礼。".to_string())?;
+    let kind = read_required_string_field(encounter, "kind")
+        .ok_or_else(|| "当前不在可结算的 NPC 交互态，无法执行交易或赠礼。".to_string())?;
+    if kind != "npc" {
+        return Err("当前不在可结算的 NPC 交互态，无法执行交易或赠礼。".to_string());
+    }
+    let npc_name = current_encounter_name(game_state);
+    let npc_id = current_encounter_id(game_state).unwrap_or_else(|| npc_name.clone());
+    if resolve_current_encounter_npc_state(game_state, npc_id.as_str(), npc_name.as_str()).is_none()
+    {
+        return Err("当前 NPC 状态不存在，无法继续结算。".to_string());
+    }
+    Ok((npc_id, npc_name))
+}
+
+pub(super) fn current_npc_inventory_items<'a>(game_state: &'a Value) -> Vec<&'a Value> {
+    let Some(npc_id) = current_encounter_id(game_state) else {
+        return Vec::new();
+    };
+    let npc_name = current_encounter_name(game_state);
+    resolve_current_encounter_npc_state(game_state, npc_id.as_str(), npc_name.as_str())
+        .map(|state| read_array_field(state, "inventory"))
+        .unwrap_or_default()
+}
+
+/// 兼容桥沿用 Node 旧域的入口预处理：在读取选项或结算动作前，
+/// 先确保当前 NPC 的持久状态最少可用，避免空快照直接打断交易/赠礼/委托主链。
+pub(super) fn ensure_runtime_story_bridge_state(game_state: &mut Value) {
+    ensure_current_encounter_npc_state_initialized(game_state);
+}
+
+/// 这里不尝试一次性重建完整真相态，只补 compat bridge 当前确实依赖的字段，
+/// 并为“纯商贩型 NPC”补一份确定性 trade stock，保证旧前端菜单不因空状态掉链子。
+pub(super) fn ensure_current_encounter_npc_state_initialized(game_state: &mut Value) {
+    let Some(encounter) = read_object_field(game_state, "currentEncounter").cloned() else {
+        return;
+    };
+    if read_optional_string_field(&encounter, "kind").as_deref() != Some("npc") {
+        return;
+    }
+
+    let npc_name = read_optional_string_field(&encounter, "npcName")
+        .or_else(|| read_optional_string_field(&encounter, "name"))
+        .unwrap_or_else(|| "当前遭遇".to_string());
+    let npc_id = read_optional_string_field(&encounter, "id").unwrap_or_else(|| npc_name.clone());
+    let storage_key = resolve_npc_state_storage_key(game_state, npc_id.as_str(), npc_name.as_str());
+    let existing_state = read_field(game_state, "npcStates")
+        .and_then(|states| read_field(states, storage_key.as_str()))
+        .cloned();
+
+    let affinity = existing_state
+        .as_ref()
+        .and_then(|state| read_i32_field(state, "affinity"))
+        .unwrap_or_else(|| default_current_npc_affinity(&encounter));
+    let recruited = existing_state
+        .as_ref()
+        .and_then(|state| read_bool_field(state, "recruited"))
+        .unwrap_or(false);
+    let chatted_count = existing_state
+        .as_ref()
+        .and_then(|state| read_i32_field(state, "chattedCount"))
+        .unwrap_or(0)
+        .max(0);
+    let gifts_given = existing_state
+        .as_ref()
+        .and_then(|state| read_i32_field(state, "giftsGiven"))
+        .unwrap_or(0)
+        .max(0);
+    let help_used = existing_state
+        .as_ref()
+        .and_then(|state| read_bool_field(state, "helpUsed"))
+        .unwrap_or(false);
+    let first_meaningful_contact_resolved = existing_state
+        .as_ref()
+        .and_then(|state| read_bool_field(state, "firstMeaningfulContactResolved"))
+        .unwrap_or(false);
+    let revealed_facts = existing_state
+        .as_ref()
+        .map(|state| read_string_list_field(state, "revealedFacts"))
+        .unwrap_or_default();
+    let known_attribute_rumors = existing_state
+        .as_ref()
+        .map(|state| read_string_list_field(state, "knownAttributeRumors"))
+        .unwrap_or_default();
+    let seen_backstory_chapter_ids = existing_state
+        .as_ref()
+        .map(|state| read_string_list_field(state, "seenBackstoryChapterIds"))
+        .unwrap_or_default();
+    let existing_inventory = existing_state
+        .as_ref()
+        .map(|state| {
+            read_array_field(state, "inventory")
+                .into_iter()
+                .cloned()
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+    let existing_trade_stock_signature = existing_state
+        .as_ref()
+        .and_then(|state| read_optional_string_field(state, "tradeStockSignature"));
+    let hostile = read_bool_field(&encounter, "hostile").unwrap_or(false)
+        || read_optional_string_field(&encounter, "monsterPresetId").is_some()
+        || affinity < 0;
+    let context_text = read_optional_string_field(&encounter, "context");
+
+    let (inventory, trade_stock_signature) = if is_trade_driven_role_npc(&encounter) {
+        let next_signature = build_current_npc_trade_stock_signature(game_state, npc_id.as_str());
+        if existing_trade_stock_signature.as_deref() == Some(next_signature.as_str()) {
+            (existing_inventory, Some(next_signature))
+        } else {
+            (
+                sync_bootstrapped_trade_inventory(
+                    game_state,
+                    npc_id.as_str(),
+                    npc_name.as_str(),
+                    existing_inventory,
+                    next_signature.as_str(),
+                ),
+                Some(next_signature),
+            )
+        }
+    } else {
+        (existing_inventory, existing_trade_stock_signature)
+    };
+
+    let relation_state = build_runtime_story_relation_state_value(affinity);
+    let stance_profile = build_runtime_story_stance_profile_value(
+        affinity,
+        recruited,
+        hostile,
+        context_text.as_deref(),
+        existing_state
+            .as_ref()
+            .and_then(|state| read_field(state, "stanceProfile"))
+            .and_then(Value::as_object),
+    );
+    let npc_state = json!({
+        "affinity": affinity,
+        "chattedCount": chatted_count,
+        "helpUsed": help_used,
+        "giftsGiven": gifts_given,
+        "inventory": inventory,
+        "recruited": recruited,
+        "relationState": relation_state,
+        "revealedFacts": revealed_facts,
+        "knownAttributeRumors": known_attribute_rumors,
+        "firstMeaningfulContactResolved": first_meaningful_contact_resolved,
+        "seenBackstoryChapterIds": seen_backstory_chapter_ids,
+        "tradeStockSignature": trade_stock_signature,
+        "stanceProfile": stance_profile,
+    });
+
+    let root = ensure_json_object(game_state);
+    let npc_states = root
+        .entry("npcStates".to_string())
+        .or_insert_with(|| Value::Object(Map::new()));
+    if !npc_states.is_object() {
+        *npc_states = Value::Object(Map::new());
+    }
+    npc_states
+        .as_object_mut()
+        .expect("npcStates should be object")
+        .insert(storage_key, npc_state);
+}
+
+pub(super) fn resolve_npc_state_storage_key(
+    game_state: &Value,
+    npc_id: &str,
+    npc_name: &str,
+) -> String {
+    read_object_field(game_state, "npcStates")
+        .and_then(Value::as_object)
+        .and_then(|states| {
+            if states.contains_key(npc_id) {
+                Some(npc_id.to_string())
+            } else if states.contains_key(npc_name) {
+                Some(npc_name.to_string())
+            } else {
+                None
+            }
+        })
+        .unwrap_or_else(|| npc_id.to_string())
+}
+
+pub(super) fn default_current_npc_affinity(encounter: &Value) -> i32 {
+    read_i32_field(encounter, "initialAffinity").unwrap_or_else(|| {
+        if read_optional_string_field(encounter, "monsterPresetId").is_some() {
+            -40
+        } else if read_optional_string_field(encounter, "characterId").is_some() {
+            18
+        } else {
+            6
+        }
+    })
+}
+
+pub(super) fn read_string_list_field(value: &Value, key: &str) -> Vec<String> {
+    let mut items = read_array_field(value, key)
+        .into_iter()
+        .filter_map(Value::as_str)
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .map(str::to_string)
+        .collect::<Vec<_>>();
+    if items.len() > 3 {
+        items = items.split_off(items.len() - 3);
+    }
+    items
+}
+
+pub(super) fn build_runtime_story_relation_state_value(affinity: i32) -> Value {
+    let relation_state = build_module_npc_relation_state(affinity);
+    json!({
+        "affinity": relation_state.affinity,
+        "stance": npc_relation_stance_key(relation_state.stance),
+    })
+}
+
+pub(super) fn npc_relation_stance_key(value: NpcRelationStance) -> &'static str {
+    match value {
+        NpcRelationStance::Hostile => "hostile",
+        NpcRelationStance::Guarded => "guarded",
+        NpcRelationStance::Neutral => "neutral",
+        NpcRelationStance::Cooperative => "cooperative",
+        NpcRelationStance::Bonded => "bonded",
+    }
+}
+
+pub(super) fn build_runtime_story_stance_profile_value(
+    affinity: i32,
+    recruited: bool,
+    hostile: bool,
+    role_text: Option<&str>,
+    existing_profile: Option<&Map<String, Value>>,
+) -> Value {
+    let base = build_module_npc_initial_stance_profile(affinity, recruited, hostile, role_text);
+    let read_metric = |key: &str, fallback: u8| -> i32 {
+        existing_profile
+            .and_then(|profile| profile.get(key))
+            .and_then(Value::as_i64)
+            .and_then(|value| i32::try_from(value).ok())
+            .unwrap_or(i32::from(fallback))
+            .clamp(0, 100)
+    };
+    let recent_approvals = existing_profile
+        .and_then(|profile| profile.get("recentApprovals"))
+        .map(|value| read_string_list_field(value, ""))
+        .unwrap_or_else(|| base.recent_approvals.clone());
+    let recent_disapprovals = existing_profile
+        .and_then(|profile| profile.get("recentDisapprovals"))
+        .map(|value| read_string_list_field(value, ""))
+        .unwrap_or_else(|| base.recent_disapprovals.clone());
+
+    json!({
+        "trust": read_metric("trust", base.trust),
+        "warmth": read_metric("warmth", base.warmth),
+        "ideologicalFit": read_metric("ideologicalFit", base.ideological_fit),
+        "fearOrGuard": read_metric("fearOrGuard", base.fear_or_guard),
+        "loyalty": read_metric("loyalty", base.loyalty),
+        "currentConflictTag": existing_profile
+            .and_then(|profile| profile.get("currentConflictTag"))
+            .and_then(Value::as_str)
+            .map(str::to_string)
+            .or(base.current_conflict_tag),
+        "recentApprovals": recent_approvals,
+        "recentDisapprovals": recent_disapprovals,
+    })
+}
+
+pub(super) fn is_trade_driven_role_npc(encounter: &Value) -> bool {
+    read_optional_string_field(encounter, "characterId").is_none()
+        && read_optional_string_field(encounter, "monsterPresetId").is_none()
+}
+
+pub(super) fn build_current_npc_trade_stock_signature(game_state: &Value, npc_id: &str) -> String {
+    let scene_key = read_object_field(game_state, "currentScenePreset")
+        .and_then(|preset| {
+            read_optional_string_field(preset, "id")
+                .or_else(|| read_optional_string_field(preset, "name"))
+        })
+        .or_else(|| read_optional_string_field(game_state, "currentScene"))
+        .unwrap_or_else(|| "scene".to_string());
+    let world_key = current_world_type(game_state).unwrap_or_else(|| "world".to_string());
+    format!(
+        "{}:{}:{}",
+        sanitize_trade_stock_fragment(npc_id),
+        sanitize_trade_stock_fragment(scene_key.as_str()),
+        sanitize_trade_stock_fragment(world_key.as_str())
+    )
+}
+
+pub(super) fn sanitize_trade_stock_fragment(value: &str) -> String {
+    let normalized = value
+        .trim()
+        .chars()
+        .map(|ch| match ch {
+            ':' | '/' | '\\' | ' ' => '-',
+            _ => ch,
+        })
+        .collect::<String>();
+    if normalized.is_empty() {
+        "unknown".to_string()
+    } else {
+        normalized
+    }
+}
+
+pub(super) fn sync_bootstrapped_trade_inventory(
+    game_state: &Value,
+    npc_id: &str,
+    npc_name: &str,
+    existing_inventory: Vec<Value>,
+    trade_stock_signature: &str,
+) -> Vec<Value> {
+    let preserved_inventory = existing_inventory
+        .into_iter()
+        .filter(|item| {
+            read_field(item, "runtimeMetadata")
+                .and_then(|metadata| read_optional_string_field(metadata, "generationChannel"))
+                .as_deref()
+                != Some("npc_trade")
+        })
+        .collect::<Vec<_>>();
+    let mut next_inventory = preserved_inventory;
+    next_inventory.extend(build_bootstrapped_trade_inventory(
+        game_state,
+        npc_id,
+        npc_name,
+        trade_stock_signature,
+    ));
+    next_inventory
+}
+
+pub(super) fn build_bootstrapped_trade_inventory(
+    game_state: &Value,
+    npc_id: &str,
+    npc_name: &str,
+    trade_stock_signature: &str,
+) -> Vec<Value> {
+    let world_type = current_world_type(game_state);
+    let consumable_name = if world_type.as_deref() == Some("XIANXIA") {
+        "回灵散"
+    } else {
+        "回气散"
+    };
+    let material_name = if world_type.as_deref() == Some("XIANXIA") {
+        "凝光纱"
+    } else {
+        "工巧残材"
+    };
+    let relic_name = if world_type.as_deref() == Some("XIANXIA") {
+        "行旅护符"
+    } else {
+        "结绳护符"
+    };
+    let armor_name = if world_type.as_deref() == Some("XIANXIA") {
+        "护行法衣"
+    } else {
+        "护行短甲"
+    };
+    let tonic_id = format!("npc-trade:{trade_stock_signature}:tonic");
+    let material_id = format!("npc-trade:{trade_stock_signature}:material");
+    let relic_id = format!("npc-trade:{trade_stock_signature}:relic");
+    let armor_id = format!("npc-trade:{trade_stock_signature}:armor");
+
+    vec![
+        build_bootstrapped_trade_consumable_item(
+            tonic_id.as_str(),
+            consumable_name,
+            npc_name,
+            world_type.as_deref(),
+        ),
+        attach_generated_trade_metadata(
+            build_runtime_material_item(
+                game_state,
+                material_name,
+                2,
+                &["工巧", "补给"],
+                "uncommon",
+            ),
+            material_id.as_str(),
+            "npc_trade",
+            format!("{npc_id}:material").as_str(),
+            format!("{npc_name}整理出来的可交易工坊材料。").as_str(),
+        ),
+        attach_generated_trade_metadata(
+            build_runtime_equipment_item(
+                game_state,
+                relic_name,
+                "relic",
+                "rare",
+                "适合长途行路时稳住灵力与节奏的护符。",
+                "护持",
+                &["护持", "法力"],
+                &["护持", "法力"],
+                json!({
+                    "maxManaBonus": 12,
+                    "outgoingDamageBonus": 0.05
+                }),
+            ),
+            relic_id.as_str(),
+            "npc_trade",
+            format!("{npc_id}:relic").as_str(),
+            format!("{npc_name}随身携带的护身小物。").as_str(),
+        ),
+        attach_generated_trade_metadata(
+            build_runtime_equipment_item(
+                game_state,
+                armor_name,
+                "armor",
+                "rare",
+                "为行路与近身护体准备的轻装护具。",
+                "守御",
+                &["守御", "护体"],
+                &["守御", "护体"],
+                json!({
+                    "maxHpBonus": 18,
+                    "incomingDamageMultiplier": 0.93
+                }),
+            ),
+            armor_id.as_str(),
+            "npc_trade",
+            format!("{npc_id}:armor").as_str(),
+            format!("{npc_name}压箱底留下的一件护身装备。").as_str(),
+        ),
+    ]
+}
+
+pub(super) fn build_bootstrapped_trade_consumable_item(
+    item_id: &str,
+    name: &str,
+    npc_name: &str,
+    world_type: Option<&str>,
+) -> Value {
+    json!({
+        "id": item_id,
+        "category": "消耗品",
+        "name": name,
+        "description": format!("{npc_name}常备的一份行路补给。"),
+        "quantity": 2,
+        "rarity": "uncommon",
+        "tags": if world_type == Some("XIANXIA") {
+            vec!["mana", "support", "trade"]
+        } else {
+            vec!["mana", "support", "trade"]
+        },
+        "useProfile": {
+            "hpRestore": 0,
+            "manaRestore": 10,
+            "cooldownReduction": 0,
+            "buildBuffs": []
+        },
+        "runtimeMetadata": {
+            "origin": "procedural",
+            "generationChannel": "npc_trade",
+            "seedKey": format!("{item_id}:seed"),
+            "sourceReason": format!("{npc_name}把最常用的补给拿出来做成了交易库存。"),
+            "storyFingerprint": {
+                "relatedScarIds": [format!("scar:npc_trade:{item_id}")],
+                "relatedThreadIds": [],
+                "visibleClue": format!("{npc_name}随身药囊里最顺手的一味补给。"),
+                "witnessMark": "药包封口处还留着反复拆开的折痕。",
+                "unresolvedQuestion": "这份补给之前究竟替谁留着。"
+            }
+        }
+    })
+}
+
+pub(super) fn attach_generated_trade_metadata(
+    mut item: Value,
+    item_id: &str,
+    generation_channel: &str,
+    seed_key: &str,
+    source_reason: &str,
+) -> Value {
+    let item_name = read_inventory_item_name(&item);
+    let entry = ensure_json_object(&mut item);
+    entry.insert("id".to_string(), Value::String(item_id.to_string()));
+    entry.insert(
+        "runtimeMetadata".to_string(),
+        json!({
+            "origin": "procedural",
+            "generationChannel": generation_channel,
+            "seedKey": seed_key,
+            "sourceReason": source_reason,
+            "storyFingerprint": {
+                "relatedScarIds": [format!("scar:{generation_channel}:{seed_key}")],
+                "relatedThreadIds": [],
+                "visibleClue": format!("{item_name}上保留着反复流转留下的使用痕迹。"),
+                "witnessMark": "表面仍残留旧主人长期携带的磨损。",
+                "unresolvedQuestion": format!("{item_name}最初为什么会落到这名 NPC 手里。"),
+            }
+        }),
+    );
+    item
+}
+
+pub(super) fn read_current_npc_inventory_item<'a>(
+    game_state: &'a Value,
+    item_id: &str,
+) -> Option<&'a Value> {
+    current_npc_inventory_items(game_state)
+        .into_iter()
+        .find(|item| read_optional_string_field(item, "id").as_deref() == Some(item_id))
+}
+
+pub(super) fn adjust_current_npc_affinity(
+    game_state: &mut Value,
+    delta: i32,
+) -> Option<(String, i32, i32)> {
+    let npc_id = current_encounter_id(game_state)?;
+    let npc_name = current_encounter_name(game_state);
+    let state = ensure_npc_state_object(game_state, npc_id.as_str(), npc_name.as_str());
+    let previous_affinity = state
+        .get("affinity")
+        .and_then(Value::as_i64)
+        .and_then(|value| i32::try_from(value).ok())
+        .unwrap_or(0);
+    let next_affinity = (previous_affinity + delta).clamp(-100, 100);
+    state.insert("affinity".to_string(), json!(next_affinity));
+    state
+        .entry("recruited".to_string())
+        .or_insert(Value::Bool(false));
+
+    Some((npc_id, previous_affinity, next_affinity))
+}
+
+pub(super) fn read_current_npc_state_i32_field(game_state: &Value, key: &str) -> Option<i32> {
+    let npc_id = current_encounter_id(game_state)?;
+    let npc_name = current_encounter_name(game_state);
+    resolve_current_encounter_npc_state(game_state, npc_id.as_str(), npc_name.as_str())
+        .and_then(|state| read_i32_field(state, key))
+}
+
+pub(super) fn read_current_npc_state_bool_field(game_state: &Value, key: &str) -> Option<bool> {
+    let npc_id = current_encounter_id(game_state)?;
+    let npc_name = current_encounter_name(game_state);
+    resolve_current_encounter_npc_state(game_state, npc_id.as_str(), npc_name.as_str())
+        .and_then(|state| read_bool_field(state, key))
+}
+
+pub(super) fn write_current_npc_state_i32_field(game_state: &mut Value, key: &str, value: i32) {
+    let Some(npc_id) = current_encounter_id(game_state) else {
+        return;
+    };
+    let npc_name = current_encounter_name(game_state);
+    let state = ensure_npc_state_object(game_state, npc_id.as_str(), npc_name.as_str());
+    state.insert(key.to_string(), json!(value));
+}
+
+pub(super) fn write_current_npc_state_bool_field(game_state: &mut Value, key: &str, value: bool) {
+    let Some(npc_id) = current_encounter_id(game_state) else {
+        return;
+    };
+    let npc_name = current_encounter_name(game_state);
+    let state = ensure_npc_state_object(game_state, npc_id.as_str(), npc_name.as_str());
+    state.insert(key.to_string(), Value::Bool(value));
+}
+
+pub(super) fn set_current_npc_recruited(
+    game_state: &mut Value,
+    recruited: bool,
+) -> Option<(i32, i32)> {
+    let npc_id = current_encounter_id(game_state)?;
+    let npc_name = current_encounter_name(game_state);
+    let state = ensure_npc_state_object(game_state, npc_id.as_str(), npc_name.as_str());
+    let previous_affinity = state
+        .get("affinity")
+        .and_then(Value::as_i64)
+        .and_then(|value| i32::try_from(value).ok())
+        .unwrap_or(0);
+    let next_affinity = previous_affinity.max(60);
+    state.insert("affinity".to_string(), json!(next_affinity));
+    state.insert("recruited".to_string(), Value::Bool(recruited));
+
+    Some((previous_affinity, next_affinity))
+}
+
+pub(super) fn read_current_npc_affinity(game_state: &Value) -> i32 {
+    let Some(npc_id) = current_encounter_id(game_state) else {
+        return 0;
+    };
+    let npc_name = current_encounter_name(game_state);
+    resolve_current_encounter_npc_state(game_state, npc_id.as_str(), npc_name.as_str())
+        .and_then(|state| read_i32_field(state, "affinity"))
+        .unwrap_or(0)
+}
+
+pub(super) fn ensure_npc_state_object<'a>(
+    game_state: &'a mut Value,
+    npc_id: &str,
+    npc_name: &str,
+) -> &'a mut Map<String, Value> {
+    let root = ensure_json_object(game_state);
+    let npc_states = root
+        .entry("npcStates".to_string())
+        .or_insert_with(|| Value::Object(Map::new()));
+    if !npc_states.is_object() {
+        *npc_states = Value::Object(Map::new());
+    }
+    let states = npc_states
+        .as_object_mut()
+        .expect("npcStates should be object");
+    let existing_key = if states.contains_key(npc_id) {
+        npc_id.to_string()
+    } else if states.contains_key(npc_name) {
+        npc_name.to_string()
+    } else {
+        npc_id.to_string()
+    };
+    let state = states
+        .entry(existing_key)
+        .or_insert_with(|| Value::Object(Map::new()));
+    if !state.is_object() {
+        *state = Value::Object(Map::new());
+    }
+    state.as_object_mut().expect("npc state should be object")
+}
+
+pub(super) fn mark_current_npc_first_meaningful_contact_resolved(game_state: &mut Value) {
+    write_current_npc_state_bool_field(game_state, "firstMeaningfulContactResolved", true);
+}
+
+pub(super) fn ensure_current_npc_inventory_array<'a>(
+    game_state: &'a mut Value,
+) -> Option<&'a mut Vec<Value>> {
+    let npc_id = current_encounter_id(game_state)?;
+    let npc_name = current_encounter_name(game_state);
+    let state = ensure_npc_state_object(game_state, npc_id.as_str(), npc_name.as_str());
+    let inventory = state
+        .entry("inventory".to_string())
+        .or_insert_with(|| Value::Array(Vec::new()));
+    if !inventory.is_array() {
+        *inventory = Value::Array(Vec::new());
+    }
+    inventory.as_array_mut()
+}
+
+pub(super) fn add_current_npc_inventory_items(game_state: &mut Value, additions: Vec<Value>) {
+    if additions.is_empty() {
+        return;
+    }
+    let Some(items) = ensure_current_npc_inventory_array(game_state) else {
+        return;
+    };
+    for addition in additions {
+        let Some(add_id) = read_optional_string_field(&addition, "id") else {
+            continue;
+        };
+        let add_quantity = read_i32_field(&addition, "quantity").unwrap_or(1).max(1);
+        if let Some(existing) = items
+            .iter_mut()
+            .find(|item| read_optional_string_field(item, "id").as_deref() == Some(add_id.as_str()))
+        {
+            let next_quantity =
+                read_i32_field(existing, "quantity").unwrap_or(0).max(0) + add_quantity;
+            if let Some(existing_object) = existing.as_object_mut() {
+                existing_object.insert("quantity".to_string(), json!(next_quantity));
+            }
+            continue;
+        }
+        items.push(addition);
+    }
+}
+
+pub(super) fn remove_current_npc_inventory_item(
+    game_state: &mut Value,
+    item_id: &str,
+    quantity: i32,
+) {
+    if quantity <= 0 {
+        return;
+    }
+    let Some(items) = ensure_current_npc_inventory_array(game_state) else {
+        return;
+    };
+    let Some(index) = items
+        .iter()
+        .position(|entry| read_optional_string_field(entry, "id").as_deref() == Some(item_id))
+    else {
+        return;
+    };
+    let current_quantity = read_i32_field(&items[index], "quantity")
+        .unwrap_or(0)
+        .max(0);
+    let next_quantity = current_quantity - quantity;
+    if next_quantity <= 0 {
+        items.remove(index);
+        return;
+    }
+    if let Some(entry) = items[index].as_object_mut() {
+        entry.insert("quantity".to_string(), json!(next_quantity));
+    }
+}

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

@@ -0,0 +1,398 @@
+use super::*;
+
+pub(super) fn resolve_npc_preview_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let npc_name = current_encounter_name(game_state);
+    write_bool_field(game_state, "npcInteractionActive", true);
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text("转向眼前角色", request),
+        result_text: format!("{npc_name} 注意到了你的靠近，正在等你先把话说出来。"),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: vec![build_status_patch(game_state)],
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_npc_affinity_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+    default_action_text: &str,
+    affinity_delta: i32,
+    fallback_result_text: &str,
+) -> Result<StoryResolution, String> {
+    write_bool_field(game_state, "npcInteractionActive", true);
+    let affinity_patch = adjust_current_npc_affinity(game_state, affinity_delta).map(
+        |(npc_id, previous_affinity, next_affinity)| RuntimeStoryPatch::NpcAffinityChanged {
+            npc_id,
+            previous_affinity,
+            next_affinity,
+        },
+    );
+    let mut patches = Vec::new();
+    if let Some(patch) = affinity_patch {
+        patches.push(patch);
+    }
+    patches.push(build_status_patch(game_state));
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(default_action_text, request),
+        result_text: fallback_result_text.to_string(),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches,
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_npc_chat_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let chatted_count = read_current_npc_state_i32_field(game_state, "chattedCount").unwrap_or(0);
+    let affinity_gain = (6 - chatted_count).max(2);
+    let result_text = format!(
+        "{} 愿意把话接下去，态度比刚才明显松动了一些。当前关系推进了 {} 点。",
+        current_encounter_name(game_state),
+        affinity_gain
+    );
+    let mut resolution = resolve_npc_affinity_action(
+        game_state,
+        request,
+        "继续交谈",
+        affinity_gain,
+        result_text.as_str(),
+    )?;
+    write_current_npc_state_i32_field(game_state, "chattedCount", chatted_count.saturating_add(1));
+    write_current_npc_state_bool_field(game_state, "firstMeaningfulContactResolved", true);
+    resolution.action_text = format!("继续和{}交谈", current_encounter_name(game_state));
+    Ok(resolution)
+}
+
+pub(super) fn resolve_npc_help_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    if read_current_npc_state_bool_field(game_state, "helpUsed").unwrap_or(false) {
+        return Err("当前 NPC 的一次性援手已经用完了".to_string());
+    }
+
+    restore_player_resource(game_state, 10, 8);
+    write_current_npc_state_bool_field(game_state, "helpUsed", true);
+    resolve_npc_affinity_action(
+        game_state,
+        request,
+        &format!("向{}请求援手", current_encounter_name(game_state)),
+        4,
+        &format!(
+            "{} 给了你一次及时支援，你的状态暂时稳住了，关系也顺势拉近了一点。",
+            current_encounter_name(game_state)
+        ),
+    )
+}
+
+pub(super) fn resolve_npc_battle_entry_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+    function_id: &str,
+) -> Result<StoryResolution, String> {
+    let npc_id = current_encounter_id(game_state).unwrap_or_else(|| "npc_current".to_string());
+    let npc_name = current_encounter_name(game_state);
+    let battle_mode = if function_id == "npc_spar" {
+        "spar"
+    } else {
+        "fight"
+    };
+    write_bool_field(game_state, "inBattle", true);
+    write_bool_field(game_state, "npcInteractionActive", false);
+    write_string_field(game_state, "currentBattleNpcId", npc_id.as_str());
+    write_string_field(game_state, "currentNpcBattleMode", battle_mode);
+    write_null_field(game_state, "currentNpcBattleOutcome");
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(
+            if battle_mode == "spar" {
+                "点到为止切磋"
+            } else {
+                "与对方战斗"
+            },
+            request,
+        ),
+        result_text: format!(
+            "{npc_name} 已经进入{}节奏，下一步必须按战斗动作结算。",
+            battle_mode_text(battle_mode)
+        ),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: vec![build_status_patch(game_state)],
+        battle: Some(RuntimeBattlePresentation {
+            target_id: Some(npc_id),
+            target_name: Some(npc_name),
+            damage_dealt: None,
+            damage_taken: None,
+            outcome: Some("ongoing".to_string()),
+        }),
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_npc_recruit_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let npc_id = current_encounter_id(game_state).unwrap_or_else(|| "npc_current".to_string());
+    let npc_name = current_encounter_name(game_state);
+    let current_affinity = read_current_npc_affinity(game_state);
+    if read_current_npc_state_bool_field(game_state, "recruited").unwrap_or(false) {
+        return Err("当前 NPC 已经处于已招募状态".to_string());
+    }
+    if current_affinity < 60 {
+        return Err("当前关系还没达到招募阈值，暂时不能邀请入队".to_string());
+    }
+
+    let release_npc_id = request
+        .action
+        .payload
+        .as_ref()
+        .and_then(|payload| read_optional_string_field(payload, "releaseNpcId"));
+    let released_companion_name = recruit_companion_to_party(
+        game_state,
+        npc_id.as_str(),
+        current_affinity,
+        release_npc_id.as_deref(),
+    )?;
+    let affinity_patch =
+        set_current_npc_recruited(game_state, true).map(|(previous_affinity, next_affinity)| {
+            RuntimeStoryPatch::NpcAffinityChanged {
+                npc_id: npc_id.clone(),
+                previous_affinity,
+                next_affinity,
+            }
+        });
+    write_current_npc_state_bool_field(game_state, "firstMeaningfulContactResolved", true);
+    write_bool_field(game_state, "npcInteractionActive", false);
+    clear_encounter_only(game_state);
+    write_null_field(game_state, "currentNpcBattleMode");
+    write_null_field(game_state, "currentNpcBattleOutcome");
+    write_bool_field(game_state, "inBattle", false);
+
+    let mut patches = Vec::new();
+    if let Some(patch) = affinity_patch {
+        patches.push(patch);
+    }
+    patches.push(build_status_patch(game_state));
+    patches.push(RuntimeStoryPatch::EncounterChanged { encounter_id: None });
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("邀请{npc_name}加入队伍"), request),
+        result_text: match released_companion_name {
+            Some(released_name) => format!(
+                "{npc_name} 接受了你的邀请，你先让 {released_name} 暂时离队，把位置腾给了新的同行者。"
+            ),
+            None => format!("{npc_name} 接受了你的邀请，正式进入了同行队伍。"),
+        },
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches,
+        battle: None,
+        toast: Some(format!("{npc_name} 已加入队伍")),
+    })
+}
+
+/// 先按 NPC 当前遭遇态结算简化版买卖逻辑，保持与 Node compat 一致的字段写回，
+/// 后续再由真相态 inventory / runtime-item reducer 接管。
+pub(super) fn resolve_npc_trade_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let (_npc_id, npc_name) = current_npc_trade_context(game_state)?;
+    let payload = request.action.payload.as_ref();
+    let mode = payload
+        .and_then(|value| read_optional_string_field(value, "mode"))
+        .ok_or_else(|| "npc_trade 缺少合法 mode，需为 buy 或 sell".to_string())?;
+    if mode != "buy" && mode != "sell" {
+        return Err("npc_trade 缺少合法 mode，需为 buy 或 sell".to_string());
+    }
+    let item_id = payload
+        .and_then(|value| {
+            read_optional_string_field(value, "itemId")
+                .or_else(|| read_optional_string_field(value, "selectedNpcItemId"))
+                .or_else(|| read_optional_string_field(value, "selectedPlayerItemId"))
+        })
+        .or_else(|| request.action.target_id.clone())
+        .ok_or_else(|| "npc_trade 缺少 itemId".to_string())?;
+    let quantity = payload
+        .and_then(|value| read_i32_field(value, "quantity"))
+        .unwrap_or(1)
+        .max(1);
+
+    if mode == "buy" {
+        let npc_item = read_current_npc_inventory_item(game_state, item_id.as_str())
+            .cloned()
+            .ok_or_else(|| "目标商品不存在或库存不足。".to_string())?;
+        let available_quantity = read_i32_field(&npc_item, "quantity").unwrap_or(0).max(0);
+        if available_quantity < quantity {
+            return Err("目标商品不存在或库存不足。".to_string());
+        }
+        let total_price = npc_purchase_price(&npc_item, read_current_npc_affinity(game_state))
+            .saturating_mul(quantity);
+        let player_currency = read_i32_field(game_state, "playerCurrency").unwrap_or(0);
+        if player_currency < total_price {
+            return Err("当前钱币不足，无法完成购买。".to_string());
+        }
+
+        write_i32_field(game_state, "playerCurrency", player_currency - total_price);
+        add_player_inventory_items(
+            game_state,
+            vec![clone_inventory_item_with_quantity(&npc_item, quantity)],
+        );
+        remove_current_npc_inventory_item(game_state, item_id.as_str(), quantity);
+        mark_current_npc_first_meaningful_contact_resolved(game_state);
+
+        let item_name = read_inventory_item_name(&npc_item);
+        return Ok(StoryResolution {
+            action_text: resolve_action_text(
+                &format!(
+                    "从{}手里买下{}{}",
+                    npc_name,
+                    item_name,
+                    trade_quantity_suffix(quantity)
+                ),
+                request,
+            ),
+            result_text: format!(
+                "{}收下了{}，把{}{}卖给了你。",
+                npc_name,
+                format_currency_text(
+                    total_price,
+                    read_optional_string_field(game_state, "worldType").as_deref()
+                ),
+                item_name,
+                trade_quantity_suffix(quantity)
+            ),
+            story_text: None,
+            presentation_options: None,
+            saved_current_story: None,
+            patches: Vec::new(),
+            battle: None,
+            toast: None,
+        });
+    }
+
+    let player_item = find_player_inventory_entry(game_state, item_id.as_str())
+        .cloned()
+        .ok_or_else(|| "背包里没有足够数量的目标物品。".to_string())?;
+    let available_quantity = read_i32_field(&player_item, "quantity").unwrap_or(0).max(0);
+    if available_quantity < quantity {
+        return Err("背包里没有足够数量的目标物品。".to_string());
+    }
+    let total_price = npc_buyback_price(&player_item, read_current_npc_affinity(game_state))
+        .saturating_mul(quantity);
+    let player_currency = read_i32_field(game_state, "playerCurrency").unwrap_or(0);
+    write_i32_field(
+        game_state,
+        "playerCurrency",
+        player_currency.saturating_add(total_price),
+    );
+    remove_player_inventory_item(game_state, item_id.as_str(), quantity);
+    add_current_npc_inventory_items(
+        game_state,
+        vec![clone_inventory_item_with_quantity(&player_item, quantity)],
+    );
+    mark_current_npc_first_meaningful_contact_resolved(game_state);
+
+    let item_name = read_inventory_item_name(&player_item);
+    Ok(StoryResolution {
+        action_text: resolve_action_text(
+            &format!(
+                "把{}{}卖给{}",
+                item_name,
+                trade_quantity_suffix(quantity),
+                npc_name
+            ),
+            request,
+        ),
+        result_text: format!(
+            "{}收下了{}{}，付给你{}。",
+            npc_name,
+            item_name,
+            trade_quantity_suffix(quantity),
+            format_currency_text(
+                total_price,
+                read_optional_string_field(game_state, "worldType").as_deref()
+            )
+        ),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: Vec::new(),
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_npc_gift_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let (npc_id, npc_name) = current_npc_trade_context(game_state)?;
+    let item_id = request
+        .action
+        .payload
+        .as_ref()
+        .and_then(|payload| read_optional_string_field(payload, "itemId"))
+        .or_else(|| request.action.target_id.clone())
+        .ok_or_else(|| "npc_gift 缺少 itemId".to_string())?;
+    let gift_item = find_player_inventory_entry(game_state, item_id.as_str())
+        .cloned()
+        .ok_or_else(|| "背包里没有这件可赠送的物品。".to_string())?;
+    if read_i32_field(&gift_item, "quantity").unwrap_or(0) <= 0 {
+        return Err("背包里没有这件可赠送的物品。".to_string());
+    }
+
+    let previous_affinity = read_current_npc_affinity(game_state);
+    let affinity_gain = resolve_npc_gift_affinity_gain(&gift_item);
+    let next_affinity = (previous_affinity + affinity_gain).clamp(-100, 100);
+    remove_player_inventory_item(game_state, item_id.as_str(), 1);
+    add_current_npc_inventory_items(
+        game_state,
+        vec![clone_inventory_item_with_quantity(&gift_item, 1)],
+    );
+    write_current_npc_state_i32_field(game_state, "affinity", next_affinity);
+    let next_gifts_given =
+        read_current_npc_state_i32_field(game_state, "giftsGiven").unwrap_or(0) + 1;
+    write_current_npc_state_i32_field(game_state, "giftsGiven", next_gifts_given);
+    mark_current_npc_first_meaningful_contact_resolved(game_state);
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(
+            &format!("把{}赠给{}", read_inventory_item_name(&gift_item), npc_name),
+            request,
+        ),
+        result_text: build_npc_gift_result_text(
+            npc_name.as_str(),
+            &gift_item,
+            affinity_gain,
+            next_affinity,
+        ),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: vec![RuntimeStoryPatch::NpcAffinityChanged {
+            npc_id,
+            previous_affinity,
+            next_affinity,
+        }],
+        battle: None,
+        toast: None,
+    })
+}

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

@@ -0,0 +1,734 @@
+use super::*;
+
+pub(super) fn build_runtime_story_state_response(
+    requested_session_id: &str,
+    client_version: Option<u32>,
+    mut snapshot: RuntimeStorySnapshotPayload,
+) -> RuntimeStoryActionResponse {
+    ensure_runtime_story_bridge_state(&mut snapshot.game_state);
+    let session_id = read_runtime_session_id(&snapshot.game_state)
+        .unwrap_or_else(|| requested_session_id.to_string());
+    let options =
+        build_runtime_story_options(snapshot.current_story.as_ref(), &snapshot.game_state);
+    let story_text = read_story_text(snapshot.current_story.as_ref())
+        .unwrap_or_else(|| build_fallback_story_text(&snapshot.game_state));
+    let server_version = read_u32_field(&snapshot.game_state, "runtimeActionVersion")
+        .or(client_version)
+        .unwrap_or(0);
+
+    build_runtime_story_action_response(RuntimeStoryActionResponseParts {
+        requested_session_id: session_id,
+        server_version,
+        snapshot,
+        action_text: String::new(),
+        result_text: String::new(),
+        story_text,
+        options,
+        patches: Vec::new(),
+        toast: None,
+        battle: None,
+    })
+}
+
+pub(super) fn build_runtime_story_action_response(
+    parts: RuntimeStoryActionResponseParts,
+) -> RuntimeStoryActionResponse {
+    let session_id = read_runtime_session_id(&parts.snapshot.game_state)
+        .unwrap_or_else(|| parts.requested_session_id);
+
+    RuntimeStoryActionResponse {
+        session_id,
+        server_version: parts.server_version,
+        view_model: build_runtime_story_view_model(&parts.snapshot.game_state, &parts.options),
+        presentation: RuntimeStoryPresentation {
+            action_text: parts.action_text,
+            result_text: parts.result_text,
+            story_text: parts.story_text,
+            options: parts.options,
+            toast: parts.toast,
+            battle: parts.battle,
+        },
+        patches: parts.patches,
+        snapshot: parts.snapshot,
+    }
+}
+
+pub(super) fn build_dialogue_current_story(
+    npc_name: &str,
+    text: &str,
+    deferred_options: &[RuntimeStoryOptionView],
+) -> Value {
+    let continue_option = build_continue_adventure_runtime_story_option();
+    // 对齐 Node 旧 currentStory：先展示单轮对话，只把真实下一步选项压到 deferredOptions。
+    json!({
+        "text": text,
+        "options": vec![build_story_option_from_runtime_option(&continue_option)],
+        "displayMode": "dialogue",
+        "dialogue": parse_dialogue_turns(text, npc_name),
+        "streaming": false,
+        "deferredOptions": deferred_options
+            .iter()
+            .map(build_story_option_from_runtime_option)
+            .collect::<Vec<_>>(),
+    })
+}
+
+pub(super) fn build_continue_adventure_runtime_story_option() -> RuntimeStoryOptionView {
+    build_static_runtime_story_option(CONTINUE_ADVENTURE_FUNCTION_ID, "继续推进冒险", "story")
+}
+
+pub(super) fn parse_dialogue_turns(text: &str, npc_name: &str) -> Vec<Value> {
+    let mut turns = Vec::new();
+    for raw_line in text.lines() {
+        let line = raw_line.trim();
+        if line.is_empty() {
+            continue;
+        }
+        if let Some(turn) = parse_dialogue_line(line, npc_name) {
+            turns.push(turn);
+        }
+    }
+
+    if turns.is_empty() && !text.trim().is_empty() {
+        turns.push(json!({
+            "speaker": "npc",
+            "speakerName": npc_name,
+            "text": text.trim(),
+        }));
+    }
+
+    turns
+}
+
+pub(super) fn parse_dialogue_line(line: &str, npc_name: &str) -> Option<Value> {
+    let delimiter_index = line.find('：').or_else(|| line.find(':'))?;
+    let speaker_name = line[..delimiter_index].trim();
+    let content_start = delimiter_index + line[delimiter_index..].chars().next()?.len_utf8();
+    let content = line[content_start..].trim();
+    if content.is_empty() {
+        return None;
+    }
+
+    if speaker_name == "你" {
+        return Some(json!({
+            "speaker": "player",
+            "text": content,
+        }));
+    }
+
+    if speaker_name == npc_name {
+        return Some(json!({
+            "speaker": "npc",
+            "speakerName": npc_name,
+            "text": content,
+        }));
+    }
+
+    Some(json!({
+        "speaker": "companion",
+        "speakerName": speaker_name,
+        "text": content,
+    }))
+}
+
+pub(super) fn build_runtime_story_options(
+    current_story: Option<&Value>,
+    game_state: &Value,
+) -> Vec<RuntimeStoryOptionView> {
+    if let Some(story) = current_story {
+        let prefers_deferred = read_required_string_field(story, "displayMode")
+            .is_some_and(|value| value == "dialogue")
+            && !read_array_field(story, "deferredOptions").is_empty();
+
+        let source = if prefers_deferred {
+            read_array_field(story, "deferredOptions")
+        } else {
+            read_array_field(story, "options")
+        };
+
+        let compiled = source
+            .into_iter()
+            .filter_map(build_runtime_story_option_from_story_option)
+            .collect::<Vec<_>>();
+
+        if !compiled.is_empty() {
+            return compiled;
+        }
+    }
+
+    build_fallback_runtime_story_options(game_state)
+}
+
+pub(super) fn build_fallback_runtime_story_options(
+    game_state: &Value,
+) -> Vec<RuntimeStoryOptionView> {
+    if read_bool_field(game_state, "inBattle").unwrap_or(false) {
+        return build_battle_runtime_story_options(game_state);
+    }
+
+    let encounter = read_object_field(game_state, "currentEncounter");
+    if let Some(encounter) = encounter {
+        if matches!(
+            read_required_string_field(encounter, "kind").as_deref(),
+            Some("npc")
+        ) {
+            let interaction_active =
+                read_bool_field(game_state, "npcInteractionActive").unwrap_or(false);
+            let npc_id = read_required_string_field(encounter, "id")
+                .unwrap_or_else(|| "npc_current".to_string());
+            if let Some(active_quest) = find_active_quest_for_issuer(game_state, npc_id.as_str()) {
+                if read_optional_string_field(active_quest, "status")
+                    .is_some_and(|status| status == "completed")
+                {
+                    return vec![
+                        build_npc_runtime_story_option_with_quest(
+                            "npc_quest_turn_in",
+                            &format!("向{}交付委托", current_encounter_name(game_state)),
+                            &npc_id,
+                            "quest_turn_in",
+                            read_optional_string_field(active_quest, "id"),
+                        ),
+                        build_npc_runtime_story_option(
+                            "npc_leave",
+                            "离开当前角色",
+                            &npc_id,
+                            "leave",
+                        ),
+                    ];
+                }
+            }
+            if interaction_active {
+                return build_active_npc_runtime_story_options(game_state, npc_id.as_str());
+            }
+
+            return vec![
+                build_npc_runtime_story_option("npc_preview_talk", "转向眼前角色", &npc_id, "chat"),
+                build_npc_runtime_story_option("npc_fight", "与对方战斗", &npc_id, "fight"),
+                build_npc_runtime_story_option("npc_leave", "离开当前角色", &npc_id, "leave"),
+            ];
+        }
+    }
+
+    vec![
+        build_static_runtime_story_option("idle_observe_signs", "观察周围迹象", "story"),
+        build_static_runtime_story_option("idle_call_out", "主动出声试探", "story"),
+        build_static_runtime_story_option("idle_rest_focus", "原地调息", "story"),
+        build_static_runtime_story_option("idle_explore_forward", "继续向前探索", "story"),
+        build_static_runtime_story_option("idle_travel_next_scene", "前往相邻场景", "story"),
+        build_static_runtime_story_option(CONTINUE_ADVENTURE_FUNCTION_ID, "继续推进冒险", "story"),
+    ]
+}
+
+pub(super) fn build_npc_runtime_story_option(
+    function_id: &str,
+    action_text: &str,
+    npc_id: &str,
+    action: &str,
+) -> RuntimeStoryOptionView {
+    RuntimeStoryOptionView {
+        interaction: Some(RuntimeStoryOptionInteraction::Npc {
+            npc_id: npc_id.to_string(),
+            action: action.to_string(),
+            quest_id: None,
+        }),
+        ..build_static_runtime_story_option(function_id, action_text, "npc")
+    }
+}
+
+pub(super) fn build_npc_runtime_story_option_with_payload(
+    function_id: &str,
+    action_text: &str,
+    npc_id: &str,
+    action: &str,
+    payload: Value,
+) -> RuntimeStoryOptionView {
+    RuntimeStoryOptionView {
+        payload: Some(payload),
+        ..build_npc_runtime_story_option(function_id, action_text, npc_id, action)
+    }
+}
+
+pub(super) fn build_npc_runtime_story_option_with_quest(
+    function_id: &str,
+    action_text: &str,
+    npc_id: &str,
+    action: &str,
+    quest_id: Option<String>,
+) -> RuntimeStoryOptionView {
+    RuntimeStoryOptionView {
+        interaction: Some(RuntimeStoryOptionInteraction::Npc {
+            npc_id: npc_id.to_string(),
+            action: action.to_string(),
+            quest_id,
+        }),
+        ..build_static_runtime_story_option(function_id, action_text, "npc")
+    }
+}
+
+/// 对齐 Node 旧 compat 入口顺序，在 NPC 交互态下统一补齐交易、赠礼、委托与招募入口。
+pub(super) fn build_active_npc_runtime_story_options(
+    game_state: &Value,
+    npc_id: &str,
+) -> Vec<RuntimeStoryOptionView> {
+    let mut options = vec![
+        build_npc_runtime_story_option("npc_chat", "继续交谈", npc_id, "chat"),
+        build_npc_help_runtime_story_option(game_state, npc_id),
+        build_npc_runtime_story_option("npc_spar", "点到为止切磋", npc_id, "spar"),
+        build_npc_runtime_story_option("npc_fight", "与对方战斗", npc_id, "fight"),
+    ];
+
+    if current_npc_inventory_items(game_state)
+        .iter()
+        .any(|item| read_i32_field(item, "quantity").unwrap_or(0) > 0)
+    {
+        options.push(build_npc_runtime_story_option(
+            "npc_trade",
+            "交易",
+            npc_id,
+            "trade",
+        ));
+    }
+
+    if has_giftable_player_inventory(game_state) {
+        options.push(build_npc_runtime_story_option(
+            "npc_gift",
+            "赠送礼物",
+            npc_id,
+            "gift",
+        ));
+    }
+
+    let active_quest = find_active_quest_for_issuer(game_state, npc_id);
+    if let Some(active_quest) = active_quest {
+        let can_turn_in = read_optional_string_field(active_quest, "status")
+            .is_some_and(|status| status == "completed" || status == "ready_to_turn_in");
+        if can_turn_in {
+            options.push(build_npc_runtime_story_option_with_quest(
+                "npc_quest_turn_in",
+                &format!("向{}交付委托", current_encounter_name(game_state)),
+                npc_id,
+                "quest_turn_in",
+                read_optional_string_field(active_quest, "id"),
+            ));
+        }
+    } else {
+        options.push(build_npc_runtime_story_option(
+            "npc_quest_accept",
+            "接下委托",
+            npc_id,
+            "quest_accept",
+        ));
+    }
+
+    if read_current_npc_affinity(game_state) >= 60
+        && !read_current_npc_state_bool_field(game_state, "recruited").unwrap_or(false)
+    {
+        options.push(build_npc_runtime_story_option(
+            "npc_recruit",
+            "邀请同行",
+            npc_id,
+            "recruit",
+        ));
+    }
+
+    options.push(build_npc_runtime_story_option(
+        "npc_leave",
+        "离开当前角色",
+        npc_id,
+        "leave",
+    ));
+    options
+}
+
+pub(super) fn build_npc_help_runtime_story_option(
+    game_state: &Value,
+    npc_id: &str,
+) -> RuntimeStoryOptionView {
+    if read_current_npc_state_bool_field(game_state, "helpUsed").unwrap_or(false) {
+        return build_disabled_runtime_story_option(
+            "npc_help",
+            "请求援手",
+            "npc",
+            None,
+            "当前 NPC 的一次性援手已经用完了。",
+            None,
+        );
+    }
+    build_npc_runtime_story_option("npc_help", "请求援手", npc_id, "help")
+}
+
+pub(super) fn current_encounter_npc_quest_context(
+    game_state: &Value,
+) -> Result<CurrentEncounterNpcQuestContext, String> {
+    let encounter = read_object_field(game_state, "currentEncounter")
+        .ok_or_else(|| "当前不在可结算的 NPC 委托态。".to_string())?;
+    let kind = read_required_string_field(encounter, "kind")
+        .ok_or_else(|| "当前不在可结算的 NPC 委托态。".to_string())?;
+    if kind != "npc" {
+        return Err("当前不在可结算的 NPC 委托态。".to_string());
+    }
+
+    let npc_name = read_optional_string_field(encounter, "npcName")
+        .or_else(|| read_optional_string_field(encounter, "name"))
+        .unwrap_or_else(|| "当前角色".to_string());
+    let npc_id = read_optional_string_field(encounter, "id").unwrap_or_else(|| npc_name.clone());
+
+    if resolve_current_encounter_npc_state(game_state, npc_id.as_str(), npc_name.as_str()).is_none()
+    {
+        return Err("当前 NPC 状态不存在，无法处理委托。".to_string());
+    }
+
+    Ok(CurrentEncounterNpcQuestContext { npc_id, npc_name })
+}
+
+pub(super) fn read_pending_quest_offer_context(
+    current_story: Option<&Value>,
+    npc_key: &str,
+) -> Option<PendingQuestOfferContext> {
+    let current_story = current_story?;
+    let npc_chat_state = read_object_field(current_story, "npcChatState")?;
+    let pending_offer = read_object_field(npc_chat_state, "pendingQuestOffer")?;
+    let quest = read_object_field(pending_offer, "quest")?.clone();
+    let quest_id = read_optional_string_field(&quest, "id")?;
+    let pending_npc_id = read_optional_string_field(npc_chat_state, "npcId");
+    let issuer_npc_id = read_optional_string_field(&quest, "issuerNpcId");
+    if pending_npc_id
+        .as_deref()
+        .is_some_and(|value| value != npc_key)
+    {
+        return None;
+    }
+    if issuer_npc_id
+        .as_deref()
+        .is_some_and(|value| value != npc_key)
+    {
+        return None;
+    }
+
+    Some(PendingQuestOfferContext {
+        dialogue: read_array_field(current_story, "dialogue")
+            .into_iter()
+            .cloned()
+            .collect(),
+        turn_count: read_i32_field(npc_chat_state, "turnCount").unwrap_or(0),
+        custom_input_placeholder: read_optional_string_field(
+            npc_chat_state,
+            "customInputPlaceholder",
+        )
+        .unwrap_or_else(|| "输入你想对 TA 说的话".to_string()),
+        quest,
+        quest_id,
+        intro_text: read_optional_string_field(pending_offer, "introText"),
+    })
+}
+
+pub(super) fn build_quest_offer_dialogue_text(npc_name: &str, quest: &Value) -> String {
+    let summary_text = read_optional_string_field(quest, "summary")
+        .or_else(|| read_optional_string_field(quest, "description"))
+        .unwrap_or_default();
+    if summary_text.is_empty() {
+        return format!(
+            "{npc_name}沉吟了片刻，像是终于把真正想托付的事说了出来。如果你愿意，我想把眼前这件事正式交给你。"
+        );
+    }
+    format!(
+        "{npc_name}沉吟了片刻，像是终于把真正想托付的事说了出来。如果你愿意，我想把这件事正式交给你：{summary_text}"
+    )
+}
+
+pub(super) fn append_dialogue_turns(existing: &[Value], additions: Vec<Value>) -> Vec<Value> {
+    let mut dialogue = existing.to_vec();
+    dialogue.extend(additions);
+    dialogue
+}
+
+pub(super) fn build_pending_quest_offer_options(npc_id: &str) -> Vec<RuntimeStoryOptionView> {
+    vec![
+        build_npc_runtime_story_option_with_payload(
+            "npc_chat_quest_offer_view",
+            "查看任务",
+            npc_id,
+            "quest_offer_view",
+            json!({
+                "npcChatQuestOfferAction": "view"
+            }),
+        ),
+        build_npc_runtime_story_option_with_payload(
+            "npc_chat_quest_offer_replace",
+            "更换任务",
+            npc_id,
+            "quest_offer_replace",
+            json!({
+                "npcChatQuestOfferAction": "replace"
+            }),
+        ),
+        build_npc_runtime_story_option_with_payload(
+            "npc_chat_quest_offer_abandon",
+            "放弃任务",
+            npc_id,
+            "quest_offer_abandon",
+            json!({
+                "npcChatQuestOfferAction": "abandon"
+            }),
+        ),
+    ]
+}
+
+pub(super) fn build_post_quest_offer_chat_options(npc_id: &str) -> Vec<RuntimeStoryOptionView> {
+    vec![
+        build_npc_runtime_story_option(
+            "npc_chat",
+            "那先继续聊聊你刚才没说完的部分",
+            npc_id,
+            "chat",
+        ),
+        build_npc_runtime_story_option(
+            "npc_chat",
+            "除了委托，你对眼前局势还有什么判断",
+            npc_id,
+            "chat",
+        ),
+        build_npc_runtime_story_option(
+            "npc_chat",
+            "先把这附近真正危险的地方说清楚",
+            npc_id,
+            "chat",
+        ),
+    ]
+}
+
+pub(super) fn build_post_quest_accept_chat_options(npc_id: &str) -> Vec<RuntimeStoryOptionView> {
+    vec![
+        build_npc_runtime_story_option("npc_chat", "这件事里你最担心哪一步", npc_id, "chat"),
+        build_npc_runtime_story_option("npc_chat", "我回来时你最想先知道什么", npc_id, "chat"),
+        build_npc_runtime_story_option(
+            "npc_chat",
+            "除了这份委托，你还想提醒我什么",
+            npc_id,
+            "chat",
+        ),
+    ]
+}
+
+pub(super) fn build_pending_quest_offer_story(
+    dialogue: Vec<Value>,
+    npc_id: &str,
+    npc_name: &str,
+    turn_count: i32,
+    custom_input_placeholder: &str,
+    pending_quest: Option<Value>,
+    options: &[RuntimeStoryOptionView],
+) -> Value {
+    json!({
+        "text": dialogue
+            .iter()
+            .filter_map(|entry| read_optional_string_field(entry, "text"))
+            .collect::<Vec<_>>()
+            .join("\n"),
+        "options": options.iter().map(build_story_option_from_runtime_option).collect::<Vec<_>>(),
+        "displayMode": "dialogue",
+        "dialogue": dialogue,
+        "streaming": false,
+        "npcChatState": {
+            "npcId": npc_id,
+            "npcName": npc_name,
+            "turnCount": turn_count,
+            "customInputPlaceholder": custom_input_placeholder,
+            "pendingQuestOffer": pending_quest.map(|quest| json!({ "quest": quest })),
+        }
+    })
+}
+
+pub(super) fn build_next_pending_quest_offer(
+    game_state: &Value,
+    npc_id: &str,
+    npc_name: &str,
+    previous_quest_id: Option<&str>,
+) -> Value {
+    let next_id = if previous_quest_id.is_some_and(|id| id == "quest-bridge-offer") {
+        "quest-bridge-replaced"
+    } else {
+        "quest-generated-replaced"
+    };
+    let title = if next_id == "quest-bridge-replaced" {
+        "断桥夜巡"
+    } else {
+        "新的临时委托"
+    };
+    let scene_id = read_object_field(game_state, "currentScenePreset")
+        .and_then(|scene| read_optional_string_field(scene, "id"));
+    json!({
+        "id": next_id,
+        "issuerNpcId": npc_id,
+        "issuerNpcName": npc_name,
+        "sceneId": scene_id,
+        "title": title,
+        "description": format!("{title}的详细说明。"),
+        "summary": format!("{title}的简要目标。"),
+        "objective": {
+            "kind": "talk_to_npc",
+            "requiredCount": 1
+        },
+        "progress": 0,
+        "status": "active",
+        "reward": {
+            "affinityBonus": 6,
+            "currency": 30,
+            "items": []
+        },
+        "rewardText": "完成后可以领取报酬。",
+        "steps": [{
+            "id": format!("{next_id}-step-1"),
+            "title": "查清线索",
+            "kind": "talk_to_npc",
+            "requiredCount": 1,
+            "progress": 0,
+            "revealText": "先去断桥口附近把相关线索问清楚。",
+            "completeText": "关键线索已经问清。"
+        }],
+        "activeStepId": format!("{next_id}-step-1")
+    })
+}
+
+pub(super) fn find_active_quest_for_issuer<'a>(
+    game_state: &'a Value,
+    issuer_npc_id: &str,
+) -> Option<&'a Value> {
+    read_array_field(game_state, "quests")
+        .into_iter()
+        .find(|quest| {
+            read_optional_string_field(quest, "issuerNpcId").as_deref() == Some(issuer_npc_id)
+                && read_optional_string_field(quest, "status")
+                    .is_some_and(|status| status != "turned_in")
+        })
+}
+
+pub(super) fn push_quest_record(game_state: &mut Value, quest: &Value) {
+    let root = ensure_json_object(game_state);
+    let quests = root
+        .entry("quests".to_string())
+        .or_insert_with(|| Value::Array(Vec::new()));
+    if !quests.is_array() {
+        *quests = Value::Array(Vec::new());
+    }
+    quests
+        .as_array_mut()
+        .expect("quests should be array")
+        .push(quest.clone());
+}
+
+pub(super) fn first_quest_reveal_text(quest: &Value) -> Option<String> {
+    read_array_field(quest, "steps")
+        .first()
+        .and_then(|step| read_optional_string_field(step, "revealText"))
+}
+
+pub(super) fn build_quest_accept_result_text(quest: &Value) -> String {
+    let issuer_name =
+        read_optional_string_field(quest, "issuerNpcName").unwrap_or_else(|| "对方".to_string());
+    let title = read_optional_string_field(quest, "title").unwrap_or_else(|| "委托".to_string());
+    format!("你正式接下了 {issuer_name} 的委托「{title}」，接下来可以开始推进任务目标。")
+}
+
+pub(super) fn turn_in_quest_record(
+    game_state: &mut Value,
+    issuer_npc_id: &str,
+    quest_id: &str,
+) -> Result<Value, String> {
+    let root = ensure_json_object(game_state);
+    let quests = root
+        .entry("quests".to_string())
+        .or_insert_with(|| Value::Array(Vec::new()));
+    if !quests.is_array() {
+        *quests = Value::Array(Vec::new());
+    }
+    let quests = quests.as_array_mut().expect("quests should be array");
+    let Some(index) = quests.iter().position(|quest| {
+        read_optional_string_field(quest, "id").as_deref() == Some(quest_id)
+            && read_optional_string_field(quest, "issuerNpcId").as_deref() == Some(issuer_npc_id)
+    }) else {
+        return Err("当前没有可交付的委托。".to_string());
+    };
+
+    let mut turned_in = quests[index].clone();
+    if read_optional_string_field(&turned_in, "status").as_deref() != Some("completed") {
+        return Err("这份委托还没有达到可交付状态。".to_string());
+    }
+    if let Some(object) = turned_in.as_object_mut() {
+        object.insert("status".to_string(), Value::String("turned_in".to_string()));
+        object.insert("completionNotified".to_string(), Value::Bool(true));
+        if let Some(steps) = object.get_mut("steps").and_then(Value::as_array_mut) {
+            for step in steps.iter_mut() {
+                let required_count = read_i32_field(step, "requiredCount").unwrap_or(0);
+                if let Some(step_object) = step.as_object_mut() {
+                    step_object.insert("progress".to_string(), json!(required_count.max(0)));
+                }
+            }
+        }
+    }
+    quests[index] = turned_in.clone();
+    Ok(turned_in)
+}
+
+pub(super) fn build_quest_turn_in_result_text(quest: &Value) -> String {
+    let title = read_optional_string_field(quest, "title").unwrap_or_else(|| "委托".to_string());
+    let reward_text = read_optional_string_field(quest, "rewardText")
+        .unwrap_or_else(|| "报酬已经结清。".to_string());
+    format!("你已经完成并交付了「{title}」。{reward_text}")
+}
+
+pub(super) fn apply_quest_turn_in_rewards(game_state: &mut Value, quest: &Value) {
+    let Some(reward) = read_field(quest, "reward") else {
+        return;
+    };
+
+    let currency = read_i32_field(reward, "currency").unwrap_or(0).max(0);
+    if currency > 0 {
+        add_player_currency(game_state, currency);
+    }
+
+    let reward_items = read_array_field(reward, "items")
+        .into_iter()
+        .cloned()
+        .collect::<Vec<_>>();
+    if !reward_items.is_empty() {
+        add_player_inventory_items(game_state, reward_items);
+    }
+
+    let experience = read_i32_field(reward, "experience").unwrap_or(0).max(0);
+    if experience > 0 {
+        grant_player_progression_experience(game_state, experience, "quest");
+    }
+}
+
+pub(super) fn build_legacy_current_story(
+    story_text: &str,
+    options: &[RuntimeStoryOptionView],
+) -> Value {
+    json!({
+        "text": story_text,
+        "options": options.iter().map(build_story_option_from_runtime_option).collect::<Vec<_>>(),
+        "streaming": false
+    })
+}
+
+pub(super) fn read_story_text(current_story: Option<&Value>) -> Option<String> {
+    current_story.and_then(|story| read_optional_string_field(story, "text"))
+}
+
+pub(super) fn build_fallback_story_text(game_state: &Value) -> String {
+    if read_bool_field(game_state, "inBattle").unwrap_or(false) {
+        let encounter_name = read_object_field(game_state, "currentEncounter")
+            .and_then(|encounter| read_optional_string_field(encounter, "npcName"))
+            .unwrap_or_else(|| "眼前的敌人".to_string());
+        return format!("战斗还没有结束，{encounter_name} 仍在逼你立刻做出下一步判断。");
+    }
+
+    if let Some(encounter) = read_object_field(game_state, "currentEncounter")
+        && let Some(npc_name) = read_optional_string_field(encounter, "npcName")
+    {
+        return format!("{npc_name} 正在等你表态，当前局势已经可以继续推进。");
+    }
+
+    "当前故事状态已经同步到兼容状态桥，可以继续推进这一轮运行时动作。".to_string()
+}

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

@@ -0,0 +1,234 @@
+use super::*;
+
+pub(super) fn resolve_pending_quest_offer_view_action(
+    game_state: &mut Value,
+    current_story: Option<&Value>,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let encounter = current_encounter_npc_quest_context(game_state)?;
+    let pending_offer = read_pending_quest_offer_context(current_story, encounter.npc_id.as_str())
+        .ok_or_else(|| "当前没有待处理的委托可查看。".to_string())?;
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("查看{}提出的委托", encounter.npc_name), request),
+        result_text: pending_offer.intro_text.clone().unwrap_or_else(|| {
+            build_quest_offer_dialogue_text(encounter.npc_name.as_str(), &pending_offer.quest)
+        }),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: vec![],
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_pending_quest_offer_replace_action(
+    game_state: &mut Value,
+    current_story: Option<&Value>,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let encounter = current_encounter_npc_quest_context(game_state)?;
+    let pending_offer = read_pending_quest_offer_context(current_story, encounter.npc_id.as_str())
+        .ok_or_else(|| "当前没有待处理的委托可更换。".to_string())?;
+    let next_quest = build_next_pending_quest_offer(
+        game_state,
+        encounter.npc_id.as_str(),
+        encounter.npc_name.as_str(),
+        Some(pending_offer.quest_id.as_str()),
+    );
+    let quest_text = build_quest_offer_dialogue_text(encounter.npc_name.as_str(), &next_quest);
+    let dialogue = append_dialogue_turns(
+        pending_offer.dialogue.as_slice(),
+        vec![
+            json!({
+                "speaker": "player",
+                "text": "能不能换一份更适合眼下局势的委托？"
+            }),
+            json!({
+                "speaker": "npc",
+                "speakerName": encounter.npc_name,
+                "text": quest_text,
+            }),
+        ],
+    );
+    let options = build_pending_quest_offer_options(encounter.npc_id.as_str());
+    let saved_current_story = build_pending_quest_offer_story(
+        dialogue,
+        encounter.npc_id.as_str(),
+        encounter.npc_name.as_str(),
+        pending_offer.turn_count,
+        pending_offer.custom_input_placeholder.as_str(),
+        Some(next_quest.clone()),
+        options.as_slice(),
+    );
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("请{}更换委托", encounter.npc_name), request),
+        result_text: quest_text.clone(),
+        story_text: Some(quest_text),
+        presentation_options: Some(options),
+        saved_current_story: Some(saved_current_story),
+        patches: vec![],
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_pending_quest_offer_abandon_action(
+    game_state: &mut Value,
+    current_story: Option<&Value>,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let encounter = current_encounter_npc_quest_context(game_state)?;
+    let pending_offer = read_pending_quest_offer_context(current_story, encounter.npc_id.as_str())
+        .ok_or_else(|| "当前没有待处理的委托可放弃。".to_string())?;
+    let npc_reply = format!(
+        "{}点了点头，没有继续强求，只把这份委托暂时收了回去。",
+        encounter.npc_name
+    );
+    let dialogue = append_dialogue_turns(
+        pending_offer.dialogue.as_slice(),
+        vec![
+            json!({
+                "speaker": "player",
+                "text": "这件事我先不接，咱们还是先聊别的。"
+            }),
+            json!({
+                "speaker": "npc",
+                "speakerName": encounter.npc_name,
+                "text": npc_reply,
+            }),
+        ],
+    );
+    let options = build_post_quest_offer_chat_options(encounter.npc_id.as_str());
+    let saved_current_story = build_pending_quest_offer_story(
+        dialogue,
+        encounter.npc_id.as_str(),
+        encounter.npc_name.as_str(),
+        pending_offer.turn_count,
+        pending_offer.custom_input_placeholder.as_str(),
+        None,
+        options.as_slice(),
+    );
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("暂不接受{}的委托", encounter.npc_name), request),
+        result_text: npc_reply.clone(),
+        story_text: Some(npc_reply),
+        presentation_options: Some(options),
+        saved_current_story: Some(saved_current_story),
+        patches: vec![],
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_pending_quest_accept_action(
+    game_state: &mut Value,
+    current_story: Option<&Value>,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let encounter = current_encounter_npc_quest_context(game_state)?;
+    let pending_offer = read_pending_quest_offer_context(current_story, encounter.npc_id.as_str())
+        .ok_or_else(|| "当前没有待处理的委托可接下。".to_string())?;
+    if find_active_quest_for_issuer(game_state, encounter.npc_id.as_str()).is_some() {
+        return Err("当前角色已经有未结清的委托。".to_string());
+    }
+
+    let quest = pending_offer.quest.clone();
+    push_quest_record(game_state, &quest);
+    increment_runtime_stat(game_state, "questsAccepted", 1);
+    write_current_npc_state_bool_field(game_state, "firstMeaningfulContactResolved", true);
+
+    let reply_text = first_quest_reveal_text(&quest)
+        .map(|text| format!("那就拜托你了。{text}"))
+        .unwrap_or_else(|| {
+            format!(
+                "那就拜托你了。{}",
+                read_optional_string_field(&quest, "summary")
+                    .unwrap_or_else(|| "这份委托的关键要点我已经交给你。".to_string())
+            )
+        });
+    let dialogue = append_dialogue_turns(
+        pending_offer.dialogue.as_slice(),
+        vec![
+            json!({
+                "speaker": "player",
+                "text": "这件事我愿意接下，你把关键要点交给我。"
+            }),
+            json!({
+                "speaker": "npc",
+                "speakerName": encounter.npc_name,
+                "text": reply_text,
+            }),
+        ],
+    );
+    let options = build_post_quest_accept_chat_options(encounter.npc_id.as_str());
+    let saved_current_story = build_pending_quest_offer_story(
+        dialogue,
+        encounter.npc_id.as_str(),
+        encounter.npc_name.as_str(),
+        pending_offer.turn_count,
+        pending_offer.custom_input_placeholder.as_str(),
+        None,
+        options.as_slice(),
+    );
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("接下{}的委托", encounter.npc_name), request),
+        result_text: build_quest_accept_result_text(&quest),
+        story_text: Some(
+            saved_current_story["text"]
+                .as_str()
+                .unwrap_or_default()
+                .to_string(),
+        ),
+        presentation_options: Some(options),
+        saved_current_story: Some(saved_current_story),
+        patches: vec![],
+        battle: None,
+        toast: None,
+    })
+}
+
+pub(super) fn resolve_pending_quest_turn_in_action(
+    game_state: &mut Value,
+    request: &RuntimeStoryActionRequest,
+) -> Result<StoryResolution, String> {
+    let encounter = current_encounter_npc_quest_context(game_state)?;
+    let quest_id = request
+        .action
+        .payload
+        .as_ref()
+        .and_then(|payload| read_optional_string_field(payload, "questId"))
+        .or_else(|| request.action.target_id.clone())
+        .or_else(|| {
+            find_active_quest_for_issuer(game_state, encounter.npc_id.as_str())
+                .and_then(|quest| read_optional_string_field(quest, "id"))
+        })
+        .ok_or_else(|| "当前没有可交付的委托。".to_string())?;
+    let turned_in = turn_in_quest_record(game_state, encounter.npc_id.as_str(), quest_id.as_str())?;
+    let previous_affinity = read_current_npc_affinity(game_state);
+    let affinity_bonus = read_field(&turned_in, "reward")
+        .and_then(|reward| read_i32_field(reward, "affinityBonus"))
+        .unwrap_or(0);
+    let next_affinity = previous_affinity.saturating_add(affinity_bonus);
+    write_current_npc_state_i32_field(game_state, "affinity", next_affinity);
+    write_current_npc_state_bool_field(game_state, "firstMeaningfulContactResolved", true);
+    apply_quest_turn_in_rewards(game_state, &turned_in);
+
+    Ok(StoryResolution {
+        action_text: resolve_action_text(&format!("向{}交付委托", encounter.npc_name), request),
+        result_text: build_quest_turn_in_result_text(&turned_in),
+        story_text: None,
+        presentation_options: None,
+        saved_current_story: None,
+        patches: vec![RuntimeStoryPatch::NpcAffinityChanged {
+            npc_id: encounter.npc_id,
+            previous_affinity,
+            next_affinity,
+        }],
+        battle: None,
+        toast: None,
+    })
+}

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

@@ -1,16 +1,26 @@
 use std::{error::Error, fmt};
 
+#[cfg(test)]
+use std::{
+    collections::HashMap,
+    sync::{Arc, Mutex},
+};
+
 use module_ai::{AiTaskService, InMemoryAiTaskStore};
 use module_auth::{
     AuthUserService, InMemoryAuthStore, PasswordEntryService, PhoneAuthService,
     RefreshSessionService, WechatAuthService, WechatAuthStateService,
 };
+use module_runtime::RuntimeSnapshotRecord;
+#[cfg(test)]
+use module_runtime::{SAVE_SNAPSHOT_VERSION, format_utc_micros};
 use platform_auth::{
     JwtConfig, JwtError, RefreshCookieConfig, RefreshCookieError, RefreshCookieSameSite,
 };
 use platform_llm::{LlmClient, LlmConfig, LlmError};
 use platform_oss::{OssClient, OssConfig, OssError};
-use spacetime_client::{SpacetimeClient, SpacetimeClientConfig};
+use serde_json::Value;
+use spacetime_client::{SpacetimeClient, SpacetimeClientConfig, SpacetimeClientError};
 
 use crate::config::AppConfig;
 use crate::wechat_provider::{WechatProvider, build_wechat_provider};
@@ -35,6 +45,9 @@ pub struct AppState {
     ai_task_service: AiTaskService,
     spacetime_client: SpacetimeClient,
     llm_client: Option<LlmClient>,
+    #[cfg(test)]
+    // 测试环境允许在未启动 SpacetimeDB 时，用内存快照兜底当前 runtime story 回归链。
+    test_runtime_snapshot_store: Arc<Mutex<HashMap<String, RuntimeSnapshotRecord>>>,
 }
 
 #[derive(Debug)]
@@ -98,6 +111,8 @@ impl AppState {
             ai_task_service,
             spacetime_client,
             llm_client,
+            #[cfg(test)]
+            test_runtime_snapshot_store: Arc::new(Mutex::new(HashMap::new())),
         })
     }
 
@@ -153,6 +168,162 @@ impl AppState {
     pub fn llm_client(&self) -> Option<&LlmClient> {
         self.llm_client.as_ref()
     }
+
+    pub async fn get_runtime_snapshot_record(
+        &self,
+        user_id: String,
+    ) -> Result<Option<RuntimeSnapshotRecord>, SpacetimeClientError> {
+        match self
+            .spacetime_client
+            .get_runtime_snapshot(user_id.clone())
+            .await
+        {
+            Ok(record) => {
+                #[cfg(test)]
+                if let Some(snapshot) = record.as_ref() {
+                    self.cache_test_runtime_snapshot(snapshot.clone());
+                }
+                Ok(record)
+            }
+            #[cfg(test)]
+            Err(_) => Ok(self.read_test_runtime_snapshot(user_id.as_str())),
+            #[cfg(not(test))]
+            Err(error) => Err(error),
+        }
+    }
+
+    pub async fn put_runtime_snapshot_record(
+        &self,
+        user_id: String,
+        saved_at_micros: i64,
+        bottom_tab: String,
+        game_state: Value,
+        current_story: Option<Value>,
+        updated_at_micros: i64,
+    ) -> Result<RuntimeSnapshotRecord, SpacetimeClientError> {
+        match self
+            .spacetime_client
+            .put_runtime_snapshot(
+                user_id.clone(),
+                saved_at_micros,
+                bottom_tab.clone(),
+                game_state.clone(),
+                current_story.clone(),
+                updated_at_micros,
+            )
+            .await
+        {
+            Ok(record) => {
+                #[cfg(test)]
+                self.cache_test_runtime_snapshot(record.clone());
+                Ok(record)
+            }
+            #[cfg(test)]
+            Err(_) => {
+                let snapshot = self.build_test_runtime_snapshot_record(
+                    user_id,
+                    saved_at_micros,
+                    bottom_tab,
+                    game_state,
+                    current_story,
+                    updated_at_micros,
+                )?;
+                self.cache_test_runtime_snapshot(snapshot.clone());
+                Ok(snapshot)
+            }
+            #[cfg(not(test))]
+            Err(error) => Err(error),
+        }
+    }
+
+    pub async fn delete_runtime_snapshot_record(
+        &self,
+        user_id: String,
+    ) -> Result<bool, SpacetimeClientError> {
+        match self
+            .spacetime_client
+            .delete_runtime_snapshot(user_id.clone())
+            .await
+        {
+            Ok(deleted) => {
+                #[cfg(test)]
+                if deleted {
+                    self.remove_test_runtime_snapshot(user_id.as_str());
+                }
+                Ok(deleted)
+            }
+            #[cfg(test)]
+            Err(_) => Ok(self
+                .remove_test_runtime_snapshot(user_id.as_str())
+                .is_some()),
+            #[cfg(not(test))]
+            Err(error) => Err(error),
+        }
+    }
+}
+
+#[cfg(test)]
+impl AppState {
+    fn cache_test_runtime_snapshot(&self, record: RuntimeSnapshotRecord) {
+        self.test_runtime_snapshot_store
+            .lock()
+            .expect("test runtime snapshot store should lock")
+            .insert(record.user_id.clone(), record);
+    }
+
+    fn read_test_runtime_snapshot(&self, user_id: &str) -> Option<RuntimeSnapshotRecord> {
+        self.test_runtime_snapshot_store
+            .lock()
+            .expect("test runtime snapshot store should lock")
+            .get(user_id)
+            .cloned()
+    }
+
+    fn remove_test_runtime_snapshot(&self, user_id: &str) -> Option<RuntimeSnapshotRecord> {
+        self.test_runtime_snapshot_store
+            .lock()
+            .expect("test runtime snapshot store should lock")
+            .remove(user_id)
+    }
+
+    fn build_test_runtime_snapshot_record(
+        &self,
+        user_id: String,
+        saved_at_micros: i64,
+        bottom_tab: String,
+        game_state: Value,
+        current_story: Option<Value>,
+        updated_at_micros: i64,
+    ) -> Result<RuntimeSnapshotRecord, SpacetimeClientError> {
+        let previous = self.read_test_runtime_snapshot(user_id.as_str());
+        let game_state_json = serde_json::to_string(&game_state).map_err(|error| {
+            SpacetimeClientError::Runtime(format!("测试快照 game_state 序列化失败: {error}"))
+        })?;
+        let current_story_json = current_story
+            .as_ref()
+            .map(serde_json::to_string)
+            .transpose()
+            .map_err(|error| {
+                SpacetimeClientError::Runtime(format!("测试快照 current_story 序列化失败: {error}"))
+            })?;
+
+        Ok(RuntimeSnapshotRecord {
+            user_id,
+            version: SAVE_SNAPSHOT_VERSION,
+            saved_at: format_utc_micros(saved_at_micros),
+            saved_at_micros,
+            bottom_tab,
+            game_state,
+            current_story,
+            game_state_json,
+            current_story_json,
+            created_at_micros: previous
+                .as_ref()
+                .map(|record| record.created_at_micros)
+                .unwrap_or(updated_at_micros),
+            updated_at_micros,
+        })
+    }
 }
 
 impl fmt::Display for AppStateInitError {