wren-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wren Onboarding — Agent Workflow

Wren 入门引导 — Agent 工作流

This skill walks the agent through onboarding — environment checks, project scaffolding, profile creation, MDL generation, and first query. Procedural details, per-datasource setup notes, and the troubleshooting playbook live in the docs, not here. The skill's job is to enforce the agent-side rules (one step per turn, never ask for credentials in chat) and to dispatch the agent to the right doc / sibling skill at each step.

Reference docs (the skill points to these — never duplicate their content):

```
docs/core/get_started/installation.md
```
— CLI install + skill install
```
docs/core/guides/connect.md
```
— full connection procedure, per-datasource setup notes, complete troubleshooting playbook

docs/core/get_started/quickstart.md

— bundled

jaffle_shop

demo

该skill会引导agent完成入门流程——环境检查、项目脚手架搭建、配置文件创建、MDL生成以及首次查询。**流程细节、各数据源的设置说明和故障排查手册均记录在文档中，此处不重复。**本skill的作用是执行agent端的规则（每轮仅执行一个步骤，绝不要求在聊天中提供凭证），并在每个步骤将agent引导至正确的文档/关联skill。

参考文档（本skill会指向这些文档——绝不复制其内容）：

```
docs/core/get_started/installation.md
```
— CLI安装 + skill安装
```
docs/core/guides/connect.md
```
— 完整连接流程、各数据源设置说明、完整故障排查手册

docs/core/get_started/quickstart.md

— 内置

jaffle_shop

演示项目

Version check

版本检查

Silently fetch

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json

. Compare the

wren-onboarding

key with this skill's version (from the frontmatter above). If the remote version is newer, notify the user:

A newer version of the wren-onboarding skill is available. Update with:
npx skills add Canner/WrenAI --skill wren-onboarding

Continue regardless of update status.

静默获取

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json

。将其中的

wren-onboarding

版本与本skill的版本（来自上方的前置信息）进行对比。如果远程版本更新，通知用户：

wren-onboarding skill有新版本可用。更新命令：
npx skills add Canner/WrenAI --skill wren-onboarding

无论是否更新，继续后续流程。

Mode of operation — READ THIS FIRST

操作模式 — 请先阅读本部分

One step per round-trip. Each numbered step below is its own turn: explain briefly, ask only what the step needs, run the command(s), confirm, move on.

❌ Never collect information for future steps upfront. Do not ask for project name + database type + credentials in one message.
❌ Never ask for credentials in chat — not host, port, user, password, tokens, anything. Credentials always go through
```
.env
```
. The user fills the file in their editor; the agent never sees the values.
❌ Never query the database before MDL is built via the
```
wren-generate-mdl
```
skill.
❌ Never invent connection field names. Always run
```
wren docs connection-info <ds>
```
to see the real fields — it's introspected from the live Pydantic schema, so it's always correct.
✅ Wait for each command to finish, report its output in plain language, then move on.
✅ For any error, consult
```
connect.md#troubleshooting
```
and surface the relevant section to the user — don't carry a copy of the playbook here.

每轮仅执行一个步骤。以下每个编号步骤对应一次交互：简要说明，仅询问该步骤所需信息，运行命令，确认完成，再进入下一步。

❌ 绝不提前收集后续步骤的信息。不要在一条消息中同时询问项目名称、数据库类型和凭证。
❌ 绝不要求在聊天中提供凭证——包括主机、端口、用户名、密码、令牌等任何信息。凭证始终通过
```
.env
```
文件提供。用户在自己的编辑器中填写文件，agent绝不会看到具体值。
❌ 在通过
wren-generate-mdl
skill生成MDL之前，绝不查询数据库。
❌ 绝不自行编造连接字段名称。始终运行
```
wren docs connection-info <ds>
```
查看真实字段——该信息从实时Pydantic架构中获取，因此始终准确。
✅ 等待每个命令执行完成，用平实语言报告输出结果，再进入下一步。
✅ 若出现任何错误，请查阅
```
connect.md#troubleshooting
```
并向用户展示相关章节——不要在此处复制故障排查手册内容。

Preflight (environment only — no user questions about the project)

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

Read-only checks. Report findings, do not ask about project / credentials / datasource yet.

```
python3 --version
```
— requires Python 3.11+. If older, ask the user to upgrade and stop.

Check virtualenv:

python3 -c "import sys; print(sys.prefix != sys.base_prefix)"

. If

False

, offer to create one (

python3 -m venv .venv && source .venv/bin/activate

). PEP 668 systems will need this.

