feat: implement cursor-based pagination across various components and APIs

domain/virtual_fs/api.py

@@ -183,9 +183,10 @@ async def browse_fs(
     page_size: int = Query(50, ge=1, le=500, description="每页条数"),
     sort_by: str = Query("name", description="按字段排序: name, size, mtime"),
     sort_order: str = Query("asc", description="排序顺序: asc, desc"),
+    cursor: str | None = Query(None, description="游标分页位置"),
 ):
     data = await VirtualFSService.list_directory_with_permission(
-        full_path, current_user.id, page_num, page_size, sort_by, sort_order
+        full_path, current_user.id, page_num, page_size, sort_by, sort_order, cursor
     )
     return success(data)
 
@@ -211,9 +212,10 @@ async def root_listing(
     page_size: int = Query(50, ge=1, le=500, description="每页条数"),
     sort_by: str = Query("name", description="按字段排序: name, size, mtime"),
     sort_order: str = Query("asc", description="排序顺序: asc, desc"),
+    cursor: str | None = Query(None, description="游标分页位置"),
 ):
     # 根目录不需要权限检查，但需要过滤无权限的子目录
     data = await VirtualFSService.list_directory_with_permission(
-        "/", current_user.id, page_num, page_size, sort_by, sort_order
+        "/", current_user.id, page_num, page_size, sort_by, sort_order, cursor
     )
     return success(data)

domain/virtual_fs/listing.py

@@ -57,6 +57,7 @@ class VirtualFSListingMixin(VirtualFSResolverMixin):
         page_size: int = 50,
         sort_by: str = "name",
         sort_order: str = "asc",
+        cursor: str | None = None,
     ) -> Dict:
         norm = cls._normalize_path(path).rstrip("/") or "/"
         adapters = await StorageAdapter.filter(enabled=True)
@@ -119,12 +120,28 @@ class VirtualFSListingMixin(VirtualFSResolverMixin):
         adapter_entries_for_merge: List[Dict] = []
         adapter_entries_page: List[Dict] | None = None
         adapter_total: int | None = None
+        adapter_listing: Dict[str, Any] | None = None
         if adapter_model and adapter_instance:
             list_dir = getattr(adapter_instance, "list_dir", None)
             if callable(list_dir):
-                adapter_entries_page, adapter_total = await list_dir(
-                    effective_root, rel, page_num, page_size, sort_by, sort_order
-                )
+                try:
+                    parameters = inspect.signature(list_dir).parameters
+                except (TypeError, ValueError):
+                    parameters = {}
+                if "cursor" in parameters:
+                    raw_listing = await list_dir(
+                        effective_root, rel, page_num, page_size, sort_by, sort_order, cursor=cursor
+                    )
+                else:
+                    raw_listing = await list_dir(
+                        effective_root, rel, page_num, page_size, sort_by, sort_order
+                    )
+                if isinstance(raw_listing, dict):
+                    adapter_listing = raw_listing
+                    adapter_entries_page = raw_listing.get("items", [])
+                    adapter_total = raw_listing.get("total")
+                else:
+                    adapter_entries_page, adapter_total = raw_listing
             if rel:
                 parent_rel = cls._parent_rel(rel)
                 if rel:
@@ -189,6 +206,9 @@ class VirtualFSListingMixin(VirtualFSResolverMixin):
         annotate_entry_list = adapter_entries_page or []
         for ent in annotate_entry_list:
             annotate_entry(ent)
+        if adapter_listing and adapter_listing.get("pagination_mode") == "cursor":
+            adapter_listing["items"] = annotate_entry_list
+            return adapter_listing
         return page(adapter_entries_page, adapter_total, page_num, page_size)
 
     @classmethod
@@ -296,13 +316,14 @@ class VirtualFSListingMixin(VirtualFSResolverMixin):
         page_size: int = 50,
         sort_by: str = "name",
         sort_order: str = "asc",
+        cursor: str | None = None,
     ) -> Dict:
         """
         带权限过滤的目录列表
         
         过滤掉用户没有读取权限的条目
         """
