WrenAI

1. 项目概览

2. 它主要能做什么

WrenAI 解决的是企业数据分析 Agent 的一个核心问题：大模型能看见数据库 schema，但 schema 并不等于业务语义。真实客户问“本月活跃客户”“退款收入”“项目 Lighthouse 转化率”时，数据库里往往只有各种表、字段、枚举值和历史命名，缺少业务定义、标准口径、批准过的 join 路径和历史成功查询。让 LLM 直接猜 SQL，很容易生成看起来合理但实际错误的结果。

WrenAI 的做法是在数据源和 AI Agent 中间放一个开放上下文层。这个上下文层通过 MDL、业务规则、记忆、校验和 connector，让 Agent 不直接碰原始表，而是通过被建模、被审核、可复用的业务语义来生成 SQL 和 Dashboard。

可以把它理解为：

它主要提供三件事：

3. 和旧版 Wren GenBI Classic 的区别

这个点非常重要。很多客户看到 WrenAI 可能以为它是一个开箱即用的聊天式 BI Web 产品，但当前主线已经不是这个形态。

售前时建议直接说明：如果客户要的是“立即部署一个完整 Web BI SaaS”，当前开源主线并不是最佳答案；如果客户要的是“让 Agent 可信地访问企业数据、生成 SQL、生成 Dashboard”，WrenAI 的定位就很清楚。

4. 核心概念

4.1 GenBI

GenBI 在 WrenAI 的语境中不是简单“AI 生成图表”。它是 Agent 基于可信上下文完成从问题、SQL、图表到 Dashboard 的链路。

典型流程：

1. 用户向 Agent 提问，例如“按月份展示今年收入趋势，并区分退款状态”。
2. Agent 使用 Wren 的 skill 获取工作流。
3. Wren memory 召回相关模型、字段、业务规则和历史 SQL。
4. Agent 编写基于 MDL 模型的 SQL，而不是直接猜原始表。
5. Wren dry-plan 展开并校验 SQL。
6. Wren 执行查询并返回结果。
7. Agent 可进一步生成 Dashboard app，并通过 Vercel 或 Cloudflare Pages 发布。

4.2 Context Layer 上下文层

官方文档把 WrenAI 定位为 open context layer。它补足数据库 schema 没有表达的业务语义，例如：

• status = 4 在业务上代表 refunded。
• “活跃客户”排除测试账号或服务账号。
• 某个团队实际使用的是 loyalty_v3，不是历史遗留表。
• “Project Lighthouse” 需要映射到某个 campaign_id。
• “收入”应该使用 approved revenue 口径，而不是随便 SUM 一个金额字段。

官方文档里的关键示意图很好地表达了“缺少上下文层”和“引入 WrenAI 后”的差异：

4.3 MDL

MDL 是 Modeling Definition Language，用 YAML 文件描述模型、字段、关系、视图、cube、指标、权限等。它把原始数据库结构转成 Agent 可使用的业务语义表面。

一个极简例子：

name: orders
table_reference:
  schema: public
  table: orders
columns:
  - name: order_id
    type: integer
  - name: customer_id
    type: integer
  - name: total
    type: double
  - name: status
    type: varchar
primary_key: order_id

售前解释可以说：MDL 相当于把企业数据字典、指标口径、可用字段、join 关系变成 AI 能读、工程能审、Git 能管的文件。

4.4 Memory

Memory 使用本地 LanceDB 语义记忆来保存和召回：

• MDL schema。
• knowledge/rules/ 里的业务规则。
• knowledge/sql/ 里的确认过的自然语言到 SQL 样例。
• 过去成功问题和查询。

这解决了一个常见问题：不要把 500 张表的 schema 全丢给模型，也不要让模型凭直觉挑表，而是根据问题召回相关上下文。

4.5 Skills

WrenAI 的 skill 是给 Claude Code、Codex、Cursor、Cline 等 AI coding agent 使用的工作流指南。用户只需安装一个 discovery stub，具体的 onboarding、generate-mdl、usage、enrich-context、genbi 等 workflow guide 由 wren skills get 按需获取。

这点对售前很有意思：它不是让客户手动学习一堆 CLI，而是把 CLI 封装成 Agent 可执行的可控流程。

5. 核心能力清单

6. 适用场景

6.1 企业可信 Text-to-SQL

客户痛点：

• 业务人员不会写 SQL。
• 数据团队被大量临时取数需求淹没。
• 让 LLM 直接查库容易口径错、join 错、字段错。

WrenAI 的价值：

• 用 MDL 明确哪些表、字段、关系和指标能被 Agent 使用。
• 用 memory 召回类似历史查询。
• 用 dry-plan 和 dry-run 让错误在执行前暴露。

售前说法：

“我们不是把数据库直接暴露给大模型，而是在中间加一层可审查的业务语义层，让 AI 按企业认可的口径查数。”

6.2 Agentic BI / 数据分析 Agent

如果客户已经在做企业 Agent 平台，WrenAI 可以作为“数据分析工具层”接入，让 Agent 拥有可信查数能力。

适合：

• 企业内部 Copilot。
• 数据分析 Agent。
• 经营分析助手。
• 销售/运营/财务自助分析助手。
• BI 平台增强。

