oh-my-pi 内置 Rust 规则解析：从 std::sync 迁移到 parking_lot 的 Mutex/RwLock 实战指南

本文以 oh-my-pi（一个将 IDE 能力接入 Coding Agent 的开源项目）中内置的 TTSR（Time Traveling Stream Rules）规则文档 rs-parking-lot.md 为主线，完整解读"当代码对锁结果立即 unwrap 时，应使用 parking_lot::{Mutex, RwLock} 替代 std::sync::{Mutex, RwLock}"这一编码规约的技术依据、迁移步骤与边界条件。读完本文，你将掌握 parking_lot 与 std::sync 的 API 对应关系、锁中毒（poisoning）机制的区别、同步锁与异步锁的正确取舍，并理解这条规则如何在 oh-my-pi 的 Agent 中通过 TTSR 机制自动生效。

一、规则概览：一条"嵌入式"的 Rust 编码规约

在 oh-my-pi 仓库中，内置编码规则以 Markdown 文件形式存放于 packages/coding-agent/src/discovery/builtin-rules/。rs-parking-lot.md 是其中面向 Rust 项目的规则之一，其 Frontmatter 完整定义了该规则的触发条件与作用范围：

---
description: Use parking_lot instead of std::sync for Mutex/RwLock
condition:
  - "\\.lock\\(\\)\\.unwrap\\(\\)"
  - "\\.read\\(\\)\\.unwrap\\(\\)"
  - "\\.write\\(\\)\\.unwrap\\(\\)"
scope: "tool:edit(*.rs), tool:write(*.rs)"
interruptMode: never
---

逐项解读：

• condition：三条正则表达式，分别匹配 \.lock().unwrap()、.read().unwrap()、.write().unwrap() 三种"加锁后立即 unwrap"的调用形态；
• scope：限定规则的监控范围是 tool:edit(*.rs) 与 tool:write(*.rs)，即仅在 Agent 通过编辑工具（edit）或写入工具（write）操作 .rs 文件时生效；
• interruptMode: never：该规则命中时不中断 Agent 的生成流，而是走"非中断注入"路径（详见下文第六节）。

从源码结构看，这批规则由 builtin-rules/index.ts 统一通过 with { type: "text" } 导入，再经 builtin-defaults.ts 注册为 builtin-defaults Provider（优先级最低，任何同名用户/项目规则都可覆盖），最终被 bun build --compile 直接嵌入编译产物，随 Agent 二进制分发。

二、为什么推荐 parking_lot：四个核心理由

规则正文用四个要点阐述了推荐理由，下面逐一展开：

1. lock()、read()、write() 直接返回守卫（Guard）

std::sync::Mutex::lock() 返回 LockResult<MutexGuard>，即 Result<MutexGuard, PoisonError<MutexGuard>>；RwLock 的 read()/write() 同理返回 Result。因此标准库写法必须接 unwrap()（或 ?、expect、match）才能拿到守卫：

// std::sync：加锁是 Result，需要解包
let guard = data.lock().unwrap();

而 parking_lot::Mutex::lock() 直接返回 MutexGuard<'_, T>，RwLock 的 read()/write() 同样直接返回守卫，无需任何解包：

// parking_lot：加锁直接得到守卫
let guard = data.lock();

2. 没有需要 unwrap 的中毒（Poisoning）错误路径

标准库 std::sync 的锁具有中毒机制：当持有锁的线程在持锁期间 panic，锁会被标记为 poisoned，此后任何线程再 lock()/read()/write() 都会返回 PoisonError，调用方被迫决定是 unwrap() 直接 panic、还是调用 into_inner() 强行获取。这带来的直接后果是——只要想"正常"拿锁，几乎必然出现 unwrap()。

parking_lot 设计上移除了中毒语义：加锁失败的唯一情形是竞争被抢占（由内部队列与 fair lock 机制处理），不存在"锁被污染"的概念，因此也不存在需要 unwrap 的错误路径。这正是规则以 \.lock\(\)\.unwrap\(\) 等三条正则作为触发条件的根本原因——在标准库体系下，unwrap 只是中毒机制的"配套样板"；迁移到 parking_lot 后，这套样板整体消失。

3. 守卫更小，常见竞争场景下更快

规则原文表述为 "Guards are smaller and faster in common contention cases"。从 API 设计看，parking_lot 的守卫同样实现了 Deref/DerefMut，但内部不携带结果枚举包装，类型更精简；其内部锁实现采用自适应自旋 + 队列化休眠的策略（这是 parking_lot 项目自身宣称的设计），在低竞争与常见竞争场景下通常优于标准库的 futex 实现。需要注意：这是规则文件给出的动机陈述，具体数值差异依赖目标平台与负载特征，迁移时应以实际基准为准。

