Skip to content

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

fix(storage): 启动时初始化完整 agent 目录 (#4956)

bot-of-qin-ctxb54001e2e5c9
diff --git a/openviking/core/directories.py b/openviking/core/directories.py
index 53c20dceb..f887ffa75 100644
--- a/openviking/core/directories.py
+++ b/openviking/core/directories.py
@@ -19,7 +19,7 @@ from openviking.core.namespace import (
user_space_fragment,
)
from openviking.server.identity import RequestContext
-from openviking.storage.abstract_overview import AbstractOverviewFormatError
+from openviking.storage.abstract_overview import AbstractOverviewFormatError, body_for_preview
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
from openviking.storage.vector_ids import vector_record_id
@@ -49,7 +49,7 @@ class _DirectoryTarget:
ctx: RequestContext
-# Preset directory tree - each scope has a root DirectoryDefinition
+# Preset directory trees, keyed by their namespace path.
PRESET_DIRECTORIES: Dict[str, DirectoryDefinition] = {
"user": DirectoryDefinition(
path="",
@@ -152,6 +152,39 @@ PRESET_DIRECTORIES: Dict[str, DirectoryDefinition] = {
overview="Globally shared resource storage, organized by project/topic. "
"No preset subdirectory structure, users create project directories as needed.",
),
+ "agent": DirectoryDefinition(
+ path="",
+ abstract="Shared agent capabilities and configuration available across the account.",
+ overview="Account-wide capability definitions, organized into skills, communication "
+ "endpoints, tools, and payments. Each category has its own directory.",
+ children=[
+ DirectoryDefinition(
+ path="skills",
+ abstract="Shared skill registry. Stores callable skill definitions available across the account.",
+ overview="Use this directory for skills shared by users in the same account. "
+ "Each skill is stored in its own directory using the SKILL.md format. "
+ "User-private skills remain under viking://user/{user_id}/skills.",
+ ),
+ DirectoryDefinition(
+ path="endpoints",
+ abstract="Shared communication endpoint configuration for agent capabilities.",
+ overview="Stores definitions of external communication endpoints, organized "
+ "by protocol or service, such as A2A and ANP.",
+ ),
+ DirectoryDefinition(
+ path="tools",
+ abstract="Shared tool configuration for agent capabilities.",
+ overview="Stores tool integration definitions, organized by protocol or "
+ "provider, such as MCP server configurations.",
+ ),
+ DirectoryDefinition(
+ path="payments",
+ abstract="Shared payment capability configuration for agents.",
+ overview="Stores payment capability definitions, organized by protocol "
+ "or provider, such as AP2 configurations.",
+ ),
+ ],
+ ),
}
@@ -175,46 +208,23 @@ class DirectoryInitializer:
async def initialize_account_workspace(self, ctx: RequestContext) -> tuple[int, int]:
"""Initialize account and first-user preset directories as one batch."""
- account_target = self._account_directory_target(ctx)
+ account_roots, account_children = self._account_directory_targets(ctx)
user_root, user_children = self._user_directory_targets(ctx)
-
- root_targets = (account_target, user_root)
- root_results = await asyncio.gather(
- self._ensure_agfs_directory(account_target),
- self._ensure_agfs_directory(user_root),
- return_exceptions=True,
- )
- created_targets, root_error = self._partition_directory_results(root_targets, root_results)
- if root_error is not None:
- await self._ensure_directory_l0_l1_vectors(created_targets)
- raise root_error
-
- child_results = await asyncio.gather(
- *(self._ensure_agfs_directory(target) for target in user_children),
- return_exceptions=True,
- )
- created_children, child_error = self._partition_directory_results(
- user_children, child_results
- )
- created_targets.extend(created_children)
- await self._ensure_directory_l0_l1_vectors(created_targets)
- if child_error is not None:
- raise child_error
- return int(root_results[0] is True), int(root_results[1] is True) + sum(
- result is True for result in child_results
+ created = await self._initialize_directory_trees(
+ (*account_roots, user_root), (*account_children, *user_children)
)
+ user_count = sum(target.scope == "user" for target in created)
+ return len(created) - user_count, user_count
async def initialize_account_directories(self, ctx: RequestContext) -> int:
- """Initialize account-shared scope roots.
+ """Initialize account-shared roots and their preset first-level directories.
``viking://user`` is the container of user spaces, not a space itself.
Its concrete metadata belongs to ``viking://user/{user_id}`` and is
created by ``initialize_user_directories``.
"""
- target = self._account_directory_target(ctx)
- created = await self._ensure_agfs_directory(target)
- await self._ensure_directory_l0_l1_vectors([target] if created else [])
- return int(created)
+ roots, children = self._account_directory_targets(ctx)
+ return len(await self._initialize_directory_trees(roots, children))
async def initialize_user_directories(self, ctx: RequestContext) -> int:
"""Initialize the current user's root and first-level entry directories.
@@ -226,30 +236,58 @@ class DirectoryInitializer:
if "user" not in PRESET_DIRECTORIES:
return 0
user_root, user_children = self._user_directory_targets(ctx)
- root_created = await self._ensure_agfs_directory(user_root)
- child_results = await asyncio.gather(
- *(self._ensure_agfs_directory(target) for target in user_children),
+ return len(await self._initialize_directory_trees((user_root,), user_children))
+
+ async def _initialize_directory_trees(
+ self, roots: Sequence[_DirectoryTarget], children: Sequence[_DirectoryTarget]
+ ) -> list[_DirectoryTarget]:
+ """Initialize roots before children and index successful writes as one batch."""
+ results = await asyncio.gather(
+ *(self._ensure_agfs_directory(target) for target in roots),
return_exceptions=True,
)
- created_targets = [user_root] if root_created else []
- created_children, child_error = self._partition_directory_results(
- user_children, child_results
- )
- created_targets.extend(created_children)
- await self._ensure_directory_l0_l1_vectors(created_targets)
- if child_error is not None:
- raise child_error
- return int(root_created) + sum(result is True for result in child_results)
+ created, error = self._partition_directory_results(results)
+ if error is None:
+ results = await asyncio.gather(
+ *(self._ensure_agfs_directory(target) for target in children),
+ return_exceptions=True,
+ )
+ created_children, error = self._partition_directory_results(results)
+ created.extend(created_children)
+ await self._ensure_directory_l0_l1_vectors(created)
+ if error is not None:
+ raise error
+ return created
@staticmethod
- def _account_directory_target(ctx: RequestContext) -> _DirectoryTarget:
- return _DirectoryTarget(
- uri="viking://resources",
- parent_uri=None,
- definition=PRESET_DIRECTORIES["resources"],
- scope="resources",
- ctx=ctx,
- )
+ def _account_directory_targets(
+ ctx: RequestContext,
+ ) -> tuple[list[_DirectoryTarget], list[_DirectoryTarget]]:
+ roots = []
+ children = []
+ for scope in ("resources", "agent"):
+ uri = f"viking://{scope}"
+ tree = PRESET_DIRECTORIES[scope]
+ roots.append(
+ _DirectoryTarget(
+ uri=uri,
+ parent_uri=None,
+ definition=tree,
+ scope=scope,
+ ctx=ctx,
+ )
+ )
+ children.extend(
+ _DirectoryTarget(
+ uri=f"{uri}/{child.path}",
+ parent_uri=uri,
+ definition=child,
+ scope=scope,
+ ctx=ctx,
+ )
+ for child in tree.children
+ )
+ return roots, children
@staticmethod
def _user_directory_targets(
@@ -284,49 +322,61 @@ class DirectoryInitializer:
@staticmethod
def _partition_directory_results(
- targets: Sequence[_DirectoryTarget],
- results: Sequence[bool | BaseException],
+ results: Sequence[_DirectoryTarget | None | BaseException],
) -> tuple[list[_DirectoryTarget], Optional[BaseException]]:
"""Keep successful concurrent writes while preserving the first failure."""
created_targets = []
first_error = None
- for target, result in zip(targets, results, strict=True):
+ for result in results:
if isinstance(result, asyncio.CancelledError):
raise result
if isinstance(result, BaseException):
if first_error is None:
first_error = result
- elif result:
- created_targets.append(target)
+ elif result is not None:
+ created_targets.append(result)
return created_targets, first_error
- async def _ensure_agfs_directory(self, target: _DirectoryTarget) -> bool:
- """Ensure one directory exists in AGFS and report whether it was created."""
+ async def _ensure_agfs_directory(self, target: _DirectoryTarget) -> _DirectoryTarget | None:
+ """Fill missing L0/L1 files, preserving stored text for vector initialization."""
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
+ viking_fs = self._get_viking_fs()
+ contents = {}
+ missing = {}
try:
- directory_exists = await self._check_agfs_files_exist(target.uri, ctx=target.ctx)
+ for name, default in (
+ ("abstract", target.definition.abstract),
+ ("overview", target.definition.overview),
+ ):
+ try:
+ raw = await viking_fs.read_file(f"{target.uri}/.{name}.md", ctx=target.ctx)
+ except (FileNotFoundError, NotFoundError):
+ contents[name] = default
+ missing[name] = contents[name]
+ else:
+ contents[name] = body_for_preview(raw)
except AbstractOverviewFormatError as exc:
logger.warning(
- "[VikingFS] Directory %s (account=%s) has an invalid abstract; "
+ "[VikingFS] Directory %s (account=%s) has invalid L0/L1 metadata; "
"preserving existing contents: %s",
target.uri,
target.ctx.account_id,
exc,
)
- return False
- if directory_exists:
+ return None
+ if not missing:
logger.debug(f"[VikingFS] Directory {target.uri} already exists")
- return False
+ return None
logger.debug(f"[VikingFS] Creating directory: {target.uri} for scope {target.scope}")
- await self._create_agfs_structure(
- target.uri,
- target.definition.abstract,
- target.definition.overview,
+ await viking_fs.write_context(
+ uri=target.uri,
+ **missing,
+ is_leaf=False,
ctx=target.ctx,
)
- return True
+ return replace(target, definition=replace(target.definition, **contents))
async def _ensure_directory_l0_l1_vectors(self, targets: list[_DirectoryTarget]) -> None:
"""Seed missing L0/L1 records after one batch existence read."""
@@ -377,24 +427,3 @@ class DirectoryInitializer:
if scope in {"user", "session"}:
return user_space_fragment(ctx)
return ""
-
- async def _check_agfs_files_exist(self, uri: str, ctx: RequestContext) -> bool:
- """Check if L0/L1 files exist in AGFS."""
- try:
- viking_fs = self._get_viking_fs()
- await viking_fs.abstract(uri, ctx=ctx)
- return True
- except (FileNotFoundError, NotFoundError):
- return False
-
- async def _create_agfs_structure(
- self, uri: str, abstract: str, overview: str, ctx: RequestContext
- ) -> None:
- """Create L0/L1 file structure for directory in AGFS."""
- await self._get_viking_fs().write_context(
- uri=uri,
- abstract=abstract,
- overview=overview,
- is_leaf=False, # Preset directories can continue traversing downward
- ctx=ctx,
- )
diff --git a/openviking/storage/viking_fs/_access.py b/openviking/storage/viking_fs/_access.py
index 0a335889d..1d5f91b4a 100644
--- a/openviking/storage/viking_fs/_access.py
+++ b/openviking/storage/viking_fs/_access.py
@@ -379,10 +379,6 @@ class _AccessMixin:
resource=normalized_uri,
)
if parts == ["agent"]:
- # Parity with _ensure_supported_write_namespace, which forbids the
- # account-shared viking://agent root: deleting it would recursively
- # wipe every account's agent skills/endpoints/tools/payments. Concrete
- # sub-paths (viking://agent/skills/...) remain deletable.
raise PermissionDeniedError(
"Deleting viking://agent root is not supported; use a concrete "
"agent sub-path (e.g. viking://agent/skills/...) instead.",
@@ -402,17 +398,11 @@ class _AccessMixin:
f"Writing {normalized_uri} is not supported; use user-owned namespaces instead.",
resource=normalized_uri,
)
- if parts and parts[0] == "agent":
- if len(parts) >= 2 and parts[1] not in {"skills", "endpoints", "tools", "payments"}:
- raise PermissionDeniedError(
- "viking://agent/{agent_id} is deprecated. Use viking://user/.../peers/{agent_id} instead.",
- resource=normalized_uri,
- )
- if len(parts) < 2:
- raise PermissionDeniedError(
- "Writing to viking://agent root is not supported.",
- resource=normalized_uri,
- )
+ if self._is_legacy_agent_id_uri(normalized_uri):
+ raise PermissionDeniedError(
+ "viking://agent/{agent_id} is deprecated. Use viking://user/.../peers/{agent_id} instead.",
+ resource=normalized_uri,
+ )
def _pathlock_fs_ctx(
self,
@@ -690,6 +680,7 @@ class _AccessMixin:
and parts[0] == "agent"
and len(parts) >= 2
and parts[1] not in {"skills", "endpoints", "tools", "payments"}
+ and not (len(parts) == 2 and parts[1] in self._DIR_MARKER_LEVELS)
)
def _read_paths(self, uri: str, ctx: Optional[RequestContext] = None) -> List[str]:
diff --git a/tests/unit/test_directory_initializer.py b/tests/unit/test_directory_initializer.py
index b1a363277..9c2a5fcd6 100644
--- a/tests/unit/test_directory_initializer.py
+++ b/tests/unit/test_directory_initializer.py
@@ -9,7 +9,6 @@ from openviking.core.namespace import (
may_include_hidden_actor_peers,
)
from openviking.server.identity import RequestContext, Role
-from openviking.storage.abstract_overview import body_for_preview
from openviking_cli.session.user_id import UserIdentifier
@@ -30,25 +29,30 @@ class _FakeVikingFS:
def __init__(self):
self.contexts = {}
- async def abstract(self, uri, ctx):
- if uri not in self.contexts:
+ async def read_file(self, uri, ctx):
+ directory, filename = uri.rsplit("/", 1)
+ name = filename.removeprefix(".").removesuffix(".md")
+ if directory not in self.contexts or name not in self.contexts[directory]:
raise FileNotFoundError(uri)
- return body_for_preview(self.contexts[uri]["abstract"])
+ return self.contexts[directory][name]
- async def write_context(self, uri, abstract, overview, is_leaf, ctx):
+ async def write_context(self, uri, abstract="", overview="", is_leaf=False, ctx=None):
if ctx.actor_peer_id and may_include_hidden_actor_peers(uri, ctx):
raise PermissionError(f"actor peer cannot mutate {uri}")
- self.contexts[uri] = {
- "abstract": abstract,
- "overview": overview,
- "is_leaf": is_leaf,
- }
+ context = self.contexts.setdefault(uri, {})
+ if abstract:
+ context["abstract"] = abstract
+ if overview:
+ context["overview"] = overview
+ context["is_leaf"] = is_leaf
@pytest.mark.asyncio
async def test_initialize_account_workspace_batches_preset_directories(monkeypatch):
vikingdb = _FakeVikingDB()
viking_fs = _FakeVikingFS()
+ viking_fs.contexts["viking://agent"] = {}
+ viking_fs.contexts["viking://agent/tools"] = {"abstract": "Existing tool configuration"}
initializer = DirectoryInitializer(vikingdb, viking_fs=viking_fs)
ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.ADMIN)
@@ -59,15 +63,37 @@ async def test_initialize_account_workspace_batches_preset_directories(monkeypat
user_root,
*(f"{user_root}/{child.path}" for child in PRESET_DIRECTORIES["user"].children),
}
- expected_uris = {"viking://resources", *expected_user_uris}
- assert account_count == 1
+ expected_agent_uris = {
+ "viking://agent",
+ "viking://agent/skills",
+ "viking://agent/endpoints",
+ "viking://agent/tools",
+ "viking://agent/payments",
+ }
+ expected_uris = {"viking://resources", *expected_agent_uris, *expected_user_uris}
+ assert account_count == 6
assert user_count == len(expected_user_uris)
assert set(viking_fs.contexts) == expected_uris
assert f"{user_root}/memories/preferences" not in viking_fs.contexts
+ for uri in expected_agent_uris:
+ assert viking_fs.contexts[uri]["abstract"]
+ assert viking_fs.contexts[uri]["overview"]
+ assert viking_fs.contexts["viking://agent/tools"]["abstract"] == "Existing tool configuration"
assert len(vikingdb.get_calls) == 1
+
+ assert await initializer.initialize_account_directories(ctx) == 0
+ assert set(viking_fs.contexts) == expected_uris
vectorized_uris = {uri for uri in expected_uris if not is_session_uri(uri)}
assert len(vikingdb.get_calls[0][0]) == 2 * len(vectorized_uris)
assert len(vikingdb.embedding_messages) == 2 * len(vectorized_uris)
+ for message in vikingdb.embedding_messages:
+ uri = message.context_data["uri"]
+ if uri in expected_agent_uris:
+ name = "abstract" if message.context_data["level"] == 0 else "overview"
+ assert message.message == viking_fs.contexts[uri][name]
+ assert message.context_data["parent_uri"] == (
+ None if uri == "viking://agent" else "viking://agent"
+ )
malformed_abstract = "---\ndirectory: viking://resources/\n"
viking_fs.contexts["viking://resources"]["abstract"] = malformed_abstract
@@ -80,7 +106,7 @@ async def test_initialize_account_workspace_batches_preset_directories(monkeypat
assert len(vikingdb.get_calls) == 1
storage_error = PermissionError("storage access denied")
- monkeypatch.setattr(viking_fs, "abstract", AsyncMock(side_effect=storage_error))
+ monkeypatch.setattr(viking_fs, "read_file", AsyncMock(side_effect=storage_error))
with pytest.raises(PermissionError) as exc_info:
await initializer.initialize_account_workspace(ctx)
assert exc_info.value is storage_error