尧图网站建设 
WrenAI 开发手册从 CLAUDE.md 解析仓库结构、构建命令与 Rust 语义引擎原理【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI本文基于仓库根目录下的 .claude/CLAUDE.md 展开——这份文件既是 Claude Code 等 AI 编码代理在本仓库工作时的操作指南也是贡献者理解 WrenAIGenBI代码库的最佳入口。全文将完整继承其中的项目定位、模块结构、四个核心模块的构建命令、语义查询流程与工程约定并结合 core/wren-core/Cargo.toml、core/wren/justfile、core/wren/pyproject.toml 等真实配置逐项佐证。读完之后你将掌握Wren 各子模块的职责边界与产物发布渠道、每个模块的编译/测试/格式化入口、SQL 从语义层到数据源执行的完整链路以及提交 PR 前必须通过的贡献门槛。一、项目定位面向 AI Agent 的开源语义引擎CLAUDE.md 开篇对 Wren 的定义是一个面向 MCP 客户端和 AI Agent 的开源语义引擎semantic engine。其核心工作是通过语义层MDLModeling Definition Language建模定义语言翻译 SQL 查询在22 数据源PostgreSQL、BigQuery、Snowflake、Spark 等上执行查询Rust 引擎基于Apache DataFusion构建且已切换到上游 crates.io 版本v53不再是 Canner fork。这一点可以从 core/wren-core/Cargo.toml 得到确认workspace 依赖中声明了datafusion { version 53, ... }启用了sql、parquet、各类表达式 feature 等工作区还固定了rust-version 1.78和insta 1.41.1对应后文快照测试约定。文档同时交代了一个重要的历史分界线旧的 WrenAI 服务wren-ui/、wren-ai-service/、wren-launcher/、docker/、deployment/在导入 wren-engine 时已整体迁移到legacy/v1分支tagv1-final当前主干的活跃开发聚焦于Open Context Engine。这意味着你在主干上看到的代码组织方式与早期 WrenAI 完全不同阅读旧分支代码时不要将其作为当前架构的参考。二、仓库结构core/ 下的五个模块CLAUDE.md 给出的目录骨架如下完整继承原文档core/ ├── wren-core/ Rust 语义引擎Cargo workspacecrates.io: wren-semantic-core库名 wren_core ├── wren-core-base/ 共享 Rust crate —— manifest 类型Model, Column, Metric, Relationship, View ManifestBuildercrates.io: wren-core-base ├── wren-core-py/ PyO3 绑定把 wren-core 暴露给 PythonPyPI: wren-core ├── wren-core-wasm/ wren-core 的 WebAssembly 构建用于浏览器内语义 SQLnpm: wren-core-wasm ├── wren/ Python SDK 与 CLI —— wren 命令、profile/context/memory 管理PyPI: wrenai └── wren-mdl/ MDL JSON Schema 定义 docs/core/ 模块文档 examples/ 示例项目文档标注为占位待补充 skills/ 基于 CLI 的 Agent 技能wren-generate-mdl、wren-usage、wren-dlt-connector、wren-onboarding scripts/ 仓库辅助脚本结合当前仓库实际内容可以补充三点wren-core是一个 Cargo workspace。从 core/wren-core/Cargo.toml 可见其 members 为benchmarks、core、sqllogictest、wren-example——即 TPCH 基准测试、核心引擎、SQL 逻辑测试框架和示例程序都内嵌在同一个 workspace 中。examples/并非完全空置。CLAUDE.md 将其标注为“placeholder — to be populated”但当前仓库中examples/v5-jaffle/下已有一个包含 models、views、cubes、knowledge 的完整示例项目可作为理解 v5 项目布局的参照。MDL 的 JSON Schema 独立存放在 core/wren-mdl/mdl.schema.json供校验与生成器消费。三、构建与开发命令四个模块逐一拆解CLAUDE.md 的核心价值之一是把每个模块“装什么、跑什么、测什么”固化成命令清单。下面按模块完整继承并结合各自的 justfile 说明底层动作。3.1 core/wren-coreRust 语义引擎cd core/wren-core cargo check --all-targets # 编译检查 cargo test --lib --tests --bins # 测试需设置 RUST_MIN_STACK8388608 cargo fmt --all # 格式化 cargo clippy --all-targets --all-features -- -D warnings # Lint taplo fmt # 格式化 Cargo.toml两个关键细节RUST_MIN_STACK83886088 MiB不是随口一提的提示。在 core/wren-core/core/src/mdl/mod.rs 的测试注释中明确写道“8 MiB matches CIs RUST_MIN_STACK”——即 CI 与本地测试需要保持一致的栈大小否则大递归/深解析场景下测试行为会与 CI 不一致。测试分布有明确约定多数单元测试集中在core/wren-core/core/src/mdl/mod.rsSQL 端到端测试则使用 sqllogictest 框架测试文件位于 core/wren-core/sqllogictest/test_files/含model.slt、view.slt、type.slt与tpch/下的 22 个查询。3.2 core/wren-core-pyPython 绑定cd core/wren-core-py just install # uv sync仅依赖--no-install-project just develop # 用 maturin 构建开发轮子 just test-rs # Rust 测试cargo test --no-default-features just test-py # Python 测试pytest just test # 两者都跑 just format # cargo fmt ruff taplo对照 core/wren-core-py/justfile 可以看到底层实现install实际执行uv sync --no-install-project只装依赖、不装本项目build/develop走maturin build/maturin develop且支持ENVprod时追加--release标志test-rs精确对应cargo test --no-default-featuresformat聚合了cargo fmt、ruff format、ruff check --fix、taplo fmt四步。该模块的测试位于 core/wren-core-py/tests/如test_modeling_core.py、test_cube.py。3.3 core/wren-core-wasm浏览器端 WASM 构建cd core/wren-core-wasm just build # wasm-pack buildbrowser target just test # wasm-pack test文档特别说明了产物特性输出约 68 MB 的 WASM 二进制经 npm 和 unpkg 分发jsDelivr 的单文件 50 MB CDN 上限导致其无法直接托管。当前 core/wren-core-wasm/justfile 比 CLAUDE.md 中的清单更细build拆为build-wasmwasm-pack build --target web --releasebuild-distnpm install 后由scripts/build.mjs组装 dist/macOS 上会自动指向 Homebrew 的 LLVM clang/llvm-ar 作为wasm32-unknown-unknown工具链另有size报告 raw/gzip 体积、typecheck对sdk/做tsc --noEmit、serve在localhost:8787上运行 examples/ 页面等配方。SDK 侧的 TypeScript 包装与声明位于 core/wren-core-wasm/sdk/src/index.ts。3.4 core/wrenPython SDK 与 CLIcd core/wren just install # uv sync锁定 PyPI 预构建 wren-core-py 轮子无需 Rust 工具链 just install-all # 带全部可选 extras含 memory just install-extra e # 例如 just install-extra postgres just install-memory # memory extralancedb sentence-transformers just install-local # 引擎开发uv sync 构建本地轮子 overlay just use-local-core # Rust 改动后重新构建并重新 overlay just dev # 运行 wren CLI just test # pytest tests/ just test-memory # memory 专项测试 just lint # ruff format --check ruff check just format # ruff 自动修复 just build # uv build产出 wheel文档明确了两条工程决策使用uv而非 Poetrypyproject.toml采用hatchling作为构建后端。结合 core/wren/justfile 与 core/wren/pyproject.toml可以补全 extras 全貌extra依赖pyproject.toml 实际声明postgrespsycopg[binary]3mysqlmysqlclient2.2justfile 中还会尝试通过 brew 设置PKG_CONFIG_PATHbigquerygoogle-cloud-bigquery3.40,4google-authsnowflakesnowflake-connector-python[pandas]3.10clickhouse/trino/mssqlclickhouse-connect0.8/trino0.333,1/pyodbc5,6databricks/redshift/sparkdatabricks-sql-connectordatabricks-sdk/redshift_connector/pyspark3.5athena/oraclepyathena[pandas]3/oracledb2memorylancedb0.6sentence-transformers3.0.0值得注意的是CLAUDE.md 列出的 extra 清单postgres…memory、all、dev之外pyproject 中还声明了memory-onnx与memory互斥的无 torch 向量后端被有意排除在all之外、interactive、ui、mcp、main等组合 extra——按需安装时以 core/wren/pyproject.toml 的声明为准。just dev底层是uv run --no-sync wren--no-sync的意图在 justfile 注释中写明保留本地 core overlay 不被覆盖依赖变更后需重跑 install 类配方。use-local-core则执行cd ../wren-core-py just install just build后用uv pip install --reinstall --no-index把本地轮子叠进当前.venv——这是“Rust 引擎开发 ↔ Python SDK”联调的正式姿势。四、架构一条 SQL 的语义查询流CLAUDE.md 给出的查询流程原文档完整继承SQL query → wren CLI / wren-core-py → wren-core (Rust): MDL analysis → logical plan → optimization → DataFusion (query planning, upstream crates.io v53) → connector-specific SQL (Ibis / sqlglot) → native execution on the target data source即用户/Agent 的 SQL 先经wrenCLI 或 PyO3 绑定进入 Rust 引擎做 MDL 分析与逻辑计划生成和优化交给上游 DataFusion v53 做查询规划再转译为目标连接器方言的 SQL经由 Ibis / sqlglot最终在数据源上原生执行。4.1 wren-core 内部结构文档对 core/wren-core/core/src/ 的关键组件划分如下均可在当前源码中一一对应mdl/—— MDL 核心处理WrenMDLmanifest 符号表、AnalyzedWrenMDL带 lineage 血缘、按方言组织的函数定义scalar/aggregate/window见mdl/function/dialect/如 BigQuery 的scalar.rs、aggregate.rs、window.rs、类型规划mdl/type_planner.rs、方言 SQL 生成mdl/dialect/wren_dialect.rs、mdl/lineage.rslogical_plan/analyze/—— DataFusion 分析器规则ModelAnalyzeRule把TableScan改写为ModelPlanNode、作用域跟踪analyze/scope.rs、访问控制 RLAC/CLACanalyze/access_control.rs、视图展开analyze/expand_view.rs、关系链解析analyze/relation_chain.rslogical_plan/optimize/—— 优化 pass类型强转optimize/type_coercion.rs、时间戳简化optimize/simplify_timestamp.rsSQL 解析与分析文档列有sql/模块而当前core/src顶层实际为mdl/、logical_plan/、unparser.rs计划反向解析回 SQL、error.rs、utils.rs——从源码结构看SQL 解析能力依托 DataFusion 的sqlfeature见 workspace 依赖声明阅读时以当前仓库实际目录为准。其中ModelAnalyzeRule的实现注释model_anlayze.rs恰好印证了文档的“TableScan → ModelPlanNode”描述该规则分三步——(1) 自底向上遍历逻辑计划、按作用域收集 model 所需列(2) 自底向上生成ModelPlanNode含SubqueryAlias → TableScan的预处理捷径(3) 自顶向下剥离 Wren 的 catalog/schema 前缀并刷新 schema。4.2 Manifest 类型与 PyO3 桥接文档指出 core/wren-core-base/src/mdl/ 是 manifest 类型的家manifest.rs 定义Manifest、Model、Column、Metric、Relationship、View、RowLevelAccessControl、ColumnLevelAccessControlbuilder.rs 提供流式ManifestBuilderAPI通过wren-manifest-macro宏自动生成 Pydantic 兼容的 Python 类。从 manifest.rs 的源码结构看这一“双份实现”是编译期 feature 驱动的非python-binding场景下宏实例manifest!、model!、column!、row_level_access_control!等十余个只生成 serde 类型开启python-bindingfeature 后同一批宏额外引入pyo3::pyclass生成 Python 可交互的类。也就是说PyO3 绑定并非手写胶水而是由 core/wren-core-base/manifest-macro/ 统一派生保证 Rust 与 Python 两侧字段严格同源。五、已知限制ModelAnalyzeRule 的关联子查询问题CLAUDE.md 用独立一节记录了 wren-core 的一个已知边界原文档完整继承ModelAnalyzeRule — 关联子查询中的列解析无法解析关联子查询内部对外层列的引用只能看到子查询自身的表作用域。影响 TPCH Q2、Q4、Q15、Q17、Q20、Q21、Q22。这条限制的落点正是 core/wren-core/core/src/logical_plan/analyze/model_anlayze.rs 中的作用域机制——如前所述该规则靠ScopeManager在遍历中逐层 push/pop 子查询作用域而外层列引用在子查询作用域内不可见因此这类查询无法被语义层正确展开。仓库内 sqllogictest/test_files/tpch/ 下 Q2/Q4/Q15/Q17/Q20/Q21/Q22 均有对应测试文件基准工程 core/wren-core/benchmarks/ 也会复现这些用例如果你在这条链路上做引擎开发应把这些查询当作回归基线而非“已解决”状态。六、工程约定ConventionsCLAUDE.md 的 Conventions 一节可视为本仓库的“硬性风格契约”逐条继承提交信息Conventional Commitsfeat:、fix:、chore:、refactor:、test:、docs:、perf:、deps:。发布由release-please 自动化且每个模块独立成发布线——这与根目录 release-please-config.json 的多模块配置以及各模块各自的CHANGELOG.md如 core/wren-core/CHANGELOG.md、core/wren/CHANGELOG.md相互印证。Rustcargo fmt格式化、clippy -D warningsLint、TOML 用taplo。Pythonruff格式化与 Lintline-length 88、target Python 3.11core/wren-core-py与core/wren均使用 uv。core/wren/pyproject.toml 中[tool.ruff]段确为line-length 88、target-version py311且刻意extend-exclude [*.md]文档由人工排版ruff 0.16 默认会格式化 Markdown 代码块。DataFusion使用上游datafusionv53crates.io不再是 Canner fork。快照测试wren-core 使用insta做 Rust 快照测试workspace 依赖已固定insta 1.41.1。CI按模块做路径过滤path-filtered——workflow 只在该模块目录内发生改动时触发这也是多模块发布线能保持独立的基建前提。七、贡献门槛Contribution BarCLAUDE.md 最后是一节措辞相当强硬的“Contribution Bar”并说明其存在的原因相当比例的外部 PR 会因违反这些规则而被直接关闭close rather than iterate。完整继承其六条规则7.1 先证明问题再修复不要断言你未观察过的外部系统行为。如果你声称某引擎、驱动或库会拒绝某种输入必须复现并把真实报错贴进 PR 描述。无证据的断言——“解析器会拒绝结尾分号”“某些客户端不接受这个”——会被直接拒收历史上已有若干此类断言经测试后被证明是错的。不要为未证明可达的状态添加防御代码。需要追踪调用路径并在描述中说明坏值是如何传到的。如果仓库上游已做校验CLAUDE.md 同时指向core/wren/.claude/CLAUDE.md中的 “Validation boundaries” 一节下游重复校验就是死代码。无法复现失败时你拥有的只是假设不是 bug。此时应提 issue 并附上复现尝试而不是提 PR。7.2 诚实打标fix:要求存在一个可复现的失败且该改动修复了它行为上无可见差异的改动应标refactor:或chore:。PR 描述必须说明“对用户而言变了什么”。“提升鲁棒性”“加固 X”这类表述不算答案。7.3 测试必须真正执行你改动的代码把源文件当文本读、对子串做断言的测试什么都测不到——应调用函数断言其返回值或向下游传递的内容每条断言都必须有能力失败。断言代码根本无法产生的条件属于噪音确认测试真的会在 CI 里运行。部分测试文件被可选 extras 或容器门控默认 job 会跳过——把无需服务的测试放进这类文件它永远不会被执行这解释了 core/wren/justfile 中大量按 connector marker 拆分的test-postgres/test-mysql等配方。7.4 一个改动只做一次开 PR 前先搜已有 PR同文件的重复 PR 不评审直接关闭跨多个文件/连接器的机械式改动应合并进一个PR评审者需要在单个 diff 中看到最终形成的约定。7.5 尊重已记录的决策如果某条注释或测试记录了有意为之的选择不要悄悄反转它——应在描述中引用原文并论证为何要改。7.6 保持分支最新请求评审前先 rebase 到目标分支。一个基于旧基线的分支可能文本上合并干净、语义上却是坏的——“文本上干净的合并”不等于“语义上正确的合并”。八、小结如何使用这份指南.claude/CLAUDE.md 本质上是把“AI Agent 协作所需的仓库知识”与“人类贡献者所需的工程纪律”写进了同一份文件前半部分模块结构、构建命令、查询流、已知限制回答了“在哪里改、怎么构建、边界在哪”后半部分Conventions、Contribution Bar回答了“什么样的改动会被接受”。对贡献者而言实操路径是先按第三节选对模块的 justfile 配方把本地环境跑通用sqllogictest与 insta 快照理解既有行为对照第五节避开已知限制再带着第七节的标准组织你的 PR——这也是该仓库 CI 按模块路径过滤、release-please 按模块独立发布的治理结构所要求的协作方式。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WrenAI 开发手册：从 CLAUDE.md 解析仓库结构、构建命令与 Rust 语义引擎原理
WrenAI 开发手册从 CLAUDE.md 解析仓库结构、构建命令与 Rust 语义引擎原理【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI本文基于仓库根目录下的 .claude/CLAUDE.md 展开——这份文件既是 Claude Code 等 AI 编码代理在本仓库工作时的操作指南也是贡献者理解 WrenAIGenBI代码库的最佳入口。全文将完整继承其中的项目定位、模块结构、四个核心模块的构建命令、语义查询流程与工程约定并结合 core/wren-core/Cargo.toml、core/wren/justfile、core/wren/pyproject.toml 等真实配置逐项佐证。读完之后你将掌握Wren 各子模块的职责边界与产物发布渠道、每个模块的编译/测试/格式化入口、SQL 从语义层到数据源执行的完整链路以及提交 PR 前必须通过的贡献门槛。一、项目定位面向 AI Agent 的开源语义引擎CLAUDE.md 开篇对 Wren 的定义是一个面向 MCP 客户端和 AI Agent 的开源语义引擎semantic engine。其核心工作是通过语义层MDLModeling Definition Language建模定义语言翻译 SQL 查询在22 数据源PostgreSQL、BigQuery、Snowflake、Spark 等上执行查询Rust 引擎基于Apache DataFusion构建且已切换到上游 crates.io 版本v53不再是 Canner fork。这一点可以从 core/wren-core/Cargo.toml 得到确认workspace 依赖中声明了datafusion { version 53, ... }启用了sql、parquet、各类表达式 feature 等工作区还固定了rust-version 1.78和insta 1.41.1对应后文快照测试约定。文档同时交代了一个重要的历史分界线旧的 WrenAI 服务wren-ui/、wren-ai-service/、wren-launcher/、docker/、deployment/在导入 wren-engine 时已整体迁移到legacy/v1分支tagv1-final当前主干的活跃开发聚焦于Open Context Engine。这意味着你在主干上看到的代码组织方式与早期 WrenAI 完全不同阅读旧分支代码时不要将其作为当前架构的参考。二、仓库结构core/ 下的五个模块CLAUDE.md 给出的目录骨架如下完整继承原文档core/ ├── wren-core/ Rust 语义引擎Cargo workspacecrates.io: wren-semantic-core库名 wren_core ├── wren-core-base/ 共享 Rust crate —— manifest 类型Model, Column, Metric, Relationship, View ManifestBuildercrates.io: wren-core-base ├── wren-core-py/ PyO3 绑定把 wren-core 暴露给 PythonPyPI: wren-core ├── wren-core-wasm/ wren-core 的 WebAssembly 构建用于浏览器内语义 SQLnpm: wren-core-wasm ├── wren/ Python SDK 与 CLI —— wren 命令、profile/context/memory 管理PyPI: wrenai └── wren-mdl/ MDL JSON Schema 定义 docs/core/ 模块文档 examples/ 示例项目文档标注为占位待补充 skills/ 基于 CLI 的 Agent 技能wren-generate-mdl、wren-usage、wren-dlt-connector、wren-onboarding scripts/ 仓库辅助脚本结合当前仓库实际内容可以补充三点wren-core是一个 Cargo workspace。从 core/wren-core/Cargo.toml 可见其 members 为benchmarks、core、sqllogictest、wren-example——即 TPCH 基准测试、核心引擎、SQL 逻辑测试框架和示例程序都内嵌在同一个 workspace 中。examples/并非完全空置。CLAUDE.md 将其标注为“placeholder — to be populated”但当前仓库中examples/v5-jaffle/下已有一个包含 models、views、cubes、knowledge 的完整示例项目可作为理解 v5 项目布局的参照。MDL 的 JSON Schema 独立存放在 core/wren-mdl/mdl.schema.json供校验与生成器消费。三、构建与开发命令四个模块逐一拆解CLAUDE.md 的核心价值之一是把每个模块“装什么、跑什么、测什么”固化成命令清单。下面按模块完整继承并结合各自的 justfile 说明底层动作。3.1 core/wren-coreRust 语义引擎cd core/wren-core cargo check --all-targets # 编译检查 cargo test --lib --tests --bins # 测试需设置 RUST_MIN_STACK8388608 cargo fmt --all # 格式化 cargo clippy --all-targets --all-features -- -D warnings # Lint taplo fmt # 格式化 Cargo.toml两个关键细节RUST_MIN_STACK83886088 MiB不是随口一提的提示。在 core/wren-core/core/src/mdl/mod.rs 的测试注释中明确写道“8 MiB matches CIs RUST_MIN_STACK”——即 CI 与本地测试需要保持一致的栈大小否则大递归/深解析场景下测试行为会与 CI 不一致。测试分布有明确约定多数单元测试集中在core/wren-core/core/src/mdl/mod.rsSQL 端到端测试则使用 sqllogictest 框架测试文件位于 core/wren-core/sqllogictest/test_files/含model.slt、view.slt、type.slt与tpch/下的 22 个查询。3.2 core/wren-core-pyPython 绑定cd core/wren-core-py just install # uv sync仅依赖--no-install-project just develop # 用 maturin 构建开发轮子 just test-rs # Rust 测试cargo test --no-default-features just test-py # Python 测试pytest just test # 两者都跑 just format # cargo fmt ruff taplo对照 core/wren-core-py/justfile 可以看到底层实现install实际执行uv sync --no-install-project只装依赖、不装本项目build/develop走maturin build/maturin develop且支持ENVprod时追加--release标志test-rs精确对应cargo test --no-default-featuresformat聚合了cargo fmt、ruff format、ruff check --fix、taplo fmt四步。该模块的测试位于 core/wren-core-py/tests/如test_modeling_core.py、test_cube.py。3.3 core/wren-core-wasm浏览器端 WASM 构建cd core/wren-core-wasm just build # wasm-pack buildbrowser target just test # wasm-pack test文档特别说明了产物特性输出约 68 MB 的 WASM 二进制经 npm 和 unpkg 分发jsDelivr 的单文件 50 MB CDN 上限导致其无法直接托管。当前 core/wren-core-wasm/justfile 比 CLAUDE.md 中的清单更细build拆为build-wasmwasm-pack build --target web --releasebuild-distnpm install 后由scripts/build.mjs组装 dist/macOS 上会自动指向 Homebrew 的 LLVM clang/llvm-ar 作为wasm32-unknown-unknown工具链另有size报告 raw/gzip 体积、typecheck对sdk/做tsc --noEmit、serve在localhost:8787上运行 examples/ 页面等配方。SDK 侧的 TypeScript 包装与声明位于 core/wren-core-wasm/sdk/src/index.ts。3.4 core/wrenPython SDK 与 CLIcd core/wren just install # uv sync锁定 PyPI 预构建 wren-core-py 轮子无需 Rust 工具链 just install-all # 带全部可选 extras含 memory just install-extra e # 例如 just install-extra postgres just install-memory # memory extralancedb sentence-transformers just install-local # 引擎开发uv sync 构建本地轮子 overlay just use-local-core # Rust 改动后重新构建并重新 overlay just dev # 运行 wren CLI just test # pytest tests/ just test-memory # memory 专项测试 just lint # ruff format --check ruff check just format # ruff 自动修复 just build # uv build产出 wheel文档明确了两条工程决策使用uv而非 Poetrypyproject.toml采用hatchling作为构建后端。结合 core/wren/justfile 与 core/wren/pyproject.toml可以补全 extras 全貌extra依赖pyproject.toml 实际声明postgrespsycopg[binary]3mysqlmysqlclient2.2justfile 中还会尝试通过 brew 设置PKG_CONFIG_PATHbigquerygoogle-cloud-bigquery3.40,4google-authsnowflakesnowflake-connector-python[pandas]3.10clickhouse/trino/mssqlclickhouse-connect0.8/trino0.333,1/pyodbc5,6databricks/redshift/sparkdatabricks-sql-connectordatabricks-sdk/redshift_connector/pyspark3.5athena/oraclepyathena[pandas]3/oracledb2memorylancedb0.6sentence-transformers3.0.0值得注意的是CLAUDE.md 列出的 extra 清单postgres…memory、all、dev之外pyproject 中还声明了memory-onnx与memory互斥的无 torch 向量后端被有意排除在all之外、interactive、ui、mcp、main等组合 extra——按需安装时以 core/wren/pyproject.toml 的声明为准。just dev底层是uv run --no-sync wren--no-sync的意图在 justfile 注释中写明保留本地 core overlay 不被覆盖依赖变更后需重跑 install 类配方。use-local-core则执行cd ../wren-core-py just install just build后用uv pip install --reinstall --no-index把本地轮子叠进当前.venv——这是“Rust 引擎开发 ↔ Python SDK”联调的正式姿势。四、架构一条 SQL 的语义查询流CLAUDE.md 给出的查询流程原文档完整继承SQL query → wren CLI / wren-core-py → wren-core (Rust): MDL analysis → logical plan → optimization → DataFusion (query planning, upstream crates.io v53) → connector-specific SQL (Ibis / sqlglot) → native execution on the target data source即用户/Agent 的 SQL 先经wrenCLI 或 PyO3 绑定进入 Rust 引擎做 MDL 分析与逻辑计划生成和优化交给上游 DataFusion v53 做查询规划再转译为目标连接器方言的 SQL经由 Ibis / sqlglot最终在数据源上原生执行。4.1 wren-core 内部结构文档对 core/wren-core/core/src/ 的关键组件划分如下均可在当前源码中一一对应mdl/—— MDL 核心处理WrenMDLmanifest 符号表、AnalyzedWrenMDL带 lineage 血缘、按方言组织的函数定义scalar/aggregate/window见mdl/function/dialect/如 BigQuery 的scalar.rs、aggregate.rs、window.rs、类型规划mdl/type_planner.rs、方言 SQL 生成mdl/dialect/wren_dialect.rs、mdl/lineage.rslogical_plan/analyze/—— DataFusion 分析器规则ModelAnalyzeRule把TableScan改写为ModelPlanNode、作用域跟踪analyze/scope.rs、访问控制 RLAC/CLACanalyze/access_control.rs、视图展开analyze/expand_view.rs、关系链解析analyze/relation_chain.rslogical_plan/optimize/—— 优化 pass类型强转optimize/type_coercion.rs、时间戳简化optimize/simplify_timestamp.rsSQL 解析与分析文档列有sql/模块而当前core/src顶层实际为mdl/、logical_plan/、unparser.rs计划反向解析回 SQL、error.rs、utils.rs——从源码结构看SQL 解析能力依托 DataFusion 的sqlfeature见 workspace 依赖声明阅读时以当前仓库实际目录为准。其中ModelAnalyzeRule的实现注释model_anlayze.rs恰好印证了文档的“TableScan → ModelPlanNode”描述该规则分三步——(1) 自底向上遍历逻辑计划、按作用域收集 model 所需列(2) 自底向上生成ModelPlanNode含SubqueryAlias → TableScan的预处理捷径(3) 自顶向下剥离 Wren 的 catalog/schema 前缀并刷新 schema。4.2 Manifest 类型与 PyO3 桥接文档指出 core/wren-core-base/src/mdl/ 是 manifest 类型的家manifest.rs 定义Manifest、Model、Column、Metric、Relationship、View、RowLevelAccessControl、ColumnLevelAccessControlbuilder.rs 提供流式ManifestBuilderAPI通过wren-manifest-macro宏自动生成 Pydantic 兼容的 Python 类。从 manifest.rs 的源码结构看这一“双份实现”是编译期 feature 驱动的非python-binding场景下宏实例manifest!、model!、column!、row_level_access_control!等十余个只生成 serde 类型开启python-bindingfeature 后同一批宏额外引入pyo3::pyclass生成 Python 可交互的类。也就是说PyO3 绑定并非手写胶水而是由 core/wren-core-base/manifest-macro/ 统一派生保证 Rust 与 Python 两侧字段严格同源。五、已知限制ModelAnalyzeRule 的关联子查询问题CLAUDE.md 用独立一节记录了 wren-core 的一个已知边界原文档完整继承ModelAnalyzeRule — 关联子查询中的列解析无法解析关联子查询内部对外层列的引用只能看到子查询自身的表作用域。影响 TPCH Q2、Q4、Q15、Q17、Q20、Q21、Q22。这条限制的落点正是 core/wren-core/core/src/logical_plan/analyze/model_anlayze.rs 中的作用域机制——如前所述该规则靠ScopeManager在遍历中逐层 push/pop 子查询作用域而外层列引用在子查询作用域内不可见因此这类查询无法被语义层正确展开。仓库内 sqllogictest/test_files/tpch/ 下 Q2/Q4/Q15/Q17/Q20/Q21/Q22 均有对应测试文件基准工程 core/wren-core/benchmarks/ 也会复现这些用例如果你在这条链路上做引擎开发应把这些查询当作回归基线而非“已解决”状态。六、工程约定ConventionsCLAUDE.md 的 Conventions 一节可视为本仓库的“硬性风格契约”逐条继承提交信息Conventional Commitsfeat:、fix:、chore:、refactor:、test:、docs:、perf:、deps:。发布由release-please 自动化且每个模块独立成发布线——这与根目录 release-please-config.json 的多模块配置以及各模块各自的CHANGELOG.md如 core/wren-core/CHANGELOG.md、core/wren/CHANGELOG.md相互印证。Rustcargo fmt格式化、clippy -D warningsLint、TOML 用taplo。Pythonruff格式化与 Lintline-length 88、target Python 3.11core/wren-core-py与core/wren均使用 uv。core/wren/pyproject.toml 中[tool.ruff]段确为line-length 88、target-version py311且刻意extend-exclude [*.md]文档由人工排版ruff 0.16 默认会格式化 Markdown 代码块。DataFusion使用上游datafusionv53crates.io不再是 Canner fork。快照测试wren-core 使用insta做 Rust 快照测试workspace 依赖已固定insta 1.41.1。CI按模块做路径过滤path-filtered——workflow 只在该模块目录内发生改动时触发这也是多模块发布线能保持独立的基建前提。七、贡献门槛Contribution BarCLAUDE.md 最后是一节措辞相当强硬的“Contribution Bar”并说明其存在的原因相当比例的外部 PR 会因违反这些规则而被直接关闭close rather than iterate。完整继承其六条规则7.1 先证明问题再修复不要断言你未观察过的外部系统行为。如果你声称某引擎、驱动或库会拒绝某种输入必须复现并把真实报错贴进 PR 描述。无证据的断言——“解析器会拒绝结尾分号”“某些客户端不接受这个”——会被直接拒收历史上已有若干此类断言经测试后被证明是错的。不要为未证明可达的状态添加防御代码。需要追踪调用路径并在描述中说明坏值是如何传到的。如果仓库上游已做校验CLAUDE.md 同时指向core/wren/.claude/CLAUDE.md中的 “Validation boundaries” 一节下游重复校验就是死代码。无法复现失败时你拥有的只是假设不是 bug。此时应提 issue 并附上复现尝试而不是提 PR。7.2 诚实打标fix:要求存在一个可复现的失败且该改动修复了它行为上无可见差异的改动应标refactor:或chore:。PR 描述必须说明“对用户而言变了什么”。“提升鲁棒性”“加固 X”这类表述不算答案。7.3 测试必须真正执行你改动的代码把源文件当文本读、对子串做断言的测试什么都测不到——应调用函数断言其返回值或向下游传递的内容每条断言都必须有能力失败。断言代码根本无法产生的条件属于噪音确认测试真的会在 CI 里运行。部分测试文件被可选 extras 或容器门控默认 job 会跳过——把无需服务的测试放进这类文件它永远不会被执行这解释了 core/wren/justfile 中大量按 connector marker 拆分的test-postgres/test-mysql等配方。7.4 一个改动只做一次开 PR 前先搜已有 PR同文件的重复 PR 不评审直接关闭跨多个文件/连接器的机械式改动应合并进一个PR评审者需要在单个 diff 中看到最终形成的约定。7.5 尊重已记录的决策如果某条注释或测试记录了有意为之的选择不要悄悄反转它——应在描述中引用原文并论证为何要改。7.6 保持分支最新请求评审前先 rebase 到目标分支。一个基于旧基线的分支可能文本上合并干净、语义上却是坏的——“文本上干净的合并”不等于“语义上正确的合并”。八、小结如何使用这份指南.claude/CLAUDE.md 本质上是把“AI Agent 协作所需的仓库知识”与“人类贡献者所需的工程纪律”写进了同一份文件前半部分模块结构、构建命令、查询流、已知限制回答了“在哪里改、怎么构建、边界在哪”后半部分Conventions、Contribution Bar回答了“什么样的改动会被接受”。对贡献者而言实操路径是先按第三节选对模块的 justfile 配方把本地环境跑通用sqllogictest与 insta 快照理解既有行为对照第五节避开已知限制再带着第七节的标准组织你的 PR——这也是该仓库 CI 按模块路径过滤、release-please 按模块独立发布的治理结构所要求的协作方式。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考