6.3 数据语义层治理

很多企业已经有数仓、dbt、指标平台或 BI，但缺少一个对 Agent 友好的上下文层。WrenAI 可以把业务定义、查询规则和历史样例以文件形式管理。

适合客户：

• 数据团队希望让业务口径 Git 化。
• 已有 dbt/数仓建模，但 AI 应用无法理解业务语义。
• 需要在多个 Agent 或工具之间复用同一套数据上下文。

6.4 快速生成可分享 Dashboard

GenBI app 可以把分析结果生成浏览器端 Dashboard，并部署到 Vercel 或 Cloudflare Pages。默认 snapshot 模式把数据打包进 app，适合 demo、小型报表、一次性分析交付；live 模式适合需要实时数据的生产看板，但需要额外处理 CORS 和凭证安全。

适合：

• 售前 demo 报表。
• 项目周报、经营复盘。
• 小型客户数据故事展示。
• 给管理层分享一个临时报表链接。

6.5 数据产品 PoC 底座

WrenAI 非常适合做 PoC，因为它覆盖了客户最关心的几个点：

• 是否能理解业务口径。
• 是否能连接客户真实数据源。
• 是否能减少 SQL 幻觉。
• 是否能把回答变成图表和 Dashboard。
• 是否能把上下文以文件方式审核和迭代。

7. 不太适合的场景

8. 架构和组件

8.1 仓库结构

README 中给出的项目结构：

core/
  wren-core/         Rust semantic engine, Apache DataFusion
  wren-core-base/    Shared manifest types + MDL builder
  wren-core-py/      Python bindings, PyPI: wren-core
  wren-core-wasm/    WebAssembly build, npm: wren-core-wasm
  wren/              Python SDK and CLI, PyPI: wrenai
  wren-mdl/          MDL JSON schema
sdk/
  wren-langchain/    Reference agent SDK integration
skills/              Agent skills for context authoring
docs/                Module documentation
examples/            Example projects

8.2 技术栈理解

8.3 正确性机制

官方文档把防幻觉拆成五层：

这部分是销售给数据团队和 IT 架构团队时最有说服力的技术抓手。

9. 怎么安装和使用

9.1 安装 CLI

pip install wrenai

根据数据源安装 extras：

pip install "wrenai[postgres,memory,main]"
pip install "wrenai[bigquery,main]"
pip install "wrenai[snowflake,main]"
pip install "wrenai[all]"

要求 Python 3.11+。如果使用 npx skills add 安装 Agent skill，还需要 Node.js/npm。

9.2 安装 Agent discovery stub

npx skills add Canner/WrenAI

也可以用 install script：

curl -fsSL https://raw.githubusercontent.com/Canner/WrenAI/main/skills/install.sh | bash

安装后，可以在 Codex、Claude Code、Cursor、Cline 等 Agent 中让 Agent 调用 /wren 或相关 skill 流程。

9.3 初始化项目

mkdir my-wren-project
cd my-wren-project
wren context init

生成结构大致是：

my-wren-project/
├── wren_project.yml
├── models/
├── views/
├── cubes/
├── relationships.yml
├── knowledge/
│   ├── rules/
│   └── sql/
└── target/
    └── mdl.json

9.4 配置数据源 profile

wren profile add my-db --ui
wren profile debug
wren context set-profile my-db

也可以用 YAML 文件导入，适合 Agent 驱动和环境变量管理：

wren profile add my-db --from-file connection.yml

9.5 生成 MDL

在 Agent 中让它使用 Wren skill：

Use Wren to explore my Postgres database and generate the MDL for all tables.

Agent 会调用 wren skills get generate-mdl，再执行表发现、字段类型解析、关系推断、YAML 写入、validate、build、memory index 等步骤。

9.6 提问和查询

Who are our top 10 customers by sales this quarter?

背后典型动作：

wren memory fetch --query "top customers by sales this quarter"
wren memory recall --query "top customers"
wren dry-plan --sql "..."
wren --sql "..."
wren memory store --nl "..." --sql "..."

9.7 生成 Dashboard

Turn this into an interactive dashboard I can filter by product, then preview it locally.

Agent 会调用 wren skills get genbi，生成 app、校验、预览，并可部署：

Deploy it to Vercel.

部署 token 放在 ~/.wren/.env，例如 VERCEL_TOKEN 或 Cloudflare 相关 token，不建议通过命令行参数传递。

10. 售前可以怎么讲

10.1 对业务负责人

“WrenAI 不是让业务人员学习 SQL，而是让他们用自然语言问问题，同时系统会按公司认可的数据口径去查数。比如收入、活跃客户、退款、留存这些口径，不再让 AI 自己猜，而是通过可审核的业务定义统一管理。”

10.2 对数据团队

“WrenAI 可以把你们已有的数据字典、指标口径、join 关系、历史 SQL 样例沉淀成 MDL 和 knowledge 文件。Agent 使用这些上下文生成 SQL，并在执行前 dry-plan 和 validate，这比直接把 schema 扔给大模型可靠很多。”

10.3 对 IT 架构团队

