feat(cli): ov cli grep with --exclude-uri/ -x option (#1174)

heaoxiang-ai · web-flow · commit 2ce4fd497694 · 2026-04-02T20:17:55.000+08:00
* feat: add ov grep cli  exclude uri args

* feat: grep with exclude uri

* feat: add sdk document and grep method() args
diff --git a/bot/vikingbot/openviking_mount/ov_server.py b/bot/vikingbot/openviking_mount/ov_server.py
@@ -334,10 +334,21 @@ async def search_memory(
             "agent_memory": agent_memory.memories if hasattr(agent_memory, "memories") else [],
         }
 
-    async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict[str, Any]:
+    async def grep(
+        self,
+        uri: str,
+        pattern: str,
+        case_insensitive: bool = False,
+        node_limit: Optional[int] = 10,
+        exclude_uri: Optional[str] = None,
+    ) -> Dict[str, Any]:
         """通过模式（正则表达式）搜索内容"""
         return await self.client.grep(
-            uri, pattern, case_insensitive=case_insensitive, node_limit=10
+            uri,
+            pattern,
+            case_insensitive=case_insensitive,
+            node_limit=node_limit,
+            exclude_uri=exclude_uri,
         )
 
     async def glob(self, pattern: str, uri: Optional[str] = None) -> Dict[str, Any]:
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
@@ -514,12 +514,14 @@ impl HttpClient {
     pub async fn grep(
         &self,
         uri: &str,
+        exclude_uri: Option<String>,
         pattern: &str,
         ignore_case: bool,
         node_limit: i32,
     ) -> Result<serde_json::Value> {
         let body = serde_json::json!({
             "uri": uri,
+            "exclude_uri": exclude_uri,
             "pattern": pattern,
             "case_insensitive": ignore_case,
             "node_limit": node_limit,
diff --git a/crates/ov_cli/src/commands/search.rs b/crates/ov_cli/src/commands/search.rs
@@ -44,13 +44,16 @@ pub async fn search(
 pub async fn grep(
     client: &HttpClient,
     uri: &str,
+    exclude_uri: Option<String>,
     pattern: &str,
     ignore_case: bool,
     node_limit: i32,
     output_format: OutputFormat,
     compact: bool,
 ) -> Result<()> {
-    let result = client.grep(uri, pattern, ignore_case, node_limit).await?;
+    let result = client
+        .grep(uri, exclude_uri, pattern, ignore_case, node_limit)
+        .await?;
     output_success(&result, output_format, compact);
     Ok(())
 }
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
@@ -405,6 +405,9 @@ enum Commands {
         /// Target URI
         #[arg(short, long, default_value = "viking://")]
         uri: String,
+        /// Excluded URI range. Any entry whose URI falls under this URI prefix is skipped
+        #[arg(short = 'x', long = "exclude-uri")]
+        exclude_uri: Option<String>,
         /// Search pattern
         pattern: String,
         /// Case insensitive
@@ -801,10 +804,11 @@ async fn main() {
         } => handle_search(query, uri, session_id, node_limit, threshold, ctx).await,
         Commands::Grep {
             uri,
+            exclude_uri,
             pattern,
             ignore_case,
             node_limit,
-        } => handle_grep(uri, pattern, ignore_case, node_limit, ctx).await,
+        } => handle_grep(uri, exclude_uri, pattern, ignore_case, node_limit, ctx).await,
 
         Commands::Glob {
             pattern,
@@ -1425,12 +1429,16 @@ async fn handle_stat(uri: String, ctx: CliContext) -> Result<()> {
 
 async fn handle_grep(
     uri: String,
+    exclude_uri: Option<String>,
     pattern: String,
     ignore_case: bool,
     node_limit: i32,
     ctx: CliContext,
 ) -> Result<()> {
     let mut params = vec![format!("--uri={}", uri), format!("-n {}", node_limit)];
+    if let Some(excluded) = &exclude_uri {
+        params.push(format!("-x {}", excluded));
+    }
     if ignore_case {
         params.push("-i".to_string());
     }
@@ -1440,6 +1448,7 @@ async fn handle_grep(
     commands::search::grep(
         &client,
         &uri,
+        exclude_uri,
         &pattern,
         ignore_case,
         node_limit,
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
@@ -299,6 +299,8 @@ Search content by pattern (regex).
 | uri | str | Yes | - | Viking URI to search in |
 | pattern | str | Yes | - | Search pattern (regex) |
 | case_insensitive | bool | No | False | Ignore case |
+| node_limit | int | No | None | Maximum number of nodes to search |
+| exclude_uri | str | No | None | URI prefix to exclude from search |
 
 **Python SDK (Embedded / HTTP)**
 
diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
@@ -299,6 +299,8 @@ curl -X POST http://localhost:1933/api/v1/search/search \
 | uri | str | 是 | - | 要搜索的 Viking URI |
 | pattern | str | 是 | - | 搜索模式（正则表达式） |
 | case_insensitive | bool | 否 | False | 忽略大小写 |
+| node_limit | int | 否 | None | 最大搜索节点数 |
+| exclude_uri | str | 否 | None | 要排除在搜索之外的 URI 前缀 |
 
 **Python SDK (Embedded / HTTP)**
 
diff --git a/openviking/async_client.py b/openviking/async_client.py
@@ -422,10 +422,23 @@ async def rm(self, uri: str, recursive: bool = False) -> None:
         await self._ensure_initialized()
         await self._client.rm(uri, recursive=recursive)
 
-    async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:
+    async def grep(
+        self,
+        uri: str,
+        pattern: str,
+        case_insensitive: bool = False,
+        node_limit: Optional[int] = None,
+        exclude_uri: Optional[str] = None,
+    ) -> Dict:
         """Content search"""
         await self._ensure_initialized()
-        return await self._client.grep(uri, pattern, case_insensitive=case_insensitive)
+        return await self._client.grep(
+            uri,
+            pattern,
+            case_insensitive=case_insensitive,
+            node_limit=node_limit,
+            exclude_uri=exclude_uri,
+        )
 
     async def glob(self, pattern: str, uri: str = "viking://") -> Dict:
         """File pattern matching"""
diff --git a/openviking/client/local.py b/openviking/client/local.py
@@ -320,10 +320,22 @@ async def _search():
             execution.telemetry,
         )
 
-    async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict[str, Any]:
+    async def grep(
+        self,
+        uri: str,
+        pattern: str,
+        case_insensitive: bool = False,
+        node_limit: Optional[int] = None,
+        exclude_uri: Optional[str] = None,
+    ) -> Dict[str, Any]:
         """Content search with pattern."""
         return await self._service.fs.grep(
-            uri, pattern, ctx=self._ctx, case_insensitive=case_insensitive
+            uri,
+            pattern,
+            ctx=self._ctx,
+            case_insensitive=case_insensitive,
+            node_limit=node_limit,
+            exclude_uri=exclude_uri,
         )
 
     async def glob(self, pattern: str, uri: str = "viking://") -> Dict[str, Any]:
diff --git a/openviking/server/routers/search.py b/openviking/server/routers/search.py
@@ -63,6 +63,7 @@ class GrepRequest(BaseModel):
     """Request model for grep."""
 
     uri: str
+    exclude_uri: Optional[str] = None
     pattern: str
     case_insensitive: bool = False
     node_limit: Optional[int] = None
@@ -158,6 +159,7 @@ async def grep(
         request.uri,
         request.pattern,
         ctx=_ctx,
+        exclude_uri=request.exclude_uri,
         case_insensitive=request.case_insensitive,
         node_limit=request.node_limit,
     )
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
@@ -162,13 +162,19 @@ async def grep(
         uri: str,
         pattern: str,
         ctx: RequestContext,
+        exclude_uri: Optional[str] = None,
         case_insensitive: bool = False,
         node_limit: Optional[int] = None,
     ) -> Dict:
         """Content search."""
         viking_fs = self._ensure_initialized()
         return await viking_fs.grep(
-            uri, pattern, case_insensitive=case_insensitive, node_limit=node_limit, ctx=ctx
+            uri,
+            pattern,
+            exclude_uri=exclude_uri,
+            case_insensitive=case_insensitive,
+            node_limit=node_limit,
+            ctx=ctx,
         )
 
     async def glob(
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
@@ -536,6 +536,7 @@ async def grep(
         self,
         uri: str,
         pattern: str,
+        exclude_uri: Optional[str] = None,
         case_insensitive: bool = False,
         node_limit: Optional[int] = None,
         ctx: Optional[RequestContext] = None,
@@ -548,23 +549,40 @@ async def grep(
 
         flags = re.IGNORECASE if case_insensitive else 0
         compiled_pattern = re.compile(pattern, flags)
+        excluded_prefix = None
+        if exclude_uri:
+            excluded_prefix = self._normalize_uri(exclude_uri).rstrip("/")
+            self._ensure_access(excluded_prefix, ctx)
 
         results = []
 
         async def search_recursive(current_uri: str):
             if node_limit and len(results) >= node_limit:
                 return
 
+            normalized_current_uri = self._normalize_uri(current_uri)
+            if excluded_prefix and (
+                normalized_current_uri == excluded_prefix
+                or normalized_current_uri.startswith(excluded_prefix + "/")
+            ):
+                logger.debug(f"Skipping excluded uri during grep: {normalized_current_uri}")
+                return
+
             try:
-                entries = await self.ls(current_uri, ctx=ctx)
+                entries = await self.ls(normalized_current_uri, ctx=ctx)
             except Exception:
                 return
 
             for entry in entries:
                 if node_limit and len(results) >= node_limit:
                     break
 
-                entry_uri = f"{current_uri.rstrip('/')}/{entry['name']}"
+                entry_uri = f"{normalized_current_uri.rstrip('/')}/{entry['name']}"
+                if excluded_prefix and (
+                    entry_uri == excluded_prefix or entry_uri.startswith(excluded_prefix + "/")
+                ):
+                    logger.debug(f"Skipping excluded uri during grep: {entry_uri}")
+                    continue
 
                 if entry.get("isDir"):
                     await search_recursive(entry_uri)
@@ -591,7 +609,7 @@ async def search_recursive(current_uri: str):
 
         await search_recursive(uri)
 
-        return {"matches": results}
+        return {"matches": results, "count": len(results)}
 
     async def stat(self, uri: str, ctx: Optional[RequestContext] = None) -> Dict[str, Any]:
         """
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
@@ -263,9 +263,20 @@ def wait_processed(self, timeout: float = None) -> Dict[str, Any]:
         """Wait for all async operations to complete"""
         return run_async(self._async_client.wait_processed(timeout))
 
-    def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict:
+    def grep(
+        self,
+        uri: str,
+        pattern: str,
+        case_insensitive: bool = False,
+        node_limit: Optional[int] = None,
+        exclude_uri: Optional[str] = None,
+    ) -> Dict:
         """Content search"""
-        return run_async(self._async_client.grep(uri, pattern, case_insensitive))
+        return run_async(
+            self._async_client.grep(
+                uri, pattern, case_insensitive, node_limit, exclude_uri
+            )
+        )
 
     def glob(self, pattern: str, uri: str = "viking://") -> Dict:
         """File pattern matching"""
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
@@ -176,7 +176,14 @@ async def search(
         ...
 
     @abstractmethod
-    async def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> Dict[str, Any]:
+    async def grep(
+        self,
+        uri: str,
+        pattern: str,
+        case_insensitive: bool = False,
+        exclude_uri: Optional[str] = None,
+        node_limit: Optional[int] = None
+    ) -> Dict[str, Any]:
         """Content search with pattern."""
         ...
 
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
@@ -648,6 +648,7 @@ async def grep(
         pattern: str,
         case_insensitive: bool = False,
         node_limit: Optional[int] = None,
+        exclude_uri: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Content search with pattern."""
         uri = VikingURI.normalize(uri)
@@ -658,6 +659,8 @@ async def grep(
         }
         if node_limit is not None:
             request_json["node_limit"] = node_limit
+        if exclude_uri is not None:
+            request_json["exclude_uri"] = VikingURI.normalize(exclude_uri)
         response = await self._http.post(
             "/api/v1/search/grep",
             json=request_json,
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
@@ -248,9 +248,10 @@ def grep(
         pattern: str,
         case_insensitive: bool = False,
         node_limit: Optional[int] = None,
+        exclude_uri: Optional[str] = None,
     ) -> Dict:
         """Content search with pattern."""
-        return run_async(self._async_client.grep(uri, pattern, case_insensitive, node_limit))
+        return run_async(self._async_client.grep(uri, pattern, case_insensitive, node_limit, exclude_uri))
 
     def glob(self, pattern: str, uri: str = "viking://") -> Dict:
         """File pattern matching."""
diff --git a/tests/api_test/api/client.py b/tests/api_test/api/client.py
@@ -191,10 +191,21 @@ def search(
             payload["filter"] = filter
         return self._request_with_retry("POST", url, json=payload)
 
-    def grep(self, uri: str, pattern: str, case_insensitive: bool = False) -> requests.Response:
+    def grep(
+        self,
+        uri: str,
+        pattern: str,
+        case_insensitive: bool = False,
+        node_limit: Optional[int] = None,
+        exclude_uri: Optional[str] = None,
+    ) -> requests.Response:
         endpoint = "/api/v1/search/grep"
         url = self._build_url(self.server_url, endpoint)
         payload = {"uri": uri, "pattern": pattern, "case_insensitive": case_insensitive}
+        if node_limit is not None:
+            payload["node_limit"] = node_limit
+        if exclude_uri is not None:
+            payload["exclude_uri"] = exclude_uri
         return self._request_with_retry("POST", url, json=payload)
 
     def glob(self, pattern: str, uri: Optional[str] = None) -> requests.Response:
diff --git a/tests/server/test_api_search.py b/tests/server/test_api_search.py
