Himalaya pimdir 后端的读者-生产者改造：从“误当仓库主人”到“只读索引、队列写意图”

• CLI

本篇文章基于 Himalaya（Rust 编写的 CLI 邮件客户端）仓库中pimdir-producer-reader变更记录，讲解 pimdir 后端的一次关键架构修正：Himalaya 不再以“同步引擎仓库拥有者”的身份直接改写本地 pimdir 存储，而是以只读读者 + 队列生产者的双重角色访问它。读完本文，你将理解 pimdir 邮箱名为何要按“服务器命名”展示与解析、写操作为何一律先入队、pimdir.account与pimdir.namespace的正确用法，以及“body not fetched”状态与短公共 ID 的由来。

背景：两个真实缺陷

本次变更（cairn 变更记录pimdir-producer-reader，proposal.md，2026-08-26 落地）针对的是一个真实的 Neverest 同步存储暴露出的两个缺陷，一个立竿见影，一个尚未爆发。

缺陷一：邮箱按存储键命名

Neverest 以<namespace>/<name>作为 hub collection 的键，因此服务器口中的INBOX在存储里实际是imap/INBOX。旧实现把完整的 collection id 直接当作显示名，并要求用户输入时也回传该 id，结果：

• mailbox list把 id 打印了两遍；
• -m INBOX查找的是一个从未被写入任何内容的 collection——得到一个空的 envelope 表，且无任何报错；
• mailbox.alias.inbox以及“未指定邮箱时默认 INBOX”这两条路径在 pimdir 账户下全部失效，因为它们解析出的都是不带命名空间的裸名。

换句话说，用户永远无法通过-m INBOX操作真正的收件箱。

缺陷二：写路径跑的是“主人”的写路径

store_flags及其余四个写动词此前驱动 io-replica 的mutate协程，最终进入ReplicaStorage::write；而在 io-pimdir 0.2 中，该写路径会在每个批次结束时执行collect_garbage：DELETE FROM objects WHERE refcount = 0并 unlink 对应的 blob。

Neverest 的水合（hydration）阶段先把消息体以 refcount 0 流式写入 blob 树，随后在下一阶段才挂接引用（pimdir SPEC §14 明确允许这种“挂起待办”的状态）。于是，一次在同步进行中执行的himalaya flag add就会删除所有尚未挂接的消息体，连同字节一并销毁——而该存储以 GB 计，全靠同步引擎回填。更糟的是 io-pimdir 0.2 不持有任何 owner 锁，两个进程之间没有任何互斥机制。

结论很明确：Himalaya 从来就不是这个仓库的主人，它应当读取副本、登记意图（intent）。格式本身早已如此规定——读者不加锁，生产者加共享锁并追加动作队列，由主人排空。

核心转变：读者与生产者，而非主人

本次改造把 pimdir 后端彻底切换为“读者 + 生产者”模型，实现位于 src/pimdir/client.rs：

let store = PimdirReader::open(&root)? .with_pending();

• 读路径：通过PimdirReader::open以只读方式打开存储，不获取任何锁（_lock: None），因此同步进行中的 Himalaya 既不会阻塞同步，也不会被同步阻塞。with_pending()让读者把队列叠加在索引之上，本进程刚入队的动作在下一次读取时立即可见，不必等主人应用。
• 写路径：每次暂存（staging）才通过PimdirProducer::open(&root, PRODUCER)短暂进入生产者角色（PRODUCER = "himalaya"，记录在队列行上），持有共享锁完成一次入队后立即释放，见 src/pimdir/client.rs。

后端绝不写入索引、绝不加载 collection、绝不运行主人的对象清扫（sweep）——同步旁的清扫会毁掉已流式写入但尚未挂接的消息体。与之配套的依赖升级为 io-pimdir 0.2→0.3、io-replica 0.3→0.4（在 Neverest 发布前以 git 补丁形式使用，见 tasks.md）。

邮箱命名：按服务器的方式，而非存储键

变更在 SPEC 中新增了一条需求“pimdir names a mailbox the way its server does”（delta.md）：