4. 调用点展示的是"加锁"，而非"错误处理样板"

对比两种写法：

// std::sync
let data = std::sync::Mutex::new(Vec::new());
let guard = data.lock().unwrap(); // 语义被 .unwrap() 稀释

// parking_lot
use parking_lot::Mutex;
let data = Mutex::new(Vec::new());
let guard = data.lock(); // 语义清晰：加锁，直接持有守卫

去掉 unwrap() 后，调用点的意图一目了然——读者看到的是"我在加锁并持有守卫"，而不是"我在处理一个（实际上永远不会失败的）锁错误"。代码的可读性、可审查性都随之提升。

三、迁移示例：Before / After

规则文档给出了最简洁的迁移样板，这里补充为一个完整可运行的最小示例：

// Before —— std::sync 体系
use std::sync::Mutex;

let data = Mutex::new(Vec::new());

// std::sync 的 lock() 返回 Result，必须 unwrap
let guard = data.lock().unwrap();
guard.push(1);

// After —— parking_lot 体系
use parking_lot::Mutex;

let data = Mutex::new(Vec::new());

// parking_lot 的 lock() 直接返回守卫，无需 unwrap
let guard = data.lock();
guard.push(1);

RwLock 的迁移完全对称：

// Before
use std::sync::RwLock;
let cache = RwLock::new(HashMap::new());
let readers = cache.read().unwrap();   // 读锁：Result，需 unwrap
let writer = cache.write().unwrap();   // 写锁：Result，需 unwrap

// After
use parking_lot::RwLock;
let cache = RwLock::new(HashMap::new());
let readers = cache.read();            // 直接得到读守卫
let writer = cache.write();            // 直接得到写守卫

此外，parking_lot 的守卫还提供标准库没有的便捷方法，例如 MutexGuard::map()/RwLockReadGuard::map() 可以投影出字段级守卫，进一步提升细粒度锁的可用性（此类细节可查阅 parking_lot 自身文档，不在此赘述）。

四、API 对照表：std::sync 与 parking_lot

规则文档以表格形式给出了两者核心类型的一一对应关系：

std::sync	parking_lot
Mutex<T>	Mutex<T>
RwLock<T>	RwLock<T>
Condvar	Condvar
Once	Once

几点补充说明：

• Mutex<T> / RwLock<T>：类型名一致，只需改 use 路径，迁移成本低；差异集中在加锁返回值（无 Result）与守卫生命周期（parking_lot 的守卫同样遵循借用规则，不能跨越其所借变量的作用域）。
• Condvar：parking_lot::Condvar 与 Mutex 配合使用，常用方法 wait/notify_one/notify_all 与标准库对应。
• Once：对应标准库 std::sync::Once（早期一次性初始化原语）。如果初始化逻辑可以在声明时给出，规则集中还有另一条姊妹规则 rs-lazylock.md 会进一步建议优先使用 std::sync::LazyLock——这说明不同规则之间是互补关系，需要结合具体场景综合判断。

五、边界条件：保持异步锁为异步

规则最后明确划出了一条边界——不要把所有锁都无脑换成 parking_lot：

Use tokio::sync::Mutex / tokio::sync::RwLock when a guard is held across .await or the lock belongs to async coordination.

即满足以下任一条件时，应使用 tokio::sync 的异步锁：

1. 守卫需要跨越 .await 持有：parking_lot 与 std::sync 的守卫都是"非 Send"的同步守卫，持锁跨 .await 会导致 future 无法跨 await 点传递，编译报错；tokio::sync::MutexGuard 则被设计为可以安全跨越 .await。
2. 锁本身属于异步协调场景：例如多个异步任务之间需要互斥共享状态，此时异步锁配合 Tokio 调度器能避免同步阻塞 worker 线程。

正确取舍：

// 同步路径（短临界区、不跨 await）—— 用 parking_lot
use parking_lot::Mutex;
let shared = Mutex::new(State::default());

// 异步协调路径（临界区可能跨 await）—— 用 tokio::sync
use tokio::sync::Mutex;
let shared = Mutex::new(State::default());
let guard = shared.lock().await; // 注意：tokio 锁也是锁，临界区要尽量短

需要强调的是，即使在异步场景，也应优先考虑"避免跨 await 持锁"的重构（如提取无锁的纯函数、用消息传递代替共享状态），锁只是最后手段。

六、规则背后的机制：TTSR 如何让规约自动生效