-        result = await cls.list_virtual_dir(path, page_num, page_size, sort_by, sort_order)
+        result = await cls.list_virtual_dir(path, page_num, page_size, sort_by, sort_order, cursor)
         items = result.get("items", [])
         if not items:
             return result

domain/virtual_fs/routes.py

@@ -275,15 +275,30 @@ class VirtualFSRouteMixin(VirtualFSTempLinkMixin):
     async def list_directory(cls, full_path: str, page_num: int, page_size: int, sort_by: str, sort_order: str):
         full_path = cls._normalize_path(full_path)
         result = await cls.list_virtual_dir(full_path, page_num, page_size, sort_by, sort_order)
+        pagination = {
+            "mode": result.get("pagination_mode", "paged"),
+            "page_size": result.get("page_size", page_size),
+        }
+        if pagination["mode"] == "cursor":
+            pagination.update(
+                {
+                    "cursor": result.get("cursor"),
+                    "next_cursor": result.get("next_cursor"),
+                    "has_next": bool(result.get("has_next")),
+                }
+            )
+        else:
+            pagination.update(
+                {
+                    "total": result["total"],
+                    "page": result["page"],
+                    "pages": result["pages"],
+                }
+            )
         return {
             "path": full_path,
             "entries": result["items"],
-            "pagination": {
-                "total": result["total"],
-                "page": result["page"],
-                "page_size": result["page_size"],
-                "pages": result["pages"],
-            },
+            "pagination": pagination,
         }
 
     @classmethod

domain/virtual_fs/service.py

@@ -26,9 +26,10 @@ class VirtualFSService(
         page_size: int = 50,
         sort_by: str = "name",
         sort_order: str = "asc",
+        cursor: str | None = None,
     ):
         """列出目录内容"""
-        return await cls.list_virtual_dir(path, page_num, page_size, sort_by, sort_order)
+        return await cls.list_virtual_dir(path, page_num, page_size, sort_by, sort_order, cursor)
 
     @classmethod
     async def list_directory_with_permission(
@@ -39,19 +40,35 @@ class VirtualFSService(
         page_size: int = 50,
         sort_by: str = "name",
         sort_order: str = "asc",
+        cursor: str | None = None,
     ):
         """列出目录内容（带权限过滤）"""
         full_path = cls._normalize_path(path).rstrip("/") or "/"
         result = await cls.list_virtual_dir_with_permission(
-            full_path, user_id, page_num, page_size, sort_by, sort_order
+            full_path, user_id, page_num, page_size, sort_by, sort_order, cursor
         )
+        pagination = {
+            "mode": result.get("pagination_mode", "paged") if isinstance(result, dict) else "paged",
+            "page_size": result.get("page_size", page_size) if isinstance(result, dict) else page_size,
+        }
+        if pagination["mode"] == "cursor":
+            pagination.update(
+                {
+                    "cursor": result.get("cursor") if isinstance(result, dict) else cursor,
+                    "next_cursor": result.get("next_cursor") if isinstance(result, dict) else None,
+                    "has_next": bool(result.get("has_next")) if isinstance(result, dict) else False,
+                }
+            )
+        else:
+            pagination.update(
+                {
+                    "total": result.get("total", 0) if isinstance(result, dict) else 0,
+                    "page": result.get("page", page_num) if isinstance(result, dict) else page_num,
+                    "pages": result.get("pages", 0) if isinstance(result, dict) else 0,
+                }
+            )
         return {
             "path": full_path,
             "entries": result.get("items", []) if isinstance(result, dict) else [],
-            "pagination": {
-                "total": result.get("total", 0) if isinstance(result, dict) else 0,
-                "page": result.get("page", page_num) if isinstance(result, dict) else page_num,
-                "page_size": result.get("page_size", page_size) if isinstance(result, dict) else page_size,
-                "pages": result.get("pages", 0) if isinstance(result, dict) else 0,
-            },
+            "pagination": pagination,
         }