21.9 KB · updated 2026-07-06 · md

v0.2.0.zh.md

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

Tesserae v0.2.0 — 类型化检索、代码图谱、本体演化

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

发布于 2026-05-21 · PyPI · GitHub release · pip install --upgrade tesserae

Tesserae 0.2.0 是 v0.1.0 系列之上的首个特性版本，带来了 六项叠加式新特性，且不引入任何破坏性变更。本次发布把 Tesserae 的检索能力从「类型化图谱之上的 BM25」推进到 HippoRAG-2 风格的混合检索器（Personalized PageRank 种子扩展），奠定了「代码即图谱」的基础——将散文式洞见与源码符号关联起来，并新增两项本体演化处理（社区摘要与记忆衰减）以及一份 schema-drift 报告。这些特性对应用户工作流中的三个环节：在*查询时*获得更高召回（graph_ppr、混合 search_nodes），在*编译时*获得更丰富的节点（ingest-code、社区摘要、衰减/supersedes），以及对本体本身更快速的*迭代循环*（schema-drift）。

MD0 — 在类型化图谱上运行 Personalized PageRank
混合 MD0 — 通过 RRF 融合 BM25 + 词法 + 向量
MD0 — Python AST → 类型化代码图谱
社区摘要 — Louvain + LLM（可选启用）
衰减打分 + MD0 + MD1
MD0 — EDC 枚举建议
从 v0.1.0 升级
战略背景

1. `graph_ppr` — 在类型化图谱上运行 Personalized PageRank

是什么

一个全新的 MCP 工具，在一个或多个种子节点 ID 上运行 Personalized PageRank（个性化 PageRank，简称 PPR），按平稳分布质量返回相关性最高的 top-k 节点。该游走过程感知边的类型：边的权重由其关系类型决定，默认配置会对在 Tesserae 图谱中携带最多「真实」信号的四种边类型加权——derived_from_session、discussed_in、references 和 supersedes。这与 HippoRAG 2 使用的多跳种子扩展原语相同，只不过针对 Tesserae 的类型化边而非段落级共现图进行了适配。

具体来说，graph_ppr 以一种 BFS 或 BM25 都做不到的方式回答这样一个问题：「按照我真正关心的关系加权，这个节点的邻域究竟是什么样？」。一个 Decision 种子会拉入产生它的会话、它所回答的问题、它取代的文档，以及那些文档所讨论的概念——即便这些节点之间没有共享任何关键词。

如何使用

启动 Tesserae MCP 服务器后，工具会自动注册。从任意 MCP 客户端：

// 单节点种子，默认 α=0.15，返回 top-10
{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_id": "decision-2026-05-12-switch-to-hybrid-retrieval",
    "top_k": 10
  }
}

// 多节点种子（一个「概念簇」），自定义 α + 边权重
{
  "tool": "graph_ppr",
  "arguments": {
    "seed_node_ids": ["concept-rrf", "concept-bm25", "concept-embedding-fusion"],
    "top_k": 25,
    "alpha": 0.2,
    "edge_type_weights": {
      "derived_from_session": 3.0,
      "discussed_in": 2.0,
      "references": 1.5,
      "supersedes": 1.5
    }
  }
}

该工具按平稳质量排序返回 {node_id, score, kind, title} 数组。在 Claude Code 会话中，只需告诉 agent「使用 graph_ppr，以 \<node\> 为种子，top-k 15」，using-tesserae skill 就会自动路由该调用。

何时使用

在以下场景考虑使用 graph_ppr：

你已经有一个明确识别的节点（一项决策、一篇论文、一条会话发现），并希望获取其*以图距离衡量的邻域*，而非关键词匹配的兄弟节点。
你需要多跳召回——例如「距离这个概念两到三跳之内、并偏向会话产出发现的所有节点」。
普通的 search_nodes 返回了正确的节点，但通过 references 链接到的上下文过于狭窄。

如果是从一段短语出发的自由文本查询，请优先使用混合 search_nodes（特性 2）；如果是检索某个已知节点的文本上下文，请优先使用 node_context。

代码位置

核心实现：MD0。工具注册：tesserae/mcp_server.py。

注意事项