rs-parking-lot.md 不是一篇孤立的技术笔记，而是一条被 oh-my-pi 的 TTSR（Time Traveling Stream Rules，流式规则注入）系统实际消费的规则。理解其 Frontmatter 字段，就能还原它在 Agent 运行时的完整行为链路，详见仓库文档 docs/ttsr-injection-lifecycle.md：

1. 条件编译：规则中的 condition 正则会被 capability/rule.ts 中的 compileRuleCondition() 编译为 RegExp。该文件同时实现了 parseRuleConditionAndScope()：当 condition 项形如 *.rs 这类文件 glob 时，会被推断为 tool:edit(*.rs) 与 tool:write(*.rs) 两个 scope 快捷写法；而 rs-parking-lot.md 采用的是显式 scope 声明。
2. 流式匹配：会话创建时，loadCapability("rules") 按 rule.name 以"先到先得"去重（更高优先级 Provider 的规则胜出），随后 bucketRules() 将规则分桶。匹配阶段，Agent 生成工具调用参数（edit/write 的流式内容）时，TTSR 协调器对每个 .rs 文件流调用 checkDelta()/checkSnapshot()，用规则正则检测 .lock().unwrap() 等模式。
3. 非中断注入：interruptMode: never 意味着命中后不 abort 生成流。对工具类匹配（source === "tool"），规则被挂到对应工具调用上，工具真正产生结果后，在 toolResult 内容前置一个 <system-reminder reason="rule_violation" rule="rs-parking-lot" ...> 提醒块，把规则正文（即本文讲解的迁移指南）带给 Agent 参考；对文本类匹配则延迟在消息结束后以隐藏 custom message 注入。

这样，"用 parking_lot 替代 std::sync"就不再依赖开发者记忆，而是由 Agent 在写 .rs 代码的过程中自动触发、自动给出迁移建议。

七、如何覆盖、禁用或自定义这条规则

作为 builtin-defaults 内置规则，rs-parking-lot 享有最低优先级，用户有四种方式干预：

• 整体关闭内置规则：在 ttsr 配置组中设置 builtinRules: false（对应源码 builtin-defaults.ts 中描述的能力），整个内置规则集不再加载；
• 单独禁用：在 ttsr.disabledRules 中列出 rs-parking-lot，该规则在 bucketRules() 阶段被直接丢弃（见 docs/ttsr-injection-lifecycle.md 的 disabledRules 说明）；
• 同名覆盖：在任何更高优先级的规则源（项目 .omp/rules/、用户 ~/.omp/agent/rules/ 等）定义同名规则 rs-parking-lot，按名称去重时内置副本会被遮蔽；
• 按需调整 interruptMode：若希望命中时中断生成流强制修正，可将 interruptMode 改为 always（可选值为 never / prose-only / tool-only / always，解析逻辑见 capability/rule.ts）。

八、仓库实证：oh-my-pi 自身的 parking_lot 实践

规则并非空谈——oh-my-pi 仓库的 Rust 原生 crate 中大量使用 parking_lot，可作为迁移后的真实参考。以 crates/pi-natives/Cargo.toml 为例，其依赖声明为：

parking_lot.workspace = true

即通过 workspace 统一管理版本。源码层面，多个原生模块直接 use parking_lot::Mutex; 并省略 unwrap，例如：

• crates/pi-natives/src/audio.rs（音频模块）
• crates/pi-natives/src/grep.rs（文本搜索）
• crates/pi-natives/src/clipboard.rs（剪贴板）
• crates/pi-natives/src/diff.rs（差异计算）
• crates/pi-natives/src/desktop/mod.rs（桌面集成）

此外 crates/pi-builtins（shell 内建命令集合）与 crates/pi-iso（文件系统快照与同步）等 crate 同样引入 parking_lot。这些调用点展示了规则期望的最终形态：lock() 后直接持有守卫，不再出现 .unwrap() 错误处理样板。

总结

rs-parking-lot 规则的核心可归纳为一句话：当代码对锁结果立即 unwrap 时，用 parking_lot::{Mutex, RwLock} 替代 std::sync::{Mutex, RwLock}。它基于四个技术事实——直接返回守卫、无中毒错误路径、守卫更小更快、调用点更清晰；它划出了一条明确边界——守卫跨 .await 或属于异步协调时改用 tokio::sync；它还被编码进 oh-my-pi 的 TTSR 规则系统，在 Agent 编辑 .rs 文件时自动触发非中断提醒。对于 Rust 开发者，这不仅是一条可立即执行的迁移清单，更是一个理解"同步锁、异步锁、一次性初始化"三者选型的完整决策框架。