技能介绍

要解决什么问题

在 Hugging Face Hub 上选数据集时，你往往需要先确认仓库是否能在 Dataset Viewer 里打开、看清 config/split 结构，再抽样看字段与行内容，必要时做全文搜索或谓词筛选，而不是一上来就整库下载。私有或 gated 数据集还要在只读前提下带上认证。本技能把上述探索路径收敛成一组 GET 端点调用约定，并补充「上传 Parquet 让 Viewer 可用」以及「把代理会话痕迹托管到 Datasets」两条相关流程。

技能如何工作

只读 Viewer API 的典型顺序：

可选调用 /is-valid?dataset= 检查数据集是否可用。
用 /splits?dataset= 解析 config + split。
/first-rows 快速预览；需要更多行时用 /rows，通过 offset（从 0 起）和 length（行类端点通常 ≤100）分页。
文本匹配走 /search；结构化条件走 /filter（where 谓词，可选 orderby），二者保持只读、无副作用。
元数据与导出线索：/parquet 列分片链接，/size、/statistics 看规模与列统计；若 Hub 提供，还可查 /croissant。

默认基址为 https://datasets-server.huggingface.co；查询参数需 URL 编码。分页不完整时，用响应里的 num_rows_total、num_rows_per_page、partial 决定是否继续拉取。若你要在 CLI 里做 Parquet URL 发现或 SQL，SKILL.md 指向 hf-cli 技能中的 hf datasets parquet / hf datasets sql，与本技能的 HTTP 探索互补。

创建与上传（按依赖选择）：零本地依赖可在 Hub UI 新建数据集仓库并上传 Parquet；低依赖可用 npx @huggingface/hub / hfjs 上传文件夹（可私有创建）。上传后仍建议用 /parquet 确认分片出现在 Viewer 中，以便后续用 @~parquet 类路径查询。

代理痕迹：Hub 可识别 Claude Code、Codex、Pi Agent 等导出的 JSONL 痕迹，自动标记为 Traces 并启用痕迹查看器。默认应使用私有仓库；保留原始 .jsonl，按项目/cwd 嵌套目录上传，避免把所有会话堆在数据集根目录。

适用边界

本技能侧重 Dataset Viewer / datasets-server 的只读 HTTP 流程，不是 datasets 库本地 map/filter 的全量 ETL。
受限数据集必须在请求头提供 Authorization: Bearer <token>。
/search 的全文行为由服务端实现细节决定；复杂 SQL 或大规模离线处理应走 hf-cli 或本地下载，而非无限分页 /rows。