wren-onboarding

Wren 入门 — Agent 工作流

此技能将引导 Agent 完成入门流程，包括环境检查、项目脚手架搭建、配置文件创建、MDL 生成和首次查询。操作步骤、各数据源的设置说明以及故障排查手册都在文档中，不在这里。此技能的作用是强制执行 Agent 端的规则（每轮只进行一个步骤，绝不在聊天中索要凭据），并在每个步骤将 Agent 引导至正确的文档或配套技能。

参考文档（此技能会指向这些文档，绝不重复其中的内容）：

• docs/core/get_started/installation.md — CLI 安装和技能安装
• docs/core/guides/connect.md — 完整的连接流程、各数据源的设置说明和完整的故障排查手册
• docs/core/get_started/quickstart.md — 内置的 jaffle_shop 演示

版本检查

静默获取 https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json。将 wren-onboarding 键的值与此技能的版本（见上方 frontmatter）进行比较。如果远程版本更新，则通知用户：

有较新版本的 wren-onboarding 技能可用。 使用以下命令更新：

npx skills add Canner/WrenAI --skill wren-onboarding

无论是否更新，都继续执行。

操作模式 — 请先阅读

每次往返只进行一个步骤。 以下每个编号步骤都独立占用一轮：简要说明，只询问该步骤所需的信息，运行命令，确认结果，然后继续。

• ❌ 绝不提前收集后续步骤的信息。 不要在一条消息中同时询问项目名称、数据库类型和凭据。
• ❌ 绝不在聊天中索要凭据 — 包括主机、端口、用户名、密码、令牌等任何信息。 凭据始终通过 .env 提供。用户在编辑器中填写文件，Agent 绝不会看到其中的值。
• ❌ 绝不在通过 wren-generate-mdl 技能构建 MDL 之前查询数据库。
• ❌ 绝不臆造连接字段名称。 始终运行 wren docs connection-info <ds> 查看实际字段——这些字段是从实时 Pydantic 架构中内省得出的，因此始终准确。
• ✅ 等待每条命令执行完毕，用通俗语言报告其输出，然后继续。
• ✅ 遇到任何错误时，查阅 connect.md#troubleshooting，并向用户提供相关章节——不要在此处复制故障排查手册。

预检（仅检查环境 — 不询问项目相关问题）

只读检查。报告检查结果，暂不询问项目、凭据或数据源。

1. python3 --version — 需要 Python 3.11+。如果版本较低，请用户升级后停止。
2. 检查虚拟环境：python3 -c "import sys; print(sys.prefix != sys.base_prefix)"。如果结果为 False，建议创建虚拟环境（python3 -m venv .venv && source .venv/bin/activate）。使用 PEP 668 系统的用户需要创建虚拟环境。
3. wren --version — 如果已安装，请在重新安装前先确认。
4. pwd — 记录当前路径。暂时不要询问项目应放在哪里。

以 4 条项目符号列表报告检查结果，然后继续。

提前分支 — 演示还是使用自己的数据库？

“先试试内置的 jaffle_shop 演示（约 30 秒，无需数据库），还是连接你自己的数据库？”

• demo → 指向 quickstart.md，然后停止此技能。
• own DB → 继续。

步骤 1 — 收集项目名称和数据库类型

步骤 2 只需要这两项；请一次询问，方便用户顺利交接：

“开始搭建前，需要确认两件事：

1. 项目名称——我会创建 ~/<name>/ 并进入该目录。
2. 数据库类型——运行 wren docs connection-info（不带参数）查看完整列表，或选择常见类型：postgres（用于 Aurora PostgreSQL）、mysql（用于 Aurora MySQL）、bigquery、snowflake、clickhouse、trino、duckdb，……”

等待用户提供两项信息。不要询问凭据。

步骤 2 — 工作区和 .env 设置（批量执行）

副作用：创建 ~/<project>/，安装 wrenai[<ds>,main]，生成空的 .env 模板。项目文件（如 wren_project.yml）稍后在步骤 3.5 创建——此时只有一个等待填写凭据的目录。

批量执行——简要说明每条命令，然后最后只提醒用户填写 .env：

1. mkdir -p ~/<project> && cd ~/<project>。

2. pip install "wrenai[<ds>,main]"。有关特定数据源安装时的注意事项（macOS mysql 等），请参阅 connect.md#per-datasource-setup-notes。