“它是 CLI/SDK/engine/skills 组成的开放能力层，可以接入现有 Agent 平台、数据仓库和 CI/CD。核心和 SDK 是 Apache-2.0，便于二次开发。生产落地时，我们会把它和企业身份认证、数据权限、审计、模型网关结合，而不是单独裸跑。”

10.4 对管理层

“它能把零散的临时分析需求变成可复用的数据应用。一次自然语言问答可以进一步生成图表和 Dashboard，并发布成链接，减少数据团队重复出数和手工做报表的压力。”

11. 常见客户问题

12. PoC 建议

12.1 PoC 目标

建议 PoC 不要只验证“能不能连库”，而是围绕“可信查数”设计：

• 能否用客户真实业务口径生成正确 SQL。
• 能否减少错误表、错误 join、错误指标口径。
• 能否把自然语言问题转成图表和 Dashboard。
• 能否让数据团队审核和版本化上下文。
• 能否接入客户已有 Agent 或 BI 工作流。

12.2 两周 PoC 设计

12.3 推荐指标

13. 风险和注意事项

13.1 不要过度承诺“零幻觉”

WrenAI 的架构是在降低幻觉和错误 SQL，但不是保证 100% 正确。业务口径、MDL 质量、历史样例、模型能力、数据权限都会影响结果。

13.2 需要数据团队参与建模

如果客户没有人能确认表关系、指标口径、枚举含义和业务规则，WrenAI 的上下文层就很难发挥效果。售前 PoC 一定要让数据团队参与，而不是只给业务方演示。

13.3 当前主线偏 Agent/CLI，不是完整 Web 产品

这既是优势也是门槛。优势是开放、可集成、适合 Agent 工程；门槛是客户如果期待点点鼠标的 BI 平台，可能需要额外产品化封装。

13.4 生产权限和审计要补齐

strict mode、denied functions、MDL 可见性等是基础，但企业生产通常还需要：

• SSO/IAM。
• 数据库最小权限账号。
• 行级/列级权限与组织架构绑定。
• 查询审计。
• 敏感字段脱敏。
• LLM 调用日志与成本控制。
• Dashboard 分享权限。

13.5 Dashboard 部署要注意数据暴露

GenBI snapshot 模式会把数据随 app 打包。官方文档也提醒，部署到公共静态站点时，任何拿到 URL 的人可能读取 app 文件，因此不能把敏感明细或凭证打进去。live 模式也不能内嵌凭证，需要后端 API 和权限控制。

13.6 版本演进较快

项目从 2026-05 后发生明显定位变化，并且 2026-07 仍在密集 release。正式项目建议冻结版本、建立升级策略，并避免依赖未稳定的 roadmap 能力。

14. 与相邻产品的区别

15. 可包装的解决方案方向

15.1 企业可信数据问答助手

将 WrenAI 接入客户数仓和企业 Agent 平台，面向业务人员提供自然语言查数。重点交付 MDL、业务规则、历史 SQL 记忆和权限控制。

15.2 AI 数据分析 Agent 工具层

为已有 Agent 平台补一个“可治理的数据查询工具”。Agent 不直接连库，而是通过 Wren 上下文层访问被建模的数据对象。

15.3 数据语义治理工作台

把客户数据字典、指标口径、join 关系、常用问题、历史 SQL 统一沉淀到 Git 仓库，形成可审查、可版本化的数据语义资产。

15.4 经营分析 Dashboard 快速生成

针对管理报表、周报、销售分析、运营复盘，用自然语言生成可分享 Dashboard。PoC 阶段优先使用 snapshot 模式，生产阶段再评估 live 模式。

16. 我的售前判断

WrenAI 是一个很值得关注的 Agentic BI 基础项目。它的卖点不是“UI 做得多完整”，而是非常准确地抓住了企业落地 Text-to-SQL 的痛点：模型缺少业务上下文，直接生成 SQL 很危险。它用 MDL、memory、dry-plan、skills 和多数据源 connector，把“可信查数”拆成一组 Agent 可以调用的工程原语。

对售前来说，WrenAI 适合放在“企业 AI 数据助手”“可信 Text-to-SQL”“Agent 访问数据仓库的语义层”这些方案里，而不适合单独包装成完整 BI 平台。最好的打法是选一个客户真实业务域，用 5-10 个高频问题做 PoC，通过人工 SQL 对比来证明它能减少口径错误和查询错误，再进一步演示 Dashboard 生成和部署。

如果客户已有数据团队、数仓和 AI Agent 战略，WrenAI 的契合度很高；如果客户只是想买一个开箱即用的报表工具，应该考虑商业 BI 或 Wren AI Commercial，而不是直接采用当前开源主线。

17. 参考资料

• GitHub 仓库：Canner/WrenAI
• 官方文档：Wren AI OSS Introduction
• 快速开始：Quick Start: Wren CLI with jaffle_shop
• 数据源连接：Connect your database
• GenBI Dashboard：Build & deploy a GenBI app
• 正确性机制：How does Wren AI keep agents from hallucinating?
• PyPI 包：wrenai
• 最新 Release：wren-v0.13.1
• 商业网站：getwren.ai