用途：为 Convex 应用提供高效聚合能力，通过反规范化 B-tree 在 O(log n) 时间内完成 count、sum、min、max、rank、offset 访问与百分位查询。
主要能力：提供 TableAggregate（绑定 Convex 表，从文档字段派生键并自动同步）与 DirectAggregate（独立使用，手动增删改，适合分析、指标等非表数据）。支持排序键（number、string、null 或元组）、命名空间分区、bounds 范围/前缀/精确匹配限制。查询方法包括 count、sum、at（支持负索引）、indexOf、min、max、random、paginate 与异步迭代器 iter。写入方法包括 insert、delete、replace 及幂等变体 insertIfDoesNotExist、deleteIfExists、replaceOrInsert，另有 indexOfDoc、clear、clearAll、makeRootLazy。
使用方式：先执行 npm install @convex-dev/aggregate，在 convex/convex.config.ts 中通过 app.use(aggregate) 注册，可多次注册并指定 name；运行 npx convex dev 生成组件 API。随后按需创建 TableAggregate 或 DirectAggregate 实例，并在修改源表后同步更新聚合，推荐使用封装 helper 或 convex-helpers 的 Triggers。
适用场景：排行榜、按游戏或用户分区的统计、时间范围查询、随机抽样、偏移分页、分析指标等。
限制与注意：修改源表时必须同步更新聚合，否则数据不一致；命名空间之间相互隔离，无法跨命名空间聚合；排序键结构决定 max/min 结果，例如 [game, username] 的 max 返回字母序最大的用户名而非分数；建议尽量使用 bounds 以减少读依赖与写争用；写密集场景用默认 lazy root，读密集可设 rootLazy: false。更多示例与高级主题见 references/examples.md 与 references/advanced.md。