mcpField
D
duckdb-docs

duckdb-docs

github.com/duckdb数据与数据库6131.3k 次安装28 周前更新
代码仓库

关于 duckdb-docs

通过本地搜索索引查找 DuckDB 或 DuckLake 文档，并在需要时刷新缓存。适合希望获取相关文档段落及技术问题综合解答的用户。

主要功能

  1. 01选择 DuckDB 或 DuckLake 索引
  2. 02选择文档版本
  3. 03刷新过期的本地缓存
  4. 04使用 BM25 搜索索引内容
  5. 05呈现文档段落并综合回答

适用场景

  1. 01查找 DuckDB 函数文档
  2. 02查询 DuckLake 专属指南
  3. 03查阅技术问题相关的博客背景

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/duckdb/duckdb-skills --skill duckdb-docs

安装后在 Claude Code 中输入/duckdb-docs确认已加载。

详细介绍

你正在帮助用户查找相关的 DuckDB 或 DuckLake 文档。

查询：$@

按顺序执行以下步骤。

步骤 1 — 检查是否已安装 DuckDB

command -v duckdb

如果未找到，则委托给 /duckdb-skills:install-duckdb，然后继续。

步骤 2 — 确保已安装所需扩展

duckdb :memory: -c "INSTALL httpfs; INSTALL fts;"

如果失败，报告错误并停止。

步骤 3 — 选择数据源并提取搜索词

查询为：$@

数据源选择

有两个可用的搜索索引：

索引远程 URL本地缓存文件名版本适用场景
DuckDB 文档 + 博客https://duckdb.org/data/docs-search.duckdbduckdb-docs.duckdblts、current、blog默认 — 适用于任何 DuckDB 问题
DuckLake 文档https://ducklake.select/data/docs-search.duckdbducklake-docs.duckdbstable、preview查询提及 DuckLake、目录或 DuckLake 特有功能时

两个索引使用相同的架构：

列类型描述
chunk_idVARCHAR (PK)例如：stable/sql/functions/numeric#absx
page_titleVARCHAR来自 front matter 的页面标题
sectionVARCHAR章节标题（页面简介为 null）
breadcrumbVARCHAR例如：SQL > Functions > Numeric
urlVARCHAR带锚点的 URL 路径
versionVARCHAR参见上表
textTEXT该文本块的完整 Markdown

默认情况下，搜索 DuckDB 文档，并筛选 version = 'lts'。以下情况使用其他版本：

  • 用户明确询问 current/nightly 功能 → version = 'current'
  • 用户询问博客文章或想了解背景/动机 → version = 'blog'
  • 用户询问 DuckLake → 搜索 DuckLake 索引，使用 version = 'stable'
  • 不确定时，省略版本筛选条件，搜索所有版本。
搜索词

如果输入是自然语言问题（例如“如何查找出现频率最高的值”），提取关键技术词（名词、函数名、SQL 关键字），组成简洁的 BM25 查询字符串。删除“如何”“我”“的”等停用词。

如果输入本身是函数名或技术术语（例如 arg_max、GROUP BY ALL），则原样使用。

在下一步中，将提取的词用作 SEARCH_QUERY。

步骤 4 — 确保本地缓存为最新

缓存位于 $HOME/.duckdb/docs/CACHE_FILENAME（其中 CACHE_FILENAME 根据步骤 3 为 duckdb-docs.duckdb 或 ducklake-docs.duckdb）。

首先，确保目录存在：

mkdir -p "$HOME/.duckdb/docs"

然后检查缓存文件是否存在且为最新（不超过 2 天）：

CACHE_FILE="$HOME/.duckdb/docs/CACHE_FILENAME"
if [ -f "$CACHE_FILE" ]; then
    MTIME=$(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE")
    CACHE_AGE_DAYS=$(( ( $(date +%s) - MTIME ) / 86400 ))
else
    CACHE_AGE_DAYS=999
fi
echo "Cache age: $CACHE_AGE_DAYS days"

如果 CACHE_AGE_DAYS ≤ 2 → 跳至步骤 5。

否则（缓存已过期或缺失）→ 获取索引：

duckdb -c "
LOAD httpfs;
LOAD fts;
ATTACH 'REMOTE_URL' AS remote (READ_ONLY);
ATTACH '$HOME/.duckdb/docs/CACHE_FILENAME.tmp' AS tmp;
COPY FROM DATABASE remote TO tmp;
" && mv "$HOME/.duckdb/docs/CACHE_FILENAME.tmp" "$HOME/.duckdb/docs/CACHE_FILENAME"

根据步骤 3 替换 REMOTE_URL 和 CACHE_FILENAME。如果获取失败（网络错误），报告错误并停止。

步骤 5 — 搜索文档

duckdb "$HOME/.duckdb/docs/CACHE_FILENAME" -readonly -json -c "
LOAD fts;
SELECT
    chunk_id, page_title, section, breadcrumb, url, version, text,
    fts_main_docs_chunks.match_bm25(chunk_id, 'SEARCH_QUERY') AS score
FROM docs_chunks
WHERE score IS NOT NULL
  AND version = 'VERSION'
ORDER BY score DESC
LIMIT 8;
"

根据步骤 3 替换 CACHE_FILENAME、SEARCH_QUERY 和 VERSION。如果要搜索所有版本，请删除 AND version = 'VERSION' 这一行。

如果用户的问题可能同时适合搜索 DuckDB 文档和博客结果，则运行两个查询（一个使用 version = 'stable'，另一个使用 version = 'blog'），或者完全省略版本筛选条件。

步骤 6 — 处理错误

  • 未安装扩展（未找到 httpfs 或 fts）：运行 duckdb :memory: -c "INSTALL httpfs; INSTALL fts;"，然后重试。
  • ATTACH 失败／网络无法连接：告知用户文档索引不可用，并建议检查网络连接。DuckDB 索引托管在 https://duckdb.org/data/docs-search.duckdb，DuckLake 索引托管在 https://ducklake.select/data/docs-search.duckdb。
  • 没有结果（所有分数均为 NULL 或结果集为空）：尝试扩大查询范围——删去最不具体的词，或尝试将查询改为单个词——然后重试步骤 5。如果仍然没有结果，告知用户未找到匹配的文档，并建议直接访问 https://duckdb.org/docs 或 https://ducklake.select/docs。

步骤 7 — 呈现结果

对于返回的每个结果片段（按分数降序排列），按以下格式呈现：

### {section} — {page_title}
{url}

{text}

---

呈现完所有片段后，根据检索到的文档，为用户的原始问题（$@）撰写简洁的回答。如果片段能直接回答问题，请先给出答案，再展示来源。

评论

支持 Markdown