使用 Hermes Agent 快速安装与配置 Wren AI：从 skills 安装到首次查询的完整指南-迪斯科星球

使用 Hermes Agent 快速安装与配置 Wren AI：从 skills 安装到首次查询的完整指南

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

本文是一份面向 Hermes 编码代理（coding agent）用户的实操指南，介绍如何通过 Wren AI 官方发布的wrenskill（技能包）让 Hermes Agent 自动完成环境检查、profile 创建、项目脚手架搭建与首次数据查询的全流程。读完本文，你将掌握npx skills add安装技能、用一句话触发 onboarding 工作流、以及理解该工作流在 CLI 层的真实执行逻辑，从而在任何支持 skills 的代理环境中快速复现这一套开箱即用的 GenBI（Generative BI）语义层搭建流程。

Wren AI 与 Hermes Agent：为什么需要 skill

Wren AI 是一个开源的、受治理的 text-to-SQL 平台，通过一个开放的上下文层（context layer，即 MDL——Modeling Definition Language）把自然语言问题转化为可信的 SQL 与图表，可对接 20+ 数据源（PostgreSQL、MySQL、BigQuery、Snowflake、ClickHouse、Amazon Redshift、Databricks 等）。其核心产品形态之一是Wren CLI（Python 包wrenai），而让 AI 编码代理能正确驱动 CLI 的，就是仓库中的skills/目录——它存放着一个名为wren的发现式桩（discovery stub）。

Hermes Agent 是 Vercel Labs 生态中的编码代理之一。Wren AI 为它提供了与 Claude Code、Cursor、Codex 等代理一致的技能安装方式：只安装一个极简的wren桩，真正的多步工作流指南（onboarding、usage、generate-mdl、dlt-connector、enrich-context、genbi）都内置于 CLI 内部，按需通过wren skills get <name>动态获取。

这种"桩 + 按需拉取"的设计在仓库中有明确的实现依据：skills/wren/SKILL.md的 frontmatter 中声明了allowed-tools: Bash(wren:*)，正文则写道"This is a discovery stub. The actual workflow guides and prompt helpers live inside thewrenCLI itself, so they always match the installed wrenai version (no skill cache, no version drift)"——技能内容随wrenaiwheel 分发，代理读取到的版本永远与本地安装的 CLI 一致，从根本上消除了"技能文档与 CLI 版本漂移"的问题。

前置条件

在开始之前，请确认：

Hermes Agent 已安装并完成认证。技能安装工具skills需要能识别到你的代理环境。
系统具备Python 3.11+（onboarding 工作流的环境检查项之一）。
具备npx（Node.js / npm）执行环境，因为技能安装命令默认走npx skills。
可选：Git，用于后续克隆示例数据集。

安装 wren skills

打开终端，执行：

npx skills add Canner/WrenAI --agent hermes-agent

该命令从Canner/WrenAI仓库拉取skills/wren目录，并将其安装为 Hermes Agent 的本地技能。--agent hermes-agent用于显式指定目标代理；如果省略，安装工具会自动探测已安装的编码代理（参照 installation 文档中的说明：npx skills add Canner/WrenAI会自检 Claude Code、Cursor、Cline、Codex 等客户端）。

如果你希望技能同时出现在所有已安装的代理中，可以传通配符：

npx skills add Canner/WrenAI --agent '*'

仓库还提供了一份等价的 bash 安装脚本 skills/install.sh，它支持本地仓库安装与远程 curl 管道两种模式，且支持--force覆盖已存在的安装：

curl -fsSL https://raw.githubusercontent.com/Canner/WrenAI/main/skills/install.sh | bash

注意：整个安装过程只会产生一个技能——wren。这是有意为之：从 Wren 0.8 起，工作流指南不再以独立技能目录的形式安装，而是全部打包进wrenaiPython 包内（位于core/wren/src/wren/skills_content/），由wren skills get <name>按需输出。skills/index.json中的描述也印证了这一点：它称自己为"Discovery stub for the Wren AI agent skill bundle"，并声明实际工作流由 CLI 提供。

运行 onboarding：让 Hermes Agent 接管安装流程

技能安装完成后，技能内容会在新会话启动时加载。因此请关闭当前会话，在 Hermes Agent 中打开你的项目文件夹，然后新建一个聊天会话，直接输入：

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

这句话会命中wren桩中声明的触发词（triggers），例如install wren、set up wren engine、wren onboarding。Hermes Agent 随即通过wren skills get onboarding拉取 onboard 工作流指南，并据此逐步执行。

