Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(pathlock): adjust pathlock config (#3854)
baojun-zhangbd5cce09c7d7
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex 2e44b318e..1a663291a 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -1327,7 +1327,7 @@ impl RAGFSBindingClient {pl_value.get("lock_expire_secs").and_then(|v| v.as_f64())- .unwrap_or(1800.0),+ .unwrap_or(30.0),)?;let lock_timeout_secs = validate_timeout_secs(pl_valuediff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsindex 979e4f03e..c0ea5b04d 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -155,7 +155,7 @@ mod tests {pathlock: PathLockConfig {provider: "filesystem".to_string(),lock_timeout_secs: 0.0,- lock_expire_secs: 1800.0,+ lock_expire_secs: 30.0,},}}diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex ef57fef1c..275a287c2 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -39,7 +39,7 @@ impl Default for PathLockConfig {Self {provider: "filesystem".to_string(),lock_timeout_secs: 0.0,- lock_expire_secs: 1800.0,+ lock_expire_secs: 30.0,}}}@@ -311,8 +311,17 @@ impl PathLockManager {let mut all_ok = true;for lp in &lock_paths {match refresh_provider.refresh_token(lp, &owner_id, now_ns).await {- Ok(true) => {}- _ => all_ok = false,+ Ok(true) => {+ info!(lease_ref = %lease_ref, owner_id = %owner_id, lock_path = %lp, "pathlock lease automatically refreshed");+ }+ Ok(false) => {+ all_ok = false;+ info!(lease_ref = %lease_ref, owner_id = %owner_id, lock_path = %lp, "pathlock lease automatic refresh failed");+ }+ Err(error) => {+ all_ok = false;+ info!(lease_ref = %lease_ref, owner_id = %owner_id, lock_path = %lp, error = %error, "pathlock lease automatic refresh failed");+ }}}drop(refresh_guard);@@ -1108,7 +1117,7 @@ impl PathLockManager {}let result = if all_ok && any_ok { "refreshed" } else if any_ok { "lost" } else { "failed" };- debug!(lease_ref = %lease.lease.lease_ref, owner_id = %lease.lease.owner_id, lock_paths = ?lease.lease.lock_paths, result = %result, "pathlock refresh completed");+ info!(lease_ref = %lease.lease.lease_ref, owner_id = %lease.lease.owner_id, lock_paths = ?lease.lease.lock_paths, result = %result, "pathlock refresh completed");Ok(result.to_string())}diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.mdindex f440b20ed..8d53f380d 100644--- a/docs/en/concepts/09-transaction.md+++ b/docs/en/concepts/09-transaction.md@@ -358,7 +358,7 @@ for conflicts first:### Lock Expiry Cleanup-**Stale lock detection**: PathLockEngine checks the fencing token timestamp. Locks older than `lock_expire` (default 1800s / 30 minutes) are considered stale and are removed automatically during acquisition.+**Stale lock detection**: PathLockEngine checks the fencing token timestamp. Locks older than `lock_expire` (default 30s) are considered stale and are removed automatically during acquisition.**In-process cleanup**: LockManager checks active LockHandles every 60 seconds. Handles that still own lock files but have been inactive for longer than `lock_expire` are force-released.@@ -371,7 +371,7 @@ After startup, QueueManager resumes persisted `session_commit` jobs:| Scenario | Recovery action ||----------|----------------|| session_memory extraction crash | Recover Phase 2 from archive and continue the `session_commit` job |-| Crash while holding lock | Lock file remains in AGFS; stale detection auto-cleans on next acquisition (default 1800s / 30-minute expiry) |+| Crash while holding lock | Lock file remains in AGFS; stale detection auto-cleans on next acquisition (default 30s expiry) || Crash after enqueue, before worker processes | QueueFS SQLite persistence; worker auto-pulls after restart || Orphan index | Cleaned on L2 on-demand load |@@ -387,7 +387,7 @@ After startup, QueueManager resumes persisted `session_commit` jobs:## Configuration-Path locks are enabled by default with no extra configuration needed. Prefer `storage.agfs.pathlock` for default wait and expiry settings. `storage.transaction` remains only as a legacy compatibility layer: `lock_timeout` and `lock_expire` are automatically mapped when the new fields are unset, while `redo_recovery_enabled` is deprecated and ignored.+Path locks are enabled by default with no extra configuration needed. Prefer `storage.agfs.pathlock` for expiry settings. The runtime wait timeout is fixed at `0.0` seconds and no longer accepts external configuration. `storage.transaction` remains only as a legacy compatibility layer: `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is deprecated and ignored.Recommended configuration:@@ -396,8 +396,7 @@ Recommended configuration:"storage": {"agfs": {"pathlock": {- "lock_timeout_secs": 5.0,- "lock_expire_secs": 1800.0+ "lock_expire_secs": 30.0}}}@@ -410,8 +409,7 @@ Legacy compatibility form:{"storage": {"transaction": {- "lock_timeout": 5.0,- "lock_expire": 1800.0+ "lock_expire": 30.0}}}@@ -419,8 +417,8 @@ Legacy compatibility form:| Parameter | Type | Description | Default ||-----------|------|-------------|---------|-| `lock_timeout` | float | Deprecated. Use `storage.agfs.pathlock.lock_timeout_secs`. | `0.0` |-| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. | `1800.0` |+| `lock_timeout` | float | Deprecated and ignored. Runtime wait timeout is fixed at `0.0`. | `0.0` |+| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. | `30.0` |### QueueFS Persistencediff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 28b7cc282..e15c8c6d2 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1647,7 +1647,7 @@ For startup and deployment details see [Deployment](./03-deployment.md), for aut## storage.transaction Section-`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` for active PathLock configuration. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` and `lock_expire` are automatically mapped when the new fields are unset, while `redo_recovery_enabled` is ignored.+`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` only for active PathLock expiry configuration. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is ignored.Recommended configuration:@@ -1656,8 +1656,7 @@ Recommended configuration:"storage": {"agfs": {"pathlock": {- "lock_timeout_secs": 5.0,- "lock_expire_secs": 1800.0+ "lock_expire_secs": 30.0}}}@@ -1670,8 +1669,7 @@ Legacy compatibility form (not recommended for new deployments):{"storage": {"transaction": {- "lock_timeout": 5.0,- "lock_expire": 1800.0+ "lock_expire": 30.0}}}@@ -1679,8 +1677,8 @@ Legacy compatibility form (not recommended for new deployments):| Parameter | Type | Description | Default ||-----------|------|-------------|---------|-| `lock_timeout` | float | Deprecated. Use `storage.agfs.pathlock.lock_timeout_secs`. Automatically mapped when the new field is unset. | `0.0` |-| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. Automatically mapped when the new field is unset. | `1800.0` |+| `lock_timeout` | float | Deprecated and ignored. Runtime wait timeout is fixed at `0.0`. | `0.0` |+| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. Automatically mapped when the new field is unset. | `30.0` || `redo_recovery_enabled` | bool | Deprecated and ignored. Session commit phase-2 recovery now resumes from the persistent `session_commit` queue. | `true` |For details on the lock mechanism, see [Path Locks and Crash Recovery](../concepts/09-transaction.md).@@ -1861,7 +1859,6 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry"timeout": 10},"transaction": {- "lock_timeout": 0.0,"lock_expire": 300.0},"vectordb": {diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.mdindex 5789ad948..547044a56 100644--- a/docs/zh/concepts/09-transaction.md+++ b/docs/zh/concepts/09-transaction.md@@ -366,7 +366,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败### 锁过期清理-**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 1800s / 30 分钟)的锁被视为陈旧锁,在加锁过程中自动移除。+**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 30s)的锁被视为陈旧锁,在加锁过程中自动移除。**进程内清理**:LockManager 每 60 秒检查活跃的 LockHandle。仍持有锁文件且失活时间超过 `lock_expire` 的 handle 会被强制释放。@@ -379,7 +379,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败| 场景 | 恢复方式 ||------|---------|| session_memory 提取中途崩溃 | 从 archive 恢复 Phase 2 并继续消费 `session_commit` 任务 |-| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 1800s / 30 分钟过期)|+| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 30s 过期)|| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化,worker 重启后自动拉取 || 孤儿索引 | L2 按需加载时清理 |@@ -395,7 +395,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败## 配置-路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置默认等待时间和过期时间。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。+路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置过期时间。运行时等待超时固定为 `0.0` 秒,不再接受外部配置。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。推荐写法:@@ -404,8 +404,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败"storage": {"agfs": {"pathlock": {- "lock_timeout_secs": 5.0,- "lock_expire_secs": 1800.0+ "lock_expire_secs": 30.0}}}@@ -418,8 +417,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败{"storage": {"transaction": {- "lock_timeout": 5.0,- "lock_expire": 1800.0+ "lock_expire": 30.0}}}@@ -427,8 +425,8 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|-| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。 | `0.0` |-| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。 | `1800.0` |+| `lock_timeout` | float | 已废弃且忽略。运行时等待超时固定为 `0.0`。 | `0.0` |+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。 | `30.0` |### QueueFS 持久化diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex b32f83c27..5746dd37c 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1824,7 +1824,7 @@ openviking add-resource ./docs --exclude "*.tmp"## storage.transaction 段-`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock`。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。+`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请仅使用 `storage.agfs.pathlock` 配置过期时间。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。推荐写法:@@ -1833,8 +1833,7 @@ openviking add-resource ./docs --exclude "*.tmp""storage": {"agfs": {"pathlock": {- "lock_timeout_secs": 5.0,- "lock_expire_secs": 1800.0+ "lock_expire_secs": 30.0}}}@@ -1847,8 +1846,7 @@ openviking add-resource ./docs --exclude "*.tmp"{"storage": {"transaction": {- "lock_timeout": 5.0,- "lock_expire": 1800.0+ "lock_expire": 30.0}}}@@ -1856,8 +1854,8 @@ openviking add-resource ./docs --exclude "*.tmp"| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|-| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。未显式配置新字段时会自动映射。 | `0.0` |-| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `1800.0` |+| `lock_timeout` | float | 已废弃且忽略。运行时等待超时固定为 `0.0`。 | `0.0` |+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `30.0` || `redo_recovery_enabled` | bool | 已废弃且忽略。当前版本的 `session.commit` phase-2 恢复由持久化 `session_commit` 队列负责。 | `true` |路径锁机制的详细说明见 [路径锁与崩溃恢复](../concepts/09-transaction.md)。@@ -1943,7 +1941,6 @@ Task 记录文件位于所属账号的系统目录:"timeout": 10},"transaction": {- "lock_timeout": 0.0,"lock_expire": 300.0},"vectordb": {diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 48e8c4c9b..3b654718e 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -67,8 +67,7 @@"timeout": 10,"pathlock": {"provider": "filesystem",- "lock_timeout_secs": 0.0,- "lock_expire_secs": 1800.0+ "lock_expire_secs": 30.0},"s3": {"bucket": null,diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.pyindex 304578db2..5bb01ef92 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -398,16 +398,27 @@ class AGFSCacheConfig(BaseModel):class AGFSPathLockConfig(BaseModel):"""Configuration for the native RAGFS path lock service."""+ @model_validator(mode="after")+ def ignore_deprecated_lock_timeout(self):+ """Warn and force the deprecated timeout back to the fixed runtime value."""+ if "lock_timeout_secs" in self.model_fields_set:+ logger.warning(+ "AGFSPathLockConfig: 'storage.agfs.pathlock.lock_timeout_secs' is deprecated "+ "and ignored; the runtime wait timeout is fixed at 0.0 seconds."+ )+ self.lock_timeout_secs = 0.0+ return self+provider: str = Field(default="filesystem",description="PathLock provider: 'filesystem' | 'memory'",)lock_timeout_secs: float = Field(default=0.0,- description="Default wait timeout for auto-acquired path locks in seconds.",+ description="Deprecated internal field. Runtime auto-pathlock wait timeout is fixed at 0.0 seconds.",)lock_expire_secs: float = Field(- default=1800.0,+ default=30.0,description="Seconds before an unrefreshed lock token becomes stale.",)@@ -418,8 +429,6 @@ class AGFSPathLockConfig(BaseModel):"""Validate provider and timeout/expiry ranges."""if self.provider not in {"filesystem", "memory"}:raise ValueError("pathlock provider must be one of: 'filesystem', 'memory'")- if self.lock_timeout_secs < 0.0:- raise ValueError("pathlock lock_timeout_secs must be >= 0.0")if self.lock_expire_secs < 1.0:raise ValueError("pathlock lock_expire_secs must be >= 1.0")return selfdiff --git a/openviking_cli/utils/config/storage_config.py b/openviking_cli/utils/config/storage_config.pyindex 558365f23..2c10cf20e 100644--- a/openviking_cli/utils/config/storage_config.py+++ b/openviking_cli/utils/config/storage_config.py@@ -64,19 +64,10 @@ class StorageConfig(BaseModel):@model_validator(mode="after")def resolve_paths(self):"""Normalize storage paths and map legacy transaction settings into native pathlock config."""- if (- "lock_timeout" in self.transaction.model_fields_set- and "lock_timeout_secs" not in self.agfs.pathlock.model_fields_set- ):- self.agfs.pathlock.lock_timeout_secs = self.transaction.lock_timeout- logger.warning(- "StorageConfig: 'transaction.lock_timeout' is deprecated. "- "Mapped to 'storage.agfs.pathlock.lock_timeout_secs'."- )- elif "lock_timeout" in self.transaction.model_fields_set:+ if "lock_timeout" in self.transaction.model_fields_set:logger.warning(- "StorageConfig: 'transaction.lock_timeout' is deprecated and ignored because "- "'storage.agfs.pathlock.lock_timeout_secs' is set."+ "StorageConfig: 'transaction.lock_timeout' is deprecated and ignored. "+ "The runtime wait timeout is fixed at 0.0 seconds.")if (diff --git a/openviking_cli/utils/config/transaction_config.py b/openviking_cli/utils/config/transaction_config.pyindex 97e76acd2..4184b5254 100644--- a/openviking_cli/utils/config/transaction_config.py+++ b/openviking_cli/utils/config/transaction_config.py@@ -6,20 +6,19 @@ from pydantic import BaseModel, Fieldclass TransactionConfig(BaseModel):"""Deprecated compatibility settings for legacy transaction fields.- Prefer ``storage.agfs.pathlock`` for active PathLock configuration.+ Prefer ``storage.agfs.pathlock`` only for active expiry configuration."""lock_timeout: float = Field(default=0.0,description=("Deprecated compatibility field. "- "Use storage.agfs.pathlock.lock_timeout_secs instead. "- "When the new field is unset, this value is mapped to it."+ "Ignored by the current implementation; runtime wait timeout is fixed at 0.0 seconds."),)lock_expire: float = Field(- default=1800.0,+ default=30.0,description=("Deprecated compatibility field. ""Use storage.agfs.pathlock.lock_expire_secs instead. "diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex 6059d778b..d5bffa0f3 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -730,7 +730,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p"cache": agfs_config.cache.model_dump(mode="json"),"pathlock": {"provider": "filesystem",- "lock_expire_secs": 1800.0,+ "lock_expire_secs": 30.0,"lock_timeout_secs": 0.0,},}@@ -751,8 +751,6 @@ def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):AGFSConfig(path=str(tmp_path), pathlock={"provider": "redis"})with pytest.raises(ValueError, match="lock_expire_secs"):AGFSConfig(path=str(tmp_path), pathlock={"lock_expire_secs": 0.0})- with pytest.raises(ValueError, match="lock_timeout_secs"):- AGFSConfig(path=str(tmp_path), pathlock={"lock_timeout_secs": -1.0})def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):diff --git a/tests/unit/config/test_transaction_config.py b/tests/unit/config/test_transaction_config.pyindex 6ad33b71c..8cd667025 100644--- a/tests/unit/config/test_transaction_config.py+++ b/tests/unit/config/test_transaction_config.py@@ -1,5 +1,5 @@from openviking_cli.utils.config.transaction_config import TransactionConfig-def test_lock_expire_defaults_to_thirty_minutes():- assert TransactionConfig().lock_expire == 30 * 60+def test_lock_expire_defaults_to_thirty_seconds():+ assert TransactionConfig().lock_expire == 30