Tesserae v0.7.2 — 发现与编译不再卡死

<!-- translations:start -->

English · 한국어 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

发布日期 2026-06-12 · PyPI · GitHub release · pip install --upgrade tesserae==0.7.2

这是一个错误修复版本，消除了在拥有大量代理会话历史的机器上 Tesserae 可能停滞的三种途径：永不返回的会话发现、超时后永久卡死的 CLI 代理子进程，以及堆叠在同一项目状态上的并发编译。

1. tesserae sessions discover 能正常返回了 — 即使有几十 GB 的历史

此前的发现流程会在过滤之前对每个账户根目录下所有项目的全部转录文件做完整 JSON 解析。在一台拥有约 57 GB Claude Code / Codex 历史的机器上，这意味着命令实际上永远不会返回。

三项修复相乘生效：

• 标记预过滤 — 转录文件只有在文件中逐字出现项目路径时才可能属于当前项目，因此其他项目的转录现在先经过原始字节扫描（比解析快约 50 倍）筛除，无需任何 JSON 处理。
• 符号链接的账户根目录去重 — ~/.claude 指向 ~/.claude-personal1 不再导致每个转录被扫描两次。
• 基于 mtime 的扫描缓存 — 筛查结果持久化在 ~/.cache/tesserae/discovery_scan.sqlite（可用 TESSERAE_DISCOVERY_CACHE 覆盖），重复运行时只重新读取新增或已变更的转录。

在问题机器上的实测：永不返回 → 冷启动 3 分 16 秒 → 热启动 1 分 26 秒，找到 4,048 个会话。tesserae refresh 和会话导入走同一路径，同样提速。

2. CLI 代理超时不再卡死编译

codex exec / claude -p 调用使用 subprocess.run(capture_output=True, timeout=...)，它在超时后只杀死直接子进程，然后不带超时地排空输出管道。代理 CLI 会派生继承这些管道的自有子进程，因此一次超时可能让编译在孤儿孙进程后面以 0% CPU 无限期阻塞（实际观测：约 2 天）。

现在 LLM CLI 调用在自己的进程组中运行，超时会杀死整个进程组并在限定时间内排空 — 超时永远意味着已终止，绝不再是卡死。

3. 每个项目同时只允许一个编译

ProjectWiki.compile 现在对 .tesserae/compile.lock 持有独占锁。当编译已在运行时，由钩子触发的 refresh 会立即失败，并给出指明持锁进程 pid 的清晰消息，而不是悄悄堆叠到同一 .tesserae 状态上。设置 TESSERAE_COMPILE_LOCK_WAIT=<秒> 可改为等待锁。锁基于 flock(2)，因此编译崩溃也不会留下陈旧的锁。

4. tesserae --version

根帮助现在以已安装版本开头，tesserae --version（也可用 -V / version）直接打印版本号。

从 v0.7.1 升级

直接替换即可，无需修改配置。升级后第一次 sessions discover / refresh 会支付一次性的筛查成本以填充扫描缓存；之后的运行都很快。