```
wren --version
```
— if already installed, confirm before reinstalling.
```
pwd
```
— record it. Don't ask where the project should live yet.

Report findings as a 4-bullet list, then continue.

只读检查。报告检查结果，暂不询问项目/凭证/数据源相关问题。

```
python3 --version
```
— 要求Python 3.11及以上版本。若版本过低，请用户升级后停止流程。
检查虚拟环境：
```
python3 -c "import sys; print(sys.prefix != sys.base_prefix)"
```
。若返回
```
False
```
，则提议创建虚拟环境（
```
python3 -m venv .venv && source .venv/bin/activate
```
）。符合PEP 668标准的系统需要此步骤。
```
wren --version
```
— 若已安装，在重新安装前确认。
```
pwd
```
— 记录当前路径。暂不询问项目应创建在何处。

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

Early branch — demo or own database?

分支选择 — 演示项目还是自有数据库？

"Try the bundled
jaffle_shop
demo first (~30s, no DB needed), or connect your own database?"

demo → point at
```
quickstart.md
```
and stop this skill.
own DB → continue.

"先尝试内置的
jaffle_shop
演示项目（约30秒，无需数据库），还是连接您自己的数据库？"

演示项目 → 指向
```
quickstart.md
```
并结束本skill。
自有数据库 → 继续流程。

Step 1 — Collect project name + database type

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

These two are the only thing Step 2 needs; ask both together so the user has a clean handoff:

"Two things before I scaffold:
Project name — I'll create
~/<name>/
and
cd
into it.
Database type — run
wren docs connection-info
(no argument) to see the full list, or pick a common one:
postgres
,
mysql
,
bigquery
,
snowflake
,
clickhouse
,
trino
,
duckdb
, …"

Wait for both. Don't ask for credentials.

这两项是步骤2所需的全部信息，可同时询问以便用户顺畅交接：

"搭建项目前需要两个信息：
项目名称 — 我将创建
~/<name>/
目录并进入该目录。
数据库类型 — 运行
wren docs connection-info
（无参数）查看完整列表，或选择常见类型：
postgres
、
mysql
、
bigquery
、
snowflake
、
clickhouse
、
trino
、
duckdb
……"

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

Step 2 — Workspace + .env setup (batch)

步骤2 — 工作区 + .env设置（批量操作）

Side effects: creates

~/<project>/

, installs

wren-engine[<ds>,main]

, generates an empty

.env

template. The project files (

wren_project.yml

etc.) come later in Step 3.5 — at this point we only have a directory with credentials waiting to be filled.

Run as a batch — report each command briefly, then end with one "please fill

.env

" ask:

```
mkdir -p ~/<project> && cd ~/<project>
```
.

pip install "wren-engine[<ds>,main]"

. For datasource-specific install gotchas (macOS mysql, etc.), see

connect.md#per-datasource-setup-notes

Generate the
.env
template by introspecting the connector:
bash
```
wren docs connection-info <ds> --format md
```
Use the field list to write
```
.env
```
with
```
<DS>_<FIELD>=
```
keys (UPPER_SNAKE), values empty. Example for postgres:
ini
```
POSTGRES_HOST=
POSTGRES_PORT=5432
POSTGRES_DATABASE=
POSTGRES_USER=
POSTGRES_PASSWORD=
```
Special encodings (BigQuery base64, Snowflake account format, Athena AWS creds, etc.) are documented in
```
connect.md#per-datasource-setup-notes
```
. Surface the relevant section to the user verbatim — don't paraphrase.
Add
```
.env
```
to
```
.gitignore
```
if the project is a git repo. Suggest
```
chmod 600 .env
```
.
Tell the user:
```
.env
```
is at
```
<path>
```
, please fill every value and reply "done".

操作结果：创建

~/<project>/

目录，安装

wren-engine[<ds>,main]

，生成空的

.env

模板。项目文件（如

wren_project.yml

等）将在步骤3.5中生成——此时仅创建一个包含待填充凭证的目录。

批量运行以下命令——简要报告每个命令的执行情况，最后提示用户“请填充

.env

文件”：

