用途
Hugging Face Dataset Viewer 技能用于对 Hugging Face 数据集执行只读的 Dataset Viewer API 调用，以便进行数据集探索与内容提取。当任务明确涉及 Hugging Face 数据集浏览、检索或元数据查询时使用。
主要能力
该技能覆盖以下 Dataset Viewer 接口：
- 校验数据集：
/is-valid?dataset=<namespace/repo> - 列出子集与划分：
/splits?dataset=<namespace/repo> - 预览首行：
/first-rows?dataset=<namespace/repo>&config=<config>&split=<split> - 分页读取行：
/rows?dataset=<namespace/repo>&config=<config>&split=<split>&offset=<int>&length=<int> - 文本搜索：
/search?dataset=<namespace/repo>&config=<config>&split=<split>&query=<text>&offset=<int>&length=<int> - 条件过滤：
/filter?dataset=<namespace/repo>&config=<config>&split=<split>&where=<predicate>&orderby=<sort>&offset=<int>&length=<int> - 列出 parquet 分片：
/parquet?dataset=<namespace/repo> - 获取大小总计：
/size?dataset=<namespace/repo> - 获取列统计：
/statistics?dataset=<namespace/repo>&config=<config>&split=<split> - 获取 Croissant 元数据（如可用）：
/croissant?dataset=<namespace/repo>
使用方式
核心工作流：可选先用 /is-valid 校验数据集可用性；用 /splits 解析 config 与 split；用 /first-rows 预览；用 /rows 配合 offset 与 length（最大 100）分页；用 /search 做文本匹配，用 /filter 做行谓词过滤；通过 /parquet 获取 parquet 链接，通过 /size 和 /statistics 获取总计与元数据。
默认设置：基础 URL 为 https://datasets-server.huggingface.co；默认 API 方法为 GET；查询参数应进行 URL 编码；offset 从 0 开始；行类接口的 length 上限通常为 100；受限或私有数据集需要 Authorization: Bearer <HF_TOKEN>。
分页示例：
curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=0&length=100"
curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=100&length=100"
当分页不完整时，可使用响应字段如 num_rows_total、num_rows_per_page 和 partial 来驱动续读逻辑。
搜索与过滤说明：/search 匹配字符串列（全文风格行为由 API 内部实现）；/filter 需要在 where 中提供谓词语法，并可在 orderby 中提供可选排序。过滤与搜索应保持只读且无副作用。若需基于 CLI 发现 parquet URL 或执行 SQL，可使用 hf-cli 技能中的 hf datasets parquet 与 hf datasets sql。
创建与上传数据集
根据依赖约束选择以下流程之一。
零本地依赖（Hub 网页界面）：
- 在浏览器中创建数据集仓库：https://huggingface.co/new-dataset
- 在仓库的 "Files and versions" 页面上传 parquet 文件。
- 验证分片出现在 Dataset Viewer 中：
curl -s "https://datasets-server.huggingface.co/parquet?dataset=<namespace>/<repo>"
低依赖 CLI 流程（npx @huggingface/hub / hfjs）：
设置认证令牌：
export HF_TOKEN=<your_hf_token>
上传 parquet 文件夹到数据集仓库（仓库缺失时自动创建）：
npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data
创建时上传为私有仓库：
npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data --private
上传后，调用 /parquet 发现 <config>/<split>/<shard> 值，以便使用 @~parquet 进行查询。
Agent Traces
Hub 支持来自 Claude Code、Codex 和 Pi Agent 的原始 agent 会话轨迹。将它们作为原始 JSONL 文件上传到 Hugging Face Datasets，Hub 可自动检测轨迹格式、将数据集标记为 Traces，并启用 trace viewer 以浏览会话、轮次、工具调用和模型响应。常见本地会话目录：
- Claude Code：
~/.claude/projects - Codex：
~/.codex/sessions - Pi：
~/.pi/agent/sessions
默认应使用私有数据集仓库，因为轨迹可能包含提示词、文件路径、工具输出、密钥或 PII。保留原始 .jsonl 文件，并按项目/cwd 嵌套，而不是将所有会话上传到数据集根目录。
hf repos create <namespace>/<repo> --type dataset --private --exist-ok
hf upload <namespace>/<repo> ~/.codex/sessions codex/<project-or-cwd> --type dataset
适用场景
适用于需要浏览、检索、过滤或提取 Hugging Face 数据集内容的场景，以及需要创建数据集仓库、上传 parquet 文件或上传 agent 会话轨迹以启用 trace viewer 的场景。
限制
仅在任务明确匹配其上游产品或 API 范围时使用此技能。在做出更改前，应依据当前官方文档核实命令、API 行为、定价、配额、凭据和部署影响。不要将生成的示例视为环境特定测试、安全审查或对破坏性/高成本操作的用户批准的替代品。