zenodo-skill

Zenodo 技能

通过 Zenodo REST API 存储、发布、创建版本并搜索研究成果。Zenodo 会为每条已发布记录分配一个可引用的 DOI。

适用场景

• 用户想要将数据集、代码版本、论文、海报或其他成果上传到 Zenodo
• 用户想要为研究成果获取 DOI
• 用户想要更新现有存储记录或发布新版本
• 用户想要搜索 Zenodo 中的记录

更新检查

每次安装每 24 小时最多检查一次；未经用户明确同意，绝不修改技能目录。

1. 如果 <this-skill-dir>/.last_update 存在且距今不到 24 小时，则完全跳过此步骤。

2. 否则，从上游获取最新标签：

   git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
     | awk '{print $2}' | sed 's|refs/tags/||' \
     | sort -V | tail -1
   

3. 将上游标签与此技能 frontmatter 中的 metadata.version 比较。如果上游标签更新（按 semver 判断），告知用户一行，并询问：

   “此技能有新版本可用：vX.Y.Z → vA.B.C。要我执行 git pull 吗？”

   如果用户同意，运行 git -C <this-skill-dir> pull --ff-only。无论用户是否同意，都刷新 .last_update，以免 24 小时内重复提示。

4. 如果上游版本相同或更旧，则静默刷新 .last_update 并继续。

5. 遇到任何失败（离线、不是 git 检出副本，例如通过 ClawHub 安装的副本、路径只读、无权限）时，静默忽略错误并继续处理用户的任务。不要提及失败。

设置

有两种环境——在一个会话中选择一种并始终使用：

环境	基础 URL	令牌页面
生产环境	https://zenodo.org/api	https://zenodo.org/account/settings/applications/tokens/new/
沙盒（测试）	https://sandbox.zenodo.org/api	https://sandbox.zenodo.org/account/settings/applications/tokens/new/

沙盒账户和令牌与生产环境相互独立。始终先在沙盒中测试新的工作流——已发布的生产环境记录无法删除。

令牌所需的作用域：deposit:write 和 deposit:actions。

运行命令前导出令牌：

export ZENODO_TOKEN=...        # never inline the token in commands you show the user
export ZENODO_BASE=https://sandbox.zenodo.org/api   # or https://zenodo.org/api

如果未设置 ZENODO_TOKEN，请先向用户询问令牌以及要使用的环境。

核心工作流：存储新成果

存储生命周期为创建 → 上传文件 → 设置元数据 → 发布。每一步都是单独的 API 调用；请按顺序执行。

1. 创建空存储记录

curl -sS -X POST "$ZENODO_BASE/deposit/depositions" \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

响应 JSON 中有两项需要记住：

• id — 存储记录 ID，用于元数据、发布和版本操作
• links.bucket — 文件上传用的 bucket URL（新版文件 API）

例如，使用 jq 获取这些值：

RESP=$(curl -sS -X POST "$ZENODO_BASE/deposit/depositions" \
  -H "Authorization: Bearer $ZENODO_TOKEN" -H "Content-Type: application/json" -d '{}')
DEPOSIT_ID=$(echo "$RESP" | jq -r .id)
BUCKET=$(echo "$RESP" | jq -r .links.bucket)

2. 上传文件（优先使用 bucket API）

bucket API 支持每条记录最多 50 GB 总容量 / 100 个文件。使用 --upload-file（HTTP PUT）——不要使用 multipart 表单上传。URL 中的文件名就是记录中显示的文件名。

curl -sS --upload-file ./data.csv \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  "$BUCKET/data.csv"

每个文件重复一次。文件较多时，可在 shell 中使用循环。旧版 /files multipart 端点每个文件限制为 100 MB——请避免使用。

3. 设置元数据

通过对存储记录执行 PUT 来提交元数据。必填字段：upload_type、title、creators、description。完整模式、允许的 upload_type 值、许可证代码及条件字段（例如 publication_type、embargo_date）请参阅 references/metadata.md。

最简示例：

curl -sS -X PUT "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID" \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "My dataset",
      "upload_type": "dataset",
      "description": "<p>A short description (HTML allowed).</p>",
      "creators": [{"name": "Doe, Jane", "affiliation": "Example Univ.", "orcid": "0000-0002-1825-0097"}]
    }
  }'

检查响应——Zenodo 会在此处进行验证；如果有字段缺失或格式错误，会返回 400 错误并指出具体字段。请修正后重试，再进行发布。

4. 发布

在生产环境中，发布操作不可撤销（之后可以编辑元数据，但无法移除文件或删除记录）。除非用户使用的是沙盒，否则请在此步骤前征求用户确认。

curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/publish" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

响应中包含 doi 和 links.record_html——请将两者都展示给用户。

现有记录的新版本

当用户之前已发布记录，并希望以相同的 concept-DOI 发布更新后的数据/代码时，请使用此流程。

# 1. Create new version draft (returns links.latest_draft)
curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/newversion" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

然后根据新草稿的存储桶（从 links.latest_draft 获取 → GET 它 → 使用其 links.bucket）上传变更的文件、更新元数据，并按上述步骤 2–4 发布。默认情况下，新版本会继承上一版本的文件——使用 DELETE $BUCKET/<filename> 删除想要替换的文件。

丢弃草稿

curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/discard" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

搜索已发布记录

公开搜索无需令牌。

curl -sS "$ZENODO_BASE/records?q=climate+model&size=10&sort=mostrecent"

查询语法基于 Elasticsearch——creators.name:"Doe, Jane"、communities:zenodo、resource_type.type:dataset 等字段查询都可使用。查询模式请参阅 references/search.md。

约定与注意事项

• 始终检查 HTTP 状态。 201 = 已创建，202 = 已接受发布请求，400 = 元数据错误（请读取响应正文），401 = 令牌无效，403 = 权限范围错误，429 = 请求过多。
• 速率限制： 已认证用户每分钟 100 次请求，每小时 5000 次请求。注意 X-RateLimit-Remaining。
• 切勿在命令中直接写入令牌——请使用 $ZENODO_TOKEN。不要将令牌写入文件。
• 先使用 Sandbox。 对于任何首次工作流，请建议使用 Sandbox；仅在用户明确确认后才切换到生产环境。
• 发布前先核实。 在生产环境调用 actions/publish 之前，先 GET 存档记录，并与用户一起检查文件和元数据。
• 上传大文件： 对于大于几百 MB 的文件，可考虑使用带 --progress-bar 的 curl 上传，并提醒用户注意时间/带宽。

参考资料

• references/metadata.md — 完整的元数据架构、upload_type 值、许可证代码及条件字段
• references/search.md — 搜索查询语法和实用筛选条件
• references/examples.md — 常见场景的端到端 Shell 脚本（数据集上传、软件发布、新版本）