14.7 KB · updated 2026-07-06 · md

v0.5.0.zh.md

docs/i18n/release-notes/v0.5.0.zh.md

Tesserae v0.5.0 — 引擎骨架与按需上下文编译器

<!-- translations:start -->

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

<!-- translations:end -->

发布于 2026-06-06 · PyPI · GitHub release · pip install --upgrade tesserae==0.5.0

Tesserae 0.5.0 是本项目成为其使命所描述的上下文引擎的版本。它交付引擎骨架 —— 流水线编排器、监督守护进程与实时会话监控器 —— 以及支柱 3 的头条功能：按需上下文编译器，它把"给我关于 X 的上下文"变成一个量身定制、带引用、可直接交给智能体的捆绑包。在底层，自我改进各阶段现在经由 node_memory 边车被激活并持久化（输出中呈现数值化复现置信度、supersede 默认开启），真正的默认嵌入取代了哈希桶桩（轨道 B），增量编译基础设施落地但保持标志 OFF/实验性。沿途发现的两个真实编译缺陷被修复（仅变更幂等性、注入存储契约），测试套件达到 1544 通过 / 0 失败。这是交付上下文引擎路线图阶段 0–6 的版本。

目录：

  1. 按需上下文编译器 —— MD0（支柱 3，头条）
  2. 引擎骨架 —— 编排器、守护进程、实时会话监控器
  3. 被激活并持久化的自我改进（MD0 边车）
  4. 真正的默认嵌入（轨道 B）
  5. 增量编译基础设施（标志 OFF）+ 两个编译修复
  6. 从 v0.4.0 升级
  7. 战略背景

1. 按需上下文编译器 —— compile_context（支柱 3，头条）

是什么

整张路线图所指向的特性：一个查询（或一组种子节点）进，一个量身定制、带引用、可直接交给智能体的上下文捆绑包出。 compile_context 是一个纯函数 —— 它读取图并返回内存中的 ContextBundle，不向磁盘写入任何东西。流水线是：查询/种子 → 为种子做 PPR + 混合检索 → 深度受限的 k 跳邻域遍历 → 组装相关维基正文 → 可选 LLM 综合（带优雅的确定性回退）→ 带词边界截断标记的预算控制。每个有贡献的节点都被记录为一个 ContextCitation，因此捆绑包的引用都能解析回真实的图节点。

类型角色
`compile_context(query \seeds, depth, budget, …)`纯入口；返回一个 ContextBundle。
ContextBundle组装好的上下文及其引用列表。
ContextCitation一个可解析的引用（节点 id → 贡献正文）。

编译器以三种方式暴露：

  • MCP 工具 compile_context —— 供智能体在对话中调用。budget=0 表示不设上限。
  • CLI tesserae project context —— exit-0 / stdout / --output / 确定性，用于脚本与流水线。
  • 主题范围导出 —— slice_export_context_for_topic 产出一个主题范围的 llms.txt 切片，智能体 harness 简报现在经由 compile_context 按主题渲染（模式 4 + 模式 6），而不是硬编码的前 12 个。

两项相关检索升级随之而来：node_context 获得一条 use_ppr 排序路径（带抑制感知的邻居填充和边/上限控制），主题切片使用规范维基 slug，使引用与导出对齐。

使用方法

# CLI：为某主题编译一份带引用的上下文文档，打印到 stdout 或文件
tesserae project context "检索排序与 RRF 融合"
tesserae project context "检索排序" --output ./context-retrieval.md

从 MCP 客户端：

{
  "tool": "compile_context",
  "arguments": {
    "query": "我们的检索栈如何对候选排序？",
    "depth": 2,
    "budget": 4000
  }
}
// → 返回一个 ContextBundle：组装好的正文 + 一个可解析引用列表。
//   budget: 0 表示不设上限。

当你已知锚点时，也可以直接从节点 id 播种（跳过检索步骤）：

{
  "tool": "compile_context",
  "arguments": {
    "seeds": ["decision-2026-05-22-switch-to-rrf-fusion"],
    "depth": 2,
    "budget": 0
  }
}

何时使用

  • 智能体需要对单一主题的聚焦简报，而不是整语料 llms.txt 转储或单个 wiki_page 正文。
  • 你想要可解析的引用 —— 捆绑包中的每个论断都能追溯回一个图节点 —— 以便智能体跟进。
  • 你在脚本化一次交接，想要一个确定性的上下文工件（--output、无 LLM 组装模式），并按主题重新生成。

