figshare-skill：AI编程助手技能包，自动化管理科研数据

1. 项目概述与核心价值

如果你经常和科研数据打交道，尤其是需要在 Figshare 这个全球知名的研究数据共享平台上搜索、下载或管理自己的数据集，那么你很可能已经受够了在浏览器、命令行和 API 文档之间反复横跳的繁琐。手动拼接curl命令、处理分块上传、解析 JSON 响应，这些重复性劳动不仅耗时，还容易出错。今天要介绍的figshare-skill，正是为了解决这些痛点而生。它是一个专为 AI 编程助手（如 Claude Code、Codex、OpenClaw 等）设计的技能包，将 Figshare API v2 的完整功能封装成了一组开箱即用的命令行工具和智能指令。简单来说，它让你能用最自然的方式与 Figshare 交互：说人话，办大事。

这个技能的核心价值在于“自动化”和“降门槛”。它不是一个需要你从头学习的全新工具，而是无缝嵌入到你已有的 AI 编程工作流中。无论你是想批量下载某个热门数据集的所有文件，还是需要将本地几个 GB 的实验结果打包上传并发布新版本，figshare-skill都能将复杂的多步 API 调用，简化为一句清晰的指令。它背后是curl和jq的稳定组合，但前端呈现的却是高度抽象的友好接口。对于数据科学家、研究工程师和任何需要高效管理开放科学数据的从业者来说，这相当于给你的数字工具箱里添了一把瑞士军刀，专门用来对付 Figshare 上的各种任务。

2. 核心功能深度解析与设计思路

2.1 功能全景：从搜索到版本管理的完整覆盖

figshare-skill的设计目标非常明确：覆盖科研数据生命周期中与 Figshare 交互的所有关键环节。我们可以将其功能拆解为四个核心模块：

1. 智能搜索与发现：这不仅仅是简单的关键词匹配。技能内置了对 Figshare 高级搜索字段操作符（如:title:、:author:、:tag:、:category:、:doi:）的理解。这意味着你可以直接命令 AI 助手“搜索标题包含‘单细胞转录组’且作者是‘Jane Doe’的数据集”，技能会自动将其转换为正确的 API 查询参数。这种语义化搜索能力，让数据发现过程从“猜关键词”变成了“提需求”。

2. 高效的批量数据获取：看到一篇有用的文章，里面可能有几十个数据文件。手动一个个点下载？太原始了。figshare-skill的download.sh脚本允许你通过文章 ID、DOI 或完整的 figshare.com URL，一键下载该文章下所有公开的文件，并保持原始的文件名和目录结构。这对于复现研究或进行批量数据分析至关重要。

3. 全流程的内容管理：这是面向内容创建者的核心。你可以通过技能创建草稿文章、更新元数据（标题、描述、标签等）、上传文件，并最终发布。更重要的是，它完整支持 Figshare 的版本控制工作流。已发布的文章是“冻结”的，无法直接修改。figshare-skill提供了new-version.sh脚本来处理“发布新版本”这个标准流程：预留新版本号、上传更新后的文件、然后发布。这确保了学术记录的完整性。

4. 大文件上传的“黑盒”处理：上传超过一定大小（通常是几十MB）的文件到 Figshare，必须使用其“多部分上传”API。这个过程涉及初始化上传、将文件分割成多个部分分别上传、计算并验证 MD5 校验和，最后完成上传。figshare-skill的upload.sh脚本将这个复杂的三步流程完全自动化了。你只需要提供文章 ID 和文件路径，剩下的分块、计算、并发上传（在脚本逻辑内顺序执行）都由它搞定。这可能是整个技能中最能体现其“省心”价值的特性。

2.2 设计哲学：为什么是“Skill”而非独立 CLI 工具？

你可能会问，为什么不直接写一个功能强大的独立命令行工具（CLI）？figshare-skill选择以“技能”的形式存在，背后有深刻的考量。

