WrenAI Agent Skills 分发机制详解Discovery Stub 架构、安装与 CLI 工作流【免费下载链接】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本指南以 WrenAI 仓库 skills/README.md 为核心系统讲解 Wren Engine 面向 AI Agent 的Skills技能分发机制为什么技能内容全部内置于wrenCLI 而非随目录分发、三种安装 discovery stub 的方式、Agent 安装后如何通过 CLI 按需拉取六类工作流指南以及如何在仓库中新增一个技能。读完你将掌握从零开始为 Claude Code、Cursor、Cline 等 AI 客户端装配 Wren 数据查询能力并理解其无技能缓存、无版本漂移设计背后的源码原理。一、核心设计理念内容随 CLI 走目录只放发现桩在深入安装步骤之前必须先理解 WrenAI 这套技能体系的分层架构它决定了后面所有命令的组织方式。┌─────────────────────────────────────────────────────┐ │ 技能内容workflow guides / references / scripts │ │ 全部内置于 wren CLI 的 Python 包数据中 │ │ core/wren/src/wren/skills_content/name/ │ ├─────────────────────────────────────────────────────┤ │ 仓库 skills/ 目录只提供一个 discovery stub │ │ 即 skills/wren/SKILL.md供 AI 客户端一次性安装 │ ├─────────────────────────────────────────────────────┤ │ AI 客户端Claude Code / Cursor / Cline ... │ │ 安装 stub 后按需调用 wren skills get 拉取内容 │ └─────────────────────────────────────────────────────┘正如 skills/README.md 开篇所述真正的技能内容工作流指南、参考文档、提示词辅助全部存放在wrenCLI 内部skills/目录只是发布一个discovery stub发现桩AI 客户端安装一次即可。之后 Agent 在运行时通过 CLI 拉取其余一切内容——这样内容永远与已安装的 wrenai 版本匹配不会出现技能缓存过期或版本漂移。这一定位同样体现在 skills/index.json 中它声明的描述明确写着 The actual workflow guides and prompt helpers live inside the wren CLI... and are served bywren skills get/wren ask该清单本身只注册名为wren的单一 stub 技能tags 覆盖cli、sql、mdl、semantic-layer、genbi等关键词帮助 AI 客户端在会话启动时快速判断何时该触发 Wren。为什么要这样设计传统做法是把技能文件直接分发到 AI 客户端的 skills 目录一旦 CLI 升级缓存里的指南就会与当前二进制行为脱节。WrenAI 选择内容随 wheel 包发布、按需流式获取从构造上消除了版本不一致问题详见后文 AUTHORING.md 的注册新技能一节它明确注明不再需要维护versions.json/index.json。完整的命令面与设计文档见 skills/SKILLS.md它给出了比 README 更完整的命令清单包含--full、--script等选项。二、安装先装 CLI再装 Discovery Stub整个安装分两步第一步安装承载全部内容的wrenCLI第二步安装让 AI 客户端知道 CLI 存在的发现桩。两者缺一不可。2.1 安装 CLI 本身所有技能内容的载体pip install wrenai如需连接特定数据库按数据源安装对应 extrapip install wrenai[extras]从 core/wren/src/wren/skills_content/usage/SKILL.md 的 Preflight 章节可以看到可用的数据源 extra 包括postgres用于 Aurora PostgreSQL、mysql用于 Aurora MySQL、bigquery、snowflake、clickhouse、trino、mssql、databricks、redshift、spark、athena、oracle而DuckDB 默认包含无需额外 extra。若同时启用语义记忆、交互式提示与 Web UI推荐pip install wrenai[datasource,main]2.2 安装 Discovery Stub三选一README 提供三种方式让 AI 客户端感知到wrenCLI方式一Claude Code 插件市场/plugin marketplace add Canner/WrenAI --path skills /plugin install wrenwren方式二npx skills自动检测客户端npx skills add Canner/WrenAI安装器会自动检测你的 AI 客户端如需指定目标客户端追加--agent name例如claude-code、cursor、windsurf、cline。方式三本地安装脚本bash skills/install.sh # 安装 discovery stub bash skills/install.sh --force # 覆盖已存在的安装该脚本skills/install.sh的实现值得展开说明其行为由以下要点构成默认安装目标目录为$HOME/.claude/skills可通过CLAUDE_SKILLS_DIR环境变量覆盖安装的 stub 名固定为wren支持--force参数不加时若目标已存在会跳过并提示 Use --force to overwrite加--force则直接覆盖智能双模式若检测到从本地仓库克隆运行BASH_SOURCE存在且非/dev/stdin则直接复制本地skills/wren目录否则视为 curl 管道模式从仓库归档中提取skills/wren到临时目录再安装分支名可通过WREN_SKILLS_BRANCH环境变量指定默认main安装完成后提示在 AI 客户端中通过/skill即/wren唤起并提示后续更新用bash -s -- --force重跑。三、Agent 拿到 Stub 之后按需拉取技能内容安装完成后Agent 阅读wren/SKILL.md即 skills/wren/SKILL.md即可学会调用以下命令wren skills list # 发现全部工作流指南 wren skills get onboarding # 拉取某份指南六选一 wren docs connection-info ds # 获取某个数据源的连接字段 wren ask question --guided|--direct # 为 Agent 包装一条提示词其中wren skills list会列出所有可用指南及其附带资源。以 core/wren/src/wren/skills_cli.py 的实现为准list命令调用skills_delivery.list_skills()对每个技能打印名称、一行摘要取自 SKILL.md frontmatter 的description截断到 100 字符并额外标注该技能附带哪些references与scripts。3.1 六大门户技能从建连到部署的完整闭环skills/wren/SKILL.md 列出了完整的技能清单覆盖 Wren Engine 使用的全部主要场景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 可包含该技能的参考文档 # 追加 --script name 可拉取捆绑脚本如 dlt-connector 的 introspect_dlt这些指南的内容实体位于仓库 core/wren/src/wren/skills_content/ 下的同名目录。以 onboarding 技能 为例其工作流极具代表性能直观说明Agent 拿指南做什么Preflight 环境检查确认 Python 3.11、虚拟环境、wren --version与当前目录只读检查不向用户追问项目细节分支决策询问用户先跑内置jaffle_shop演示约 30 秒、无需数据库还是连接自己的数据库Step 1 收集项目名 数据库类型仅这两项禁止一次性收集全部信息严禁在聊天中索要任何凭据——凭据一律通过.env文件由用户在编辑器内填写Agent 永远看不到明文Step 2 创建工作区与.env运行wren docs connection-info ds --format md从实时 Pydantic 模型内省连接字段据此生成DS_FIELD形式的空.env模板Step 3 创建连接 profile将每个字段写成${VAR}占位符生成/tmp/conn.yml再执行wren profile add project --from-file /tmp/conn.yml自动校验静默覆盖旧 profile无--force标志Step 3.5/3.6 脚手架项目并绑定 profilewren context init --empty创建models/、views/、relationships.yml、knowledge/等目录wren context set-profile project把profile与data_source写入wren_project.yml使该项目未来查询与全局活跃 profile 解耦Step 4 生成 MDL 并校验转交wren skills get generate-mdl完成后执行wren context validate与wren context build若模型数 ≥ 200 建议安装wrenai[memory]并执行wren memory indexStep 5 移交日常查询给出 23 个基于已发现表结构的自然语言问题建议并将后续查询工作流转交wren skills get usage。该技能还内置了跨技能路由表提到 SaaS 源HubSpot、Stripe、Salesforce、GitHub、Slack→dlt-connector已连接数据库但无 MDL →generate-mdlMDL 就绪要查询 →usage其他从零开始 →onboarding。3.2 参考文档与提示词增强wren docs connection-info ds # 某数据源必填 可选连接字段 wren ask question --guided # 为较弱的 LLM 包装问题严格任务流程 wren ask question --direct # 为较强的 LLM 包装问题最小包装wren ask --guided与--direct的语义差异对应 core/wren/src/wren/ask_templates/ 下的两套模板guided.md.tmpl与direct.md.tmpl前者给弱模型强约束的任务流程后者尽量少包裹以发挥强模型能力。README 还提示完整参考文档位于仓库 docs/core 目录。3.3 日常数据命令顶层命令非子应用除技能获取命令外skills/wren/SKILL.md 还列举了 Agent 日常直接可用的顶层命令wren --sql ... # 通过 MDL 层执行 SQL wren query --sql ... # 同上显式子命令 wren dry-plan --sql ... # 仅做转译不触达数据库 wren context show / build / validate # 项目 / MDL 生命周期 wren profile add / list / switch # 命名连接 profile wren memory index / recall / store # 语义记忆需要 [memory] extra这些命令的注册与实现位于 core/wren/src/wren/cli.py顶层wren应用通过app.add_typer(...)挂载了skills_app、context_app、profile_app、memory_app、genbi_app、docs_app等子命令组wren --sql与wren query --sql共享_build_engine路径——它会优先解析项目绑定的 profile含${VAR}环境变量展开见expand_profile_secrets再回退到~/.wren/connection_info.json或显式传入的--connection-file。运行wren --help可查看完整命令面。四、深入源码内容分发与渐进式披露原理4.1skills_delivery内容如何在运行时被读取所有技能获取命令的底层逻辑都在 core/wren/src/wren/skills_delivery.py 中其关键机制如下内容根目录通过importlib.resources.files(wren) / skills_content定位即技能内容作为Python 包数据随 wheel 一起安装因此天然与 CLI 版本绑定get_skill(name, fullFalse)读取该技能目录下的SKILL.md当fullTrue时会把references/目录下所有按文件名排序的.md追加到主指南之后每篇以# Reference: name分隔标题衔接get_script(name, script)在scripts/目录中按文件名去扩展名匹配返回脚本源码文本list_skills()遍历skills_content下所有含SKILL.md的目录解析 frontmatter 的description生成一行摘要超 100 字符截断加省略号并统计references/与scripts/未命中时抛出SkillNotFoundError/ScriptNotFoundError由 skills_cli.py 捕获后打印Run wren skills list for available names.的提示并以退出码 1 结束。4.2 渐进式披露Progressive Disclosure三级内容加载模型AUTHORING.md 用一个清晰的表格定义了技能内容的分层加载策略这也是 Agent 上下文管理的核心层级内容何时加载1 — Discovery stubskills/wren/SKILL.md的 frontmatter 描述约几百 token每次 AI 客户端会话启动2 — 主指南wren skills get nameAgent 判定用户任务匹配时执行该命令3 — 参考文档wren skills get name --fullAgent 需要深入细节时按需选择3 — 捆绑脚本wren skills get name --script s同上因此SKILL.md正文应控制在约 500 行以内参考型内容一律下沉到references/。这与onboarding/SKILL.md的做法完全一致——它明确写道过程细节、各数据源设置说明与排障手册都在文档里技能只负责执行 Agent 侧规则每步一个回合、绝不在聊天中索要凭据并把 Agent 引导到正确的文档/兄弟技能。4.3 技能内容的标准目录结构skills/AUTHORING.md 规定了每个技能在core/wren/src/wren/skills_content/下的布局也适用于对本仓库现有技能的阅读导航name/ ├── SKILL.md # 必需 —— frontmatter 工作流指令 ├── references/ # 可选 —— 参考文档由 wren skills get name --full 提供 │ ├── some-topic.md │ └── another-topic.md └── scripts/ # 可选 —— 捆绑脚本由 wren skills get name --script s 提供frontmatter 遵循 Agent Skills 开放规范但有意去掉了version:字段——因为内容版本即已安装的 wrenai 版本SKILL.md 随 wheel 分发无需独立版本号。命名约定为技能目录kebab-case、name字段与目录同名、参考文档与脚本均用描述性kebab-case脚本示例introspect_dlt.py。以现有技能为参照usage技能附带references/memory.md与references/wren-sql.md两份参考enrich-context附带references/cube_proposals.md与references/gap_catalog.mddlt-connector附带references/dlt_sources.md与scripts/introspect_dlt.py。4.4 测试保障内容交付契约仓库用 core/wren/tests/unit/test_skills_cli.py 固化了内容交付契约主要断言包括六技能齐备list_skills()的结果必须恰为{onboarding, usage, generate-mdl, dlt-connector, enrich-context, genbi}内容剥离所有技能的 SKILL.md 都不得再包含versions.json、## Version check 或 frontmatter 中的version:字段验证版本漂移补丁已被移除这一设计目标--full行为get_skill(enrich-context, fullTrue)必须比主指南更长且包含# Reference: cube_proposals与# Reference: gap_catalog无references/目录的技能如onboarding在--full下返回与主指南完全一致--script行为get_script(dlt-connector, introspect_dlt)必须以#!/usr/bin/env python3开头且包含introspect--full不会把脚本内联进指南错误提示未知技能名必须提示Runwren skills list。4.5 如何新增一个技能按 skills/AUTHORING.md 的注册流程新增技能不在skills/目录下新建文件夹而是在core/wren/src/wren/skills_content/name/下创建SKILL.md及可选的references/、scripts/按前述规范撰写内容在 core/wren/tests/unit/test_skills_cli.py 中为wren skills get name与--full若含 references各加一条测试完成——无需更新任何versions.json/index.json包数据随 wheel 发布wren skills list自动枚举。五、前置条件与环境要求按 skills/README.md 的 Requirements 小节使用这套技能体系需要wrenCLI 已安装pip install wrenai或pip install wrenai[extras]一个数据库连接通过wren profile add配置profile 支持${VAR}环境变量占位见 onboarding 技能 的 Step 3所有字段写成${VAR}占位符验证自动执行支持 skills 的 AI 客户端Claude Code、Cursor、Cline 等。此外 onboarding 技能 强调的 Agent 侧铁律也适用于所有使用场景每步一个回合、只在需要时才收集信息、绝不在聊天中索要凭据、MDL 构建完成前不得查询数据库、不臆造连接字段名一律以wren docs connection-info ds的实时内省结果为准。六、结语一套面向 Agent 的零漂移技能分发范式WrenAI 的 skills 体系提供了一个值得借鉴的模式把技能内容与技能发现分离——分发到 AI 客户端的只是一个几百 token 的轻量桩skills/wren/SKILL.md真正的工作流指南、参考文档与辅助脚本全部内置于wrenCLI 包数据中按需流式获取。这带来的直接收益是技能内容永远与已安装的 wrenai 版本一致无缓存、无版本漂移Agent 上下文占用被渐进式披露压缩到最小同时一套命令面wren skills list/get/ask/docs即可支撑从数据库建连、MDL 生成、业务上下文增强到 GenBI 部署的完整数据工作流。对本仓库的读者而言无论是想快速给本地 AI 客户端接入 Wren还是打算贡献一个全新技能本文给出的命令、目录约定与测试契约都可以直接落地使用。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考