修复 AGC 文件列举被无关临时锁删除打断（#552） (#580)

列举 `assets` 时，原实现先递归扫描整个项目，再过滤范围；`.agent/project.lock` 在枚举与读取元数据之间正常删除会使整次查询失败。

现在在读取条目元数据前裁剪目标范围与受保护路径，只遍历目标子树及必要祖先。枚举后消失的文件／目录仅跳过 `NotFound`，其余权限与 IO 错误仍返回；进入排队目录前复核符号链接与 Windows 重解析点。通用文件树保留原有可见范围，Agent 结果继续过滤、排序后分页。

通过通道协调真实项目写锁释放，确定性覆盖全量扫描的 TOCTOU 及定向 `assets` 扫描；另覆盖目录消失／类型变化、权限错误、私有路径、链接、引擎目录和分页。同步更新 AGC 契约与共享排障记录。

验证：

- 15 条定向 Rust 测试通过：`cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- --test-threads=1 project_file_listing generic_file_tools local_project_file_commands external_listing`
- 生产 Rust 检查通过：`cargo check --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell`
- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。
- 本地验证在 Linux 执行，未运行 Windows 专属运行时验证；分页仍是实时观察，不承诺跨请求快照一致性。

Fixes #552

Reviewed-on: #580

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

@@ -1288,23 +1288,15 @@ fn bridge_list_project_files(root: &Path, arguments: &Value) -> Value {
         let scope_relative = scope
             .and_then(|scope| scope.project_relative)
             .filter(|path| !path.is_empty());
-        let listed = list_local_project_files_at(root)?;
-        let scope_prefix = scope_relative.as_ref().map(|path| format!("{path}/"));
+        let listed = list_local_project_files_scoped_at(root, scope_relative.as_deref(), |path| {
+            bridge_project_file_is_hidden_control_path(path)
+                || should_skip_project_snapshot_path(path)
+                || reject_sensitive_project_file_read(path).is_err()
+        })?;
         let mut files = listed
             .files
             .into_iter()
             .filter(|file| file.kind == "file")
-            .filter(|file| !bridge_project_file_is_hidden_control_path(&file.path))
-            .filter(|file| !should_skip_project_snapshot_path(&file.path))
-            .filter(|file| reject_sensitive_project_file_read(&file.path).is_ok())
-            .filter(|file| {
-                scope_relative.as_ref().is_none_or(|scope| {
-                    file.path == *scope
-                        || scope_prefix
-                            .as_ref()
-                            .is_some_and(|prefix| file.path.starts_with(prefix))
-                })
-            })
             .filter(|file| {
                 let (category, _) = bridge_project_file_class(&file.path);
                 requested_kind == "all" || requested_kind == category
@@ -4195,6 +4187,73 @@ mod tests {
         );
     }
 
+    #[test]
+    fn bridge_project_file_listing_scopes_filters_and_paginates_visible_files() {
+        let temporary = tempfile::tempdir().unwrap();
+        let root = temporary.path();
+        init_local_game_project_at(root, "scoped-file-listing", "定向文件列举").unwrap();
+        for path in [
+            "assets/z.png",
+            "assets/nested/b.png",
+            "assets/a.png",
+            "assets/notes.txt",
+            "assets-other/wrong.png",
+            "unrelated/wrong.png",
+            ".agent/hidden.png",
+            "assets/.env",
+            "assets/secret.key",
+            "assets/.codex/hidden.png",
+            "assets/node_modules/hidden.png",
+            "assets/.git/hidden.png",
+        ] {
+            let target = root.join(path);
+            fs::create_dir_all(target.parent().unwrap()).unwrap();
+            fs::write(target, b"test-only").unwrap();
+        }
+        let payload = |arguments: Value| {
+            let result = bridge_list_project_files(root, &arguments);
+            assert_eq!(result["isError"], false, "{result}");
+            serde_json::from_str::<Value>(result["content"][0]["text"].as_str().unwrap()).unwrap()
+        };
+        let first = payload(json!({ "path": "assets", "kind": "image", "limit": 2 }));
+        assert_eq!(first["total"], 3);
+        assert_eq!(first["offset"], 0);
+        assert_eq!(first["limit"], 2);
+        assert_eq!(first["nextOffset"], 2);
+        assert_eq!(first["files"][0]["path"], "assets/a.png");
+        assert_eq!(first["files"][1]["path"], "assets/nested/b.png");
+        let last = payload(json!({ "path": "assets", "kind": "image", "offset": 2, "limit": 2 }));
+        assert_eq!(last["total"], 3);
+        assert_eq!(last["files"].as_array().unwrap().len(), 1);
+        assert_eq!(last["files"][0]["path"], "assets/z.png");
+        assert!(last["nextOffset"].is_null());
+        for path in ["assets/nested", "assets/nested/b.png"] {
+            let page = payload(json!({ "path": path }));
+            assert_eq!(page["total"], 1);
+            assert_eq!(page["files"][0]["path"], "assets/nested/b.png");
+        }
+        assert_eq!(
+            payload(json!({ "path": "assets", "query": "NESTED" }))["total"],
+            1
+        );
+        assert_eq!(payload(json!({ "path": "assets" }))["total"], 4);
+        assert_eq!(payload(json!({ "path": "missing" }))["total"], 0);
+        let beyond = payload(json!({ "path": "assets", "offset": 20 }));
+        assert!(beyond["files"].as_array().unwrap().is_empty());
+        assert!(beyond["nextOffset"].is_null());
+        for path in [
+            ".agent",
+            "assets/.env",
+            "assets/.codex",
+            "assets/node_modules",
+        ] {
+            assert_eq!(
+                bridge_list_project_files(root, &json!({ "path": path }))["isError"],
+                true
+            );
+        }
+    }
+
     #[tokio::test]
     async fn analytics_real_file_write_preserves_original_identity_and_failed_run_revision() {
         use crate::analytics::{

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

@@ -1,5 +1,8 @@
 use super::*;
 
+#[cfg(test)]
+mod listing_tests;
+
 /**
  * Cocos Creator 工程根目录下的**生成目录**（导入缓存、构建临时目录、编辑器本地配置）。
  *
@@ -18,6 +21,24 @@ fn is_engine_generated_root_directory(relative_path: &str) -> bool {
 
 pub(crate) fn list_local_project_files_at(
     root: &Path,
+) -> Result<ListLocalProjectFilesResult, String> {
+    list_local_project_files_scoped_at(root, None, |_| false)
+}
+
+/// 在读取元数据前裁剪范围；调用方的可见性规则不改变通用文件树。
+pub(crate) fn list_local_project_files_scoped_at(
+    root: &Path,
+    scope: Option<&str>,
+    exclude: impl Fn(&str) -> bool,
+) -> Result<ListLocalProjectFilesResult, String> {
+    list_local_project_files_with_metadata(root, scope, exclude, |path| fs::symlink_metadata(path))
+}
+
+fn list_local_project_files_with_metadata(
+    root: &Path,
+    scope: Option<&str>,
+    exclude: impl Fn(&str) -> bool,
+    mut read_metadata: impl FnMut(&Path) -> std::io::Result<fs::Metadata>,
 ) -> Result<ListLocalProjectFilesResult, String> {
     validate_project_root(root)?;
     if !root.exists() {
@@ -37,28 +58,58 @@ pub(crate) fn list_local_project_files_at(
      */
     let skip_engine_generated_directories = discover_local_cocos_project_root(root)?.is_some();
     let is_unity_project = discover_local_unity_project_root(root)?.is_some();
+    let scope_prefix = scope.map(|path| format!("{path}/"));
     let mut files = Vec::new();
     let mut dirs = vec![root.to_path_buf()];
     while let Some(dir) = dirs.pop() {
-        for entry in fs::read_dir(&dir)
-            .map_err(|error| format!("读取项目目录失败：{}: {error}", dir.display()))?
-        {
+        // 目录排队后可能消失或被换成链接，进入前重新核验。
+        let metadata = match read_metadata(&dir) {
+            Ok(metadata) => metadata,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(error) => return Err(format!("读取文件元数据失败：{}: {error}", dir.display())),
+        };
+        if metadata.file_type().is_symlink() || windows_metadata_is_reparse_point(&metadata) {
+            continue;
+        }
+        let entries = match fs::read_dir(&dir) {
+            Ok(entries) => entries,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(error) => return Err(format!("读取项目目录失败：{}: {error}", dir.display())),
+        };
+        for entry in entries {
             let entry =
                 entry.map_err(|error| format!("读取项目文件失败：{}: {error}", dir.display()))?;
             let path = entry.path();
-            let metadata = fs::symlink_metadata(&path)
-                .map_err(|error| format!("读取文件元数据失败：{}: {error}", path.display()))?;
-            if metadata.file_type().is_symlink() || windows_metadata_is_reparse_point(&metadata) {
+            let relative_path = relative_project_path(root, &path)?;
+            let in_scope = scope.is_none_or(|scope| {
+                relative_path == scope
+                    || scope_prefix
+                        .as_ref()
+                        .is_some_and(|prefix| relative_path.starts_with(prefix))
+            });
+            let scope_ancestor =
+                scope.is_some_and(|scope| scope.starts_with(&format!("{relative_path}/")));
+            if (!in_scope && !scope_ancestor) || exclude(&relative_path) {
                 continue;
             }
-            let file_type = metadata.file_type();
-            let relative_path = relative_project_path(root, &path)?;
             if is_agent_runtime_private_control_path(&relative_path)
                 || is_agent_checkpoint_control_path(&relative_path)
                 || is_agent_workbench_control_path(&relative_path)
             {
                 continue;
             }
+            let metadata = match read_metadata(&path) {
+                Ok(metadata) => metadata,
+                // read_dir 只观察名字，不保证随后还能读取该条目。
+                Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+                Err(error) => {
+                    return Err(format!("读取文件元数据失败：{}: {error}", path.display()))
+                }
+            };
+            if metadata.file_type().is_symlink() || windows_metadata_is_reparse_point(&metadata) {
+                continue;
+            }
+            let file_type = metadata.file_type();
             let modified_at = metadata
                 .modified()
                 .ok()
@@ -80,14 +131,16 @@ pub(crate) fn list_local_project_files_at(
                 {
                     continue;
                 }
-                files.push(LocalProjectFileEntry {
-                    path: relative_path,
-                    kind: "directory".to_string(),
-                    size: 0,
-                    modified_at,
-                });
+                if in_scope {
+                    files.push(LocalProjectFileEntry {
+                        path: relative_path,
+                        kind: "directory".to_string(),
+                        size: 0,
+                        modified_at,
+                    });
+                }
                 dirs.push(path);
-            } else if file_type.is_file() {
+            } else if file_type.is_file() && in_scope {
                 let size = metadata.len();
                 files.push(LocalProjectFileEntry {
                     path: relative_path,

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

@@ -0,0 +1,288 @@
+use super::*;
+use std::io::{Error, ErrorKind};
+use std::sync::mpsc;
+use std::time::Duration;
+
+#[test]
+fn project_file_listing_survives_lock_release_between_enumeration_and_metadata() {
+    for scope in [None, Some("assets")] {
+        let temporary = tempfile::tempdir().unwrap();
+        let root = temporary.path().canonicalize().unwrap();
+        fs::create_dir(root.join("assets")).unwrap();
+        fs::write(root.join("assets/hero.png"), b"image").unwrap();
+        let (ready_tx, ready_rx) = mpsc::channel();
+        let (release_tx, release_rx) = mpsc::channel();
+        let (released_tx, released_rx) = mpsc::channel();
+        let timeout = Duration::from_secs(10);
+
+        std::thread::scope(|threads| {
+            let owner_root = &root;
+            let owner = threads.spawn(move || {
+                let lock = acquire_project_write_lock(owner_root, "file-listing-race").unwrap();
+                ready_tx.send(()).unwrap();
+                release_rx.recv_timeout(timeout).unwrap();
+                drop(lock);
+                released_tx.send(()).unwrap();
+            });
+            ready_rx.recv_timeout(timeout).unwrap();
+            let mut observed_gap = false;
+            let listed = list_local_project_files_with_metadata(
+                &root,
+                scope,
+                |_| false,
+                |path| {
+                    if scope.is_some() {
+                        assert!(
+                            !path.starts_with(root.join(".agent")),
+                            "定向列举不得检查锁目录"
+                        );
+                    }
+                    let trigger = if scope.is_some() {
+                        root.join("assets")
+                    } else {
+                        root.join(PROJECT_WRITE_LOCK_PATH)
+                    };
+                    if path == trigger && !observed_gap {
+                        // 全量列举复现锁的 TOCTOU；定向列举在访问 assets 时同时释放锁。
+                        release_tx.send(()).unwrap();
+                        released_rx.recv_timeout(timeout).unwrap();
+                        let result = fs::symlink_metadata(path);
+                        if scope.is_none() {
+                            assert_eq!(result.as_ref().unwrap_err().kind(), ErrorKind::NotFound);
+                        }
+                        observed_gap = true;
+                        return result;
+                    }
+                    fs::symlink_metadata(path)
+                },
+            )
+            .unwrap();
+            owner.join().unwrap();
+            assert!(observed_gap, "夹具必须在列举期间释放真实锁");
+            assert!(listed
+                .files
+                .iter()
+                .any(|file| file.path == "assets/hero.png"));
+            assert!(!listed
+                .files
+                .iter()
+                .any(|file| file.path == PROJECT_WRITE_LOCK_PATH));
+        });
+    }
+}
+
+#[test]
+fn project_file_listing_prunes_scope_and_private_paths_before_metadata() {
+    let temporary = tempfile::tempdir().unwrap();
+    let root = temporary.path();
+    for path in [
+        "assets/nested",
+        "assets-other",
+        ".agent/runtime",
+        ".agent/checkpoints",
+        ".agent/workbench",
+    ] {
+        fs::create_dir_all(root.join(path)).unwrap();
+    }
+    fs::write(root.join("assets/nested/hero.png"), b"image").unwrap();
+    fs::write(root.join("assets/other.png"), b"other").unwrap();
+    fs::write(root.join(".env"), b"test-only").unwrap();
+    for scope in ["assets/nested", "assets/nested/hero.png"] {
+        let listed = list_local_project_files_with_metadata(
+            root,
+            Some(scope),
+            |_| false,
+            |path| {
+                if path != root
+                    && path != root.join("assets")
+                    && !path.starts_with(root.join("assets/nested"))
+                {
+                    panic!("不应读取范围外元数据：{}", path.display());
+                }
+                fs::symlink_metadata(path)
+            },
+        )
+        .unwrap();
+        assert_eq!(
+            listed
+                .files
+                .iter()
+                .filter(|file| file.kind == "file")
+                .map(|file| file.path.as_str())
+                .collect::<Vec<_>>(),
+            ["assets/nested/hero.png"]
+        );
+    }
+    let listed = list_local_project_files_with_metadata(
+        root,
+        None,
+        |path| path == ".env",
+        |path| {
+            for excluded in [
+                ".env",
+                ".agent/runtime",
+                ".agent/checkpoints",
+                ".agent/workbench",
+            ] {
+                assert!(
+                    !path.starts_with(root.join(excluded)),
+                    "过滤必须早于元数据读取"
+                );
+            }
+            fs::symlink_metadata(path)
+        },
+    )
+    .unwrap();
+    assert!(
+        listed.files.iter().any(|file| file.path == ".agent"),
+        "通用文件树仍可见普通控制面目录"
+    );
+}
+
+#[test]
+fn project_file_listing_skips_disappearing_entries_but_preserves_io_errors() {
+    let temporary = tempfile::tempdir().unwrap();
+    let root = temporary.path();
+    fs::create_dir(root.join("assets")).unwrap();
+    let target = root.join("assets/hero.png");
+    fs::write(&target, b"image").unwrap();
+    for kind in [ErrorKind::PermissionDenied, ErrorKind::Other] {
+        let error = list_local_project_files_with_metadata(
+            root,
+            Some("assets"),
+            |_| false,
+            |path| {
+                if path == target {
+                    return Err(Error::new(kind, "listing-error-sentinel"));
+                }
+                fs::symlink_metadata(path)
+            },
+        )
+        .unwrap_err();
+        assert!(
+            error.contains("hero.png") && error.contains("listing-error-sentinel"),
+            "{error}"
+        );
+    }
+    let listed = list_local_project_files_with_metadata(
+        root,
+        Some("assets"),
+        |_| false,
+        |path| {
+            if path == target {
+                fs::remove_file(path).unwrap();
+            }
+            fs::symlink_metadata(path)
+        },
+    )
+    .unwrap();
+    assert!(!listed.files.iter().any(|file| file.kind == "file"));
+}
+
+#[test]
+fn project_file_listing_handles_queued_directory_disappearance_and_type_change() {
+    for change in ["before-metadata", "before-read-dir", "replace-with-file"] {
+        let temporary = tempfile::tempdir().unwrap();
+        let root = temporary.path();
+        let target = root.join("assets");
+        fs::create_dir(&target).unwrap();
+        let mut visits = 0;
+        let result = list_local_project_files_with_metadata(
+            root,
+            Some("assets"),
+            |_| false,
+            |path| {
+                if path == target {
+                    visits += 1;
+                    if visits == 2 {
+                        let previous = fs::symlink_metadata(path);
+                        fs::remove_dir(path).unwrap();
+                        if change == "before-read-dir" {
+                            return previous;
+                        }
+                        if change == "replace-with-file" {
+                            fs::write(path, b"not a directory").unwrap();
+                        }
+                    }
+                }
+                fs::symlink_metadata(path)
+            },
+        );
+        assert_eq!(visits, 2);
+        if change == "replace-with-file" {
+            assert!(result.unwrap_err().contains("读取项目目录失败"));
+        } else {
+            assert!(!result.unwrap().files.iter().any(|file| file.kind == "file"));
+        }
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn project_file_listing_reports_target_permission_errors_but_ignores_unrelated_ones() {
+    use std::os::unix::fs::PermissionsExt;
+    let temporary = tempfile::tempdir().unwrap();
+    let root = temporary.path();
+    let blocked = root.join("blocked");
+    fs::create_dir(&blocked).unwrap();
+    fs::create_dir(root.join("assets")).unwrap();
+    fs::write(root.join("assets/hero.png"), b"image").unwrap();
+    fs::set_permissions(&blocked, fs::Permissions::from_mode(0o000)).unwrap();
+    // 先恢复权限再断言，避免失败时影响临时目录回收。
+    let scoped = list_local_project_files_scoped_at(root, Some("assets"), |_| false);
+    let blocked_result = list_local_project_files_scoped_at(root, Some("blocked"), |_| false);
+    let permission_denied = fs::read_dir(&blocked).is_err();
+    fs::set_permissions(&blocked, fs::Permissions::from_mode(0o700)).unwrap();
+    assert!(scoped
+        .unwrap()
+        .files
+        .iter()
+        .any(|file| file.path == "assets/hero.png"));
+    // root / CAP_DAC_OVERRIDE 环境不能制造真实 EACCES；注入用例仍覆盖错误分支。
+    if permission_denied {
+        let error = blocked_result.unwrap_err();
+        assert!(
+            error.contains("读取项目目录失败") && error.contains("blocked"),
+            "{error}"
+        );
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn project_file_listing_never_enters_linked_or_replaced_directories() {
+    use std::os::unix::fs::symlink;
+    let temporary = tempfile::tempdir().unwrap();
+    let outside = tempfile::tempdir().unwrap();
+    let root = temporary.path();
+    fs::write(outside.path().join("private.txt"), b"outside").unwrap();
+    symlink(outside.path(), root.join("linked")).unwrap();
+    fs::create_dir(root.join("assets")).unwrap();
+    let mut visits = 0;
+    let listed = list_local_project_files_with_metadata(
+        root,
+        None,
+        |_| false,
+        |path| {
+            if path == root.join("assets") {
+                visits += 1;
+                if visits == 2 {
+                    fs::remove_dir(path).unwrap();
+                    symlink(outside.path(), path).unwrap();
+                }
+            }
+            fs::symlink_metadata(path)
+        },
+    )
+    .unwrap();
+    assert_eq!(visits, 2);
+    assert!(!listed.files.iter().any(|file| file.kind == "file"));
+    for scope in ["linked", "linked/private.txt", "assets/private.txt"] {
+        assert!(
+            list_local_project_files_scoped_at(root, Some(scope), |_| false)
+                .unwrap()
+                .files
+                .is_empty()
+        );
+    }
+}

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

@@ -3860,6 +3860,23 @@ fn local_project_file_listing_skips_engine_generated_directories_only_for_engine
     .expect("write cocos package.json");
 
     let listed = list_local_project_files_at(cocos).expect("list cocos project files");
+    for scope in ["library", "library/imported/hero.json", "temp/programming"] {
+        assert!(
+            list_local_project_files_scoped_at(cocos, Some(scope), |_| false)
+                .expect("list generated scope")
+                .files
+                .is_empty()
+        );
+    }
+    fs::create_dir_all(cocos.join("assets/library")).unwrap();
+    fs::write(cocos.join("assets/library/kept.png"), b"image").unwrap();
+    assert!(
+        list_local_project_files_scoped_at(cocos, Some("assets/library"), |_| false)
+            .unwrap()
+            .files
+            .iter()
+            .any(|file| file.path == "assets/library/kept.png")
+    );
     let paths = listed
         .files
         .iter()