根据仓库中 onboarding/SKILL.md 的说明，整个过程会覆盖：

环境检查（Preflight）：检查python3 --version（要求 3.11+）、虚拟环境（sys.prefix != sys.base_prefix，PEP 668 系统需要 venv）、wren --version（是否已安装）、pwd（记录工作目录）；
连接配置：通过wren docs connection-info <ds> --format md从连接器 Pydantic schema 实时内省字段，生成.env模板（如POSTGRES_HOST=、POSTGRES_PORT=5432等），凭据只写入.env，代理全程看不到值；
Profile 创建：wren profile add <project> --from-file /tmp/conn.yml（字段以${VAR}占位符形式引用.env键），随后自动校验；
项目脚手架：wren context init --empty生成models/、views/、relationships.yml、knowledge/与AGENTS.md；再用wren context set-profile <project>把 profile 绑定进wren_project.yml；
MDL 生成：转交给wren skills get generate-mdl工作流完成表结构内省、类型归一化与 YAML 生成，最后执行wren context validate与wren context build；
首次查询：基于生成的 MDL 提出 2～3 个自然语言问题，验证整条链路。

onboarding 工作流对代理侧有几条强约束（来自同一份 SKILL.md）：每次往返只做一步（one step per round-trip）、绝不在聊天中索要凭据（host/port/user/password/token 一律走.env）、在 MDL 构建完成前绝不查询数据库、绝不臆造连接字段名（必须wren docs connection-info <ds>内省真实字段）。

CLI 层是如何服务这些技能的：源码视角

从源码看，wren skills命令的实现位于 skills_cli.py：

wren skills list枚举所有内置技能，并附带展示每个技能的 references 与 scripts 列表；
wren skills get <name>输出SKILL.md主指南；--full追加所有references/*.md（按文件名排序）；--script <stem>输出某个捆绑脚本的源码。

底层交付逻辑在 skills_delivery.py 中：技能内容通过importlib.resources从wren/skills_content/读取，list_skills()从每个SKILL.md的 frontmatterdescription字段提取一句话摘要（截断至 100 字符），get_skill()支持--full拼接参考文档。也就是说，你在 Hermes Agent 里看到的每一条工作流指南，都是直接从本地安装的 wheel 中实时打印的——这也正是"零版本漂移"的机制来源。

此外，仓库还有一个 CI 守卫测试（tests/unit/test_served_content_guard.py，见 skills 参考文档），它会扫描已交付技能内容、参考文档与 ask 模板中出现的每一个wren <cmd>调用，与真实 CLI 命令树比对——确保指南永远不会教代理运行一个不存在的命令或 flag。这层保障让 Hermes Agent 按指南执行时更加可靠。

首次查询之后：day-to-day 工作流

onboarding 完成后，日常提问走usage工作流（wren skills get usage）。代理在回答每个自然语言问题时遵循一条完整链路：

取上下文：wren memory fetch --query "..."定位相关表与列；
召回相似查询：wren memory recall --query "..." --limit 3；
写 SQL：基于模型名（而非原始表名）通过上下文层编写；
执行：wren --sql "..."（简单问题直接执行；复杂问题先用wren dry-plan预演再执行）；
存储：wren memory store --nl "..." --sql "..."保存成功的 NL→SQL 对，供未来召回。

该流程的完整定义见 skills 参考文档的 usage 章节，以及 quickstart 中对应的命令速查表。

后续步骤

Quickstart with sample data—— 使用内置的jaffle_shop示例数据集，端到端走一遍完整流程（无需自备数据库，约 15 分钟）；
Connect your data—— 把 Wren AI 指向真实数据库：该文档包含完整的连接流程、按数据源区分的配置要点，以及排错手册（wren: command not found、pip install … externally-managed-environment、MissingSecretError、驱动认证失败、PydanticValidationError、连接被拒/防火墙/云数据库 IP 白名单等）。

如果你更想先"零成本"体验，也可以在 onboarding 的分支询问中选择内置 demo：代理会直接引导你进入jaffle_shop快速上手，跳过自备数据库的环节。之后无论是连接新的数据库、通过 dlt 接入 SaaS 数据（HubSpot、Stripe、Salesforce 等），还是把上下文层构建成可分享的 GenBI 网页应用并部署到 Vercel / Cloudflare，都可以用同样的方式对 Hermes Agent 说一句话，让它调用对应的wren skills get <name>工作流来完成。

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

企业官网建设流程全解析