3. 通过检查连接器生成 .env 模板：

   wren docs connection-info <ds> --format md
   

   使用字段列表，将 .env 写为 <DS>_<FIELD>= 键（UPPER_SNAKE），值留空。postgres 示例：

   POSTGRES_HOST=
   POSTGRES_PORT=5432
   POSTGRES_DATABASE=
   POSTGRES_USER=
   POSTGRES_PASSWORD=
   

   特殊编码（BigQuery base64、Snowflake 账户格式、Athena AWS 凭据等）请参阅 connect.md#per-datasource-setup-notes 中的说明。将相关章节原文展示给用户——不要改述。

4. 如果项目是 git 仓库，将 .env 添加到 .gitignore。建议执行 chmod 600 .env。

5. 告诉用户：.env 位于 <path>，请填写所有值，然后回复 “done”。

步骤 3 — 创建连接配置

仅在用户回复“done”后执行。

将 /tmp/conn.yml 写入与步骤 2 生成的 .env 键相匹配的所有字段的 ${VAR} 占位符：

datasource: <ds>
host: ${<DS>_HOST}
port: ${<DS>_PORT}
# … one line per field from `wren docs connection-info <ds>`

然后：

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

验证会自动运行。CLI 会静默覆盖配置文件——没有 --force 标志。

• ✓ 成功 → 继续步骤 3.5。
• ⚠ 出现任何警告 → 根据 connect.md#troubleshooting 查找对应的具体症状（缺少密钥、驱动程序身份验证失败、ValidationError、主机无法访问等），并告知用户需要修复的内容。

步骤 3.5 — 搭建项目

wren context init --empty

如果 wren_project.yml 已存在，则拒绝覆盖。创建项目目录结构（models/、views/、relationships.yml、instructions.md、AGENTS.md、queries.yml）。

步骤 3.6 — 将配置绑定到项目

wren context set-profile <project>

在 wren_project.yml 中写入 profile: <project> 和 data_source: <ds>（data_source 取自刚刚验证通过的配置，因此一定正确）。未来的 CLI 命令和 SDK 都会确定性地解析该连接，不受当前全局启用配置的影响。

此步骤还可让项目为多项目设置做好准备：记录绑定后，在其他位置切换 wren profile switch 永远不会导致该项目的查询失效。

步骤 4 — 生成 MDL（交接）

⚠️ Agent 必须先构建 MDL，才能进行任何数据查询。查询 MDL 中不存在的表会失败。

调用 wren-generate-mdl 技能。它会引导 Agent 完成表检查、类型标准化和 YAML 生成。完成后返回此处并运行：

wren context validate
wren context build

报告模型数量以及任何 validate 警告。

内存建议：使用 wren context show | grep -c '^model:' 统计模型数量。如果 >= 200，建议运行 pip install "wrenai[memory]" + wren memory index（约 800 MB）。如果 < 200，则跳过。

第 5 步——准备就绪，开始探索（交接）

根据发现的表，推荐 2–3 个自然语言问题（例如，对于订单架构：“上个月有多少订单？”，“按总金额排名前 5 的客户有哪些？”）。然后结束此技能：日常查询时，Agent 应切换到 wren-usage 技能。

跨技能路由

触发条件	技能
用户提到 SaaS 来源（HubSpot、Stripe、Salesforce、GitHub、Slack 等）	wren-dlt-connector
用户已连接数据库，但还没有 MDL	wren-generate-mdl
用户已准备好 MDL，并希望进行查询	wren-usage
其他从零开始的情况	wren-onboarding（此技能）

出错时

不要在此处保留错误处理指南——向用户展示 connect.md#troubleshooting 中的相关部分。该文档涵盖：

• wren: command not found
• pip install … externally-managed-environment
• 缺少密钥（MissingSecretError）
• 驱动程序身份验证失败
• Pydantic ValidationError / 未知数据源
• 连接被拒绝 / 防火墙 / 云数据库 IP 允许列表
• wren context validate 警告类别

如果遇到指南中未提及的问题，请告知用户：

"我遇到了不知道如何修复的错误：<error>。 请参阅 https://docs.getwren.ai/oss/introduction，或在 https://github.com/Canner/WrenAI/issues 提交问题。"