跳至正文
浏览文档
更多资源

架构与源码导航

从公开 API 出发,找到对应的实现与扩展位置。

公开入口

index.ts 注册全部 Node.js 引擎,导出 AVA 和公开类型;index.browser.ts 只注册 JavaScript。ava.ts 协调数据源状态、数据模型、事件与引擎生命周期。

源码目录

源码职责
ava.ts公开 API、数据源状态与生命周期
types.ts统一维护公开类型定义及 schema 推导类型
contracts/按 source、schema、profile、semantic、query、analyze、suggest 与图表 API 组织契约
engines.ts引擎选择与注册表
analysis/Direct 与 Loop 分析策略
duckdb/SQL 引擎、数据源加载器与统计
interpreter/javascript/内存数据与 JavaScript 执行
interpreter/python/pandas 执行与数据源验证
remote/supabase/Management API、结构发现与统计
remote/clickhouse/远程 SQL、结构发现与统计
remote/snowflake/Snowflake 驱动会话、结构发现与统计
query/查询生成与方言验证
visualization/图表推荐、GPT-Vis 配置与 HTML 生成
suggest/分析问题推荐
event/事件类型与载荷
cli/命令与本地数据集会话
util/目录组装、模型格式化、指标执行规则与结果限制

契约按公开 API 组织。source/ 按数据源类型分文件维护运行时 schema,包括 CSV/JSON/Excel 读取选项;source/index.ts 组装数据源联合契约,source/shared.ts 维护共用的文件与连接字段。schema.ts、profile.ts、semantic.ts、query.ts、analyze.ts、translate.ts、suggest.ts 分别维护对应 API 输入与输出的运行时 schema。visualize.ts 维护 recommend()、viz()、visualize() 共用的图表结构。跨 API 的 JSON 值与数据模型基础定义放在 shared/。

types.ts 汇总公开的配置、引擎、策略及数据类型定义;数据类型从运行时 schema 推导。数据模型组装器维护从公共元数据字段派生的严格输入校验。模块通过 contracts/index.ts 导入 API schema,从所属模块导入内部 schema,通过 types.ts 导入类型;契约定义之间直接引用,避免循环依赖。index.ts 与 index.browser.ts 统一导出 API 输入、输出 schema,类型沿用原有名称;CLI 消息协议、AI 阶段输出与引擎专用限制仍由各自模块维护。

方法与模块的对应关系

公开方法职责与实现
source() / schema() / dispose()ava.ts 中的数据源状态与引擎生命周期
profile()各引擎实现统计计算,共享指标约定位于 util/profile.ts
analyze()分发到 analysis/direct.ts 或 analysis/loop.ts
translate() / query()引擎的 getDSL() / execute()
suggest()suggest/index.ts
recommend()visualization/advisor.ts 与配置生成
viz()visualization/generator.ts 中的 HTML 包装
visualize()组合 recommend() 和 viz()

上下文与状态

每个 AVA 实例持有一个活动引擎及其 schema、profile 缓存。source() 加载数据,schema() 在首次使用时发现结构;profile() 重新计算并保存统计信息;需要时再由缓存元数据组装数据模型。重新加载或释放实例会清空两类缓存。

引擎持有数据与连接。load() 不返回元数据,schema() 发现结构,profile(schema, options?) 计算统计信息,getDSL(query, dataModel) 使用 AVA 组装的数据模型。共享数据校验位于 contracts/;目录组装与指标执行工具保留在 util/。

分析策略共享一个运行时,其中包括引擎、模型配置、数据模型与事件发射器。查询结果限制通过共享工具统一规范化。

文档组织方式

每个主题都是 site/content/docs/ 下的独立 MDX 文件,按 data/、analysis/、visualization/、engines/、reference/ 分组。这样的组织对应公开能力,无需将每个内部辅助函数都拆成独立的用户文档。