调优参考 — 环境变量

<!-- translations:start -->

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

<!-- translations:end -->

Tesserae 从环境读取的每个旋钮、其默认值及实际何时更改它。 这里的任何内容都不是必需的：默认值的选择使得普通的 tesserae compile 能够正确运行。

项目和全局配置（.tesserae/config.json、~/.tesserae/config.json） 对 LLM 后端设置优先；下面的环境变量在设置的运行中优先于两者。

花钱的钩子

Claude Code 插件附带可以后台编译的钩子。任何花钱的默认关闭：

export TESSERAE_HOOK_AUTOCOMPILE=1   # 选择性加入自动重新编译

受限：posttooluse-edit.sh（在每次 Edit/Write 上触发）和 session-end.sh。不受限，因为它们花费零：session-start.sh 运行 tesserae code sync，这是确定性的，pretooluse-compile.sh 仅拦截您自己输入的 tesserae compile。

这个默认值之所以存在是因为替代方案已经过测量。位于 ~/.tesserae 的知识库使 $HOME 看起来像一个项目根目录，钩子解析器从工作目录向上走到它找到的第一个 .tesserae/ — 因此任何在已注册项目外启动的会话都会解析为 $HOME 并编译整个主目录：15k 个文件，一个 795 MB 的图，~10 小时的 LLM 花费，来自一个比启动它的会话存活时间更长的分离进程。

resolve_project_root() 现在通过任一路径拒绝 $HOME，并返回空值而不是回退到工作目录，因此调用者不执行任何操作而不是猜测。后台运行模型工作的钩子应该被刻意打开，而不是在账单到达后关闭。

提取

TESSERAE_EXTRACT_TIMEOUT

默认 1800（秒），每次尝试。 限制每个 codex/claude 提取 调用，以便 wedged CLI 子进程无法挂起编译。

这是真实发生的：一次编译在 0% CPU 下观察到 5 h 43 m 后面跟着一个空闲 4 h 6 m 的 codex exec 子进程，一直持有 .tesserae/compile.lock。 它已经在内存中构建了 32 个社区摘要，但从未持久化它们。

每次尝试，不是每个文档——超时后客户端轮换到下一个 CODEX_HOME / claude 配置目录，所以一个文档的最坏情况是 timeout × 配置的配置文件。

export TESSERAE_EXTRACT_TIMEOUT=3600   # 为非常大的文档提供更多空间
export TESSERAE_EXTRACT_TIMEOUT=0      # 无截断——运行至完成

设置但无法使用的值（10m、600s、负数、inf）会在 stderr 上警告 并保持默认值。拼写错误不得以静默方式禁用安全阀。

TESSERAE_EXTRACT_CONCURRENCY

默认 4。 并行提取的文档。每个都是一个阻塞 CLI 子进程，大约需要一分钟，所以顺序循环使得挂钟时间 是每个模型往返时间的总和——对 161 个文档测量为 ~2 h 40 m。

上限是提供商账户的速率限制，而不是您的机器，这就是为什么 默认值很低。设置 1 以实现严格的顺序行为。

并发永远不会改变输出：工作列表按路径顺序固定， 结果按索引收集，因此并行运行与 顺序运行字节相同。

TESSERAE_LLM_CACHE

默认打开。 CLI 提供商响应的内容寻址缓存，位于 ~/.tesserae/llm_cache 下，由（文档、种类、指导）以及模型和 推理努力进行键控——因此切换模型会重新询问而不是服用先前 模型的答案。只存储可解析的响应，因此一个不良生成 无法成为永久的。

export TESSERAE_LLM_CACHE=0   # 始终重新询问

TESSERAE_LLM_CHUNK_CHARS

当文档太大而无法进行一次调用时，每个块的字符数。除非您 在达到上下文限制，否则保持未设置。

LLM 后端

tesserae config status 打印解析后的后端并对其进行活性检测。

编译通道

关于社区摘要： 编译通道急切地覆盖最粗粒度； graph_map 另外在您第一次下降到冷作用域时懒惰地具体化一个摘要， 按级别缓存。关闭通道是合法的成本策略——您只为 实际访问的分支付费——但有一个警告： 联合下降永远不会懒惰地具体化。 兄弟项目的卡片只能 从其在图内摘要或已热缓存中命名，所以跨项目导航的项目 需要打开急切通道。

查询和综合

路径和基础设施

恢复降级的语料库

当文档提取失败时，它由确定性基线服用和 在 .tesserae/manifest.json 中标记。没有标记，它无法 与干净提取区分，所以 --changed-only 会永远跳过它， 降级将是永久的，直到文件自身内容改变。

tesserae compile --changed-only --retry-fallbacks

仅重新尝试标记的文档；干净的保持跳过。

检查层次结构

tesserae graph-map                          # 根地图
tesserae graph-map --scope <scope_id>       # 下降
tesserae graph-map --scope '<alias>::'      # 兄弟注册项目

每张卡从层次结构 sidecar 报告 size 和 leaf_member_count， 加上 live_member_count——*当前*图实际携带的成员数。 一个 0 那里意味着作用域是死的（sidecar/图 skew）：跳过它 而不是下降。

代理写入图表

\graph_write\ (MCP) 采用模式验证的类型化节点和边，带有强制性出处，因此代理将发现记录为*结构*，而不是提取器必须猜测类型的散文。

它拒绝而不是强制：无类型边、受控词汇外的节点或边类型、悬空端点和缺少出处的写入都被拒绝。重复写入是幂等的。代理写入的节点可以存活完整重新编译、删除的 \graph.json\、\--limit\ 和完整语料库删除。

对照图验证声明

\verify_claim\ (MCP) 回答图是否许可三元组。它接受 \(subject, predicate, object)\ — 没有自然语言参数，设计上出于这个原因，因为解析器使前一个版本对它所支持的声明的否定回答 SUPPORTED。

判定是图字节的纯函数：没有 LLM、没有嵌入、决策路径上没有模糊匹配。

它故意不会做两件事。它从不将 \supersedes\ 视为驳斥 — 该关系说一个*节点*被替换，而不是说三元组为假。代理写入只能*削弱*出处类，永远不能升级，所以代理声称的任何东西都不能呈现为文件接地。

值得在阅读结果时了解：在一个有 15,284 条边的真实图上，约 40% 的 \SUPPORTED\ 判定是同义反复 — \evidenced_by\ 边其引用的跨度是边自身的目标。真的，但无信息。

路由问题

\tesserae ask\ 根据问题形状选择检索路径：单实体查询去廉价后端，多跳 / "什么变了" / "为什么" / 语料库范围问题去图。独立基准表明图在多跳、时间和合成问题上领先，在简单事实查询和成本上*落后* — 所以为每个问题支付图价格是亏损。

决定出现在返回的信封中，因此廉价答案是可审计的。用 CLI 上的 \--route\ 或 MCP 工具上的 \route\ 参数覆盖它。