在 Crush 中安装与配置 Wren AI：Charm TUI 编码 Agent 的完整上手指南-港品优选

在 Crush 中安装与配置 Wren AI：Charm TUI 编码 Agent 的完整上手指南

【免费下载链接】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

本篇技术指南讲解如何在Crush（Charm 出品的终端 TUI 编码 Agent）中安装 Wren AI 的技能（Skills）、触发 onboarding 工作流，并完成环境检查、Profile 创建、项目脚手架与首次查询的端到端配置。读完本文，你将掌握在纯终端环境中让 AI Agent 驱动 Wren AI 安装与初始化的完整操作链路，并理解该过程背后由仓库源码支撑的实现原理。

Crush 与 Wren AI：为什么在终端里就能完成全部安装

Crush 是 Charm 推出的 TUI 编码 Agent，整个交互发生在终端中，不需要打开浏览器或额外图形界面。Wren AI 将自身的能力封装为Skills——一系列 Markdown 工作流指南，指示 AI 编码 Agent（Claude Code、Codex、Crush 等）如何操作wrenCLI。二者结合后，你可以在一个终端会话里完成从零到首次查询的全部初始化。

这套机制的关键设计是"发现桩（discovery stub）"模式：你安装的只有一个名为wren的桩技能，真正的流程指南保存在wrenCLI 内部，由wren skills get <name>按需拉取。正如 skills/index.json 所描述，工作流指南位于wrenCLI（pip install wrenai）中，通过wren skills get/wren ask提供服务，从而避免技能缓存与版本漂移问题。

前置条件

开始之前，请确认你的环境满足以下要求：

Crush 已安装并完成认证（crush命令可用）。
Python 3.11+：onboarding 技能的环境检查要求python3 --version不低于 3.11。
Node.js / npm：安装 Wren skills 使用npx skills add命令，需要 npm 环境。
Git：用于克隆示例项目（如需jaffle_shop示例数据）。

若你的系统 Python 是 PEP 668 管理的（externally-managed-environment），onboarding 技能会建议先创建虚拟环境（python3 -m venv .venv && source .venv/bin/activate）再继续。

第一步：安装 Wren skills

在终端执行：

npx skills add Canner/WrenAI --agent crush

--agent crush参数用于指定目标 Agent。该命令安装的是 skills/wren/SKILL.md 这个发现桩：它的allowed-tools声明为Bash(wren:*)，即允许 Agent 调用任意wren子命令；其描述字段覆盖了数据提问、安装 Wren Engine、连接数据库、通过 dlt 连接 SaaS 数据、生成 MDL、丰富业务上下文、构建并部署 GenBI 应用等全部触发场景。

除npx之外，仓库同时提供了 skills/install.sh 脚本作为等效安装途径。该脚本支持--force参数覆盖已存在的安装，并可通过环境变量WREN_SKILLS_BRANCH指定分支、CLAUDE_SKILLS_DIR指定目标目录（默认$HOME/.claude/skills）。两种方式殊途同归：最终安装的只有一个wren发现桩，其余流程指南全部由 CLI 按需下发。

第二步：启动 Crush 并触发 onboarding

安装完成后，启动 Crush：

crush

然后在 Crush 的对话框中输入：

Use the /wren skill to install and set up Wren AI.

这条指令让 Crush 加载/wren技能。技能识别到这是从零初始化的任务后，会拉取onboarding工作流指南（对应 core/wren/src/wren/skills_content/onboarding/SKILL.md），由它驱动 Agent 完成整个安装设置流程。

onboarding 背后发生了什么：Agent 的逐步执行流程

正如原文档所述，"the skill walks the agent through environment checks, profile creation, project scaffolding, and a first query"。结合仓库中 onboarding 技能的实现，这一过程可细分为以下几个阶段：

1. 环境预检（Preflight）

Agent 首先执行一组只读检查并汇报结果，此阶段不询问任何项目信息：

python3 --version：验证 Python 3.11+，不满足则要求升级并停止；
检查是否处于虚拟环境（python3 -c "import sys; print(sys.prefix != sys.base_prefix)"），返回False时建议创建.venv；
wren --version：若已安装则确认而非重复安装；
pwd：记录当前目录。

