使用 Kilo Code 安装与接入 Wren AI：基于 Agent Skills 的 Text-to-SQL 快速上手

使用 Kilo Code 安装与接入 Wren AI：基于 Agent Skills 的 Text-to-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

本篇技术指南以 docs/core/get_started/quickstart-with-agent/kilo.md 为核心骨架，讲解如何在 VS Code 的编码 AgentKilo Code（Roo Code 的 fork）中安装 Wren AI 的 Agent Skills，并通过一个提问完成环境检查、Profile 创建、项目脚手架与首次查询的完整 onboarding 流程。读完本文，你将掌握npx skills安装方式、--agent kilo参数的作用、/wren技能背后的 discovery stub 架构，以及从零到可提问的完整接入链路。

1. 背景：为什么要在 Kilo Code 里安装 Wren AI Skills

Kilo Code 是 VS Code 生态中的一款编码 Agent（本仓库文档对其定位为 Roo Code 的分支）。Wren AI 的核心能力是GenBI / governed text-to-SQL：通过一个开放的 context layer，把自然语言问题转成可信的 SQL、图表与看板，支持 BigQuery、Snowflake、PostgreSQL、ClickHouse、Amazon Redshift、Databricks 等 20+ 数据源。

要让 Kilo Code 这样的 Agent 学会操作 Wren AI，仓库采用了一套Skills 分发架构：

• 真正的技能内容住在wrenCLI 内部（pip install wrenai后随包分发），即 core/wren/src/wren/skills_content/ 目录下的各份SKILL.md工作流指南；
• 仓库的 skills/ 目录只维护一个 discovery stub（wren），Agent 安装一次 stub 后，在运行时通过wren skills get <name>按需拉取指南，因此内容永远与已安装的 wrenai 版本匹配，不存在技能缓存与版本漂移。

这一点在 skills/README.md 中有明确说明，并由 core/wren/tests/unit/test_skill_stubs.py 的守卫测试保证（旧的五个 fat skills 目录与versions.json已被移除，只允许单一 discovery stub 存在）。

2. 前置条件

开始之前，请确认：

• Kilo Code已安装并完成登录认证（官网地址见原文档，此处不展开）；
• Python 3.11+：Wren AI 的 CLI 要求的最低 Python 版本，onboarding 技能的 preflight 第一步就会检查python3 --version；
• Node.js / npm：用于执行npx skills add安装技能（见下文）；
• Git：克隆示例项目等场景会用到。

3. 安装 Wren Skills：npx skills add与--agent kilo

在终端中执行：

npx skills add Canner/WrenAI --agent kilo

这条命令完成两件事：

1. 从Canner/WrenAI仓库拉取 skills/wren/SKILL.md 这份 discovery stub；
2. 通过--agent kilo将 stub 安装到 Kilo Code 对应的技能目录（npx skills会自动探测你的 AI 客户端；要精确指定某个客户端时使用--agent <name>，例如claude-code、cursor、windsurf、cline，kilo也是其中之一）。

如果你更喜欢脚本方式，仓库还提供了等效的本地安装脚本 skills/install.sh：

bash skills/install.sh # 安装 discovery stub bash skills/install.sh --force # 覆盖已有安装

该脚本会读取DEST="${CLAUDE_SKILLS_DIR:-$HOME/.claude/skills}"作为目标目录（可用环境变量覆盖），并把skills/wren整个目录复制过去。安装完成后，在 Agent 中输入/wren即可唤起。

关于 stub 的元数据，skills/index.json 中定义了它的描述：它教会 Agent 调用wren skills list、wren skills get <name>、wren ask <prompt> --guided|--direct，并在用户提出数据问题、安装/设置 Wren、连接数据库、生成 MDL、构建 GenBI 应用等场景时自动触发。

4. 运行 onboarding：启动 Kilo Code 并下达一条指令

4.1 两种启动方式

在 VS Code 中打开你的项目文件夹（需已安装 Kilo Code 扩展），然后任选其一：

• 图形界面：点击 Activity Bar（活动栏）中的 Kilo 图标；
• 命令行：

kilo

4.2 下达指令

进入对话后，直接提问：

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

Kilo Code 会识别这条请求并加载/wren技能（即上一步安装的 discovery stub），随后由wrenstub 指引 Agent 拉取onboarding工作流指南（对应wren skills get onboarding，其内容位于 core/wren/src/wren/skills_content/onboarding/SKILL.md）。

根据该技能的定义，整个流程会依次完成：环境检查（environment checks）→ Profile 创建（profile creation）→ 项目脚手架（project scaffolding）→ 首次查询（a first query）。

5. 深挖 onboarding 流程：Kilo Code 背后发生了什么

虽然原文档对 onboarding 只给了结论，但仓库里的 onboarding/SKILL.md 完整定义了 Agent 的行为规则，可以帮助你理解 Kilo Code 将如何执行任务：

5.1 工作模式：一次往返只做一步

技能强制 Agent每轮只执行一个步骤：先简要说明、只询问当前步骤所需的信息、运行命令、确认结果后再进入下一步。绝不允许在一开始就一次性收集项目名、数据库类型、账号密码等所有信息。

5.2 Preflight 环境检查（只读）

Agent 先做四项只读检查并汇报：

1. python3 --version—— 要求 Python 3.11+，不满足则请用户升级并停止；
2. 虚拟环境检查：python3 -c "import sys; print(sys.prefix != sys.base_prefix)"，在 PEP 668 系统上需要python3 -m venv .venv && source .venv/bin/activate；
3. wren --version—— 若已安装则先确认再决定是否重装；
4. pwd—— 记录当前目录。

