使用 ForgeCode 安装 Wren AI：从 Skills 安装到 Onboarding 全流程指南-二趣网

使用 ForgeCode 安装 Wren AI：从 Skills 安装到 Onboarding 全流程指南

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

Wren AI（开源 Generative BI 引擎）通过可复用的Skills（AI Agent 工作流指南）让 Claude Code、Cursor、Cline、ForgeCode 等 AI 编程 Agent 自动完成环境检查、连接配置、项目脚手架、MDL 建模与首次查询的完整落地。本文以docs/core/get_started/quickstart-with-agent/forgecode.md为骨架，讲解如何用 ForgeCode（forge）这一 AI 编码 Agent 安装并初始化 Wren AI，读完你将掌握：安装wrendiscovery stub、通过/wrenskill 触发 onboarding 流程、以及 Onboarding 全流程背后每一步的具体命令与判断规则。

前置条件

在开始之前，确保你的机器满足唯一一个硬性要求：

ForgeCode 已安装并完成认证（authenticated）。

Wren AI 的安装本身不要求你提前装好数据库、Docker 或云基础设施——后续流程中的环境检查（Python 版本、虚拟环境、wrenCLI 是否存在等）由 Onboarding skill 在对话中自动完成，你只需要一个能运行npx和forge的终端环境。

第一步：安装 Wren Skills

Wren AI 把"如何操作 CLI"的指南以Skills形式交付给 AI Agent。在 ForgeCode 中安装只需一行命令：

npx skills add Canner/WrenAI --agent forgecode

这条命令通过npx skills工具从Canner/WrenAI仓库安装名为wren的discovery stub（发现存根），并显式指定目标 Agent 为forgecode。--agent <name>参数用于指定具体的 AI 客户端（例如claude-code、cursor、windsurf、cline），不加该参数时安装器会自动检测当前已安装的 Agent。

Skills 的交付模型：存根在 Agent，内容在 CLI

理解这条命令做了什么，需要先了解 Wren AI 的 Skill 分发设计（见 skills/SKILLS.md）：

安装到 ForgeCode 的只是一个约 50 行的discovery stub（skills/wren/SKILL.md），它只告诉 Agent："工作流指南和提示词模板都存在wrenCLI 里，请按需拉取"；
真正的workflow guides（onboarding、usage、generate-mdl、dlt-connector、enrich-context、genbi）随wrenaiPython 包分发，通过wren skills get <name>按需输出；
因为内容随 wheel 一起发布，Agent 读到的指南永远与已安装的 CLI 版本一致（无缓存、无版本漂移）。

也就是说，npx skills add安装的只是一个"入口"，真正的操作手册在安装wrenai包之后由 CLI 动态提供。

备选安装方式：如果不使用npx，也可以运行仓库自带的 skills/install.sh 脚本安装同一个 stub（支持--force覆盖已有安装）。该脚本既支持从本地仓库克隆目录安装，也支持通过curl ... | bash从远端拉取。

第二步：运行 Onboarding

安装完 skill 后，启动 ForgeCode：

forge

然后在对话中向 Agent 提问：

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

Agent 读到 discovery stub 后，会识别出这是一个onboarding任务，并自动执行wren skills get onboarding拉取完整的安装工作流指南（源码位于 core/wren/src/wren/skills_content/onboarding/SKILL.md）。

正如关联文档所述，这条 skill 会引导 Agent 依次完成：环境检查 → profile 创建 → 项目脚手架 → 首次查询。下面是每一步在仓库中可验证的具体实现。

环境预检（Preflight，只读）

Onboarding 首先做 4 项只读环境检查，此时不会询问任何项目/凭据信息：

python3 --version— 要求 Python 3.11+，版本过低则请用户升级后停止；
检查虚拟环境：python3 -c "import sys; print(sys.prefix != sys.base_prefix)"，若输出False（即不在虚拟环境中），建议创建并激活（PEP 668 系统必须使用虚拟环境）；
wren --version— 若已安装则确认后再决定是否重装；
pwd— 记录当前工作目录。

分支决策：自带数据 vs 示例数据

预检通过后，Agent 会询问用户："先试用内置的jaffle_shop演示数据（约 30 秒，无需数据库），还是连接你自己的数据库？"

选demo→ 转入 docs/core/get_started/quickstart.md 的jaffle_shop端到端演示并结束本 skill；
选own DB→ 继续执行下面的安装流程。

关键 Agent 行为规则

从 onboarding skill 的源码可以确认，Agent 在整条流程中必须遵守四条硬性规则（这也是整个 Skills 系统的设计哲学，见 docs/core/reference/skills.md）：

