Skip to content

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

feat(agfs): make binding client optional, add server bootstrap, tune logging and CI (#451)

Qin Haojieee2786cd986b
diff --git a/.github/workflows/build-docker-image.yml b/.github/workflows/build-docker-image.yml
index 6ed2dba72..95f5a4582 100644
--- a/.github/workflows/build-docker-image.yml
+++ b/.github/workflows/build-docker-image.yml
@@ -8,10 +8,7 @@ on:
required: true
type: string
push:
- branches: [ "main" ]
tags: [ "v*.*.*" ]
- pull_request:
- branches: [ "main" ]
env:
REGISTRY: ghcr.io
diff --git a/openviking/server/app.py b/openviking/server/app.py
index d8583b119..0867d1751 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -136,7 +136,7 @@ def create_app(
# Catch-all for unhandled exceptions so clients always get JSON
@app.exception_handler(Exception)
async def general_error_handler(request: Request, exc: Exception):
- logger.exception("Unhandled exception in request handler")
+ logger.warning("Unhandled exception: %s", exc)
return JSONResponse(
status_code=500,
content=Response(
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 24e8da5fb..554d81804 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -26,6 +26,7 @@ from pyagfs.exceptions import AGFSHTTPError
from openviking.server.identity import RequestContext, Role
from openviking.utils.time_utils import format_simplified, get_current_timestamp, parse_iso_datetime
+from openviking_cli.exceptions import NotFoundError
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.logger import get_logger
from openviking_cli.utils.uri import VikingURI
@@ -793,7 +794,7 @@ class VikingFS:
entries.append(RelationEntry(id=link_id, uris=uris, reason=reason))
await self._write_relation_table(from_path, entries)
- logger.info(f"[VikingFS] Created link: {from_uri} -> {uris}")
+ logger.debug(f"[VikingFS] Created link: {from_uri} -> {uris}")
async def unlink(
self,
@@ -816,17 +817,17 @@ class VikingFS:
break
if not entry_to_modify:
- logger.warning(f"[VikingFS] URI not found in relations: {uri}")
+ logger.debug(f"[VikingFS] URI not found in relations: {uri}")
return
entry_to_modify.uris.remove(uri)
if not entry_to_modify.uris:
entries.remove(entry_to_modify)
- logger.info(f"[VikingFS] Removed empty entry: {entry_to_modify.id}")
+ logger.debug(f"[VikingFS] Removed empty entry: {entry_to_modify.id}")
await self._write_relation_table(from_path, entries)
- logger.info(f"[VikingFS] Removed link: {from_uri} -> {uri}")
+ logger.debug(f"[VikingFS] Removed link: {from_uri} -> {uri}")
except Exception as e:
logger.error(f"[VikingFS] Failed to unlink {from_uri} -> {uri}: {e}")
@@ -1080,7 +1081,7 @@ class VikingFS:
try:
await vector_store.delete_uris(real_ctx, uris)
for uri in uris:
- logger.info(f"[VikingFS] Deleted from vector store: {uri}")
+ logger.debug(f"[VikingFS] Deleted from vector store: {uri}")
except Exception as e:
logger.warning(f"[VikingFS] Failed to delete from vector store: {e}")
@@ -1128,7 +1129,7 @@ class VikingFS:
new_uri=new_uri,
new_parent_uri=new_parent_uri,
)
- logger.info(f"[VikingFS] Updated URI: {uri} -> {new_uri}")
+ logger.debug(f"[VikingFS] Updated URI: {uri} -> {new_uri}")
except Exception as e:
logger.warning(f"[VikingFS] Failed to update {uri} in vector store: {e}")
@@ -1254,8 +1255,8 @@ class VikingFS:
path = self._uri_to_path(uri, ctx=ctx)
try:
content = self.agfs.read(path)
- except Exception as e:
- raise FileNotFoundError(f"Failed to read {uri}: {e}")
+ except Exception:
+ raise NotFoundError(uri, "file")
text = self._handle_agfs_content(content)
if offset == 0 and limit == -1:
return text
@@ -1273,8 +1274,8 @@ class VikingFS:
path = self._uri_to_path(uri, ctx=ctx)
try:
return self._handle_agfs_read(self.agfs.read(path))
- except Exception as e:
- raise FileNotFoundError(f"Failed to read {uri}: {e}")
+ except Exception:
+ raise NotFoundError(uri, "file")
async def write_file_bytes(
self,
@@ -1359,8 +1360,8 @@ class VikingFS:
real_ctx = self._ctx_or_default(ctx)
try:
entries = self._ls_entries(path)
- except Exception as e:
- raise FileNotFoundError(f"Failed to list {uri}: {e}")
+ except Exception:
+ raise NotFoundError(uri, "directory")
# basic info
now = datetime.now()
all_entries = []
@@ -1423,8 +1424,8 @@ class VikingFS:
elif show_all_hidden:
all_entries.append(new_entry)
return all_entries
- except Exception as e:
- raise FileNotFoundError(f"Failed to list {uri}: {e}")
+ except Exception:
+ raise NotFoundError(uri, "directory")
async def move_file(
self,
diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.py
index 9b3d2d572..535f86d54 100644
--- a/openviking/utils/agfs_utils.py
+++ b/openviking/utils/agfs_utils.py
@@ -30,11 +30,13 @@ def create_agfs_client(agfs_config: Any) -> Any:
if mode == "binding-client":
# Import binding client if mode is binding-client
- try:
- from pyagfs import AGFSBindingClient
- except ImportError:
+ from pyagfs import AGFSBindingClient
+
+ if AGFSBindingClient is None:
raise ImportError(
- "AGFS binding client not found. Please run 'pip install -e .' in the project root to install the AGFS SDK."
+ "AGFS binding client is not available. The native library (libagfsbinding) "
+ "could not be loaded. Please run 'pip install -e .' in the project root "
+ "to build and install the AGFS SDK with native bindings."
)
lib_path = getattr(agfs_config, "lib_path", None)
@@ -83,9 +85,8 @@ def mount_agfs_backend(agfs: Any, agfs_config: Any) -> None:
from openviking.agfs_manager import AGFSManager
- # Only binding-client needs manual mounting, but we can also do it for HTTP client
- # if it supports it. Usually, HTTP server handles its own mounting.
- if not isinstance(agfs, AGFSBindingClient):
+ # Only binding-client needs manual mounting. HTTP server handles its own mounting.
+ if AGFSBindingClient is None or not isinstance(agfs, AGFSBindingClient):
return
# 1. Mount standard plugins to align with HTTP server behavior
diff --git a/openviking_cli/server_bootstrap.py b/openviking_cli/server_bootstrap.py
new file mode 100644
index 000000000..d086082f9
--- /dev/null
+++ b/openviking_cli/server_bootstrap.py
@@ -0,0 +1,35 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Lightweight entry point for openviking-server.
+
+This module lives outside the ``openviking`` package so that importing it
+does NOT trigger ``openviking/__init__.py`` (which eagerly imports clients
+and initialises the config singleton via module-level loggers).
+
+The real bootstrap logic stays in ``openviking.server.bootstrap``; we just
+pre-parse ``--config`` and set the environment variable before that module
+is ever imported.
+"""
+
+import os
+import sys
+
+
+def main():
+ # Pre-parse --config from sys.argv before any openviking imports,
+ # so the env var is visible when the config singleton first initialises.
+ for i, arg in enumerate(sys.argv):
+ if arg == "--config" and i + 1 < len(sys.argv):
+ os.environ["OPENVIKING_CONFIG_FILE"] = sys.argv[i + 1]
+ break
+ if arg.startswith("--config="):
+ os.environ["OPENVIKING_CONFIG_FILE"] = arg.split("=", 1)[1]
+ break
+
+ from openviking.server.bootstrap import main as _real_main
+
+ _real_main()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/pyproject.toml b/pyproject.toml
index c25ca5db1..e45918e7e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -107,7 +107,7 @@ Issues = "https://github.com/volcengine/openviking/issues"
[project.scripts]
ov = "openviking_cli.rust_cli:main" # Rust CLI 入口(极简包装器)
openviking = "openviking_cli.rust_cli:main" # Rust CLI 入口(放弃 python CLI)
-openviking-server = "openviking.server.bootstrap:main"
+openviking-server = "openviking_cli.server_bootstrap:main"
[tool.setuptools_scm]
write_to = "openviking/_version.py"
diff --git a/third_party/agfs/agfs-sdk/python/pyagfs/__init__.py b/third_party/agfs/agfs-sdk/python/pyagfs/__init__.py
index ac0c665d6..848a40521 100644
--- a/third_party/agfs/agfs-sdk/python/pyagfs/__init__.py
+++ b/third_party/agfs/agfs-sdk/python/pyagfs/__init__.py
@@ -3,7 +3,6 @@
__version__ = "0.1.7"
from .client import AGFSClient, FileHandle
-from .binding_client import AGFSBindingClient, FileHandle as BindingFileHandle
from .exceptions import (
AGFSClientError,
AGFSConnectionError,
@@ -13,6 +12,15 @@ from .exceptions import (
)
from .helpers import cp, upload, download
+# Binding client depends on a native shared library (libagfsbinding.so/dylib/dll).
+# Make it optional so the pure-HTTP AGFSClient remains usable when the native
+# library is not installed (e.g. Docker images without CGO build).
+try:
+ from .binding_client import AGFSBindingClient, FileHandle as BindingFileHandle
+except (ImportError, OSError):
+ AGFSBindingClient = None
+ BindingFileHandle = None
+
__all__ = [
"AGFSClient",
"AGFSBindingClient",