首先，它降低了使用门槛。用户不需要记忆复杂的命令语法和参数选项。在与 AI 助手对话的上下文中，你只需要用自然语言描述你的意图，比如“帮我把./analysis_results.zip上传到我的 Figshare 草稿文章 123456 里”。AI 助手理解意图后，会调用技能中封装好的逻辑来执行。这比记忆figshare-cli upload --article 123456 --file ./analysis_results.zip要直观得多，尤其对于非频繁用户或需要执行复杂组合操作时。

其次，它实现了上下文智能。技能被设计为可以在对话中自动触发。当你在聊天中提到一个figshare.com的链接或一个10.6084/m9.figshare.*格式的 DOI 时，AI 助手能自动识别并询问你是否需要相关操作（如下载）。这种基于上下文的主动服务，是传统 CLI 工具难以实现的。

最后，它具备平台可移植性。通过遵循Agent Skills开放格式（核心是SKILL.md文件），这个技能可以同时被 Codex、Claude Code、OpenClaw、SkillsMP 等多个主流 AI 编程助手平台加载和使用。开发者维护一套代码，就能服务多个生态的用户，极大地提高了工具的覆盖面和生命力。这种设计选择反映了当前开发者工具向“AI-Native”演进的趋势。

3. 环境准备与技能安装实战

3.1 基础依赖与认证配置

无论你使用哪个平台，figshare-skill的运行都依赖于两个最基础、也最普遍的命令行工具：curl和jq。

• curl：用于发起所有的 HTTP 请求到 Figshare API。几乎所有的 Linux/macOS 系统都预装了它，Windows 用户可以通过 WSL、Git Bash 或 Cygwin 获得。
• jq：一个轻量级且强大的命令行 JSON 处理器。API 的响应都是 JSON 格式，jq用于从中提取所需信息（如文章 ID、文件列表、上传 URL 等）。你可以通过系统包管理器安装它（例如，在 Ubuntu/Debian 上使用sudo apt-get install jq，在 macOS 上使用brew install jq）。

接下来是最关键的一步：获取 Figshare 个人令牌。这个令牌是你身份的凭证，用于执行所有需要权限的操作，如管理你的文章、上传文件等。

注意：公开的搜索、查看文章信息和下载公开文件不需要令牌。只有涉及你的个人账户（/account/...路径）或上传操作时，才需要配置令牌。

获取令牌的步骤：

1. 登录你的 Figshare 账户。
2. 访问https://figshare.com/account/applications。
3. 在 “Personal token” 部分，点击 “Generate new token”。
4. 为令牌起一个描述性的名字（例如 “My-Agent-Skill”），然后生成。
5. 务必立即复制生成的令牌字符串并妥善保存，因为它只显示一次。

获取令牌后，你需要将其设置为环境变量。最佳实践是在你的 shell 配置文件（如~/.bashrc、~/.zshrc或~/.profile）中永久设置：

export FIGSHARE_TOKEN="你的令牌字符串"

然后执行source ~/.bashrc（或对应配置文件）使其生效。你也可以在每次启动新的终端会话时临时设置。

3.2 多平台安装指南详解

figshare-skill支持多种 AI 助手平台，安装路径略有不同。核心都是通过git clone将技能仓库克隆到特定的目录下，该目录会被相应的 AI 助手自动扫描并加载。

3.2.1 Claude Code 安装

Claude Code 支持全局安装和项目级安装。

• 全局安装：技能对所有项目可用。

  git clone https://github.com/Agents365-ai/figshare-skill.git ~/.claude/skills/figshare-skill

• 项目级安装：技能仅对当前项目可用，便于管理项目特定的依赖。

  # 在你的项目根目录下执行 git clone https://github.com/Agents365-ai/figshare-skill.git .claude/skills/figshare-skill

安装后，在 Claude Code 的对话中，当你提及figshare或相关操作时，它就能自动调用该技能。

3.2.2 Codex 安装

Codex 通常使用全局技能目录。

git clone https://github.com/Agents365-ai/figshare-skill.git ~/.codex/skills/figshare-skill

3.2.3 OpenClaw 安装

与 Claude Code 类似，OpenClaw 也支持两种方式。

• 全局安装：

  git clone https://github.com/Agents365-ai/figshare-skill.git ~/.openclaw/skills/figshare-skill

