feat: 优化回收站逻辑，废除剪贴板 Hacking，支持快捷键多选删除回退机制与高精度物理判定

2bitbit · 2bitbit · commit d91be763e399 · 2026-05-27T13:13:04.000+08:00
diff --git a/.agents/rules/README.md b/.agents/rules/README.md
@@ -0,0 +1,94 @@
+# 项目架构规范与设计原则 (.agents/rules)
+
+为了保证项目的健壮性、可读性以及跨语言数据契约的一致性，特制定以下开发规范与技术决策规范。后续无论是人类开发者还是 AI 代理，均应严格遵守以下准则。
+
+---
+
+## 1. VS Code 插件命令与快捷键设计规范
+
+- **智能混合路由与剪贴板回退（Hybrid Routing & Clipboard Fallback）**：
+  - **原则**：因为 VS Code 自身架构限制，当通过键盘快捷键（如 `Delete` 键）触发命令时，VS Code **不会**在参数中向命令处理函数传入当前侧边栏的多选 `uris` 数组；只有通过右键上下文菜单触发时，才会传入 `uris` 数组。
+  - **规范做法**：
+    1. **右键菜单路径**：直接读取原生传入的 `uris` 数组。这种方式最快、最安全，不产生任何剪贴板读写和时序延时。
+    2. **快捷键路径**：若 `uris` 数组为 `undefined` 或为空，则说明是通过快捷键触发的。此时程序必须安全回退到**“读取并暂存剪贴板 -> 执行 copyFilePath 命令复制选中项 -> 延时等待写入 -> 读取解析选中项 -> 立即恢复剪贴板”**的 Hack 逻辑以取回侧边栏选中的多路径列表。
+    3. **兜底路径**：如果依然为空，则依次尝试获取单个 `activeUri` 或是当前活动编辑器（`activeTextEditor`）中的文档路径。
+  - **实现模板**：
+    ```typescript
+    export async function myCommand(activeUri?: vscode.Uri, uris?: vscode.Uri[]) {
+      let targetUris: vscode.Uri[] = [];
+      
+      if (uris && uris.length > 0) {
+        // 右键菜单直接使用原生 uris
+        targetUris = uris;
+      } else {
+        // 快捷键触发回退到剪贴板 Hack
+        const originalClipboard = await vscode.env.clipboard.readText();
+        await vscode.commands.executeCommand("copyFilePath");
+        await delay(100);
+        const selectedPaths = await vscode.env.clipboard.readText();
+        await vscode.env.clipboard.writeText(originalClipboard);
+        if (selectedPaths.trim()) {
+          targetUris = selectedPaths.split(/\r?\n/).map(p => vscode.Uri.file(p));
+        }
+      }
+      
+      // 执行兜底与后续的包含路径去重过滤...
+    }
+    ```
+
+- **统一快捷键与右键菜单指令**：
+  - 在 `package.json` 中，将右键菜单与快捷键的 `command` 统一指向该混合路由命令，简化注册并在底层保证多选删除在两个入口下均能完美兼容。
+
+---
+
+## 2. 嵌套路径的安全删除规范
+
+- **原理**：当执行批量删除（特别是在 Rust 端的 `delete_all`）时，如果入参路径数组中同时包含父目录（如 `/a`）和子目录或文件（如 `/a/b.txt`），先删除父目录会导致子目录在物理磁盘上瞬间消失。后面对子目录的删除操作会因“路径不存在”而抛出底层 IO 异常，导致整个批处理操作崩溃中断。
+- **安全过滤规范**：在任何需要执行批量删除的接口前，必须对路径列表执行**子路径去重过滤**。如果某个路径是另一个待删路径的子集，则在前端剔除该子路径。
+- **实现算法**：
+  ```typescript
+  export function filterNestedPaths(paths: string[]): string[] {
+    const uniquePaths = Array.from(new Set(paths));
+    return uniquePaths.filter(path => {
+      return !uniquePaths.some(other => {
+        if (path === other) return false;
+        const parentWithSlash1 = other.endsWith("/") ? other : other + "/";
+        const parentWithSlash2 = other.endsWith("\\") ? other : other + "\\";
+        return path.startsWith(parentWithSlash1) || path.startsWith(parentWithSlash2);
+      });
+    });
+  }
+  ```
+
+---
+
+## 3. 回收站物理类型的判定规范
+
+- **废弃启发式正则判断**：
+  - **缺陷**：严禁在前端使用文件名正则（如“是否有点号后缀”）来启发式猜测回收站的项目是文件还是文件夹。这会导致 `LICENSE`、`Makefile` 等无后缀文件以及 `v1.0` 等带点号文件夹被完全判定错误。
+- **规范做法**：
+  - **跨语言传输**：由 Rust 核心层通过真实的操作系统回收站物理状态进行检查，在数据结构中透出 `is_dir` 物理类型布尔值。
+  - **Rust 后端判定算法**：
+    在 Linux (FreeDesktop) 环境中，每一个删除的文件对应 `~/.local/share/Trash/info/[Name].trashinfo`（元数据）与 `~/.local/share/Trash/files/[Name]`（真实被删物理内容）。
+    因此可以通过 `info` 的绝对路径，逆向推导其在 `files/` 目录中的真实路径，利用 Rust 的 `std::path::Path::is_dir()` 进行高精度检查：
+    ```rust
+    fn is_trash_item_dir(id_str: &str) -> bool {
+        let info_path = Path::new(id_str);
+        if let Some(parent) = info_path.parent().and_then(|p| p.parent()) {
+            if let Some(stem) = info_path.file_stem() {
+                let files_path = parent.join("files").join(stem);
+                return files_path.is_dir();
+            }
+        }
+        false
+    }
+    ```
+
+---
+
+## 4. 跨语言编译与发布规范
+
+- **N-API 桥接契约**：
+  - 对 Rust 端导出的任何结构体或函数变动，必须同步更新 [`src/core/trashBackend.d.ts`](file:///wsl.localhost/Ubuntu/home/finnwsl/repos/trash4wsl-in-vscode/src/core/trashBackend.d.ts) 中的 TypeScript 类型契约定义，并保证前端映射字段（如 `timeDeleted` -> `time_deleted` 等驼峰转换）完全正确。
+- **多架构分发**：
+  - 核心层基于 Linux 系统进行编译（WSL / SSH），分发包必须包含 `linux-x64-gnu` 和 `linux-arm64-gnu` 两套原生 `.node` 模块，并通过 CI（GitHub Actions）的交叉编译工具链（如 `gcc-aarch64-linux-gnu`）进行构建打包。
diff --git a/native-bindings/trash4wsl-backend.linux-x64-gnu.node b/native-bindings/trash4wsl-backend.linux-x64-gnu.node
diff --git a/package.json b/package.json
@@ -1,15 +1,11 @@
 {
-  "version": "2.0.1",
+  "version": "2.1.0",
   "contributes": {
     "commands": [
       {
-        "command": "trash4wsl-in-vscode.trashPutViaContextMenu",
+        "command": "trash4wsl-in-vscode.trashPut",
         "title": "丢入回收站(Trash It)"
       },
-      {
-        "command": "trash4wsl-in-vscode.trashPutViaShortcut",
-        "title": "通过快捷键丢入回收站"
-      },
       {
         "command": "trash4wsl-in-vscode.browseTrash",
         "title": "浏览回收站（历史记录、恢复、清空）",
@@ -19,7 +15,7 @@
     ],
     "keybindings": [
       {
-        "command": "trash4wsl-in-vscode.trashPutViaShortcut",
+        "command": "trash4wsl-in-vscode.trashPut",
         "key": "delete",
         "mac": "delete",
         "when": "resourceScheme == 'vscode-remote' && filesExplorerFocus && !explorerResourceIsRoot && resourceSet && !inputFocus"
@@ -34,18 +30,14 @@
     "menus": {
       "explorer/context": [
         {
-          "command": "trash4wsl-in-vscode.trashPutViaContextMenu",
+          "command": "trash4wsl-in-vscode.trashPut",
           "when": "resourceScheme == 'vscode-remote' && !explorerResourceIsRoot",
           "group": "7_modification@0"
         }
       ],
       "commandPalette": [
         {
-          "command": "trash4wsl-in-vscode.trashPutViaContextMenu",
-          "when": "false"
-        },
-        {
-          "command": "trash4wsl-in-vscode.trashPutViaShortcut",
+          "command": "trash4wsl-in-vscode.trashPut",
           "when": "false"
         }
       ]
diff --git a/rust-core/src/lib.rs b/rust-core/src/lib.rs
@@ -2,6 +2,7 @@
 
 use napi::bindgen_prelude::*;
 use napi_derive::napi; // 直接导入具体的宏
+use std::path::Path;
 use trash::delete_all;
 use trash::os_limited::{list, purge_all, restore_all};
 
@@ -11,6 +12,18 @@ pub struct TrashItemNode {
     pub name: String,
     pub original_parent: String,
     pub time_deleted: f64, // not i64, use f64 for JS number compatibility (timestamps)
+    pub is_dir: bool,
+}
+
+fn is_trash_item_dir(id_str: &str) -> bool {
+    let info_path = Path::new(id_str);
+    if let Some(parent) = info_path.parent().and_then(|p| p.parent()) {
+        if let Some(stem) = info_path.file_stem() {
+            let files_path = parent.join("files").join(stem);
+            return files_path.is_dir();
+        }
+    }
+    false
 }
 
 #[napi]
@@ -24,11 +37,16 @@ pub fn list_trash() -> Result<Vec<TrashItemNode>> {
     let items = list().map_err(|e| Error::from_reason(e.to_string()))?;
     Ok(items
         .into_iter()
-        .map(|item| TrashItemNode {
-            id: item.id.clone().into_string().unwrap_or_default(),
-            name: item.name.clone(),
-            original_parent: item.original_parent.to_string_lossy().into_owned(),
-            time_deleted: item.time_deleted as f64,
+        .map(|item| {
+            let id_str = item.id.clone().into_string().unwrap_or_default();
+            let is_dir = is_trash_item_dir(&id_str);
+            TrashItemNode {
+                id: id_str,
+                name: item.name.clone(),
+                original_parent: item.original_parent.to_string_lossy().into_owned(),
+                time_deleted: item.time_deleted as f64,
+                is_dir,
+            }
         })
         .collect())
 }
@@ -48,11 +66,14 @@ pub fn list_workspace_trash(path_prefix: String) -> Result<Vec<TrashItemNode>> {
                 || parent.starts_with(&path_with_slash)
                 || full_path == path_prefix
             {
+                let id_str = item.id.clone().into_string().unwrap_or_default();
+                let is_dir = is_trash_item_dir(&id_str);
                 Some(TrashItemNode {
-                    id: item.id.clone().into_string().unwrap_or_default(),
+                    id: id_str,
                     name: item.name.clone(),
                     original_parent: parent,
                     time_deleted: item.time_deleted as f64,
+                    is_dir,
                 })
             } else {
                 None
diff --git a/src/core/fsUtils.ts b/src/core/fsUtils.ts
@@ -16,28 +16,31 @@ export function getWorkspacePaths(): string[] {
 }
 
 /**
- * 根据输入参数或当前选择确定要处理的文件列表
+ * 根据输入参数或当前选择确定要处理的文件列表并进行去重与路径包含过滤
  * @param uris 所有要处理的文件/文件夹的 URI 数组
- * @returns 要处理的文件/文件夹的路径，转义后的数组
+ * @returns 过滤与去重后、要处理的文件/文件夹的绝对路径数组
  */
 export function Uris2Paths(uris: vscode.Uri[]): string[] {
-  return uris // 让父目录永远排在子目录/文件前面。这样删除的时候，父目录会先被删除，子目录/文件后被删除。便于恢复。
-    .map((f) => f.fsPath)
-    .sort((a, b) => {
-      if (a.startsWith(b + "/")) {
-        return 1;
-      }
-      if (b.startsWith(a + "/")) {
-        return -1;
+  // 1. 获取所有 fsPath 并去重
+  const uniquePaths = Array.from(new Set(uris.map((f) => f.fsPath)));
+
+  // 2. 过滤掉已被父目录包含的冗余子路径
+  // 例如，如果同时存在 "/a" 和 "/a/b"，因后者属于前者的子孙路径，移动父目录时子路径会被一并带走。
+  // 过滤掉子路径能彻底避免 Rust 端 delete_all 因找不到已被移走的子路径而抛出 Entity not found 错误。
+  return uniquePaths.filter((path) => {
+    return !uniquePaths.some((other) => {
+      if (path === other) {
+        return false;
       }
-      // 其他情况按字母顺序排序
-      return a.localeCompare(b);
+      const parentWithSlash1 = other.endsWith("/") ? other : other + "/";
+      const parentWithSlash2 = other.endsWith("\\") ? other : other + "\\";
+      return path.startsWith(parentWithSlash1) || path.startsWith(parentWithSlash2);
     });
+  });
 }
 
-/** 判断给定的path是文件还是目录*/
+/** 判断给定的path是文件还是目录 - 已废弃：存在启发式精度问题，新版本中应直接使用来自后端的物理 item.isDir 属性 */
 export function isFile(path: string): boolean {
-  // 不能使用 fsUtils.isFile(path) 因为这些文件已经被删除到回收站了
   const hasExtension = /\.[^/\.]+$/.test(path);
   const endsWithSlash = path.endsWith("/") || path.endsWith("\\");
   return hasExtension && !endsWithSlash;
diff --git a/src/core/trashBackend.d.ts b/src/core/trashBackend.d.ts
@@ -8,6 +8,7 @@ export interface TrashItemNode {
   name: string;
   originalParent: string;
   timeDeleted: number;
+  isDir: boolean;
 }
 
 export interface TrashBackend {
diff --git a/src/core/trashPutCommand.ts b/src/core/trashPutCommand.ts
@@ -2,36 +2,70 @@ import * as vscode from "vscode";
 import { normalizePaths, Uris2Paths } from "./fsUtils.js";
 import * as trashService from "./trashService.js";
 
-/** 在explorer的右键上下文菜单点击，丢入回收站 */
-export async function trashPutViaContextMenu(
-  _: vscode.Uri,
-  uris: vscode.Uri[],
-) {
-  // 处理参数：uris已经包含了所有的文件/文件夹，第一个参数是右键单击的那个文件/文件夹uri，不必理会。
-  let paths = Uris2Paths(uris);
-  paths = normalizePaths(paths);
-  await execTrashPut(paths);
-}
-
 const CLIPBOARD_DELAY_MS = 100;
 function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/**在explorer选中，通过快捷键执行trash-put */
-export async function trashPutViaShortcut() {
-  const originalClipboard = await vscode.env.clipboard.readText();
-  await vscode.commands.executeCommand("copyFilePath");
-  await delay(CLIPBOARD_DELAY_MS); // Required delay for VS Code to fill the clipboard asynchronously
-  const selectedPaths = await vscode.env.clipboard.readText();
-  await vscode.env.clipboard.writeText(originalClipboard);
+/**
+ * 统一的删除到回收站入口函数。
+ * 无论是通过右键上下文菜单还是快捷键触发，VS Code 在侧边栏有焦点时都会传入参数：
+ * @param activeUri 当前激活/聚焦的项的 URI
+ * @param uris 当前选中的所有项 of URI 数组
+ */
+export async function trashPut(
+  activeUri?: vscode.Uri,
+  uris?: vscode.Uri[],
+) {
+  console.log("执行 trashPut 命令, activeUri:", activeUri?.fsPath, "uris count:", uris?.length);
+
+  let targetUris: vscode.Uri[] = [];
+
+  // 1. 如果是通过右键菜单触发，VS Code 会在 arguments 中直接传入选中的 uris 数组
+  if (uris && uris.length > 0) {
+    targetUris = uris;
+  } else {
+    // 2. 如果是通过键盘快捷键（Delete）触发，VS Code 不会在参数中传入选中列表。
+    //    此时我们必须使用剪贴板 Hack 来安全获取侧边栏的当前选中项目。
+    try {
+      const originalClipboard = await vscode.env.clipboard.readText();
+      await vscode.commands.executeCommand("copyFilePath");
+      await delay(CLIPBOARD_DELAY_MS); // 等待异步剪贴板写入完成
+      const selectedPaths = await vscode.env.clipboard.readText();
+      await vscode.env.clipboard.writeText(originalClipboard); // 立即恢复用户原剪贴板内容
 
-  if (!selectedPaths.trim()) {
+      if (selectedPaths && selectedPaths.trim()) {
+        const paths = selectedPaths.split(/\r?\n/);
+        const normalized = normalizePaths(paths);
+        targetUris = normalized.map((p) => vscode.Uri.file(p));
+      }
+    } catch (err) {
+      console.error("通过剪贴板获取侧边栏选中文件失败:", err);
+    }
+  }
+
+  // 3. 兜底策略：如果以上机制均未获取到，则尝试使用 activeUri 或当前活动编辑器对应的文件
+  if (targetUris.length === 0) {
+    if (activeUri) {
+      targetUris = [activeUri];
+    } else if (vscode.window.activeTextEditor) {
+      targetUris = [vscode.window.activeTextEditor.document.uri];
+    }
+  }
+
+  if (targetUris.length === 0) {
+    console.log("未检测到待删除的有效目标");
     return;
   }
 
-  let paths = selectedPaths.split("\n");
+  // 转换成绝对路径并进行包含去重过滤
+  let paths = Uris2Paths(targetUris);
   paths = normalizePaths(paths);
+
+  if (paths.length === 0) {
+    return;
+  }
+
   await execTrashPut(paths);
 }
 
diff --git a/src/core/trashService.ts b/src/core/trashService.ts
@@ -45,6 +45,7 @@ export interface TrashItem {
   path: string;
   deletionDate: string;
   _id: string; // Internal native ID tracking
+  isDir: boolean;
 }
 
 /**
@@ -86,6 +87,7 @@ export async function listRestorableTrashItems(
         path: `${i.originalParent}/${i.name}`,
         deletionDate: dateStr,
         _id: i.id, // Track the native ID for restoring
+        isDir: i.isDir,
       };
     });
 
diff --git a/src/extension.ts b/src/extension.ts
diff --git a/src/ui/TrashPalette.ts b/src/ui/TrashPalette.ts

Original file line number	Diff line number	Diff line change
`@@ -1,15 +1,11 @@`
`1`	`1`	`{`
`2`		`- "version": "2.0.1",`
	`2`	`+ "version": "2.1.0",`
`3`	`3`	`"contributes": {`
`4`	`4`	`"commands": [`
`5`	`5`	`{`
`6`		`- "command": "trash4wsl-in-vscode.trashPutViaContextMenu",`
	`6`	`+ "command": "trash4wsl-in-vscode.trashPut",`
`7`	`7`	`"title": "丢入回收站(Trash It)"`
`8`	`8`	`},`
`9`		`- {`
`10`		`- "command": "trash4wsl-in-vscode.trashPutViaShortcut",`
`11`		`- "title": "通过快捷键丢入回收站"`
`12`		`- },`
`13`	`9`	`{`
`14`	`10`	`"command": "trash4wsl-in-vscode.browseTrash",`
`15`	`11`	`"title": "浏览回收站（历史记录、恢复、清空）",`
`@@ -19,7 +15,7 @@`
`19`	`15`	`],`
`20`	`16`	`"keybindings": [`
`21`	`17`	`{`
`22`		`- "command": "trash4wsl-in-vscode.trashPutViaShortcut",`
	`18`	`+ "command": "trash4wsl-in-vscode.trashPut",`
`23`	`19`	`"key": "delete",`
`24`	`20`	`"mac": "delete",`
`25`	`21`	`"when": "resourceScheme == 'vscode-remote' && filesExplorerFocus && !explorerResourceIsRoot && resourceSet && !inputFocus"`
`@@ -34,18 +30,14 @@`
`34`	`30`	`"menus": {`
`35`	`31`	`"explorer/context": [`
`36`	`32`	`{`
`37`		`- "command": "trash4wsl-in-vscode.trashPutViaContextMenu",`
	`33`	`+ "command": "trash4wsl-in-vscode.trashPut",`
`38`	`34`	`"when": "resourceScheme == 'vscode-remote' && !explorerResourceIsRoot",`
`39`	`35`	`"group": "7_modification@0"`
`40`	`36`	`}`
`41`	`37`	`],`
`42`	`38`	`"commandPalette": [`
`43`	`39`	`{`
`44`		`- "command": "trash4wsl-in-vscode.trashPutViaContextMenu",`
`45`		`- "when": "false"`
`46`		`- },`
`47`		`- {`
`48`		`- "command": "trash4wsl-in-vscode.trashPutViaShortcut",`
	`40`	`+ "command": "trash4wsl-in-vscode.trashPut",`
`49`	`41`	`"when": "false"`
`50`	`42`	`}`
`51`	`43`	`]`
Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,7 @@ export interface TrashItemNode {`
`8`	`8`	`name: string;`
`9`	`9`	`originalParent: string;`
`10`	`10`	`timeDeleted: number;`
	`11`	`+ isDir: boolean;`
`11`	`12`	`}`
`12`	`13`
`13`	`14`	`export interface TrashBackend {`