默认 α=0.15（重启概率）和 50 次迭代上限是针对典型项目记忆图谱（5k–50k 节点）调优的。超大图（>250k 节点）可能需要更低的 α 以及对节点度感知的初始化；这是后续工作。
边权重对称应用；非对称配置（例如让 references 与其反向边权重不同）尚未对外暴露。
实现为纯 Python，且不引入新的运行时依赖；如果你需要在单次会话中调用 graph_ppr 数千次形成热循环，建议在多次调用之间缓存列随机矩阵。

2. 混合 `search_nodes` — 通过 RRF 融合 BM25 + 词法 + 向量

是什么

原有的 search_nodes MCP 工具新增了 mode 参数，底层接入了融合检索器。新的默认值 mode="hybrid" 会并行运行三种检索器——BM25（v0.1.0 基线）、词法（token 重合 / 子串匹配）以及向量（语义相似度）——并通过 Reciprocal Rank Fusion（RRF(d) = Σ 1/(k + rank_i(d))，k=60，即 Cormack 等人 2009 提出的常数）进行融合。这与 Microsoft GraphRAG 的本地搜索以及 LightRAG 混合模式所采用的融合方法一致。

mode 参数接受：

模式	使用的检索器
`hybrid` （默认）	BM25 + 词法 + 向量，通过 RRF 融合
`lexical`	仅词法
`bm25`	仅 BM25
`embedding`	仅向量
`legacy`	v0.1.0 的精确排序——逐位保留

向量后端按以下顺序自动探测：若 sentence-transformers 可导入，则加载 sentence-transformers/all-MiniLM-L6-v2（384 维，约 80MB，MIT 许可，首次下载后无需联网）。否则回退到确定性的 hash-bucket 投影——可用、零依赖、可复现，但语义召回较弱。

新增配套 MCP 工具 embedding_status 会报告当前激活的后端，方便你确认混合得分是来自真实向量还是 hash-bucket 回退方案。

如何使用

// 新默认 —— 融合，返回 top 10
{
  "tool": "search_nodes",
  "arguments": { "query": "RRF fusion constant choice", "top_k": 10 }
}

// 为消融实验强制使用单一检索器
{ "tool": "search_nodes", "arguments": { "query": "RRF fusion", "mode": "bm25" } }

// 逐位回退到 v0.1.0 行为
{ "tool": "search_nodes", "arguments": { "query": "RRF fusion", "mode": "legacy" } }

// 查看当前激活的向量后端
{ "tool": "embedding_status", "arguments": {} }

要使用真正的 sentence-transformers 后端而非 hash-bucket 回退：

pip install 'sentence-transformers>=2.7'
# 首次调用会下载 MiniLM 权重（约 80MB）到 HF 缓存；后续调用离线即可。

各模式的使用时机

默认情况下一律使用 hybrid。RRF 对某个检索器返回垃圾结果具有鲁棒性，因为排名倒数衰减能限制单一检索器的贡献上限。
当查询本质上是标签或结构化 slug（concept-rrf、decision-2026-05-12-…）时使用 bm25——精确匹配占主导，向量反而带来噪声。
当查询是改写或问句、且匹配节点使用截然不同的词汇时使用 embedding。
在与 v0.1.0 基线进行消融对比时使用 legacy，也可作为出现单点回归时的逃生口。

代码位置

核心实现：MD0。

注意事项

hash-bucket 回退方案可复现，但对改写句的语义召回有限——embedding_status 会让这一选择显而易见。
当前 RRF 常数固定为 60；如需测试其他取值，将其改为按调用可配置只是一个小型后续工作。
向量缓存按进程隔离；持久化向量存储（Lance / SQLite-vec）是 v0.3 的候选方向。

3. `tesserae project ingest-code` — Python AST → 类型化代码图谱

是什么

一个全新的 CLI 子命令，使用标准库 ast 模块遍历 Python 仓库，铸造 五种类型化节点 与 五种边：

节点	边
`CODE_FILE`、`CODE_MODULE`、`CODE_CLASS`、`CODE_FUNCTION`、`CODE_METHOD`	`contains`、`calls`、`imports`、`inherits_from`、`declared_in`

