1. 项目概述一个为AI编程助手赋能的Figshare命令行技能如果你经常和科研数据打交道或者需要管理、分享自己的学术成果那么Figshare这个平台你一定不陌生。它是一个广受欢迎的研究数据存储库让学者们可以轻松地发布数据集、代码、图表等研究成果并获得一个永久可引用的DOI。然而当你需要批量下载某个项目里的几十个文件或者想通过命令行自动化上传一个几GB的大数据集时原生的Figshare网页界面和基础的API调用就显得有些力不从心了。这正是figshare-skill诞生的原因。它不是一个独立的全新工具而是一个专门为AI编程助手如Codex、Claude Code、OpenClaw等设计的“技能包”。简单来说它把对Figshare API的复杂操作——尤其是那些繁琐、容易出错的步骤——封装成了一系列清晰、可复用的指令和脚本。当你向你的AI助手描述一个与Figshare相关的任务时比如“帮我把这个文件夹里的所有数据上传到我的Figshare草稿文章里”安装了此技能的AI助手就能理解你的意图并调用背后封装好的最佳实践来完成任务而不是从头开始、磕磕绊绊地编写可能充满错误的curl命令。这个技能的核心价值在于“化繁为简”和“最佳实践内置”。它特别适合以下几类人经常使用Figshare管理数据的研究人员希望自动化数据上传/下载流程的开发者以及任何想要更高效、更可靠地与Figshare API交互但又不想深陷其复杂细节的用户。接下来我将带你深入拆解这个技能的设计思路、每一个核心功能的使用细节并分享在实际集成和使用过程中积累的宝贵经验。2. 核心功能与设计哲学解析2.1 功能全景从搜索到版本管理的完整工作流figshare-skill覆盖了一个科研数据生命周期中与Figshare交互的大部分关键环节。我们可以将其功能划分为三个层次数据发现、数据操作和项目管理。数据发现层的核心是增强型搜索。原生的Figshare API搜索功能比较基础而这个技能引入了类似高级搜索引擎的字段操作符。例如你想找标题中包含“genome”且作者是“Jane Doe”的文章可以直接使用:title:genome :author:Jane Doe这样的查询语法。这背后是对API查询参数的智能组装将用户自然语言描述的精确定位需求转化为API能理解的高效查询极大地提升了文献和数据集的检索精度。数据操作层是技能的重头戏主要解决“上传”和“下载”两大痛点。对于下载它提供了batch-download功能你只需提供一个文章ID、DOI或完整的figshare.com网址它就能自动获取文章的所有文件列表并并行或顺序下载到指定目录。对于上传它重点攻克了大文件多部分上传的难题。Figshare API对于大文件要求使用复杂的“初始化-分块上传-完成”三步流程还需要计算MD5和分块大小。这个技能将整个流程封装在upload.sh脚本中对用户完全透明你只需要关心“传什么”和“传到哪”。项目管理层则涉及更高级的API操作包括文章的创建、更新、发布以及新版本发布和集合/项目管理。这里有一个关键设计严格区分“草稿”和“已发布”状态。已发布的文章版本是冻结的任何修改都必须通过创建新版本new-version.sh来完成。技能内置了这个工作流防止用户误操作直接更新已发布内容导致版本混乱。2.2 设计哲学为什么选择“技能”而非独立CLI工具你可能会问为什么不直接写一个功能强大的独立命令行工具CLI比如用Python的click库而要做一个给AI助手用的“技能”这背后有深刻的考量。首先定位不同。一个独立的CLI工具要求用户记忆命令、参数和语法。而“技能”的目标是自然语言交互。用户只需用平实的语言描述需求“搜索关于气候变化的数据集”AI助手结合技能知识就能生成正确的操作。这降低了使用门槛尤其适合不熟悉命令行或API细节的研究人员。其次生态集成。像Codex、Claude Code这样的AI编程助手正在形成一个以“技能”为核心的插件生态。在这个生态里技能可以相互组合。比如一个数据处理技能的输出可以直接作为figshare-skill的输入进行上传。这种“可组合性”比独立的、封闭的CLI工具更具想象力和扩展性。第三降低重复认知负荷。对于AI助手来说每次被要求与Figshare交互时如果都没有技能它需要从零开始回忆API文档、认证方式、端点URL、错误处理等。这不仅速度慢而且容易出错。figshare-skill将这些知识固化、标准化作为AI的“长期记忆”和“最佳实践手册”确保了每次交互的准确性和一致性。从项目对比表格中可以看出有技能之后AI助手从“可能知道基础URL”变成了“肯定知道”从“需要重新发明多部分上传流程”变成了“直接调用封装好的可靠脚本”。最后轻量化和专注。这个技能本身不包含复杂的运行时或依赖它本质是一组精心编写的文档SKILL.md和几个纯粹的Bash脚本依赖curl和jq。它专注于解决Figshare API交互中的特定难题而不试图成为一个大而全的瑞士军刀。这种专注使得它易于维护、理解并且能深度优化其核心功能。3. 环境准备与多平台安装实战3.1 基础依赖与令牌获取无论你在哪个AI助手平台使用这个技能有两样东西是通用的、必须提前准备的基础命令行工具和Figshare个人令牌。基础工具curl和jq这两个是Linux/macOS系统上通常自带的强大工具。curl用于处理网络请求jq用于解析和格式化JSON响应。在Windows上如果你使用WSL (Windows Subsystem for Linux)、Git Bash或Cygwin它们通常也包含在内。你可以通过运行curl --version和jq --version来检查是否已安装。如果没有在Ubuntu/Debian上使用sudo apt install curl jq在macOS上使用brew install curl jq即可安装。注意虽然技能脚本尽力保持了兼容性但在不同的Shell环境如bash, zsh和不同版本的jq中某些JSON解析语法可能略有差异。如果遇到脚本执行错误首先检查jq的语法是否被你的环境完全支持。Figshare个人令牌这是你身份的钥匙用于执行任何涉及你个人账户的操作上传、管理文章等。获取步骤非常简单登录 Figshare网站 。点击右上角头像进入“Settings”。在左侧菜单中找到“Applications”应用程序。在“Personal token”个人令牌部分点击“Generate new token”。为令牌起一个名字例如“My-AI-Assistant-Skill”然后点击生成。非常重要立即复制生成的令牌字符串。这个令牌只显示一次关闭页面后就无法再次查看如果丢失需要重新生成。获取令牌后你需要将其设置为环境变量。打开你的终端执行export FIGSHARE_TOKEN你的令牌字符串为了不用每次打开新终端都重新设置可以将这行命令添加到你的Shell配置文件中如~/.bashrc,~/.zshrc。添加后执行source ~/.zshrc或对应的配置文件使其生效。实操心得安全地管理令牌至关重要。切勿将包含令牌的脚本或命令提交到公开的代码仓库如GitHub。使用环境变量是推荐的方式。在一些自动化流水线中如GitHub Actions可以使用仓库的Secrets功能来安全地存储和传递这个令牌。3.2 四大AI助手平台安装指南figshare-skill遵循了agentskills.io提出的技能格式规范这使得它能适配多个主流AI编程助手平台。每个平台的技能加载机制略有不同但核心都是将技能仓库克隆到特定的目录下。1. Codex 平台安装Codex这里指的应是基于OpenAI Codex的特定AI编程环境通常期望技能安装在用户的全局目录中。git clone https://github.com/Agents365-ai/figshare-skill.git ~/.codex/skills/figshare-skill执行后Codex会在其技能库中自动发现figshare-skill。agents/openai.yaml文件提供了UI元数据帮助Codex在界面中更好地展示和推荐这个技能。2. 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项目级安装非常适合团队协作可以将项目所需的特定技能随项目代码一起管理确保环境一致性。3. OpenClaw 平台安装OpenClaw的安装方式与Claude Code类似。全局安装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注意项目级路径没有前面的点.这与Claude Code不同安装时需留意目标平台的文档说明。4. SkillsMP 平台安装SkillsMP 是一个技能索引和分发平台提供了最简便的安装方式。skills install figshare-skill这条命令会从SkillsMP的仓库中自动获取并安装技能。这是最“傻瓜式”的方法前提是你已经安装了SkillsMP的CLI工具。注意事项安装完成后通常需要重启你的AI助手客户端或重新加载技能列表新的技能才能被识别和启用。如果安装后技能未出现请检查目标路径是否正确以及AI助手是否有读取该路径的权限。4. 核心脚本深度剖析与使用示例技能包中的三个Bash脚本upload.sh,download.sh,new-version.sh是封装了复杂逻辑的利器。理解它们的工作原理不仅能帮助你更好地使用还能在出现问题时快速排查。4.1download.sh公共资源批量下载器这个脚本用于一键下载某个公开Figshare文章的所有文件。其核心逻辑如下解析输入接受文章ID、DOI或URL。脚本内部使用正则表达式提取出纯数字的文章ID。获取文件列表向https://api.figshare.com/v2/articles/{article_id}发送GET请求获取文章的完整元数据其中包含files数组。遍历下载循环处理files数组中的每一个文件对象获取其下载链接download_url和文件名name然后使用curl进行下载。使用示例# 使用文章ID下载 ./scripts/download.sh 31957606 ./my_dataset # 使用DOI下载 ./scripts/download.sh 10.6084/m9.figshare.31957606 ./my_dataset # 使用完整URL下载 ./scripts/download.sh https://figshare.com/articles/dataset/Title/31957606 ./my_dataset第二个参数[dir]是可选的下载目录默认为当前目录。实操心得这个脚本在下载数十个甚至上百个小文件时非常方便。但如果文件非常大比如每个都超过1GB由于是顺序下载可能会比较慢。你可以手动修改脚本在curl命令中加入-L参数跟随重定向和-C -参数断点续传以增强其健壮性。另外Figshare的下载链接有时效性如果脚本运行中途失败重新运行即可它会覆盖已下载完成的部分文件。4.2upload.sh大文件多部分上传的自动化引擎这是技能中最复杂的脚本它自动化了Figshare大文件上传的“初始化-上传分块-完成”三步流程。我们详细拆解一下第一步初始化 (initiate)脚本首先计算待上传文件的MD5校验和和文件大小。然后调用POST /v2/account/articles/{article_id}/files端点告诉Figshare“我准备上传一个文件它叫这个名字有这么大MD5是这么多。” Figshare会响应一个包含upload_url和upload_token等信息的对象。最关键的是Figshare会告知文件应该被分成多少块parts以及每块的大小partSize。脚本会根据这些信息来规划上传。第二步分块上传 (PUT parts)这是最核心的循环。脚本使用dd命令按照partSize将大文件切割成多个小块part。对于每一块它需要计算该分块的MD5。向{upload_url}/{part_number}发送一个PUT请求请求体就是该分块的二进制数据并在请求头中携带该分块的MD5值。 这个过程循环进行直到所有分块上传完毕。项目文档中提到当前脚本使用dd bs1来精确读取每一个字节这对于确保分块边界绝对正确是稳妥的但对于GB级的大文件效率确实不高。社区常见的优化是使用bs1M配合skip和count参数来跳跃读取。第三步完成 (complete)当所有分块都成功上传后脚本向POST /v2/account/articles/{article_id}/files/{file_id}发送请求并携带最初的upload_token告知Figshare“所有分块已就位请组装成完整的文件并验证MD5。” Figshare服务端会进行验证成功后文件便出现在你的文章草稿中。使用示例# 确保 FIGSHARE_TOKEN 环境变量已设置 export FIGSHARE_TOKENyour_token_here # 上传文件到指定草稿文章 ./scripts/upload.sh 31957803 ./analysis_results.zip重要提示upload.sh只能上传到处于“草稿”状态的文章。如果文章已发布你需要使用new-version.sh。4.3new-version.sh已发布文章的更新工作流对于已发布的文章Figshare的策略是“版本化”。已发布的版本是只读的。如果你想更新内容必须创建一个新版本。new-version.sh脚本将这个多步骤工作流自动化了预留新版本调用POST /v2/account/articles/{article_id}/versions基于旧版本创建一个新的草稿版本。这会返回一个新版本的ID。上传文件本质上它内部调用了与upload.sh类似的上传逻辑但是将文件上传到新版本对应的文章ID这是一个新的草稿文章。发布新版本文件上传完成后调用POST /v2/account/articles/{new_article_id}/publish来发布这个新版本。使用示例./scripts/new-version.sh 12345678 ./updated_data_v2.csv执行后原文章ID: 12345678下就会出现版本2包含了你的新文件。原版本1仍然存在且可访问。避坑指南务必理解“文章ID”和“版本”的关系。当你创建一个新版本时Figshare实际上在后台为你创建了一个全新的、独立的文章实体并将其与旧版本关联起来。new-version.sh返回和操作的是这个新文章ID。在管理时不要混淆不同版本对应的文章ID。5. 与AI助手协同工作的模式与技巧安装技能后你与AI助手的交互模式会发生根本变化。你不再需要记忆API细节而是转向“描述目标”。5.1 自然语言指令范例你可以尝试向你的AI助手如Claude Code输入以下指令观察它如何利用技能知识进行响应搜索与发现“搜索Figshare上标题包含‘machine learning’且类别是‘Computer Science’的公开文章列出前5个。”“帮我找一下作者是‘Smith, John’最近一年上传的数据集。”AI助手可能会生成类似这样的命令组合使用curl调用搜索API并利用:title:和:category:操作符过滤最后用jq美化输出。数据获取“下载这个Figshare文章URL: https://figshare.com/...的所有文件到当前目录的‘raw_data’文件夹里。”AI助手会识别出这是下载任务直接建议或执行./scripts/download.sh url ./raw_data。内容管理“我有个草稿文章ID是31957803把‘final_report.pdf’和‘data.csv’这两个文件传上去。”AI助手会理解需要依次调用两次upload.sh脚本。“为我创建一个新的Figshare文章草稿标题是‘Experiment Results - May 2024’描述是‘Raw data and analysis for the conductivity tests.’类别选‘Engineering’许可证选‘CC BY 4.0’。”这里AI助手需要先知道类别和许可证的ID。它可能会先指导你或帮你查询/v2/categories和/v2/licenses接口获取‘Engineering’和‘CC BY 4.0’对应的数字ID然后再组装创建文章的API请求。5.2 提示工程与技能触发为了让AI助手更准确地调用技能你可以掌握一些“提示工程”小技巧明确提及技能或关键词在指令中直接包含“$figshare-skill”、“使用figshare技能”或“Figshare API”能更直接地触发助手加载相关上下文。提供结构化信息当要求创建或更新文章时一次性提供尽可能多的元数据标题、描述、作者列表、标签、类别ID、许可证ID可以减少来回对话的次数。分步复杂任务对于非常复杂的任务可以分解步骤。例如“第一步在Figshare上搜索关于‘珊瑚白化’的公开数据集并列出。第二步将第一个数据集的所有文件下载到本地。第三步用我本地的‘cleaned_data.csv’文件创建一个新的草稿文章。”5.3 故障排查与AI协作调试即使有技能AI助手生成的命令或脚本调用也可能因为环境问题、参数错误或API变动而失败。这时你需要和AI助手协作调试。检查环境变量最常见的失败原因是FIGSHARE_TOKEN未设置或失效。让AI助手帮你生成一条检查命令如echo $FIGSHARE_TOKEN或env | grep FIGSHARE。查看详细错误请求失败时curl通常会返回错误码和消息。指示AI助手在命令中加入-v详细模式或-i包含响应头参数以便获取更详细的错误信息例如curl -i -H Authorization: token $FIGSHARE_TOKEN ...。验证API端点如果怀疑是技能知识过时尽管概率低可以让AI助手直接测试一个最简单的API端点比如curl -X GET https://api.figshare.com/v2/articles/1来验证网络连通性和API基本状态。脚本调试如果辅助脚本执行出错可以和AI助手一起阅读脚本源码定位问题行。例如jq命令解析JSON失败可能是响应格式不符合预期可以先把原始响应保存到文件查看。6. 高级应用场景与性能优化考量6.1 集成到自动化工作流中figshare-skill的脚本虽然是面向AI助手设计的但其本质是标准的Bash脚本这意味着它们可以轻松地被集成到任何自动化流水线中比如Shell脚本、Makefile、或是CI/CD流程如GitHub Actions、GitLab CI。场景示例自动化数据发布流水线假设你有一个每周运行的数据分析管道最终会生成一个报告文件weekly_report.zip。你可以编写一个Shell脚本来自动化发布#!/bin/bash # auto_publish.sh set -e # 遇到错误即停止 # 1. 运行你的数据分析脚本生成 weekly_report.zip python run_analysis.py # 2. 使用 figshare-skill 上传到指定的草稿文章 # 假设你的草稿文章ID是固定的或者可以从配置中读取 ARTICLE_ID31957803 export FIGSHARE_TOKEN$FIGSHARE_TOKEN # 从CI Secrets传入 # 调用技能脚本 ./path/to/figshare-skill/scripts/upload.sh $ARTICLE_ID ./output/weekly_report.zip # 3. (可选) 自动发布文章 # 注意通常自动发布需要谨慎这里仅作示例。你可能需要先设置好元数据。 # curl -X POST -H Authorization: token $FIGSHARE_TOKEN \ # https://api.figshare.com/v2/account/articles/$ARTICLE_ID/publish echo File uploaded to article $ARTICLE_ID successfully.在GitHub Actions中你可以将FIGSHARE_TOKEN存储在仓库的Secrets中然后在工作流步骤里调用这个脚本。6.2 处理超大规模文件与性能调优项目文档中提到了一个已知限制dd bs1对于超大文件分块较慢。如果你经常需要上传数十GB的单个文件可以考虑对upload.sh脚本进行本地化优化。优化思路替换掉低效的dd bs1分块读取方式。核心是计算每个分块的起始偏移量和大小然后用更高效的块大小进行读取。# 原脚本中效率较低的部分简化示意 dd if$file bs1 skip$(( (part_number-1) * partSize )) count$partSize 2/dev/null | ... # 优化方案概念性代码 # 计算偏移量 offset$(( (part_number - 1) * partSize )) # 使用更大的块大小如1MB进行读取count参数表示读取多少个bs单位 dd if$file bs1M skip$(( offset / 1024 / 1024 )) count$(( (partSize 1024*1024 -1) / (1024*1024) )) 2/dev/null | ...重要警告修改脚本需要非常小心必须确保计算出的字节范围绝对精确否则上传的文件MD5校验会失败。建议先在本地用一个小文件测试优化后的分块逻辑是否正确。应对速率限制Figshare建议的请求速率是每秒不超过1次。脚本目前没有内置限流。如果你在短时间内触发大量API调用例如批量上传几百个小文件可能会被限流。一个简单的改进是在脚本的循环中尤其是上传分块的循环加入sleep 1命令在每次请求后暂停1秒。对于下载脚本如果并行下载多个文件也可能触发限流可以考虑改为顺序下载或加入延迟。6.3 元数据管理的技巧创建或更新文章时除了文件元数据标题、描述、标签、类别、许可证同样重要。技能本身不包含复杂的元数据编辑脚本但这正是AI助手可以大显身手的地方。你可以让AI助手帮你查询ID“获取Figshare中‘Biology’类别对应的ID是多少”通过GET /v2/categories构建复杂的JSON“帮我生成一个创建文章的JSON请求体标题是X描述是Y标签是[‘tag1’ ‘tag2’]类别ID是Z许可证ID是1。”批量更新“读取这个CSV文件每一行包含一个文章ID和新标题批量更新这些文章的标题。”通过组合AI助手的代码生成能力和figshare-skill提供的API知识框架你可以构建出非常灵活和强大的元数据管理方案。7. 常见问题与故障排查实录在实际使用中你可能会遇到一些典型问题。这里我根据经验整理了一份排查清单。7.1 认证与权限问题问题现象可能原因解决方案curl命令返回401 Unauthorized1.FIGSHARE_TOKEN环境变量未设置或为空。2. 令牌已过期或被撤销。3. 令牌作用域不足但Figshare个人令牌通常有全部权限。1. 执行echo $FIGSHARE_TOKEN确认。在脚本中显式传递FIGSHARE_TOKENxxx ./upload.sh ...。2. 登录Figshare后台在Applications下重新生成令牌。3. 确认操作是否需要账户权限如上传到私有项目。可以搜索公开文章但无法管理自己的文章未设置令牌或令牌错误。公开接口无需认证账户相关接口需要。确保在执行管理操作前正确设置FIGSHARE_TOKEN。脚本提示jq命令解析错误但API返回了数据API返回了错误信息JSON如{message: Forbidden}而非预期的数据JSON。在curl命令后添加-i参数查看完整HTTP状态码和响应头确认是否是4xx或5xx错误。先解决API请求本身的问题。7.2 上传与下载故障问题现象可能原因解决方案upload.sh失败提示Part size mismatch或MD5错误1. 文件在上传过程中被修改。2.dd分块逻辑在特定环境下有瑕疵极少数情况。3. 网络传输中数据损坏。1. 确保上传期间文件未被其他进程写入。2. 对于超大文件尝试使用优化后的dd命令见6.2节。3. 重试上传。Figshare的多部分上传是幂等的可以重传单个分块。download.sh下载的文件大小为0或损坏1. 下载链接是重定向链接curl未跟随。2. 网络中断导致文件不完整。1. 在脚本的curl命令中添加-L参数以跟随重定向。2. 使用curl -C -支持断点续传并重试下载。上传速度非常慢1. 网络问题。2. 使用dd bs1分块对于大文件。3. Figshare服务器限流或繁忙。1. 检查网络。2. 考虑优化upload.sh脚本的分块逻辑。3. 在脚本中加入sleep间隔避免触发速率限制。new-version.sh执行后找不到新版本新版本创建后处于“草稿”状态需要手动或通过API发布。new-version.sh通常包含发布步骤检查其执行日志。确认脚本是否成功调用了发布接口。可以手动登录Figshare网站在文章页面查看“版本”历史。7.3 环境与脚本执行问题问题现象可能原因解决方案bash: ./scripts/upload.sh: Permission denied脚本没有执行权限。运行chmod x scripts/*.sh为所有脚本添加执行权限。command not found: jq或curl系统未安装curl或jq。根据操作系统安装所需工具见3.1节。在Windows Git Bash中运行脚本路径或语法错误Windows和Unix的路径分隔符、换行符不同或者Shell解释器有差异。1. 确保在Git Bash或WSL环境中运行。2. 检查脚本第一行的shebang#!/bin/bash。3. 避免在脚本中使用绝对路径使用相对路径。AI助手无法识别或调用技能1. 技能未安装到正确路径。2. AI助手未加载技能列表。3. 技能描述文件SKILL.md格式有误。1. 对照第3章的安装路径表仔细检查。2. 重启AI助手客户端或重新加载技能。3. 检查SKILL.md文件是否存在且内容完整。7.4 API限制与最佳实践速率限制始终假设存在每秒1次的速率限制。在编写循环调用API的脚本时主动加入sleep 1是良好的习惯。文章状态牢记“草稿可编辑已发布版本不可编辑”。更新内容用new-version.sh更新草稿元数据用普通的updateAPI。文件大小虽然技能支持多部分上传但单个文件过大如超过10GB可能会遇到其他限制或超时。如果可能将超大文件分割成多个逻辑部分上传。令牌安全永远不要在日志、公开代码或聊天记录中泄露你的FIGSHARE_TOKEN。在自动化系统中使用环境变量或安全的密钥管理服务。通过理解这些常见问题及其解决方案你可以更自信地使用figshare-skill并在遇到障碍时快速找到方向。这个技能的价值在于它提供了一个坚实、可靠的起点而你可以基于此根据自己特定的工作流和环境进行定制和扩展。