• 项目级安装：

  # 在你的项目根目录下执行 git clone https://github.com/Agents365-ai/figshare-skill.git skills/figshare-skill

3.2.4 SkillsMP 安装

SkillsMP 是一个技能管理平台，提供了更便捷的安装方式。

# 使用 SkillsMP 的 CLI 工具直接安装 skills install figshare-skill

这种方式通常会自动处理依赖和路径，是最用户友好的方式。

实操心得：对于个人日常使用，推荐全局安装，一劳永逸。如果你在为一个团队项目配置标准化环境，或者需要确保技能版本与项目代码同步，则使用项目级安装。安装后，如果 AI 助手没有立即识别，尝试重启一下你的 AI 助手客户端或 IDE 插件。

4. 核心使用场景与脚本实操详解

安装配置完成后，我们就可以进入最激动人心的实战环节。figshare-skill的强大，在于它能将复杂的 API 操作转化为简单的对话或脚本执行。下面我们通过几个典型场景，来拆解其使用方法和背后的原理。

4.1 场景一：精准搜索与数据发现

假设你正在调研“气候变化对鸟类迁徙”相关的公开数据集。

传统方式：打开浏览器 -> 访问 Figshare -> 在搜索框输入关键词 -> 在结果页中手动筛选 -> 可能还需要用高级搜索语法，但界面支持有限。

使用figshare-skill：直接在 Claude Code 或你的 AI 助手中输入：

搜索 Figshare 中标题包含“bird migration”且标签包含“climate change”的文章，显示前5个结果。

或者更精确地使用字段操作符：

使用 $figshare-skill 搜索 :title:bird migration :tag:climate change，并显示它们的标题、作者和 DOI。

背后发生了什么：AI 助手识别出你的意图和figshare-skill的触发词，它会调用技能内封装的搜索逻辑。技能会将你的自然语言或字段操作符，转换为对 Figshare APIGET /v2/articles端点的调用，并添加相应的查询参数（如?search=title:bird migration&tags=climate change）。返回的 JSON 结果会通过jq被格式化成清晰易读的列表展示给你。你不仅得到了结果，而且整个过程在对话中完成，无需离开你的编码或思考环境。

4.2 场景二：一键批量下载数据集

你找到了一个理想的数据集，其 Figshare 文章 URL 是https://figshare.com/articles/dataset/Global_Bird_Migration_Data/31957606。里面包含了十几个不同格式的数据文件（CSV, JSON, 图片）。

传统方式：点击文章页面 -> 找到“文件”列表 -> 逐个点击文件后的下载按钮 -> 选择保存位置 -> 重复十几次。繁琐且容易漏。

使用figshare-skill：在命令行中直接运行技能提供的脚本：

# 假设脚本已在 PATH 中，或你进入到了技能目录的 scripts/ 下 ./download.sh https://figshare.com/articles/dataset/Global_Bird_Migration_Data/31957606 ./bird_data

或者告诉你的 AI 助手：

帮我把 https://figshare.com/articles/dataset/Global_Bird_Migration_Data/31957606 的所有文件下载到当前目录的 `bird_data` 文件夹里。

脚本原理剖析：download.sh脚本是这个场景的功臣。它执行了以下步骤：

1. 解析输入：脚本接受文章 ID、DOI 或 URL，从中提取出唯一的文章 ID。
2. 获取文件列表：使用curl调用GET /v2/articles/{article_id}/filesAPI，获取该文章下所有文件的元数据（包括文件名、下载链接、大小等）。
3. 循环下载：遍历文件列表，对每个文件再次使用curl跟随其下载链接，并将内容写入到本地指定的目录中，保持原始文件名。
4. 进度反馈：在下载每个文件时，通常会显示进度信息，让你知道正在发生什么。

注意事项：下载大量或超大文件时，请确保网络稳定和磁盘空间充足。虽然脚本本身不处理断点续传，但简单的循环下载对于大多数科研数据集已经足够高效。

4.3 场景三：上传成果与发布新版本

这是研究者最核心的用例。你完成了一项分析，生成了一个final_analysis.zip文件（大小 2.5GB），需要更新你已发表在 Figshare 上的文章（ID: 12345678）。