结果会持久化到 .tesserae/code-graph.json，并由下一次 tesserae project compile 摄入，使得代码符号成为一等公民的图节点：可以从散文中链接到它们、通过 search_nodes 检索、通过 graph_ppr 扩展，并与概念、论文一起可视化。这为*将决策与实现它们的符号关联起来*奠定了基础——这正是当前其他 PKM-AI 工具尚未填补的切入点。

如何使用

# 在已激活的 Tesserae 项目中
tesserae project ingest-code

# 或针对任意根目录
tesserae project ingest-code --root ./my-package

# 然后一次普通的 compile 即可拾取新的 code-graph.json
tesserae project compile

下次 compile 之后，代码节点即可被检索：

tesserae ask "Where is the RRF fusion implemented?"

……agent 也可以通过 references / declared_in 边，从一个散文 Decision 节点游走到实现它的 CODE_FUNCTION。

何时使用

你希望决策与发现链接到它们讨论的真实符号，而不仅是提到这些符号的 README。
你希望获得代码感知检索，又不想另外搭建一套代码搜索索引——同一套 search_nodes + graph_ppr 工具如今就同时覆盖了散文与代码。
你正在使用 Understand-Anything 集成，但希望有一份*更轻量*、零依赖的代码图谱，存在于主 Tesserae 图谱内而非附属 JSON 中。

代码位置

核心实现：MD0。

注意事项

v0.2.0 仅支持 Python。提取器在结构上为后续添加各语言遍历器留好了空间；TypeScript / Rust / Go 列入 v0.3 路线图。
calls 边通过在同一模块作用域内按名称查找进行解析；跨模块调用使用 import 别名解析，但不会做完整的类型推断。对于大量重载的名称会出现中等程度的误报——用于检索没问题，但不适合用于重构。
装饰器会记录在被装饰节点的属性上，但（目前）不会铸造独立的边类型。

4. 社区摘要 — Louvain + LLM（可选启用）

是什么

一个可选启用的编译后处理过程：先对类型化图谱运行 Louvain 社区检测，再让 LLM 为每个规模 ≥ 4 的社区生成一段摘要。每条摘要会被实体化为一个 COMMUNITY_SUMMARY 节点，通过 summarizes 边链接到其成员，并按成员 ID 列表的 SHA 做缓存——这样一次 re-compile 只会对成员实际发生变化的社区重新摘要。这与 Microsoft GraphRAG 用于在查询时呈现「这个簇大致讲什么？」的模式如出一辙。

新增 MCP 工具 list_communities(min_size, limit) 会按成员数排序返回社区摘要节点，方便你不加载完整图谱就浏览其宏观结构。

如何使用

通过环境变量启用，然后编译：

export TESSERAE_COMMUNITY_SUMMARIES=true
tesserae project compile

之后即可查询生成的摘要：

{ "tool": "list_communities", "arguments": { "min_size": 5, "limit": 20 } }

也可以通过 node_context 沿着某个社区摘要节点的 summarizes 边回溯到其成员。

何时启用

你的图谱处于中到大规模（>500 节点是大致经验值），希望获得*簇级别的目录*。
你希望让 LLM 撰写的簇标签附着到静态站点图视图的配色分组上。
你在定期产出（周报 / 月报）摘要，并希望「宏观结构」段落只在成员实际变动时才更新。

如果图谱很小（单项目 README + 少量文档），结构化的 Synthesis 节点已经足以覆盖——此时社区摘要只会增加噪声，而非信号。

代码位置

核心实现：MD0。

注意事项

默认关闭——Louvain + LLM 摘要会增加耗时，且对于社区众多的图谱 LLM 成本不可忽视。缓存会在多次 re-compile 之间摊销这一开销。
社区成员归属在 Louvain 种子之间是非确定性的；该过程在项目内固定了随机种子以确保可复现，但跨项目比较社区 ID 没有意义。
摘要 prompt 是通用版本；按领域定制 prompt 覆盖是计划中的后续工作。

5. 衰减打分 + `supersedes` + `fresh_insights`

是什么

两个互补的原语，均受 A-MEM 艾宾浩斯衰减记忆模型启发：

衰减打分为每个会话发现节点（Insight / Decision / Question / TODO / Hypothesis / Takeaway）按经典遗忘曲线赋予一个连续的 decay_score ∈ (0, 1]：

decay_score = exp(-ln(2) · age_days / half_life)

