feat: checkpoint m5 and bootstrap m6 asset flow

server-rs/crates/shared-contracts/README.md

@@ -54,8 +54,10 @@
 当前阶段新增 Stage5 `runtime story` 兼容桥 DTO 基线：
 
 1. `runtime/story/state/resolve` 请求 DTO
+2. `runtime/story/actions/resolve`、`runtime/story/initial`、`runtime/story/continue` 请求 DTO
 2. `RuntimeStoryActionResponse` 兼容响应 DTO
 3. `RuntimeStoryViewModel / presentation / patches / snapshot` 显式结构
+4. `RuntimeStoryAiResponse` 兼容响应 DTO
 
 当前仍刻意未做：
 

server-rs/crates/shared-contracts/src/runtime_story.rs

@@ -4,7 +4,8 @@ use serde_json::Value;
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct RuntimeStorySnapshotPayload {
-    pub saved_at: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub saved_at: Option<String>,
     pub bottom_tab: String,
     pub game_state: Value,
     #[serde(default)]
@@ -21,6 +22,72 @@ pub struct RuntimeStoryStateResolveRequest {
     pub snapshot: Option<RuntimeStorySnapshotPayload>,
 }
 
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeStoryChoiceAction {
+    #[serde(rename = "type")]
+    pub action_type: String,
+    pub function_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub target_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub payload: Option<Value>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeStoryActionRequest {
+    pub session_id: String,
+    #[serde(default)]
+    pub client_version: Option<u32>,
+    pub action: RuntimeStoryChoiceAction,
+    #[serde(default)]
+    pub snapshot: Option<RuntimeStorySnapshotPayload>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeStoryAiRequestOptions {
+    #[serde(default)]
+    pub available_options: Vec<Value>,
+    #[serde(default)]
+    pub option_catalog: Vec<Value>,
+}
+
+impl Default for RuntimeStoryAiRequestOptions {
+    fn default() -> Self {
+        Self {
+            available_options: Vec::new(),
+            option_catalog: Vec::new(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeStoryAiRequest {
+    pub world_type: String,
+    pub character: Value,
+    #[serde(default)]
+    pub monsters: Vec<Value>,
+    #[serde(default)]
+    pub history: Vec<Value>,
+    #[serde(default)]
+    pub choice: String,
+    pub context: Value,
+    #[serde(default)]
+    pub request_options: RuntimeStoryAiRequestOptions,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeStoryAiResponse {
+    pub story_text: String,
+    pub options: Vec<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub encounter: Option<Value>,
+}
+
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct RuntimeStoryOptionView {
@@ -197,28 +264,70 @@ mod tests {
     use serde_json::json;
 
     #[test]
-    fn runtime_story_state_resolve_request_uses_camel_case_fields() {
-        let payload = serde_json::to_value(RuntimeStoryStateResolveRequest {
+    fn runtime_story_state_resolve_request_accepts_missing_saved_at() {
+        let payload: RuntimeStoryStateResolveRequest = serde_json::from_value(json!({
+            "sessionId": "runtime-main",
+            "clientVersion": 7,
+            "snapshot": {
+                "bottomTab": "adventure",
+                "gameState": { "runtimeSessionId": "runtime-main" },
+                "currentStory": { "text": "营地里的火光还没有熄灭。" }
+            }
+        }))
+        .expect("payload should deserialize");
+
+        assert_eq!(payload.session_id, "runtime-main");
+        assert_eq!(payload.client_version, Some(7));
+        assert_eq!(
+            payload.snapshot.expect("snapshot should exist").saved_at,
+            None
+        );
+    }
+
+    #[test]
+    fn runtime_story_action_request_uses_camel_case_fields() {
+        let payload = serde_json::to_value(RuntimeStoryActionRequest {
             session_id: "runtime-main".to_string(),
-            client_version: Some(7),
+            client_version: Some(8),
+            action: RuntimeStoryChoiceAction {
+                action_type: "story_choice".to_string(),
+                function_id: "npc_chat".to_string(),
+                target_id: Some("npc_camp_firekeeper".to_string()),
+                payload: Some(json!({ "optionText": "继续交谈" })),
+            },
             snapshot: Some(RuntimeStorySnapshotPayload {
-                saved_at: "2026-04-22T12:00:00.000Z".to_string(),
+                saved_at: Some("2026-04-22T12:00:00.000Z".to_string()),
                 bottom_tab: "adventure".to_string(),
                 game_state: json!({ "runtimeSessionId": "runtime-main" }),
-                current_story: Some(json!({ "text": "营地里的火光还没有熄灭。" })),
+                current_story: None,
             }),
         })
         .expect("payload should serialize");
 
         assert_eq!(payload["sessionId"], json!("runtime-main"));
-        assert_eq!(payload["clientVersion"], json!(7));
-        assert_eq!(payload["snapshot"]["savedAt"], json!("2026-04-22T12:00:00.000Z"));
-        assert_eq!(payload["snapshot"]["bottomTab"], json!("adventure"));
-        assert_eq!(payload["snapshot"]["gameState"]["runtimeSessionId"], json!("runtime-main"));
+        assert_eq!(payload["clientVersion"], json!(8));
+        assert_eq!(payload["action"]["type"], json!("story_choice"));
+        assert_eq!(payload["action"]["functionId"], json!("npc_chat"));
         assert_eq!(
-            payload["snapshot"]["currentStory"]["text"],
-            json!("营地里的火光还没有熄灭。")
+            payload["action"]["targetId"],
+            json!("npc_camp_firekeeper")
         );
+        assert_eq!(payload["snapshot"]["savedAt"], json!("2026-04-22T12:00:00.000Z"));
+    }
+
+    #[test]
+    fn runtime_story_ai_request_defaults_optional_arrays() {
+        let payload: RuntimeStoryAiRequest = serde_json::from_value(json!({
+            "worldType": "martial",
+            "character": { "name": "林迟" },
+            "context": { "scene": "camp" }
+        }))
+        .expect("payload should deserialize");
+
+        assert_eq!(payload.world_type, "martial");
+        assert!(payload.monsters.is_empty());
+        assert!(payload.history.is_empty());
+        assert!(payload.request_options.available_options.is_empty());
     }
 
     #[test]
@@ -297,7 +406,7 @@ mod tests {
                 current_npc_battle_outcome: None,
             }],
             snapshot: RuntimeStorySnapshotPayload {
-                saved_at: "2026-04-22T12:00:00.000Z".to_string(),
+                saved_at: Some("2026-04-22T12:00:00.000Z".to_string()),
                 bottom_tab: "adventure".to_string(),
                 game_state: json!({ "runtimeSessionId": "runtime-main" }),
                 current_story: Some(json!({