```
mkdir -p ~/<project> && cd ~/<project>
```
。
```
pip install "wren-engine[<ds>,main]"
```
。数据源特定的安装注意事项（如macOS系统的mysql安装等），请查看
```
connect.md#per-datasource-setup-notes
```
。
通过自省连接器生成
.env
模板：
bash
```
wren docs connection-info <ds> --format md
```
使用字段列表创建
```
.env
```
文件，键名为
```
<DS>_<FIELD>
```
（大写蛇形命名），值留空。postgres示例：
ini
```
POSTGRES_HOST=
POSTGRES_PORT=5432
POSTGRES_DATABASE=
POSTGRES_USER=
POSTGRES_PASSWORD=
```
特殊编码格式（如BigQuery的base64、Snowflake的账户格式、Athena的AWS凭证等）记录在
```
connect.md#per-datasource-setup-notes
```
中。直接向用户展示相关章节内容——不要改写。
如果项目是git仓库，将
```
.env
```
添加到
```
.gitignore
```
中。建议运行
```
chmod 600 .env
```
。
告知用户：
```
.env
```
文件位于
```
<path>
```
，请填充所有值并回复**"done"**。

Step 3 — Create the connection profile

步骤3 — 创建连接配置文件

Only after the user replies "done".

Write

/tmp/conn.yml

with every field as a
${VAR}
placeholder matching the

.env

keys you generated in Step 2:

yaml

datasource: <ds>
host: ${<DS>_HOST}
port: ${<DS>_PORT}

仅在用户回复"done"后执行。

创建

/tmp/conn.yml

文件，每个字段均使用与步骤2中生成的
.env
键名对应的
${VAR}
占位符：

yaml

datasource: <ds>
host: ${<DS>_HOST}
port: ${<DS>_PORT}

… one line per field from

wren docs connection-info <ds>

… 每一行对应

wren docs connection-info <ds>

中的一个字段


Then:

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

Validation runs automatically. The CLI overwrites profiles silently — there is no

--force

flag.

✓ Success → continue to Step 3.5.
⚠ Any warning → consult
```
connect.md#troubleshooting
```
for the exact symptom (missing secret, driver auth failure, ValidationError, unreachable host, …) and tell the user what to fix.


然后运行：

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

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

--force

参数。

✓ 成功 → 进入步骤3.5。
⚠ 任何警告 → 根据具体症状（缺失密钥、驱动认证失败、ValidationError、主机不可达等）查阅
```
connect.md#troubleshooting
```
，并告知用户需要修复的内容。

Step 3.5 — Scaffold the project

步骤3.5 — 搭建项目脚手架

bash

wren context init --empty

Refuses to overwrite an existing

wren_project.yml