位于何处

核心实现：MD0（compile_context、ContextBundle、ContextCitation）。MCP 注册与分派：tesserae/mcp_server.py。CLI 接线：tesserae/cli.py 中的 context 子解析器与 _handle_context。主题范围的 harness/导出渲染经由 compile_context 路由。

注意事项

  • 综合质量取决于 LLM 后端；没有后端时，编译器回退到确定性组装（仍带引用，只是未综合）。回退是优雅的 —— 综合失败绝不会中止捆绑包。
  • k 跳遍历是深度受限的，PPR 在深度受限的子图上运行；非常大的图受益于紧凑的 depth 加一个真实的 budget，而非 budget=0。
  • 预算截断在词边界处切断并附加截断标记，因此被裁剪的捆绑包仍可读，而不会在 token 中途结束。

2. 引擎骨架 —— 编排器、守护进程、实时会话监控器

是什么

审计称为最大差距的三个基础部件，现在已在 tesserae/engine/ 下发布：

  • 流水线编排器（pipeline.py）—— ingest → compile → project → publish 链条，从斜杠命令 markdown 技能中提升为一个一等的进程内对象，供守护进程、CLI 与 MCP 共同调用。这是一切持续之物所依附的共享代码路径。
  • 监督守护进程（daemon.py）—— 一个受监督的长运行进程，拥有单一事件循环，把触发突发合并为单次流水线运行，处理优雅的 SIGTERM / SIGINT 关闭，并在流水线异常时不死掉而存活。
  • 实时会话监控器（session_tail.py）—— 跟踪实时 harness 转录，在会话运行时摄取轮次，取代事后的 sessions discover --import 扫描（支柱 1）。

三者结合，把 Tesserae 从一次性批处理 CLI 变成一个可以持续监视并摄取的进程。

何时使用

  • 你想要"持续更新"属性 —— 会话与编辑无需手动命令即可流入图。
  • 你在 Tesserae 之上构建，想要供守护进程、CLI 与 MCP 使用的一个共享流水线入口，而不是重新实现刷新链。

位于何处

tesserae/engine/pipeline.py、tesserae/engine/daemon.py、tesserae/engine/session_tail.py（作为引擎骨架合并，路线图阶段 0–2）。

3. 被激活并持久化的自我改进（node_memory 边车）

是什么

"自我改进基础"支柱从附加阶段转为一个持久化的 node_memory 边车（tesserae/memory/）。两项用户可见的变更：

  • 带确定性判定的 supersede 默认开启。 supersede 阶段现在默认运行（无需 TESSERAE_SUPERSEDE_PASS=true），带有双向确定且果断的会话 id 判定与阈值守卫，外加下游抑制，使被取代的事实从上下文输出中消失，而不仅仅是获得一条边。
  • 输出中呈现数值化复现置信度。 复现洞见强化现在从跨会话频率产出一个数值置信度，经由 memory_by_id 注入 TemporalFactProjector，取代此前粗糙的字符串启发式。跨会话重申一个事实会在输出中可度量地提升其置信度。

何时使用

  • 你运行同一洞见反复出现的多会话项目 —— 强化把那种复现变成智能体可据以排序的置信信号。
  • 你想让过时事实从编译后的上下文中消失，而不仅仅被标记。

位于何处

tesserae/memory/ —— store.py、reinforce.py（数值化复现置信度）、supersede.py（默认开启、确定性判定 + 抑制），外加 decay.py、contradiction.py 与 insight_symbol_link.py。自我改进测试套件（此前为零测试）现在覆盖确定性、幂等性与 LLM 覆盖路径。

注意事项

  • 衰减与矛盾的脚手架随同一边车发布；v0.5.0 面向用户的默认开启行为是 supersede + 数值化复现置信度。

4. 真正的默认嵌入（轨道 B）

是什么

默认"语义"通道不再是确定性哈希桶伪嵌入。v0.5.0 交付一个真正的 Model2VecBackend，并让 active_embedding_backend 在失败时明确报错，而不是静默降级到 blake2b。在用的语义后端在 embedding_status 中呈现，一个余弦下限让嵌入通道纳入候选（而不仅是重排），从而让改写与同义词查询浮现出 BM25 错过的节点。

使用方法

{ "tool": "embedding_status" }
// → 报告哪个语义后端在用（真实 vs 回退），从而你能一眼看出
//   开箱即用的检索是否真正语义。