传统方式（极其痛苦）：

1. 登录 Figshare -> 进入“我的数据” -> 找到文章 -> 点击“创建新版本”。
2. 等待系统创建新版本草稿。
3. 在草稿页面上传文件。由于文件超过 100MB，浏览器上传可能不稳定，甚至中途失败。
4. 如果使用 API，你需要自己写脚本处理多部分上传：计算文件 MD5、分块、初始化、上传每个分块、完成上传。代码复杂，调试困难。

使用figshare-skill：

# 使用 new-version.sh 脚本，它封装了创建新版本草稿和上传的完整流程 ./new-version.sh 12345678 ./final_analysis.zip

或者直接告诉 AI 助手：

为我的 Figshare 文章 12345678 发布一个新版本，上传文件 ./final_analysis.zip。

new-version.sh与upload.sh的魔法：

• new-version.sh脚本实际上是一个更高层次的封装。它内部依次执行了：

  1. 创建新版本草稿：调用POST /v2/account/articles/{article_id}/versions创建一个新的、可编辑的版本草稿，并获取新的文章 ID（版本号递增）。
  2. 调用上传脚本：将新的文章 ID 和文件路径传递给upload.sh脚本。
  3. 发布新版本：在上传成功后，调用POST /v2/account/articles/{new_article_id}/publish来发布这个新版本。

• upload.sh脚本是处理大文件上传的核心。它自动化了 Figshare 多部分上传流程：

  1. 初始化：向POST /v2/account/articles/{article_id}/files发送文件信息（名称、大小、MD5），API 返回一个包含上传 URL 和所需分块信息的上传令牌。
  2. 分块与上传：脚本根据 Figshare API 的要求（通常每块 5-15MB），将大文件在内存中逻辑分块。然后，它循环遍历每个分块，使用PUT请求将分块数据上传到指定的 URL。这里脚本使用dd bs=1来精确读取每个字节，虽然对于超大文件可能不是最快，但保证了准确性。
  3. 完成上传：所有分块上传成功后，调用POST /v2/account/articles/{article_id}/files/{file_id}来通知 Figshare 文件已上传完毕，服务器会验证 MD5 并整合文件。

实操心得：在上传非常大的文件（例如 >10GB）时，网络中断的风险增加。虽然脚本本身没有内置的断点续传机制，但你可以通过监控脚本输出（它会显示正在上传第几块）来了解进度。如果中断，你需要手动清理 Figshare 上未完成的文件部分（在文章草稿的文件管理中删除），然后重新运行脚本。对于超大规模数据上传，考虑将数据拆分成多个小于 5GB 的文件分别上传，会更稳妥。

5. 技能内部机制与高级技巧

5.1SKILL.md：技能的灵魂文件

SKILL.md文件是Agent Skills格式的核心，也是所有 AI 平台加载这个技能的入口。你可以把它理解为一个高度结构化的“说明书”或“能力定义文件”。AI 助手通过读取这个文件来理解：

• 这个技能叫什么、是做什么的（元数据）。
• 在什么情况下应该触发这个技能（触发词：如 “figshare”, “10.6084/m9.figshare.*”）。
• 这个技能具体能执行哪些操作（功能描述）。
• 执行这些操作需要调用哪些命令、脚本，以及如何解析用户的输入（实现逻辑）。

figshare-skill的SKILL.md文件写得非常清晰，它定义了从搜索、下载到上传、版本管理的完整交互逻辑。当用户说“搜索 Figshare 关于 XXX 的数据”时，AI 助手会根据SKILL.md中的指引，知道要去组合curl和jq命令，调用特定的搜索 API，并以友好的格式返回结果。这种设计将复杂的 API 知识封装在了技能内部，对用户完全透明。

5.2 辅助脚本：可独立使用的利器

虽然技能主要通过与 AI 对话使用，但其附带的scripts/目录下的 shell 脚本（upload.sh,download.sh,new-version.sh）本身就是功能完整、可独立运行的工具。这意味着即使你不使用 Claude Code 或 Codex，你也可以在终端里直接运行这些脚本，享受自动化带来的便利。