. Creates the project directory layout (

models/

views/

relationships.yml

instructions.md

AGENTS.md

queries.yml

bash

wren context init --empty

该命令不会覆盖已有的

wren_project.yml

文件。会创建项目目录结构（

models/

、

views/

、

relationships.yml

、

instructions.md

、

AGENTS.md

、

queries.yml

）。

Step 3.6 — Bind the profile to the project

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

bash

wren context set-profile <project>

Writes both

profile: <project>

and

data_source: <ds>

into

wren_project.yml

(data_source is taken from the profile we just validated, so it's guaranteed correct). Future CLI commands and the SDK resolve the connection deterministically — independent of which profile is globally active.

This step also future-proofs the project for multi-project setups: once the binding is recorded, switching

wren profile switch

elsewhere never breaks this project's queries.

bash

wren context set-profile <project>

会将

profile: <project>

和

data_source: <ds>

写入

wren_project.yml

（data_source取自刚验证过的配置文件，因此确保正确）。后续的CLI命令和SDK会确定性地解析连接——与全局激活的配置文件无关。

此步骤还为多项目设置提供了前瞻性支持：一旦绑定记录完成，在其他地方运行

wren profile switch

绝不会破坏本项目的查询。

Step 4 — Generate MDL (hand off)

步骤4 — 生成MDL（移交至其他skill）

⚠️ The agent must build MDL before any data query. Queries against tables not in MDL will fail.

Invoke the wren-generate-mdl
skill. It walks the agent through table introspection, type normalization, and YAML generation. When it finishes, return here and run:

bash

wren context validate
wren context build

Report the model count and any validate warnings.

Memory recommendation: count models with

wren context show | grep -c '^model:'

. If

>= 200

, suggest

pip install "wren-engine[memory]"

wren memory index

(~800 MB). If

< 200

, skip.

⚠️ agent必须在查询数据前生成MDL。对不在MDL中的表进行查询会失败。

调用**

wren-generate-mdl

** skill。它会引导agent完成表自省、类型规范化和YAML文件生成。完成后返回此处并运行：

bash

wren context validate
wren context build

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

内存建议：运行

wren context show | grep -c '^model:'

统计模型数量。如果数量

>= 200

，建议运行

pip install "wren-engine[memory]"

wren memory index

（约占用800 MB内存）。如果数量

< 200

，可跳过此步骤。

Step 5 — Ready to explore (hand off)

步骤5 — 准备探索（移交至其他skill）

Suggest 2–3 NL questions based on the discovered tables (e.g. for an orders schema: "How many orders last month?", "Top 5 customers by total"). Then end this skill: for day-to-day querying the agent should switch to the wren-usage
skill.

根据发现的表建议2-3个自然语言问题（例如，对于订单表：“上个月有多少订单？”、“消费总额前五的客户是哪些？”）。然后结束本skill：日常查询应切换至**

wren-usage

** skill。

Cross-skill routing

跨skill路由

Trigger	Skill
User mentions a SaaS source (HubSpot, Stripe, Salesforce, GitHub, Slack, …)	`wren-dlt-connector`
User has a connected DB but no MDL yet	`wren-generate-mdl`
User has MDL ready, wants to query	`wren-usage`
Anything else from-scratch	`wren-onboarding` (this skill)

触发条件	对应skill
用户提及SaaS数据源（HubSpot、Stripe、Salesforce、GitHub、Slack等）	`wren-dlt-connector`
用户已连接数据库但尚未生成MDL	`wren-generate-mdl`
用户已准备好MDL，想要查询数据	`wren-usage`
其他从零开始的场景	`wren-onboarding` （本skill）

On error

错误处理

Don't carry an error playbook here — surface

connect.md#troubleshooting

sections to the user. The doc covers:

```
wren: command not found
```

pip install … externally-managed-environment

Missing secret (
```
MissingSecretError
```
)
Driver authentication failures
Pydantic
```
ValidationError
```
/ unknown datasource
Connection refused / firewall / cloud DB IP allow-list
```
wren context validate
```
warning categories

If you hit something not in the playbook, tell the user:

"I hit an error I don't know how to fix:
<error>
. See https://docs.getwren.ai/oss/introduction or open an issue at https://github.com/Canner/WrenAI/issues."

此处不包含错误排查手册——直接向用户展示

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提交问题。"

wren-onboarding

Original

Translation

Wren Onboarding — Agent Workflow

Wren 入门引导 — Agent 工作流

Version check

版本检查

Mode of operation — READ THIS FIRST

操作模式 — 请先阅读本部分

Preflight (environment only — no user questions about the project)

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

Early branch — demo or own database?

分支选择 — 演示项目还是自有数据库？

Step 1 — Collect project name + database type

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

Step 2 — Workspace + .env setup (batch)

步骤2 — 工作区 + .env设置（批量操作）

Step 3 — Create the connection profile

步骤3 — 创建连接配置文件

… one line per field from
`wren docs connection-info <ds>`

… 每一行对应
`wren docs connection-info <ds>`
中的一个字段

Step 3.5 — Scaffold the project

步骤3.5 — 搭建项目脚手架

Step 3.6 — Bind the profile to the project

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

Step 4 — Generate MDL (hand off)

步骤4 — 生成MDL（移交至其他skill）

Step 5 — Ready to explore (hand off)

步骤5 — 准备探索（移交至其他skill）

Cross-skill routing

跨skill路由

On error

错误处理

wren-onboarding

Original

Translation

Wren Onboarding — Agent Workflow

Wren 入门引导 — Agent 工作流

Version check

版本检查

Mode of operation — READ THIS FIRST

操作模式 — 请先阅读本部分

Preflight (environment only — no user questions about the project)

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

Early branch — demo or own database?

分支选择 — 演示项目还是自有数据库？

Step 1 — Collect project name + database type

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

Step 2 — Workspace + .env setup (batch)

步骤2 — 工作区 + .env设置（批量操作）

Step 3 — Create the connection profile

步骤3 — 创建连接配置文件

… one line per field from wren docs connection-info <ds>

… 每一行对应wren docs connection-info <ds>中的一个字段

Step 3.5 — Scaffold the project

步骤3.5 — 搭建项目脚手架

Step 3.6 — Bind the profile to the project

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

Step 4 — Generate MDL (hand off)

步骤4 — 生成MDL（移交至其他skill）

Step 5 — Ready to explore (hand off)

步骤5 — 准备探索（移交至其他skill）

Cross-skill routing

跨skill路由

On error

错误处理

… one line per field from
`wren docs connection-info <ds>`

… 每一行对应
`wren docs connection-info <ds>`
中的一个字段