reactor(ragfs): prevent recursive backup sync loop by moving default backup workspace and renaming config key

docs/en/guides/13-multi-write-storage.md

@@ -28,7 +28,7 @@ The following example uses a local directory as the primary backend and replicat
             "name": "local-backup",
             "backend": "local",
             "local": {
-              "local_dir": "./data/backup"
+                "workspace": "./data/backup"
             }
           }
         ]
@@ -43,6 +43,7 @@ Notes:
 - The top-level `backend` is the primary backend.
 - `backups.items[]` is the backup backend list.
 - `name` is the stable identity of a backup; later sync metadata refers to it.
+- A backup with `backend = "local"` uses `local.workspace` to point to its local directory.
 - If `sync_type` is omitted, treat it as async by default.
 
 ## Configuring Multiple Backups
@@ -62,7 +63,7 @@ You can configure more than one backup. The following example writes to both a l
             "name": "local-az2",
             "backend": "local",
             "local": {
-              "local_dir": "./data/local-az2"
+                "workspace": "./data/local-az2"
             }
           },
           {
@@ -291,7 +292,7 @@ Example with global encryption enabled:
             "name": "encrypted-backup",
             "backend": "local",
             "local": {
-              "local_dir": "./data/encrypted-backup"
+                "workspace": "./data/encrypted-backup"
             },
             "encryption": {
               "enabled": true

docs/zh/guides/13-multi-write-storage.md

@@ -28,7 +28,7 @@
             "name": "local-backup",
             "backend": "local",
             "local": {
-              "local_dir": "./data/backup"
+                "workspace": "./data/backup"
             }
           }
         ]
@@ -43,6 +43,7 @@
 - 顶层 `backend` 是 primary。
 - `backups.items[]` 是 backup 列表。
 - `name` 是 backup 的稳定身份，后续同步元数据会引用它。
+- `backend = "local"` 的 backup 使用 `local.workspace` 指定本地目录。
 - `sync_type` 不配置时默认按异步模式理解。
 
 ## 多 Backup 配置
@@ -62,7 +63,7 @@
             "name": "local-az2",
             "backend": "local",
             "local": {
-              "local_dir": "./data/local-az2"
+                "workspace": "./data/local-az2"
             }
           },
           {
@@ -291,7 +292,7 @@ Exclude 用于让某个 backup 跳过匹配文件。
             "name": "encrypted-backup",
             "backend": "local",
             "local": {
-              "local_dir": "./data/encrypted-backup"
+                "workspace": "./data/encrypted-backup"
             },
             "encryption": {
               "enabled": true

openviking/utils/agfs_utils.py

@@ -331,12 +331,12 @@ def _serialize_s3_backup_params(
 def _serialize_local_backup_params(
     item: Any, backend_config: Any, data_path: Path
 ) -> Dict[str, Any]:
-    """Serialize one local backup item and fill the default workspace local_dir."""
+    """Serialize one local backup item and map workspace to the localfs local_dir param."""
     local_dir = (
-        _get_config_value(backend_config, "local_dir") if backend_config is not None else None
+        _get_config_value(backend_config, "workspace") if backend_config is not None else None
     )
     if local_dir is None:
-        local_dir = data_path / "viking" / "_backups" / _get_config_value(item, "name")
+        local_dir = data_path / "_backups" / _get_config_value(item, "name")
     local_dir_path = Path(local_dir).expanduser()
     return {"local_dir": str(local_dir_path)}
 

tests/misc/test_config_validation.py

@@ -14,8 +14,8 @@
     create_agfs_client,
     mount_agfs_backend,
 )
-from openviking_cli.utils.config.consts import OPENVIKING_CONFIG_ENV
 from openviking_cli.utils.config.agfs_config import AGFSConfig, S3Config
+from openviking_cli.utils.config.consts import OPENVIKING_CONFIG_ENV
 from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig
 from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig, VolcengineConfig
 from openviking_cli.utils.config.vlm_config import VLMConfig
@@ -432,7 +432,7 @@ def test_generate_plugin_config_materializes_multiwrite_backups(tmp_path):
                 {
                     "name": "local-explicit",
                     "backend": "local",
-                    "local": {"local_dir": str(explicit_backup_dir)},
+                    "local": {"workspace": str(explicit_backup_dir)},
                 },
                 {
                     "name": "local-default",
@@ -469,9 +469,7 @@ def test_generate_plugin_config_materializes_multiwrite_backups(tmp_path):
     assert not explicit_backup_dir.exists()
 
     assert default_local["backend"] == "localfs"
-    assert default_local["params"]["local_dir"] == str(
-        tmp_path / "viking" / "_backups" / "local-default"
-    )
+    assert default_local["params"]["local_dir"] == str(tmp_path / "_backups" / "local-default")
 
     assert s3_backup["backend"] == "s3fs"
     assert s3_backup["params"] == {