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(config): add compatible default timeout for ragfs pathlock (#3641)
baojun-zhang7c956f23bc07
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex 96ba44dc5..c5e4f4273 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -1167,10 +1167,18 @@ impl RAGFSBindingClient {pl_value.get("lock_expire_secs").and_then(|v| v.as_f64())- .unwrap_or(300.0),+ .unwrap_or(1800.0),)?;+ let lock_timeout_secs = validate_timeout_secs(+ pl_value+ .get("lock_timeout_secs")+ .and_then(|v| v.as_f64())+ .unwrap_or(0.0),+ )?+ .as_secs_f64();ragfs_cfg.pathlock = PathLockConfig {provider: provider.to_string(),+ lock_timeout_secs,lock_expire_secs,};}diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsindex da89b1cdc..979e4f03e 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -154,7 +154,8 @@ mod tests {}),pathlock: PathLockConfig {provider: "filesystem".to_string(),- lock_expire_secs: 300.0,+ lock_timeout_secs: 0.0,+ lock_expire_secs: 1800.0,},}}diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex ad39d43e9..10707cd00 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -28,6 +28,8 @@ use super::types::{pub struct PathLockConfig {/// Built-in provider name: `filesystem` or `memory`.pub provider: String,+ /// Default wait timeout for auto-acquired locks.+ pub lock_timeout_secs: f64,/// Seconds after which a lock token is considered stale.pub lock_expire_secs: f64,}@@ -36,7 +38,8 @@ impl Default for PathLockConfig {fn default() -> Self {Self {provider: "filesystem".to_string(),- lock_expire_secs: 300.0,+ lock_timeout_secs: 0.0,+ lock_expire_secs: 1800.0,}}}@@ -267,6 +270,11 @@ pub struct PathLockManager {}impl PathLockManager {+ /// Return the configured default timeout for automatic lock acquisition.+ pub fn default_lock_timeout(&self) -> Duration {+ Duration::from_secs_f64(self.config.lock_timeout_secs)+ }+/// Create a new PathLockManager.pub fn new(fs: Arc<dyn FileSystem>,diff --git a/crates/ragfs/src/lock/wrapper.rs b/crates/ragfs/src/lock/wrapper.rsindex 4e690884b..0258203b0 100644--- a/crates/ragfs/src/lock/wrapper.rs+++ b/crates/ragfs/src/lock/wrapper.rs@@ -8,8 +8,6 @@//! `PathLockManager`.use std::sync::Arc;-use std::time::Duration;-use async_trait::async_trait;use crate::core::filesystem::FileSystem;@@ -20,9 +18,6 @@ use crate::core::MountableFS;use super::manager::{AutoPathLockAction, PathLockManager};use super::types::{PathLockKind, PathLockRequest};-/// Default timeout for auto-acquired locks.-const AUTO_LOCK_TIMEOUT: Duration = Duration::ZERO;-/// A `FileSystem` wrapper that auto-acquires path locks for mutating operations.pub struct PathLockWrappedFS {/// The lock manager (single source of truth).@@ -109,7 +104,7 @@ impl FileSystem for PathLockWrappedFS {}let lease = self.manager- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .acquire_exact(path, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.create(path).await;@@ -134,7 +129,7 @@ impl FileSystem for PathLockWrappedFS {}let lease = self.manager- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .acquire_exact(path, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.remove(path).await;@@ -155,7 +150,7 @@ impl FileSystem for PathLockWrappedFS {}let lease = self.manager- .acquire_tree(path, AUTO_LOCK_TIMEOUT, None)+ .acquire_tree(path, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.remove_all(path).await;@@ -186,7 +181,7 @@ impl FileSystem for PathLockWrappedFS {}let lease = self.manager- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .acquire_exact(path, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.write(path, data, offset, flags).await;@@ -245,7 +240,7 @@ impl FileSystem for PathLockWrappedFS {let lease = self.manager- .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)+ .acquire_batch(&requests, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.rename(old_path, new_path).await;@@ -273,7 +268,7 @@ impl FileSystem for PathLockWrappedFS {}let lease = self.manager- .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)+ .acquire_batch(&requests, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.replace(src_path, dst_path).await;@@ -298,7 +293,7 @@ impl FileSystem for PathLockWrappedFS {}let lease = self.manager- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)+ .acquire_exact(path, self.manager.default_lock_timeout(), None).await.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;let result = self.inner.truncate(path, size).await;diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.mdindex 613950c2c..f440b20ed 100644--- a/docs/en/concepts/09-transaction.md+++ b/docs/en/concepts/09-transaction.md@@ -1,6 +1,6 @@# Path Locks and Crash Recovery-OpenViking uses two simple primitives — **path locks** and **redo log** — to protect the consistency of core write operations (`rm`, `mv`, `add_resource`, `session.commit`), ensuring that VikingFS, VectorDB, and QueueManager remain consistent even when failures occur.+OpenViking uses two simple primitives — **path locks** and **persistent queue recovery** — to protect the consistency of core write operations (`rm`, `mv`, `add_resource`, `session.commit`), ensuring that VikingFS, VectorDB, and QueueManager remain consistent even when failures occur.## Design Philosophy@@ -13,7 +13,7 @@ OpenViking is a context database where FS is the source of truth and VectorDB is1. **Write-exclusive**: Path locks ensure only one write operation can operate on a path at a time2. **On by default**: All data operations automatically acquire locks; no extra configuration needed3. **Lock as protection**: LockContext acquires locks on entry, releases on exit — no undo/journal/commit semantics-4. **Only session_memory needs crash recovery**: RedoLog re-executes memory extraction after a process crash+4. **Only session_memory needs crash recovery**: a persistent `session_commit` queue resumes Phase 2 after a process crash5. **Queue operations run outside locks**: SemanticQueue/EmbeddingQueue enqueue operations are idempotent and retriable## Architecture@@ -57,26 +57,23 @@ class LockHandle:**LockManager** is a global singleton managing lock lifecycle:- Creates/releases LockHandles- Background cleanup of leaked locks (in-process safety net)-- Executes RedoLog recovery on startup+- Relies on QueueManager to resume persisted `session_commit` Phase 2 work after startup**LockContext** is an async context manager encapsulating the lock/unlock lifecycle:```python-from openviking.storage.transaction import LockContext, get_lock_manager--async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.+async with LockContext(lock_manager, [path], lock_mode="exact") as handle:# Perform operations under lock protection...# Lock automatically released on exit (including exceptions)```-### Component 2: RedoLog (Crash Recovery)--Used only for the memory extraction phase of `session.commit`. Writes a marker before the operation, deletes it after success, and scans for leftover markers on startup to redo.+### Component 2: Persistent `session_commit` Queue (Crash Recovery)-```-/local/_system/redo/{task_id}/redo.json-```+`session.commit` Phase 2 no longer uses a standalone redo log. Phase 1 persists archive metadata first,+then enqueues a durable `SessionCommitMsg`; after restart, QueueManager resumes any leftover+`session_commit` jobs and continues Phase 2.Memory extraction is idempotent — re-extracting from the same archive produces the same result.@@ -207,7 +204,7 @@ hold separate ExactPathLocks for the two source files. Refreshing `preferences/.| Problem | Solution ||---------|----------|-| Messages cleared but archive not written -> conversation data lost | Phase 1 without lock (incomplete archive has no side effects) + Phase 2 with RedoLog |+| Messages cleared but archive not written -> conversation data lost | Phase 1 without lock (incomplete archive has no side effects) + Phase 2 with a persistent `session_commit` queue |LLM calls have unpredictable latency (5s~60s+) and cannot be inside a lock-holding operation. The design splits into two phases:@@ -218,32 +215,29 @@ Phase 1 — Archive (no lock):3. Clear messages.jsonl4. Clear in-memory message list-Phase 2 — Memory extraction + write (RedoLog):- 1. Write redo marker (archive_uri, session_uri, user identity)+Phase 2 — Memory extraction + write (persistent `session_commit` queue):+ 1. Persist archive metadata and enqueue `SessionCommitMsg`2. Extract memories from archived messages (LLM)3. Write current message state4. Write relations5. Directly enqueue SemanticQueue- 6. Delete redo marker```**Crash recovery analysis**:| Failure moment | State | Recovery action ||------------|-------|----------------|-| During Phase 1 archive write | No marker | Incomplete archive; next commit scans history/ for index, unaffected |-| Phase 1 archive complete but messages not cleared | No marker | Archive complete + messages still present = redundant but safe |-| During Phase 2 memory extraction/write | Redo marker exists | On startup: redo extraction + write + enqueue from archive |-| Phase 2 complete | Redo marker deleted | No recovery needed |+| During Phase 1 archive write | Queue not published yet | Incomplete archive; next commit scans history/ for index, unaffected |+| Phase 1 archive complete but messages not cleared | Queue not published yet | Archive complete + messages still present = redundant but safe |+| During Phase 2 memory extraction/write | `session_commit` job still persisted | After restart: resume the job and recover Phase 2 from archive |+| Phase 2 complete | Archive marked complete | No recovery needed |## LockContext`LockContext` is an **async** context manager that encapsulates lock acquisition and release:```python-from openviking.storage.transaction import LockContext, get_lock_manager--lock_manager = get_lock_manager()+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.# Exact lock (write operations, semantic processing)async with LockContext(lock_manager, [path], lock_mode="exact"):@@ -372,11 +366,11 @@ for conflicts first:## Crash Recovery-`LockManager.start()` automatically scans for leftover markers in `/local/_system/redo/` on startup:+After startup, QueueManager resumes persisted `session_commit` jobs:| Scenario | Recovery action ||----------|----------------|-| session_memory extraction crash | Redo memory extraction + write + enqueue from archive |+| 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 after enqueue, before worker processes | QueueFS SQLite persistence; worker auto-pulls after restart || Orphan index | Cleaned on L2 on-demand load |@@ -387,13 +381,30 @@ for conflicts first:|-----------------|--------|-----------------|| Crash during operation | Lock auto-expires + stale detection | Next acquisition of same path lock || Crash during add_resource semantic processing | Lifecycle lock expires + SemanticProcessor re-acquires on restart | Worker restart |-| Crash during session.commit Phase 2 | RedoLog marker + redo | On restart |+| Crash during session.commit Phase 2 | Persistent `session_commit` queue + resumed consumption | On restart || Crash after enqueue, before worker | QueueFS SQLite persistence | Worker restart || Orphan index | L2 on-demand load cleanup | When user accesses |## Configuration-Path locks are enabled by default with no extra configuration needed. **The default behavior is no-wait**: if the path is locked, `LockAcquisitionError` is raised immediately. To allow wait/retry, configure the `storage.transaction` section:+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.++Recommended configuration:++```json+{+ "storage": {+ "agfs": {+ "pathlock": {+ "lock_timeout_secs": 5.0,+ "lock_expire_secs": 1800.0+ }+ }+ }+}+```++Legacy compatibility form:```json{@@ -408,8 +419,8 @@ Path locks are enabled by default with no extra configuration needed. **The defa| Parameter | Type | Description | Default ||-----------|------|-------------|---------|-| `lock_timeout` | float | Lock acquisition timeout (seconds). `0` = fail immediately if locked (default). `> 0` = wait/retry up to this many seconds. | `0.0` |-| `lock_expire` | float | Lock inactivity threshold (seconds). Locks not refreshed within this window are treated as stale and reclaimed. | `1800.0` |+| `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` |### QueueFS Persistencediff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 088415dc2..97fb549ea 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1552,14 +1552,31 @@ For startup and deployment details see [Deployment](./03-deployment.md), for aut## storage.transaction Section-Path locks are enabled by default and usually require no configuration. **The default behavior is no-wait**: if the target path is already locked by another operation, the operation fails immediately with `LockAcquisitionError`. Set `lock_timeout` to a positive value to allow polling/retry.+`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.++Recommended configuration:++```json+{+ "storage": {+ "agfs": {+ "pathlock": {+ "lock_timeout_secs": 5.0,+ "lock_expire_secs": 1800.0+ }+ }+ }+}+```++Legacy compatibility form (not recommended for new deployments):```json{"storage": {"transaction": {"lock_timeout": 5.0,- "lock_expire": 300.0+ "lock_expire": 1800.0}}}@@ -1567,8 +1584,9 @@ Path locks are enabled by default and usually require no configuration. **The de| Parameter | Type | Description | Default ||-----------|------|-------------|---------|-| `lock_timeout` | float | Path lock acquisition timeout (seconds). `0` = fail immediately if locked (default). `> 0` = wait/retry up to this many seconds, then raise `LockAcquisitionError`. | `0.0` |-| `lock_expire` | float | Lock inactivity threshold (seconds). Locks not refreshed within this window are treated as stale and reclaimed. | `300.0` |+| `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` |+| `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).diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.mdindex 033aacf9d..5789ad948 100644--- a/docs/zh/concepts/09-transaction.md+++ b/docs/zh/concepts/09-transaction.md@@ -1,6 +1,6 @@# 路径锁与崩溃恢复-OpenViking 通过**路径锁**和**Redo Log** 两个简单原语保护核心写操作(`rm`、`mv`、`add_resource`、`session.commit`)的一致性,确保 VikingFS、VectorDB、QueueManager 三个子系统在故障时不会出现数据不一致。+OpenViking 通过**路径锁**和**持久化队列恢复**两个简单原语保护核心写操作(`rm`、`mv`、`add_resource`、`session.commit`)的一致性,确保 VikingFS、VectorDB、QueueManager 三个子系统在故障时不会出现数据不一致。## 设计哲学@@ -13,7 +13,7 @@ OpenViking 是上下文数据库,FS 是源数据,VectorDB 是派生索引。1. **写互斥**:通过路径锁保证同一路径同一时间只有一个写操作2. **默认生效**:所有数据操作命令自动加锁,用户无需额外配置3. **锁即保护**:进入 LockContext 时加锁,退出时释放,没有 undo/journal/commit 语义-4. **仅 session_memory 需要崩溃恢复**:通过 RedoLog 在进程崩溃后重做记忆提取+4. **仅 session_memory 需要崩溃恢复**:通过持久化 `session_commit` 队列在进程崩溃后恢复 Phase 25. **Queue 操作在锁外执行**:SemanticQueue/EmbeddingQueue 的 enqueue 是幂等的,失败可重试## 架构@@ -56,28 +56,25 @@ class LockHandle:**LockManager** 是全局单例,管理锁生命周期:- 创建/释放 LockHandle- 后台清理泄漏的锁(进程内安全网)-- 启动时执行 RedoLog 恢复+- 启动后由 QueueManager 恢复持久化的 `session_commit` Phase 2 任务**LockContext** 是异步上下文管理器,封装加锁/解锁生命周期:```python-from openviking.storage.transaction import LockContext, get_lock_manager--async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.+async with LockContext(lock_manager, [path], lock_mode="exact") as handle:# 在锁保护下执行操作...# 退出时自动释放锁(包括异常情况)```-### 组件 2:RedoLog(崩溃恢复)--仅用于 `session.commit` 的记忆提取阶段。操作前写标记,成功后删标记,启动时扫描遗留标记并重做。+### 组件 2:持久化 `session_commit` 队列(崩溃恢复)-```-/local/_system/redo/{task_id}/redo.json-```+`session.commit` 的 Phase 2 不再使用独立 RedoLog。Phase 1 会先把 archive 元数据持久化,再把+`SessionCommitMsg` 写入持久化队列;进程重启后,QueueManager 会继续消费遗留的 `session_commit`+任务并恢复 Phase 2。-Memory 提取是幂等的 — 从同一个 archive 重新提取会得到相同结果。+Memory 提取是幂等的,从同一个 archive 重新提取会得到相同结果。## 一致性问题与解决方案@@ -201,7 +198,7 @@ viking://user/default/memories/preferences/editor.md| 问题 | 方案 ||------|------|-| 消息已清空但 archive 未写入 -> 对话数据丢失 | Phase 1 无锁(archive 不完整无副作用)+ Phase 2 RedoLog |+| 消息已清空但 archive 未写入 -> 对话数据丢失 | Phase 1 无锁(archive 不完整无副作用)+ Phase 2 持久化 `session_commit` 队列 |LLM 调用耗时不可控(5s~60s+),不能放在持锁操作内。设计拆为两个阶段:@@ -212,32 +209,29 @@ Phase 1 — 归档(无锁):3. 清空 messages.jsonl4. 清空内存中的消息列表-Phase 2 — 记忆提取 + 写入(RedoLog):- 1. 写 redo 标记(archive_uri、session_uri、用户身份信息)+Phase 2 — 记忆提取 + 写入(持久化 `session_commit` 队列):+ 1. 持久化 archive 元数据并 enqueue `SessionCommitMsg`2. 从归档消息提取 memories(LLM)3. 写当前消息状态4. 写 relations5. 直接 enqueue SemanticQueue- 6. 删除 redo 标记```**崩溃恢复分析**:| 崩溃时间点 | 状态 | 恢复动作 ||-----------|------|---------|-| Phase 1 写 archive 中途 | 无标记 | archive 不完整,下次 commit 从 history/ 扫描 index,不受影响 |-| Phase 1 archive 完成但 messages 未清空 | 无标记 | archive 完整 + messages 仍在 = 数据冗余但安全 |-| Phase 2 记忆提取/写入中途 | redo 标记存在 | 启动恢复:从 archive 重做提取+写入+入队 |-| Phase 2 完成 | redo 标记已删 | 无需恢复 |+| Phase 1 写 archive 中途 | 队列未发布 | archive 不完整,下次 commit 从 history/ 扫描 index,不受影响 |+| Phase 1 archive 完成但 messages 未清空 | 队列未发布 | archive 完整 + messages 仍在 = 数据冗余但安全 |+| Phase 2 记忆提取/写入中途 | `session_commit` 任务仍在持久化队列中 | 重启后继续消费该任务,从 archive 恢复 Phase 2 |+| Phase 2 完成 | archive 标记为完成 | 无需恢复 |## LockContext`LockContext` 是**异步**上下文管理器,封装锁的获取和释放:```python-from openviking.storage.transaction import LockContext, get_lock_manager--lock_manager = get_lock_manager()+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.# Exact 锁(写操作、语义处理)async with LockContext(lock_manager, [path], lock_mode="exact"):@@ -380,11 +374,11 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败## 崩溃恢复-`LockManager.start()` 启动时自动扫描 `/local/_system/redo/` 目录中的遗留标记:+服务启动后,QueueManager 会继续消费持久化的 `session_commit` 任务:| 场景 | 恢复方式 ||------|---------|-| session_memory 提取中途崩溃 | 从 archive 重做记忆提取 + 写入 + enqueue |+| session_memory 提取中途崩溃 | 从 archive 恢复 Phase 2 并继续消费 `session_commit` 任务 || 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 1800s / 30 分钟过期)|| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化,worker 重启后自动拉取 || 孤儿索引 | L2 按需加载时清理 |@@ -395,13 +389,30 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败|---------|------|---------|| 操作中途崩溃 | 锁自动过期 + stale 检测 | 下次获取同路径锁时 || add_resource 语义处理中途崩溃 | 生命周期锁过期 + SemanticProcessor 重启时重新获取 | worker 重启后 |-| session.commit Phase 2 崩溃 | RedoLog 标记 + 重做 | 重启时 |+| session.commit Phase 2 崩溃 | 持久化 `session_commit` 队列 + 重试消费 | 重启时 || enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化 | worker 重启后 || 孤儿索引 | L2 按需加载时清理 | 用户访问时 |## 配置-路径锁默认启用,无需额外配置。**默认不等待**:若路径被锁定则立即抛出 `LockAcquisitionError`。如需允许等待重试,可通过 `storage.transaction` 段配置:+路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置默认等待时间和过期时间。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。++推荐写法:++```json+{+ "storage": {+ "agfs": {+ "pathlock": {+ "lock_timeout_secs": 5.0,+ "lock_expire_secs": 1800.0+ }+ }+ }+}+```++兼容旧写法:```json{@@ -416,8 +427,8 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|-| `lock_timeout` | float | 获取锁的等待超时(秒)。`0` = 立即失败(默认);`> 0` = 最多等待此时间 | `0.0` |-| `lock_expire` | float | 锁失活阈值(秒),超过此时间未被 refresh 的锁会被视为陈旧锁并回收 | `1800.0` |+| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。 | `0.0` |+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。 | `1800.0` |### QueueFS 持久化diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 3015d3e7a..2a0aaab93 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1611,14 +1611,31 @@ openviking add-resource ./docs --exclude "*.tmp"## storage.transaction 段-路径锁默认启用,通常无需配置。**默认行为是不等待**:若目标路径已被其他操作锁定,操作立即失败并抛出 `LockAcquisitionError`。若需要等待重试,请将 `lock_timeout` 设为正数。+`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock`。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。++推荐写法:++```json+{+ "storage": {+ "agfs": {+ "pathlock": {+ "lock_timeout_secs": 5.0,+ "lock_expire_secs": 1800.0+ }+ }+ }+}+```++兼容旧写法(不推荐新项目继续使用):```json{"storage": {"transaction": {"lock_timeout": 5.0,- "lock_expire": 300.0+ "lock_expire": 1800.0}}}@@ -1626,8 +1643,9 @@ openviking add-resource ./docs --exclude "*.tmp"| 参数 | 类型 | 说明 | 默认值 ||------|------|------|--------|-| `lock_timeout` | float | 获取路径锁的等待超时(秒)。`0` = 立即失败(默认);`> 0` = 最多等待此时间后抛出 `LockAcquisitionError` | `0.0` |-| `lock_expire` | float | 锁失活阈值(秒)。超过此时间未被 refresh 的锁会被视为陈旧锁并回收 | `300.0` |+| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。未显式配置新字段时会自动映射。 | `0.0` |+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `1800.0` |+| `redo_recovery_enabled` | bool | 已废弃且忽略。当前版本的 `session.commit` phase-2 恢复由持久化 `session_commit` 队列负责。 | `true` |路径锁机制的详细说明见 [路径锁与崩溃恢复](../concepts/09-transaction.md)。diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 4527f69ad..0c3f6bb53 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -64,6 +64,11 @@"agfs": {"backend": "local","timeout": 10,+ "pathlock": {+ "provider": "filesystem",+ "lock_timeout_secs": 0.0,+ "lock_expire_secs": 1800.0+ },"s3": {"bucket": null,"region": null,diff --git a/openviking/storage/transaction/__init__.py b/openviking/storage/transaction/__init__.pyindex 93e772ac0..99de417b1 100644--- a/openviking/storage/transaction/__init__.py+++ b/openviking/storage/transaction/__init__.py@@ -7,8 +7,4 @@ Path-lock management has been moved to the Rust ragfs layer.Python-side lock operations now go through RAGFSBindingClient.pathlock_* methods."""-from openviking.storage.transaction.redo_log import RedoLog--__all__ = [- "RedoLog",-]+__all__: list[str] = []diff --git a/openviking/storage/transaction/redo_log.py b/openviking/storage/transaction/redo_log.pydeleted file mode 100644index 7631919c1..000000000--- a/openviking/storage/transaction/redo_log.py+++ /dev/null@@ -1,59 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Lightweight redo log for crash recovery of session_memory operations."""--import json-from typing import Any, Dict, List--from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient-from openviking_cli.utils.logger import get_logger--logger = get_logger(__name__)--_REDO_ROOT = "/local/_system/redo"---class RedoLog:- """Lightweight pending-task marker.-- Write a marker before the operation starts; delete it after success.- On startup, scan for leftover markers and redo.- """-- def __init__(self, agfs: AGFSSyncClientProtocol):- self._async_agfs = AsyncAGFSClient(agfs)-- def _task_path(self, task_id: str) -> str:- return f"{_REDO_ROOT}/{task_id}/redo.json"-- async def mark_done_async(self, task_id: str) -> None:- """Delete the redo marker after a successful operation."""- try:- await self._async_agfs.rm(f"{_REDO_ROOT}/{task_id}", recursive=True)- except Exception as e:- logger.warning(f"Failed to clean redo marker {task_id}: {e}")-- async def list_pending_async(self) -> List[str]:- """Return all pending task IDs (directories under _REDO_ROOT)."""- try:- entries = await self._async_agfs.ls(_REDO_ROOT)- if not isinstance(entries, list):- return []- return [- e["name"]- for e in entries- if isinstance(e, dict) and e.get("isDir") and e.get("name") not in (".", "..")- ]- except Exception:- return []-- async def read_async(self, task_id: str) -> Dict[str, Any]:- """Read the info dict of a pending task."""- try:- content = await self._async_agfs.cat(self._task_path(task_id))- if isinstance(content, bytes):- content = content.decode("utf-8")- return json.loads(content)- except Exception as e:- logger.warning(f"Failed to read redo info for {task_id}: {e}")- return {}diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.pyindex feed25756..b86bc7f64 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -322,8 +322,12 @@ class AGFSPathLockConfig(BaseModel):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.",+ )lock_expire_secs: float = Field(- default=300.0,+ default=1800.0,description="Seconds before an unrefreshed lock token becomes stale.",)@@ -331,9 +335,11 @@ class AGFSPathLockConfig(BaseModel):@model_validator(mode="after")def validate_config(self):- """Validate provider and stale-lock expiry."""+ """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 059b1e4a6..558365f23 100644--- a/openviking_cli/utils/config/storage_config.py+++ b/openviking_cli/utils/config/storage_config.py@@ -63,6 +63,44 @@ 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:+ logger.warning(+ "StorageConfig: 'transaction.lock_timeout' is deprecated and ignored because "+ "'storage.agfs.pathlock.lock_timeout_secs' is set."+ )++ if (+ "lock_expire" in self.transaction.model_fields_set+ and "lock_expire_secs" not in self.agfs.pathlock.model_fields_set+ ):+ self.agfs.pathlock.lock_expire_secs = self.transaction.lock_expire+ logger.warning(+ "StorageConfig: 'transaction.lock_expire' is deprecated. "+ "Mapped to 'storage.agfs.pathlock.lock_expire_secs'."+ )+ elif "lock_expire" in self.transaction.model_fields_set:+ logger.warning(+ "StorageConfig: 'transaction.lock_expire' is deprecated and ignored because "+ "'storage.agfs.pathlock.lock_expire_secs' is set."+ )++ if "redo_recovery_enabled" in self.transaction.model_fields_set:+ logger.warning(+ "StorageConfig: 'transaction.redo_recovery_enabled' is deprecated and ignored. "+ "Session commit phase-2 recovery now resumes from the persistent "+ "'session_commit' queue."+ )+if self.agfs.path is not None:logger.warning(f"StorageConfig: 'agfs.path' is deprecated and will be ignored. "diff --git a/openviking_cli/utils/config/transaction_config.py b/openviking_cli/utils/config/transaction_config.pyindex ead027358..97e76acd2 100644--- a/openviking_cli/utils/config/transaction_config.py+++ b/openviking_cli/utils/config/transaction_config.py@@ -4,36 +4,35 @@ from pydantic import BaseModel, Fieldclass TransactionConfig(BaseModel):- """Configuration for the transaction mechanism.+ """Deprecated compatibility settings for legacy transaction fields.- By default, lock acquisition does not wait (``lock_timeout=0``): if a- conflicting lock is held the operation fails immediately with- ``LockAcquisitionError``. Set ``lock_timeout`` to a positive value to- allow the caller to block and retry for up to that many seconds.+ Prefer ``storage.agfs.pathlock`` for active PathLock configuration."""lock_timeout: float = Field(default=0.0,description=(- "Path lock acquisition timeout (seconds). "- "0 = fail immediately if locked (default). "- "> 0 = wait/retry up to this many seconds before raising LockAcquisitionError."+ "Deprecated compatibility field. "+ "Use storage.agfs.pathlock.lock_timeout_secs instead. "+ "When the new field is unset, this value is mapped to it."),)lock_expire: float = Field(default=1800.0,description=(- "Lock inactivity threshold (seconds). "- "Locks not refreshed within this window are treated as stale and reclaimed."+ "Deprecated compatibility field. "+ "Use storage.agfs.pathlock.lock_expire_secs instead. "+ "When the new field is unset, this value is mapped to it."),)redo_recovery_enabled: bool = Field(default=True,description=(- "Enable session commit phase-2 crash-recovery redo. "- "When false, pending redo markers are not written and startup redo recovery is skipped."+ "Deprecated compatibility flag for the legacy session commit phase-2 redo recovery. "+ "Ignored in the current implementation, which resumes phase-2 work from the "+ "persistent session_commit queue."),)diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex dccbfcffa..3f1efeea9 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -586,7 +586,8 @@ 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": 300.0,+ "lock_expire_secs": 1800.0,+ "lock_timeout_secs": 0.0,},}@@ -606,6 +607,8 @@ 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/transaction/test_redo_log.py b/tests/transaction/test_redo_log.pydeleted file mode 100644index 9feef74ea..000000000--- a/tests/transaction/test_redo_log.py+++ /dev/null@@ -1,24 +0,0 @@-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.-# SPDX-License-Identifier: AGPL-3.0-"""Tests for RedoLog crash recovery."""---import pytest--from openviking.storage.transaction.redo_log import RedoLog---def redo(agfs_client):- return RedoLog(agfs_client)---class TestRedoLogBasic:- async def test_read_nonexistent_returns_empty(self, redo):- result = await redo.read_async("nonexistent-task-id")- assert result == {}-- async def test_list_pending_empty(self, redo):- # Should not crash even if _REDO_ROOT doesn't exist yet- pending = await redo.list_pending_async()- assert isinstance(pending, list)