WrenAI Wren CLI 技能发现指南：面向 AI Agent 的语义 SQL 层操作手册-开发者社区

WrenAI Wren CLI 技能发现指南：面向 AI Agent 的语义 SQL 层操作手册

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

本文以仓库 skills/wren/SKILL.md 为骨架，结合wrenCLI 的源码实现（skills_cli.py、skills_delivery.py、cli.py）与完整命令参考 docs/cli.md 展开。读者将掌握：如何安装wrenai、如何通过wren skills发现并加载六类内置工作流指南、如何用wren ask做提示词增强、以及如何用wren --sql / context / profile / memory等顶层命令完成从"连接数据库 → 生成 MDL → 查询数据 → 沉淀记忆 → 部署 GenBI 应用"的全流程。文中所有命令与行为均以当前仓库所对应的 wrenai 版本为准。

设计理念：为什么这是一个 "Discovery Stub"

skills/wren/SKILL.md本身是一份发现桩（discovery stub），它刻意保持轻量，只负责两件事：告诉 Agent「wren CLI 是什么、能干什么、什么时候该触发它」，以及「详细的流程指南去哪里取」。

其 frontmatter 中的description字段（技能元数据）给出了非常明确的触发条件：只要用户提出数据类问题（how many、show me、top N、compare、trend、breakdown、metric、revenue、customers、orders），或提到安装/设置 Wren Engine、连接新数据库、通过 dlt 连接 SaaS 数据（HubSpot、Stripe、Salesforce、GitHub、Slack）、从数据库 schema 生成/重新生成 MDL 项目、用业务上下文（枚举含义、单位、ARR/DAU/churn 等 cube）丰富项目、或把项目的 context layer 变成可分享的 GenBI Web 应用并部署到 Vercel/Cloudflare，就应该触发本技能。

