.@activegraphai v1.2.0 现已发布 👇

🧩 图投影现在可插拔 🕸️ FalkorDB = 原生边 + Cypher 下推 ⚡ 2跳查询：~8.9s → ~300ms 🧪 一致性测试套件 + 完整 CI 门禁 🤝 社区构建的核心架构

https://t.co/jxGgP3WjFr

Active Graph v1.2.0：图投影变得可插拔

来源：https://activegraph.ai/blog/activegraph-v1-2-0 v1.2.0 使物化图成为一个可插拔的接口，FalkorDB 作为首个外部后端——原生边、Cypher 查询下推、为未来后端准备的一致性测试套件——以及完整测试套件的 CI 门禁和统一许可证。

Active Graph (https://activegraph.ai/) v1.2.0 现已上线 PyPI (https://pypi.org/project/activegraph/)。

此次发布与上一次的起源故事不同。v1.1.0 是一次精心策划的收紧调整。v1.2.0 则来自外部：外部贡献者 @dudizimber (https://github.com/dudizimber) 在一周内提交了四个 issue，随后提交了相应的 pull request。结果自 packs 以来最大的架构新增——物化图投影现在是一个可插拔的接口，FalkorDB 作为首个外部后端。

TL;DR - 新增 GraphStore 接口：选择当前状态图的物化位置。事件日志仍然是真相来源；投影现在是一个可插拔、可丢弃的视图。 - FalkorDBGraphStore 用真实的图数据库支持投影——原生边、Cypher 查询、一个可以在 FalkorDB 浏览器中实际看到的连通图。 - 结构查询下推到数据库。对 20,000 个对象的 2 跳模式匹配从约 8.9 秒降至约 300 毫秒，因为成本现在随结果大小而非图大小扩展。 - GraphStoreConformance 是扩展契约：任何未来的后端都必须通过相同的可执行测试套件。 - 完整测试套件现在作为 CI 门禁，运行于 Python 3.11 + 3.12 矩阵，FalkorDB 和 Postgres 一致性套件执行而非跳过。 - 所有架构决策已锁定在 CONTRACT.md § v1.2 中，且一个许可证——Apache 2.0——现在出现在任何地方，包括网站。

安装或升级：

本次发布的由来

Active Graph 一直将物化图——对象、关系、补丁——保存在进程内存中，每次运行时从事件日志重建。这是正确的默认行为。但这使得一旦运行的当前状态视图变得有趣，三件事就变得困难：无法使用图查询语言查询它，无法跨进程共享它，以及它必须适合堆内存。

事件日志已经为此提供了接口——EventStore，背后有 SQLite 和 Postgres。投影却没有对应的接口。Issue #38 指出了这个空白，第一个 PR 引入了 GraphStore 接口：一个用于投影所在位置的接口，InMemoryGraphStore 作为不变的默认实现，FalkorDBGraphStore 作为第一个外部后端。

使其安全的不变量是：事件日志仍然是真相来源，投影是可丢弃的。清除 GraphStore 不会丢失任何东西——重放日志会重建它。持久性和审计继续由 EventStore 提供。这种不对称性让本次发布的其余部分得以快速推进。

使用 pip install 'activegraph[falkordb]'（服务器客户端）或 pip install 'activegraph[falkordb-embedded]'（嵌入式引擎，Python 3.12+）安装后端。两者都不通过 [all] 拉取——选择图数据库始终是显式的。

关系变为真正的边

第一个 FalkorDB 实现将每个关系存储为携带源/目标属性的独立节点。这保留了一个微妙的 Active Graph 特性——悬挂关系，即关系可以引用尚不存在的对象——但这违背了图数据库的初衷。浏览器渲染了一堆断开的节点云。原生遍历和图算法无法应用。每一跳都是手动属性连接。

Issue #41 指出了这一点，后续的 PR 重新建模了存储。关系现在变成了原生边，具有单一固定关系类型，将关系的种类作为边属性携带：

悬挂关系通过共享的 :AGNode 端点标签存活下来：真实对象是 :AGNode:AGObject，悬挂端点是裸的 :AGNode 占位符，当对象到达时晋升。固定的关系类型还确保每个值都是绑定参数——关系种类永远不会进入查询文本，因此写入路径中没有注入风险。

由于投影是可丢弃的，布局变化不需要任何迁移工具。将 Runtime.load 指向事件日志，它就会以新形状重新物化。

查询下推到数据库

用 FalkorDB 支持投影只有在查询在那里运行时才有用。最初它们没有：每个 Graph 查询都将整个投影从数据库中拉出并在 Python 中过滤，因此成本随图大小而非结果大小扩展。Issue #43 和 #45 填补了这一空白。

GraphStore 现在暴露了可选的查询钩子——find_objects、find_objects_in_types、find_relations、neighborhood 和 match_chain——每个都有定义语义的 Python 默认实现。后端可以覆盖某个钩子以将工作推入数据库，但结果必须与默认实现相同。在 FalkorDB 上，类型过滤、关系查找、邻域遍历和整个模式链现在作为索引支持的 Cypher 运行。一个曾经逐跳遍历投影的模式会合并成单个查询。

数据来自仓库中提供的基准脚本（仅供参考，单机，关注比率）：对 20,000 个对象进行 2 跳模式匹配，内存匹配器的全投影遍历耗时约 8.9 秒，下推后约 300 毫秒——大约 30 倍——并且差距随图大小扩大，因为 FalkorDB 的成本随匹配数而非节点数扩展。内存实现仍在小图上获胜，并且在写入上始终获胜；FalkorDB 指南有完整表格和经验法则。

无法忠实翻译的部分故意保持在 Python 中。where 谓词语言对下推后的候选集进行评估，因为结构化负载存储为 JSON，今天无法实现忠实翻译。结构过滤器下推；其余部分保持原位。原生 where 下推被列为路线图中的后续工作。

一致性测试套件是扩展契约

如何让两个后端——以及任何未来的后端——在“结果必须相同”这一要求上保持诚实？通过一个可执行契约。GraphStoreConformance 是一个 pytest 可收集的测试套件，涵盖往返、级联删除、查询钩子语义、占位符晋升和降级、以及循环安全的邻域遍历。InMemoryGraphStore 和 FalkorDBGraphStore 都继承它。

这也是未来之门。Neo4j 或 Postgres-graph 后端不需要设计辩论；它只需要子类化一致性套件并使其通过。契约就是测试，而不是散文。

测试套件现在成为 CI 门禁

本次发布揭示了一个令人不安的事实：Active Graph 有六个 CI 工作流——文档构建、文档字符串覆盖率、严格类型检查、wheel 完整性、部署验证——但没有一个运行测试套件。大约 700 个测试仅通过约定在本地由驱动者运行。FalkorDB 的 PR 在没有自动化测试执行的情况下合并了。

这与项目自身的门禁理念相矛盾，因此 v1.2.0 解决了这一问题。一个新的工作流在每次推送和 pull request 上运行测试套件，基于 Python 3.11 + 3.12 矩阵。3.12 版本安装嵌入式 FalkorDB 引擎，以便存储和一致性测试执行而非跳过，Postgres 服务容器对 Postgres 事件存储测试做了同样的事。锁定不变式：仓库中每个非慢速测试至少在一条分支上执行。如果某个可选依赖跳过没有分支执行，那就是门控回归，而非中性跳过。

事后诚实锁定决策

Active Graph 的开发纪律是契约优先：决策在代码提交时被锁定在 CONTRACT.md 中。FalkorDB 的开发弧线颠倒了这一点——代码来自社区，按社区的节奏，合并好代码比排在其契约散文后面更重要。

在发布前偿还了技术债务。CONTRACT.md § v1.2 锁定了该弧线引入的每个架构决策——接口及其真相来源不变量、连接模型、原生边形状、查询钩子语义（直至哪些钩子保证顺序）、以及一致性规则——并附有来源说明，明确说明锁定是在代码之后编写的，以及原因。如果未来贡献以同样的方式落地，该模式现在已命名：先合并，然后在发布前锁定。

同样的整理恢复了其周围的规划节奏。路线图现在界定了下一个周期（类型完整性清理、原生结构化输出模式、where 下推设计、社区界面），每一个被推迟的想法都带有明确的回顾触发器，以便推迟不会无声地过期，并且公共界面的文档字符串覆盖率达到了 100%——Runtime、View 和 Budget 不幸是最后几个没有文档字符串的符号。

统一许可证

一位眼光敏锐的用户注意到网站显示 MIT 而仓库显示 Apache 2.0——并合理询问是否是 AI 在某处进行了意外编辑。

并非意外，而是一个真实的不一致。Active Graph 在 v1.0 发布前从 MIT 切换到了 Apache 2.0，出于明确的专利授权和精确的贡献条款。仓库自此保持一致——LICENSE、NOTICE、wheel 元数据以及强制执行的 CI 测试。网站是过时的产物，现在也和其他所有地方一样显示 Apache 2.0。如果你正在基于 Active Graph 进行商业构建：Apache 2.0，带有专利授权，经 CI 验证。

迁移说明

无需迁移。

• 未传递 graph_store= 的运行行为与之前字节一致。InMemoryGraphStore 仍然是默认实现。
• FalkorDB 后端通过 [falkordb] 或 [falkordb-embedded] 附加包可选启用。
• 如果你尝试了预发布的关系即节点布局：无需工具。投影是可丢弃的——使用 graph_store= 重新加载运行，它会重新物化为原生边。
• v1.2.0 未添加新的事件类型、原因代码或错误类。

为什么这次发布很重要

两个原因，一个技术性，一个社会性。

技术原因：长期运行代理系统的当前状态视图现在是一个真正的图，你可以使用真正的工具指向它。对实时状态进行 Cypher 查询，仪表盘和侧车检查器共享一个投影，结构查询的成本等于答案的成本——同时事件日志继续作为下方无聊、持久、可重放的真相来源。

社会原因：这是第一个核心能力由项目外部人员设计、争论和构建的 Active Graph 发布，通过项目要求贡献者遵循的优先 issue 流程。四个 issue，每个陈述一个问题、一种变通方案和一个提议；然后是解决它们的 PR。该流程在其第一次真实测试中经受住了考验，与之一起发布的契约、一致性测试套件和 CI 门禁，使得下一个外部贡献比这次更容易。

PyPI: https://pypi.org/project/activegraph/1.2.0/

GitHub 发布: https://github.com/yoheinakajima/activegraph/releases/tag/v1.2.0

FalkorDB 指南: https://docs.activegraph.ai/guides/using-falkordb/