架构与源码导航

公开入口

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

源码目录

源码	职责
`ava.ts`	公开 API、数据源状态与生命周期
`types.ts`	配置、引擎与结果接口约定
`engines.ts`	内部引擎注册表
`analysis/`	Direct 与 Loop 分析策略
`duckdb/`	SQL 引擎、数据源加载器与统计
`interpreter/javascript/`	内存数据与 JavaScript 执行
`interpreter/python/`	pandas 执行与数据源验证
`remote/supabase/`	Management API、结构发现与统计
`remote/clickhouse/`	远程 SQL、结构发现与统计
`query/`	查询生成与方言验证
`visualization/`	图表推荐、GPT-Vis 配置与 HTML 生成
`suggest/`	分析问题推荐
`event/`	事件类型与载荷
`cli/`	命令与本地数据集会话
`util/`	模型解析、结构定义、指标与结果限制

方法与模块的对应关系

公开方法	职责与实现
`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 组装的数据模型。共享验证逻辑位于 util/schema.ts 与 util/profile.ts。

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

文档组织方式

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