在 Cursor 中安装与使用 Wren AI：从 Skills 安装到首次自然语言查询

在 Cursor 中安装与使用 Wren AI从 Skills 安装到首次自然语言查询【免费下载链接】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/WrenAIWren AI 是一个面向 AI Agent 的开源 GenBIGenerative BI语义 SQL 层可通过一个开放上下文层把自然语言问题转化为可信的 SQL、图表与仪表盘支持 20 数据源BigQuery、Snowflake、PostgreSQL、ClickHouse、Amazon Redshift、Databricks 等。本文聚焦 Cursor IDE 场景如何在 Cursor 中安装 Wren 的 Agent Skill、驱动/wren技能完成环境检查、Profile 创建、项目脚手架与首次查询的完整 on boarding 流程。读完本文你将掌握在 Cursor 中以一条指令完成 Wren AI 安装与初始化、再以自然语言提问的技术方案并理解其背后的 Skills 分发机制与 CLI 调用链。前置条件在开始前确保满足Cursor IDE已安装并完成账号登录认证本文面向 Cursor 桌面版Windows / macOS / Linux 均适用。可选Python 3.11 与 Node.js / npmnpx安装 Skills 时需要 NodewrenCLI 本体通过pip安装。在 Cursor 中安装 Wren SkillsWren 以Agent SkillMarkdown 工作流指南的形式交付给 AI 编码 Agent。在 Cursor 中通过npx skills一条命令即可安装npx skills add Canner/WrenAI --agent cursor其中Canner/WrenAI是 GitHub 上的 WrenAI 仓库标识安装器会从其中拉取 Skills 分发目录--agent cursor显式指定安装目标为 Cursor省略时安装器会自动探测你已安装的 AI 客户端支持的 Agent 包括cursor、claude-code、windsurf、cline等也可用--agent *一次性安装到所有客户端。安装的是什么一个 Discovery Stub而非完整文档需要特别说明的是这条命令安装的只有一个wren发现桩discovery stub而不是整套工作流指南。从仓库的 skills/wren/SKILL.md 可以看到该 Stub 的前言明确写道This is a discovery stub. The actual workflow guides and prompt helpers live inside thewrenCLI itself, so they always match the installed wrenai version (no skill cache, no version drift).这一设计带来的核心收益是无版本漂移实际的工作流指南onboarding、usage、generate-mdl、dlt-connector、enrich-context、genbi以包数据的形式随wrenCLI 一起分发位于 core/wren/src/wren/skills_content/ 目录Stub 只负责在运行时通过wren skills get name按需取回指南因此内容永远与你安装的 wrenai 版本一致不会出现 Skills 缓存过期的问题。运行 Onboarding第 1 步在 Cursor 中打开项目在 Cursor 中打开你的项目文件夹File → Open Folder...或快捷键⌘O/CtrlO然后按⌘L/CtrlL打开聊天面板。第 2 步向 Agent 发出指令在聊天面板中输入Use the /wren skill to install and set up Wren AI./wren是 Cursor 加载到 Skills 后暴露的斜杠命令。Agent 读取 Stub 后会调用 CLI 拉取onboarding指南对应wren skills get onboarding并沿着一套**每轮只做一步one step per round-trip**的 Agent 工作流推进。根据 core/wren/src/wren/skills_content/onboarding/SKILL.md整个流程大致分为以下阶段阶段主要动作涉及命令Preflight环境检查检查 Python 版本、虚拟环境、wren是否已装、记录当前目录python3 --version、python3 -c import sys; print(sys.prefix ! sys.base_prefix)、wren --version分支决策询问用户先跑内置jaffle_shop示例还是连接自有数据库—Step 1收集项目名 数据库类型wren docs connection-info查看完整数据源列表Step 2创建工作区目录、安装wrenai[ds,main]、生成.env模板pip install wrenai[ds,main]、wren docs connection-info ds --format mdStep 3生成连接 Profilewren profile add project --from-file /tmp/conn.ymlStep 3.5脚手架项目结构wren context init --emptyStep 3.6绑定 Profile 到项目wren context set-profile projectStep 4生成 MDL 并构建wren skills get generate-mdl→wren context validate/wren context buildStep 5提出示例问题并结束 Onboarding交给wren skills get usageAgent 驱动 Onboarding 的三条硬性规则从源码可以确认onboardingSkill 对 Agent 施加了三条不可违反的约束这也是 Wren AI 与普通 CLI 教程的本质区别——它把如何操作编码进了 Agent 的运行时规则绝不在聊天中索要凭据host、port、user、password、token 一律通过.env文件由用户自行填写Agent 永远看不到这些值绝不臆造连接字段名必须先用wren docs connection-info ds查看从 Pydantic 连接 schema 实时内省出的真实字段再生成.env与/tmp/conn.ymlMDL 构建之前绝不查询数据库对未纳入 MDL 的表发起查询必然失败因此必须先执行generate-mdl指南。深入Onboarding 各步骤背后的技术原理环境检查Preflight 只读检查Agent 先执行只读的环境检查并以 4 条摘要汇报此阶段不询问任何项目相关问题python3 --version—— 要求Python 3.11虚拟环境检测 —— 如果python3 -c import sys; print(sys.prefix ! sys.base_prefix)输出False说明未激活 venv在 PEP 668 系统上需要先创建并激活虚拟环境wren --version—— 若已安装则确认后再决定是否重装pwd—— 记录当前目录。环境变量模板从连接 schema 实时内省安装依赖并创建项目目录后Agent 通过wren docs connection-info ds --format md内省连接器字段据此生成一个键值全空的.env模板。以 PostgreSQL 为例POSTGRES_HOST POSTGRES_PORT5432 POSTGRES_DATABASE POSTGRES_USER POSTGRES_PASSWORD字段命名遵循DS_FIELD的 UPPER_SNAKE 约定。特殊数据源有各自的编码约定如 BigQuery 的 base64 凭据、Snowflake 的 account 格式、Athena 的 AWS 凭据Agent 会把 docs/core/guides/connect.md 中对应章节原文呈现给用户而不是转述。connect.md还要求将.env加入.gitignore并建议chmod 600 .env收紧权限。Profile 创建与项目绑定用户填完.env并回复 done 后Agent 会写出一个每个字段都是${VAR}占位符的/tmp/conn.yml例如datasource: postgres host: ${POSTGRES_HOST} port: ${POSTGRES_PORT} # … 其余字段与 wren docs connection-info postgres 输出一一对应然后执行wren profile add project --from-file /tmp/conn.yml自动完成校验CLI 会静默覆盖同名 Profile没有--force标志。接着wren context init --empty # 脚手架拒绝覆盖已有 wren_project.yml wren context set-profile projectwren context set-profile会把profile: project与data_source: ds一并写入wren_project.yml将项目锁定到指定连接——此后无论全局激活哪个 Profile该项目的 CLI 命令与 SDK 调用都会确定性地解析到绑定连接wren profile switch不会误伤其他项目。MDL 生成从数据库 schema 到语义模型Onboarding 的最后一步是构建 MDLModeling Definition Language。Agent 通过wren skills get generate-mdl指南驱动探测表结构 → 通过 SQLAlchemy 或information_schema内省列与类型 → 用wren utils parse-type规范化类型 → 按一表一目录写入models/下的 YAML → 从外键与命名约定推断关系 → 补充描述 →wren context validatewren context build验证构建。内存规模提示onboarding指南建议用wren context show | grep -c ^model:统计模型数若 ≥ 200 个模型再安装wrenai[memory]约 800MB并执行wren memory index模型较少时可跳过避免不必要的内存与磁盘开销。安装完成后以自然语言提问Onboarding 结束后Cursor 中的 Agent 即具备完整的查询能力。你只需提出业务问题例如How many customers placed more than one order?What are the top 5 products by total revenue?Agent 会依据usage指南完成一条完整的 NL→SQL 闭环取上下文wren memory fetch --query ...—— 定位与问题相关的表与列回忆相似查询wren memory recall --query ...—— 检索历史相似 NL-SQL 对写 SQL使用**模型名业务语义**而非裸表名绝不臆造列名通过wren context show核实执行wren --sql .../wren query --sql ...—— 经 Wren 引擎运行沉淀wren memory store --nl ... --sql ...—— 保存成功的 NL-SQL 对供未来召回。提问越多记忆系统越聪明——每次沉淀都会提升后续召回准确率这是 Wren AI 上下文层区别于普通 schema 直读的关键。进一步理解/wrenSkill 背后的 CLI 命令面wrenSkill 的核心价值是教会 Agent 在正确的时机调用正确的 CLI 命令。仓库 skills/wren/SKILL.md 列出了完整的命令面其中与 Cursor Onboarding 直接相关的包括命令作用wren skills list列出所有可用工作流指南wren skills get onboarding获取端到端安装指南即本文主题wren skills get usage获取日常查询指南wren skills get generate-mdl从数据库 schema 生成 MDLwren skills get dlt-connector通过 dlt 连接 SaaS 数据源HubSpot、Stripe、Salesforce 等wren skills get enrich-context添加业务上下文单位、枚举、Cube 如 ARR / DAU / churnwren skills get genbi构建并部署可分享的 GenBI Web 应用wren docs connection-info ds查看某数据源必填/可选连接字段wren ask question --guided/--direct为 Agent 包装用户问题关于wren ask的两种模式从 core/wren/src/wren/ask.py 的源码注释可以确认其定位--guided会前置一段严格任务流程适合较弱的 LLM例如先wren context show查看模型、再wren memory recall回忆历史、用模型名写 SQL、wren dry-plan校验、wren query执行模板见 guided.md.tmpl--direct则只做最轻量包装适合较强的 LLM见 direct.md.tmpl。wren ask只负责渲染提示词到 stdout本身不执行任何查询。Skills 的按需分发实现wren skills get name之所以能始终匹配安装版本是因为其实现直接读取 wheel 内的包数据。skills_delivery.py 通过importlib.resources.files(wren) / skills_content定位 skills_content 目录get_skill(name, fullFalse)返回该目录下SKILL.md主指南--full会在主指南后按文件名排序追加references/*.md--script则从scripts/取回捆绑脚本。命令行入口见 skills_cli.py 中的list与get两个子命令。常见问题排查npx skills add报错 / 未装到 Cursor确认 Cursor 已登录并显式追加--agent cursor若装了多个 Agent 想全部安装用--agent *。wren: command not foundwrenCLI 需要单独安装pip install wrenai或pip install wrenai[memory,main]Skills 只是分发指南不是 CLI 本体。PEP 668 externally-managed-environment在虚拟环境内安装python3 -m venv ~/.venvs/wren source ~/.venvs/wren/bin/activate并在每个新终端先激活该环境再运行wren命令。连接失败按 docs/core/guides/connect.md 的排查清单依次检查凭据、网络可达性、SSL 设置与云数据库 IP 白名单。未知数据源或字段名错误Pydantic ValidationError切勿手写字段名始终以wren docs connection-info ds的输出为准。下一步Quickstart with sample data —— 使用内置jaffle_shop示例数据集端到端走一遍完整流程约 15 分钟无需自带数据库Connect your data —— 将 Wren AI 指向真实数据库并创建连接 ProfileSkills reference —— 详细了解每个 Skill 指南的职责与完整命令面。【免费下载链接】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），仅供参考