duckdb-skills install-duckdb使用指南:一条命令装社区扩展并自动体检DuckDB版本
duckdb-skills install-duckdb使用指南:一条命令装社区扩展并自动体检DuckDB版本
duckdb-skills 是 DuckDB 官方出品的 Claude Code 插件,提供 7 个数据探索技能;其中的 install-duckdb 技能让你用一条命令批量安装 DuckDB 核心扩展与社区扩展,并在执行 --update 时自动"体检"你的 DuckDB 版本是否落后,是扩展管理的新手福音。
一、install-duckdb 技能是什么?🧩
README.md 对它的定义是:
Install or update DuckDB extensions. Supports
name@reposyntax for community extensions and a--updateflag that also checks whether your DuckDB CLI is on the latest stable version.
一句话概括,它解决三个痛点:
- 批量安装:一条命令装多个扩展,不用手动逐条敲
INSTALL - 社区扩展支持:用
name@repo语法从任意扩展仓库安装 - 自动体检:
--update模式先比对 CLI 版本,再更新扩展,老版本一目了然
技能说明文档位于 skills/install-duckdb/SKILL.md,参数提示为 [--update] [ext1 ext2@repo ext3 ...]。
二、准备工作:先装插件和 DuckDB CLI ⚙️
第 1 步:在 Claude Code 中安装插件
/plugin marketplace add duckdb/duckdb-skills
/plugin install duckdb-skills@duckdb-skills
安装后,所有技能以 /duckdb-skills:<技能名> 的形式在每个会话中可用。
第 2 步:确保本机已安装 DuckDB CLI
技能运行时会先执行 command -v duckdb 定位 DuckDB。如果没找到,它会停下来并提示你按平台安装:
| 平台 | 安装方式 |
|---|---|
| macOS | brew install duckdb |
| Linux | 使用 install.duckdb.org 官方安装脚本 |
| Windows | winget install DuckDB.cli |
💡 这也是插件的"前置引导":其他技能(如
query、read-file)发现 DuckDB 缺失时,也会主动让你走一遍 install-duckdb 流程。
三、基本用法:安装核心扩展 📦
核心扩展只需给出扩展名,技能会将其翻译成 INSTALL <name>;:
/duckdb-skills:install-duckdb spatial httpfs
技能会把所有参数拼装到一次 DuckDB 调用中完成安装:
duckdb :memory: -c "INSTALL spatial; INSTALL httpfs;"
多个扩展一次装好,省去反复打开数据库的麻烦。
四、社区扩展:name@repo 语法 🔌
想装不在核心仓库的扩展?在名字后加上 @repo 即可,技能会翻译为 INSTALL <name> FROM <repo>;:
/duckdb-skills:install-duckdb gcs@community
对应执行:
INSTALL gcs FROM community;
核心扩展和社区扩展还可以混着写,一行全搞定:
/duckdb-skills:install-duckdb spatial magic@community
五、--update 自动体检:版本检查 + 扩展更新 🩺
加一个 --update 参数,就进入"更新 + 体检"模式:
/duckdb-skills:install-duckdb --update
它分两步走:
第 1 步:体检 DuckDB CLI 版本
-
读取本地版本:
duckdb --version提取x.y.z -
拉取最新稳定版本号并比对
- 一致 → 提示 "DuckDB CLI 已是最新" ✅
- 不一致 → 主动询问是否立即升级,并自动选择平台命令(macOS 走
brew upgrade duckdb,Linux 重跑官方脚本,Windows 走winget upgrade)
第 2 步:更新扩展
- 不带扩展名 → 执行
UPDATE EXTENSIONS;,全量更新 - 带扩展名 → 只更新指定的那几个(此时
@repo部分会被忽略):
duckdb :memory: -c "UPDATE EXTENSIONS (httpfs);"
六、幕后原理:技能执行的三个步骤 🔍
对照 SKILL.md 的文档,整个流程只有 3 步,非常透明:
- Locate DuckDB:
command -v duckdb,找不到就停止并给出安装指引 - Check --update flag:有
--update走更新模式,否则走安装模式 - Build and run statements:把每个参数解析成
INSTALL或UPDATE EXTENSIONS语句,合并成单次调用执行,最后汇报成功或失败
这种"先定位、再分流、后批量执行"的设计,正是新手也能零配置上手的原因。
七、质量保障:端到端测试脚本 🧪
项目自带一套评测脚本 skills/install-duckdb/eval.sh,它会真实调用技能并验证扩展确实可加载(LOAD <ext>),覆盖的场景包括:
- 单扩展安装(httpfs、json)
- 社区扩展安装(
magic@community) - 多扩展批量安装(
spatial httpfs、spatial magic@community) - 更新模式(
--update全量 / 指定扩展) - 版本信息检查(
--update输出中必须包含版本号)
脚本会统计每个用例的耗时并汇总通过率,方便开发者回归验证。
八、进阶技巧 🚀
- 与其他技能联动:装好
httpfs后,read-file 才能顺畅读取 S3/远程文件;装好fts后,duckdb-docs 的文档全文检索才能工作 - 本地开发测试:克隆仓库
git clone https://gitcode.com/gh_mirrors/du/duckdb-skills后,用claude --plugin-dir .启动,直接跑/duckdb-skills:install-duckdb httpfs即可,修改 SKILL.md 后重启会话立即生效 - 平台支持:目前完整支持 macOS 与 Linux,Windows 尚不完全兼容,部分 shell 命令和路径处理可能异常
九、文件导航 📁
| 文件 | 说明 |
|---|---|
| skills/install-duckdb/SKILL.md | 技能核心文档,定义参数语法与执行步骤 |
| skills/install-duckdb/eval.sh | 端到端测试脚本 |
| README.md | 插件安装、全部 7 个技能一览与更新方式 |
常见问题 ❓
Q:装扩展失败怎么办?
先确认 DuckDB CLI 已安装且在 PATH 中,再检查网络能否访问扩展仓库;失败信息会在技能末尾如实汇报。
Q:--update 和直接 INSTALL 有什么区别?
INSTALL 是安装/覆盖,UPDATE EXTENSIONS 是升级已装扩展;且只有 --update 模式会附带 CLI 版本体检。
Q:如何更新这个插件本身?
两条命令:/plugin marketplace update duckdb-skills,然后 /plugin update duckdb-skills@duckdb-skills。
掌握以上用法,你就可以在 Claude Code 里用一句话管理好整个 DuckDB 扩展环境,把时间留给真正的数据分析。