Tesserae v0.28.3 — 提取器的单轮上限，以及它悄悄付出的代价

<!-- translations:start -->

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

<!-- translations:end -->

Released 2026-07-31 · PyPI · GitHub release · pip install --upgrade tesserae==0.28.3

只是一个参数。它自第一次流水线提交起就存在于 Claude 提取器中，在配置了 MCP 服务器的 机器上，它让 LLM 提取完全无法工作——却不会让编译失败。

--max-turns 1 从来不是一个决定

两处 Claude CLI 调用点都在执行：

claude -p --output-format text --max-turns 1

--max-turns 统计的是工具调用，而不是回复。如果 CLI 的配置目录里有 MCP 服务器或 钩子，模型的第一个动作可能就是一次工具调用——那唯一的一轮就此耗尽。CLI 随即以 Reached max turns (1) 退出 1，连一个字节的 JSON 都没有输出。

Tesserae 捕获了这个错误并回退到确定性提取，因为提供方故障不应中止整个编译。于是 编译成功了，图看起来也合情合理，而 LLM 什么都没贡献。

这个参数从未被选择过。它随最初的流水线提交进入代码，三个月后 ClaudeCLIJsonClient 原样照抄，因为它的 docstring 写着"沿用 run_claude_cli 的 模式"。没有任何一条提交信息提到过它。

--strict-mcp-config 才是"一次性调用"的真正含义

轮次上限的本意是"只回答一次，不要跑智能体循环"。表达这一点的正确方式是不加载任何 MCP 服务器，这样就没有工具可以消耗轮次：

claude -p --output-format text --strict-mcp-config

模型的第一次回复就是答案，已配置的 MCP 服务器再也不会把这次调用饿死。两处调用点均 已修复，并有回归测试断言轮次上限不会在任何一处回归。

检查它是否让你损失了一张图

这个故障在编译摘要里是看不见的，它只存在于日志中：

grep -c 'Reached max turns' <你的编译日志>

只要大于零，就说明那些文件是被确定性提取的，在此版本上重新编译即可恢复。在本项目 自己的图上，恢复真正的 LLM 提取后，节点数从 5,155 增至 13,182——确定性回退此前一直 在吞掉大约 60% 的图。

编译在大部分文件都丢失 LLM 提取的情况下仍报告成功，这是另一个独立缺陷，记录在 #92，本次未修复。本次发布 只是移除了静默回退的一个成因，而非那份静默本身。

从 v0.28.2 升级

直接替换即可。没有 API、模式或配置变更。如果你之前的编译受到影响，重新编译即可拿回 缺失的提取——~/.tesserae/llm_cache 中缓存的 LLM 响应会被复用，因此只有当初回退的 文件才需要花费。