• hub collection 以<namespace>/<name>为键，后端展示与接受名称时去掉命名空间：imap/INBOX即邮箱INBOX；
• 当该账户的所有邮件 collection 共享同一前缀时，命名空间被自动推导（单源账户必然满足）；
• 推导结果可被pimdir.namespace覆盖；若一个存储中的邮件 collection 横跨两个命名空间，则保留完整 id 作为名称，避免把两个邮箱折叠成一个。

用户输入的名称会先解析到该账户的邮件 collection 集合上，完整 collection id 仍按原样接受；匹配不到或匹配到多个的名称会被拒绝并列出账户实际持有的候选邮箱，而不是把未解析的名称直接传给存储——后者会读成一个“存在但为空”的邮箱。核心解析逻辑在 src/pimdir/backend.rs 的hub_id：

if ids.iter().any(|id| id == mailbox) { return Ok(mailbox.to_string()); } ids.sort(); bail!("Mailbox `{mailbox}` not found in the pimdir store, which holds: {}", ids.join(", "));

对应两个验收场景：

• 配置的收件箱别名可解析：给定一个 collection 键带imap命名空间的存储，运行带-m INBOX的命令（或未指定邮箱而配置了mailbox.alias.inbox = "INBOX"）时，列出的是imap/INBOX；
• 未知邮箱会说明现状：同一存储上运行-m Nope，命令失败，并列出账户持有的全部邮箱，不产生任何空结果。

读路径：可用性感知的缓存读取

“pimdir 是可能不完整的缓存”这一事实被显式编码进读路径（src/pimdir/mod.rs 模块注释）：

• 信封只由存储的 mail summary 构建，不读正文，因此一个正文尚未本地化的条目依然能正常列出；
• get_message对level < Full、无存储对象的条目返回明确的“body not fetched”状态（“run a sync to hydrate it”），而不是数据丢失类错误——这正是触发同步的提示。对应实现见 src/pimdir/backend.rs：

let Some(hash) = item.object else { bail!("Message `{id}` in `{mailbox}` is not downloaded yet (body not fetched); \ run a sync to hydrate it"); };

短公共 ID 与校验

条目在items.seq上持有存储分配的小整数公共 ID（同一消息在多个邮箱中归档时保持不变），后端将其作为Envelope.id对外展示，而不是内部的长link_id。在读取正文或暂存动作之前，ID 会被校验（非数字或未知 ID 明确报错），parse_id会拒绝非数值输入（src/pimdir/backend.rs）。

写路径：一切先入队，动作由主人执行

五个写动词全部映射为入队的PimdirAction（delta.md）：

动作一律以公共seq寻址，由存储的主人（同步引擎）在下次运行时应用并推送。关键约束有三条：

1. 正文先落盘、动作后入队：add_message/send_message先把正文写入 blob 存储并持久化提交，再由队列行钉住（pin）该对象，之后才入队引用它的动作（src/pimdir/backend.rs）。这样在两者之间没有任何回收会清走正文。
2. SetFlags是全量替换集合：若存储报告的当前标记集合未知（PimdirFlags::Unknown），则以空集合为基底构建已知集合，绝不把未知集合向前传递——未知集合会抹掉同步已知的标记。apply_flag_op的三种操作（Set/Add/Remove）实现及“未知集合上 Add 暂存已知集合”的测试见 src/pimdir/backend.rs 与同文件测试a_flag_op_on_an_unknown_set_stages_a_known_one。
3. pimdir 没有原生垃圾箱：删除即入队Remove，由同步引擎以对应后端自身的处置方式完成。

新消息的 link id 推导

新增消息通过io_pimdir::conventions（SPEC Annex A 的唯一实现）推导 link id、summary 与排序键，并按存储已有的拼写方式书写 link id，使新增消息能与已同步副本去重，而不是二次链接。本地实现derive_link_and_meta与pimdir/hash.rs被删除（tasks.md）。

已知分歧：mid:前缀在接缝处翻译

