figshare-skill

Figshare 技能

通过 Figshare v2 REST API 搜索、下载、创建和上传研究成果。

前提条件

• curl 和 jq 已添加到 PATH。

• 对于需要身份验证的端点（/account/... 下的任何端点或上传操作），需要从 https://figshare.com/account/applications 获取个人令牌，并将其导出为：

  export FIGSHARE_TOKEN=xxxxxxxxxxxxxxxx
  

• 公共端点（搜索、公开文章、下载）无需令牌。

在用户账户中创建、修改、发布或删除任何内容之前，务必先征得用户确认——这些操作很难撤销。

更新检查

每个安装每 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 checkout——例如通过 ClawHub 安装的副本、路径只读、没有权限），静默忽略错误并继续处理用户的任务。不要提及故障。

API 基础信息

• 基础 URL： https://api.figshare.com/v2
• 身份验证标头： Authorization: token $FIGSHARE_TOKEN
• Content-Type： POST/PUT 请求体使用 application/json
• 速率限制： 每秒请求数保持在约 1 次以下，以避免触发滥用限流
• 错误： JSON 正文包含 message、code；常见代码为 400/401/403/404/422

常用示例

搜索公开文章

curl -s -X POST https://api.figshare.com/v2/articles/search \
  -H "Content-Type: application/json" \
  -d '{"search_for": ":title: single cell", "page_size": 20}' | jq

字段运算符：:title:、:author:、:tag:、:category:、:doi:、:resource_doi:。

获取公开文章（按 ID 或 DOI）

curl -s https://api.figshare.com/v2/articles/{article_id} | jq
# or resolve from a figshare.com URL: the numeric tail is the article_id

下载公开文章中的所有文件

ART=12345678
curl -s https://api.figshare.com/v2/articles/$ART/files \
  | jq -r '.[] | "\(.download_url)\t\(.name)"' \
  | while IFS=$'\t' read -r url name; do curl -L -o "$name" "$url"; done

列出你自己的文章

curl -s -H "Authorization: token $FIGSHARE_TOKEN" \
  "https://api.figshare.com/v2/account/articles?page=1&page_size=50" | jq

创建文章（草稿）

curl -s -X POST https://api.figshare.com/v2/account/articles \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My dataset",
    "description": "Full description here.",
    "defined_type": "dataset",
    "tags": ["demo"],
    "categories": [2]
  }' | jq

响应为 { "location": ".../account/articles/{id}", "entity_id": 123 }。

更新／发布文章

# update metadata
curl -s -X PUT https://api.figshare.com/v2/account/articles/$ART \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'

# publish (becomes public, assigns DOI, version is frozen)
curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/publish \
  -H "Authorization: token $FIGSHARE_TOKEN"

发布前务必征求确认——该版本发布后无法撤回。

集合和项目

# create collection that groups existing articles
curl -s -X POST https://api.figshare.com/v2/account/collections \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Collection", "articles": [123, 456]}'

# create project
curl -s -X POST https://api.figshare.com/v2/account/projects \
  -H "Authorization: token $FIGSHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Research Project"}'

上传文件（分段流程）

Figshare 上传分为 3 个步骤：初始化 → PUT 每个分段 → 完成。对于任何复杂操作，请使用捆绑的辅助工具：

# upload a file to an existing draft article
./scripts/upload.sh <article_id> <path/to/file>

# batch-download every file from a public article (accepts id or figshare.com URL)
./scripts/download.sh <article_id_or_url> [output_dir]

# reserve + upload + publish a new version of an already-published article
./scripts/new-version.sh <article_id> <path/to/file>

如需调整，可参考原始流程：

1. 初始化——计算 md5 和大小，并 POST 到文章：

   SIZE=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE")
   MD5=$(md5sum "$FILE" | awk '{print $1}')   # or: md5 -q on macOS
   curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/files \
     -H "Authorization: token $FIGSHARE_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"md5\":\"$MD5\",\"name\":\"$(basename $FILE)\",\"size\":$SIZE}"
   

   响应中的 location 指向 /account/articles/$ART/files/$FILE_ID。

2. 获取上传信息——从该文件记录中获取，其中包含 upload_url。GET 该 upload_url 以了解分段布局（parts: [{partNo, startOffset, endOffset}]）。

3. 上传分段——对每个分段，将字节范围 PUT 到 ${upload_url}/${partNo}：

   dd if="$FILE" bs=1 skip=$START count=$((END-START+1)) 2>/dev/null \
     | curl -s -X PUT --data-binary @- "${upload_url}/${partNo}" \
       -H "Authorization: token $FIGSHARE_TOKEN"
   

4. 完成——向文件记录发送 POST 以完成上传：

   curl -s -X POST https://api.figshare.com/v2/account/articles/$ART/files/$FILE_ID \
     -H "Authorization: token $FIGSHARE_TOKEN"
   

为何分为三个步骤：Figshare 会通过单独的上传服务流式传输大文件。如果跳过完成调用，文件会处于待处理状态，也不会显示在文章中。

分页

大多数列表端点支持 page+page_size 或 limit+offset。page_size 通常最大为 1000。对于大量数据采集，请循环获取，直到页面为空：

page=1
while :; do
  out=$(curl -s "https://api.figshare.com/v2/articles?page=$page&page_size=100")
  [ "$(echo "$out" | jq 'length')" = "0" ] && break
  echo "$out" | jq -c '.[]'
  page=$((page+1))
  sleep 1
done

故障排除

• 401 — 缺少令牌或令牌已过期；重新检查 $FIGSHARE_TOKEN。
• 403（/account/...）— 令牌缺少所需的权限范围；使用完整权限重新生成令牌。
• 422（创建文章时）— 缺少必填字段（通常是 title），或 categories/defined_type 无效。
• 上传分块不匹配 — 第 1 步中的 md5 或大小与实际上传的字节数不符；重新计算并重新开始。
• 已发布的文章无法更新 — 发布会冻结一个版本；请改为创建新版本。

参考资料

• API 参考：https://docs.figshare.com/
• 令牌管理：https://figshare.com/account/applications
• 类别 ID：GET https://api.figshare.com/v2/categories
• 许可证 ID：GET https://api.figshare.com/v2/licenses