默认半衰期为 14 天，并且 access_count 的累加（每次该节点被 ask 或 fresh_insights 召回时）会进一步减缓衰减。结构化决策的时间戳从父会话推导得出，从而让回填的发现也能拥有合理的年龄。

supersedes 处理是一个可选启用的编译后步骤：通过 标题 + 内容 shingle 上的 Jaccard 相似度 寻找近似重复的会话发现，再让 LLM 判断较新的是否真的取代了较旧的。确认成立的配对会获得一条 supersedes 边，旧节点的有效 decay_score 会被抑制。

新增 MCP 工具 fresh_insights(limit, kind) 按当前 decay_score 返回排名靠前的发现，排除被取代的节点。这是「agent 应该从过往会话中优先关注什么？」这一查询的规范实现。

如何使用

衰减打分在每次 compile 时自动运行。要启用 supersedes 处理：

export TESSERAE_SUPERSEDE_PASS=true
tesserae project compile

然后查询最新且未被取代的发现：

{
  "tool": "fresh_insights",
  "arguments": { "limit": 15, "kind": "Decision" }
}

或省略 kind，获得跨所有会话发现类型的混合订阅。

何时启用 supersedes 处理

你每周都在累积会话，Decision / Hypothesis 查询开始返回相互矛盾的过时条目。
你希望 agent 的 using-tesserae 召回流程偏向「关于 X 当前的看法是什么」而不是「我们对 X 曾经的所有想法」。
成本可接受：每次 compile 仅需一次 Jaccard 处理（成本低）加上对超过 Jaccard 阈值的候选对的 N 次 LLM 判断调用（按内容哈希缓存）。

如果你只有几周的会话，单靠衰减通常就足够了——supersedes 边是面向更老、更密集图谱的优化手段。

代码位置

衰减打分：MD0
supersedes 处理：MD0

注意事项

14 天的半衰期对于活跃的研究项目是一个合理默认值；长周期的归档图谱可能需要 60–90 天。按节点类型分别配置半衰期表是计划中的 v0.3 特性。
Jaccard 候选生成使用固定的 shingle 大小 5；非常短的发现（一句话的 Takeaway）可能聚类不够紧密。
supersedes 的 LLM 判断按设计偏保守——漏判（漏掉重复）的代价大于误判（错误的 supersedes 边）。

6. `tesserae project schema-drift` — EDC 枚举建议

是什么

一个全新的 CLI 子命令，帮助本体随语料一同演化。它实现了 EDC 模式（Extract-Define-Canonicalize，抽取-定义-规范化，EMNLP'24）：对每种高频节点类型，先以标题+内容 shingle 进行 Jaccard 聚类，再让 LLM 提出 PascalCase 子类型，并附上简短理由和每个簇三条代表性成员预览。输出会写入 .tesserae/schema-drift.md，呈现为可直接复制粘贴到 ontology/ 下本体文件中的枚举增补清单。

LLM 提议以原子方式缓存（先写临时文件再 rename），并以簇成员 ID 的 SHA 为键，所以重复运行成本很低；当语料未变时，结果会收敛到相同的提议。

如何使用

tesserae project schema-drift
# → 写出 .tesserae/schema-drift.md

然后打开报告，审阅提议的枚举（每个代码块都是可复制粘贴的 Python 字面量），将你接受的内容粘贴到 ontology/ 下相关文件中。下一次 tesserae project compile 将基于更新后的 schema 进行校验。

何时使用

在批量新增大量文档 / 会话之后，在将某个新的节点类型值提升为一等枚举之前。
在长期项目上周期性运行（每月），用于发现本体漂移——报告生成速度快且为只读。
作为交接产物：该 markdown 自包含，可以交给评审人（或另一个 agent），无需对方搭建完整的 Tesserae CLI。

代码位置

核心实现：MD0。

注意事项

提议只是*建议*——具体哪些簇要转化为真实的枚举值，仍由人类（或下游 agent）决定。该过程刻意不会自行修改 ontology/。
Jaccard 聚类与 supersedes 处理共享同样的 shingle 大小假设；非常短的成员可能聚类不够锐利。
该过程聚焦于高频类型；稀有类型（≤ 3 个成员）会被跳过，以避免产生臆测性的枚举。

从 v0.1.0 升级

pip install --upgrade tesserae