conventions::derive返回裸的Message-ID作为 link id，而 Neverest 写入的是mid:<id>，且所有已被 Neverest 同步的存储都使用后者（真实存储验证可见"link_id":"mid:1.0.C.0.1DD2C438E0EFF2E.0@mail29243.apostello.io"）。若直接暂存裸形式，会把同一消息链接两次、正文存两份——这正是conventions要消除的失败模式。因此后端在接缝处把 link id 翻译为mid:前缀，并留有一条 NOTE 标注删除该翻译的条件：由 io-pimdir 与 Neverest 哪一方采纳conventions，是它们自己的决定（proposal.md 的 “Known divergence” 一节）。

单账户读取与配置项变更

pimdir.account取代pimdir.source

旧配置pimdir.source随 mutate 路径一并删除——生产者不会把动作归属于某个源，而读者真正需要回答的问题是“展示哪个账户的 collection 集合”（pimdir SPEC §9.2）。新配置项pimdir.account在 src/config.rs 定义：

[pimdir] root = "~/Mail" # 存储目录，含 pimdir.db 与 objects/ account = "..." # 可选；多账户共享存储时指定

• 未设置时自动推导：存储只含一个账户（或一组未分组集合）时按该账户读取；含多个账户时拒绝猜测并报错列出候选，避免展示错误的邮箱集合（src/pimdir/client.rs 的resolve_account）。
• 存储必须已存在：PimdirClient::new会检查pimdir.db，不存在则报错“No pimdir store at …; run a sync to create one”，而不是创建一个空库来掩盖路径写错的问题（src/pimdir/client.rs）。

队列可见性：pimdir queue

暂存的创建/发送动作在主人应用前没有公共 ID，因此不构成信封、在普通列表中无行可显示。为此提供pimdir queue list（别名ls）与pimdir queue cancel两个子命令（src/pimdir/queue/cli.rs）：前者把队列中的创建与发送渲染为邮件（正文由动作钉住的 blob 推导，Add显示其标记，submit意图以已读呈现）；后者是暂存创建唯一的撤回手段，取消本身是一次 owner 写，若同步正在进行会被立即拒绝而非等待（src/pimdir/client.rs）。

验证与测试

该变更在真实账户存储上验证（2026-08-26-pimdir-producer-reader.md）：

• 存储含 8824 个条目、2.3 GiB blob；mailbox list以裸名列出全部 16 个邮箱；-m INBOX与别名均可列出；未知邮箱报错并列出这 16 个；message read从 blob 渲染正文；
• 写路径在索引的临时副本上驱动：flag add暂存set-flags seq 5005 -> [\Flagged \Seen]（保留已有标记）；message move与message delete暂存move seq N -> imap/Trash（目标重新带命名空间）；message save把 blob 写入分片路径并入队add link mid:staged@himalaya, object aw64hcc…；
• 116 个测试全绿，fmt 与 clippy 干净。

相关测试覆盖：信封从 summary 无正文构建、同一Message-ID的两个条目投影出两个公共 ID、未读取的未知标记集渲染为空标记而非崩溃、flag 三种操作的集合运算、submit载荷（v/object/from/rcpts/subject）的结构化输出，以及无邮箱/无收件人的发送不产生任何暂存（src/pimdir/backend.rs）。

小结

这次pimdir-producer-reader变更把 Himalaya 的 pimdir 后端从“误当仓库主人”的角色中彻底解放出来：读走无锁只读路径、对未水合的正文给出可操作的提示；写全部降级为按公共seq入队的PimdirAction，正文先落盘并由队列行钉住，交给同步引擎在下次运行时应用。邮箱名按服务器命名展示与解析，pimdir.account与pimdir.namespace分别解决多账户归属与命名空间推导问题，而mid:前缀翻译则守住与既有 Neverest 存储的去重边界。对使用者而言，理解这套读者-生产者模型，就能安全地在同步进行中读写 pimdir 缓存，并正确解读body not fetched与pimdir queue这两个新出现的界面。

• CLI