diff --git a/apps/ai-game-creator-shell/scripts/check-config.mjs b/apps/ai-game-creator-shell/scripts/check-config.mjs index 0149d953a..f2c19ac58 100644 --- a/apps/ai-game-creator-shell/scripts/check-config.mjs +++ b/apps/ai-game-creator-shell/scripts/check-config.mjs @@ -1705,10 +1705,16 @@ if ( runtimeConfigSetupStart === -1 || runtimeConfigSetupEnd === -1 || !runtimeConfigSetupSource.includes('sanitize_diagnostic_message(') || - !runtimeConfigSetupSource.includes('append_bounded_diagnostic_line(') || + !runtimeConfigSetupSource.includes('setup_log.fail(') || !runtimeConfigSetupSource.includes( 'startup.appdata.configure.failed details={details}', - ) + ) || + !tauriHandlerSource.includes('impl StartupLogSlot {') || + !tauriHandlerSource.includes('append_bounded_diagnostic_line(&path, line)') || + !tauriHandlerSource.includes( + 'self.append(line);\n show_startup_error_dialog(self.path().as_deref());', + ) || + !tauriHandlerSource.includes('early_startup_log_path(') ) { throw new Error( 'AI game creator setup must configure the runtime AppData directory and log sanitized setup failures', 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..de5353beb 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,136 @@ pub(crate) fn sanitize_diagnostic_message(value: &str, private_root: Option<&Pat sanitized.chars().take(2_048).collect() } -fn show_startup_error_dialog(log_path: &Path) { - app_log!("Genarrative startup failed; see {}", log_path.display()); +/// 启动阶段的致命失败必须让用户看得见：release 双击启动时 stderr 不可见，只写日志 +/// 等于什么都没发生。Windows 用系统消息框，其它平台退化为 stderr。日志路径尚未 +/// 确定时仍然要提示，只是不给路径。 +#[cfg(windows)] +fn show_startup_error_dialog(log_path: Option<&Path>) { + 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 = match log_path { + Some(log_path) => format!( + "应用启动失败，请把下面的诊断日志发给开发人员：\n{}", + log_path.display() + ), + None => { + "应用启动失败，诊断日志路径尚未确定；请把这条提示和复现步骤发给开发人员。".to_string() + } + }; + 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: Option<&Path>) { + if STARTUP_ERROR_DIALOG_SHOWN.swap(true, std::sync::atomic::Ordering::AcqRel) { + return; + } + match log_path { + Some(log_path) => eprintln!( + "Genarrative AI Game Creator startup failed; see {}", + log_path.display() + ), + None => eprintln!( + "Genarrative AI Game Creator startup failed before the diagnostics log path was known" + ), + } +} + +/// 配置目录就绪前的启动日志路径：优先用已经生效的配置目录（例如 `--config-dir` +/// 已经设置好的目录），否则退到平台配置根。两者都不可用时返回 `None`，此时 +/// `StartupLogSlot::fail` 仍然必须给出用户可见提示。 +fn early_startup_log_path(identifier: &str) -> Option { + let configured_dir = game_creator_runtime_config_dir(); + resolve_early_startup_log_path(configured_dir.as_deref(), identifier) +} + +fn resolve_early_startup_log_path( + configured_dir: Option<&Path>, + identifier: &str, +) -> Option { + match configured_dir { + Some(directory) => Some(directory.join("diagnostics/startup.log")), + None => { + platform_config_root().map(|root| root.join(identifier).join("diagnostics/startup.log")) + } + } +} + +#[cfg(windows)] +fn platform_config_root() -> Option { + std::env::var_os("APPDATA").map(PathBuf::from) +} + +#[cfg(target_os = "macos")] +fn platform_config_root() -> Option { + std::env::var_os("HOME").map(|home| PathBuf::from(home).join("Library/Application Support")) +} + +#[cfg(not(any(windows, target_os = "macos")))] +fn platform_config_root() -> Option { + std::env::var_os("XDG_CONFIG_HOME") + .map(PathBuf::from) + .or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".config"))) +} + +/// 启动诊断日志槽位。`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); + show_startup_error_dialog(self.path().as_deref()); + } } #[derive(Clone, Debug)] @@ -2326,8 +2454,13 @@ fn main() { } let mut tauri_context = tauri::generate_context!(); - let startup_log: Option = None; - let setup_log = startup_log.clone(); + // 配置目录确定之前先推导启动日志路径：优先用已经生效的配置目录（例如 + // `--config-dir`），否则退到平台配置根，保证 + // `configure_game_creator_runtime_config_dir` 自身失败也有落点。 + let startup_log = Arc::new(StartupLogSlot::new(early_startup_log_path( + tauri_context.config().identifier.as_str(), + ))); + let setup_log = Arc::clone(&startup_log); let app = tauri::Builder::default() .plugin(tauri_plugin_opener::init()) .plugin(tauri_plugin_dialog::init()) @@ -2338,37 +2471,27 @@ 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() { - 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); - } + // 日志路径未知也必须记录并提示：不能因为拿不到路径就静默失败。 + let config_dir = game_creator_runtime_config_dir(); + let details = + sanitize_diagnostic_message(&error.to_string(), config_dir.as_deref()); + 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,20 +2500,13 @@ 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() { - 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); - } + let details = sanitize_diagnostic_message(error, Some(config_dir.as_path())); + setup_log.fail(&format!( + "startup.runner.configure.failed details={details}" + )); }) .map_err(|error| { std::io::Error::new( @@ -2398,20 +2514,13 @@ 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() { - 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); - } + let details = sanitize_diagnostic_message(error, Some(config_dir.as_path())); + setup_log.fail(&format!( + "startup.runner.owner-lock.failed details={details}" + )); }) .map_err(|error| { std::io::Error::new( @@ -2421,23 +2530,16 @@ 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() { - 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); - } + let details = sanitize_diagnostic_message(error, Some(config_dir.as_path())); + setup_log.fail(&format!( + "startup.runner.attach-owner.failed details={details}" + )); }) .map_err(|error| { std::io::Error::new( @@ -2445,12 +2547,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 +2713,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 +2749,55 @@ 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 early_startup_log_path_prefers_the_already_applied_config_dir() { + let directory = tempfile::tempdir().expect("create config directory"); + assert_eq!( + resolve_early_startup_log_path(Some(directory.path()), "world.genarrative.test"), + Some(directory.path().join("diagnostics/startup.log")) + ); + + // 配置目录尚未生效时才退到平台配置根，且仍要按标识符分层。 + if let Some(fallback) = resolve_early_startup_log_path(None, "world.genarrative.test") { + assert!(fallback.ends_with("world.genarrative.test/diagnostics/startup.log")); + } + } + + #[test] + fn startup_log_slot_fail_without_path_still_reports_instead_of_going_silent() { + let directory = tempfile::tempdir().expect("create diagnostics directory"); + let slot = StartupLogSlot::new(None); + + // 路径未知时 fail 不能静默：它必须仍然走到用户可见提示，同时不造日志文件。 + slot.fail("startup.runner.owner-lock.failed details=test"); + assert_eq!(fs::read_dir(directory.path()).expect("read dir").count(), 0); + + let path = directory.path().join("startup.log"); + let slot = StartupLogSlot::new(Some(path.clone())); + slot.fail("startup.runner.owner-lock.failed details=test"); + let content = fs::read_to_string(&path).expect("read startup log"); + assert!(content.contains("startup.runner.owner-lock.failed details=test")); + } + #[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..02f3c83a0 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)] @@ -49,7 +55,11 @@ impl Drop for ProjectWriteLock { #[cfg(unix)] fn project_write_lock_process_is_alive(process_id: u64) -> Option { - let process_id = i32::try_from(process_id).ok().filter(|value| *value > 0)?; + // Unix 的 pid_t 是有符号 32 位且恒大于 0，超出该范围的取值不可能是本机 + // 任何进程，说明锁文件里的 PID 已经损坏，可以直接判定持有者不存在。 + let Some(process_id) = i32::try_from(process_id).ok().filter(|value| *value > 0) else { + return Some(false); + }; let result = unsafe { libc::kill(process_id, 0) }; if result == 0 { return Some(true); @@ -72,7 +82,11 @@ fn project_write_lock_process_is_alive(process_id: u64) -> Option { fn CloseHandle(handle: *mut c_void) -> i32; } - let process_id = u32::try_from(process_id).ok().filter(|value| *value > 0)?; + // Windows 进程号是 32 位且恒大于 0，超出该范围的取值不可能是本机任何 + // 进程，说明锁文件里的 PID 已经损坏，可以直接判定持有者不存在。 + let Some(process_id) = u32::try_from(process_id).ok().filter(|value| *value > 0) else { + return Some(false); + }; const PROCESS_QUERY_LIMITED_INFORMATION: u32 = 0x1000; const STILL_ACTIVE: u32 = 259; // SAFETY: OpenProcess returns an owned kernel handle or null; it is @@ -103,53 +117,231 @@ fn project_write_lock_process_is_alive(_process_id: u64) -> Option { None } -fn project_write_lock_owner_pid(path: &Path) -> Option { - fs::read_to_string(path) - .ok() - .and_then(|content| serde_json::from_str::(&content).ok()) - .and_then(|payload| payload.get("pid").and_then(serde_json::Value::as_u64)) +/// 读取进程的启动时间（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 +} + +/// 一次读到的锁文件字节与解析结果。回收判据和随后的删除必须基于同一份快照： +/// 分别重读 `pid` / `createdAt` / `processStartedAt` 会把旧 inode 的持有者信息 +/// 和新 inode 的启动身份拼在一起，也会让判定与删除命中不同的文件。 +#[derive(Debug, Clone)] +pub(crate) struct ProjectWriteLockSnapshot { + content: Vec, + pid: Option, + created_at: Option, + process_started_at: Option, +} + +impl ProjectWriteLockSnapshot { + pub(crate) fn read(path: &Path) -> Option { + let content = fs::read(path).ok()?; + let payload = serde_json::from_slice::(&content).ok(); + let number = |key: &str| { + payload + .as_ref() + .and_then(|payload| payload.get(key)) + .and_then(serde_json::Value::as_u64) + }; + Some(Self { + pid: number("pid"), + created_at: number("createdAt"), + process_started_at: number("processStartedAt"), + content, + }) + } } fn project_write_lock_is_owned_by_current_process(path: &Path) -> bool { - project_write_lock_owner_pid(path) == Some(u64::from(std::process::id())) + ProjectWriteLockSnapshot::read(path).and_then(|snapshot| snapshot.pid) + == 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); - } +/// 读取锁文件 mtime 的 Unix 秒数；读不到时返回 `None`。调用方必须把“mtime 未知” +/// 和“mtime 等于纪元 0”区分开：后者会被算成极大的年龄，反而把保守判定反转成 +/// “立刻回收”，甚至把活持有者的锁当成 PID 复用抢走。 +fn project_write_lock_file_modified_seconds(metadata: &fs::Metadata) -> Option { metadata .modified() .ok() - .and_then(|modified| modified.elapsed().ok()) - .map(|elapsed| elapsed.as_secs()) - .unwrap_or_default() + .and_then(|modified| modified.duration_since(UNIX_EPOCH).ok()) + .map(|duration| duration.as_secs()) } -fn project_write_lock_can_be_reclaimed(path: &Path) -> bool { - let Ok(metadata) = fs::symlink_metadata(path) else { - return false; +/// 锁文件年龄（秒）。`createdAt` 与 mtime 都无法确定时返回 `None`：未知年龄只能 +/// 按“不回收”处理，不能退化成 0 或极大值。 +fn project_write_lock_age_seconds( + snapshot: &ProjectWriteLockSnapshot, + modified_at: Option, + now: u64, +) -> Option { + if let Some(created_at) = snapshot.created_at { + return Some(now.saturating_sub(created_at)); + } + modified_at.map(|modified_at| now.saturating_sub(modified_at)) +} + +/// 回收判据。进程存活与启动时间查询作为参数传入，便于用确定性用例覆盖真实进程 +/// 难以构造的分支（存活状态无法判定、mtime 不可读）。 +pub(crate) fn project_write_lock_reclaim_decision( + snapshot: &ProjectWriteLockSnapshot, + modified_at: Option, + now: u64, + process_is_alive: impl Fn(u64) -> Option, + process_started_at: impl Fn(u64) -> Option, +) -> bool { + let Some(owner_pid) = snapshot.pid else { + // 没有可用的持有者信息（空锁、坏锁、无数字 pid 的锁）：只按短宽限期回收。 + return project_write_lock_age_seconds(snapshot, modified_at, now) + .is_some_and(|age| age > PROJECT_WRITE_LOCK_UNWRITTEN_GRACE_SECONDS); }; + match process_is_alive(owner_pid) { + Some(false) => true, + Some(true) => { + // PID 会被系统复用，必须确认当前同名进程就是当时的持有者。 + match (snapshot.process_started_at, process_started_at(owner_pid)) { + // 新锁自带启动身份：同一进程的身份恒定，不一致即为 PID 复用。 + (Some(stored), Some(actual)) => stored != actual, + // 旧锁没有启动身份，只能用“启动时间晚于锁创建时间”推断 PID 复用； + // 锁创建时间未知时不做推断，避免把“未知”当成“复用”抢走活持有者。 + (None, Some(actual)) => { + let Some(lock_created_at) = snapshot.created_at.or(modified_at) else { + return false; + }; + actual + > lock_created_at + .saturating_add(PROJECT_WRITE_LOCK_PID_REUSE_TOLERANCE_SECONDS) + } + _ => false, + } + } + // 无法判定持有者是否存活时保持保守策略：只有明显过期才回收。 + None => project_write_lock_age_seconds(snapshot, modified_at, now) + .is_some_and(|age| age > PROJECT_WRITE_LOCK_STALE_AFTER_SECONDS), + } +} + +/// 判定残留锁可回收时返回判定所依据的快照，否则返回 `None`。 +fn project_write_lock_reclaimable_snapshot(path: &Path) -> Option { + let metadata = fs::symlink_metadata(path).ok()?; if metadata.file_type().is_symlink() || windows_metadata_is_reparse_point(&metadata) || !metadata.is_file() || metadata.len() > PROJECT_WRITE_LOCK_MAX_BYTES { - return false; + return None; } - 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 snapshot = ProjectWriteLockSnapshot::read(path)?; + project_write_lock_reclaim_decision( + &snapshot, + project_write_lock_file_modified_seconds(&metadata), + unix_timestamp(), + project_write_lock_process_is_alive, + project_write_lock_process_start_time_seconds, + ) + .then_some(snapshot) +} + +/// 删除判定为残留的锁文件。判定只是快照观察，删除前必须重新核对字节，确认删掉的 +/// 仍是判定时的那个文件：并发方可能已经回收并装上了自己的活锁。文件已经消失或 +/// 已被替换时返回 `false`，让调用方重试 `create_new` 重新竞争，而不是报错。 +pub(crate) fn project_write_lock_reclaim( + path: &Path, + snapshot: &ProjectWriteLockSnapshot, +) -> Result { + match fs::read(path) { + Ok(content) if content == snapshot.content => {} + Ok(_) => return Ok(false), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(false), + Err(error) => { + return Err(format!("读取失效项目写锁失败：{}: {error}", path.display())); + } + } + match fs::remove_file(path) { + Ok(()) => Ok(true), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false), + Err(error) => Err(format!("清理失效项目写锁失败：{}: {error}", path.display())), } - 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 +420,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), }); @@ -277,33 +473,29 @@ pub(crate) fn acquire_project_write_lock( bypassed_same_process: false, }); } - Err(error) - if project_write_lock_open_error_is_contention(&error) - && !retried_after_reclaim - && project_write_lock_can_be_reclaimed(&path) => - { - fs::remove_file(&path).map_err(|error| { - format!("清理失效项目写锁失败：{}: {error}", path.display()) - })?; - retried_after_reclaim = true; - } - Err(error) - if project_write_lock_open_error_is_contention(&error) - && crate::agent::autonomous_game_build_root_run_active_at(root) - && project_write_lock_is_owned_by_current_process(&path) => - { - // The autonomous game-build lane intentionally permits - // parallel specialist actions. If the durable lock belongs - // to this very process, contention is an in-process overlap, - // not another application editing the project. Return an - // advisory guard and leave the real lock untouched. - return Ok(ProjectWriteLock { - path, - content: String::new(), - bypassed_same_process: true, - }); - } Err(error) if project_write_lock_open_error_is_contention(&error) => { + if !retried_after_reclaim { + if let Some(snapshot) = project_write_lock_reclaimable_snapshot(&path) { + if project_write_lock_reclaim(&path, &snapshot)? { + retried_after_reclaim = true; + continue; + } + } + } + if crate::agent::autonomous_game_build_root_run_active_at(root) + && project_write_lock_is_owned_by_current_process(&path) + { + // The autonomous game-build lane intentionally permits + // parallel specialist actions. If the durable lock belongs + // to this very process, contention is an in-process overlap, + // not another application editing the project. Return an + // advisory guard and leave the real lock untouched. + return Ok(ProjectWriteLock { + path, + content: String::new(), + bypassed_same_process: true, + }); + } return Err(format!("项目正在被其他写操作占用：{}", path.display())); } Err(error) => { 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..9f7dc6541 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs @@ -0,0 +1,358 @@ +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。取值必须落在 Unix 有符号 32 位 pid 范围内，否则在 Unix 上会先命中 +/// “进程号不可表示”分支，而不是这条“死进程”分支。 +const DEAD_OWNER_PID: u64 = i32::MAX as u64 - 1; + +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"); +} + +/// 写入锁 fixture 并读回同一份快照，供纯判据用例使用。 +fn project_lock_snapshot(root: &Path, content: &[u8]) -> ProjectWriteLockSnapshot { + write_project_lock_fixture(root, content); + ProjectWriteLockSnapshot::read(&root.join(PROJECT_LOCK_RELATIVE_PATH)) + .expect("读取项目写锁快照") +} + +#[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(); +} + +/// 锁文件被外部改写或截断损坏、PID 超出平台进程号空间（例如 u64::MAX）时，它不 +/// 可能属于任何活进程，必须直接回收而不是再等满 600 秒；Unix 的 pid_t 只有有符号 +/// 32 位，越界取值尤其容易在这里被漏掉。 +#[test] +fn project_write_lock_reclaims_unrepresentable_owner_pid() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-invalid-pid", "锁回收-非法进程号").expect("初始化项目"); + write_project_lock_fixture( + &root, + &project_lock_fixture_payload(u64::MAX, 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(); +} + +/// 空锁超过 30 秒宽限期即回收：崩溃停在 `create_new` 与落盘 payload 之间时写入方 +/// 已经放弃，不能继续阻塞项目。 +#[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(); +} + +/// 旧格式锁（无 `processStartedAt`）记录的 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(); +} + +/// 新格式锁自带进程启动身份：即使时间戳看起来“刚刚写过”，只要身份对不上就判定 +/// 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(); +} + +/// 护栏：旧格式锁（有 `pid` 和 `createdAt`、没有 `processStartedAt`）的持有者确实 +/// 活着，且进程启动时间早于锁创建时间时，不能被当成 PID 复用抢走。 +#[cfg(any(windows, target_os = "linux"))] +#[test] +fn project_write_lock_keeps_live_old_format_holder_started_before_created_at() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-old-format-live", "锁回收-旧格式活持有者") + .expect("初始化项目"); + let unrelated = spawn_unrelated_live_process(); + let started_at = project_write_lock_process_start_time_seconds(u64::from(unrelated.id())) + .expect("读取活进程启动时间"); + // 锁是在持有者启动之后才写下的，所以进程启动时间自然早于 createdAt。 + write_project_lock_fixture( + &root, + &project_lock_fixture_payload(u64::from(unrelated.id()), started_at + 60), + ); + + let error = acquire_project_write_lock(&root, "repro.acquire-concurrent"); + stop_unrelated_live_process(unrelated); + assert!( + matches!(&error, Err(message) if message.contains("项目正在被其他写操作占用")), + "旧格式活持有者不能被当成 PID 复用，实际结果：{error:?}" + ); + fs::remove_dir_all(root).ok(); +} + +/// 护栏：回收判定只是快照观察，删除前必须重新核对内容。判定之后被并发方替换成 +/// 自己的活锁时不能删除它；文件已经消失时也不算失败。 +#[test] +fn project_write_lock_reclaim_skips_replaced_or_removed_lock_file() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-reclaim-race", "锁回收-并发替换").expect("初始化项目"); + let lock_path = root.join(PROJECT_LOCK_RELATIVE_PATH); + write_project_lock_fixture( + &root, + &project_lock_fixture_payload(4_242, unix_timestamp()), + ); + let stale_snapshot = ProjectWriteLockSnapshot::read(&lock_path).expect("读取残留锁快照"); + + // 并发方回收了残留锁并装上了自己的活锁。 + write_project_lock_fixture( + &root, + &project_lock_fixture_payload(u64::from(std::process::id()), unix_timestamp()), + ); + assert!( + !project_write_lock_reclaim(&lock_path, &stale_snapshot).expect("核对被替换的锁文件"), + "内容已经变化时必须放弃删除" + ); + assert!(lock_path.exists(), "并发方新装的活锁不能被删掉"); + + fs::remove_file(&lock_path).expect("删除锁文件"); + assert!( + !project_write_lock_reclaim(&lock_path, &stale_snapshot).expect("核对已消失的锁文件"), + "锁文件已经消失时不算失败" + ); + fs::remove_dir_all(root).ok(); +} + +/// 护栏：存活状态无法判定（`None`）时保持保守——年轻锁必须保留，明显过期才回收。 +#[test] +fn project_write_lock_decision_keeps_young_lock_when_liveness_is_unknown() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-unknown-liveness", "锁回收-存活未知") + .expect("初始化项目"); + let now = unix_timestamp(); + let snapshot = project_lock_snapshot(&root, &project_lock_fixture_payload(4_242, now)); + + assert!( + !project_write_lock_reclaim_decision(&snapshot, Some(now), now, |_| None, |_| None), + "存活状态无法判定时，新鲜锁必须保持占用" + ); + assert!( + project_write_lock_reclaim_decision(&snapshot, Some(now), now + 601, |_| None, |_| None), + "存活状态无法判定且明显过期时必须回收" + ); + fs::remove_dir_all(root).ok(); +} + +/// 护栏：mtime 不可读（未知）时不能退化成“年龄极大”。未知年龄按不回收处理， +/// 未知创建时间也不能满足“启动时间晚于创建时间”的 PID 复用推断。 +#[test] +fn project_write_lock_decision_keeps_lock_when_mtime_is_unknown() { + let root = unique_project_path(); + init_local_game_project_at(&root, "lock-unknown-mtime", "锁回收-mtime未知") + .expect("初始化项目"); + let now = unix_timestamp(); + + let empty = project_lock_snapshot(&root, b""); + assert!( + !project_write_lock_reclaim_decision(&empty, None, now + 601, |_| None, |_| None), + "mtime 未知时空锁必须保持占用" + ); + assert!( + project_write_lock_reclaim_decision(&empty, Some(now - 120), now, |_| None, |_| None), + "mtime 已知且超过宽限期的空锁必须回收" + ); + + let live_old_format = project_lock_snapshot( + &root, + &serde_json::to_vec_pretty(&serde_json::json!({ + "commandId": "repro.live-writer", + "pid": 4_242, + "nonce": 1, + })) + .expect("序列化项目写锁 fixture"), + ); + assert!( + !project_write_lock_reclaim_decision( + &live_old_format, + None, + now + 601, + |_| Some(true), + |_| Some(now + 3_600) + ), + "创建时间未知时不能按 PID 复用抢走活持有者" + ); + 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..acd0c02a6 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -8188,3 +8188,12 @@ 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 秒，mtime 不可读时按未知年龄不回收。活持有者始终不回收。 +- 决策：回收判据与删除基于同一次读到的锁文件快照——payload 只解析一次，删除前重新核对字节，只有内容仍是判定时的内容才 unlink；文件已消失或被替换时重试 `create_new`，不把并发回收当成错误。 +- 决策：启动诊断日志用 `StartupLogSlot`，优先用已生效的配置目录（含 `--config-dir`），否则退到平台配置根（Windows APPDATA、macOS Application Support、其它平台 `XDG_CONFIG_HOME` / `~/.config`），配置目录就绪后再切换；`startup.*.failed` 与 `show_startup_error_dialog` 必须可达，日志路径未知时也必须给出用户可见提示；Windows 启动失败弹系统消息框，其它平台写 stderr。 +- 边界：`agent-runner.lock` / `agent-runner.gui-owner.lock` 是 OS 独占句柄锁，进程退出即释放，残留文件不阻塞下次启动；不要把它们当成项目写锁的同类残留处理。 +- 边界：锁文件里的 PID 若超出平台进程号空间（Unix `pid_t` 是有符号 32 位、Windows 是 32 位，均恒大于 0），它不可能属于任何活进程，按“持有者不存在”直接回收，不再落回 600 秒保守分支。 +- 验证：`project_lock_recovery` 11 条与 `diagnostic_log` 7 条定向测试通过，真实二进制双实例复现“第二个实例写 `startup.runner.owner-lock.failed` 并弹出可见提示”。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index c864f70fb..5cdc004ac 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -5031,3 +5031,19 @@ - 处理：框选命中判断使用 `Element.closest('.genarrative-image-canvas__world')`，并保留 viewport 自身命中路径；回归测试通过真实 `CanvasWorld` DOM 的 `pointerdown` 冒泡覆盖内层 world content。 - 验证：`src/components/image-editor/useImageCanvasStageInteractions.test.tsx` 覆盖内层 world content 命中，定向交互测试通过。 - 关联：`packages/image-canvas-react/src/useImageCanvasStageInteractions.ts`、`packages/image-canvas-react/src/CanvasWorld.tsx`。 + +## 跨平台“死进程 PID” fixture 必须落在 Unix 有符号 32 位范围内（2026-09-09） + +- 现象：`project_lock_recovery::project_write_lock_reclaims_dead_owner_pid` 在 Windows 本地通过，在 Linux CI 报“死进程残留锁未被回收，实际错误：项目正在被其他写操作占用”。 +- 原因：fixture 用 `0xFFFF_FFF0` 当死 PID；Unix 的 `pid_t` 是有符号 32 位，`i32::try_from` 直接失败，存活判定返回 `None`（无法判定）而不是 `Some(false)`，于是落回 600 秒保守分支，残留锁不再被回收。 +- 处理：实现层把“平台不可能分配出的进程号”（0 或超出平台 pid 宽度）判为持有者不存在并直接回收；fixture 改用 `i32::MAX as u64 - 1`，另加 `u64::MAX` 非法进程号用例。 +- 验证：WSL Ubuntu 上 `cargo test --bin genarrative-ai-game-creator-shell project_lock_recovery` 7 条全过；Windows 上把可表示性判据临时回退到 HEAD 后，只有 `project_write_lock_reclaims_unrepresentable_owner_pid` 失败，说明该用例确实覆盖这条分支；Linux CI 的原始失败记录覆盖越界 PID 分支。 +- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`、`apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs`。 + +## 锁文件回收的判定与删除必须基于同一份快照（2026-09-09） + +- 现象：两个实例同时恢复同一个崩溃项目时，后判定的一方可能删掉另一方刚装上的活锁；`remove_file` 的 `NotFound` 还会被当成硬失败，直接报“清理失效项目写锁失败”。 +- 原因：`project_write_lock_can_be_reclaimed` 只是快照观察，调用方拿到 true 后无条件 unlink；helper 还分别重读 `createdAt` / `pid` / `processStartedAt`，并发替换会拼出“旧 inode 的死 PID + 新 inode 的启动身份”。 +- 处理：payload 只解析一次并连同字节一起快照；删除前重新核对字节，只有内容仍是判定时的内容才 unlink；文件已消失或被替换时返回 false 并重试 `create_new`，不报错。 +- 补充：`project_write_lock_file_modified_seconds` 读不到 mtime 时不要返回 `0`——纪元 0 会被算成极大年龄，把保守判定反转成“立刻回收”，甚至把活持有者当 PID 复用抢走；要用 `Option` 区分“mtime 未知”和“mtime 等于纪元 0”。 +- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 5cf960dcf..9313fba40 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -1330,3 +1330,10 @@ 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 秒；无法判定持有者是否存活、或 mtime 不可读时保持保守（前者 600 秒、后者不回收），活持有者仍然不回收。 +- 回收判据与删除必须基于同一次读到的锁文件快照：payload 只解析一次，删除前重新核对字节，只有内容仍是判定时的内容才 unlink；文件已消失或被替换时重试 `create_new`，不把并发回收当成错误。 +- 启动诊断日志改为 `StartupLogSlot`：优先用已经生效的配置目录（含 `--config-dir`），否则退到平台配置根（Windows APPDATA、macOS Application Support、其它平台 `XDG_CONFIG_HOME` / `~/.config`），成功后再切换到真实配置目录。`startup.*.failed` 与 `show_startup_error_dialog` 不再是死分支；日志路径未知时同样给出用户可见提示。Windows 启动失败恢复系统消息框并附诊断日志路径，其它平台写 stderr，同一进程只提示一次。 +- 边界与验证：残留的 `agent-runner.lock` / `agent-runner.gui-owner.lock` 是 OS 独占句柄锁，进程退出即释放，文件本身不阻塞下次启动；真正阻塞启动的是仍有活进程持锁。验证覆盖 `project_lock_recovery` 11 条（死 PID、非法进程号、空锁宽限、PID 复用时间推断、PID 复用身份不一致、身份一致不抢锁、旧格式活持有者不抢锁、新鲜空锁不抢锁、存活未知保守回收、mtime 未知保守回收、并发替换或已消失时不删除）、`diagnostic_log` 7 条，以及真实二进制双实例：第二个实例写入 `startup.runner.owner-lock.failed` 并弹出可见提示。