AI查文档不用翻官网:duckdb-skills duckdb-docs全文检索实战详解
AI查文档不用翻官网:duckdb-skills duckdb-docs全文检索实战详解
duckdb-skills 是一个为 Claude Code 打造的 DuckDB 技能插件,其中的 duckdb-docs 技能可以像搜索引擎一样全文检索 DuckDB 官方文档和技术博客,你只需用一句自然语言提问,AI 就能精准定位相关文档片段,再也不用手动翻官网、点目录了 🎯
为什么需要文档全文检索
用 DuckDB 写 SQL 时,你是否遇到过这种场景:
- 想知道某个函数怎么用,打开官网一层层点目录,找不到就换关键词再翻
- 报了一个报错,想查官方说明,却不知该从哪一页开始看
- 想确认某个功能在哪个版本引入,
lts还是current?
duckdb-docs 技能把整个 DuckDB 文档做成了可全文检索的数据库索引,直接问、直接答,官方文档里有什么就答什么,还附带来源链接。
快速安装 duckdb-skills 插件
在 Claude Code 中执行以下两条命令即可完成安装(具体说明见 README.md):
/plugin marketplace add duckdb/duckdb-skills
/plugin install duckdb-skills@duckdb-skills
安装后,所有技能都会以 /duckdb-skills:<技能名> 的形式可用。如果本机还没装 DuckDB CLI,技能会自动引导你走 /duckdb-skills:install-duckdb 完成安装(流程定义在 skills/install-duckdb/SKILL.md)。
工作原理:搜索索引 + 本地缓存 + BM25 打分
duckdb-docs 的核心流程定义在 skills/duckdb-docs/SKILL.md 中,整体分为几步,理解了它就知道为什么"不用翻官网":
1. 两个官方搜索索引
| 索引 | 覆盖内容 | 可用版本 | 适用场景 |
|---|---|---|---|
| DuckDB 文档 + 博客 | 官方文档与技术博客 | lts、current、blog |
默认,任何 DuckDB 问题 |
| DuckLake 文档 | DuckLake 目录服务相关 | stable、preview |
提到 DuckLake、catalog 时 |
2. 本地缓存加速
索引会通过 httpfs 扩展下载到 ~/.duckdb/docs/ 目录做本地缓存,2 天内有效。缓存过期才重新拉取,后续检索直接读本地文件,速度快且省流量(缓存机制见 SKILL.md)。
3. BM25 全文检索
每条文档在索引里被切成"块"(chunk),包含页面标题、章节、面包屑、URL 和正文。检索时由 DuckDB 的 fts 全文搜索扩展执行 BM25 打分,按相关度排序返回 Top 8 结果。
也就是说:你问的每个问题,都在和整个官方文档库做相关性排序,而不是靠人眼翻目录。
实战示例:一句话查文档
安装完成后,直接问:
/duckdb-skills:duckdb-docs window functions
或更口语化的自然语言:
/duckdb-skills:duckdb-docs "how do I read a CSV with custom delimiters?"
技能会自动完成这些事(对应 SKILL.md 的搜索词提取逻辑):
- 提取关键词:把自然语言问题压缩成紧凑的技术词(函数名、SQL 关键字),丢掉 "how"、"do" 这类停用词
- 选择索引和版本:默认查 DuckDB 文档的
lts版本;问博客背景用blog,问最新特性用current - 返回文档片段:每个结果包含章节标题、页面标题、URL 和正文,按相关度排序
- 直接给出答案:基于检索到的文档综合出简洁回答,如果文档直接回答了问题,会先给答案再列来源 🔍
对于报错排查场景也适用——比如查询出错时,把错误信息作为关键词传给 duckdb-docs 就能查官方说明(skills/query/SKILL.md 中也内置了这个自动查文档的机制)。
版本怎么选?一张表说清楚
| 你的问题 | 应查版本 |
|---|---|
| 常规用法、生产环境写法 | lts(默认) |
| 刚发布的新特性 | current |
| 想了解设计动机、背景故事 | blog |
| DuckLake 相关问题 | DuckLake 索引的 stable |
| 不确定 | 不加版本过滤,全版本检索 |
这个策略同样定义在 skills/duckdb-docs/SKILL.md。
常见问题与排查
| 现象 | 解决办法 |
|---|---|
提示 fts / httpfs 扩展未安装 |
执行 /duckdb-skills:install-duckdb fts httpfs 后重试 |
| 拉取索引失败(网络不可达) | 检查网络连接,索引托管在 duckdb.org 官方服务器上 |
| 检索结果为空 | 删掉最次要的关键词、换更短的词重试,仍无结果则建议直接看官方文档站 |
排查细节可见 skills/duckdb-docs/SKILL.md 的 Step 6。
总结
duckdb-skills 的 duckdb-docs 技能把"翻官网查文档"变成了"一句话问文档":
- 📚 覆盖全:官方文档 + 技术博客全文建索引
- ⚡ 速度快:本地缓存 + BM25 全文检索
- 🎯 够聪明:自然语言自动提取关键词、自动选版本、自动综合答案
装上之后,下次查 DuckDB 函数、报错原因或新特性,直接问 AI 就好。更多技能(如 query、read-file、attach-db)的介绍可在 README.md 中查看。