关键设计决策是：真正的流程指南全部内置于wrenCLI 本身，而不是存放在技能文件里。这样做的好处是文档永远与用户实际安装的 wrenai 版本严格匹配——没有技能缓存，没有版本漂移。从源码看，这一机制由 skills_delivery.py 实现：技能内容作为包数据随 wheel 一起发布在wren/skills_content/<name>/目录下（仓库中可见dlt-connector、enrich-context、genbi、generate-mdl、onboarding、usage六个子目录，每个目录内含SKILL.md，部分还带references/参考文档与scripts/脚本），wren skills get <name>会从包数据中实时读出对应的SKILL.md主指南，--full则把references/*.md按文件名排序追加在主指南之后。

安装

pip install wrenai

如果只需要 DuckDB 作为数据源，默认安装即可（DuckDB 无需额外 extra）。若计划连接其他数据库，则按数据源安装对应 extra：

# 例如连接 PostgreSQL pip install "wrenai[postgres]" # 同时启用语义记忆（memory）、交互式提示（interactive）与 Web UI pip install "wrenai[postgres,main]"

wrenai[main]包含memory、interactive、ui三个额外功能包。安装后可用wren --version验证版本。项目支持的数据源在 connector/ 目录中对应实现（athena、bigquery、canner、clickhouse、databricks、datafusion、duckdb、mssql、mysql、oracle、postgres、redshift、snowflake、spark、trino），安装时可用的 extra 包括postgres（含 Aurora Postgres）、mysql（含 Aurora MySQL）、bigquery、snowflake、clickhouse、trino、mssql、databricks、redshift、spark、athena、oracle。

工作流指南：`wren skills`

列出全部可用指南

wren skills list # 所有可用的工作流指南

该命令由 skills_cli.py 的list子命令实现：遍历skills_content/下所有含SKILL.md的目录，从 frontmatter 的description字段截取一行摘要，并列出每个技能附带的references/与scripts/。输出形如：

Available skills (run `wren skills get <name>`): dlt-connector Connect SaaS data ... enrich-context Augment a Wren project with business context ... genbi Turn a Wren project's context layer into a shareable ... generate-mdl Generate a Wren MDL project by exploring a database ... onboarding Onboard a user to Wren Engine end-to-end ... usage Wren Engine CLI workflow guide for AI agents ...

拉取指定指南

wren skills get onboarding # 端到端搭建 Wren wren skills get usage # 日常查询 wren skills get generate-mdl # 从数据库 schema 生成 MDL wren skills get dlt-connector # 通过 dlt 连接 SaaS 数据源 wren skills get enrich-context # 添加业务上下文（单位、枚举、cube） wren skills get genbi # 构建并部署可分享的 GenBI Web 应用

三个可选参数：

参数	作用
`--full`	在主指南后追加该技能的`references/`参考文档
`--script <name>`	直接输出技能捆绑的脚本源码（如`dlt-connector`的`introspect_dlt`），而不是指南
`--path`（部分命令）	指定项目目录

例如拉取 dlt 连接器自带的 schema 探测脚本：

wren skills get dlt-connector --script introspect_dlt > introspect_dlt.py

六个内置技能速览

onboarding：端到端新人引导。严格"一步一个来回"，检查 Python 3.11+ 与虚拟环境、执行wren --version、初始化项目、通过.env配置连接、生成 MDL、跑通第一条查询。硬性规则包括：绝不在聊天中索要凭据（一律走.env）、绝不臆造连接字段名（必须先wren docs connection-info <ds>从实时 Pydantic schema 获取真实字段）。
usage：日常数据问题工作流。预检环境 → 收集 schema 上下文（wren context show/wren memory fetch）→ 回忆历史查询（wren memory recall）→ 用模型名（而非裸表名）写 SQL →wren dry-plan校验 →wren query执行 → 用自然语言作答。参考文档 usage/references/memory.md 详述了记忆命令的决策逻辑。
generate-mdl：从数据库发现 schema 并生成 MDL 项目。七阶段流程：检测已有项目 → 确认连接与范围 → 探索 schema（SQLAlchemy / 数据库驱动 / 裸 SQL 三选一）→ 类型归一化（parse_type）→ 搭建 YAML 项目 → 校验并构建 → 初始化记忆。详见下文。
dlt-connector：用 dlt 把 HubSpot、Stripe、Salesforce、GitHub、Slack 等 SaaS 数据加载到 DuckDB，再从加载的数据自动生成 Wren 语义项目。含 dlt 管线搭建、凭据设置、introspect_dlt.py类型归一化与 DuckDB catalog 命名等关键细节。
enrich-context：用数据库 schema 承载不了的业务上下文（枚举含义、USD vs cents 等单位、NULL 语义、-1=unknown 等魔法哨兵值、软删默认过滤、业务同义词、ARR/churn/DAU/NRR 等命名聚合指标）补全项目。支持grill（一次一个问题、用户驱动）与auto-pilot（Agent 自主推断并应用、仅在冲突与高风险变更时升级询问）两种模式，输出写入 MDL、cubes/、knowledge/rules/、knowledge/sql/既有槽位。
genbi：把 Wren 项目的 context layer 变成可分享的浏览器端 GenBI Web 应用并部署到用户的 Vercel 或 Cloudflare。CLI 负责权威构建指令（wren genbi build）与确定性状态（index、verify、deploy），Agent 按指令在apps/<name>/编写应用代码；数据模式分snapshot（数据随应用打包、纯前端查询、完全 serverless）与live（应用在查看时回调用户数仓/API）两种。

参考文档：`wren docs connection-info`

wren docs connection-info <ds> # 数据源所需的必填 + 可选连接字段

这是 Agent 获取某个数据源（如postgres、mysql、bigquery）连接字段清单的标准入口。onboarding 技能强制要求先跑这条命令再配置连接，因为字段清单是从实时 Pydantic schema 反射出来的，永远正确。连接信息本身支持两种 JSON 格式（见 docs/connections.md），CLI 会自动归一化（_normalize_conn）：

// 扁平格式 {"datasource": "postgres", "host": "localhost", "port": 5432, "database": "mydb", "user": "postgres", "password": "secret"} // Envelope 格式（MCP / Wren web 使用），自动解包 {"datasource": "duckdb", "properties": {"url": "/data", "format": "duckdb"}}

提示词增强：`wren ask`

wren ask "<question>" --guided # 面向较弱 LLM：严格任务流程 wren ask "<question>" --direct # 面向较强 LLM：最小包装

wren ask把用户的自然语言问题包装成两种模板之一并输出到 stdout，本身不执行任何查询——它产出的是一段供 Agent 消费的提示词。源码 ask.py 从ask_templates/读取模板并把<USER_PROMPT>占位符替换为用户问题；--guided与--direct必须显式二选一，无默认值（两种模式包装方式差异巨大，静默切换会改变 Agent 升级后的行为）。

guided 模板（guided.md.tmpl）：强制走严格任务流。数据类问题按wren context show → wren memory recall → 用模型名写 SQL → wren dry-plan 校验 → wren query 执行 → 自然语言作答六步推进；项目探索类问题则走wren skills list → wren skills get <name> [--full] → 遵循 markdown。约束包括：只用模型名、绝不臆造列名（以wren context show核实）、绝不在聊天中索要凭据（一律走.env）。
direct 模板（direct.md.tmpl）：最小化包装，仅提示"你有 Wren CLI 可用于语义 SQL 查询，运行wren skills list或wren --help发现能力"，把自由裁量权交给强模型。

日常数据命令（顶层命令，非子应用）

查询：默认命令

wren --sql '...'与wren query --sql '...'等价，执行查询并打印结果。这是整个 CLI 最核心的入口，等价于通过 MDL 语义层执行 SQL：

wren --sql 'SELECT COUNT(*) FROM "orders"' wren --sql 'SELECT * FROM "orders" LIMIT 5' --output csv wren --sql 'SELECT * FROM "orders"' --limit 100 --output json

输出格式支持table（默认）、csv、json。执行后还会基于 sql_classify.py 的is_exploratory判断给出wren memory store存储提示（--quiet可关闭）。从 cli.py 的入口回调可以看到：默认命令即查询，连接与 MDL 都支持自动发现。

计划与预检

wren dry-plan --sql '...' # 仅转译，不触库 wren dry-plan --sql 'SELECT order_id FROM "orders"' -d postgres # 显式数据源，无需连接文件 wren dry-run --sql 'SELECT * FROM "orders" LIMIT 1' # OK wren dry-run --sql 'SELECT * FROM "NonExistent"' # Error: table not found ...

wren dry-plan：把 MDL SQL 转译（transpile）成目标数据源的原生方言 SQL，不需要数据库连接。它是验证复杂 SQL 语义的零成本手段，-d/--datasource是唯一可以脱离连接文件显式指定方言的命令。
wren dry-run：对活库做解析 + 校验，不返回行。成功打印OK，失败打印Error: <reason>。

参数覆盖与连接解析

当~/.wren/mdl.json与~/.wren/connection_info.json存在时，所有 flag 均可选。数据源始终从connection_info.json的datasource字段（或内联--connection-info）读取。

wren --sql '...' \ --mdl /path/to/other-mdl.json \ --connection-file /path/to/prod-connection_info.json wren --sql 'SELECT COUNT(*) FROM "orders"' \ --connection-info '{"datasource":"mysql","host":"localhost","port":3306,"database":"mydb","user":"root","password":"secret"}'

默认目录由环境变量WREN_HOME控制（默认~/.wren，见 cli.py）。此外，若项目已绑定 profile，引擎会优先解析项目钉住的 profile，回退到全局 active profile，并在交给引擎前展开${VAR}环境变量引用（存储的 profile 保持不变，调试输出不会泄露真实密钥）。

项目 / MDL 生命周期：`wren context`

wren context show / build / validate # 项目 / MDL 生命周期

wren context init：初始化新项目。默认脚手架包含wren_project.yml、models/、views/、cubes/、relationships.yml、knowledge/（业务规则 + NL→SQL 对）与AGENTS.md，并自动写入忽略target/的.gitignore。--empty跳过示例模型与视图（适合随后由--from-mdl导入或让 AI Agent 自行填充）；--from-mdl从已有 MDL JSON 导入；--from-osi从 OSI YAML 一次性迁移。catalog与schema是 Wren Engine 内部命名空间，不是数据库的原生 catalog/schema——数据库的真实位置写在每个模型的table_reference里。
wren context show：展示当前项目上下文，输出格式支持summary（默认，列出模型/视图/关系/业务规则行数）、json（camelCase）与yaml（snake_case）。
wren context validate：结构校验 + 语义校验（view SQL dry-plan + 描述检查）。--strict把警告升级为错误；--level控制语义检查深度（error仅 dry-plan /warning+描述 /strict+列）；超过 10 条警告时折叠为分组摘要，--verbose逐条打印。还会检查项目钉住的 profile 是否存在。
wren context build：编译生成<project>/target/mdl.json（可用-o指定输出），默认先跑校验；schema 达到 200 个模型时会提示启用语义记忆。
其他子命令：wren context import dbt（从 dbt 项目导入）、wren context instructions（输出业务规则供 LLM 消费）、wren context set-profile <name>（把 profile 绑定到项目）、wren context upgrade（升级schema_version，支持--dry-run预览）。

命名连接配置：`wren profile`

wren profile add / list / switch # 命名连接 profile

profile 存储在~/.wren/profiles.yml，让连接配置可命名、可复用、可在项目间钉选。wren profile add <name>支持四种模式：--ui（浏览器表单）、--from-file（导入 JSON/YAML 连接文件，自动展平 envelope）、--interactive（基于字段注册表的分步提示，敏感字段隐藏输入、文件字段 base64 编码）、或--datasource <ds>内联最小 profile。添加后默认执行SELECT 1连接验证，失败仅告警不删 profile。wren profile list高亮 active profile，wren profile switch <name>切换全局 active，wren profile debug显示解析后的配置（敏感字段掩码）。

语义记忆：`wren memory`

wren memory index / recall / store # 语义记忆（需要 [memory] extra）

LanceDB 支撑的语义记忆系统，为 MDL schema 搜索与 NL→SQL 检索服务。所有子命令支持--path覆盖默认存储位置（项目内<project>/.wren/memory/，无项目时回退~/.wren/memory/）。核心命令：

wren memory index：解析 MDL manifest，用本地 embedding 把模型、列、关系、视图（以及 cube 的 measure/dimension/time_dimension 项）全部索引进 LanceDB。
wren memory fetch -q "<关键词>"：为 LLM 取 schema 上下文。基于 schema 纯文本的字符长度自动选择策略：低于 30,000 字符（约 8K token）返回完整纯文本（LLM 能看到模型→列关系、连接路径、主键等完整结构）；高于 30,000 字符改为 embedding 检索只取相关片段。CJK 文本压缩率低（约 1.5 字符/token，英文为 4:1），所以中文为主的 schema 会更早切到检索——这是偏保守的安全方向。阈值可用--threshold覆盖；检索策略下可用--type（model/column/relationship/view）与--model过滤。
wren memory describe：纯 MDL→文本转换，打印完整结构化 schema，无需 embedding 或 LanceDB。
wren memory store --nl "<问题>" --sql "<SQL>" --datasource <ds>：存储一条 NL→SQL 对，供未来 few-shot 检索。
wren memory recall -q "<关键词>"：按语义相似度检索历史 NL→SQL 对，支持--datasource、--limit（默认 3）、--output（table/json）。
wren memory status：显示索引统计（存储路径、表名、行数，如schema_items: 47 rows）。
wren memory reset [--force]：清空全部记忆表。
wren memory watch：轮询项目源文件（target/mdl.json与knowledge/sql/*.md），内容指纹变化时自动等价执行wren memory index；-i/--interval（默认 5 秒）、--reindex-on-start、--max-polls（脚本/测试用）、--mdl、--path可调。

注意：memoryextra 会捆绑约 800MB 的大型原生库（lancedb + sentence-transformers/torch）。macOS 上首次加载记忆栈可能触发一次性 XProtect/Gatekeeper 扫描并暂停约一分钟，这是正常现象；且记忆栈是惰性加载的，非 memory 命令完全不受影响。

实战示例：Agent 眼中的完整工作流

把上面所有命令串起来，一次典型的数据项目端到端流程是：

# 1. 引导 wren skills get onboarding # 端到端搭建 wren docs connection-info postgres # 查真实连接字段（勿臆造） wren profile add prod --datasource postgres --interactive # 或 --ui / --from-file # 2. 生成 MDL wren context init --path ./my_project # 由 generate-mdl 技能驱动 schema 探索与类型归一化 wren context validate --path ./my_project wren context build --path ./my_project wren memory index # 3. 日常查询 wren context show # 查看模型 wren dry-plan --sql 'SELECT ...' # 先转译校验 wren query --sql 'SELECT ...' # 再执行 wren memory store --nl "..." --sql "..." # 沉淀经验 # 4. 丰富上下文（可选） wren skills get enrich-context # 补枚举/单位/cube # 5. 发布（可选） wren skills get genbi # 构建并部署 GenBI Web 应用

关键约定与注意事项

先加载指南，再驱动多步流程：SKILL.md 明确要求——执行任何多步工作流之前，先wren skills get <name>加载对应指南；整体命令面以wren --help为准。
不臆造列名：SQL 一律使用 MDL 模型名，列名以wren context show为准（guided 模板硬性约束）。
凭据不过聊天：连接凭据一律通过.env或 profile 存放，Agent 不应在对话中索要或展示密钥。
文档与版本同源：技能内容随 wheel 发布（wren/skills_content/），wren skills get实时读取，保证指南永远匹配已安装的 wrenai 版本。
变更闭环：任何 MDL/知识修改都遵循「改 YAML →wren context validate→wren context build→wren memory index」，避免构建产物与索引失配。

WrenAI Wren CLI 技能发现指南：面向 AI Agent 的语义 SQL 层操作手册