位于何处

tesserae/retrieval/hybrid.py（后端选择、失败即明确报错的 active_embedding_backend、用于仅嵌入纳入的余弦下限）与 Model2VecBackend。经由 embedding_status MCP 工具呈现。

注意事项

  • 如果真实后端无法加载，检索现在会大声报告，而不是假装哈希桩是语义的 —— 这是预期的行为变更。

5. 增量编译基础设施（标志 OFF）+ 两个编译修复

是什么

经 GraphStore 端口的设计型增量层作为基础设施落地：出处边车、GraphStore 删除接口、全量时对账、边感知就绪性、生产者出处管路，以及持久化的 url_resolver 异步运行时（不再每次调用 asyncio.run）。对全量编译的字节对等已在已覆盖路径（重命名、别名同一性、两端点移动对等门）上被证明。

incremental_compile 标志保持 OFF/实验性。 Codex 审查揭示了多所有者/生产者生命周期/上限回退缺口，因此该标志在那些缺口闭合前对已覆盖路径而言是选择开启且字节对等已证。

此项工作中揭示的两个真实编译缺陷在默认路径中被修复：

  • 仅变更幂等性 —— compile 现在尊重仅变更幂等性，使空操作重新编译不搅动图。
  • 注入存储契约 —— 项目编译中的注入存储契约被尊重，修复了直接摄取路径上的一类失败。

位于何处

增量基础设施跨越 GraphStore 端口与出处边车；两个修复落在项目编译路径（fix(project): honor changed-only idempotence + injected-store contract in compile）。

注意事项

  • 暂勿对生产图开启 incremental_compile —— 在多所有者/生命周期/上限回退缺口闭合前，它按设计是实验性的。全量编译仍是受信路径。

从 v0.4.0 升级

pip install --upgrade tesserae==0.5.0

对既有工作流而言，v0.5.0 是增量的 —— tesserae project compile 仍与从前完全一致，现在带两项正确性修复（仅变更幂等性、注入存储契约）。新界面为选择调用：

新的按需上下文编译器：

tesserae project context "<主题>"            # 把带引用的上下文捆绑包打到 stdout
tesserae project context "<主题>" --output out.md
{ "tool": "compile_context", "arguments": { "query": "<主题>", "depth": 2, "budget": 4000 } }

现在默认开启的行为（此前为选择开启或缺失）：

  • supersede 阶段默认开启（带对被取代事实的输出抑制）。
  • 在投影输出中呈现的数值化复现置信度。
  • 带失败即明确报错后端的真正默认嵌入（无静默哈希桩降级）。

仍为实验性 —— 对生产图请关闭：

  • incremental_compile（基础设施已发布，标志 OFF）。

其余一切 —— graph_ppr、混合 search_nodes、sync-code、research、实时 hook、embedding_status、fresh_insights、schema-drift、斜杠命令、维基 / Obsidian 投影 —— 自 v0.4.0 起承袭。

战略背景

上下文引擎审计（2026-06-02）用一句话点明了差距：Tesserae 曾是一个*机械上健康、测试充分的批处理 CLI 编译器*，在三大支柱上都是手动触发且事后的，而最大的缺失部件是一个拥有单一事件循环的长运行监督进程。v0.5.0 闭合了那一句。引擎骨架就是那个监督进程；实时会话监控器使支柱 1 由事后转为实时；node_memory 边车使支柱 2 原地自我改进；而按需上下文编译器就是支柱 3 —— 把类型化图、库与站点从静态投影变成按需的、查询范围的、带引用的、可直接交给智能体的输出的头条功能。

我们调查的 2026 年 PKM-AI 版图中没有工具能做这套组合。Cursor Memories、Claude CLAUDE.md、Cline memory-bank 与 Aider CONVENTIONS.md 都是没有引擎循环、没有类型化自我改进、也没有按需带引用上下文编译器的静态文本袋。Microsoft GraphRAG 有类型化实体与社区摘要，但它是一个语料-RAG 系统，而非持续运行的项目记忆引擎。v0.5.0 交付了让基础保持新鲜的循环，以及把智能体所求的恰当上下文交给它的编译器 —— 即 AGENTS.md 中明白陈述的使命，如今在代码中运行。

剩下的：阶段 7 —— 把 serve + watch + deploy 统一到监督进程之下以实现持续发布，并在增量编译标志的剩余缺口闭合后将其开启。骨架与头条已就位，收敛版本是下一步。

另见：