开源项目调研 · 技术选型参考

WrenAI

当前活跃分支已不是旧版 Docker 聊天式 BI 应用，而是一套面向 AI Agent 的「可版本化上下文包 + 语义 SQL 规划器 + 多数据源执行适配 + MCP/CLI/SDK」工具链。Agent 负责编排生成，Wren 负责建模、规划、校验、执行、召回与交付门禁。

定位　语义层 + NL2SQL 规划工具链仓库　Canner/WrenAI 许可　Apache-2.0（名称/logo 除外） 调研日　2026-08-23（源码级）

01产品定位与边界

它解决什么问题

让 Agent 使用显式业务语义而不是裸数据库 schema 写 SQL，并把可审查的模型、规则和成功样例作为项目资产（Git 友好）。它不内置大模型，当前 OSS 分支也没有完整聊天 UI（旧服务已移到 legacy/v1）。

对外表达 vs 实现事实（选型必读）

营销口径与代码实现有出入，采购判断须以代码 + PoC 为准：

对外表达	实现事实	选型影响
「22+ data sources」	代码实际枚举 20 个标识，且有复用（Doris 复用 MySQL，四种文件源复用 DuckDB）	不能等同于 22 个独立、同成熟度连接器；PoC 须逐项验证真实目标库
「GenBI 生成并部署仪表盘」	CLI 只输出构建指令，明确不写应用文件；实际由外部 Agent 编写静态应用	生成质量归属于外部 Agent 与模板，不是仓库内确定性生成器能力
「governed execution」	严格模式默认 false；只读语句检查始终开启	默认能阻止写语句，但不保证只能访问语义层对象；生产接入须显式加固

README 明确：GenBI UI、嵌入和访问控制属于商业版。当前 OSS 的主要人机界面是 CLI、MCP、Agent SDK 和少量配置网页表单。

02架构要点

技术栈与查询主链路

跨 Python / Rust / WASM 多包独立发布。Python 层主框架 Typer + 可选 FastMCP；Rust 语义层核心是 Apache DataFusion；Python/Rust 靠 PyO3 桥接；SQL AST 与方言用 SQLGlot；结果统一为 PyArrow；默认本地库 DuckDB；可选语义记忆用 LanceDB + sentence-transformers；另有浏览器内执行的 wren-core-wasm（约 68MB，单线程）。

用户 / Agent→ CLI / MCP / SDK→ 输入只读 + 严格策略→ SQLGlot CTE 重写→ Rust DataFusion 规划 + 反解析→ 最终 SQL 只读复检→ 目标数据库

核心是「先规划后执行」：Python 层做输入策略与 CTE 重写，跨 FFI 进 Rust 用 DataFusion 完成语义计划与优化，反解析回目标方言 SQL 后再做一次只读复检，最后才落到目标连接器，返回 Arrow 结果 + 截断标志 + 结构化错误。

状态与一致性

模型 / 关系 / cube / 规则 / 已确认查询是应提交 Git 的源资产；编译产物 target/mdl.json 可重建。
自然语言—SQL 对写成确定性 Markdown 源文件当真相源，LanceDB 只是可重建的派生索引。
远程数据库事务由各连接器和数据库负责，Wren 强调只读规划，无跨连接器事务协调。

03可借鉴的交互设计

最成熟的不是「一句话出答案」，而是把隐含步骤变成可观察可重试的原语

发现项目与 profile，读取模型和业务规则。
对 schema 做全量描述或按问题检索，召回相似且已确认的查询。
先 dry-plan 检查语义展开；复杂查询再对真实库 dry-run。
执行时设行数上限，返回列、行数和是否截断。
只有结果确认正确后才把自然语言—SQL 对写回知识源；写工具还需启动时显式允许。

可直接借鉴

把 schema、业务规则、历史成功查询分成不同检索入口，避免一次性塞进大 prompt。
把「查看最终 SQL」和「真实执行」分离，让人或 Agent 在副作用前看到转换结果。
工具结果显式返回 row_count、truncated、错误阶段（error phase）；写工具按能力开关注册。
profile 可项目固定也可回退全局；固定项失效时失败而不是静默访问另一个库。

需要调整（不要照搬）

「成功执行后默认沉淀」应加用户确认、数据分类、保留期限和审核状态；不应把错误但可执行的 SQL 自动当知识。
CLI 文本错误与 SDK 结构化 envelope 尚未统一；跨入口接入应定义一套稳定错误合同。
GenBI 应用生成由 Agent 完成，视觉质量、无障碍、真实运行验证需上层产品补齐。

04主要风险

接入前必须知道的限制

风险	缓解建议
严格治理非默认：strict_mode 默认 false，只依赖默认会允许读取语义层外的表	数据库用只读最小权限账号；强制开严格模式和禁用函数；加外部 SQL 网关
规划结果复检 fail-open：SQLGlot 无法解析时直接放行	高风险环境将无法解析视为拒绝，或让目标库只读事务成为最终防线
SQL 反解析有技术债：为绕开反解析问题禁用了多项 DataFusion 优化	用真实业务 SQL 黄金集覆盖目标方言；升级依赖时做差分回归
GenBI 验证不是运行验证：只做静态检查，不跑浏览器 / WASM smoke query	部署门禁加 headless browser、真实查询、可视回归、依赖供应链检查
成熟度：wrenai 标注 Beta，多包独立发版	固定组合版本，维护兼容矩阵，避免浮动下限直接进生产

05结论

是否建议引入或参照

引入 · 建议局部引入

最合适的对象是 wrenai 的 Python CLI/SDK 或 MCP 能力面，而不是整仓库和旧版 UI。前提是：目标方言黄金集、安全 PoC、只读数据库身份、严格模式、稳定版本组合、适配层隔离（上游只依赖本方定义的 plan / validate / execute / describe-context 接口）。若目标只是一次性 CSV 图表、已有成熟语义层，或要求企业级 RLS/CLS 与审计开箱即用，则不建议引入 OSS 主线。

参照 · 建议作设计参照

最值得参照：Git 友好的模型 / 规则 / 已确认查询三层上下文、先规划后执行、按阶段错误反馈、写能力显式授权、派生索引可重建、Agent 工作流渐进披露。最不应照搬：营销数字推导的连接器成熟度、自动沉淀成功查询、默认关闭严格模式、静态 GenBI 验证、浏览器承担大规模数据执行。

与锐识 AI 的直接意义：WrenAI 是三个项目里与「多智能体数据研究引擎」方向最对口的一个——语义层、查询规划、只读安全策略、结构化错误和 MCP 工具面已形成可组合闭环，是 NL2SQL / GenBI 方向的最佳参照标杆。

06来源

关键来源

仓库：https://github.com/Canner/WrenAI（分析基于固定提交 f2841bc…）
本地源码级分析：项目一/核心开源项目文档/WrenAI项目分析/（含语义查询规划、Agent 上下文记忆、GenBI 交付边界三篇专题）

方法与限制：仅静态阅读源码、配置、测试目录与官方文档；未安装依赖、未构建 / 测试 / 启动服务。所有运行性能、真实目标库兼容、MCP HTTP 安全、部署交互均未验证。