升级就这么简单——v0.2.0 是纯叠加式，无任何破坏性变更。有几个可选旋钮值得了解：

可选启用处理的环境变量：

# 启用编译后的社区摘要处理（特性 4）
export TESSERAE_COMMUNITY_SUMMARIES=true

# 启用 supersedes 近似重复处理（特性 5）
export TESSERAE_SUPERSEDE_PASS=true

唯一需要了解的 MCP 接口变化：search_nodes 现在的默认值为 mode="hybrid"。如果你有依赖 v0.1.0 精确排序的自动化流程，请传入 mode="legacy"——legacy 路径已逐位保留。

新的、可选的 Python 依赖，用于启用真实向量后端：

pip install 'sentence-transformers>=2.7'

如果跳过该步骤，search_nodes mode="hybrid" 仍然可以工作（hash-bucket 回退）；embedding_status 会报告 hash-bucket 而非 minilm-l6-v2，从而让这一选择可观测。

需要纳入肌肉记忆的新 CLI 子命令：

tesserae project ingest-code      # 铸造代码节点（特性 3）
tesserae project schema-drift     # 提议本体枚举（特性 6）

agent 现在可用的新 MCP 工具：

graph_ppr（特性 1）
embedding_status（特性 2）
list_communities（特性 4）
fresh_insights（特性 5）

其余一切——斜杠命令、hooks、ask、wiki / Obsidian 投影——保持不变。

战略背景

v0.2.0 让 Tesserae 在结构上与 2026 年 GraphRAG / agent 记忆领域的当前最优实践对齐：

混合检索（BM25 + 词法 + 向量，通过 RRF 融合） 与 Microsoft GraphRAG 本地搜索以及 LightRAG 的混合模式所采用的融合方法一致。
Personalized PageRank 种子扩展 是 HippoRAG 2 的核心多跳原语，在这里被改造用于类型化边而非段落共现。
社区摘要 与 Microsoft GraphRAG 的簇摘要层级如出一辙——这一层让「这个语料库总体上讲什么？」这类查询获得快速、结构化的答案。
衰减打分 + supersedes 是将 A-MEM 的艾宾浩斯模型应用到项目记忆；supersedes 处理在精神上更接近 Mem0 的「ADD / UPDATE / DELETE」记忆操作，但以纯粹的边形式表达，而非原地改写。
基于 EDC 的 schema-drift 沿用了 EMNLP'24 的 Extract-Define-Canonicalize 思想，只是把它应用到本体演化而非关系抽取。

Tesserae 自身的、可防御的差异化点依旧明确：全程类型化的边、把会话发现作为一等公民图节点、以及（现在）把代码符号也纳入这同一张图谱。2026 年的竞品大多完全没有类型化边；而在拥有类型化边的少数竞品中，没有任何一家把散文决策与代码符号关联起来——v0.2.0 中奠定的 feat/code-graph 基础，正是这一差异化优势开始复利的起点。

v0.2.0.zh.md

Tesserae v0.2.0 — 类型化检索、代码图谱、本体演化

1. graph_ppr — 在类型化图谱上运行 Personalized PageRank

是什么

如何使用

何时使用

代码位置

注意事项

2. 混合 search_nodes — 通过 RRF 融合 BM25 + 词法 + 向量

是什么

如何使用

各模式的使用时机

代码位置

注意事项

3. tesserae project ingest-code — Python AST → 类型化代码图谱

是什么

如何使用

何时使用

代码位置

注意事项

4. 社区摘要 — Louvain + LLM（可选启用）

是什么

如何使用

何时启用

代码位置

注意事项

5. 衰减打分 + supersedes + fresh_insights

是什么

如何使用

何时启用 supersedes 处理

代码位置

注意事项

6. tesserae project schema-drift — EDC 枚举建议

是什么

如何使用

何时使用

代码位置

注意事项

从 v0.1.0 升级

战略背景

1. `graph_ppr` — 在类型化图谱上运行 Personalized PageRank

2. 混合 `search_nodes` — 通过 RRF 融合 BM25 + 词法 + 向量

3. `tesserae project ingest-code` — Python AST → 类型化代码图谱

5. 衰减打分 + `supersedes` + `fresh_insights`

6. `tesserae project schema-drift` — EDC 枚举建议