Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

Feat/fs count api (#1989)

dingben3222b14d0cf6
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 4e98379c3..cb63a7913 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -325,6 +325,20 @@ impl HttpClient {
self.get("/api/v1/fs/stat", &params).await
}
+ pub async fn count(
+ &self,
+ uri: &str,
+ recursive: bool,
+ show_all_hidden: bool,
+ ) -> Result<serde_json::Value> {
+ let params = vec![
+ ("uri".to_string(), uri.to_string()),
+ ("recursive".to_string(), recursive.to_string()),
+ ("show_all_hidden".to_string(), show_all_hidden.to_string()),
+ ];
+ self.get("/api/v1/fs/count", &params).await
+ }
+
// ============ Search Methods ============
pub async fn find(
diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rs
index daa0c8f03..0ea2c7bdc 100644
--- a/crates/ov_cli/src/commands/filesystem.rs
+++ b/crates/ov_cli/src/commands/filesystem.rs
@@ -107,3 +107,16 @@ pub async fn stat(
output_success(&result, output_format, compact);
Ok(())
}
+
+pub async fn count(
+ client: &HttpClient,
+ uri: &str,
+ recursive: bool,
+ show_all_hidden: bool,
+ output_format: OutputFormat,
+ compact: bool,
+) -> Result<()> {
+ let result = client.count(uri, recursive, show_all_hidden).await?;
+ output_success(&result, output_format, compact);
+ Ok(())
+}
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index f9670d226..c65115bdb 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -1150,6 +1150,33 @@ pub async fn handle_stat(uri: String, ctx: CliContext) -> Result<()> {
commands::filesystem::stat(&client, &uri, ctx.output_format, ctx.compact).await
}
+pub async fn handle_count(
+ uri: String,
+ recursive: bool,
+ show_all_hidden: bool,
+ ctx: CliContext,
+) -> Result<()> {
+ let mut params = vec![uri.clone()];
+ if recursive {
+ params.push("-r".to_string());
+ }
+ if show_all_hidden {
+ params.push("-a".to_string());
+ }
+ print_command_echo("ov count", &params.join(" "), ctx.config.echo_command);
+
+ let client = ctx.get_client();
+ commands::filesystem::count(
+ &client,
+ &uri,
+ recursive,
+ show_all_hidden,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
+}
+
pub async fn handle_grep(
uri: String,
exclude_uri: Option<String>,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 64302da15..3cbf8576e 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -309,6 +309,17 @@ enum Commands {
/// Viking URI to get metadata for
uri: String,
},
+ /// [Data] Count files and sub-directories under a directory
+ Count {
+ /// Directory URI to count
+ uri: String,
+ /// Recurse into all sub-directories
+ #[arg(short, long)]
+ recursive: bool,
+ /// Include hidden files (names starting with ".")
+ #[arg(short, long)]
+ all: bool,
+ },
/// [Data] Read file content (L2)
Read {
/// Viking URI
@@ -1166,6 +1177,11 @@ async fn main() {
Commands::Rm { uri, recursive } => handlers::handle_rm(uri, recursive, ctx).await,
Commands::Mv { from_uri, to_uri } => handlers::handle_mv(from_uri, to_uri, ctx).await,
Commands::Stat { uri } => handlers::handle_stat(uri, ctx).await,
+ Commands::Count {
+ uri,
+ recursive,
+ all,
+ } => handlers::handle_count(uri, recursive, all, ctx).await,
Commands::AddMemory { content } => handlers::handle_add_memory(content, ctx).await,
Commands::Tui { uri } => handlers::handle_tui(uri, ctx).await,
Commands::Chat {
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index 1c6e8f171..68a029db1 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -499,7 +499,67 @@ openviking stat viking://resources/my-project/docs
The `isLocked` field reports whether the path is currently held by a path lock — either the path itself has a valid `.path.ovlock`, or any ancestor directory holds a SUBTREE lock. Returns `false` when the LockManager is unavailable or the lookup fails, so callers can avoid attempting a write only to observe `ResourceBusyError`.
-The `count` field (directories only) contains the estimated number of items (files and subdirectories) under this directory (from vector index).
+The `count` field (directories only) contains the estimated number of items (files and subdirectories) under this directory (from vector index). For an exact count based on the actual filesystem listing, use [`count()`](#count) instead.
+
+---
+
+### count()
+
+Count files and sub-directories under a directory based on a real filesystem traversal (not a vector-index estimate).
+
+**Parameters**
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| uri | str | Yes | - | Target directory's Viking URI |
+| recursive | bool | No | False | Count all descendants when `True`; otherwise only direct children |
+| show_all_hidden | bool | No | False | Include hidden files (names starting with `.`) |
+
+**Python SDK (Embedded / HTTP)**
+
+```python
+result = client.count("viking://resources/my-project")
+print(f"files={result['files']}, dirs={result['dirs']}, total={result['total']}")
+
+# Recursive
+result = client.count("viking://resources/my-project", recursive=True)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/fs/count?uri={uri}&recursive={bool}&show_all_hidden={bool}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/fs/count?uri=viking://resources/my-project&recursive=true" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking count viking://resources/my-project
+openviking count viking://resources/my-project -r # recursive
+openviking count viking://resources/my-project -r -a # recursive, include hidden files
+```
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/my-project",
+ "files": 12,
+ "dirs": 3,
+ "total": 15
+ },
+ "time": 0.01
+}
+```
+
+If `uri` is not a directory, a `FailedPrecondition` error is returned; if `uri` does not exist, `NotFound` is returned.
---
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index d53b21916..293573baf 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -499,7 +499,67 @@ openviking stat viking://resources/my-project/docs
`isLocked` 字段反映路径当前是否被 path lock 持有:路径自身存在有效的 `.path.ovlock`,或者任一祖先目录持有 SUBTREE 锁。当 LockManager 不可用或查询失败时返回 `false`,调用方可据此避免先写入再观察到 `ResourceBusyError`。
-`count` 字段(仅目录)包含该目录下的项目(文件和子目录)估计数量(来自向量索引)。
+`count` 字段(仅目录)包含该目录下的项目(文件和子目录)估计数量(来自向量索引)。如需对实际文件系统目录项进行精确计数,请改用 [`count()`](#count)。
+
+---
+
+### count()
+
+统计目录下的文件和子目录数量(基于实际文件系统遍历,非向量索引估算)。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | 目标目录的 Viking URI |
+| recursive | bool | 否 | False | 是否递归统计所有后代;`False` 时只统计直接子项 |
+| show_all_hidden | bool | 否 | False | 是否包含隐藏文件(文件名以 `.` 开头) |
+
+**Python SDK (Embedded / HTTP)**
+
+```python
+result = client.count("viking://resources/my-project")
+print(f"files={result['files']}, dirs={result['dirs']}, total={result['total']}")
+
+# 递归统计
+result = client.count("viking://resources/my-project", recursive=True)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/fs/count?uri={uri}&recursive={bool}&show_all_hidden={bool}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/fs/count?uri=viking://resources/my-project&recursive=true" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking count viking://resources/my-project
+openviking count viking://resources/my-project -r # 递归
+openviking count viking://resources/my-project -r -a # 递归并包含隐藏文件
+```
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/my-project",
+ "files": 12,
+ "dirs": 3,
+ "total": 15
+ },
+ "time": 0.01
+}
+```
+
+若 `uri` 不是目录,会返回 `FailedPrecondition` 错误;若 `uri` 不存在,则返回 `NotFound`。
---
diff --git a/openviking/async_client.py b/openviking/async_client.py
index d0bf84b22..9d965ccc2 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -517,6 +517,20 @@ class AsyncOpenViking:
await self._ensure_initialized()
return await self._client.stat(uri)
+ async def count(
+ self,
+ uri: str,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ) -> Dict[str, int]:
+ """Count files and sub-directories under a directory."""
+ await self._ensure_initialized()
+ return await self._client.count(
+ uri,
+ recursive=recursive,
+ show_all_hidden=show_all_hidden,
+ )
+
# ============= Relation methods =============
async def relations(self, uri: str) -> List[Dict[str, Any]]:
diff --git a/openviking/client/local.py b/openviking/client/local.py
index f4ee93319..8f473e56e 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -226,6 +226,20 @@ class LocalClient(BaseClient):
"""Get resource status."""
return await self._service.fs.stat(uri, ctx=self._ctx)
+ async def count(
+ self,
+ uri: str,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ) -> Dict[str, int]:
+ """Count files and sub-directories under a directory."""
+ return await self._service.fs.count(
+ uri,
+ ctx=self._ctx,
+ recursive=recursive,
+ show_all_hidden=show_all_hidden,
+ )
+
async def mkdir(self, uri: str, description: Optional[str] = None) -> None:
"""Create directory."""
await self._service.fs.mkdir(uri, ctx=self._ctx, description=description)
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 69f2a8bd4..e06f972f1 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -122,6 +122,41 @@ async def stat(
raise
+async def count(
+ uri: str = Query(..., description="Viking URI of a directory"),
+ recursive: bool = Query(False, description="Count all descendants recursively"),
+ show_all_hidden: bool = Query(False, description="Include hidden files/directories"),
+ _ctx: RequestContext = Depends(get_request_context),
+):
+ """Count files and sub-directories under a directory.
+
+ Returns a dict with keys ``files``, ``dirs`` and ``total``.
+ """
+ service = get_service()
+ uri = resolve_path_variables(uri)
+ try:
+ result = await service.fs.count(
+ uri,
+ ctx=_ctx,
+ recursive=recursive,
+ show_all_hidden=show_all_hidden,
+ )
+ except AGFSNotFoundError:
+ raise NotFoundError(uri, "file")
+ except AGFSClientError as e:
+ err_msg = str(e).lower()
+ if "not found" in err_msg or "no such file or directory" in err_msg:
+ raise NotFoundError(uri, "file")
+ raise
+ except Exception as exc:
+ mapped = map_exception(exc, resource=uri)
+ if mapped is not None:
+ raise mapped from exc
+ raise
+ return Response(status="ok", result={"uri": uri, **result})
+
+
class MkdirRequest(BaseModel):
"""Request model for mkdir."""
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index 64a9d8355..2ef8e5576 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -157,7 +157,9 @@ class FSService:
directory_uri = VikingURI(abstract_uri).parent.uri
return directory_uri, abstract_uri
- async def rm(self, uri: str, ctx: RequestContext, recursive: bool = False) -> Optional[Dict[str, Any]]:
+ async def rm(
+ self, uri: str, ctx: RequestContext, recursive: bool = False
+ ) -> Optional[Dict[str, Any]]:
"""Remove resource."""
uri = validate_viking_uri(uri)
viking_fs = self._ensure_initialized()
@@ -199,6 +201,29 @@ class FSService:
uri = validate_viking_uri(uri)
return await viking_fs.stat(uri, ctx=ctx)
+ async def count(
+ self,
+ uri: str,
+ ctx: RequestContext,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ) -> Dict[str, int]:
+ """Count files and sub-directories under a directory.
+
+ Args:
+ uri: Viking URI (must be a directory).
+ recursive: If True, count all descendants; otherwise only direct children.
+ show_all_hidden: If True, include hidden files/directories.
+ """
+ viking_fs = self._ensure_initialized()
+ uri = validate_viking_uri(uri)
+ return await viking_fs.count(
+ uri,
+ recursive=recursive,
+ show_all_hidden=show_all_hidden,
+ ctx=ctx,
+ )
+
async def read(self, uri: str, ctx: RequestContext, offset: int = 0, limit: int = -1) -> str:
"""Read file content."""
viking_fs = self._ensure_initialized()
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 49cfa0cc4..a2986929d 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -445,9 +445,7 @@ class VikingFS:
path = self._uri_to_path(uri, ctx=ctx)
target_uri = self._path_to_uri(path, ctx=ctx)
- async def _estimate_deleted_count(
- target_path: str, real_ctx: RequestContext
- ) -> int:
+ async def _estimate_deleted_count(target_path: str, real_ctx: RequestContext) -> int:
"""Estimate number of nodes to be deleted using vector index."""
vector_store = self._get_vector_store()
if not vector_store:
@@ -1212,6 +1210,74 @@ class VikingFS:
return all_entries
+ async def count(
+ self,
+ uri: str,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ctx: Optional[RequestContext] = None,
+ ) -> Dict[str, int]:
+ """Count files and sub-directories under a directory.
+
+ Args:
+ uri: Viking URI (must be a directory).
+ recursive: If True, count all descendants; otherwise only direct children.
+ show_all_hidden: If True, include hidden files/directories (name starts with ".").
+ ctx: Request context.
+
+ Returns:
+ Dict with keys:
+ - files: number of files
+ - dirs: number of sub-directories
+ - total: files + dirs
+ """
+ self._ensure_access(uri, ctx)
+ path = self._uri_to_path(uri, ctx=ctx)
+ real_ctx = self._ctx_or_default(ctx)
+
+ try:
+ info = self.agfs.stat(path)
+ except Exception as exc:
+ mapped = map_exception(exc, resource=uri)
+ if mapped is not None:
+ raise mapped from exc
+ raise NotFoundError(uri, "directory")
+
+ if not info.get("isDir", info.get("is_dir")):
+ raise FailedPreconditionError(
+ f"{uri} is not a directory",
+ details={"resource": uri, "expected": "directory"},
+ )
+
+ files = 0
+ dirs = 0
+
+ def _count_entries(current_path: str) -> None:
+ nonlocal files, dirs
+ try:
+ entries = self._ls_entries(current_path)
+ except Exception:
+ return
+ for entry in entries:
+ name = entry.get("name", "")
+ if name in (".", ".."):
+ continue
+ is_dir = entry.get("isDir", False)
+ entry_uri = self._path_to_uri(f"{current_path}/{name}", ctx=ctx)
+ if not self._is_accessible(entry_uri, real_ctx):
+ continue
+ if not is_dir and name.startswith(".") and not show_all_hidden:
+ continue
+ if is_dir:
+ dirs += 1
+ if recursive:
+ _count_entries(f"{current_path}/{name}")
+ else:
+ files += 1
+
+ _count_entries(path)
+ return {"files": files, "dirs": dirs, "total": files + dirs}
+
# ========== VikingFS Specific Capabilities ==========
async def abstract(
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index 77c1c4872..33f3ffe53 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -382,6 +382,21 @@ class SyncOpenViking:
"""Get resource status"""
return run_async(self._async_client.stat(uri))
+ def count(
+ self,
+ uri: str,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ) -> Dict[str, int]:
+ """Count files and sub-directories under a directory."""
+ return run_async(
+ self._async_client.count(
+ uri,
+ recursive=recursive,
+ show_all_hidden=show_all_hidden,
+ )
+ )
+
def mkdir(self, uri: str, description: Optional[str] = None) -> None:
"""Create directory"""
return run_async(self._async_client.mkdir(uri, description=description))
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index 0a9446e50..e0673ab42 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -539,6 +539,24 @@ class AsyncHTTPClient(BaseClient):
)
return self._handle_response(response)
+ async def count(
+ self,
+ uri: str,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ) -> Dict[str, Any]:
+ """Count files and sub-directories under a directory."""
+ uri = VikingURI.normalize(uri)
+ response = await self._http.get(
+ "/api/v1/fs/count",
+ params={
+ "uri": uri,
+ "recursive": recursive,
+ "show_all_hidden": show_all_hidden,
+ },
+ )
+ return self._handle_response(response)
+
async def mkdir(self, uri: str, description: Optional[str] = None) -> None:
"""Create directory."""
uri = VikingURI.normalize(uri)
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
index 9819f26db..e9077d76e 100644
--- a/openviking_cli/client/sync_http.py
+++ b/openviking_cli/client/sync_http.py
@@ -344,6 +344,21 @@ class SyncHTTPClient:
"""Get resource status."""
return run_async(self._async_client.stat(uri))
+ def count(
+ self,
+ uri: str,
+ recursive: bool = False,
+ show_all_hidden: bool = False,
+ ) -> Dict:
+ """Count files and sub-directories under a directory."""
+ return run_async(
+ self._async_client.count(
+ uri,
+ recursive=recursive,
+ show_all_hidden=show_all_hidden,
+ )
+ )
+
def mkdir(self, uri: str, description: Optional[str] = None) -> None:
"""Create directory."""
run_async(self._async_client.mkdir(uri, description=description))