WrenAIwrenaiChangelog 深度解读从 wren-engine 到生成式 BI 语义层的版本演进全览【免费下载链接】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本文以 WrenAI 仓库中core/wren/CHANGELOG.md为主线系统梳理wrenai原wren-engine从 v0.3.0 到 v0.13.4 的功能演进、连接器健壮性修复、安全治理与 GenBI 能力落地并结合 engine.py、policy.py、mcp_server.py 等源码说明每个版本变更背后的实现原理。读完本文你将掌握 wrenai CLI 的核心命令体系、跨 20 数据源的 SQL 语义层工作机制以及 2026 年该版本线中最重要的架构决策v5 项目布局、GenBI 应用构建、内存层去 LanceDB 耦合。一、版本线概览一条从 SQL 引擎走向 GenBI 平台的演进路径core/wren/CHANGELOG.md记录了wrenai包PyPI 原名wren-engine从 2026-04 到 2026-09 的持续演进。按主题可划分为三条主线演进主线代表版本核心内容语义层与 CLI 体系成型v0.3.0 → v0.6.0CTE 重写器、context 管理、profile、memory 层、WASM 支持、refSql 模型连接器大规模加固v0.7.0 → v0.13.420 数据源的分号剥离、LIMIT 下推、URL 凭据解码、SSL 修复、精度保留GenBI 与治理能力落地v0.8.0 → v0.13.4dbt 导入、OSI 语义模型、Cube 支持、GenBI app 构建部署、MCP 能力服务该版本线中最重要的转折点是 v0.7.0PyPI 包名从wren-engine正式更名为wrenai#2315这是仓库向生成式 BI 平台定位转型的标志性动作——正如仓库项目描述所言目标是把自然语言问题转译为可信的看板、图表和 SQL。README 也随之改为 Wren AI 品牌。二、v0.3.0—v0.4.0CLI 语义层的奠基2.1 CTE 式 SQL 规划v0.3.0 引入CTE-based SQL planning with per-model expansion#1479这是整个语义层的执行核心。从 engine.py 的dry_plan可以看出完整转换流水线用户 SQL目标方言如 Postgres → sqlglot parse目标方言 → qualify_tables normalize_identifiers qualify_columns → 识别引用的模型与列 → 逐模型wren-core transform_sql → Wren 方言 SQL → 逐模型sqlglot parseWren 方言→ 注入为 CTE → sqlglot generate目标方言 → 输出带模型 CTE 的目标方言 SQLcte_rewriter.py 对视图的处理方式与模型不同视图的statement是原生 SQL直接原样注入为 CTE不经过 wren-core其引用的模型则先以模型 CTE 形式前置从而保持视图作为可执行 SQL 的语义完整性。SELECT *的保留#1536则保证了通配查询在重写后不丢列。2.2 context 管理与 AGENTS.md 生成v0.3.0 的 CLI 0.2.0 大版本#1522 中给出了 Agent 回答数据问题的标准流程wren memory fetch -q question获取相关 schema 上下文wren memory recall -q question --limit 3查找相似历史查询使用 MDL 模型名而非原始表名编写 SQLwren --sql sql通过语义层执行wren memory store --nl question --sql sql保存确认结果2.3 .env 驱动的 profile 密钥管理v0.4.0 引入.env驱动的 profile 密钥与自动连接验证#1588 源码可见关键设计profile 中允许${VAR}占位符**在连接时而非保存时**通过expand_profile_secrets解析存储的 YAML 始终保留占位符因此wren profile debug永远不会打印真实密钥。环境变量加载顺序为$CWD/.env→ 项目根.env→~/.wren/.env且overrideFalse保证 shell 中已有的环境变量优先级最高。${VAR}名称被限制为[_A-Z][_A-Z0-9]*这样真实密码中的小写花括号序列如${foo}不会被误匹配。三、v0.5.0—v0.6.0引擎并入主仓库与 profile 绑定v0.5.0wren-engine作为独立仓库被导入到core/目录#2209从此与 wren-coreRust、wren-core-wasm 等模块同仓管理。v0.6.0context 支持将连接 profile 绑定到项目#2251profile 从全局配置演进为可随项目分发。四、v0.7.0—v0.8.0品牌更名、Cube 与 dbt/OSI 生态接入4.1 包名更名Breaking Changev0.7.0 将 PyPI 包名从wren-engine改为wrenai#2315。对使用者而言安装命令变为pip install wrenai[postgres,memory,ui]其中memoryextra 启用基于 embedding 的语义检索ui启用交互式界面。该 extra 机制在context.py生成的 AGENTS.md 模板和 memory CLI 的报错提示中均有体现例如pip install wrenai[memory]。4.2 Cube 全链路支持v0.7.0 的 wasm 模块实现了完整 Cube 支持——验证、翻译、PyO3、CLI、WASM、文档全链路覆盖#2282。在 CLI 中对应wren cube命令族MCP 服务器则暴露query_cube工具见下文。4.3 dbt 导入与 OSI 语义模型v0.8.0新增 dbt 导入工作流#2279 目录中可看到minimal.yaml、multi_semantic_model.yaml、tpcds_full.yaml等测试样例。v0.8.0同时修复了 SQL 标识符大小写在 policy、extract 与 CTE rewriter 三处的一致性#2310这正是 policy.py 中resolve_model_name所实现的双规则带引号的标识符必须大小写精确匹配不带引号的标识符优先精确匹配、失败后回退大小写不敏感扫描且多个候选时选择字典序最小者以保证跨进程结果确定。五、v0.9.0—v0.11.0MCP 服务、知识/技能分发与 v5 项目布局5.1 查询 MDL 视图与技能分发v0.9.0 让 SDK 重写器和 strict mode 支持查询 MDL 视图#2334 与各skills_content/模板如generate-mdl、enrich-context、onboarding。v0.10.0 支持 wren-core 的复合多列主键#2345并从 folder-per-entity 布局加载 cubes#2350。5.2 v5 项目布局schema_version 5v0.11.0 是架构性版本引入 v5 项目布局#2386、#2399knowledge/ 成为一等公民业务规则knowledge/rules/*.md、NL→SQL 示例knowledge/sql/*.md、术语表、指标说明统一收纳在项目内随项目一起版本管理memory 与 LanceDB 解耦语义索引不再是唯一真相knowledge/sql/*.md成为记忆的 source of truthLanceDB 只是可重建的派生索引同版本还带来 CTE 重写器的大小写感知列/模型绑定#2400并对 schema_version 5 的升级测试做了配套修复#2388。仓库中的 examples/v5-jaffle 就是 v5 布局的完整范例models/、views/、cubes/、knowledge/、relationships.yml、wren_project.yml一应俱全。MCP 服务器的wren://project资源会同时报告schema_version与knowledge_schema_version见 mcp_server.py。5.3 MCP 能力服务v0.13.0v0.13.0 通过 MCP 暴露项目能力#2438。从 mcp_server.py 可看到完整的工具矩阵类别工具/资源说明查询run_sql、dry_run、query_cube、dry_plan语义层执行、校验、Cube 指标查询、纯规划上下文get_mdl、list_models、describe_model、get_data_source、list_cubes、describe_cube、list_functionsMDL 与数据源自省知识get_instructions、recall_queries、get_context、describe_schema、list_stored_queries、list_knowledge业务规则、语义检索、schema 描述写入store_query仅--allow-write时注册持久化确认的 NL→SQL 对资源wren://mdl、wren://instructions、wren://project、wren://agents、wren://knowledge/{name}LLM 可直接读取的上下文提示wren_workflow回答数据问题的标准操作流程SOP关键设计细节run_sql默认行数上限 1000硬上限 10000DEFAULT_ROW_LIMIT 1000、MAX_ROW_LIMIT 10000负数 limit 直接拒绝查询采用N1 截断探测请求 N 行时实际取 N1若多出 1 行则返回truncated: true并切片到 N让 Agent 知道结果被截断Cube 查询走SQL 内嵌行数上限路线_query_cube_with_limit_probe保证LIMIT/OFFSET顺序合法并约束先物化后切片型连接器_normalize_value递归把 datetime/Decimal/bytes/NaN 等转成 JSON 原生类型保证 MCP 响应可序列化wren://knowledge/{name}资源对路径做了resolve()逃逸校验mcp_server.py拒绝任何越出knowledge/目录的路径。六、连接器健壮性战役v0.10.0—v0.13.4分号、LIMIT 与凭据v0.13.x 版本线中占比最大的是跨连接器的健壮性修复可以归纳为三大战役。6.1 尾随分号剥离trailing semicolon连接器常对用户 SQL 做子查询包裹或 EXPLAIN而引擎拒绝这些形态内的尾随分号如SELECT * FROM (SELECT 1;)或EXPLAIN SELECT 1;。connector/base.py 提供统一的strip_trailing_semicolon仅剥离结尾的分号与空白序列字符串字面量中的分号SELECT a;b得以保留。各版本逐连接器落地了该修复v0.11.0athena、canner、clickhouse、databricks、datafusion、postgres、redshift、snowflake、trinov0.12.0athenadry_run 前、databricks子查询包裹前、datafusion、oracle、postgres、redshiftv0.13.1connector 公共 dry_run 路径、mssqlsqlglot LIMIT 重写前v0.13.2duckdb、oracle、redshift、sparksql/dry_run 前、bigqueryv0.13.3sparkDataFrame.limit前v0.13.4wren 查询路径整体只接受只读 SELECT#2679对应单元测试可在 core/wren/tests/unit 中看到大量专项文件例如test_athena_semicolon.py、test_bigquery_semicolon.py、test_duckdb_semicolon_unlimited.py、test_mssql_semicolon.py、test_oracle_semicolon.py、test_postgres_semicolon_unlimited.py、test_spark_semicolon.py、test_trino_semicolon_unlimited.py、test_strip_trailing_semicolon.py等。6.2 LIMIT 下推pushdownunlimited query path指绕过 SQL 层、由连接器直接施加行数限制的路径。v0.13.x 多处把 LIMIT 推进 SQL 或提前到取数之前bigquery把 LIMIT 推入 SQL#2465athenawrap 时推 LIMIT#2457snowflakewrap 时推 LIMIT 并剥离分号#2456spark在toPandas之前用DataFrame.limit施加限制#2574避免全量取回 Python 端再切mssql展平分页包裹时保留外层 CTE 与 ORDER BY#2579。6.3 连接 URL 凭据与 SSL 修复URL 凭据解码oracle、trino、clickhouse、mssql 等在 v0.12.0/v0.13.0 中统一了connection_url中凭据与 database 的 URL 解码unquote而非unquote_plus并对 userinfo 中的方括号做 sanitize#2434、#2435、#2436、#2447、#2448、#2454、#2367SSLtrino 对verifyfalse的 URL/kwargs 做 SSL 连接类型强转#2481默认端口clickhouse 无端口clickhousehttpsURL 默认 8443 而非 8123且secure通过 kwargs/query 参数切换时对默认端口做调和#2412、#2426。6.4 数值精度保留PostgreSQL未约束的NUMERIC精度保留#2655MySQL/Doris宽 decimal 保留#2657Athena/TrinoDECIMAL(p)视为 scale 0而非默认的非零 scale#2403、#2404。6.5 会话上下文缓存与超时v0.13.3 将会话上下文缓存绑定为 32 个 LRU 条目#2628 中可见lru_cache(maxsize32)且缓存键包含按查询提取的最小 manifest裸TimeoutError统一分类为DatabaseTimeoutError#2654对应 engine.py 中query/dry_run对TimeoutError的捕获转换v0.13.4 连接改用 autocommit使失败语句无法污染连接#2683——这正是 policy.py 文档所强调的planned SQL 会被连接器原样执行且多个连接器以autocommitTrue运行写操作一旦到达数据库即持久化。七、只读查询治理与安全加固贯穿 v0.8.0—v0.13.47.1 只读 SELECT 强制始终开启v0.13.4 起查询路径只接受只读 SELECT 语句#2679但这实际是 policy 模块一直内置的能力。policy.py 的实现分两层根节点白名单仅允许Select、SetOperationUNION/INTERSECT/EXCEPT、Subquery、Values全树扫描枚举拒绝Alter、Create、Delete、Drop、Insert、Update、Merge、TruncateTable、Grant、Copy、LockFOR UPDATE/FOR SHARE、IntoT-SQLSELECT ... INTO、Block多语句、Commandsqlglot 无法建模的语法兜底等节点并以exp.DDL/exp.DML标记类作为第二道网防止未来 sqlglot 升级引入新变更节点类型被漏判。特别注意 PostgreSQL 的数据修改 CTEWITH x AS (DELETE ... RETURNING *) SELECT * FROM x根节点是Select因此必须做全树扫描而非只看根。v0.13.4 还新增validate_planned_sqlpolicy.py由于 CTE 重写会内联视图语句和模型ref_sql一个无辜的SELECT * FROM some_view可能产出变更语句所以在执行前对planned SQL再校验一次该检查对解析失败采取 fail-open避免拒绝转译器的方言输出。7.2 strict mode 与表值函数治理v0.12.0 开始治理所有位置的读数据 TVF并结构化 source-func 白名单#2419v0.12.0 还阻止 JOIN 位置的表值函数#2405。strict mode 下三类函数被区别对待类别示例处置数据/文件读取器C 类read_csv、read_parquet、glob、pg_read_file、dblink、postgres_scan、load_file、url、iceberg_scan等所有 AST 位置一律阻止防路径穿越/SSRF/横向移动合成生成器B 类generate_series、sequence、range默认阻止无界范围是 DoS 向量可通过allowed_source_functions显式放行行展开算子A 类UNNEST、FLATTEN/EXPLODE允许仅重组已在查询作用域内的数组/结构表达式值得注意的实现细节数据读取器检测先于 source 位置检查执行_check_data_readers因此UNNEST(read_csv(...))这种内嵌逃逸也被拦截policy.py错误信息只报告函数名而绝不回显函数参数如文件路径、URL、DSN避免敏感目标泄露policy.py函数名匹配同时比对原始名称与 sqlglot 规范类键如read_csv→exp.ReadCSV→readcsv并在 10 种方言下探测展开保证用户写的名字无论被 sqlglot 解析成哪个类都能命中policy.pyLATERAL FLATTEN(...)这类 LATERAL 包裹的 TVF 也会被解包检查堵住经 JOIN 到达 TVF的漏洞policy.py。对应的测试覆盖可见 core/wren/tests/unit/test_policy.py。7.3 其他安全与稳定性修复路径穿越防护context 升级路径防穿越#2649、导入路径在强制清理前校验#2580、v1 视图升级拒绝两个视图映射到同一目标#2696profile 密钥遮蔽v0.13.1 起wren profile debug遮蔽所有 registry 敏感字段#2492v0.13.2 扩展到 kwargs 与 settings 下嵌套的密钥#2525并排除connection_url作为可选项数据源#2527非结构数据容错大量skip non-dict rows / non-list models修复memory、schema_indexer、type_mapping、genbi apps.yml、vercel JSON 等防止来自动态 schema 导出器的脏数据使索引、检索或部署崩溃对应测试如 test_genbi_list_nondict.py、test_schema_indexer_extract_nonduct.py、test_vercel_request_json.py依赖安全多次 bump 传递依赖以修复 Dependabot/安全通告#2458、#2529、#2330。八、memory 记忆层从 LanceDB 到 markdown source of truthmemory 层是 WrenAI 区别于纯 SQL 引擎的核心能力其命令体系在 v0.3.0 到 v0.12.0 间逐步完备版本命令/能力v0.3.0LanceDB 记忆层schema query 检索、list/forget/dump/loadv0.10.0CLI 用find_spec延迟检测 memory extra性能v0.11.0memory 与 LanceDB 解耦knowledge/成为一等公民v0.12.0wren memory watch自动重索引#2418从 memory/cli.py 可以看到完整命令族index、describe、fetch、store、recall、status、reset、check、watch、export、list、forget。几个关键设计双后端安装wrenai[memory]时走 LanceDB embedding 语义检索未安装时自动回退 grep 后端——直接读取knowledge/sql/*.md做 token 重叠匹配。wren memory index在 grep 后端下无需构建索引knowledge/sql/ IS the indexmarkdown 为真相store始终先写knowledge/sql/slug.mdLanceDB 索引只是 best-effort 的派生层reset只丢弃派生索引而保留 markdownexport用于一次性迁移——把 LanceDB 的 query_history 导回 markdownwatch 自愈以--interval默认 5 秒轮询target/mdl.json与knowledge/sql/的内容指纹变化即触发重索引失败的 reindex 保持 pending 状态并在下一轮重试更新永不静默丢失memory/cli.py。--mdl若指向被监视项目根之外会快速失败防止跨项目索引污染。九、GenBI语义层 → 可分享 Web 应用v0.10.0—v0.13.4v0.10.0 引入 GenBI app 构建与部署#2348。关键机制CLI 不直接建应用genbi build只是输出一份项目水合的构建指令静态模板 实时项目事实 用户 prompt由 Agent 据此构建静态应用composer.pywren-core-wasm 驱动浏览器端引擎应用通过 CDN 引入wrenai/wren-core-wasmcomposer 中固定版本0.4.1在浏览器内WrenEngine.init()→engine.loadMDL(mdl, profile)→engine.query(sql)无需后端两种数据模式snapshot数据随应用走导出 parquet/.duckdb 作为静态资源完全 serverless浏览器客户端直接查询live应用在查询时回连用户自己的数仓/API。硬性规则仓库凭据绝不内联进应用——应用是公开静态站点wren genbi verify会尽力扫描内联凭据最佳努力非保证应用名校验_APP_NAME_RE只允许[A-Za-z0-9][A-Za-z0-9_-]*阻止../../etc这类路径逃逸genbi/cli.py。仓库 examples/v5-jaffle/apps/sales-report 就是一个真实构建产物index.htmlmdl.json的静态应用。相关测试包括 test_genbi_build.py、test_genbi_deploy.py、test_genbi_verify.py。十、跨方言类型映射v0.12.0v0.12.0 在type_mapping中新增跨方言类型翻译#2410 源码看提供四层 APIAPI功能示例parse_type(type_str, dialect)规范化类型字符串parse_type(character varying(255), postgres)→VARCHAR(255)parse_types(columns, dialect)批量规范化跳过非 mapping 行每列追加type键translate_type(type_str, src, dst)跨方言翻译translate_type(int8, postgres, bigquery)→INT64translate_types(columns, src, dst)批量翻译同上批量版实现统一基于 sqlglot 的DataType解析且捕获SqlglotError同时覆盖ParseError与TokenErrorv0.13.0 起后回退原字符串。批量 API 接受任意collections.abc.Mapping如 SQLAlchemyRowMapping并跳过非 dict 脏行与 CHANGELOG 中大量skip non-dict rows修复呼应。parse/translate_types的 skipped 行还会在 CLI 的wren-cli parse/translate-types中显式报告#2570。十一、如何查阅与验证这些能力要在本地复现本 CHANGELOG 所描述的能力可以从以下路径入手安装pip install wrenai[数据源,memory]数据源可选postgres、mysql、bigquery、snowflake、clickhouse、trino、mssql、databricks、redshift、spark、athena、oracle等阅读文档cli.md 与 connections.md 是 CLI 与连接器的权威参考查看项目范例examples/v5-jaffle 展示了 v5 布局的完整结构skills/wren/SKILL.md 给出 Agent 使用 wrenai 的准则运行测试核心单元测试位于 core/wren/tests/unit连接器测试位于 core/wren/tests/connectors其中每个分号/LIMIT/精度修复都有对应专项测试文件可作为行为契约。十二、总结从core/wren/CHANGELOG.md可以清晰地读出 WrenAI 的演进哲学语义层优先一切查询都经由 MDL 模型名CTE 重写器负责把模型展开为可执行 SQLpolicy 层在输入与输出两侧双重把关只读与治理连接器健壮性是一等公民20 数据源的分号剥离、LIMIT 下推、凭据解码、精度保留构成了 v0.13.x 的主旋律配套的专项测试使跨方言行为可回归面向 Agent 设计MCP 工具矩阵、AGENTS.md 自动生成、memory 记忆层、GenBI 构建指令全部服务于让 AI Agent 可信地完成从自然语言到 SQL 再到可分享应用的闭环安全内建而非外挂路径穿越防护、凭据遮蔽、数据读取器全位置拦截、函数名规范化匹配体现了面向多租户与公网部署的治理考量。对于想要理解开源、受治理的 text-to-SQL 语义层如何落地为工程实现的开发者这份 CHANGELOG 与其背后的源码、测试构成了完整的学习与复用素材。【免费下载链接】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（wrenai）Changelog 深度解读：从 wren-engine 到生成式 BI 语义层的版本演进全览
WrenAIwrenaiChangelog 深度解读从 wren-engine 到生成式 BI 语义层的版本演进全览【免费下载链接】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本文以 WrenAI 仓库中core/wren/CHANGELOG.md为主线系统梳理wrenai原wren-engine从 v0.3.0 到 v0.13.4 的功能演进、连接器健壮性修复、安全治理与 GenBI 能力落地并结合 engine.py、policy.py、mcp_server.py 等源码说明每个版本变更背后的实现原理。读完本文你将掌握 wrenai CLI 的核心命令体系、跨 20 数据源的 SQL 语义层工作机制以及 2026 年该版本线中最重要的架构决策v5 项目布局、GenBI 应用构建、内存层去 LanceDB 耦合。一、版本线概览一条从 SQL 引擎走向 GenBI 平台的演进路径core/wren/CHANGELOG.md记录了wrenai包PyPI 原名wren-engine从 2026-04 到 2026-09 的持续演进。按主题可划分为三条主线演进主线代表版本核心内容语义层与 CLI 体系成型v0.3.0 → v0.6.0CTE 重写器、context 管理、profile、memory 层、WASM 支持、refSql 模型连接器大规模加固v0.7.0 → v0.13.420 数据源的分号剥离、LIMIT 下推、URL 凭据解码、SSL 修复、精度保留GenBI 与治理能力落地v0.8.0 → v0.13.4dbt 导入、OSI 语义模型、Cube 支持、GenBI app 构建部署、MCP 能力服务该版本线中最重要的转折点是 v0.7.0PyPI 包名从wren-engine正式更名为wrenai#2315这是仓库向生成式 BI 平台定位转型的标志性动作——正如仓库项目描述所言目标是把自然语言问题转译为可信的看板、图表和 SQL。README 也随之改为 Wren AI 品牌。二、v0.3.0—v0.4.0CLI 语义层的奠基2.1 CTE 式 SQL 规划v0.3.0 引入CTE-based SQL planning with per-model expansion#1479这是整个语义层的执行核心。从 engine.py 的dry_plan可以看出完整转换流水线用户 SQL目标方言如 Postgres → sqlglot parse目标方言 → qualify_tables normalize_identifiers qualify_columns → 识别引用的模型与列 → 逐模型wren-core transform_sql → Wren 方言 SQL → 逐模型sqlglot parseWren 方言→ 注入为 CTE → sqlglot generate目标方言 → 输出带模型 CTE 的目标方言 SQLcte_rewriter.py 对视图的处理方式与模型不同视图的statement是原生 SQL直接原样注入为 CTE不经过 wren-core其引用的模型则先以模型 CTE 形式前置从而保持视图作为可执行 SQL 的语义完整性。SELECT *的保留#1536则保证了通配查询在重写后不丢列。2.2 context 管理与 AGENTS.md 生成v0.3.0 的 CLI 0.2.0 大版本#1522 中给出了 Agent 回答数据问题的标准流程wren memory fetch -q question获取相关 schema 上下文wren memory recall -q question --limit 3查找相似历史查询使用 MDL 模型名而非原始表名编写 SQLwren --sql sql通过语义层执行wren memory store --nl question --sql sql保存确认结果2.3 .env 驱动的 profile 密钥管理v0.4.0 引入.env驱动的 profile 密钥与自动连接验证#1588 源码可见关键设计profile 中允许${VAR}占位符**在连接时而非保存时**通过expand_profile_secrets解析存储的 YAML 始终保留占位符因此wren profile debug永远不会打印真实密钥。环境变量加载顺序为$CWD/.env→ 项目根.env→~/.wren/.env且overrideFalse保证 shell 中已有的环境变量优先级最高。${VAR}名称被限制为[_A-Z][_A-Z0-9]*这样真实密码中的小写花括号序列如${foo}不会被误匹配。三、v0.5.0—v0.6.0引擎并入主仓库与 profile 绑定v0.5.0wren-engine作为独立仓库被导入到core/目录#2209从此与 wren-coreRust、wren-core-wasm 等模块同仓管理。v0.6.0context 支持将连接 profile 绑定到项目#2251profile 从全局配置演进为可随项目分发。四、v0.7.0—v0.8.0品牌更名、Cube 与 dbt/OSI 生态接入4.1 包名更名Breaking Changev0.7.0 将 PyPI 包名从wren-engine改为wrenai#2315。对使用者而言安装命令变为pip install wrenai[postgres,memory,ui]其中memoryextra 启用基于 embedding 的语义检索ui启用交互式界面。该 extra 机制在context.py生成的 AGENTS.md 模板和 memory CLI 的报错提示中均有体现例如pip install wrenai[memory]。4.2 Cube 全链路支持v0.7.0 的 wasm 模块实现了完整 Cube 支持——验证、翻译、PyO3、CLI、WASM、文档全链路覆盖#2282。在 CLI 中对应wren cube命令族MCP 服务器则暴露query_cube工具见下文。4.3 dbt 导入与 OSI 语义模型v0.8.0新增 dbt 导入工作流#2279 目录中可看到minimal.yaml、multi_semantic_model.yaml、tpcds_full.yaml等测试样例。v0.8.0同时修复了 SQL 标识符大小写在 policy、extract 与 CTE rewriter 三处的一致性#2310这正是 policy.py 中resolve_model_name所实现的双规则带引号的标识符必须大小写精确匹配不带引号的标识符优先精确匹配、失败后回退大小写不敏感扫描且多个候选时选择字典序最小者以保证跨进程结果确定。五、v0.9.0—v0.11.0MCP 服务、知识/技能分发与 v5 项目布局5.1 查询 MDL 视图与技能分发v0.9.0 让 SDK 重写器和 strict mode 支持查询 MDL 视图#2334 与各skills_content/模板如generate-mdl、enrich-context、onboarding。v0.10.0 支持 wren-core 的复合多列主键#2345并从 folder-per-entity 布局加载 cubes#2350。5.2 v5 项目布局schema_version 5v0.11.0 是架构性版本引入 v5 项目布局#2386、#2399knowledge/ 成为一等公民业务规则knowledge/rules/*.md、NL→SQL 示例knowledge/sql/*.md、术语表、指标说明统一收纳在项目内随项目一起版本管理memory 与 LanceDB 解耦语义索引不再是唯一真相knowledge/sql/*.md成为记忆的 source of truthLanceDB 只是可重建的派生索引同版本还带来 CTE 重写器的大小写感知列/模型绑定#2400并对 schema_version 5 的升级测试做了配套修复#2388。仓库中的 examples/v5-jaffle 就是 v5 布局的完整范例models/、views/、cubes/、knowledge/、relationships.yml、wren_project.yml一应俱全。MCP 服务器的wren://project资源会同时报告schema_version与knowledge_schema_version见 mcp_server.py。5.3 MCP 能力服务v0.13.0v0.13.0 通过 MCP 暴露项目能力#2438。从 mcp_server.py 可看到完整的工具矩阵类别工具/资源说明查询run_sql、dry_run、query_cube、dry_plan语义层执行、校验、Cube 指标查询、纯规划上下文get_mdl、list_models、describe_model、get_data_source、list_cubes、describe_cube、list_functionsMDL 与数据源自省知识get_instructions、recall_queries、get_context、describe_schema、list_stored_queries、list_knowledge业务规则、语义检索、schema 描述写入store_query仅--allow-write时注册持久化确认的 NL→SQL 对资源wren://mdl、wren://instructions、wren://project、wren://agents、wren://knowledge/{name}LLM 可直接读取的上下文提示wren_workflow回答数据问题的标准操作流程SOP关键设计细节run_sql默认行数上限 1000硬上限 10000DEFAULT_ROW_LIMIT 1000、MAX_ROW_LIMIT 10000负数 limit 直接拒绝查询采用N1 截断探测请求 N 行时实际取 N1若多出 1 行则返回truncated: true并切片到 N让 Agent 知道结果被截断Cube 查询走SQL 内嵌行数上限路线_query_cube_with_limit_probe保证LIMIT/OFFSET顺序合法并约束先物化后切片型连接器_normalize_value递归把 datetime/Decimal/bytes/NaN 等转成 JSON 原生类型保证 MCP 响应可序列化wren://knowledge/{name}资源对路径做了resolve()逃逸校验mcp_server.py拒绝任何越出knowledge/目录的路径。六、连接器健壮性战役v0.10.0—v0.13.4分号、LIMIT 与凭据v0.13.x 版本线中占比最大的是跨连接器的健壮性修复可以归纳为三大战役。6.1 尾随分号剥离trailing semicolon连接器常对用户 SQL 做子查询包裹或 EXPLAIN而引擎拒绝这些形态内的尾随分号如SELECT * FROM (SELECT 1;)或EXPLAIN SELECT 1;。connector/base.py 提供统一的strip_trailing_semicolon仅剥离结尾的分号与空白序列字符串字面量中的分号SELECT a;b得以保留。各版本逐连接器落地了该修复v0.11.0athena、canner、clickhouse、databricks、datafusion、postgres、redshift、snowflake、trinov0.12.0athenadry_run 前、databricks子查询包裹前、datafusion、oracle、postgres、redshiftv0.13.1connector 公共 dry_run 路径、mssqlsqlglot LIMIT 重写前v0.13.2duckdb、oracle、redshift、sparksql/dry_run 前、bigqueryv0.13.3sparkDataFrame.limit前v0.13.4wren 查询路径整体只接受只读 SELECT#2679对应单元测试可在 core/wren/tests/unit 中看到大量专项文件例如test_athena_semicolon.py、test_bigquery_semicolon.py、test_duckdb_semicolon_unlimited.py、test_mssql_semicolon.py、test_oracle_semicolon.py、test_postgres_semicolon_unlimited.py、test_spark_semicolon.py、test_trino_semicolon_unlimited.py、test_strip_trailing_semicolon.py等。6.2 LIMIT 下推pushdownunlimited query path指绕过 SQL 层、由连接器直接施加行数限制的路径。v0.13.x 多处把 LIMIT 推进 SQL 或提前到取数之前bigquery把 LIMIT 推入 SQL#2465athenawrap 时推 LIMIT#2457snowflakewrap 时推 LIMIT 并剥离分号#2456spark在toPandas之前用DataFrame.limit施加限制#2574避免全量取回 Python 端再切mssql展平分页包裹时保留外层 CTE 与 ORDER BY#2579。6.3 连接 URL 凭据与 SSL 修复URL 凭据解码oracle、trino、clickhouse、mssql 等在 v0.12.0/v0.13.0 中统一了connection_url中凭据与 database 的 URL 解码unquote而非unquote_plus并对 userinfo 中的方括号做 sanitize#2434、#2435、#2436、#2447、#2448、#2454、#2367SSLtrino 对verifyfalse的 URL/kwargs 做 SSL 连接类型强转#2481默认端口clickhouse 无端口clickhousehttpsURL 默认 8443 而非 8123且secure通过 kwargs/query 参数切换时对默认端口做调和#2412、#2426。6.4 数值精度保留PostgreSQL未约束的NUMERIC精度保留#2655MySQL/Doris宽 decimal 保留#2657Athena/TrinoDECIMAL(p)视为 scale 0而非默认的非零 scale#2403、#2404。6.5 会话上下文缓存与超时v0.13.3 将会话上下文缓存绑定为 32 个 LRU 条目#2628 中可见lru_cache(maxsize32)且缓存键包含按查询提取的最小 manifest裸TimeoutError统一分类为DatabaseTimeoutError#2654对应 engine.py 中query/dry_run对TimeoutError的捕获转换v0.13.4 连接改用 autocommit使失败语句无法污染连接#2683——这正是 policy.py 文档所强调的planned SQL 会被连接器原样执行且多个连接器以autocommitTrue运行写操作一旦到达数据库即持久化。七、只读查询治理与安全加固贯穿 v0.8.0—v0.13.47.1 只读 SELECT 强制始终开启v0.13.4 起查询路径只接受只读 SELECT 语句#2679但这实际是 policy 模块一直内置的能力。policy.py 的实现分两层根节点白名单仅允许Select、SetOperationUNION/INTERSECT/EXCEPT、Subquery、Values全树扫描枚举拒绝Alter、Create、Delete、Drop、Insert、Update、Merge、TruncateTable、Grant、Copy、LockFOR UPDATE/FOR SHARE、IntoT-SQLSELECT ... INTO、Block多语句、Commandsqlglot 无法建模的语法兜底等节点并以exp.DDL/exp.DML标记类作为第二道网防止未来 sqlglot 升级引入新变更节点类型被漏判。特别注意 PostgreSQL 的数据修改 CTEWITH x AS (DELETE ... RETURNING *) SELECT * FROM x根节点是Select因此必须做全树扫描而非只看根。v0.13.4 还新增validate_planned_sqlpolicy.py由于 CTE 重写会内联视图语句和模型ref_sql一个无辜的SELECT * FROM some_view可能产出变更语句所以在执行前对planned SQL再校验一次该检查对解析失败采取 fail-open避免拒绝转译器的方言输出。7.2 strict mode 与表值函数治理v0.12.0 开始治理所有位置的读数据 TVF并结构化 source-func 白名单#2419v0.12.0 还阻止 JOIN 位置的表值函数#2405。strict mode 下三类函数被区别对待类别示例处置数据/文件读取器C 类read_csv、read_parquet、glob、pg_read_file、dblink、postgres_scan、load_file、url、iceberg_scan等所有 AST 位置一律阻止防路径穿越/SSRF/横向移动合成生成器B 类generate_series、sequence、range默认阻止无界范围是 DoS 向量可通过allowed_source_functions显式放行行展开算子A 类UNNEST、FLATTEN/EXPLODE允许仅重组已在查询作用域内的数组/结构表达式值得注意的实现细节数据读取器检测先于 source 位置检查执行_check_data_readers因此UNNEST(read_csv(...))这种内嵌逃逸也被拦截policy.py错误信息只报告函数名而绝不回显函数参数如文件路径、URL、DSN避免敏感目标泄露policy.py函数名匹配同时比对原始名称与 sqlglot 规范类键如read_csv→exp.ReadCSV→readcsv并在 10 种方言下探测展开保证用户写的名字无论被 sqlglot 解析成哪个类都能命中policy.pyLATERAL FLATTEN(...)这类 LATERAL 包裹的 TVF 也会被解包检查堵住经 JOIN 到达 TVF的漏洞policy.py。对应的测试覆盖可见 core/wren/tests/unit/test_policy.py。7.3 其他安全与稳定性修复路径穿越防护context 升级路径防穿越#2649、导入路径在强制清理前校验#2580、v1 视图升级拒绝两个视图映射到同一目标#2696profile 密钥遮蔽v0.13.1 起wren profile debug遮蔽所有 registry 敏感字段#2492v0.13.2 扩展到 kwargs 与 settings 下嵌套的密钥#2525并排除connection_url作为可选项数据源#2527非结构数据容错大量skip non-dict rows / non-list models修复memory、schema_indexer、type_mapping、genbi apps.yml、vercel JSON 等防止来自动态 schema 导出器的脏数据使索引、检索或部署崩溃对应测试如 test_genbi_list_nondict.py、test_schema_indexer_extract_nonduct.py、test_vercel_request_json.py依赖安全多次 bump 传递依赖以修复 Dependabot/安全通告#2458、#2529、#2330。八、memory 记忆层从 LanceDB 到 markdown source of truthmemory 层是 WrenAI 区别于纯 SQL 引擎的核心能力其命令体系在 v0.3.0 到 v0.12.0 间逐步完备版本命令/能力v0.3.0LanceDB 记忆层schema query 检索、list/forget/dump/loadv0.10.0CLI 用find_spec延迟检测 memory extra性能v0.11.0memory 与 LanceDB 解耦knowledge/成为一等公民v0.12.0wren memory watch自动重索引#2418从 memory/cli.py 可以看到完整命令族index、describe、fetch、store、recall、status、reset、check、watch、export、list、forget。几个关键设计双后端安装wrenai[memory]时走 LanceDB embedding 语义检索未安装时自动回退 grep 后端——直接读取knowledge/sql/*.md做 token 重叠匹配。wren memory index在 grep 后端下无需构建索引knowledge/sql/ IS the indexmarkdown 为真相store始终先写knowledge/sql/slug.mdLanceDB 索引只是 best-effort 的派生层reset只丢弃派生索引而保留 markdownexport用于一次性迁移——把 LanceDB 的 query_history 导回 markdownwatch 自愈以--interval默认 5 秒轮询target/mdl.json与knowledge/sql/的内容指纹变化即触发重索引失败的 reindex 保持 pending 状态并在下一轮重试更新永不静默丢失memory/cli.py。--mdl若指向被监视项目根之外会快速失败防止跨项目索引污染。九、GenBI语义层 → 可分享 Web 应用v0.10.0—v0.13.4v0.10.0 引入 GenBI app 构建与部署#2348。关键机制CLI 不直接建应用genbi build只是输出一份项目水合的构建指令静态模板 实时项目事实 用户 prompt由 Agent 据此构建静态应用composer.pywren-core-wasm 驱动浏览器端引擎应用通过 CDN 引入wrenai/wren-core-wasmcomposer 中固定版本0.4.1在浏览器内WrenEngine.init()→engine.loadMDL(mdl, profile)→engine.query(sql)无需后端两种数据模式snapshot数据随应用走导出 parquet/.duckdb 作为静态资源完全 serverless浏览器客户端直接查询live应用在查询时回连用户自己的数仓/API。硬性规则仓库凭据绝不内联进应用——应用是公开静态站点wren genbi verify会尽力扫描内联凭据最佳努力非保证应用名校验_APP_NAME_RE只允许[A-Za-z0-9][A-Za-z0-9_-]*阻止../../etc这类路径逃逸genbi/cli.py。仓库 examples/v5-jaffle/apps/sales-report 就是一个真实构建产物index.htmlmdl.json的静态应用。相关测试包括 test_genbi_build.py、test_genbi_deploy.py、test_genbi_verify.py。十、跨方言类型映射v0.12.0v0.12.0 在type_mapping中新增跨方言类型翻译#2410 源码看提供四层 APIAPI功能示例parse_type(type_str, dialect)规范化类型字符串parse_type(character varying(255), postgres)→VARCHAR(255)parse_types(columns, dialect)批量规范化跳过非 mapping 行每列追加type键translate_type(type_str, src, dst)跨方言翻译translate_type(int8, postgres, bigquery)→INT64translate_types(columns, src, dst)批量翻译同上批量版实现统一基于 sqlglot 的DataType解析且捕获SqlglotError同时覆盖ParseError与TokenErrorv0.13.0 起后回退原字符串。批量 API 接受任意collections.abc.Mapping如 SQLAlchemyRowMapping并跳过非 dict 脏行与 CHANGELOG 中大量skip non-dict rows修复呼应。parse/translate_types的 skipped 行还会在 CLI 的wren-cli parse/translate-types中显式报告#2570。十一、如何查阅与验证这些能力要在本地复现本 CHANGELOG 所描述的能力可以从以下路径入手安装pip install wrenai[数据源,memory]数据源可选postgres、mysql、bigquery、snowflake、clickhouse、trino、mssql、databricks、redshift、spark、athena、oracle等阅读文档cli.md 与 connections.md 是 CLI 与连接器的权威参考查看项目范例examples/v5-jaffle 展示了 v5 布局的完整结构skills/wren/SKILL.md 给出 Agent 使用 wrenai 的准则运行测试核心单元测试位于 core/wren/tests/unit连接器测试位于 core/wren/tests/connectors其中每个分号/LIMIT/精度修复都有对应专项测试文件可作为行为契约。十二、总结从core/wren/CHANGELOG.md可以清晰地读出 WrenAI 的演进哲学语义层优先一切查询都经由 MDL 模型名CTE 重写器负责把模型展开为可执行 SQLpolicy 层在输入与输出两侧双重把关只读与治理连接器健壮性是一等公民20 数据源的分号剥离、LIMIT 下推、凭据解码、精度保留构成了 v0.13.x 的主旋律配套的专项测试使跨方言行为可回归面向 Agent 设计MCP 工具矩阵、AGENTS.md 自动生成、memory 记忆层、GenBI 构建指令全部服务于让 AI Agent 可信地完成从自然语言到 SQL 再到可分享应用的闭环安全内建而非外挂路径穿越防护、凭据遮蔽、数据读取器全位置拦截、函数名规范化匹配体现了面向多租户与公网部署的治理考量。对于想要理解开源、受治理的 text-to-SQL 语义层如何落地为工程实现的开发者这份 CHANGELOG 与其背后的源码、测试构成了完整的学习与复用素材。【免费下载链接】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），仅供参考
