Skip to content

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

feat(fs): create default L0 on mkdir (#4277)

Qin Haojie234a2d9fe778
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index 0a68f2014..b3702fb23 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -429,7 +429,7 @@ Create a directory.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| uri | str | Yes | - | Viking URI for the new directory |
-| description | str | No | `null` | Initial directory description. When provided, it is written to `.abstract.md` and queued for L0 vectorization. |
+| description | str | No | `null` | Initial directory description. When omitted, the directory name is used as the default L0; when provided, this description is used. Both forms write `.abstract.md` and queue L0 vectorization. |
**Python HTTP SDK**
diff --git a/docs/en/concepts/03-context-layers.md b/docs/en/concepts/03-context-layers.md
index da4a9d23c..50c1f280b 100644
--- a/docs/en/concepts/03-context-layers.md
+++ b/docs/en/concepts/03-context-layers.md
@@ -12,7 +12,7 @@ OpenViking uses a three-layer information model to balance retrieval efficiency,
L0 and L1 are **directory-level semantic sidecars**. They describe a directory; OpenViking does not create a matching L0/L1 sidecar for every ordinary file. File summaries are inputs aggregated into the containing directory's L1.
-L0 and L1 are normally generated together, but either one may exist independently. For example, `mkdir(description=...)` initially creates only L0, so a directory with `.abstract.md` but no `.overview.md` is valid. Reads and vector rebuilds process only the levels that actually exist.
+L0 and L1 are normally generated together, but either one may exist independently. For example, `mkdir()` initially creates only L0: it uses the directory name as the default body when `description` is omitted, or the provided description otherwise. A directory with `.abstract.md` but no `.overview.md` is therefore valid. Reads and vector rebuilds process only the levels that actually exist.
The body limits are configured by `semantic.abstract_max_chars` and `semantic.overview_max_chars`; the table shows their defaults. These limits apply to the Markdown body only and do not truncate sidecar metadata.
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index e1804e424..653c17ded 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -430,7 +430,7 @@ openviking attrs set-tags viking://resources/docs --tags team=search --mode appe
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| uri | str | 是 | - | 新目录的 Viking URI |
-| description | str | 否 | `null` | 目录初始说明。传入后会写入 `.abstract.md`,并进入目录 L0 向量化队列。 |
+| description | str | 否 | `null` | 目录初始说明。未传入时使用目录名作为默认 L0;传入后使用该说明。两种情况都会写入 `.abstract.md` 并进入 L0 向量化队列。 |
**Python HTTP SDK**
diff --git a/docs/zh/concepts/03-context-layers.md b/docs/zh/concepts/03-context-layers.md
index 737a88775..a38083c14 100644
--- a/docs/zh/concepts/03-context-layers.md
+++ b/docs/zh/concepts/03-context-layers.md
@@ -12,7 +12,7 @@ OpenViking 使用三层信息模型,在检索效率、导航能力和原始内
L0/L1 是**目录级语义 sidecar**。它们描述一个目录,不是为每个普通文件创建的同名伴生文件。文件摘要会作为输入,聚合到所在目录的 L1 中。
-L0 和 L1 通常成对生成,但系统允许只存在其中一个。例如,`mkdir(description=...)` 会先创建 L0,因此只有 `.abstract.md` 的目录也是合法状态。读取和向量重建只处理实际存在的层级。
+L0 和 L1 通常成对生成,但系统允许只存在其中一个。例如,`mkdir()` 会先创建 L0:未传入 `description` 时使用目录名作为默认正文,传入后使用该说明。因此只有 `.abstract.md` 的目录也是合法状态。读取和向量重建只处理实际存在的层级。
正文上限由 `semantic.abstract_max_chars` 和 `semantic.overview_max_chars` 配置;上表是默认值。限制只作用于 Markdown 正文,不会截断 sidecar 元数据。
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index fa683b1c3..444d22cce 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -10,7 +10,7 @@ import asyncio
from typing import TYPE_CHECKING, Any, Dict, List, Optional
from openviking.core.context import ContextLevel
-from openviking.core.namespace import classify_uri, context_type_for_uri
+from openviking.core.namespace import classify_uri, context_type_for_uri, uri_leaf_name
from openviking.privacy import (
UserPrivacyConfigService,
get_skill_name_from_uri,
@@ -194,11 +194,14 @@ class FSService:
"""Create directory."""
viking_fs = self._ensure_initialized()
await viking_fs.mkdir(uri, ctx=ctx)
+
+ directory_uri, abstract_uri = self._resolve_directory_uris(uri)
abstract = self._normalize_directory_description(description)
if not abstract:
- return
+ if await viking_fs.exists(abstract_uri, ctx=ctx):
+ return
+ abstract = f"# {uri_leaf_name(directory_uri)}"
- directory_uri, abstract_uri = self._resolve_directory_uris(uri)
await viking_fs.write_file(
abstract_uri,
render_abstract_overview(
diff --git a/tests/server/test_http_client_sdk.py b/tests/server/test_http_client_sdk.py
index 14def6640..5a6324ee6 100644
--- a/tests/server/test_http_client_sdk.py
+++ b/tests/server/test_http_client_sdk.py
@@ -152,7 +152,11 @@ async def test_sdk_ls(http_client):
async def test_sdk_mkdir_and_ls(http_client):
client, _ = http_client
- await client.mkdir("viking://resources/sdk_dir/")
+ uri = "viking://resources/sdk_dir/"
+
+ await client.mkdir(uri)
+
+ assert await client.abstract(uri) == "# sdk_dir"
result = await client.ls("viking://resources/")
assert isinstance(result, list)
@@ -164,8 +168,11 @@ async def test_sdk_mkdir_with_description_sets_abstract(http_client):
await client.mkdir(uri, description=description)
- abstract = await client.abstract(uri)
- assert abstract == description
+ assert await client.abstract(uri) == description
+
+ await client.mkdir(uri)
+
+ assert await client.abstract(uri) == description
async def test_sdk_tree(http_client):