Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
Feat/fs count api (#1989)
dingben3222b14d0cf6
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 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", ¶ms).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", ¶ms).await+ }+// ============ Search Methods ============pub async fn find(diff --git a/crates/ov_cli/src/commands/filesystem.rs b/crates/ov_cli/src/commands/filesystem.rsindex 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.rsindex 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", ¶ms.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.rsindex 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 foruri: 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.mdindex 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/docsThe `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.mdindex 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.pyindex 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.pyindex 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.pyindex 69f2a8bd4..e06f972f1 100644--- a/openviking/server/routers/filesystem.py+++ b/openviking/server/routers/filesystem.py@@ -122,6 +122,41 @@ async def stat(raise[email protected]("/count")+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.pyindex 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.urireturn 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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))