2. 项目脚手架与连接配置

Agent 确认项目名与数据库类型后，批量执行：创建~/<project>/目录、安装对应连接器扩展（pip install "wrenai[<ds>,main]"）、通过wren docs connection-info <ds> --format md内省连接字段并生成.env模板。onboarding 技能在此处有一条硬性规则：绝不通过对话索取凭据，所有密钥一律由用户在自己的编辑器中填入.env文件，Agent 永远看不到值。

3. Profile 创建与绑定

Agent 将.env中的每个字段写成${VAR}占位符形式的 YAML，然后执行：

wren profile add <project> --from-file /tmp/conn.yml

创建连接 Profile 后，接着初始化项目骨架并绑定 Profile：

wren context init --empty wren context set-profile <project>

其中wren context init会生成wren_project.yml、models/、views/、relationships.yml、knowledge/（rules + sql）等目录结构，并拒绝覆盖已存在的wren_project.yml。set-profile则把profile: <project>与data_source: <ds>写入wren_project.yml，使项目与连接绑定，后续命令与 SDK 的解析不再受全局 Profile 切换影响。

4. MDL 生成与首次查询

onboarding 技能明确要求：在 MDL 构建完成之前绝不允许查询数据库。Agent 会切换到generate-mdl指南，完成表结构内省、类型归一化与 YAML 生成，随后执行：

wren context validate wren context build

至此初始化完成。Agent 会基于发现的表提出 2～3 个自然语言问题示例（如 "How many orders last month?"、"Top 5 customers by total"），之后的日常查询交由usage指南驱动。

技能分发机制：为什么无需手动维护指南版本

你可能会好奇：为什么只安装一个桩技能，Crush 就能执行完整流程？答案在 skills/wren/SKILL.md 中：

wren skills list # all available workflow guides wren skills get onboarding # set up Wren end-to-end wren skills get usage # day-to-day querying wren skills get generate-mdl # generate MDL from a database schema wren skills get dlt-connector # connect SaaS sources via dlt wren skills get enrich-context # add business context (units, enums, cubes) wren skills get genbi # build & deploy a shareable GenBI web app

指南本身存放在wrenCLI 内部，因此始终与所安装的wrenai版本匹配，不存在技能缓存与版本漂移。对 Agent 而言，它只需记住"先wren skills get <name>再执行多步工作流"这一规则即可。这也是 skills/index.json 中将其定位为 "discovery stub"（发现桩）的根本原因。

下一步：完整示例与真实数据库连接

Crush 中的 onboarding 完成后，官方文档给出了两条延伸路径：

基于示例数据的完整快速开始：以 dbt Labs 的jaffle_shop示例数据集走通端到端流程（约 15 分钟）。该文档详细覆盖了创建虚拟环境、dbt build构建 DuckDB 数据库、安装wrenai[memory,main]、创建 Profile、wren context init脚手架、生成 MDL，以及通过记忆系统进行日常问答的完整步骤，并提供了wren dry-plan、wren dry-run、wren memory fetch/recall/store等常用命令速查表。
连接你自己的数据库：将 Wren AI 指向真实数据库。该指南列出了全部受支持的数据源及其连接器扩展（PostgreSQL、MySQL、BigQuery、Snowflake、ClickHouse、Trino、SQL Server、Databricks、Redshift、Oracle、Athena、Spark 等），并说明通用的五步流程：安装连接器扩展 → 创建 Profile → 绑定到项目 → 生成 MDL → 开始查询。其中wren docs connection-info <ds>命令直接从引擎连接 Schema 生成字段说明，始终与已安装的wrenai版本一致，是确认连接字段的权威来源。

无论是走jaffle_shop示例还是接入自有数据库，Crush 用户都可以复用同一套/wren技能：只需用自然语言下达指令，Agent 会自行路由到dlt-connector、generate-mdl、usage或onboarding等对应指南，让整个 Wren AI 的安装、建模与查询闭环全部在终端内完成。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析