SlothFile: Công cụ sắp xếp tệp yêu cầu xác nhận trước khi thực hiện bất kỳ thao tác nào

Đây là bài dự thi tham gia Thử thách AI nguồn mở Hacktoberfest Tuần 3: "Chậm mà chắc" (Slow and Steady). Giới thiệu dự án SlothFile là ứng dụng máy tính ưu tiên xử lý cục bộ (local-first), có chức năng sắp xếp thư mục nhưng không tự ý đưa ra bất kỳ quyết định nào ngoài sự kiểm soát của người dùng. Ứng dụng hướng tới việc xử lý các thư mục lộn xộn, nơi tập tin "final_v2 (3).pdf" nằm cạnh ba bản sao của cùng một hóa đơn, một bản quét mang tên "0042.pdf" cùng ảnh chụp màn hình được lưu trữ từ năm 2023. SlothFile tiến hành quét thư mục, đọc trích đoạn ngắn từ các tệp định dạng .txt, .md và .pdf, sau đó sử dụng mô hình vận hành cục bộ trên Ollama để đề xuất danh mục, tên gọi chuẩn xác hơn, điểm độ tin cậy cùng một câu tóm tắt lý do. Tiếp đó, hệ thống tạm dừng và hiển thị kế hoạch để người dùng xem xét. Người dùng có thể kiểm tra từng đề xuất, chỉnh sửa tên hoặc danh mục, từ chối những mục chưa phù hợp và phê duyệt các nội dung còn lại. Chỉ những thao tác đã được phê duyệt mới được tiến hành. Từng thao tác đều được kiểm tra lại ngay trước khi thực thi và được ghi nhận vào nhật ký hệ thống trước khi có bất kỳ tác động nào tới tệp tin. Tính năng lịch sử cho phép hoàn tác sau đó, với điều kiện thao tác hoàn tác được bảo đảm an toàn tuyệt đối. Ứng dụng giúp cắt giảm các công đoạn xử lý thủ công tốn thời gian, bao gồm việc đọc tên tệp, phán đoán thư mục phân loại cho tệp PDF, gõ lại tên tệp phù hợp hơn và thao tác kéo thả từng tệp đơn lẻ. Quyền quyết định then chốt vẫn thuộc về người dùng, thông qua danh sách tổng hợp thay vì phải thao tác trực tiếp trên trình quản lý tệp vào đêm muộn. Đối tượng thụ hưởng là bất kỳ ai đang quản lý thư mục Tải về (Downloads) trong tình trạng quá tải. SlothFile được phát triển trong tuần diễn ra thử thách, do đó phạm vi ứng dụng được chủ động tinh gọn: xử lý từng thư mục đơn lẻ, lập một kế hoạch có thể kiểm tra và áp dụng một bước phê duyệt duy nhất. Đây không phải là phương thức nhanh nhất đối với nhu cầu phân loại một nhóm nhỏ gồm năm tệp tin, vốn có thể xử lý nhanh hơn bằng thao tác kéo thả thủ công. SlothFile được thiết kế cho những thư mục tồn đọng lâu ngày, nơi sự chậm trễ chủ yếu xuất phát từ quá trình ra quyết định thay vì thao tác di chuyển tệp. Ứng dụng vẫn vận hành đầy đủ khi tắt tính năng AI. Các tác vụ quét, phát hiện tệp trùng lặp, lập kế hoạch thủ công, thực thi, theo dõi lịch sử và hoàn tác đều hoạt động bình thường mà không cần mô hình ngôn ngữ. AI đóng vai trò là công cụ hỗ trợ tùy chọn, không phải yếu tố phụ thuộc bắt buộc. Tên gọi SlothFile phản ánh nhịp độ xử lý thay vì chất lượng vận hành: Quét, xem xét, phê duyệt và thực thi. Tiêu chí "chậm mà chắc" là mô hình bảo đảm an toàn cốt lõi của ứng dụng, không phải là sự thỏa hiệp về mặt hiệu năng. Trạng thái: Phiên bản 0.1.0, hiện vận hành từ mã nguồn. Chưa có bản cài đặt thương mại hoặc bản dựng trực tuyến được phát hành. Thử nghiệm và vận hành Dự án không triển khai phiên bản trực tuyến trên nền tảng web nhằm bảo đảm an toàn dữ liệu. Nguyên tắc hoạt động của SlothFile là can thiệp vào các tệp trên máy tính bằng mô hình chạy nội bộ. Một phiên bản thử nghiệm trên trình duyệt sẽ làm thay đổi bản chất ứng dụng và gia tăng nguy cơ mất an toàn thông tin. Quy trình cài đặt đầy đủ từ kho mã nguồn: git clone https://github.com/CodesWithSubham/slothfile.git cd slothfile pnpm install pnpm dev Tùy chọn tải mô hình AI cục bộ: ollama pull gemma3:4b Các bước thao tác trên ứng dụng: Cài đặt (Settings) → Kiểm tra lại (Check again) → Chọn mô hình → Chọn thư mục → Quét → Lập kế hoạch → Xem xét → Phê duyệt → Thực thi. Các tính năng hiển thị trong quá trình vận hành: Tiến trình quét tích hợp nút hủy; tiến trình chỉ dừng lại giữa các tệp, không dừng khi tệp đang trong quá trình di chuyển. Bảng đề xuất hiển thị thư mục đích, độ tin cậy, các cảnh báo xác thực và lý do do mô hình AI đưa ra. Nút "Phê duyệt các mục an toàn" (Approve all safe) tự động bỏ qua các hàng có độ tin cậy thấp hoặc có cảnh báo. Hộp thoại xác nhận cuối cùng liệt kê chi tiết mọi tệp sắp được di chuyển. Nhật ký lịch sử ghi nhận kết quả xử lý của từng tệp, đi kèm nút Hoàn tác (Undo) có cơ chế từ chối thực hiện nếu phát hiện rủi ro thay vì xử lý theo phán đoán. Để kiểm tra nhanh khả năng vận hành của hệ thống, người dùng có thể tắt AI và tạo kế hoạch thủ công. Cơ chế bảo đảm an toàn vẫn được duy trì đồng nhất. Mã nguồn CodesWithSubham / slothfile SlothFile Sắp xếp tệp tin khoa học. Tối giản hóa công sức. AI lập kế hoạch. Người dùng phê duyệt mọi thao tác. SlothFile là một ứng dụng máy tính ưu tiên xử lý cục bộ (local-first), hỗ trợ sắp xếp các thư mục lộn xộn (như thư mục Downloads). Ứng dụng quét thư mục được chỉ định, tùy chọn sử dụng mô hình AI cục bộ để gợi ý danh mục và tên rõ ràng hơn cho từng tệp, hiển thị kế hoạch dự kiến và chỉ di chuyển tệp sau khi có sự phê duyệt. Mọi thao tác di chuyển đều được ghi nhật ký và có thể hoàn tác trong điều kiện bảo đảm an toàn. Tình trạng: phiên bản thử nghiệm sớm (0.1.0). Hiện chưa công bố các bản phát hành, tệp tải về, hình ảnh giao diện hay số liệu đánh giá hiệu năng (benchmarks). Các nguyên tắc hoạt động Chậm và chắc: quy trình gồm quét kỹ lưỡng → xem xét → phê duyệt → thực thi. Ưu tiên cục bộ: siêu dữ liệu (metadata) được lưu trữ trên máy tính của người dùng; AI vận hành qua công cụ Ollama nội bộ. Con người kiểm soát: AI đề xuất, người dùng quyết định. An toàn theo mặc định: tệp không bao giờ bị xóa, không bị ghi đè và không bị di chuyển nếu không có sự đồng ý rõ ràng. Tính năng Thư mục… Xem trên GitHub Kho mã nguồn: github.com/CodesWithSubham/slothfile (giấy phép MIT) Ba tệp tin trọng tâm trong mã nguồn: src/main/ai/providers/ollama-provider.ts — xử lý đầu ra có cấu trúc, kiểm thực với Zod, thời gian chờ (timeout), hủy tác vụ và mặc định chỉ kết nối nội bộ (loopback-only). src/main/filesystem/operations/safe-move.ts — thao tác di chuyển bảo đảm không ghi đè dữ liệu. src/main/operations/recovery/reconcile.ts — quy trình xử lý phục hồi dữ liệu khi xảy ra sự cố đột ngột. Kiến trúc xây dựng Ngăn xếp công nghệ: Electron 45, electron-vite, React 19, TypeScript ở chế độ nghiêm ngặt (strict mode), Tailwind CSS v4, Zustand, TanStack Query, Zod, better-sqlite3, pdfjs-dist, Vitest, Testing Library, Playwright và Oxlint. Ứng dụng không sử dụng thư viện thành phần giao diện (UI component library). Các thành phần tại thư mục src/renderer/components/ui được xây dựng thủ công bằng HTML ngữ nghĩa, hỗ trợ phím tắt và hiển thị tiêu điểm rõ ràng. Ứng dụng được thiết kế theo kiến trúc khối đơn mô-đun (modular monolith) với ranh giới phân định nghiêm ngặt: tiến trình chính (main process) được cấp quyền tin cậy, tiến trình kết xuất (renderer) thì không. Tiến trình chính nắm quyền kiểm soát hệ thống tệp, cơ sở dữ liệu SQLite, các tác vụ xử lý và trình kết nối AI. Lớp tiền tải (preload) cung cấp giao diện lập trình ứng dụng (API) khép kín được tạo từ một danh sách tên duy nhất. Lớp này không nạp bất kỳ gói npm nào do môi trường hộp cát (sandbox) không cho phép tải thư viện bên ngoài. Tiến trình kết xuất là một ứng dụng React chạy trong môi trường hộp cát, không trực tiếp tiếp nhận đường dẫn hệ thống tệp để thực thi thao tác. Cơ chế giao tiếp liên tiến trình (IPC) được tổ chức qua một kênh duy nhất với tên định sẵn, lược đồ Zod nghiêm ngặt, cơ chế kiểm tra bên gửi/khung hình/nguồn gốc (sender/frame/origin check) và dữ liệu phản hồi được chuẩn hóa dưới dạng { ok, data } hoặc { ok: false, error }. Trình biên dịch bảo đảm tính đồng bộ tuyệt đối giữa danh sách định danh, các lược đồ và kiểu dữ liệu đầu ra. Khâu tích hợp AI được thiết kế tinh gọn có chủ đích. Ollama được kích hoạt với định dạng JSON schema, tham số nhiệt độ (temperature) bằng 0 và thời gian chờ rộng lượng do yêu cầu đầu tiên có thể bao gồm thời gian nạp mô hình. Phản hồi được phân tích cú pháp, kiểm thực qua Zod và được thử lại đúng một lần nếu dữ liệu trả về rỗng hoặc sai định dạng. Mọi trường hợp khác sẽ chuyển thành