合并最新master到埋点开发分支

同步主分支至2d61a4c05并保留客户端本地埋点实现
合并决策记录顶部新增内容，保留双方条目
验证客户端Rust编译、TypeScript、编码与文档索引通过

apps/admin-web/src/api/adminApiClient.test.ts

@@ -81,14 +81,12 @@ test('模板批量导入走 multipart，不预设 JSON Content-Type', async () =
       },
     ],
   };
-  const fetchMock = vi
-    .fn()
-    .mockImplementation(
-      async () =>
-        new Response(JSON.stringify({ ok: true, data: imported }), {
-          status: 200,
-        }),
-    );
+  const fetchMock = vi.fn().mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ ok: true, data: imported }), {
+        status: 200,
+      }),
+  );
   vi.stubGlobal('fetch', fetchMock);
 
   const form = new FormData();

apps/ai-game-creator-shell/src-tauri/src/agent/direct_execution.rs

@@ -93,10 +93,17 @@ pub(super) struct ExecutionLedger {
     pub(super) plan: Option<Value>,
     #[serde(default)]
     pub(super) last_failed_write_revision: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(super) analytics_run: Option<crate::analytics::run::Metadata>,
 }
 
 struct SessionData {
     ledger: ExecutionLedger,
+    analytics_capture: Option<(
+        crate::analytics::contract::Context,
+        crate::analytics::store::AnalyticsWriter,
+    )>,
+    analytics_output_revision: Option<u64>,
     started: Instant,
     initial_elapsed_ms: u64,
     lease_started: BTreeMap<String, Instant>,
@@ -153,6 +160,8 @@ fn executor_digest(path: &Path) -> Result<String, String> {
 
 pub(super) struct ExecutionSession {
     pub(super) root: PathBuf,
+    /// 本次确实新建执行账本；恢复和旧预算迁移均不构成新的用户受理。
+    pub(super) newly_accepted: bool,
     state_path: PathBuf,
     _owner: File,
     data: Mutex<SessionData>,
@@ -216,6 +225,16 @@ pub(crate) struct WritePermit {
     id: String,
 }
 impl WritePermit {
+    pub(super) fn record_analytics_revision(
+        &self,
+        revision: u64,
+        change_kind: crate::analytics::contract::ChangeKind,
+        files_changed_count: u64,
+    ) {
+        self.session
+            .record_analytics_revision(revision, change_kind, files_changed_count);
+    }
+
     pub(crate) fn run<T>(&self, write: impl FnOnce() -> Result<T, String>) -> Result<T, String> {
         let mut data = self.session.lock()?;
         self.session.tick_locked(&mut data)?;
@@ -401,6 +420,7 @@ pub(super) async fn begin(
     prompt: &str,
     requires_contract: bool,
     config: DirectValidationConfig,
+    analytics_run: Option<crate::analytics::run::Metadata>,
 ) -> Result<ExecutionSessionGuard, String> {
     let root = root.to_path_buf();
     let prompt_hash = hash(prompt.as_bytes());
@@ -408,13 +428,14 @@ pub(super) async fn begin(
         let turn = super::direct_taonier_active_invocation_id_at(&root)?;
         let host = crate::game_creator_runtime_config_dir()
             .ok_or("direct-execution-host: 需要客户端私有配置目录，CLI 请提供 --config-dir")?;
-        open_at(
+        open_with_analytics_at(
             &host.join("direct-executions"),
             &root,
             &turn,
             &prompt_hash,
             requires_contract,
             &config,
+            analytics_run,
         )
     })
     .await
@@ -462,6 +483,26 @@ pub(super) fn open_at(
     request_hash: &str,
     requires_contract: bool,
     config: &DirectValidationConfig,
+) -> Result<Arc<ExecutionSession>, String> {
+    open_with_analytics_at(
+        host,
+        root,
+        turn,
+        request_hash,
+        requires_contract,
+        config,
+        None,
+    )
+}
+
+pub(super) fn open_with_analytics_at(
+    host: &Path,
+    root: &Path,
+    turn: &str,
+    request_hash: &str,
+    requires_contract: bool,
+    config: &DirectValidationConfig,
+    analytics_run: Option<crate::analytics::run::Metadata>,
 ) -> Result<Arc<ExecutionSession>, String> {
     config.validate()?;
     let root = root
@@ -521,6 +562,7 @@ pub(super) fn open_at(
     };
     let project_id = super::read_existing_manifest_for_project(&root)?.project_id;
     let is_new = existing.is_none();
+    let mut newly_accepted = is_new;
     let mut ledger = existing.unwrap_or_else(|| ExecutionLedger {
         schema_version: SCHEMA.into(),
         client_turn_id: turn.into(),
@@ -546,6 +588,7 @@ pub(super) fn open_at(
         delivery_reviews: 0,
         plan: None,
         last_failed_write_revision: None,
+        analytics_run,
     });
     if is_new {
         // 只继承旧项目账本的消费量，绝不把可编辑的旧成功回执提升为宿主证据。
@@ -558,6 +601,8 @@ pub(super) fn open_at(
                 512 * 1024,
             )?;
         if let Some(legacy) = legacy {
+            newly_accepted = false;
+            ledger.analytics_run = None;
             let used = legacy["usedRuns"]
                 .as_u64()
                 .and_then(|n| u32::try_from(n).ok());
@@ -614,10 +659,13 @@ pub(super) fn open_at(
     let (changed, _) = tokio::sync::watch::channel(ledger.revision);
     let session = Arc::new(ExecutionSession {
         root,
+        newly_accepted,
         state_path,
         _owner: owner,
         data: Mutex::new(SessionData {
             ledger,
+            analytics_capture: None,
+            analytics_output_revision: None,
             started: Instant::now(),
             initial_elapsed_ms,
             lease_started: BTreeMap::new(),
@@ -738,6 +786,10 @@ impl ExecutionSession {
     pub(super) fn cancel_flag(&self) -> Arc<std::sync::atomic::AtomicBool> {
         Arc::clone(&self.cancellation)
     }
+    pub(super) fn was_aborted(&self) -> bool {
+        self.abort_requested
+            .load(std::sync::atomic::Ordering::Acquire)
+    }
     pub(super) fn record_delivery_review(&self) -> Result<u32, String> {
         let mut data = self.lock()?;
         if data.ledger.phase.is_terminal() {
@@ -765,6 +817,74 @@ impl ExecutionSession {
         self.commit(&mut data, next)?;
         Ok(json!({"plan":plan,"revision":data.ledger.revision,"acceptancePassed":false}))
     }
+    pub(super) fn set_analytics_capture(
+        &self,
+        capture: Option<(
+            crate::analytics::contract::Context,
+            crate::analytics::store::AnalyticsWriter,
+        )>,
+    ) {
+        let Ok(mut data) = self.data.try_lock() else {
+            return;
+        };
+        data.analytics_capture = capture.and_then(|(mut context, writer)| {
+            // 恢复或账号切换后仍归属于真实受理的原 run。
+            context.route = data.ledger.analytics_run.as_ref()?.context.route.clone();
+            Some((context, writer))
+        });
+    }
+
+    pub(super) fn analytics_capture(
+        &self,
+    ) -> Option<(
+        crate::analytics::contract::Context,
+        crate::analytics::store::AnalyticsWriter,
+    )> {
+        self.data.try_lock().ok()?.analytics_capture.clone()
+    }
+
+    pub(super) fn record_analytics_revision(
+        &self,
+        revision: u64,
+        change_kind: crate::analytics::contract::ChangeKind,
+        files_changed_count: u64,
+    ) {
+        use crate::analytics::contract::{RevisionCreated, RevisionSource, Source};
+        if files_changed_count == 0 {
+            return;
+        }
+        let Ok(mut data) = self.data.try_lock() else {
+            return;
+        };
+        if data.ledger.analytics_run.is_none() {
+            return;
+        }
+        data.analytics_output_revision =
+            Some(data.analytics_output_revision.unwrap_or(0).max(revision));
+        let capture = data.analytics_capture.clone();
+        let project_id = data.ledger.project_id.clone();
+        drop(data);
+        crate::analytics::project::revision(
+            capture,
+            &project_id,
+            Source::Direct,
+            RevisionCreated {
+                revision_id: revision.to_string(),
+                revision_source: RevisionSource::Agent,
+                change_kind,
+                files_changed_count: Some(files_changed_count),
+            },
+        );
+    }
+
+    pub(super) fn analytics_output_revision(&self) -> Option<String> {
+        self.data
+            .try_lock()
+            .ok()?
+            .analytics_output_revision
+            .map(|revision| revision.to_string())
+    }
+
     pub(super) fn snapshot(&self) -> Result<ExecutionLedger, String> {
         let data = self.lock()?;
         let mut state = data.ledger.clone();

apps/ai-game-creator-shell/src-tauri/src/agent/direct_execution/tests.rs

@@ -1,5 +1,74 @@
 use super::*;
 
+fn analytics_metadata(user: &str) -> crate::analytics::run::Metadata {
+    use crate::analytics::contract::{Context, Route, RunSource, Source};
+    crate::analytics::run::Metadata::new(
+        Context {
+            route: Route::from_identity(Some(user.into()), Some("https://example.com")),
+            editor_session_id: uuid::Uuid::new_v4().to_string(),
+            client_version: "1.0.0".into(),
+        },
+        Source::Direct,
+        RunSource::UserSubmit,
+    )
+}
+
+#[test]
+fn run_metadata_is_persisted_with_new_ledger_and_replay_keeps_original_identity() {
+    let temp = tempfile::tempdir().unwrap();
+    let root = temp.path().join("project");
+    crate::init_local_game_project_at(&root, "analytics-run", "执行身份").unwrap();
+    let original = analytics_metadata("A");
+    let host = temp.path().join("host");
+    let session = open_with_analytics_at(
+        &host,
+        &root,
+        "turn",
+        &hash(b"request"),
+        false,
+        &Default::default(),
+        Some(original.clone()),
+    )
+    .unwrap();
+    assert!(session.newly_accepted);
+    assert_eq!(
+        session.snapshot().unwrap().analytics_run,
+        Some(original.clone())
+    );
+    drop(session);
+    let replay = open_with_analytics_at(
+        &host,
+        &root,
+        "turn",
+        &hash(b"request"),
+        false,
+        &Default::default(),
+        Some(analytics_metadata("B")),
+    )
+    .unwrap();
+    assert!(!replay.newly_accepted);
+    assert_eq!(replay.snapshot().unwrap().analytics_run, Some(original));
+}
+
+#[test]
+fn legacy_run_without_metadata_is_not_assigned_current_users_identity() {
+    let (temp, session) = fixture(Default::default());
+    let root = session.root.clone();
+    assert!(session.snapshot().unwrap().analytics_run.is_none());
+    drop(session);
+    let replay = open_with_analytics_at(
+        &temp.path().join("host"),
+        &root,
+        "turn-test",
+        &hash(b"request"),
+        false,
+        &Default::default(),
+        Some(analytics_metadata("B")),
+    )
+    .unwrap();
+    assert!(replay.snapshot().unwrap().analytics_run.is_none());
+}
+
 fn fixture(config: DirectValidationConfig) -> (tempfile::TempDir, Arc<ExecutionSession>) {
     let temp = tempfile::tempdir().unwrap();
     let root = temp.path().join("project");
@@ -13,6 +82,7 @@ fn fixture(config: DirectValidationConfig) -> (tempfile::TempDir, Arc<ExecutionS
         &config,
     )
     .unwrap();
+    assert!(session.newly_accepted);
     session
         .freeze_contract(json!({"requirements":[{"id":"test"}]}))
         .unwrap();
@@ -159,6 +229,7 @@ fn reopened_budget_and_deadline_cannot_be_increased_by_configuration() {
     )
     .unwrap();
     let state = reopened.snapshot().unwrap();
+    assert!(!reopened.newly_accepted);
     assert_eq!(state.delivery_reviews, 1);
     assert_eq!(
         (
@@ -278,6 +349,7 @@ fn legacy_budget_is_inherited_without_trusting_project_success_evidence() {
         &Default::default(),
     )
     .unwrap();
+    assert!(!session.newly_accepted);
     assert!(session.admit(EffectKind::Execute, None).is_err());
     let state = session.snapshot().unwrap();
     assert_eq!(state.used_passes, 2);

apps/ai-game-creator-shell/src-tauri/src/agent/direct_patch.rs

@@ -229,6 +229,40 @@ fn target_fingerprints(targets: &[PatchTarget]) -> BTreeMap<String, Option<Strin
         .collect()
 }
 
+fn analytics_patch_changes(
+    before: &BTreeMap<String, Option<String>>,
+    after: &BTreeMap<String, Option<String>>,
+) -> Option<(crate::analytics::contract::ChangeKind, u64)> {
+    use crate::analytics::contract::ChangeKind;
+    let mut result = None;
+    for (path, before) in before {
+        let Some((before, after)) = before
+            .as_ref()
+            .zip(after.get(path).and_then(Option::as_ref))
+        else {
+            continue;
+        };
+        if before == after {
+            continue;
+        }
+        let Some(kind) = crate::analytics::project::file_change_kind(path) else {
+            continue;
+        };
+        result = Some(match result {
+            None => (kind, 1),
+            Some((current, count)) => (
+                if current == kind {
+                    current
+                } else {
+                    ChangeKind::Mixed
+                },
+                count + 1,
+            ),
+        });
+    }
+    result
+}
+
 fn run_transaction(
     root: &Path,
     parsed: codex_patch_parser::ApplyPatchArgs,
@@ -319,6 +353,13 @@ fn run_transaction(
         None
     };
     lease.finish(passed && !uncertain, changed, None)?;
+    if passed && !uncertain {
+        if let (Some(revision), Some((kind, count))) =
+            (revision, analytics_patch_changes(&before, &after))
+        {
+            session.record_analytics_revision(revision, kind, count);
+        }
+    }
     Ok(json!({
         "status": if passed && !uncertain { "completed" } else { "failed" },
         "changedPaths": if started { changed_paths } else { BTreeSet::new() },
@@ -351,6 +392,47 @@ pub(super) async fn apply(root: &Path, arguments: &Value) -> Result<Value, Strin
 mod tests {
     use super::*;
 
+    #[test]
+    fn analytics_patch_counts_only_known_changed_outputs() {
+        let fingerprints = |entries: &[(&str, Option<&str>)]| {
+            entries
+                .iter()
+                .map(|(path, value)| (path.to_string(), value.map(str::to_string)))
+                .collect()
+        };
+        let before = fingerprints(&[
+            ("game/a.js", Some("a")),
+            ("game/same.js", Some("same")),
+            ("game/unknown.js", None),
+            ("game/unreadable.js", Some("old")),
+            (".agent/state.json", Some("old")),
+        ]);
+        let after = fingerprints(&[
+            ("game/a.js", Some("b")),
+            ("game/same.js", Some("same")),
+            ("game/unknown.js", Some("new")),
+            ("game/unreadable.js", None),
+            (".agent/state.json", Some("new")),
+        ]);
+        assert_eq!(
+            analytics_patch_changes(&before, &after),
+            Some((crate::analytics::contract::ChangeKind::Code, 1))
+        );
+        assert_eq!(analytics_patch_changes(&before, &before), None);
+        let before = fingerprints(&[
+            ("game/a.js", Some("missing")),
+            ("assets/a.png", Some("old")),
+        ]);
+        let after = fingerprints(&[
+            ("game/a.js", Some("new")),
+            ("assets/a.png", Some("missing")),
+        ]);
+        assert_eq!(
+            analytics_patch_changes(&before, &after),
+            Some((crate::analytics::contract::ChangeKind::Mixed, 2))
+        );
+    }
+
     fn project() -> (tempfile::TempDir, PathBuf) {
         let temp = tempfile::tempdir().unwrap();
         let root = temp.path().join("project");
@@ -415,15 +497,20 @@ mod tests {
     #[tokio::test]
     async fn bundled_patch_roundtrip_preserves_partial_failure_and_rejects_closed_turn() {
         let (temp, root) = project();
-        let session = direct_execution::open_at(
+        let config = temp.path().join("analytics-config");
+        let (metadata, context, writer) =
+            super::super::direct_tool_bridge::analytics_test_writer(&config);
+        let session = direct_execution::open_with_analytics_at(
             &temp.path().join("host"),
             &root,
             "patch-roundtrip",
             &format!("{:x}", Sha256::digest(b"request")),
             false,
             &direct_validation::DirectValidationConfig::default(),
+            Some(metadata),
         )
         .unwrap();
+        session.set_analytics_capture(Some((context.clone(), writer.clone())));
         session
             .freeze_contract(json!({"fixture":"patch protocol only"}))
             .unwrap();
@@ -499,6 +586,29 @@ mod tests {
             "writes do not invent execution passes"
         );
         assert!(session.snapshot().unwrap().active.is_empty());
+        assert_eq!(
+            session.analytics_output_revision(),
+            None,
+            "text fixture files are not classified as成果"
+        );
+        let outputs = apply(&root, &json!({"patch":"*** Begin Patch\n*** Add File: game/result.js\n+const result = 1;\n*** Add File: game/style.css\n+body { color: red; }\n*** End Patch"})).await.unwrap();
+        assert_eq!(outputs["status"], "completed", "{outputs}");
+        let revision = outputs["revision"].as_u64().unwrap().to_string();
+        assert_eq!(session.analytics_output_revision(), Some(revision.clone()));
+        let partial_output = apply(&root, &json!({"patch":"*** Begin Patch\n*** Add File: game/partial.js\n+const partial = 1;\n*** Update File: game/absent.js\n@@\n-old\n+new\n*** End Patch"})).await.unwrap();
+        assert_eq!(partial_output["status"], "failed");
+        assert_eq!(session.analytics_output_revision(), Some(revision.clone()));
+        let events = super::super::direct_tool_bridge::drain_analytics_test_writer(
+            &config, &context, &writer,
+        );
+        let revisions: Vec<_> = events
+            .iter()
+            .filter(|event| event["event_name"] == "project_revision_created")
+            .collect();
+        assert_eq!(revisions.len(), 1);
+        assert_eq!(revisions[0]["user_id"], "A");
+        assert_eq!(revisions[0]["properties"]["revision_id"], revision);
+        assert_eq!(revisions[0]["properties"]["files_changed_count"], 2);
         session.interrupt("fixture stopped".into()).unwrap();
         assert!(apply(
             &root,

apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs

@@ -4243,7 +4243,44 @@ pub(crate) async fn run_direct_browser_evidence_with_cancellation_at(
     advisory_interaction: bool,
     cancellation: Option<Arc<std::sync::atomic::AtomicBool>>,
 ) -> Result<BrowserValidationResult, String> {
+    run_direct_browser_evidence_with_analytics_at(
+        root,
+        evidence_root,
+        scenario,
+        advisory_interaction,
+        cancellation,
+        None,
+    )
+    .await
+}
+
+pub(crate) async fn run_direct_browser_evidence_with_analytics_at(
+    root: &Path,
+    evidence_root: PathBuf,
+    scenario: Option<crate::browser::BrowserPlaytestScenario>,
+    advisory_interaction: bool,
+    cancellation: Option<Arc<std::sync::atomic::AtomicBool>>,
+    capture: Option<(
+        crate::analytics::contract::Context,
+        crate::analytics::store::AnalyticsWriter,
+    )>,
+) -> Result<BrowserValidationResult, String> {
+    let observation = crate::analytics::preview::prepare(
+        root,
+        capture,
+        crate::analytics::contract::Source::Direct,
+        crate::analytics::contract::PreviewSource::Agent,
+    );
+    let (_analytics_lease, observation) = match observation {
+        Some((lease, observation)) => (Some(lease), Some(observation)),
+        None => (None, None),
+    };
     let (preview, stop_sender) = start_local_game_preview_for_project(root)?;
+    if let Some(observation) = observation {
+        observation
+            .with_cancellation(cancellation.clone())
+            .schedule(preview.port);
+    }
     let validation = crate::browser::validate_local_preview_in_browser_with_cancellation(
         BrowserValidationInput {
             url: preview.url,
@@ -4261,6 +4298,7 @@ pub(crate) async fn run_direct_browser_evidence_with_cancellation_at(
         cancellation,
     )
     .await;
+    drop(_analytics_lease);
     let _ = stop_sender.send(());
     validation
 }
@@ -4781,6 +4819,8 @@ pub(crate) async fn run_direct_game_creator_turn_at_with_creation_type(
         None,
         None,
         None,
+        None,
+        None,
     )
     .await
 }
@@ -4792,6 +4832,11 @@ async fn run_direct_game_creator_turn_at_with_creation_type_and_emitter(
     turn_emitter: Option<&DirectGameCreatorTurnUpdateEmitter>,
     audit: Option<&mut DirectCodexTurnAudit>,
     direct_user_item: Option<serde_json::Value>,
+    capture: Option<(
+        crate::analytics::contract::Context,
+        crate::analytics::store::AnalyticsWriter,
+    )>,
+    analytics_attempt_id: Option<&str>,
 ) -> Result<String, String> {
     if !root.is_absolute() || !root.is_dir() {
         return Err("当前项目目录不存在或不是绝对路径".to_string());
@@ -4814,6 +4859,8 @@ async fn run_direct_game_creator_turn_at_with_creation_type_and_emitter(
         turn_emitter,
         audit,
         direct_user_item,
+        capture,
+        analytics_attempt_id,
     )
     .await
     {
@@ -5014,6 +5061,11 @@ async fn run_direct_game_creator_turn_inner(
     turn_emitter: Option<&DirectGameCreatorTurnUpdateEmitter>,
     audit: Option<&mut DirectCodexTurnAudit>,
     direct_user_item: Option<serde_json::Value>,
+    capture: Option<(
+        crate::analytics::contract::Context,
+        crate::analytics::store::AnalyticsWriter,
+    )>,
+    analytics_attempt_id: Option<&str>,
 ) -> Result<String, DirectCodexTurnFailure> {
     let requires_contract = super::direct_delivery::requires_new_web_contract(
         root,
@@ -5035,16 +5087,49 @@ async fn run_direct_game_creator_turn_inner(
             DirectCodexTurnFailure::new(DirectCodexFailureStage::CodeGeneration, error)
         })?
         .validation;
-    let execution_guard =
-        super::direct_execution::begin(root, prompt, requires_contract, execution_config)
-            .await
-            .map_err(|error| {
-                DirectCodexTurnFailure::new(DirectCodexFailureStage::CodeGeneration, error)
-            })?;
+    let analytics_run = capture.as_ref().map(|(context, _)| {
+        crate::analytics::run::Metadata::new(
+            context.clone(),
+            crate::analytics::contract::Source::Direct,
+            crate::analytics::contract::RunSource::UserSubmit,
+        )
+    });
+    let execution_guard = super::direct_execution::begin(
+        root,
+        prompt,
+        requires_contract,
+        execution_config,
+        analytics_run,
+    )
+    .await
+    .map_err(|error| DirectCodexTurnFailure::new(DirectCodexFailureStage::CodeGeneration, error))?;
     let execution_session = execution_guard.session();
+    execution_session.set_analytics_capture(capture.clone());
+    let started = execution_session
+        .newly_accepted
+        .then(std::time::Instant::now);
+    if execution_session.newly_accepted {
+        if let Ok(ledger) = execution_session.snapshot() {
+            if let (Some((_, writer)), Some(metadata)) = (&capture, &ledger.analytics_run) {
+                crate::analytics::run::accepted(writer, root, &ledger.project_id, metadata);
+            }
+        }
+    }
+    // 在 guard 仍存活时冻结整体结果，避免 Drop 的中断收尾覆盖真实失败原因。
+    let result: Result<String, DirectCodexTurnFailure> = async {
     if let Some(report) = super::direct_delivery::terminal_report(&execution_session) {
         return Ok(report);
     }
+    if execution_session.newly_accepted {
+        if let Ok(ledger) = execution_session.snapshot() {
+            crate::analytics::goal::accepted(
+                capture.clone(),
+                root,
+                &ledger.project_id,
+                crate::analytics::contract::Source::Direct,
+            );
+        }
+    }
     emit_direct_game_creator_progress(root, "codex.turn", "陶泥儿正在处理这条消息");
     if let Some(emitter) = turn_emitter {
         emitter.emit("running", Some("preparing"), None, None);
@@ -5334,6 +5419,118 @@ async fn run_direct_game_creator_turn_inner(
             })?;
     }
     Ok(visible_reply)
+    }.await;
+    if let Ok(ledger) = execution_session.snapshot() {
+        if let (Some(metadata), Some((end_reason, error_code))) = (
+            &ledger.analytics_run,
+            direct_analytics_outcome(
+                ledger.phase,
+                ledger.requires_contract || ledger.contract.is_some(),
+                result.is_err(),
+                execution_session.was_aborted(),
+            ),
+        ) {
+            let output_revision = execution_session.analytics_output_revision();
+            crate::analytics::run::direct_finished(
+                capture,
+                root,
+                &ledger.project_id,
+                metadata,
+                analytics_attempt_id,
+                crate::analytics::run::Outcome {
+                    turn_id: Some(ledger.client_turn_id.clone()),
+                    end_reason,
+                    error_code,
+                    duration_ms: started
+                        .and_then(|start| u64::try_from(start.elapsed().as_millis()).ok()),
+                    output_change_detected: output_revision.as_ref().map(|_| true),
+                    revision_id: output_revision,
+                },
+            );
+        }
+    }
+    result
+}
+
+fn direct_analytics_outcome(
+    phase: super::direct_execution::ExecutionPhase,
+    has_contract: bool,
+    failed: bool,
+    aborted: bool,
+) -> Option<(
+    crate::analytics::contract::RunEndReason,
+    Option<crate::analytics::contract::ErrorCode>,
+)> {
+    use super::direct_execution::ExecutionPhase;
+    use crate::analytics::contract::{ErrorCode, RunEndReason};
+    if phase == ExecutionPhase::Interrupted || aborted {
+        return None;
+    }
+    if phase == ExecutionPhase::Exhausted {
+        return Some((RunEndReason::Failed, Some(ErrorCode::RuntimeFailed)));
+    }
+    if failed {
+        // Direct 当前只保留 stage 和展示错误字符串，不从正文猜 Provider 错误类别。
+        return Some((
+            RunEndReason::Failed,
+            Some(ErrorCode::RuntimeErrorUnclassified),
+        ));
+    }
+    if phase == ExecutionPhase::Completed || !has_contract {
+        return Some((RunEndReason::Finished, None));
+    }
+    None
+}
+
+#[cfg(test)]
+mod direct_analytics_tests {
+    use super::*;
+    use crate::agent::direct_execution::ExecutionPhase;
+    use crate::analytics::contract::{ErrorCode, RunEndReason};
+
+    #[test]
+    fn terminal_reports_do_not_turn_exhaustion_or_cancellation_into_success() {
+        assert_eq!(
+            direct_analytics_outcome(ExecutionPhase::Exhausted, true, false, false),
+            Some((RunEndReason::Failed, Some(ErrorCode::RuntimeFailed)))
+        );
+        for failed in [true, false] {
+            assert_eq!(
+                direct_analytics_outcome(ExecutionPhase::Interrupted, true, failed, false),
+                None
+            );
+            assert_eq!(
+                direct_analytics_outcome(ExecutionPhase::Working, false, failed, true),
+                None
+            );
+        }
+    }
+
+    #[test]
+    fn complete_delivery_does_not_hide_later_projection_failure() {
+        assert_eq!(
+            direct_analytics_outcome(ExecutionPhase::Completed, true, true, false),
+            Some((
+                RunEndReason::Failed,
+                Some(ErrorCode::RuntimeErrorUnclassified)
+            ))
+        );
+        assert_eq!(
+            direct_analytics_outcome(ExecutionPhase::Completed, true, false, false),
+            Some((RunEndReason::Finished, None))
+        );
+        assert_eq!(
+            direct_analytics_outcome(ExecutionPhase::Working, false, false, false),
+            Some((RunEndReason::Finished, None))
+        );
+        for phase in [
+            ExecutionPhase::Working,
+            ExecutionPhase::Draining,
+            ExecutionPhase::Sealing,
+        ] {
+            assert_eq!(direct_analytics_outcome(phase, true, false, false), None);
+        }
+    }
 }
 
 #[cfg(test)]

apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/user_input.rs

@@ -34,8 +34,10 @@ pub(crate) async fn chat_with_game_creator_direct_codex(
     mut user_item: DirectCodexUserItem,
     creation_type: Option<String>,
     client_turn_id: Option<String>,
+    analytics_attempt_id: Option<String>,
     attachments: Option<Vec<DirectCodexTurnAttachment>>,
 ) -> Result<String, String> {
+    let capture = crate::analytics::gui::capture_writer_context();
     let root = Path::new(project_path.trim());
     let turn_id = normalize_direct_client_turn_id(client_turn_id.as_deref())?;
     let _active_invocation = DirectTaonierActiveInvocationGuard::enter(root, &turn_id)?;
@@ -99,6 +101,8 @@ pub(crate) async fn chat_with_game_creator_direct_codex(
         Some(&turn_emitter),
         Some(&mut audit),
         canonical_user_item,
+        capture,
+        analytics_attempt_id.as_deref(),
     )
     .await
     {

apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs

@@ -1600,6 +1600,15 @@ fn bridge_write_file(root: &Path, arguments: &Value) -> Value {
     bridge_write_file_with_permit(root, arguments, None)
 }
 
+fn bridge_file_content_changed(root: &Path, path: &str, content: &[u8]) -> Option<bool> {
+    crate::analytics::project::file_content_changed(
+        root,
+        path,
+        content,
+        DIRECT_TOOL_BRIDGE_MAX_WRITE_CONTENT_BYTES as u64,
+    )
+}
+
 fn bridge_write_file_with_permit(
     root: &Path,
     arguments: &Value,
@@ -1641,6 +1650,11 @@ fn bridge_write_file_with_permit(
             "direct-codex.file.write",
         )?;
         let lock_wait_ms = acquire_started.elapsed().as_millis();
+        let analytics_change_kind = write_permit.and_then(|_| {
+            let kind = crate::analytics::project::file_change_kind(&path)?;
+            (bridge_file_content_changed(root, &path, content.as_bytes()) == Some(true))
+                .then_some(kind)
+        });
         let write_started = std::time::Instant::now();
         let commit = || {
             let written = write_local_project_file_at(root, &path, content)?;
@@ -1653,6 +1667,9 @@ fn bridge_write_file_with_permit(
             Some(permit) => permit.run(commit)?,
             None => commit()?,
         };
+        if let (Some(permit), Some(kind)) = (write_permit, analytics_change_kind) {
+            permit.record_analytics_revision(revision, kind, 1);
+        }
         // 现场一次 2.6KB 写入实测 5.5 秒。只在明显偏慢时记账，正常写入不刷日志。
         if lock_wait_ms + write_ms > 200 {
             app_log!(
@@ -3473,6 +3490,82 @@ pub(in crate::agent) async fn generate_images_concurrently_for_test(
     .await
 }
 
+#[cfg(test)]
+pub(super) fn analytics_test_writer(
+    config: &Path,
+) -> (
+    crate::analytics::run::Metadata,
+    crate::analytics::contract::Context,
+    crate::analytics::store::AnalyticsWriter,
+) {
+    use crate::analytics::{
+        contract::{Context, Route, RunSource, Source},
+        run,
+        store::AnalyticsWriter,
+    };
+    let mut context = Context {
+        route: Route::from_identity(Some("A".into()), Some("https://example.com")),
+        editor_session_id: uuid::Uuid::new_v4().to_string(),
+        client_version: "1.0.0".into(),
+    };
+    fs::create_dir_all(config).expect("create analytics test config directory");
+    let metadata = run::Metadata::new(context.clone(), Source::Direct, RunSource::UserSubmit);
+    context.route.user_id = Some("B".into());
+    let writer = AnalyticsWriter::start(config.into(), context.editor_session_id.clone());
+    (metadata, context, writer)
+}
+
+#[cfg(test)]
+pub(super) fn drain_analytics_test_writer(
+    config: &Path,
+    context: &crate::analytics::contract::Context,
+    writer: &crate::analytics::store::AnalyticsWriter,
+) -> Vec<Value> {
+    use crate::analytics::contract::{EntrySource, EventData, SessionStart, Source};
+    let marker = context
+        .capture(
+            EventData::EditorSessionStart(SessionStart {
+                entry_source: EntrySource::DirectLaunch,
+                first_project_id: None,
+            }),
+            None,
+            Source::Editor,
+            None,
+        )
+        .unwrap();
+    let marker_id = marker.event_id.clone();
+    assert!(writer.try_record(context.route.clone(), marker, marker_id.clone()));
+    assert!(writer.flush());
+    let batches = config
+        .join("analytics/instances")
+        .join(&context.editor_session_id)
+        .join("batches");
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
+    loop {
+        let events: Vec<Value> = fs::read_dir(&batches)
+            .into_iter()
+            .flatten()
+            .flatten()
+            .filter(|entry| !entry.file_name().to_string_lossy().starts_with('.'))
+            .filter_map(|entry| fs::read_to_string(entry.path().join("events.jsonl")).ok())
+            .flat_map(|contents| {
+                contents
+                    .lines()
+                    .filter_map(|line| serde_json::from_str::<Value>(line).ok())
+                    .collect::<Vec<_>>()
+            })
+            .collect();
+        if events.iter().any(|event| event["event_id"] == marker_id) {
+            return events;
+        }
+        assert!(
+            std::time::Instant::now() < deadline,
+            "analytics FIFO sentinel timed out"
+        );
+        std::thread::sleep(std::time::Duration::from_millis(5));
+    }
+}
+
 #[cfg(test)]
 mod tests {
     #[tokio::test]
@@ -4262,6 +4355,293 @@ mod tests {
         assert_eq!(importability.get("assets/vector.svg"), Some(&true));
     }
 
+    #[tokio::test]
+    async fn analytics_real_file_write_preserves_original_identity_and_failed_run_revision() {
+        use crate::analytics::{
+            contract::{ErrorCode, RunEndReason},
+            run,
+        };
+        let temporary = tempfile::tempdir().unwrap();
+        let root = temporary.path().join("project");
+        let config = temporary.path().join("config");
+        let (metadata, context, writer) = analytics_test_writer(&config);
+        let original_capture = Some((metadata.context.clone(), writer.clone()));
+        let mut lifecycle = crate::analytics::gui::LifecycleFixture::start(
+            metadata.context.clone(),
+            writer.clone(),
+        );
+        lifecycle.create_and_open(&root, "direct-analytics");
+        let session = super::super::direct_execution::open_with_analytics_at(
+            &temporary.path().join("host"),
+            &root,
+            "analytics-write",
+            &format!("{:x}", Sha256::digest(b"request")),
+            false,
+            &Default::default(),
+            Some(metadata.clone()),
+        )
+        .unwrap();
+        session.set_analytics_capture(Some((context.clone(), writer.clone())));
+        super::super::direct_delivery::register_contract(
+            &root,
+            &session,
+            &json!({
+                "scope": "核对当前项目宿主写入的成果采集",
+                "changeKind": "project",
+                "requirements": [{"id": "analytics-output", "kind": "artifact", "path": "game/index.html"}]
+            }),
+        )
+        .await
+        .expect("freeze a validated delivery contract before writing");
+        let project_id = session.snapshot().unwrap().project_id;
+        run::accepted(&writer, &root, &project_id, &metadata);
+        crate::analytics::goal::accepted(
+            original_capture.clone(),
+            &root,
+            &project_id,
+            crate::analytics::contract::Source::Direct,
+        );
+        let lease = session
+            .admit(super::super::direct_execution::EffectKind::Write, None)
+            .unwrap();
+        let permit = lease.write_permit().unwrap();
+        let arguments = json!({"path":"game/index.html", "content":"<!doctype html><html><body>真实预览</body></html>"});
+        let changed = bridge_write_file_with_permit(&root, &arguments, Some(&permit));
+        assert_eq!(changed["isError"], false);
+        let payload: Value =
+            serde_json::from_str(changed["content"][0]["text"].as_str().unwrap()).unwrap();
+        let revision = payload["revision"].as_u64().unwrap().to_string();
+        assert_eq!(session.analytics_output_revision(), Some(revision.clone()));
+        assert_eq!(
+            bridge_write_file_with_permit(&root, &arguments, Some(&permit))["isError"],
+            false
+        );
+        assert_eq!(
+            bridge_write_file_with_permit(
+                &root,
+                &json!({"path":"../bad.js","content":"bad"}),
+                Some(&permit)
+            )["isError"],
+            true
+        );
+        assert_eq!(session.analytics_output_revision(), Some(revision.clone()));
+        lease.finish(true, true, None).unwrap();
+        let attempt = uuid::Uuid::new_v4().to_string();
+        run::direct_finished(
+            Some((context.clone(), writer.clone())),
+            &root,
+            &project_id,
+            &metadata,
+            Some(&attempt),
+            run::Outcome {
+                turn_id: Some("analytics-write".into()),
+                end_reason: RunEndReason::Failed,
+                error_code: Some(ErrorCode::RuntimeErrorUnclassified),
+                duration_ms: None,
+                output_change_detected: Some(true),
+                revision_id: session.analytics_output_revision(),
+            },
+        );
+        run::settle(Some((context.clone(), writer.clone())), &attempt, false);
+        // 默认项目使用 npm：预览服务读取真实构建目录，夹具提供构建入口，不调用构建器。
+        let served_root = crate::project_game_root(&root);
+        fs::create_dir_all(&served_root).unwrap();
+        fs::write(
+            served_root.join("index.html"),
+            "<!doctype html><html><body>真实预览构建</body></html>",
+        )
+        .unwrap();
+        let (preview_lease, observation) = crate::analytics::preview::prepare(
+            &root,
+            original_capture.clone(),
+            crate::analytics::contract::Source::Editor,
+            crate::analytics::contract::PreviewSource::User,
+        )
+        .unwrap();
+        let (preview, stop) = crate::start_local_game_preview_for_project(&root).unwrap();
+        observation.observe(preview.port).await;
+        let preview_revision = crate::read_game_creator_agent_runtime_project_revision(&root)
+            .unwrap()
+            .revision
+            .to_string();
+        drop(preview_lease);
+        let _ = stop.send(());
+        let checkpoint = crate::commands::checkpoint_with_capture_for_test(
+            root.to_string_lossy().into_owned(),
+            original_capture,
+        )
+        .unwrap();
+        lifecycle.exit();
+        let events = drain_analytics_test_writer(&config, &context, &writer);
+        let ids: std::collections::HashSet<_> = events
+            .iter()
+            .map(|event| event["event_id"].as_str().unwrap())
+            .collect();
+        assert_eq!(ids.len(), events.len());
+        let chain: Vec<_> = events
+            .iter()
+            .filter(|event| event["user_id"] == "A")
+            .collect();
+        for name in [
+            "editor_session_start",
+            "editor_focus_start",
+            "project_create_success",
+            "project_open",
+            "creative_task_submit",
+            "project_revision_created",
+            "agent_run_failed",
+            "preview_ready",
+            "project_save",
+            "editor_focus_end",
+            "editor_session_end",
+        ] {
+            assert_eq!(
+                chain
+                    .iter()
+                    .filter(|event| event["event_name"] == name)
+                    .count(),
+                1,
+                "{name}"
+            );
+        }
+        for event in &chain {
+            assert_eq!(
+                event["editor_session_id"],
+                metadata.context.editor_session_id
+            );
+            if !event["project_id"].is_null() {
+                assert_eq!(event["project_id"], project_id);
+            }
+            if !event["creative_task_id"].is_null() {
+                assert_eq!(event["creative_task_id"], project_id);
+            }
+            if !event["agent_run_id"].is_null() {
+                assert_eq!(event["agent_run_id"], metadata.run_id);
+            }
+            let name = event["event_name"].as_str().unwrap();
+            if matches!(
+                name,
+                "project_create_success"
+                    | "project_open"
+                    | "creative_task_submit"
+                    | "project_revision_created"
+                    | "agent_run_failed"
+                    | "preview_ready"
+                    | "project_save"
+            ) {
+                assert_eq!(
+                    event["project_id"], project_id,
+                    "{name} must identify its project"
+                );
+            }
+            if matches!(
+                name,
+                "creative_task_submit"
+                    | "project_revision_created"
+                    | "agent_run_failed"
+                    | "preview_ready"
+                    | "project_save"
+            ) {
+                assert_eq!(
+                    event["creative_task_id"], project_id,
+                    "{name} must identify its goal"
+                );
+            }
+            if name == "agent_run_failed" {
+                assert_eq!(event["agent_run_id"], metadata.run_id);
+                assert_eq!(event["agent_turn_id"], "analytics-write");
+            }
+        }
+        let save = chain
+            .iter()
+            .find(|event| event["event_name"] == "project_save")
+            .unwrap();
+        assert_eq!(save["properties"]["save_source"], "checkpoint");
+        assert!(Path::new(&checkpoint.checkpoint_path).is_dir());
+        let mut digest = Sha256::new();
+        digest.update(serde_json::to_vec(&metadata.context.route).unwrap());
+        digest.update([0]);
+        digest.update(format!("{project_id}:{}:project_save", checkpoint.checkpoint_id).as_bytes());
+        let checkpoint_fact = format!("{:x}", digest.finalize());
+        let batches = config
+            .join("analytics/instances")
+            .join(&context.editor_session_id)
+            .join("batches");
+        let checkpoint_fact_matches = fs::read_dir(batches)
+            .unwrap()
+            .flatten()
+            .filter_map(|entry| fs::read(entry.path().join("meta.json")).ok())
+            .filter_map(|bytes| serde_json::from_slice::<Value>(&bytes).ok())
+            .filter(|batch| batch["facts"][&checkpoint_fact] == save["event_id"])
+            .count();
+        assert_eq!(
+            checkpoint_fact_matches, 1,
+            "save fact must use the actual checkpoint ID"
+        );
+        let ready = chain
+            .iter()
+            .find(|event| event["event_name"] == "preview_ready")
+            .unwrap();
+        assert_eq!(ready["properties"]["preview_version"], preview_revision);
+        let focus_start = chain
+            .iter()
+            .find(|event| event["event_name"] == "editor_focus_start")
+            .unwrap();
+        let focus_end = chain
+            .iter()
+            .find(|event| event["event_name"] == "editor_focus_end")
+            .unwrap();
+        assert_eq!(
+            focus_start["properties"]["focus_interval_id"],
+            focus_end["properties"]["focus_interval_id"]
+        );
+        let revisions: Vec<_> = events
+            .iter()
+            .filter(|event| event["event_name"] == "project_revision_created")
+            .collect();
+        assert_eq!(revisions.len(), 1);
+        assert_eq!(revisions[0]["user_id"], "A");
+        assert_eq!(revisions[0]["properties"]["revision_id"], revision);
+        let failed: Vec<_> = events
+            .iter()
+            .filter(|event| event["event_name"] == "agent_run_failed")
+            .collect();
+        assert_eq!(failed.len(), 1);
+        assert_eq!(failed[0]["user_id"], "A");
+        assert_eq!(failed[0]["properties"]["revision_id"], revision);
+        assert_eq!(failed[0]["properties"]["output_change_detected"], true);
+    }
+
+    #[test]
+    fn analytics_file_comparison_requires_known_bounded_content() {
+        let temporary = tempfile::tempdir().unwrap();
+        let root = temporary.path();
+        assert_eq!(
+            bridge_file_content_changed(root, "new.js", b"new"),
+            Some(true)
+        );
+        fs::write(root.join("new.js"), b"new").unwrap();
+        assert_eq!(
+            bridge_file_content_changed(root, "new.js", b"new"),
+            Some(false)
+        );
+        assert_eq!(
+            bridge_file_content_changed(root, "new.js", b"changed"),
+            Some(true)
+        );
+        fs::create_dir(root.join("directory.js")).unwrap();
+        assert_eq!(
+            bridge_file_content_changed(root, "directory.js", b"new"),
+            None
+        );
+        fs::write(
+            root.join("large.js"),
+            vec![0; DIRECT_TOOL_BRIDGE_MAX_WRITE_CONTENT_BYTES + 1],
+        )
+        .unwrap();
+        assert_eq!(bridge_file_content_changed(root, "large.js", b"new"), None);
+    }
+
     #[test]
     fn bridge_write_file_writes_project_relative_text_without_runtime_tasks() {
         let temporary = tempfile::tempdir().expect("create direct write root");

apps/ai-game-creator-shell/src-tauri/src/agent/direct_validation.rs

@@ -453,12 +453,15 @@ async fn run_browser_with_budget(
             sequence,
         ),
     )?;
-    let evidence = super::direct_runtime::run_direct_browser_evidence_with_cancellation_at(
+    let evidence = super::direct_runtime::run_direct_browser_evidence_with_analytics_at(
         root,
         evidence_root,
         scenario,
         false,
         reservation.as_ref().map(|r| r.session.cancel_flag()),
+        reservation
+            .as_ref()
+            .and_then(|r| r.session.analytics_capture()),
     )
     .await;
     let (result, passed) = match evidence {

apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/design_session.rs

@@ -126,6 +126,9 @@ pub(crate) struct DesignTurn {
     pub(crate) attempt: u32,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub(crate) model_selection: Option<DesignModelSelection>,
+    /// 仅持久化埋点关联，旧回合缺失时不补历史执行。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) analytics: Option<crate::analytics::run::Metadata>,
 }
 
 /// 仅保存恢复所需的用户选择，不包含连接配置或凭据。

apps/ai-game-creator-shell/src-tauri/src/analytics/contract_tests.rs

@@ -0,0 +1,277 @@
+use super::*;
+use serde_json::json;
+
+fn context() -> Context {
+    Context {
+        route: Route::from_identity(Some("123".into()), Some("https://example.com/api")),
+        editor_session_id: Uuid::new_v4().to_string(),
+        client_version: "0.1.67".into(),
+    }
+}
+
+fn run() -> RunFinished {
+    RunFinished {
+        agent_type: AgentType::GameAgent,
+        run_source: RunSource::UserSubmit,
+        duration_ms: None,
+        retry_index: 0,
+        output_change_detected: None,
+        revision_id: None,
+        end_reason: RunEndReason::Finished,
+    }
+}
+
+fn samples() -> Vec<Event> {
+    let mut failed = run();
+    failed.end_reason = RunEndReason::Failed;
+    let values = vec![
+        (
+            EventData::EditorSessionStart(SessionStart {
+                entry_source: EntrySource::DirectLaunch,
+                first_project_id: None,
+            }),
+            None,
+            Source::Editor,
+        ),
+        (
+            EventData::EditorSessionEnd(SessionEnd {
+                end_reason: SessionEndReason::UserExit,
+                session_duration_ms: Some(10),
+                last_project_id: None,
+            }),
+            None,
+            Source::Editor,
+        ),
+        (
+            EventData::EditorFocusStart(FocusStart {
+                focus_interval_id: Uuid::new_v4().to_string(),
+                focus_reason: FocusReason::InitialFocus,
+                active_project_id: None,
+            }),
+            None,
+            Source::Editor,
+        ),
+        (
+            EventData::EditorFocusEnd(FocusEnd {
+                focus_interval_id: Uuid::new_v4().to_string(),
+                blur_reason: BlurReason::WindowBlur,
+                focus_duration_ms: None,
+                active_project_id: None,
+            }),
+            None,
+            Source::Editor,
+        ),
+        (
+            EventData::ProjectCreateSuccess(ProjectCreated {
+                creation_source: CreationSource::HomeGame,
+                project_template_id: None,
+            }),
+            Some("project".into()),
+            Source::Editor,
+        ),
+        (
+            EventData::ProjectOpen(ProjectOpened {
+                open_source: OpenSource::Recent,
+                is_first_open: None,
+            }),
+            Some("project".into()),
+            Source::Editor,
+        ),
+        (
+            EventData::CreativeTaskSubmit(EmptyProperties {}),
+            Some("project".into()),
+            Source::Direct,
+        ),
+        (
+            EventData::AgentRunCompleted(run()),
+            Some("project".into()),
+            Source::Direct,
+        ),
+        (
+            EventData::AgentRunFailed(failed),
+            Some("project".into()),
+            Source::Direct,
+        ),
+        (
+            EventData::ProjectRevisionCreated(RevisionCreated {
+                revision_id: "42".into(),
+                revision_source: RevisionSource::UiEditor,
+                change_kind: ChangeKind::Ui,
+                files_changed_count: Some(1),
+            }),
+            Some("project".into()),
+            Source::UiEditor,
+        ),
+        (
+            EventData::PreviewReady(PreviewReady {
+                preview_source: PreviewSource::User,
+                preview_version: "42".into(),
+                ready_duration_ms: None,
+            }),
+            Some("project".into()),
+            Source::Editor,
+        ),
+        (
+            EventData::ProjectSave(ProjectSaved {
+                save_source: SaveSource::Checkpoint,
+                revision_id: Some("42".into()),
+            }),
+            Some("project".into()),
+            Source::Manual,
+        ),
+    ];
+    values
+        .into_iter()
+        .map(|(data, project, source)| {
+            let identity = matches!(
+                data,
+                EventData::AgentRunCompleted(_) | EventData::AgentRunFailed(_)
+            )
+            .then(|| RunIdentity {
+                run_id: Uuid::new_v4().to_string(),
+                turn_id: Some("real-turn".into()),
+                error_code: matches!(data, EventData::AgentRunFailed(_))
+                    .then_some(ErrorCode::RuntimeErrorUnclassified),
+            });
+            context().capture(data, project, source, identity).unwrap()
+        })
+        .collect()
+}
+
+#[test]
+fn all_events_round_trip_with_explicit_nullable_envelopes() {
+    let events = samples();
+    assert_eq!(events.len(), 12);
+    for event in events {
+        let value = serde_json::to_value(&event).unwrap();
+        assert_eq!(value.as_object().unwrap().len(), 15);
+        let decoded: Event = serde_json::from_value(value).unwrap();
+        decoded.validate().unwrap();
+        assert_eq!(decoded.event_id, event.event_id);
+        assert_eq!(decoded.event_time, event.event_time);
+    }
+}
+
+#[test]
+fn missing_top_level_fields_and_extra_fields_are_rejected() {
+    for event in samples() {
+        let value = serde_json::to_value(event).unwrap();
+        for field in value.as_object().unwrap().keys() {
+            let mut missing = value.clone();
+            missing.as_object_mut().unwrap().remove(field);
+            assert!(
+                serde_json::from_value::<Event>(missing).is_err(),
+                "missing {field}"
+            );
+        }
+        let mut extra = value;
+        extra["prompt"] = json!("must not be accepted");
+        assert!(serde_json::from_value::<Event>(extra).is_err());
+    }
+}
+
+#[test]
+fn event_properties_are_closed_and_nullable_fields_are_required() {
+    for event in samples() {
+        let mut extra = event.clone();
+        extra.properties["access_token"] = json!("never collected");
+        assert!(extra.validate().is_err());
+        for (field, value) in event.properties.as_object().unwrap() {
+            if !value.is_null() {
+                continue;
+            }
+            let mut missing = event.clone();
+            missing.properties.as_object_mut().unwrap().remove(field);
+            assert!(
+                missing.validate().is_err(),
+                "{} missing {field}",
+                event.event_name
+            );
+        }
+    }
+    let mut nested = samples().pop().unwrap();
+    nested.properties["pending_approval"] =
+        json!({"request_id":"a", "phase":"concept", "question":"private"});
+    assert!(nested.validate().is_err());
+    nested.properties["pending_approval"] = Value::Null;
+    nested.properties["pending_clarification"] = json!({"request_id":"a", "options":[]});
+    assert!(nested.validate().is_err());
+}
+
+#[test]
+fn inconsistent_identity_status_and_numbers_are_rejected() {
+    let event = samples()
+        .into_iter()
+        .find(|e| e.event_name == "agent_run_completed")
+        .unwrap();
+    let mutate: Vec<(&str, Value)> = vec![
+        ("creative_task_id", json!("other-project")),
+        ("project_id", Value::Null),
+        ("agent_run_id", json!("project")),
+        ("status", json!("failed")),
+        ("source", json!("design_agent")),
+        ("error_code", json!("runtime_failed")),
+        ("schema_version", json!(2)),
+        ("event_time", json!("2026-09-21T00:00:00Z")),
+        ("event_id", json!("not-a-uuid")),
+        ("user_id", json!("")),
+    ];
+    for (key, value) in mutate {
+        let mut raw = serde_json::to_value(&event).unwrap();
+        raw[key] = value;
+        let invalid: Event = serde_json::from_value(raw).unwrap();
+        assert!(invalid.validate().is_err(), "{key}");
+    }
+    for (key, value) in [
+        ("duration_ms", json!(-1)),
+        ("retry_index", json!(MAX_SAFE_INTEGER + 1)),
+        ("duration_ms", json!(1.5)),
+    ] {
+        let mut invalid = event.clone();
+        invalid.properties[key] = value;
+        assert!(invalid.validate().is_err());
+    }
+}
+
+#[test]
+fn frozen_context_and_origin_do_not_inherit_new_account() {
+    let a = context();
+    let mut b = a.clone();
+    b.route = Route::from_identity(
+        Some("456".into()),
+        Some("https://other.example.com/api?token=private"),
+    );
+    let event = a
+        .capture(
+            EventData::CreativeTaskSubmit(EmptyProperties {}),
+            Some("p".into()),
+            Source::Direct,
+            None,
+        )
+        .unwrap();
+    assert_eq!(event.user_id.as_deref(), Some("123"));
+    assert_eq!(
+        a.route.destination_origin.as_deref(),
+        Some("https://example.com")
+    );
+    assert_eq!(
+        b.route.destination_origin.as_deref(),
+        Some("https://other.example.com")
+    );
+    assert_eq!(
+        Route::from_identity(None, Some("file:///private")).destination_origin,
+        None
+    );
+    assert_eq!(
+        Route::from_identity(None, Some("https://user:secret@example.com")).destination_origin,
+        None
+    );
+    assert!(
+        Route {
+            user_id: None,
+            destination_origin: Some("https://example.com/api".into())
+        }
+        .validate()
+            == false
+    );
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/design.rs

@@ -0,0 +1,55 @@
+//! 策划阶段推进按约定视为成果变化；不检查文档版本或记录工作流快照。
+use super::contract::{ChangeKind, Context, EventData, RevisionCreated, RevisionSource, Source};
+use super::store::AnalyticsWriter;
+
+pub(crate) struct PhaseChange {
+    context: Context,
+    writer: AnalyticsWriter,
+    project_id: String,
+    revision_id: String,
+}
+
+impl PhaseChange {
+    pub(crate) fn new(
+        capture: Option<(Context, AnalyticsWriter)>,
+        project_id: &str,
+        session_id: &str,
+        previous_phase: &str,
+        phase: &str,
+    ) -> Option<Self> {
+        if previous_phase == phase {
+            return None;
+        }
+        let (context, writer) = capture?;
+        Some(Self {
+            context,
+            writer,
+            project_id: project_id.to_string(),
+            revision_id: format!("design:{session_id}:{phase}"),
+        })
+    }
+
+    pub(crate) fn revision_id(&self) -> &str {
+        &self.revision_id
+    }
+
+    // 必须在阶段与审批命令成功持久化后调用，时间与事件 ID 在此刻生成。
+    pub(crate) fn record(self) {
+        let key = format!(
+            "{}:{}:project_revision_created",
+            self.project_id, self.revision_id
+        );
+        let data = EventData::ProjectRevisionCreated(RevisionCreated {
+            revision_id: self.revision_id,
+            revision_source: RevisionSource::Agent,
+            change_kind: ChangeKind::DesignDocument,
+            files_changed_count: None,
+        });
+        if let Ok(event) =
+            self.context
+                .capture(data, Some(self.project_id), Source::DesignAgent, None)
+        {
+            self.writer.try_record(self.context.route, event, key);
+        }
+    }
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/goal.rs

@@ -0,0 +1,166 @@
+//! 新建项目的目标采集资格。只在后台持锁读改写，不等待业务线程。
+use super::contract::{Context, EmptyProperties, Event, EventData, Route, Source};
+use super::store::AnalyticsWriter;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+
+const MARKER: &str = ".agent/analytics-goal.json";
+const MAX_MARKER_BYTES: usize = 4096;
+
+#[derive(Serialize)]
+pub(super) enum Request {
+    Created {
+        root: PathBuf,
+        project_id: String,
+    },
+    Accepted {
+        root: PathBuf,
+        route: Route,
+        event: Event,
+    },
+}
+
+impl Request {
+    pub(super) fn validate(&self) -> bool {
+        let (root, project_id) = match self {
+            Self::Created { root, project_id } => (root, Some(project_id.as_str())),
+            Self::Accepted { root, route, event } => {
+                if !route.validate()
+                    || route.user_id != event.user_id
+                    || event.event_name != "creative_task_submit"
+                    || event.validate().is_err()
+                    || !matches!(event.source, Source::Direct | Source::DesignAgent)
+                {
+                    return false;
+                }
+                (root, event.project_id.as_deref())
+            }
+        };
+        root.is_absolute()
+            && root.as_os_str().len() <= 32768
+            && project_id.is_some_and(|id| {
+                !id.trim().is_empty() && id.len() <= 256 && !id.chars().any(char::is_control)
+            })
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Marker {
+    schema_version: u32,
+    project_id: String,
+    submitted: bool,
+}
+
+pub(crate) fn created(writer: &AnalyticsWriter, root: &Path, project_id: &str) {
+    writer.try_goal(Request::Created {
+        root: root.into(),
+        project_id: project_id.into(),
+    });
+}
+
+pub(crate) fn accepted(
+    capture: Option<(Context, AnalyticsWriter)>,
+    root: &Path,
+    project_id: &str,
+    source: Source,
+) {
+    if !matches!(source, Source::Direct | Source::DesignAgent) {
+        return;
+    }
+    let Some((context, writer)) = capture else {
+        return;
+    };
+    let Ok(event) = context.capture(
+        EventData::CreativeTaskSubmit(EmptyProperties {}),
+        Some(project_id.into()),
+        source,
+        None,
+    ) else {
+        return;
+    };
+    writer.try_goal(Request::Accepted {
+        root: root.into(),
+        route: context.route,
+        event,
+    });
+}
+
+/// 成功消费资格才返回事件；消费后队列落盘失败允许漏记。
+pub(super) fn process(request: Request) -> Result<Option<(Route, Event)>, String> {
+    if !request.validate() {
+        return Err("invalid analytics goal request".into());
+    }
+    let (root, project_id) = match &request {
+        Request::Created { root, project_id } => (root, project_id.as_str()),
+        Request::Accepted { root, event, .. } => (root, event.project_id.as_deref().unwrap()),
+    };
+    let Some(_lock) =
+        crate::agent::try_acquire_game_creator_agent_runtime_task_lock(root, "analytics-goal")?
+    else {
+        return Ok(None);
+    };
+    let manifest_path = crate::project::resolve_local_project_path(root, ".agent/manifest.json")?;
+    if crate::project::read_manifest(&manifest_path)?.project_id != project_id {
+        return Ok(None);
+    }
+    let path = crate::project::resolve_local_project_path(root, MARKER)?;
+    let primary = std::fs::symlink_metadata(&path);
+    match &request {
+        Request::Created { .. } => {
+            // 缺失主文件但存在恢复副本仍属未知，不能重新授予资格。
+            let backup = crate::agent::agent_runtime_json_sidecar_backup_path(&path);
+            if !matches!(primary, Err(ref e) if e.kind() == std::io::ErrorKind::NotFound)
+                || !matches!(std::fs::symlink_metadata(backup), Err(ref e) if e.kind() == std::io::ErrorKind::NotFound)
+            {
+                return Ok(None);
+            }
+            crate::agent::write_agent_runtime_json_sidecar_with_max_bytes(
+                root,
+                MARKER,
+                "埋点目标资格",
+                &Marker {
+                    schema_version: 1,
+                    project_id: project_id.into(),
+                    submitted: false,
+                },
+                MAX_MARKER_BYTES,
+            )?;
+            Ok(None)
+        }
+        Request::Accepted { .. } => {
+            // 明确要求主文件存在，不启用 sidecar 的 previous 自动回退。
+            let Ok(metadata) = primary else {
+                return Ok(None);
+            };
+            if !metadata.is_file() || metadata.file_type().is_symlink() {
+                return Ok(None);
+            }
+            let Some(mut marker): Option<Marker> =
+                crate::agent::read_agent_runtime_json_sidecar_with_max_bytes(
+                    root,
+                    MARKER,
+                    "埋点目标资格",
+                    MAX_MARKER_BYTES,
+                )?
+            else {
+                return Ok(None);
+            };
+            if marker.schema_version != 1 || marker.project_id != project_id || marker.submitted {
+                return Ok(None);
+            }
+            marker.submitted = true;
+            crate::agent::write_agent_runtime_json_sidecar_with_max_bytes(
+                root,
+                MARKER,
+                "埋点目标资格",
+                &marker,
+                MAX_MARKER_BYTES,
+            )?;
+            match request {
+                Request::Accepted { route, event, .. } => Ok(Some((route, event))),
+                _ => unreachable!(),
+            }
+        }
+    }
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/gui_tests.rs

@@ -0,0 +1,189 @@
+use super::*;
+use std::fs;
+use std::time::Duration;
+
+fn state() -> (tempfile::TempDir, GuiState) {
+    let dir = tempfile::tempdir().unwrap();
+    let context = Context {
+        route: Route::from_identity(Some("A".into()), Some("https://example.com")),
+        editor_session_id: Uuid::new_v4().to_string(),
+        client_version: "1.0.0".into(),
+    };
+    let writer = AnalyticsWriter::start(dir.path().into(), context.editor_session_id.clone());
+    (dir, GuiState::new(context, 1, writer))
+}
+
+fn read_events(dir: &std::path::Path, session: &str, expected: usize) -> Vec<Event> {
+    let until = Instant::now() + Duration::from_secs(5);
+    loop {
+        let mut events = Vec::new();
+        let batches = dir
+            .join("analytics/instances")
+            .join(session)
+            .join("batches");
+        if let Ok(entries) = fs::read_dir(batches) {
+            for entry in entries.flatten() {
+                if Uuid::parse_str(&entry.file_name().to_string_lossy()).is_err() {
+                    continue;
+                }
+                if let Ok(text) = fs::read_to_string(entry.path().join("events.jsonl")) {
+                    events.extend(
+                        text.lines()
+                            .map(|line| serde_json::from_str::<Event>(line).unwrap()),
+                    );
+                }
+            }
+        }
+        if events.len() == expected {
+            return events;
+        }
+        assert!(
+            Instant::now() < until,
+            "expected {expected} events, found {}",
+            events.len()
+        );
+        std::thread::sleep(Duration::from_millis(10));
+    }
+}
+
+#[test]
+fn window_union_and_repeated_notifications_form_one_interval() {
+    let (dir, mut state) = state();
+    state.start();
+    state.windows(Some("main".into()), false, true);
+    let interval = state.focus.as_ref().unwrap().id.clone();
+    state.windows(Some("launcher".into()), false, false);
+    state.windows(Some("launcher".into()), false, false);
+    assert_eq!(state.focus.as_ref().unwrap().id, interval);
+    state.windows(None, true, false);
+    state.windows(None, true, false);
+    state.exit();
+    state.exit();
+    let events = read_events(dir.path(), &state.context.editor_session_id, 4);
+    let end = events
+        .iter()
+        .find(|e| e.event_name == "editor_focus_end")
+        .unwrap();
+    assert_eq!(end.properties["focus_interval_id"], interval);
+    assert_eq!(end.properties["blur_reason"], "minimized");
+    assert_eq!(
+        events
+            .iter()
+            .filter(|e| e.event_name == "editor_session_end")
+            .count(),
+        1
+    );
+}
+
+#[test]
+fn identity_change_splits_focus_but_refresh_and_stale_notice_do_not() {
+    let (dir, mut state) = state();
+    state.start();
+    state.windows(Some("main".into()), false, true);
+    let first = state.focus.as_ref().unwrap().id.clone();
+    open(
+        &mut state,
+        "project-a",
+        &Uuid::new_v4().to_string(),
+        "2000-01-01T00:00:00.000Z",
+    );
+    state.identity(state.context.route.clone(), 2);
+    assert_eq!(state.focus.as_ref().unwrap().id, first);
+    let route_b = Route::from_identity(Some("B".into()), Some("https://example.com"));
+    state.identity(route_b.clone(), 4);
+    state.identity(
+        Route::from_identity(Some("A".into()), Some("https://example.com")),
+        3,
+    );
+    assert_eq!(state.context.route, route_b);
+    assert!(state.projects.is_empty());
+    assert!(state.active_project.is_none());
+    assert_ne!(state.focus.as_ref().unwrap().id, first);
+    state.restart = true;
+    state.exit();
+    let events = read_events(dir.path(), &state.context.editor_session_id, 7);
+    let old_end = events
+        .iter()
+        .find(|e| e.event_name == "editor_focus_end" && e.user_id.as_deref() == Some("A"))
+        .unwrap();
+    assert_eq!(old_end.properties["blur_reason"], "account_change");
+    let new_start = events
+        .iter()
+        .find(|e| e.event_name == "editor_focus_start" && e.user_id.as_deref() == Some("B"))
+        .unwrap();
+    assert_eq!(new_start.properties["focus_reason"], "account_change");
+    assert!(new_start.project_id.is_none());
+    let end = events
+        .iter()
+        .find(|e| e.event_name == "editor_session_end")
+        .unwrap();
+    assert_eq!(end.properties["end_reason"], "app_restart");
+}
+
+fn open(state: &mut GuiState, project_id: &str, operation: &str, time: &str) {
+    state.reserve_open("main", operation, project_id, time);
+    state.project_opened(
+        "main".into(),
+        state.context.clone(),
+        OpenProject {
+            id: project_id.into(),
+            path: project_id.into(),
+            operation_id: operation.into(),
+        },
+        OpenSource::Recent,
+        time.into(),
+    );
+}
+
+#[test]
+fn explicit_reopen_records_new_operation_and_duplicate_delivery_does_not() {
+    let (dir, mut state) = state();
+    let id = Uuid::new_v4().to_string();
+    open(&mut state, "project", &id, "2026-09-21T12:00:00.001Z");
+    // 同一次已采纳操作的重复回执由幂等事实键抑制。
+    open(&mut state, "project", &id, "2026-09-21T12:00:00.001Z");
+    let next = Uuid::new_v4().to_string();
+    assert_eq!(state.projects.get("main").unwrap().operation_id, id);
+    open(&mut state, "project", &next, "2026-09-21T12:00:00.002Z");
+    state.writer.flush();
+    let events = read_events(dir.path(), &state.context.editor_session_id, 2);
+    assert!(events.iter().any(|e| e.event_id == id));
+    assert!(events.iter().any(|e| e.event_id == next));
+    assert!(events[0].properties["is_first_open"].is_null());
+    assert_eq!(events[1].properties["is_first_open"], false);
+}
+
+#[test]
+fn delayed_capture_or_manifest_read_does_not_restore_a_left_project() {
+    let (dir, mut state) = state();
+    state.windows(Some("main".into()), false, true);
+    let old = Uuid::new_v4().to_string();
+    state.reserve_open("main", &old, "old", "2026-09-21T12:00:00.001Z");
+    let new = Uuid::new_v4().to_string();
+    open(&mut state, "new", &new, "2026-09-21T12:00:00.002Z");
+    state.project_opened(
+        "main".into(),
+        state.context.clone(),
+        OpenProject {
+            id: "old".into(),
+            path: "old".into(),
+            operation_id: old,
+        },
+        OpenSource::Recent,
+        "2026-09-21T12:00:00.001Z".into(),
+    );
+    assert_eq!(state.active_project.as_deref(), Some("new"));
+    state.leave("main", Some("new"));
+    let late = Uuid::new_v4().to_string();
+    open(&mut state, "old", &late, "2000-01-01T00:00:00.000Z");
+    assert!(state.active_project.is_none());
+    state.writer.flush();
+    let events = read_events(dir.path(), &state.context.editor_session_id, 4);
+    assert_eq!(
+        events
+            .iter()
+            .filter(|e| e.event_name == "project_open")
+            .count(),
+        3
+    );
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/mod.rs

@@ -0,0 +1,10 @@
+//! 客户端产品埋点：本地采集与持久化，不发起上传。
+pub(crate) mod contract;
+pub(crate) mod design;
+pub(crate) mod goal;
+pub(crate) mod gui;
+pub(crate) mod preview;
+pub(crate) mod project;
+pub(crate) mod run;
+pub(crate) mod session;
+pub(crate) mod store;

apps/ai-game-creator-shell/src-tauri/src/analytics/preview.rs

@@ -0,0 +1,146 @@
+//! 正式 Web 预览的短时可访问性观察；不影响预览业务生命周期。
+use super::{
+    contract::{Context, EventData, PreviewReady, PreviewSource, Source},
+    store::AnalyticsWriter,
+};
+use std::{
+    path::{Path, PathBuf},
+    sync::{Arc, Weak},
+    time::{Duration, Instant},
+};
+
+pub(crate) struct Lease {
+    _alive: Arc<()>,
+}
+
+pub(crate) struct Observation {
+    alive: Weak<()>,
+    instance_id: String,
+    root: PathBuf,
+    entry: PathBuf,
+    project_id: String,
+    revision: u64,
+    context: Context,
+    writer: AnalyticsWriter,
+    source: Source,
+    preview_source: PreviewSource,
+    started: Instant,
+    cancellation: Option<Arc<std::sync::atomic::AtomicBool>>,
+}
+
+fn nonempty_entry(entry: &Path) -> bool {
+    std::fs::metadata(entry).is_ok_and(|metadata| metadata.is_file() && metadata.len() > 0)
+}
+
+pub(crate) fn prepare(
+    root: &Path,
+    capture: Option<(Context, AnalyticsWriter)>,
+    source: Source,
+    preview_source: PreviewSource,
+) -> Option<(Lease, Observation)> {
+    let (context, writer) = capture?;
+    let entry = crate::project_game_root(root).join("index.html");
+    if !nonempty_entry(&entry) {
+        return None;
+    }
+    let project_id = crate::read_existing_manifest_for_project(root)
+        .ok()?
+        .project_id;
+    let revision = crate::read_game_creator_agent_runtime_project_revision(root)
+        .ok()?
+        .revision;
+    let alive = Arc::new(());
+    let observation = Observation {
+        alive: Arc::downgrade(&alive),
+        instance_id: uuid::Uuid::new_v4().to_string(),
+        root: root.into(),
+        entry,
+        project_id,
+        revision,
+        context,
+        writer,
+        source,
+        preview_source,
+        started: Instant::now(),
+        cancellation: None,
+    };
+    Some((Lease { _alive: alive }, observation))
+}
+
+impl Observation {
+    pub(crate) fn with_cancellation(
+        mut self,
+        cancellation: Option<Arc<std::sync::atomic::AtomicBool>>,
+    ) -> Self {
+        self.cancellation = cancellation;
+        self
+    }
+
+    fn current(&self) -> bool {
+        !self
+            .cancellation
+            .as_ref()
+            .is_some_and(|flag| flag.load(std::sync::atomic::Ordering::Acquire))
+            && self.alive.strong_count() > 0
+            && self.entry == crate::project_game_root(&self.root).join("index.html")
+            && nonempty_entry(&self.entry)
+            && crate::read_game_creator_agent_runtime_project_revision(&self.root)
+                .is_ok_and(|revision| revision.revision == self.revision)
+            && crate::read_existing_manifest_for_project(&self.root)
+                .is_ok_and(|manifest| manifest.project_id == self.project_id)
+    }
+
+    pub(crate) fn schedule(self, port: u16) {
+        tauri::async_runtime::spawn(self.observe(port));
+    }
+
+    pub(crate) async fn observe(self, port: u16) {
+        if !self.current() {
+            return;
+        }
+        let reachable = tokio::time::timeout(Duration::from_secs(2), async {
+            let client = reqwest::Client::builder()
+                .no_proxy()
+                .redirect(reqwest::redirect::Policy::none())
+                .build()
+                .ok()?;
+            let mut response = client
+                .get(format!("http://127.0.0.1:{port}/"))
+                .send()
+                .await
+                .ok()?;
+            if !response.status().is_success() {
+                return None;
+            }
+            while let Some(chunk) = response.chunk().await.ok()? {
+                if !chunk.is_empty() {
+                    return Some(());
+                }
+            }
+            None
+        })
+        .await;
+        if !matches!(reachable, Ok(Some(()))) || !self.current() {
+            return;
+        }
+        let event = self.context.capture(
+            EventData::PreviewReady(PreviewReady {
+                preview_source: self.preview_source,
+                preview_version: self.revision.to_string(),
+                ready_duration_ms: u64::try_from(self.started.elapsed().as_millis()).ok(),
+            }),
+            Some(self.project_id.clone()),
+            self.source,
+            None,
+        );
+        if let Ok(event) = event {
+            if self.current() {
+                let key = format!(
+                    "{}:{}:{}:preview_ready",
+                    self.project_id, self.instance_id, self.revision
+                );
+                self.writer.try_record(self.context.route, event, key);
+            }
+        }
+    }
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/project.rs

@@ -0,0 +1,104 @@
+//! 正式项目成果事件。只接收宿主已提交的版本，不参与业务写入。
+use super::contract::{ChangeKind, Context, EventData, ProjectSaved, RevisionCreated, Source};
+use super::store::AnalyticsWriter;
+use std::io::Read;
+use std::path::Path;
+
+pub(crate) fn saved(
+    capture: Option<(Context, AnalyticsWriter)>,
+    project_id: &str,
+    source: Source,
+    operation_id: &str,
+    data: ProjectSaved,
+    event_time: Option<&str>,
+) {
+    let Some((context, writer)) = capture else {
+        return;
+    };
+    if let Ok(mut event) = context.capture(
+        EventData::ProjectSave(data),
+        Some(project_id.into()),
+        source,
+        None,
+    ) {
+        if let Some(time) = event_time {
+            event.event_time = time.into();
+        }
+        writer.try_record(
+            context.route,
+            event,
+            format!("{project_id}:{operation_id}:project_save"),
+        );
+    }
+}
+
+pub(crate) fn file_content_changed(
+    root: &Path,
+    path: &str,
+    content: &[u8],
+    max_bytes: u64,
+) -> Option<bool> {
+    let target = crate::resolve_local_project_path(root, path).ok()?;
+    match std::fs::symlink_metadata(&target) {
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Some(true),
+        Err(_) => return None,
+        Ok(_) => {}
+    }
+    let (file, metadata) =
+        crate::open_project_snapshot_regular_file(&target, "成果内容比较").ok()?;
+    if metadata.len() > max_bytes {
+        return None;
+    }
+    let mut before = Vec::new();
+    file.take(max_bytes.saturating_add(1))
+        .read_to_end(&mut before)
+        .ok()?;
+    (before.len() as u64 <= max_bytes).then(|| before != content)
+}
+
+pub(crate) fn revision(
+    capture: Option<(Context, AnalyticsWriter)>,
+    project_id: &str,
+    source: Source,
+    data: RevisionCreated,
+) {
+    let Some((context, writer)) = capture else {
+        return;
+    };
+    let key = format!("{project_id}:{}:project_revision_created", data.revision_id);
+    if let Ok(event) = context.capture(
+        EventData::ProjectRevisionCreated(data),
+        Some(project_id.into()),
+        source,
+        None,
+    ) {
+        writer.try_record(context.route, event, key);
+    }
+}
+
+// 只给已知成果分类；未知文件不猜字段，控制面和构建缓存不计成果。
+pub(crate) fn file_change_kind(path: &str) -> Option<ChangeKind> {
+    let path = path.to_ascii_lowercase();
+    if crate::should_skip_project_snapshot_path(&path)
+        || path.split('/').any(|part| part.starts_with('.'))
+    {
+        return None;
+    }
+    if path.starts_with("design_artifacts/") {
+        return Some(ChangeKind::DesignDocument);
+    }
+    if path.starts_with("ui/") {
+        return Some(ChangeKind::Ui);
+    }
+    let extension = path.rsplit_once('.')?.1;
+    match extension {
+        "png" | "jpg" | "jpeg" | "webp" | "gif" | "svg" | "avif" | "mp3" | "wav" | "ogg"
+        | "flac" | "mp4" | "webm" | "glb" | "gltf" | "ttf" | "woff" | "woff2" => {
+            Some(ChangeKind::Asset)
+        }
+        "js" | "jsx" | "ts" | "tsx" | "mjs" | "cjs" | "html" | "css" | "scss" | "json" | "vue"
+        | "svelte" | "gd" | "tscn" | "tres" | "cs" | "shader" | "glsl" | "wgsl" | "vert"
+        | "frag" | "rs" | "py" | "lua" | "cpp" | "h" | "c" | "hpp" => Some(ChangeKind::Code),
+        _ => None,
+    }
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/run.rs

@@ -0,0 +1,400 @@
+//! 可观测运行序号和终态消费。双 Agent 各保留一个槽位，不保存历史或身份。
+use super::contract::{
+    self, AgentType, Context, ErrorCode, Event, EventData, Route, RunEndReason, RunFinished,
+    RunIdentity, RunSource, Source,
+};
+use super::store::AnalyticsWriter;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+
+const PATH: &str = ".agent/analytics-runs.json";
+const MAX_BYTES: usize = 4096;
+const MAX_INTEGER: u64 = 9_007_199_254_740_991;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct Metadata {
+    pub context: Context,
+    pub run_id: String,
+    pub terminal_event_id: String,
+    pub source: Source,
+    pub run_source: RunSource,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_revision: Option<String>,
+}
+
+impl Metadata {
+    pub(crate) fn new(context: Context, source: Source, run_source: RunSource) -> Self {
+        Self {
+            context,
+            source,
+            run_source,
+            run_id: uuid::Uuid::new_v4().to_string(),
+            terminal_event_id: uuid::Uuid::new_v4().to_string(),
+            output_revision: None,
+        }
+    }
+    fn validate(&self) -> bool {
+        matches!(self.source, Source::Direct | Source::DesignAgent)
+            && uuid::Uuid::parse_str(&self.run_id).is_ok()
+            && uuid::Uuid::parse_str(&self.terminal_event_id).is_ok()
+            && self.context.route.validate()
+            && self.output_revision.as_deref().is_none_or(valid_id)
+    }
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub(crate) struct Outcome {
+    pub turn_id: Option<String>,
+    pub end_reason: RunEndReason,
+    pub error_code: Option<ErrorCode>,
+    pub duration_ms: Option<u64>,
+    pub output_change_detected: Option<bool>,
+    pub revision_id: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(super) enum Request {
+    DirectCandidate {
+        attempt_id: String,
+        terminal: Box<Request>,
+    },
+    Settle {
+        editor_session_id: String,
+        attempt_id: String,
+        discard: bool,
+    },
+    Accepted {
+        root: PathBuf,
+        project_id: String,
+        metadata: Metadata,
+    },
+    Terminal {
+        root: PathBuf,
+        project_id: String,
+        metadata: Metadata,
+        context: Context,
+        event_time: String,
+        outcome: Outcome,
+    },
+}
+
+impl Request {
+    pub(super) fn session_id(&self) -> &str {
+        match self {
+            Self::DirectCandidate { terminal, .. } => terminal.session_id(),
+            Self::Settle {
+                editor_session_id, ..
+            } => editor_session_id,
+            Self::Accepted { metadata, .. } => &metadata.context.editor_session_id,
+            Self::Terminal { context, .. } => &context.editor_session_id,
+        }
+    }
+    pub(super) fn validate(&self) -> bool {
+        match self {
+            Self::DirectCandidate {
+                attempt_id,
+                terminal,
+            } => {
+                return uuid::Uuid::parse_str(attempt_id).is_ok()
+                    && matches!(terminal.as_ref(), Self::Terminal { metadata, .. } if metadata.source == Source::Direct)
+                    && terminal.validate();
+            }
+            Self::Settle {
+                editor_session_id,
+                attempt_id,
+                ..
+            } => {
+                return uuid::Uuid::parse_str(editor_session_id).is_ok()
+                    && uuid::Uuid::parse_str(attempt_id).is_ok();
+            }
+            _ => {}
+        }
+        let (root, project_id, metadata) = match self {
+            Self::Accepted {
+                root,
+                project_id,
+                metadata,
+            } => (root, project_id, metadata),
+            Self::Terminal {
+                root,
+                project_id,
+                metadata,
+                ..
+            } => (root, project_id, metadata),
+            _ => return false,
+        };
+        root.is_absolute()
+            && root.as_os_str().len() <= 32768
+            && valid_id(project_id)
+            && metadata.validate()
+    }
+}
+
+pub(crate) fn accepted(
+    writer: &AnalyticsWriter,
+    root: &Path,
+    project_id: &str,
+    metadata: &Metadata,
+) {
+    writer.try_run(Request::Accepted {
+        root: root.into(),
+        project_id: project_id.into(),
+        metadata: metadata.clone(),
+    });
+}
+
+pub(crate) fn finished(
+    capture: Option<(Context, AnalyticsWriter)>,
+    root: &Path,
+    project_id: &str,
+    metadata: &Metadata,
+    outcome: Outcome,
+) {
+    let Some((mut context, writer)) = capture else {
+        return;
+    };
+    // 恢复后的 GUI 会话属于新实例，但账号和目标平台仍属于原运行。
+    context.route = metadata.context.route.clone();
+    writer.try_run(Request::Terminal {
+        root: root.into(),
+        project_id: project_id.into(),
+        metadata: metadata.clone(),
+        context,
+        event_time: contract::timestamp_now(),
+        outcome,
+    });
+}
+
+pub(crate) fn direct_finished(
+    capture: Option<(Context, AnalyticsWriter)>,
+    root: &Path,
+    project_id: &str,
+    metadata: &Metadata,
+    attempt_id: Option<&str>,
+    outcome: Outcome,
+) {
+    let Some(attempt_id) = attempt_id else { return };
+    let Some((mut context, writer)) = capture else {
+        return;
+    };
+    if metadata.source != Source::Direct {
+        return;
+    }
+    context.route = metadata.context.route.clone();
+    writer.try_run(Request::DirectCandidate {
+        attempt_id: attempt_id.into(),
+        terminal: Box::new(Request::Terminal {
+            root: root.into(),
+            project_id: project_id.into(),
+            metadata: metadata.clone(),
+            context,
+            event_time: contract::timestamp_now(),
+            outcome,
+        }),
+    });
+}
+
+pub(crate) fn settle(capture: Option<(Context, AnalyticsWriter)>, attempt_id: &str, discard: bool) {
+    let Some((context, writer)) = capture else {
+        return;
+    };
+    writer.try_run(Request::Settle {
+        editor_session_id: context.editor_session_id,
+        attempt_id: attempt_id.into(),
+        discard,
+    });
+}
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Slot {
+    run_id: String,
+    retry_index: u64,
+    terminal_consumed: bool,
+}
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct State {
+    schema_version: u32,
+    project_id: String,
+    retry_count: u64,
+    direct: Option<Slot>,
+    design: Option<Slot>,
+}
+
+impl State {
+    fn slot(&mut self, source: Source) -> &mut Option<Slot> {
+        if source == Source::Direct {
+            &mut self.direct
+        } else {
+            &mut self.design
+        }
+    }
+    fn validate(&self, project_id: &str) -> bool {
+        self.schema_version == 1
+            && self.project_id == project_id
+            && self.retry_count <= MAX_INTEGER
+            && [&self.direct, &self.design]
+                .into_iter()
+                .flatten()
+                .all(|slot| {
+                    uuid::Uuid::parse_str(&slot.run_id).is_ok()
+                        && slot.retry_index <= self.retry_count
+                })
+    }
+}
+
+fn valid_id(value: &str) -> bool {
+    !value.trim().is_empty() && value.len() <= 256 && !value.chars().any(char::is_control)
+}
+
+pub(super) fn process(request: Request) -> Result<Option<(Route, Event)>, String> {
+    if !request.validate() {
+        return Ok(None);
+    }
+    let (root, project_id, metadata) = match &request {
+        Request::Accepted {
+            root,
+            project_id,
+            metadata,
+        }
+        | Request::Terminal {
+            root,
+            project_id,
+            metadata,
+            ..
+        } => (root, project_id, metadata),
+        _ => return Ok(None),
+    };
+    let Some(_lock) =
+        crate::agent::try_acquire_game_creator_agent_runtime_task_lock(root, "analytics-runs")?
+    else {
+        return Ok(None);
+    };
+    let manifest_path = crate::project::resolve_local_project_path(root, ".agent/manifest.json")?;
+    if crate::project::read_manifest(&manifest_path)?.project_id != *project_id {
+        return Ok(None);
+    }
+    let path = crate::project::resolve_local_project_path(root, PATH)?;
+    let mut state = match std::fs::symlink_metadata(&path) {
+        Ok(meta) if meta.is_file() && !meta.file_type().is_symlink() => {
+            let Some(state): Option<State> =
+                crate::agent::read_agent_runtime_json_sidecar_with_max_bytes(
+                    root,
+                    PATH,
+                    "运行埋点序号",
+                    MAX_BYTES,
+                )?
+            else {
+                return Ok(None);
+            };
+            if !state.validate(project_id) {
+                return Ok(None);
+            }
+            state
+        }
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            if !matches!(request, Request::Accepted { .. }) {
+                return Ok(None);
+            }
+            let backup = crate::agent::agent_runtime_json_sidecar_backup_path(&path);
+            if !matches!(std::fs::symlink_metadata(backup), Err(ref e) if e.kind() == std::io::ErrorKind::NotFound)
+            {
+                return Ok(None);
+            }
+            State {
+                schema_version: 1,
+                project_id: project_id.clone(),
+                retry_count: 0,
+                direct: None,
+                design: None,
+            }
+        }
+        _ => return Ok(None),
+    };
+    let event = match &request {
+        Request::Accepted { .. } => {
+            if state
+                .slot(metadata.source)
+                .as_ref()
+                .is_some_and(|slot| slot.run_id == metadata.run_id)
+            {
+                return Ok(None);
+            }
+            if metadata.run_source == RunSource::UserRetry {
+                if state.retry_count == MAX_INTEGER {
+                    return Ok(None);
+                }
+                state.retry_count += 1;
+            }
+            let ordinal = state.retry_count;
+            *state.slot(metadata.source) = Some(Slot {
+                run_id: metadata.run_id.clone(),
+                retry_index: ordinal,
+                terminal_consumed: false,
+            });
+            None
+        }
+        Request::Terminal {
+            context,
+            event_time,
+            outcome,
+            ..
+        } => {
+            let Some(slot) = state.slot(metadata.source) else {
+                return Ok(None);
+            };
+            if slot.run_id != metadata.run_id || slot.terminal_consumed {
+                return Ok(None);
+            }
+            let data = RunFinished {
+                agent_type: if metadata.source == Source::Direct {
+                    AgentType::GameAgent
+                } else {
+                    AgentType::DesignAgent
+                },
+                run_source: metadata.run_source,
+                duration_ms: outcome.duration_ms,
+                retry_index: slot.retry_index,
+                output_change_detected: outcome.output_change_detected,
+                revision_id: outcome.revision_id.clone(),
+                end_reason: outcome.end_reason,
+            };
+            let data = if outcome.end_reason == RunEndReason::Failed {
+                EventData::AgentRunFailed(data)
+            } else {
+                EventData::AgentRunCompleted(data)
+            };
+            let Ok(mut event) = context.capture(
+                data,
+                Some(project_id.clone()),
+                metadata.source,
+                Some(RunIdentity {
+                    run_id: metadata.run_id.clone(),
+                    turn_id: outcome.turn_id.clone(),
+                    error_code: outcome.error_code,
+                }),
+            ) else {
+                return Ok(None);
+            };
+            event.event_id = metadata.terminal_event_id.clone();
+            event.event_time = event_time.clone();
+            if event.validate().is_err() {
+                return Ok(None);
+            }
+            slot.terminal_consumed = true;
+            Some((context.route.clone(), event))
+        }
+        _ => return Ok(None),
+    };
+    crate::agent::write_agent_runtime_json_sidecar_with_max_bytes(
+        root,
+        PATH,
+        "运行埋点序号",
+        &state,
+        MAX_BYTES,
+    )?;
+    Ok(event)
+}

apps/ai-game-creator-shell/src-tauri/src/analytics/session.rs

@@ -0,0 +1,248 @@
+//! 实例所有权与本地会话状态；仅后台 writer 访问磁盘。
+use super::contract::Route;
+use super::store::{invalid_data, read_bounded, safe_metadata};
+use serde::{Deserialize, Serialize};
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, Write};
+use std::path::Path;
+use std::time::{Duration, SystemTime};
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum LifecycleState {
+    Active,
+    Closed,
+    Incomplete,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct SessionRecord {
+    pub schema_version: u32,
+    pub editor_session_id: String,
+    pub route: Route,
+    pub lifecycle_state: LifecycleState,
+    pub focus_interval_id: Option<String>,
+    pub updated_at: String,
+    pub incomplete_detected_at: Option<String>,
+}
+
+impl SessionRecord {
+    pub(crate) fn validate(&self) -> bool {
+        self.updated_at.len() <= 64
+            && self
+                .incomplete_detected_at
+                .as_ref()
+                .is_none_or(|s| s.len() <= 64)
+            && self.route.user_id.as_ref().is_none_or(|s| s.len() <= 4096)
+            && self
+                .route
+                .destination_origin
+                .as_ref()
+                .is_none_or(|s| s.len() <= 4096)
+            && self.schema_version == 1
+            && uuid::Uuid::parse_str(&self.editor_session_id).is_ok()
+            && self.route.validate()
+            && self
+                .focus_interval_id
+                .as_ref()
+                .is_none_or(|id| uuid::Uuid::parse_str(id).is_ok())
+            && chrono::DateTime::parse_from_rfc3339(&self.updated_at).is_ok()
+            && self
+                .incomplete_detected_at
+                .as_ref()
+                .is_none_or(|s| chrono::DateTime::parse_from_rfc3339(s).is_ok())
+            && (self.lifecycle_state == LifecycleState::Incomplete)
+                == self.incomplete_detected_at.is_some()
+    }
+}
+
+pub(super) fn claim(instance: &Path) -> io::Result<File> {
+    let path = instance.join("owner.lock");
+    if path.exists() {
+        safe_metadata(&path)?;
+    }
+    let file = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .open(path)?;
+    file.try_lock().map_err(|_| invalid_data())?;
+    Ok(file)
+}
+
+fn existing_owner(instance: &Path) -> io::Result<File> {
+    let path = instance.join("owner.lock");
+    if !safe_metadata(&path)?.is_file() {
+        return Err(invalid_data());
+    }
+    let file = OpenOptions::new().read(true).write(true).open(path)?;
+    file.try_lock().map_err(|_| invalid_data())?;
+    Ok(file)
+}
+
+pub(super) fn write(instance: &Path, record: &SessionRecord, session: &str) -> io::Result<()> {
+    if !record.validate() || record.editor_session_id != session {
+        return Err(invalid_data());
+    }
+    let bytes = serde_json::to_vec(record)?;
+    if bytes.len() > 16 * 1024 {
+        return Err(invalid_data());
+    }
+    let target = instance.join("session.json");
+    if target.exists() {
+        safe_metadata(&target)?;
+    }
+    let temporary = instance.join(format!(".session-{}.tmp", uuid::Uuid::new_v4()));
+    let result = (|| {
+        let mut file = OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&temporary)?;
+        file.write_all(&bytes)?;
+        file.sync_all()?;
+        drop(file);
+        fs::rename(&temporary, target)
+    })();
+    if result.is_err() {
+        let _ = fs::remove_file(temporary);
+    }
+    result
+}
+
+fn read(instance: &Path) -> io::Result<SessionRecord> {
+    let record: SessionRecord =
+        serde_json::from_slice(&read_bounded(&instance.join("session.json"), 16 * 1024)?)?;
+    if !record.validate()
+        || instance.file_name().and_then(|s| s.to_str()) != Some(record.editor_session_id.as_str())
+    {
+        return Err(invalid_data());
+    }
+    Ok(record)
+}
+
+pub(super) fn recover(instances: &Path, current: &str) {
+    let Ok(entries) = fs::read_dir(instances) else {
+        return;
+    };
+    for entry in entries.flatten() {
+        if entry.file_name() == current || !safe_metadata(&entry.path()).is_ok_and(|m| m.is_dir()) {
+            continue;
+        }
+        let Ok(_owner) = existing_owner(&entry.path()) else {
+            continue;
+        };
+        let Ok(mut record) = read(&entry.path()) else {
+            continue;
+        };
+        if record.lifecycle_state != LifecycleState::Active {
+            continue;
+        }
+        record.lifecycle_state = LifecycleState::Incomplete;
+        record.incomplete_detected_at = Some(super::contract::timestamp_now());
+        let _ = write(&entry.path(), &record, &record.editor_session_id);
+    }
+}
+
+pub(super) fn prune(
+    instances: &Path,
+    current: &str,
+    reserve: u64,
+    limit: u64,
+    retention: Duration,
+    size: impl Fn() -> u64,
+) {
+    let Ok(entries) = fs::read_dir(instances) else {
+        return;
+    };
+    let mut candidates = Vec::new();
+    let mut inactive = Vec::new();
+    for entry in entries.flatten() {
+        if entry.file_name() == current
+            || uuid::Uuid::parse_str(&entry.file_name().to_string_lossy()).is_err()
+            || !safe_metadata(&entry.path()).is_ok_and(|m| m.is_dir())
+        {
+            continue;
+        }
+        // 文件锁是存活证明；损坏或未写完的 JSON 不能永久阻止队列清理。
+        let Ok(_owner) = existing_owner(&entry.path()) else {
+            continue;
+        };
+        let Ok(files) = fs::read_dir(entry.path()) else {
+            continue;
+        };
+        for file in files.flatten() {
+            let name = file.file_name();
+            let name = name.to_string_lossy();
+            let temporary = name
+                .strip_prefix(".session-")
+                .and_then(|name| name.strip_suffix(".tmp"))
+                .is_some_and(|id| uuid::Uuid::parse_str(id).is_ok());
+            if name != "session.json" && !temporary {
+                continue;
+            }
+            let Ok(meta) = safe_metadata(&file.path()) else {
+                continue;
+            };
+            if !meta.is_file() {
+                continue;
+            }
+            let Ok(modified) = meta.modified() else {
+                continue;
+            };
+            candidates.push((modified, entry.path(), file.path()));
+        }
+        inactive.push(entry.path());
+    }
+    candidates.sort_by_key(|(modified, _, _)| *modified);
+    for (modified, instance, path) in candidates {
+        let expired = SystemTime::now()
+            .duration_since(modified)
+            .is_ok_and(|age| age >= retention);
+        if !expired && size().saturating_add(reserve) <= limit {
+            continue;
+        }
+        let Ok(_owner) = existing_owner(&instance) else {
+            continue;
+        };
+        if safe_metadata(&path).is_ok_and(|meta| meta.is_file()) {
+            let _ = fs::remove_file(path);
+        }
+    }
+    for instance in inactive {
+        let Ok(_owner) = existing_owner(&instance) else {
+            continue;
+        };
+        remove_empty_instance(&instance);
+    }
+}
+
+fn remove_empty_instance(instance: &Path) {
+    // 只删除空目录及普通 owner.lock，不递归删除未知文件或跟随链接。
+    let batches = instance.join("batches");
+    if safe_metadata(&batches).is_ok_and(|meta| meta.is_dir()) {
+        let _ = fs::remove_dir(&batches);
+    }
+    let Ok(entries) = fs::read_dir(instance) else {
+        return;
+    };
+    let Ok(entries) = entries.collect::<Result<Vec<_>, _>>() else {
+        return;
+    };
+    if entries.len() != 1 || entries[0].file_name() != "owner.lock" {
+        return;
+    }
+    let owner = instance.join("owner.lock");
+    if !safe_metadata(&owner).is_ok_and(|meta| meta.is_file()) {
+        return;
+    }
+    // 调用者仍持有锁；实例 UUID 不复用，其他清理者不能同时取得所有权。
+    if fs::remove_file(owner).is_ok() {
+        let _ = fs::remove_dir(instance);
+    }
+}
+
+#[cfg(test)]
+#[path = "session_tests.rs"]
+mod tests;

apps/ai-game-creator-shell/src-tauri/src/analytics/session_tests.rs

@@ -0,0 +1,101 @@
+use super::*;
+
+fn fixture() -> (tempfile::TempDir, std::path::PathBuf, SessionRecord) {
+    let dir = tempfile::tempdir().unwrap();
+    let id = uuid::Uuid::new_v4().to_string();
+    let instance = dir.path().join(&id);
+    fs::create_dir(&instance).unwrap();
+    let record = SessionRecord {
+        schema_version: 1,
+        editor_session_id: id,
+        route: Route {
+            user_id: Some("user".into()),
+            destination_origin: Some("https://example.com".into()),
+        },
+        lifecycle_state: LifecycleState::Active,
+        focus_interval_id: None,
+        updated_at: "2026-09-21T00:00:00.000Z".into(),
+        incomplete_detected_at: None,
+    };
+    (dir, instance, record)
+}
+
+#[test]
+fn locked_owner_is_live_and_released_owner_is_recovered_once() {
+    let (dir, path, record) = fixture();
+    let owner = claim(&path).unwrap();
+    write(&path, &record, &record.editor_session_id).unwrap();
+    recover(dir.path(), "another");
+    assert_eq!(read(&path).unwrap().lifecycle_state, LifecycleState::Active);
+    drop(owner);
+    recover(dir.path(), "another");
+    let recovered = read(&path).unwrap();
+    assert_eq!(recovered.lifecycle_state, LifecycleState::Incomplete);
+    assert_eq!(recovered.updated_at, record.updated_at);
+    let bytes = fs::read(path.join("session.json")).unwrap();
+    recover(dir.path(), "another");
+    assert_eq!(fs::read(path.join("session.json")).unwrap(), bytes);
+}
+
+#[test]
+fn missing_proof_and_wrong_identity_are_untouched() {
+    let (dir, path, record) = fixture();
+    write(&path, &record, &record.editor_session_id).unwrap();
+    recover(dir.path(), "another");
+    assert_eq!(read(&path).unwrap().lifecycle_state, LifecycleState::Active);
+    drop(claim(&path).unwrap());
+    let mut wrong = record.clone();
+    wrong.editor_session_id = uuid::Uuid::new_v4().to_string();
+    fs::write(
+        path.join("session.json"),
+        serde_json::to_vec(&wrong).unwrap(),
+    )
+    .unwrap();
+    let before = fs::read(path.join("session.json")).unwrap();
+    recover(dir.path(), "another");
+    assert_eq!(fs::read(path.join("session.json")).unwrap(), before);
+}
+
+#[test]
+fn metadata_prune_skips_live_owner_and_removes_inactive_record() {
+    let (dir, path, mut record) = fixture();
+    let owner = claim(&path).unwrap();
+    record.lifecycle_state = LifecycleState::Closed;
+    write(&path, &record, &record.editor_session_id).unwrap();
+    prune(dir.path(), "other", 0, 0, Duration::ZERO, || 100);
+    assert!(path.join("session.json").exists());
+    drop(owner);
+    prune(dir.path(), "other", 0, 0, Duration::ZERO, || 100);
+    assert!(!path.join("session.json").exists());
+}
+
+#[test]
+fn corrupt_and_abandoned_session_files_are_bounded_and_empty_instance_is_removed() {
+    let (dir, path, _) = fixture();
+    drop(claim(&path).unwrap());
+    fs::create_dir(path.join("batches")).unwrap();
+    fs::write(path.join("session.json"), b"broken-json").unwrap();
+    let temporary = path.join(format!(".session-{}.tmp", uuid::Uuid::new_v4()));
+    fs::write(&temporary, b"unfinished").unwrap();
+    prune(dir.path(), "other", 0, u64::MAX, Duration::ZERO, || 100);
+    assert!(!path.exists());
+}
+
+#[test]
+fn pressure_prunes_corrupt_metadata_but_keeps_live_and_unknown_files() {
+    let (dir, path, _) = fixture();
+    let owner = claim(&path).unwrap();
+    fs::write(path.join("session.json"), b"broken").unwrap();
+    let temporary = path.join(format!(".session-{}.tmp", uuid::Uuid::new_v4()));
+    fs::write(&temporary, b"unfinished").unwrap();
+    fs::write(path.join("unknown.json"), b"untouched").unwrap();
+    prune(dir.path(), "other", 1, 0, Duration::MAX, || 100);
+    assert!(path.join("session.json").exists());
+    assert!(temporary.exists());
+    drop(owner);
+    prune(dir.path(), "other", 1, 0, Duration::MAX, || 100);
+    assert!(!path.join("session.json").exists());
+    assert!(!temporary.exists());
+    assert!(path.join("unknown.json").exists());
+    assert!(path.join("owner.lock").exists());
+}

apps/ai-game-creator-shell/src-tauri/src/commands.rs

@@ -590,11 +590,26 @@ pub(crate) fn create_automatic_local_game_project(
     planning: Option<bool>,
     projects_root: Option<String>,
 ) -> Result<InitLocalProjectResult, String> {
-    create_automatic_local_game_project_at(
+    let analytics_context = crate::analytics::gui::capture_analytics_context();
+    let result = create_automatic_local_game_project_at(
         &resolve_game_project_creation_root(&app, projects_root.as_deref())?,
         name.as_deref(),
         planning.unwrap_or(false),
-    )
+    );
+    if let Ok(project) = &result {
+        crate::analytics::gui::created(
+            analytics_context,
+            Path::new(&project.project_path),
+            project.manifest.project_id.clone(),
+            if planning.unwrap_or(false) {
+                crate::analytics::contract::CreationSource::HomeDesign
+            } else {
+                crate::analytics::contract::CreationSource::HomeGame
+            },
+            None,
+        );
+    }
+    result
 }
 
 #[tauri::command]
@@ -603,10 +618,24 @@ pub(crate) fn init_local_game_project(
     project_id: String,
     name: String,
 ) -> Result<InitLocalProjectResult, String> {
+    let analytics_context = crate::analytics::gui::capture_analytics_context();
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "project.create")?;
     let _lock = acquire_project_write_lock(root, "project.create")?;
-    init_local_game_project_at(root, project_id.trim(), name.trim())
+    let new_project = matches!(fs::symlink_metadata(root.join(".agent/manifest.json")), Err(error) if error.kind() == std::io::ErrorKind::NotFound);
+    let result = init_local_game_project_at(root, project_id.trim(), name.trim());
+    if new_project {
+        if let Ok(project) = &result {
+            crate::analytics::gui::created(
+                analytics_context,
+                Path::new(&project.project_path),
+                project.manifest.project_id.clone(),
+                crate::analytics::contract::CreationSource::SelectedDirectory,
+                None,
+            );
+        }
+    }
+    result
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
@@ -649,13 +678,27 @@ pub(crate) fn import_local_godot_project(
     project_id: String,
     name: String,
 ) -> Result<InitLocalProjectResult, String> {
+    let analytics_context = crate::analytics::gui::capture_analytics_context();
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "project.create")?;
     if discover_local_godot_project_root(root)?.is_none() {
         return Err("所选工作区未在根目录或一层子目录发现 project.godot".to_string());
     }
     let _lock = acquire_project_write_lock(root, "project.create")?;
-    import_local_godot_project_at(root, project_id.trim(), name.trim())
+    let new_project = matches!(fs::symlink_metadata(root.join(".agent/manifest.json")), Err(error) if error.kind() == std::io::ErrorKind::NotFound);
+    let result = import_local_godot_project_at(root, project_id.trim(), name.trim());
+    if new_project {
+        if let Ok(project) = &result {
+            crate::analytics::gui::created(
+                analytics_context,
+                Path::new(&project.project_path),
+                project.manifest.project_id.clone(),
+                crate::analytics::contract::CreationSource::SelectedDirectory,
+                None,
+            );
+        }
+    }
+    result
 }
 
 #[tauri::command]
@@ -664,6 +707,7 @@ pub(crate) fn import_local_cocos_project(
     project_id: String,
     name: String,
 ) -> Result<InitLocalProjectResult, String> {
+    let analytics_context = crate::analytics::gui::capture_analytics_context();
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "project.create")?;
     if discover_local_cocos_project_root(root)?.is_none() {
@@ -673,7 +717,20 @@ pub(crate) fn import_local_cocos_project(
         );
     }
     let _lock = acquire_project_write_lock(root, "project.create")?;
-    import_local_cocos_project_at(root, project_id.trim(), name.trim())
+    let new_project = matches!(fs::symlink_metadata(root.join(".agent/manifest.json")), Err(error) if error.kind() == std::io::ErrorKind::NotFound);
+    let result = import_local_cocos_project_at(root, project_id.trim(), name.trim());
+    if new_project {
+        if let Ok(project) = &result {
+            crate::analytics::gui::created(
+                analytics_context,
+                Path::new(&project.project_path),
+                project.manifest.project_id.clone(),
+                crate::analytics::contract::CreationSource::SelectedDirectory,
+                None,
+            );
+        }
+    }
+    result
 }
 
 #[tauri::command]
@@ -682,13 +739,27 @@ pub(crate) fn import_local_unity_project(
     project_id: String,
     name: String,
 ) -> Result<InitLocalProjectResult, String> {
+    let analytics_context = crate::analytics::gui::capture_analytics_context();
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "project.create")?;
     if discover_local_unity_project_root(root)?.is_none() {
         return Err("所选目录不是有效的 Unity 项目".to_string());
     }
     let _lock = acquire_project_write_lock(root, "project.create")?;
-    import_local_unity_project_at(root, project_id.trim(), name.trim())
+    let new_project = matches!(fs::symlink_metadata(root.join(".agent/manifest.json")), Err(error) if error.kind() == std::io::ErrorKind::NotFound);
+    let result = import_local_unity_project_at(root, project_id.trim(), name.trim());
+    if new_project {
+        if let Ok(project) = &result {
+            crate::analytics::gui::created(
+                analytics_context,
+                Path::new(&project.project_path),
+                project.manifest.project_id.clone(),
+                crate::analytics::contract::CreationSource::SelectedDirectory,
+                None,
+            );
+        }
+    }
+    result
 }
 
 #[tauri::command]
@@ -5681,11 +5752,79 @@ pub(crate) fn write_local_project_file(
     relative_path: String,
     content: String,
 ) -> Result<LocalProjectFileMutationResult, String> {
+    write_local_project_file_with_capture(
+        project_path,
+        relative_path,
+        content,
+        crate::analytics::gui::capture_writer_context(),
+    )
+}
+
+type ManualAnalyticsCapture = Option<(
+    crate::analytics::contract::Context,
+    crate::analytics::store::AnalyticsWriter,
+)>;
+
+#[cfg(test)]
+#[path = "commands_manual_analytics_tests.rs"]
+mod manual_analytics_tests;
+
+fn write_local_project_file_with_capture(
+    project_path: String,
+    relative_path: String,
+    content: String,
+    capture: ManualAnalyticsCapture,
+) -> Result<LocalProjectFileMutationResult, String> {
+    use crate::analytics::{
+        contract::{ProjectSaved, RevisionCreated, RevisionSource, SaveSource, Source},
+        project,
+    };
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "file.write")?;
     let _lock = acquire_project_write_lock(root, "file.write")?;
-    advance_agent_runtime_project_revision_locked(root)?;
-    write_local_project_file_at(root, relative_path.trim(), &content)
+    let project_id = capture
+        .as_ref()
+        .and_then(|_| read_existing_manifest_for_project(root).ok())
+        .map(|manifest| manifest.project_id);
+    let kind = normalize_relative_path(relative_path.trim())
+        .ok()
+        .and_then(|path| project::file_change_kind(&path));
+    let changed = project_id
+        .as_ref()
+        .and_then(|_| kind.as_ref())
+        .and_then(|_| {
+            project::file_content_changed(root, relative_path.trim(), content.as_bytes(), 1_500_000)
+        });
+    let operation_id = uuid::Uuid::new_v4().to_string();
+    let revision = advance_agent_runtime_project_revision_locked(root)?;
+    let result = write_local_project_file_at(root, relative_path.trim(), &content)?;
+    if let (Some(project_id), Some(kind)) = (project_id, kind) {
+        if changed == Some(true) {
+            project::revision(
+                capture.clone(),
+                &project_id,
+                Source::Manual,
+                RevisionCreated {
+                    revision_id: revision.to_string(),
+                    revision_source: RevisionSource::ManualEdit,
+                    change_kind: kind,
+                    files_changed_count: Some(1),
+                },
+            );
+        }
+        project::saved(
+            capture,
+            &project_id,
+            Source::Manual,
+            &operation_id,
+            ProjectSaved {
+                save_source: SaveSource::Manual,
+                revision_id: Some(revision.to_string()),
+            },
+            None,
+        );
+    }
+    Ok(result)
 }
 
 #[tauri::command]
@@ -5693,11 +5832,49 @@ pub(crate) fn delete_local_project_file(
     project_path: String,
     relative_path: String,
 ) -> Result<LocalProjectFileMutationResult, String> {
+    delete_local_project_file_with_capture(
+        project_path,
+        relative_path,
+        crate::analytics::gui::capture_writer_context(),
+    )
+}
+
+fn delete_local_project_file_with_capture(
+    project_path: String,
+    relative_path: String,
+    capture: ManualAnalyticsCapture,
+) -> Result<LocalProjectFileMutationResult, String> {
+    use crate::analytics::{
+        contract::{RevisionCreated, RevisionSource, Source},
+        project,
+    };
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "file.delete")?;
     let _lock = acquire_project_write_lock(root, "file.delete")?;
-    advance_agent_runtime_project_revision_locked(root)?;
-    delete_local_project_file_at(root, relative_path.trim())
+    let project_id = capture
+        .as_ref()
+        .and_then(|_| read_existing_manifest_for_project(root).ok())
+        .map(|manifest| manifest.project_id);
+    let revision = advance_agent_runtime_project_revision_locked(root)?;
+    let result = delete_local_project_file_at(root, relative_path.trim())?;
+    if result.deleted {
+        if let (Some(project_id), Some(kind)) =
+            (project_id, project::file_change_kind(&result.path))
+        {
+            project::revision(
+                capture,
+                &project_id,
+                Source::Manual,
+                RevisionCreated {
+                    revision_id: revision.to_string(),
+                    revision_source: RevisionSource::ManualEdit,
+                    change_kind: kind,
+                    files_changed_count: Some(1),
+                },
+            );
+        }
+    }
+    Ok(result)
 }
 
 #[tauri::command]
@@ -6023,10 +6200,50 @@ pub(crate) fn build_local_project_index(
 pub(crate) fn create_local_project_checkpoint(
     project_path: String,
 ) -> Result<LocalProjectCheckpointResult, String> {
+    create_local_project_checkpoint_with_capture(
+        project_path,
+        crate::analytics::gui::capture_writer_context(),
+    )
+}
+
+fn create_local_project_checkpoint_with_capture(
+    project_path: String,
+    capture: ManualAnalyticsCapture,
+) -> Result<LocalProjectCheckpointResult, String> {
+    use crate::analytics::{
+        contract::{ProjectSaved, SaveSource, Source},
+        project,
+    };
     let root = Path::new(project_path.trim());
     enforce_project_permission_policy(root, "project.checkpoint")?;
     let _lock = acquire_project_write_lock(root, "project.checkpoint")?;
-    create_local_project_checkpoint_at(root)
+    let project_id = capture
+        .as_ref()
+        .and_then(|_| read_existing_manifest_for_project(root).ok())
+        .map(|manifest| manifest.project_id);
+    let result = create_local_project_checkpoint_at(root)?;
+    if let Some(project_id) = project_id {
+        project::saved(
+            capture,
+            &project_id,
+            Source::Manual,
+            &result.checkpoint_id,
+            ProjectSaved {
+                save_source: SaveSource::Checkpoint,
+                revision_id: None,
+            },
+            None,
+        );
+    }
+    Ok(result)
+}
+
+#[cfg(test)]
+pub(crate) fn checkpoint_with_capture_for_test(
+    project_path: String,
+    capture: ManualAnalyticsCapture,
+) -> Result<LocalProjectCheckpointResult, String> {
+    create_local_project_checkpoint_with_capture(project_path, capture)
 }
 
 #[tauri::command]