规则	原因
每轮只做一步（one step per round-trip）	避免一次性向用户抛出过多信息，保持每轮对话聚焦
绝不在聊天中索要凭据（host、port、user、password、token 都不行）	凭据只通过`.env`文件传递，Agent 全程看不到具体值
绝不臆造连接字段名	必须运行`wren docs connection-info <ds>`从实时 Pydantic schema 内省真实字段
MDL 构建完成前绝不查询数据库	强制 Agent 先搭建上下文层再查数据

第三步：Onboarding 内部流程详解

虽然关联文档只用一句话概括了 Onboarding 的职责，但该 skill 在仓库中的实现（core/wren/src/wren/skills_content/onboarding/SKILL.md）把流程拆成了清晰的步骤，这也是安装 Wren AI 时 Agent 实际执行的动作：

Step 1 — 收集项目名 + 数据库类型。这两项是下一步唯一需要的信息；数据库类型可通过wren docs connection-info（无参数）查看完整列表，常见取值如postgres、mysql、bigquery、snowflake、clickhouse、trino、duckdb。

Step 2 — 工作区与.env搭建（批量执行）。创建~/<project>/目录，安装wrenai[<ds>,main]，然后通过wren docs connection-info <ds> --format md内省连接器生成.env模板（值为空的<DS>_<FIELD>键，如POSTGRES_HOST=、POSTGRES_PORT=5432）。随后用户在自己的编辑器里填好.env并回复 "done"，Agent 永远看不到值。

Step 3 — 创建连接 profile。Agent 写一个所有字段均为${VAR}占位符的/tmp/conn.yml，然后运行：

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

校验自动执行；profile 静默覆盖、没有--force标志。失败时按 docs/core/guides/connect.md 中的 troubleshooting 章节对症处理（缺密钥、驱动认证失败、ValidationError、主机不可达等）。

Step 3.5 — 脚手架项目：

wren context init --empty

生成models/、views/、relationships.yml、knowledge/（rules + sql）、AGENTS.md等目录结构，且拒绝覆盖已存在的wren_project.yml。

Step 3.6 — 绑定 profile 到项目：

wren context set-profile <project>

把profile: <project>和data_source: <ds>写入wren_project.yml，从此该项目的一切 CLI/SDK 查询都确定性地使用该连接，不受全局wren profile switch影响。

Step 4 — 生成 MDL（交接）。Agent 必须先运行wren skills get generate-mdl完成表内省、类型归一化与 YAML 生成，再执行wren context validate与wren context build并汇报模型数量与告警。

Step 5 — 进入查询阶段（交接）。Agent 基于发现的表建议 2～3 个自然语言问题，之后日常查询转由wren skills get usage指南驱动。

安装后的首查验证与后续步骤

安装完成后，你可以在项目目录里直接验证成果，例如运行wren context show查看建模上下文、wren --sql "SELECT 1"做连接 sanity 检查，然后用自然语言提问（如 "How many customers placed more than one order?"），Agent 会基于 MDL 上下文层而非原始表结构来写 SQL。

关联文档在 "Next step" 中给出了两条推荐的进阶路径，路径均已转换为仓库相对路径：

Quickstart with sample data— 用jaffle_shop示例数据走一遍端到端流程：从dbt build造数、pip install "wrenai[memory,main]"、wren profile add jaffle-shop、wren context init，到用 Agent 生成 MDL 并查询（约 15 分钟，无需云数据库）；
Connect your data— 将 Wren AI 指向真实数据库，包含按数据源分类的连接字段说明、特殊编码（BigQuery base64、Snowflake account 格式、Athena AWS 凭据等）以及完整的故障排查手册。

两条路径都与本次 ForgeCode 安装无缝衔接：Onboarding 分支中选择 demo 时直接走路径 1，选择自带数据库时则从路径 2 中的 profile 与.env配置继续。

小结

用 ForgeCode 安装 Wren AI 的本质是两条命令加一个自然语言指令：npx skills add Canner/WrenAI --agent forgecode把 discovery stub 装进 Agent，forge启动对话后一句 "Use the /wren skill to install and set up Wren AI." 触发 onboarding 工作流。随后的环境检查、.env凭据隔离、profile 创建、项目脚手架、MDL 生成与首次查询，全部由 Agent 依据wrenCLI 内动态分发的 skill 内容逐步完成——这种"存根在 Agent、内容在 CLI"的交付模型，保证了安装指南始终与所安装的wrenai版本严格一致。

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

企业官网建设流程全解析