核心用法
@openclaw/interchange 是 OpenClaw 生态的底层共享库，专为代理间通过 .md 文件进行结构化通信而设计。开发者通过 writeMd/readMd 实现原子化的元数据+内容写入与读取，配合 acquireLock 实现多进程安全的文件访问。典型流程包括：构造包含 YAML frontmatter 的数据对象 → 调用原子写入（临时文件→fsync→重命名） → 对端读取并解析 → 可选执行 Schema 校验。库内置电路熔断器、生成追踪和内容哈希，支持分布式场景下的数据一致性保障。
显著优点
1. 原子性保障：tmp + fsync + rename 模式杜绝半写文件，极端情况下数据完整性优于常规日志写入。
2. 确定性序列化：键值排序与稳定 YAML 输出，确保相同输入产生相同文件内容，便于版本对比与哈希校验。
3. 并发安全：基于 POSIX advisory locking 的锁机制，含死锁检测与陈旧锁清理，适配容器化/多进程部署。
4. 生态整合：作为 OpenClaw 技能的基础依赖，统一了跨技能的数据交换格式，降低异构代理对接成本。
潜在缺点与局限性
- 文件系统依赖：原子写入和文件锁均依赖底层 FS 语义，在 NFS（尤其 v3）或部分网络存储上可能出现锁行为不一致或 fsync 失效。
- 性能边界：单文件粒度的锁机制在高并发小文件场景下可能成为瓶颈；大文件 YAML 解析内存占用随内容线性增长。
- Schema 验证成本：严格校验虽提升健壮性，但复杂 Schema 会增加 CPU 开销，极端延迟敏感场景需权衡。
- 生态锁定：深度绑定 OpenClaw 的元数据约定，脱离该生态使用时需额外适配层。
适合人群
- OpenClaw 技能开发者（必需依赖）
- 需要进程间/代理间可靠文件通信的 Node.js 应用
- 对数据一致性要求高、可接受文件系统约束的运维自动化场景
常规风险
| 风险类别 | 说明 |
|---------|------|
| 存储兼容性 | NFS、FUSE 等文件系统可能削弱原子写入保证，生产环境建议本地 FS 或经严格测试的分布式存储 |
| 锁饥饿 | 异常进程未释放锁可能导致后续操作阻塞，需监控锁等待超时 |
| YAML 解析漏洞 | 依赖的 YAML 解析库若存在反序列化漏洞（如 npm 历史 CVE），可能引入 RCE 风险，建议定期审计依赖 |