From 3153d4f6743beab2049a2b577e4a22376113cffc Mon Sep 17 00:00:00 2001 From: Suzumiya Date: Wed, 9 Sep 2026 16:53:49 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20AGC=20=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E5=86=99=E9=94=81=E6=AE=8B=E7=95=99=E6=97=A0=E6=B3=95=E5=9B=9E?= =?UTF-8?q?=E6=94=B6=E4=B8=8E=E5=90=AF=E5=8A=A8=E5=A4=B1=E8=B4=A5=E6=97=A0?= =?UTF-8?q?=E8=AF=8A=E6=96=AD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .agent/project.lock 新增 processStartedAt，PID 存活时核对进程启动身份，身份不一致判定 PID 复用并回收 - 旧锁缺少 processStartedAt 时退回“进程启动时间晚于锁 createdAt 加 5 秒容差”的 PID 复用推断 - 空锁 / 坏锁（崩溃停在 create_new 与落盘之间）宽限期由 600 秒收紧到 30 秒，无法判定持有者存活时仍保持 600 秒 - 新增 StartupLogSlot，配置目录就绪前后都能写 startup.log，startup.*.failed 与启动错误提示不再是死分支 - Windows 启动失败恢复系统消息框并附诊断日志路径，其它平台写 stderr，同一进程只提示一次 - 新增 project_lock_recovery 6 条回归用例：死 PID、空锁宽限、PID 复用时间推断、PID 复用身份不一致、身份一致不抢锁、新鲜空锁不抢锁 - 同步 decision-log 与 App 实施计划文档 --- .../src-tauri/src/main.rs | 209 ++++++++++++------ .../src-tauri/src/project/filesystem.rs | 171 ++++++++++++-- .../src-tauri/src/tests/mod.rs | 1 + .../src/tests/project_lock_recovery.rs | 208 +++++++++++++++++ .../shared-memory/decision-log.md | 7 + ...案】AI游戏创作智能体App实施计划-2026-06-24.md | 6 + 6 files changed, 518 insertions(+), 84 deletions(-) create mode 100644 apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs index 317b82348..bc46a3074 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/main.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs @@ -1998,8 +1998,89 @@ pub(crate) fn sanitize_diagnostic_message(value: &str, private_root: Option<&Pat sanitized.chars().take(2_048).collect() } +/// 启动阶段的致命失败必须让用户看得见：release 双击启动时 stderr 不可见，只写日志 +/// 等于什么都没发生。Windows 用系统消息框，其它平台退化为 stderr。 +#[cfg(windows)] fn show_startup_error_dialog(log_path: &Path) { - app_log!("Genarrative startup failed; see {}", log_path.display()); + use std::os::windows::ffi::OsStrExt; + use windows_sys::Win32::UI::WindowsAndMessaging::{ + MessageBoxW, MB_ICONERROR, MB_OK, MB_SETFOREGROUND, + }; + + if STARTUP_ERROR_DIALOG_SHOWN.swap(true, std::sync::atomic::Ordering::AcqRel) { + return; + } + let title = std::ffi::OsStr::new("Genarrative AI Game Creator") + .encode_wide() + .chain(Some(0)) + .collect::>(); + let message_text = format!( + "应用启动失败，请把下面的诊断日志发给开发人员：\n{}", + log_path.display() + ); + let message = std::ffi::OsStr::new(&message_text) + .encode_wide() + .chain(Some(0)) + .collect::>(); + // SAFETY: both UTF-16 buffers are NUL-terminated and live for the duration of the call. + unsafe { + MessageBoxW( + std::ptr::null_mut(), + message.as_ptr(), + title.as_ptr(), + MB_OK | MB_ICONERROR | MB_SETFOREGROUND, + ); + } +} + +#[cfg(not(windows))] +fn show_startup_error_dialog(log_path: &Path) { + if STARTUP_ERROR_DIALOG_SHOWN.swap(true, std::sync::atomic::Ordering::AcqRel) { + return; + } + eprintln!( + "Genarrative AI Game Creator startup failed; see {}", + log_path.display() + ); +} + +/// 启动诊断日志槽位。`configure_game_creator_runtime_config_dir` 之前只能退回按 +/// 标识符推导的 APPDATA 路径，成功后再切换到真实配置目录，保证早期失败也有落点。 +#[derive(Debug, Default)] +struct StartupLogSlot(Mutex>); + +impl StartupLogSlot { + fn new(path: Option) -> Self { + Self(Mutex::new(path)) + } + + fn set(&self, path: PathBuf) { + match self.0.lock() { + Ok(mut guard) => *guard = Some(path), + Err(poisoned) => *poisoned.into_inner() = Some(path), + } + } + + fn path(&self) -> Option { + match self.0.lock() { + Ok(guard) => guard.clone(), + Err(poisoned) => poisoned.into_inner().clone(), + } + } + + fn append(&self, line: &str) { + if let Some(path) = self.path() { + let _ = append_bounded_diagnostic_line(&path, line); + } + } + + /// 启动阶段的致命失败：先落盘，再给出用户可见提示。 + fn fail(&self, line: &str) { + self.append(line); + if let Some(path) = self.path() { + show_startup_error_dialog(&path); + } + } } #[derive(Clone, Debug)] @@ -2326,8 +2407,18 @@ fn main() { } let mut tauri_context = tauri::generate_context!(); - let startup_log: Option = None; - let setup_log = startup_log.clone(); + // 配置目录确定之前先按标识符推导 APPDATA 下的日志路径，确定后再切到真实配置 + // 目录，保证 `configure_game_creator_runtime_config_dir` 自身失败也有落点。 + let startup_log = Arc::new(StartupLogSlot::new( + std::env::var_os("APPDATA") + .map(PathBuf::from) + .map(|appdata| { + appdata + .join(tauri_context.config().identifier.as_str()) + .join("diagnostics/startup.log") + }), + )); + let setup_log = Arc::clone(&startup_log); let app = tauri::Builder::default() .plugin(tauri_plugin_opener::init()) .plugin(tauri_plugin_dialog::init()) @@ -2338,37 +2429,26 @@ fn main() { .manage(ProjectResourcePreviewReadManager::default()) .setup(move |app| { error_report::initialize_notifications(app.handle()); - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.setup.begin"); - let _ = append_bounded_diagnostic_line(path, "startup.appdata.configure.begin"); - } + setup_log.append("startup.setup.begin"); + setup_log.append("startup.appdata.configure.begin"); configure_game_creator_runtime_config_dir(app.handle()).inspect_err(|error| { - if let Some(path) = setup_log.as_deref() { + if let Some(path) = setup_log.path() { let details = sanitize_diagnostic_message(&error.to_string(), path.parent()); - let _ = append_bounded_diagnostic_line( - path, - &format!("startup.appdata.configure.failed details={details}"), - ); - show_startup_error_dialog(path); + setup_log.fail(&format!( + "startup.appdata.configure.failed details={details}" + )); } })?; - let startup_log = game_creator_runtime_config_dir() - .map(|directory| directory.join("diagnostics/startup.log")); - if let Some(path) = startup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.appdata.configure.complete"); + if let Some(directory) = game_creator_runtime_config_dir() { + setup_log.set(directory.join("diagnostics/startup.log")); } + setup_log.append("startup.appdata.configure.complete"); let config_dir = game_creator_runtime_config_dir().ok_or_else(|| { let error = std::io::Error::new( std::io::ErrorKind::NotFound, "客户端 AppData 配置目录未初始化", ); - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line( - path, - "startup.appdata.resolve.failed details=config-dir-uninitialized", - ); - show_startup_error_dialog(path); - } + setup_log.fail("startup.appdata.resolve.failed details=config-dir-uninitialized"); error })?; load_platform_session_fixture_from_env(&config_dir).map_err(|error| { @@ -2377,19 +2457,15 @@ fn main() { format!("加载平台登录态测试 fixture 失败：{error}"), ) })?; - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.runner.configure.begin"); - } + setup_log.append("startup.runner.configure.begin"); configure_external_agent_runner(&config_dir) .inspect_err(|error| { - if let Some(path) = setup_log.as_deref() { + if let Some(path) = setup_log.path() { let details = sanitize_diagnostic_message(error, Some(config_dir.as_path())); - let _ = append_bounded_diagnostic_line( - path, - &format!("startup.runner.configure.failed details={details}"), - ); - show_startup_error_dialog(path); + setup_log.fail(&format!( + "startup.runner.configure.failed details={details}" + )); } }) .map_err(|error| { @@ -2398,19 +2474,15 @@ fn main() { format!("配置 Agent Runner 失败：{error}"), ) })?; - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.runner.configure.complete"); - } + setup_log.append("startup.runner.configure.complete"); let gui_owner_lock = acquire_external_agent_runner_gui_owner_lock(&config_dir) .inspect_err(|error| { - if let Some(path) = setup_log.as_deref() { + if let Some(path) = setup_log.path() { let details = sanitize_diagnostic_message(error, Some(config_dir.as_path())); - let _ = append_bounded_diagnostic_line( - path, - &format!("startup.runner.owner-lock.failed details={details}"), - ); - show_startup_error_dialog(path); + setup_log.fail(&format!( + "startup.runner.owner-lock.failed details={details}" + )); } }) .map_err(|error| { @@ -2421,22 +2493,18 @@ fn main() { })?; let gui_owner_epoch = gui_owner_lock.owner_epoch().to_string(); app.manage(gui_owner_lock); - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.runner.start.begin"); - } + setup_log.append("startup.runner.start.begin"); set_game_creator_agent_runtime_update_app_handle(app.handle().clone()); let manifest_event_sink = start_game_creator_manifest_invalidation_event_sink(app.handle().clone())?; attach_external_agent_runner_gui_owner(&manifest_event_sink, &gui_owner_epoch) .inspect_err(|error| { - if let Some(path) = setup_log.as_deref() { + if let Some(path) = setup_log.path() { let details = sanitize_diagnostic_message(error, Some(config_dir.as_path())); - let _ = append_bounded_diagnostic_line( - path, - &format!("startup.runner.attach-owner.failed details={details}"), - ); - show_startup_error_dialog(path); + setup_log.fail(&format!( + "startup.runner.attach-owner.failed details={details}" + )); } }) .map_err(|error| { @@ -2445,12 +2513,8 @@ fn main() { format!("绑定 Agent Runner GUI owner 失败：{error}"), ) })?; - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.runner.start.complete"); - } - if let Some(path) = setup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.setup.complete"); - } + setup_log.append("startup.runner.start.complete"); + setup_log.append("startup.setup.complete"); Ok(()) }) .invoke_handler(tauri::generate_handler![ @@ -2615,19 +2679,13 @@ fn main() { .build(tauri_context); let app = match app { Ok(app) => { - if let Some(path) = startup_log.as_deref() { - let _ = append_bounded_diagnostic_line(path, "startup.build.complete"); - } + startup_log.append("startup.build.complete"); app } Err(error) => { - if let Some(path) = startup_log.as_deref() { + if let Some(path) = startup_log.path() { let details = sanitize_diagnostic_message(&error.to_string(), path.parent()); - let _ = append_bounded_diagnostic_line( - path, - &format!("startup.build.failed details={details}"), - ); - show_startup_error_dialog(path); + startup_log.fail(&format!("startup.build.failed details={details}")); } app_log!("failed to build Genarrative AI Game Creator shell: {error}"); std::process::exit(1); @@ -2657,6 +2715,25 @@ mod diagnostic_log_tests { assert!(previous.contains(&"x".repeat(32))); } + #[test] + fn startup_log_slot_keeps_early_failures_after_the_real_config_dir_is_known() { + let directory = tempfile::tempdir().expect("create diagnostics directory"); + let path = directory.path().join("startup.log"); + let slot = StartupLogSlot::new(None); + + // 配置目录未知时不能凭空造出日志文件。 + slot.append("startup.setup.begin"); + assert!(!path.exists()); + + slot.set(path.clone()); + slot.append("startup.setup.begin"); + slot.append("startup.appdata.configure.complete"); + + let content = fs::read_to_string(&path).expect("read startup log"); + assert!(content.contains("startup.setup.begin")); + assert!(content.contains("startup.appdata.configure.complete")); + } + #[test] fn diagnostic_message_redacts_sensitive_values_and_absolute_paths() { assert_eq!( diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs b/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs index ca1a45b15..109b3a8cb 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs @@ -6,6 +6,12 @@ pub(crate) const PROJECT_FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000; static PROJECT_WRITE_LOCK_NONCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1); const PROJECT_WRITE_LOCK_STALE_AFTER_SECONDS: u64 = 600; +/// 崩溃可能停在 `create_new` 成功、payload 落盘之前，此时锁文件没有任何持有者 +/// 信息。写入方正常情况下在毫秒级完成落盘，所以只需要很短的宽限期就能确认它 +/// 已经放弃，而不是让项目在整整 10 分钟里都不可写。 +const PROJECT_WRITE_LOCK_UNWRITTEN_GRACE_SECONDS: u64 = 30; +/// 进程启动时间与锁 `createdAt` 之间的允许偏差（秒），用来抵消时间戳精度差异。 +const PROJECT_WRITE_LOCK_PID_REUSE_TOLERANCE_SECONDS: u64 = 5; const PROJECT_WRITE_LOCK_MAX_BYTES: u64 = 4 * 1024; #[derive(Debug)] @@ -103,6 +109,91 @@ fn project_write_lock_process_is_alive(_process_id: u64) -> Option { None } +/// 读取进程的启动时间（Unix 秒）。用来区分“锁记录里的 PID 仍然属于原来的持有 +/// 者”和“PID 已经被系统复用给另一个进程”。无法判定的平台返回 `None`，此时 +/// 保持原有的保守回收策略。 +#[cfg(windows)] +pub(crate) fn project_write_lock_process_start_time_seconds(process_id: u64) -> Option { + use std::ffi::c_void; + + #[repr(C)] + struct FileTime { + low_date_time: u32, + high_date_time: u32, + } + + #[link(name = "kernel32")] + unsafe extern "system" { + fn OpenProcess(access: u32, inherit_handle: i32, process_id: u32) -> *mut c_void; + fn GetProcessTimes( + process: *mut c_void, + creation_time: *mut FileTime, + exit_time: *mut FileTime, + kernel_time: *mut FileTime, + user_time: *mut FileTime, + ) -> i32; + fn CloseHandle(handle: *mut c_void) -> i32; + } + + const PROCESS_QUERY_LIMITED_INFORMATION: u32 = 0x1000; + /// Windows FILETIME 起点（1601-01-01）到 Unix 纪元之间的 100 纳秒数。 + const FILETIME_UNIX_EPOCH_OFFSET: u64 = 116_444_736_000_000_000; + let process_id = u32::try_from(process_id).ok().filter(|value| *value > 0)?; + // SAFETY: OpenProcess returns an owned kernel handle or null; it is closed below. + let process = unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, process_id) }; + if process.is_null() { + return None; + } + // SAFETY: every FileTime is plain data filled by GetProcessTimes. + let mut creation = unsafe { std::mem::zeroed::() }; + let mut exit = unsafe { std::mem::zeroed::() }; + let mut kernel = unsafe { std::mem::zeroed::() }; + let mut user = unsafe { std::mem::zeroed::() }; + // SAFETY: `process` is a live handle and all four pointers are writable scalars. + let result = + unsafe { GetProcessTimes(process, &mut creation, &mut exit, &mut kernel, &mut user) }; + // SAFETY: `process` is an owned handle returned by OpenProcess. + unsafe { CloseHandle(process) }; + if result == 0 { + return None; + } + let file_time = (u64::from(creation.high_date_time) << 32) | u64::from(creation.low_date_time); + file_time + .checked_sub(FILETIME_UNIX_EPOCH_OFFSET) + .map(|unix_100ns| unix_100ns / 10_000_000) +} + +#[cfg(target_os = "linux")] +pub(crate) fn project_write_lock_process_start_time_seconds(process_id: u64) -> Option { + let process_id = u32::try_from(process_id).ok().filter(|value| *value > 0)?; + // SAFETY: sysconf has no memory safety preconditions and returns -1 on failure. + let clock_ticks = unsafe { libc::sysconf(libc::_SC_CLK_TCK) }; + if clock_ticks <= 0 { + return None; + } + let stat = fs::read_to_string(format!("/proc/{process_id}/stat")).ok()?; + let start_ticks = stat + .rsplit_once(") ")? + .1 + .split_whitespace() + .nth(19)? + .parse::() + .ok()?; + let boot_time = fs::read_to_string("/proc/stat") + .ok()? + .lines() + .find_map(|line| line.strip_prefix("btime "))? + .trim() + .parse::() + .ok()?; + Some(boot_time + start_ticks / clock_ticks as u64) +} + +#[cfg(not(any(windows, target_os = "linux")))] +pub(crate) fn project_write_lock_process_start_time_seconds(_process_id: u64) -> Option { + None +} + fn project_write_lock_owner_pid(path: &Path) -> Option { fs::read_to_string(path) .ok() @@ -110,26 +201,45 @@ fn project_write_lock_owner_pid(path: &Path) -> Option { .and_then(|payload| payload.get("pid").and_then(serde_json::Value::as_u64)) } +fn project_write_lock_owner_created_at(path: &Path) -> Option { + fs::read_to_string(path) + .ok() + .and_then(|content| serde_json::from_str::(&content).ok()) + .and_then(|payload| payload.get("createdAt").and_then(serde_json::Value::as_u64)) +} + +fn project_write_lock_owner_started_at(path: &Path) -> Option { + fs::read_to_string(path) + .ok() + .and_then(|content| serde_json::from_str::(&content).ok()) + .and_then(|payload| { + payload + .get("processStartedAt") + .and_then(serde_json::Value::as_u64) + }) +} + fn project_write_lock_is_owned_by_current_process(path: &Path) -> bool { project_write_lock_owner_pid(path) == Some(u64::from(std::process::id())) } -fn project_write_lock_age_seconds(path: &Path, metadata: &fs::Metadata) -> u64 { - let created_at = fs::read_to_string(path) - .ok() - .and_then(|content| serde_json::from_str::(&content).ok()) - .and_then(|payload| payload.get("createdAt").and_then(serde_json::Value::as_u64)); - if let Some(created_at) = created_at { - return unix_timestamp().saturating_sub(created_at); - } +fn project_write_lock_file_modified_seconds(metadata: &fs::Metadata) -> u64 { metadata .modified() .ok() - .and_then(|modified| modified.elapsed().ok()) - .map(|elapsed| elapsed.as_secs()) + .and_then(|modified| modified.duration_since(UNIX_EPOCH).ok()) + .map(|duration| duration.as_secs()) .unwrap_or_default() } +fn project_write_lock_age_seconds(path: &Path, metadata: &fs::Metadata) -> u64 { + if let Some(created_at) = project_write_lock_owner_created_at(path) { + return unix_timestamp().saturating_sub(created_at); + } + let modified_at = project_write_lock_file_modified_seconds(metadata); + unix_timestamp().saturating_sub(modified_at) +} + fn project_write_lock_can_be_reclaimed(path: &Path) -> bool { let Ok(metadata) = fs::symlink_metadata(path) else { return false; @@ -141,15 +251,36 @@ fn project_write_lock_can_be_reclaimed(path: &Path) -> bool { { return false; } - let content = fs::read_to_string(path).ok(); - let owner_pid = content - .as_deref() - .and_then(|content| serde_json::from_str::(content).ok()) - .and_then(|payload| payload.get("pid").and_then(serde_json::Value::as_u64)); - if let Some(owner_alive) = owner_pid.and_then(project_write_lock_process_is_alive) { - return !owner_alive; + let created_at = project_write_lock_owner_created_at(path); + let Some(owner_pid) = project_write_lock_owner_pid(path) else { + // 没有任何持有者信息：只可能是崩溃在落盘 payload 之前留下的空锁或坏锁。 + return project_write_lock_age_seconds(path, &metadata) + > PROJECT_WRITE_LOCK_UNWRITTEN_GRACE_SECONDS; + }; + match project_write_lock_process_is_alive(owner_pid) { + Some(false) => true, + Some(true) => { + // PID 会被系统复用，必须确认当前同名进程就是当时的持有者。 + let actual_started_at = project_write_lock_process_start_time_seconds(owner_pid); + match (project_write_lock_owner_started_at(path), actual_started_at) { + // 新锁自带启动身份：同一进程的身份恒定，不一致即为 PID 复用。 + (Some(stored), Some(actual)) => stored != actual, + // 旧锁没有启动身份，只能用“启动时间晚于锁创建时间”推断 PID 复用。 + (None, Some(actual)) => { + let lock_created_at = created_at + .unwrap_or_else(|| project_write_lock_file_modified_seconds(&metadata)); + actual + > lock_created_at + .saturating_add(PROJECT_WRITE_LOCK_PID_REUSE_TOLERANCE_SECONDS) + } + _ => false, + } + } + // 无法判定持有者是否存活时保持原有保守策略：只有明显过期才回收。 + None => { + project_write_lock_age_seconds(path, &metadata) > PROJECT_WRITE_LOCK_STALE_AFTER_SECONDS + } } - project_write_lock_age_seconds(path, &metadata) > PROJECT_WRITE_LOCK_STALE_AFTER_SECONDS } fn project_write_lock_open_error_is_contention(error: &std::io::Error) -> bool { @@ -228,6 +359,10 @@ pub(crate) fn acquire_project_write_lock( let payload = serde_json::json!({ "commandId": command_id, "pid": std::process::id(), + // 进程启动身份：崩溃残留锁要靠它区分“PID 被复用”和“持有者仍然活着”。 + "processStartedAt": project_write_lock_process_start_time_seconds(u64::from( + std::process::id() + )), "createdAt": unix_timestamp(), "nonce": PROJECT_WRITE_LOCK_NONCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed), }); diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs index 68c898339..e2c15a956 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs @@ -6069,6 +6069,7 @@ mod command_runtime; pub(crate) mod configuration; mod goal; mod project; +mod project_lock_recovery; mod project_tools; mod provider; mod response_stream; diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs new file mode 100644 index 000000000..51dfeac1e --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs @@ -0,0 +1,208 @@ +use super::*; +use std::process::Stdio; + +// Issue #310 复现：异常退出后在项目里残留 `.agent/project.lock`，下一次打开 +// 项目时所有写操作都被拒绝。 +// +// 下面的用例描述的是期望行为（残留锁必须能被安全回收）。在当前实现下它们会 +// 失败，用来证明缺陷；修复后应当全部通过，并作为回归用例保留。 + +const PROJECT_LOCK_RELATIVE_PATH: &str = ".agent/project.lock"; +/// 一个确定不会被占用的进程号：Windows 的 OpenProcess 对它返回 +/// ERROR_INVALID_PARAMETER，Unix 的 kill(pid, 0) 返回 ESRCH。 +const DEAD_OWNER_PID: u64 = 0xFFFF_FFF0; + +fn write_project_lock_fixture(root: &Path, content: &[u8]) { + fs::write(root.join(PROJECT_LOCK_RELATIVE_PATH), content).expect("写入项目写锁 fixture"); +} + +fn project_lock_fixture_payload(pid: u64, created_at: u64) -> Vec { + serde_json::to_vec_pretty(&serde_json::json!({ + "commandId": "repro.crashed-writer", + "pid": pid, + "createdAt": created_at, + "nonce": 1, + })) + .expect("序列化项目写锁 fixture") +} + +fn backdate_project_lock_fixture(root: &Path, seconds: u64) { + let file = fs::OpenOptions::new() + .write(true) + .open(root.join(PROJECT_LOCK_RELATIVE_PATH)) + .expect("打开项目写锁 fixture"); + file.set_modified(SystemTime::now() - Duration::from_secs(seconds)) + .expect("回拨项目写锁 fixture mtime"); +} + +#[cfg(windows)] +fn spawn_unrelated_live_process() -> std::process::Child { + std::process::Command::new("ping") + .args(["-n", "30", "127.0.0.1"]) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .expect("启动无关的活进程") +} + +#[cfg(target_os = "linux")] +fn spawn_unrelated_live_process() -> std::process::Child { + std::process::Command::new("sleep") + .arg("30") + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .expect("启动无关的活进程") +} + +fn stop_unrelated_live_process(mut child: std::process::Child) { + let _ = child.kill(); + let _ = child.wait(); +} + +/// 基线：记录着已死进程号的残留锁本来就应该被回收。 +#[test] +fn project_write_lock_reclaims_dead_owner_pid() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-dead-owner", "锁回收-死进程").expect("初始化项目"); + write_project_lock_fixture( + &root, + &project_lock_fixture_payload(DEAD_OWNER_PID, unix_timestamp()), + ); + + let acquired = acquire_project_write_lock(&root, "repro.acquire-after-crash"); + assert!( + acquired.is_ok(), + "死进程残留锁未被回收，实际错误：{:?}", + acquired.err() + ); + drop(acquired); + fs::remove_dir_all(root).ok(); +} + +/// 复现 A：崩溃发生在 create_new 成功、payload 写盘之前，留下 0 字节锁。 +/// 现在要等满 600 秒才会回收，重启后 10 分钟内所有写操作都失败。 +#[test] +fn project_write_lock_reclaims_empty_body_after_short_grace() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-empty-body", "锁回收-空锁").expect("初始化项目"); + write_project_lock_fixture(&root, b""); + backdate_project_lock_fixture(&root, 120); + + let acquired = acquire_project_write_lock(&root, "repro.acquire-after-crash"); + assert!( + acquired.is_ok(), + "空残留锁超过宽限期仍未被回收，实际错误：{:?}", + acquired.err() + ); + drop(acquired); + fs::remove_dir_all(root).ok(); +} + +/// 复现 B：崩溃后 Windows 把同一个 PID 复用给了另一个无关进程。 +/// 只要那个进程还活着，残留锁就永远不会被回收。 +#[cfg(any(windows, target_os = "linux"))] +#[test] +fn project_write_lock_reclaims_pid_reused_by_other_live_process() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-pid-reuse", "锁回收-PID复用").expect("初始化项目"); + + let unrelated = spawn_unrelated_live_process(); + // 锁是在一小时前被写下的，而记录里的 PID 现在属于刚刚才启动的另一个进程： + // 这只能是 PID 复用，原持有者早已退出。 + write_project_lock_fixture( + &root, + &project_lock_fixture_payload(u64::from(unrelated.id()), unix_timestamp() - 3_600), + ); + + let acquired = acquire_project_write_lock(&root, "repro.acquire-after-crash"); + stop_unrelated_live_process(unrelated); + assert!( + acquired.is_ok(), + "PID 复用后的残留锁未被回收，实际错误：{:?}", + acquired.err() + ); + drop(acquired); + fs::remove_dir_all(root).ok(); +} + +/// 复现 C：新锁自带进程启动身份。即使时间戳看起来“刚刚写过”，只要身份对不上 +/// 就说明是 PID 复用，必须回收；这条路径不依赖系统时钟是否发生跳变。 +#[cfg(any(windows, target_os = "linux"))] +#[test] +fn project_write_lock_reclaims_pid_reused_identity_mismatch() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-pid-identity", "锁回收-身份不一致") + .expect("初始化项目"); + let unrelated = spawn_unrelated_live_process(); + let started_at = project_write_lock_process_start_time_seconds(u64::from(unrelated.id())) + .expect("读取活进程启动时间"); + write_project_lock_fixture( + &root, + &serde_json::to_vec_pretty(&serde_json::json!({ + "commandId": "repro.crashed-writer", + "pid": u64::from(unrelated.id()), + "processStartedAt": started_at + 1, + "createdAt": unix_timestamp(), + "nonce": 1, + })) + .expect("序列化项目写锁 fixture"), + ); + + let acquired = acquire_project_write_lock(&root, "repro.acquire-after-crash"); + stop_unrelated_live_process(unrelated); + assert!( + acquired.is_ok(), + "启动身份不一致的残留锁未被回收，实际错误：{:?}", + acquired.err() + ); + drop(acquired); + fs::remove_dir_all(root).ok(); +} + +/// 护栏：PID 与启动身份都吻合说明持有者真的活着，绝不能抢锁。 +#[cfg(any(windows, target_os = "linux"))] +#[test] +fn project_write_lock_keeps_matching_process_identity() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-live-identity", "锁回收-身份一致").expect("初始化项目"); + let unrelated = spawn_unrelated_live_process(); + let started_at = project_write_lock_process_start_time_seconds(u64::from(unrelated.id())) + .expect("读取活进程启动时间"); + write_project_lock_fixture( + &root, + &serde_json::to_vec_pretty(&serde_json::json!({ + "commandId": "repro.live-writer", + "pid": u64::from(unrelated.id()), + "processStartedAt": started_at, + "createdAt": unix_timestamp(), + "nonce": 1, + })) + .expect("序列化项目写锁 fixture"), + ); + + let error = acquire_project_write_lock(&root, "repro.acquire-concurrent") + .expect_err("持有者仍然活着时不能回收"); + stop_unrelated_live_process(unrelated); + assert!( + error.contains("项目正在被其他写操作占用"), + "活持有者必须进入占用分支，实际错误：{error}" + ); + fs::remove_dir_all(root).ok(); +} + +/// 护栏：刚创建的空锁可能只是写入方还没落盘，绝不能被别人抢走。 +#[test] +fn project_write_lock_keeps_fresh_empty_body() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-fresh-empty", "锁回收-新鲜空锁").expect("初始化项目"); + write_project_lock_fixture(&root, b""); + + let error = acquire_project_write_lock(&root, "repro.acquire-concurrent") + .expect_err("刚创建的空锁必须保持占用"); + assert!( + error.contains("项目正在被其他写操作占用"), + "并发写必须进入占用分支，实际错误：{error}" + ); + fs::remove_dir_all(root).ok(); +} diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index d1c0b090c..2a381f16d 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -8188,3 +8188,10 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 问题回答携带被回答卡片的 questionId，在已有回合锁内核对 Session 和当前问题；自由文本回答同样绑定问题，已完成回合保留幂等重放。此身份匹配服务于用户提交，不增加恢复门禁或模型输出要求。 - hydrate 结果（包括空结果）写入前端状态前同时核对请求序列和当前项目路径；过期结果直接丢弃，不重试、不阻塞正常 run。 + +## 2026-09-09 项目写锁残留回收与启动诊断 + +- 决策：`.agent/project.lock` 记录 `processStartedAt`；PID 存活时用启动身份区分“原持有者仍在”与“PID 被复用”，身份不一致才回收。旧锁无该字段时用“进程启动时间晚于锁 `createdAt` + 5 秒容差”推断。空锁 / 坏锁（崩溃停在 `create_new` 与落盘之间）宽限期 30 秒，无法判定存活时保持 600 秒。活持有者始终不回收。 +- 决策：启动诊断日志用 `StartupLogSlot` 先按标识符推导 APPDATA 路径、配置目录就绪后切换，`startup.*.failed` 与 `show_startup_error_dialog` 必须可达；Windows 启动失败弹系统消息框，其它平台写 stderr。 +- 边界：`agent-runner.lock` / `agent-runner.gui-owner.lock` 是 OS 独占句柄锁，进程退出即释放，残留文件不阻塞下次启动；不要把它们当成项目写锁的同类残留处理。 +- 验证：`project_lock_recovery` 6 条与 `diagnostic_log` 5 条定向测试通过，真实二进制双实例复现“第二个实例写 `startup.runner.owner-lock.failed` 并弹出可见提示”。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 5cf960dcf..ec85badf8 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -1330,3 +1330,9 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过 - `/api/llm/responses` 与 `/api/llm/chat/completions` 的正式请求体上限为 `32 MiB`。两个路由必须显式配置 Axum `DefaultBodyLimit::max(LLM_REQUEST_MAX_BODY_BYTES)`；不能依赖 handler 内的 `Bytes / Json` 后置检查，否则 Axum 默认 `2 MiB` 会先拒绝 Direct Codex 携带图片工具结果的大上下文请求。超过 `32 MiB` 仍返回 `413 PAYLOAD_TOO_LARGE`。 - Codex app-server 的 failed turn 需要把上游 / 连接层 HTTP 413、`PAYLOAD_TOO_LARGE` 和 provider proxy 的 `provider request too large` 映射为稳定分类 `codex-app-server-error:request-too-large`；用户可见文案固定为“模型请求体过大，请减少参考图或上下文后重试”，不得落入 `other` 或泛化成权限 / 安全策略错误。 + +## 2026-09-09 项目写锁残留回收与启动诊断 + +- `.agent/project.lock` 新增 `processStartedAt`（持有进程启动时间，Unix 秒）。PID 仍存活时必须先核对启动身份：身份不一致即判定 PID 复用，可直接回收；旧锁没有该字段时退回“进程启动时间晚于锁 `createdAt` 加 5 秒容差”的推断。崩溃停在 `create_new` 与落盘 payload 之间的空锁 / 坏锁宽限期从 600 秒收紧到 30 秒；无法判定持有者是否存活时继续按 600 秒保守回收，活持有者仍然不回收。 +- 启动诊断日志改为 `StartupLogSlot`：`configure_game_creator_runtime_config_dir` 之前按应用标识符推导 APPDATA 路径，成功后再切换到真实配置目录，`startup.*.failed` 与 `show_startup_error_dialog` 不再是死分支。Windows 启动失败恢复系统消息框并附诊断日志路径，其它平台写 stderr，同一进程只提示一次。 +- 边界与验证：残留的 `agent-runner.lock` / `agent-runner.gui-owner.lock` 是 OS 独占句柄锁，进程退出即释放，文件本身不阻塞下次启动；真正阻塞启动的是仍有活进程持锁。验证覆盖 `project_lock_recovery` 6 条（死 PID、空锁宽限、PID 复用时间推断、PID 复用身份不一致、身份一致不抢锁、新鲜空锁不抢锁）、`diagnostic_log` 5 条，以及真实二进制双实例：第二个实例写入 `startup.runner.owner-lock.failed` 并弹出可见提示。