Skip to content

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

CLI commands (ls, tree) output optimize (#156)

MaojiaSheng49c0afaaf8f5
diff --git a/openviking/async_client.py b/openviking/async_client.py
index 9eaa76ce7..b4f48ed5a 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -268,7 +268,17 @@ class AsyncOpenViking:
await self._ensure_initialized()
recursive = kwargs.get("recursive", False)
simple = kwargs.get("simple", False)
- return await self._client.ls(uri, recursive=recursive, simple=simple)
+ output = kwargs.get("output", "original")
+ abs_limit = kwargs.get("abs_limit", 256)
+ show_all_hidden = kwargs.get("show_all_hidden", True)
+ return await self._client.ls(
+ uri,
+ recursive=recursive,
+ simple=simple,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ )
async def rm(self, uri: str, recursive: bool = False) -> None:
"""Remove resource"""
@@ -290,10 +300,15 @@ class AsyncOpenViking:
await self._ensure_initialized()
await self._client.mv(from_uri, to_uri)
- async def tree(self, uri: str) -> Dict:
+ async def tree(self, uri: str, **kwargs) -> Dict:
"""Get directory tree"""
await self._ensure_initialized()
- return await self._client.tree(uri)
+ output = kwargs.get("output", "original")
+ abs_limit = kwargs.get("abs_limit", 128)
+ show_all_hidden = kwargs.get("show_all_hidden", True)
+ return await self._client.tree(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
async def mkdir(self, uri: str) -> None:
"""Create directory"""
diff --git a/openviking/client/local.py b/openviking/client/local.py
index 6e84a63ba..46acca99d 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -88,13 +88,36 @@ class LocalClient(BaseClient):
# ============= File System =============
- async def ls(self, uri: str, simple: bool = False, recursive: bool = False) -> List[Any]:
+ async def ls(
+ self,
+ uri: str,
+ simple: bool = False,
+ recursive: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ ) -> List[Any]:
"""List directory contents."""
- return await self._service.fs.ls(uri, simple=simple, recursive=recursive)
+ return await self._service.fs.ls(
+ uri,
+ simple=simple,
+ recursive=recursive,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ )
- async def tree(self, uri: str) -> List[Dict[str, Any]]:
+ async def tree(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ ) -> List[Dict[str, Any]]:
"""Get directory tree."""
- return await self._service.fs.tree(uri)
+ return await self._service.fs.tree(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
async def stat(self, uri: str) -> Dict[str, Any]:
"""Get resource status."""
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 8fe121c87..5e71fe656 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -19,22 +19,37 @@ async def ls(
uri: str = Query(..., description="Viking URI"),
simple: bool = Query(False, description="Return only relative path list"),
recursive: bool = Query(False, description="List all subdirectories recursively"),
+ output: str = Query("agent", description="Output format: original or agent"),
+ abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),
+ show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),
_: bool = Depends(verify_api_key),
):
"""List directory contents."""
service = get_service()
- result = await service.fs.ls(uri, recursive=recursive, simple=simple)
+ result = await service.fs.ls(
+ uri,
+ recursive=recursive,
+ simple=simple,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ )
return Response(status="ok", result=result)
@router.get("/tree")
async def tree(
uri: str = Query(..., description="Viking URI"),
+ output: str = Query("agent", description="Output format: original or agent"),
+ abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),
+ show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),
_: bool = Depends(verify_api_key),
):
"""Get directory tree."""
service = get_service()
- result = await service.fs.tree(uri)
+ result = await service.fs.tree(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
return Response(status="ok", result=result)
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index 52f6d4a6e..72e5526d8 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -31,20 +31,35 @@ class FSService:
raise NotInitializedError("VikingFS")
return self._viking_fs
- async def ls(self, uri: str, recursive: bool = False, simple: bool = False) -> List[Any]:
+ async def ls(
+ self,
+ uri: str,
+ recursive: bool = False,
+ simple: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ ) -> List[Any]:
"""List directory contents.
Args:
uri: Viking URI
recursive: List all subdirectories recursively
simple: Return only relative path list
+ output: str = "original" or "agent"
+ abs_limit: int = 256 if output == "agent" else ignore
+ show_all_hidden: bool = False (list all hidden files, like -a)
"""
viking_fs = self._ensure_initialized()
if recursive:
- entries = await viking_fs.tree(uri)
+ entries = await viking_fs.tree(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
else:
- entries = await viking_fs.ls(uri)
+ entries = await viking_fs.ls(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
if simple:
return [e.get("rel_path", e.get("name", "")) for e in entries]
@@ -65,10 +80,18 @@ class FSService:
viking_fs = self._ensure_initialized()
await viking_fs.mv(from_uri, to_uri)
- async def tree(self, uri: str) -> List[Dict[str, Any]]:
+ async def tree(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ ) -> List[Dict[str, Any]]:
"""Get directory tree."""
viking_fs = self._ensure_initialized()
- return await viking_fs.tree(uri)
+ return await viking_fs.tree(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
async def stat(self, uri: str) -> Dict[str, Any]:
"""Get resource status."""
diff --git a/openviking/storage/vectordb/collection/local_collection.py b/openviking/storage/vectordb/collection/local_collection.py
index 60b451255..1a8b10caf 100644
--- a/openviking/storage/vectordb/collection/local_collection.py
+++ b/openviking/storage/vectordb/collection/local_collection.py
@@ -291,6 +291,7 @@ class LocalCollection(ICollection):
if not self.store_mgr:
raise RuntimeError("Store manager is not initialized")
cands_list = self.store_mgr.fetch_cands_data(label_list)
+ cands_list = [cand for cand in cands_list if cand is not None]
cands_fields = [json.loads(cand.fields) for cand in cands_list]
if self.meta.primary_key:
pk_list = [
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index d7a9f6476..2b42dc332 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -15,14 +15,16 @@ Responsibilities:
import asyncio
import json
from dataclasses import dataclass, field
+from datetime import datetime
from pathlib import PurePath
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
from pyagfs import AGFSClient
from openviking.storage.vikingdb_interface import VikingDBInterface
-from openviking.utils.time_utils import get_current_timestamp
+from openviking.utils.time_utils import format_simplified, get_current_timestamp
from openviking_cli.utils.logger import get_logger
+from openviking_cli.utils.uri import VikingURI
if TYPE_CHECKING:
from openviking_cli.utils.config import RerankConfig
@@ -204,11 +206,67 @@ class VikingFS:
matches.append(f"{base_uri}/{rel_path}")
return {"matches": matches, "count": len(matches)}
+ async def _batch_fetch_abstracts(
+ self,
+ entries: List[Dict[str, Any]],
+ abs_limit: int,
+ ) -> None:
+ """Batch fetch abstracts for entries.
+
+ Args:
+ entries: List of entries to fetch abstracts for
+ abs_limit: Maximum length for abstract truncation
+ """
+ semaphore = asyncio.Semaphore(6)
+
+ async def fetch_abstract(index: int, entry: Dict[str, Any]) -> tuple[int, str]:
+ async with semaphore:
+ if not entry.get("isDir", False):
+ return index, ""
+ try:
+ abstract = await self.abstract(entry["uri"])
+ return index, abstract
+ except Exception:
+ return index, "[.abstract.md is not ready]"
+
+ tasks = [fetch_abstract(i, entry) for i, entry in enumerate(entries)]
+ abstract_results = await asyncio.gather(*tasks)
+ for index, abstract in abstract_results:
+ if len(abstract) > abs_limit:
+ abstract = abstract[: abs_limit - 3] + "..."
+ entries[index]["abstract"] = abstract
+
async def tree(
self,
uri: str = "viking://",
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
) -> List[Dict[str, Any]]:
- """Recursively list all contents (includes rel_path)."""
+ """
+ Recursively list all contents (includes rel_path).
+
+ Args:
+ uri: Viking URI
+ output: str = "original" or "agent"
+ abs_limit: int = 256 (for agent output abstract truncation)
+ show_all_hidden: bool = False (list all hidden files, like -a)
+
+ output="original"
+ [{'name': '.abstract.md', 'size': 100, 'mode': 420, 'modTime': '2026-02-11T16:52:16.256334192+08:00', 'isDir': False, 'meta': {...}, 'rel_path': '.abstract.md', 'uri': 'viking://resources...'}]
+
+ output="agent"
+ [{'name': '.abstract.md', 'size': 100, 'modTime': '2026-02-11 16:52:16', 'isDir': False, 'rel_path': '.abstract.md', 'uri': 'viking://resources...', 'abstract': "..."}]
+ """
+ if output == "original":
+ return await self._tree_original(uri, show_all_hidden)
+ elif output == "agent":
+ return await self._tree_agent(uri, abs_limit, show_all_hidden)
+ else:
+ raise ValueError(f"Invalid output format: {output}")
+
+ async def _tree_original(self, uri: str, show_all_hidden: bool = False) -> List[Dict[str, Any]]:
+ """Recursively list all contents (original format)."""
path = self._uri_to_path(uri)
all_entries = []
@@ -218,17 +276,56 @@ class VikingFS:
if name in [".", ".."]:
continue
rel_path = f"{current_rel}/{name}" if current_rel else name
- # Create new dict to add rel_path, avoid modifying original data
new_entry = dict(entry)
new_entry["rel_path"] = rel_path
new_entry["uri"] = self._path_to_uri(f"{current_path}/{name}")
- all_entries.append(new_entry)
if entry.get("isDir"):
+ all_entries.append(new_entry)
await _walk(f"{current_path}/{name}", rel_path)
+ elif not name.startswith("."):
+ all_entries.append(new_entry)
+ elif show_all_hidden:
+ all_entries.append(new_entry)
await _walk(path, "")
return all_entries
+ async def _tree_agent(
+ self, uri: str, abs_limit: int, show_all_hidden: bool = False
+ ) -> List[Dict[str, Any]]:
+ """Recursively list all contents (agent format with abstracts)."""
+ path = self._uri_to_path(uri)
+ all_entries = []
+ now = datetime.now()
+
+ async def _walk(current_path: str, current_rel: str):
+ for entry in self.agfs.ls(current_path):
+ name = entry.get("name", "")
+ if name in [".", ".."]:
+ continue
+ rel_path = f"{current_rel}/{name}" if current_rel else name
+ new_entry = {
+ "uri": str(VikingURI(uri).join(name)),
+ "size": entry.get("size", 0),
+ "isDir": entry.get("isDir", False),
+ "modTime": format_simplified(
+ datetime.fromisoformat(entry.get("modTime", "")), now
+ ),
+ }
+ if entry.get("isDir"):
+ all_entries.append(new_entry)
+ await _walk(f"{current_path}/{name}", rel_path)
+ elif not name.startswith("."):
+ all_entries.append(new_entry)
+ elif show_all_hidden:
+ all_entries.append(new_entry)
+
+ await _walk(path, "")
+
+ await self._batch_fetch_abstracts(all_entries, abs_limit)
+
+ return all_entries
+
# ========== VikingFS Specific Capabilities ==========
async def abstract(
@@ -830,19 +927,80 @@ class VikingFS:
async def ls(
self,
uri: str,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ ) -> List[Dict[str, Any]]:
+ """
+ List directory contents (URI version).
+
+ Args:
+ uri: Viking URI
+ output: str = "original"
+ abs_limit: int = 256
+ show_all_hidden: bool = False (list all hidden files, like -a)
+
+ output="original"
+ [{'name': '.abstract.md', 'size': 100, 'mode': 420, 'modTime': '2026-02-11T16:52:16.256334192+08:00', 'isDir': False, 'meta': {'Name': 'localfs', 'Type': 'local', 'Content': None}, 'uri': 'viking://resources/.abstract.md'}]
+
+ output="agent"
+ [{'name': '.abstract.md', 'size': 100, 'modTime': '2026-02-11(or 16:52:16 for today)', 'isDir': False, 'uri': 'viking://resources/.abstract.md', 'abstract': "..."}]
+ """
+ if output == "original":
+ return await self._ls_original(uri, show_all_hidden)
+ elif output == "agent":
+ return await self._ls_agent(uri, abs_limit, show_all_hidden)
+ else:
+ raise ValueError(f"Invalid output format: {output}")
+
+ async def _ls_agent(
+ self, uri: str, abs_limit: int, show_all_hidden: bool
) -> List[Dict[str, Any]]:
+ """List directory contents (URI version)."""
+ path = self._uri_to_path(uri)
+ try:
+ entries = self.agfs.ls(path)
+ except Exception as e:
+ raise FileNotFoundError(f"Failed to list {uri}: {e}")
+ # basic info
+ now = datetime.now()
+ all_entries = []
+ for entry in entries:
+ name = entry.get("name", "")
+ new_entry = {
+ "uri": str(VikingURI(uri).join(name)),
+ "size": entry.get("size", 0),
+ "isDir": entry.get("isDir", False),
+ "modTime": format_simplified(datetime.fromisoformat(entry.get("modTime", "")), now),
+ }
+ if entry.get("isDir"):
+ all_entries.append(new_entry)
+ elif not name.startswith("."):
+ all_entries.append(new_entry)
+ elif show_all_hidden:
+ all_entries.append(new_entry)
+ # call abstract in parallel 6 threads
+ await self._batch_fetch_abstracts(all_entries, abs_limit)
+ return all_entries
+
+ async def _ls_original(self, uri: str, show_all_hidden: bool = False) -> List[Dict[str, Any]]:
"""List directory contents (URI version)."""
path = self._uri_to_path(uri)
try:
entries = self.agfs.ls(path)
# AGFS returns read-only structure, need to create new dict
- result = []
+ all_entries = []
for entry in entries:
name = entry.get("name", "")
new_entry = dict(entry) # Copy original data
- new_entry["uri"] = f"{uri.rstrip('/')}/{name}"
- result.append(new_entry)
- return result
+ new_entry["uri"] = str(VikingURI(uri).join(name))
+ if entry.get("isDir"):
+ all_entries.append(new_entry)
+ elif not name.startswith("."):
+ all_entries.append(new_entry)
+ elif show_all_hidden:
+ all_entries.append(new_entry)
+ return all_entries
except Exception as e:
raise FileNotFoundError(f"Failed to list {uri}: {e}")
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index b8f0aa098..632c9d7a0 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -175,9 +175,9 @@ class SyncOpenViking:
"""Move resource"""
return run_async(self._async_client.mv(from_uri, to_uri))
- def tree(self, uri: str) -> Dict:
+ def tree(self, uri: str, **kwargs) -> Dict:
"""Get directory tree"""
- return run_async(self._async_client.tree(uri))
+ return run_async(self._async_client.tree(uri, **kwargs))
def stat(self, uri: str) -> Dict:
"""Get resource status"""
diff --git a/openviking/utils/time_utils.py b/openviking/utils/time_utils.py
index db6df6ecf..8861f17b1 100644
--- a/openviking/utils/time_utils.py
+++ b/openviking/utils/time_utils.py
@@ -16,6 +16,20 @@ def format_iso8601(dt: datetime) -> str:
return dt.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+def format_simplified(dt: datetime, now: datetime) -> str:
+ """
+ Format datetime object to simplified format: yyyy-MM-dd (if not in a day) or HH:mm:ss (if in a day).
+
+ This format is more readable for humans and is used in VikingDB.
+ """
+ dt = dt.replace(tzinfo=None)
+ # if in a day
+ if (now - dt).days < 1:
+ return dt.strftime("%H:%M:%S")
+ else:
+ return dt.strftime("%Y-%m-%d")
+
+
def get_current_timestamp() -> str:
"""
Get current timestamp in ISO 8601 format compatible with VikingDB.
diff --git a/openviking_cli/cli/commands/filesystem.py b/openviking_cli/cli/commands/filesystem.py
index 309deebf4..1aef4c820 100644
--- a/openviking_cli/cli/commands/filesystem.py
+++ b/openviking_cli/cli/commands/filesystem.py
@@ -21,17 +21,42 @@ def register(app: typer.Typer) -> None:
"-r",
help="List all subdirectories recursively",
),
+ output_format: str = typer.Option(
+ "agent", "--output-format", "-o", help="Output format: agent or original"
+ ),
+ abs_limit: int = typer.Option(256, "--abs-limit", "-l", help="Abstract content limit"),
+ show_all_hidden: bool = typer.Option(False, "--all", "-a", help="Show all hidden files"),
) -> None:
"""List directory contents."""
- run(ctx, lambda client: client.ls(uri, simple=simple, recursive=recursive))
+ run(
+ ctx,
+ lambda client: client.ls(
+ uri,
+ simple=simple,
+ recursive=recursive,
+ output=output_format,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ ),
+ )
@app.command("tree")
def tree_command(
ctx: typer.Context,
uri: str = typer.Argument(..., help="Viking URI"),
+ output_format: str = typer.Option(
+ "agent", "--output-format", "-o", help="Output format: agent or original"
+ ),
+ abs_limit: int = typer.Option(128, "--abs-limit", "-l", help="Abstract content limit"),
+ show_all_hidden: bool = typer.Option(False, "--all", "-a", help="Show all hidden files"),
) -> None:
"""Get directory tree."""
- run(ctx, lambda client: client.tree(uri))
+ run(
+ ctx,
+ lambda client: client.tree(
+ uri, output=output_format, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ ),
+ )
@app.command("mkdir")
def mkdir_command(
diff --git a/openviking_cli/cli/output.py b/openviking_cli/cli/output.py
index f48cd01c7..0c5e4ff26 100644
--- a/openviking_cli/cli/output.py
+++ b/openviking_cli/cli/output.py
@@ -11,7 +11,7 @@ from tabulate import tabulate
from openviking_cli.cli.context import CLIContext
-_MAX_COL_WIDTH = 80
+_MAX_COL_WIDTH = 256
def _to_serializable(value: Any) -> Any:
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index 131832243..b72d4f3a0 100644
--- a/openviking_cli/client/base.py
+++ b/openviking_cli/client/base.py
@@ -60,12 +60,26 @@ class BaseClient(ABC):
# ============= File System =============
@abstractmethod
- async def ls(self, uri: str, simple: bool = False, recursive: bool = False) -> List[Any]:
+ async def ls(
+ self,
+ uri: str,
+ simple: bool = False,
+ recursive: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ ) -> List[Any]:
"""List directory contents."""
...
@abstractmethod
- async def tree(self, uri: str) -> List[Dict[str, Any]]:
+ async def tree(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ ) -> List[Dict[str, Any]]:
"""Get directory tree."""
...
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index d1a33b94a..a8ae37266 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -270,19 +270,45 @@ class AsyncHTTPClient(BaseClient):
# ============= File System =============
- async def ls(self, uri: str, simple: bool = False, recursive: bool = False) -> List[Any]:
+ async def ls(
+ self,
+ uri: str,
+ simple: bool = False,
+ recursive: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ ) -> List[Any]:
"""List directory contents."""
response = await self._http.get(
"/api/v1/fs/ls",
- params={"uri": uri, "simple": simple, "recursive": recursive},
+ params={
+ "uri": uri,
+ "simple": simple,
+ "recursive": recursive,
+ "output": output,
+ "abs_limit": abs_limit,
+ "show_all_hidden": show_all_hidden,
+ },
)
return self._handle_response(response)
- async def tree(self, uri: str) -> List[Dict[str, Any]]:
+ async def tree(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ ) -> List[Dict[str, Any]]:
"""Get directory tree."""
response = await self._http.get(
"/api/v1/fs/tree",
- params={"uri": uri},
+ params={
+ "uri": uri,
+ "output": output,
+ "abs_limit": abs_limit,
+ "show_all_hidden": show_all_hidden,
+ },
)
return self._handle_response(response)
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
index 63617cbc7..fdfa450f5 100644
--- a/openviking_cli/client/sync_http.py
+++ b/openviking_cli/client/sync_http.py
@@ -152,13 +152,40 @@ class SyncHTTPClient:
# ============= File System =============
- def ls(self, uri: str, simple: bool = False, recursive: bool = False) -> List[Any]:
+ def ls(
+ self,
+ uri: str,
+ simple: bool = False,
+ recursive: bool = False,
+ output: str = "original",
+ abs_limit: int = 256,
+ show_all_hidden: bool = False,
+ ) -> List[Any]:
"""List directory contents."""
- return run_async(self._async_client.ls(uri, simple=simple, recursive=recursive))
+ return run_async(
+ self._async_client.ls(
+ uri,
+ simple=simple,
+ recursive=recursive,
+ output=output,
+ abs_limit=abs_limit,
+ show_all_hidden=show_all_hidden,
+ )
+ )
- def tree(self, uri: str) -> Dict:
+ def tree(
+ self,
+ uri: str,
+ output: str = "original",
+ abs_limit: int = 128,
+ show_all_hidden: bool = False,
+ ) -> Dict:
"""Get directory tree."""
- return run_async(self._async_client.tree(uri))
+ return run_async(
+ self._async_client.tree(
+ uri, output=output, abs_limit=abs_limit, show_all_hidden=show_all_hidden
+ )
+ )
def stat(self, uri: str) -> Dict:
"""Get resource status."""