例如，你可以在一个纯粹的 Bash 脚本或 Makefile 中集成download.sh，作为数据流水线的一环，自动获取最新的参考数据集。这种设计增加了技能的灵活性和复用价值。

5.3 元数据文件与平台适配

为了在不同 AI 助手平台上获得最佳体验（例如在 Codex 的 UI 中显示技能图标和描述，或提供快捷输入提示），figshare-skill包含了平台特定的元数据文件，如agents/openai.yaml（用于 Codex）。这些文件提供了 UI 层面的信息，不影响核心功能，但提升了用户发现的便利性和使用的流畅度。这体现了技能开发者对多平台生态的细致考量。

6. 常见问题排查与性能优化

6.1 认证与权限问题

• 问题：执行上传或管理操作时，返回401 Unauthorized或403 Forbidden错误。
• 排查：
  1. 检查令牌：首先运行echo $FIGSHARE_TOKEN确认环境变量已设置且值正确。令牌字符串应完整无误。
  2. 令牌权限：确保你的 Figshare 个人令牌具有足够的权限（通常创建时默认有所有权限）。如果你在组织账户下，可能需要管理员授权。
  3. 文章所有权：确认你尝试修改或上传的文章 ID 确实属于你的账户。你无法管理他人的文章。

6.2 上传失败或超时

• 问题：上传大文件时脚本卡住、报错或网络超时。
• 排查与优化：
  1. 网络环境：上传大文件需要稳定、高速的网络。如果可能，在服务器或网络条件好的机器上执行。
  2. 脚本速度：如前所述，upload.sh使用dd bs=1分块读取，对于数 GB 的文件可能较慢。这是为了精确性牺牲了一些速度。如果这是瓶颈，可以考虑修改脚本，使用更大的块大小（如bs=1M）并结合skip和count参数来定位，但这会增加复杂性。
  3. Figshare 限制：关注 Figshare 的 API 速率限制（虽然没有公开硬性规定，但建议每秒请求数 ≤1）。脚本没有内置限流，但在连续上传多个文件时，可以手动在命令间添加sleep 1来避免触发限制。
  4. 文件完整性：上传完成后，务必在 Figshare 网站上检查文件大小和 MD5 是否与本地一致。MD5 校验是 API 的一部分，失败会上传失败。

6.3 版本发布流程错误

• 问题：使用new-version.sh时，提示文章状态不允许或发布失败。
• 排查：
  1. 文章状态：只有已经发布的文章才能创建新版本。草稿文章不能执行“发布新版本”操作，你应该直接上传到草稿。
  2. 版本预留：new-version.sh的第一步是创建版本草稿。如果失败，可能是 API 临时问题或文章已被锁定（例如正在处理中）。
  3. 发布权限：确认你的账户有发布文章的权限（个人账户通常有，机构账户可能有审核流程）。

6.4 搜索或下载公开内容失败

• 问题：搜索无结果或下载公开文件时连接被拒绝。
• 排查：
  1. 网络连通性：首先确认能访问api.figshare.com。可以ping api.figshare.com或curl -I https://api.figshare.com/v2/articles测试。
  2. 搜索语法：检查你的搜索关键词或字段操作符是否正确。可以先用简单的关键词测试。
  3. 文章可见性：确认你要下载的文章和文件是“公开”状态，而非“私有”或“仅限邀请”。

6.5 技能未被 AI 助手识别

• 问题：在 AI 助手中提到 Figshare 相关词汇，但没有触发技能建议。
• 排查：
  1. 安装路径：确认技能被克隆到了正确的平台特定目录（见第 3.2 节表格）。路径错误是最常见的原因。
  2. 技能加载：有些 AI 助手需要重启或重新加载技能列表。尝试重启你的 IDE 或 AI 助手客户端。
  3. 技能格式：极少数情况下，SKILL.md文件格式错误可能导致解析失败。可以尝试从官方仓库重新克隆。

通过系统地理解这些常见问题及其解决方案，你可以更自信地运用figshare-skill来处理各种实际任务，即使遇到障碍也能快速定位和排除。这个工具的价值，正是在于将 Figshare API 的复杂性封装起来，让你能专注于更重要的科研和数据工作本身。