5.3 Profile 创建与项目脚手架

• 通过wren docs connection-info <ds> --format md动态生成连接字段清单（字段从实时的 Pydantic schema 内省而来，保证准确）；
• 用wren profile add <project> --from-file /tmp/conn.yml创建连接 Profile（自动校验）；
• 用wren context init --empty生成项目目录结构（models/、views/、relationships.yml、knowledge/）；
• 用wren context set-profile <project>将 Profile 绑定到项目，写死profile与data_source，之后无论全局 active profile 如何切换，本项目查询都不会被误导向。

5.4 一个安全约束值得注意

技能明确规定绝不在聊天中索要凭据（host、port、user、password、token 都不行），凭据一律通过.env文件由用户在编辑器里填写，Agent 全程看不到明文——在 Kilo Code 中接入真实数据库时同样适用。

6. 技能分发原理：wren skills命令行是怎么工作的

Kilo Code 装好 stub 后，所有指南都由 CLI 提供。入口命令定义在 core/wren/src/wren/skills_cli.py：

wren skills list # 列出所有可用指南 wren skills get onboarding # 拉取 onboarding 主指南 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> 可获取捆绑脚本

底层实现 core/wren/src/wren/skills_delivery.py 通过importlib.resources读取包内的wren/skills_content/<name>/SKILL.md；--full会按文件名排序追加references/*.md，--script则返回scripts/下的捆绑脚本。也就是说，Kilo Code 中无论何时执行wren skills get <name>，拿到的都是与当前wrenai安装版本严格一致的指南内容。

另外，skills/wren/SKILL.md 还展示了日常查询命令（均为一等命令而非子应用）：

wren --sql '...' # 通过 MDL 层执行 SQL wren dry-plan --sql '...' # 仅做转译，不访问数据库 wren context show / build / validate wren profile add / list / switch wren memory index / recall / store # 语义记忆（需 [memory] extra）

7. 下一步：两条官方推荐路径

完成 onboarding 后，原文档给出两个继续深入的方向：

7.1 用示例数据走一遍完整 Quickstart

参考 Quickstart（jaffle_shop）：用 dbt Labs 的公开示例库jaffle_shop端到端演示。无需云数据库、无需 Docker，核心步骤包括：

1. git clonedbt 的jaffle_shop_duckdb项目并用dbt build生成jaffle_shop.duckdb；
2. pip install "wrenai[memory,main]"（DuckDB 默认内置，其他数据源追加 connector extra，如postgres、bigquery、snowflake等）；
3. npx skills add Canner/WrenAI安装技能（或curl -fsSL .../skills/install.sh | bash）；
4. wren profile add jaffle-shop --ui（推荐浏览器表单）或--interactive/--from-file三种方式创建 Profile；
5. wren context init+wren context set-profile jaffle-shop初始化并绑定项目；
6. 在项目目录打开 Agent，提问生成 MDL：

   Use the /wren skill to explore the jaffle_shop database and generate the MDL for the customers and orders tables. Skip the raw_* seeds and stg_* views. The data source is DuckDB.

7. 用wren context show、wren memory status验证，然后开始自然语言提问（例如 "How many customers placed more than one order?"）。

7.2 连接真实数据库

参考 连接数据源指南：把 Wren AI 指向真实数据库。其中会用到wren docs connection-info <ds>查看某个数据源必填/选填的连接字段，并通过.env+wren profile add完成凭据配置（对 Kilo Code 这类 Agent 而言，凭据不经过对话，安全性由 onboarding 技能的工作模式保证）。

8. 常见问题速查

场景	处理方式
安装 stub 时已存在旧版本	使用bash skills/install.sh --force覆盖
想知道当前 Agent 支持哪些安装目标	npx skills add会自动探测，--agent <name>精确指定
想查看某个数据源的连接字段	wren docs connection-info <ds>（字段来自实时 Pydantic schema）
不知道有哪些技能指南	wren skills list
想把技能参考文档一并拉取	wren skills get <name> --full

9. 关键文件索引

• docs/core/get_started/quickstart-with-agent/kilo.md —— 本文主体文档
• skills/wren/SKILL.md —— discovery stub 本体
• skills/index.json —— 技能注册元数据
• skills/install.sh —— 本地安装脚本
• skills/README.md —— 技能分发设计与安装说明
• core/wren/src/wren/skills_cli.py ——wren skills命令入口
• core/wren/src/wren/skills_delivery.py —— 技能内容加载实现
• core/wren/src/wren/skills_content/onboarding/SKILL.md —— onboarding 工作流细则
• core/wren/tests/unit/test_skill_stubs.py —— discovery stub 分发守卫测试
• docs/core/get_started/quickstart.md —— jaffle_shop 端到端 Quickstart
• docs/core/guides/connect.md —— 真实数据库连接指南

小结

在 Kilo Code 中接入 Wren AI 的核心动作只有三步：npx skills add Canner/WrenAI --agent kilo安装 discovery stub、启动kilo后输入Use the /wren skill to install and set up Wren AI.、随后由 Agent 按 onboarding 技能完成环境检查、Profile 创建、项目脚手架与首次查询。理解了 stub + CLI 按需取指南的分发模型后，你就能把同样的接入方式迁移到 Claude Code、Cursor、Windsurf、Cline 等其他 Agent，并在接入真实数据库时遵循"凭据走.env、字段来自wren docs connection-info"的安全与准确原则。

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