⚡

协议.io集成Skill protocolsio-integration

Protocols.io集成技能是一个API集成工具，允许开发者通过代码与protocols.io平台交互，实现科学协议的管理、协作和自动化。此技能支持协议搜索、创建、更新、发布、讨论管理、工作空间组织和文件上传，适用于科研、实验室管理和科学文档场景。关键词：protocols.io API, 科学协议管理, 实验室管理, 协作工具, 文件管理, 实验跟踪, 协议搜索, 数据集成, 后端开发, API集成。

后端开发 0 次安装 0 次浏览 更新于 3/16/2026

name: protocolsio-integration description: 与protocols.io API集成，用于管理科学协议。此技能应在使用protocols.io时使用，以搜索、创建、更新或发布协议；管理协议步骤和材料；处理讨论和评论；组织工作空间；上传和管理文件；或将protocols.io功能集成到工作流程中。适用于协议发现、协作协议开发、实验跟踪、实验室协议管理和科学文档。

Protocols.io集成

概述

Protocols.io是一个全面的平台，用于开发、共享和管理科学协议。此技能提供与protocols.io API v3的完全集成，使能够通过编程访问协议、工作空间、讨论、文件管理和协作功能。

何时使用此技能

在以下场景中使用此技能：

  • 协议发现：通过关键词、DOI或类别搜索现有协议
  • 协议管理：创建、更新或发布科学协议
  • 步骤管理：添加、编辑或组织协议步骤和程序
  • 协作开发：与团队成员在共享协议上工作
  • 工作空间组织：管理实验室或机构协议存储库
  • 讨论与反馈：添加或回复协议评论
  • 文件管理：上传数据文件、图像或文档到协议
  • 实验跟踪：记录协议执行和结果
  • 数据导出：备份或迁移协议集合
  • 集成项目：构建与protocols.io交互的工具

核心能力

此技能提供五个主要能力领域的全面指导：

1. 认证与访问

使用访问令牌和OAuth流程管理API认证。包括个人内容的客户端访问令牌和多用户应用的OAuth令牌。

关键操作：

  • 为OAuth流程生成授权链接
  • 交换授权码以获取访问令牌
  • 刷新过期令牌
  • 管理速率限制和权限

参考： 阅读references/authentication.md获取详细认证程序、OAuth实施和安全最佳实践。

2. 协议操作

从创建到发布的完整协议生命周期管理。

关键操作：

  • 通过关键词、过滤器或DOI搜索和发现协议
  • 检索包含所有步骤的详细协议信息
  • 使用元数据和标签创建新协议
  • 更新协议信息和设置
  • 管理协议步骤（创建、更新、删除、重新排序）
  • 处理协议材料和试剂
  • 发布协议并分配DOI
  • 为快速访问添加书签
  • 生成协议PDF

参考： 阅读references/protocols_api.md获取全面的协议管理指导，包括API端点、参数、常见工作流和示例。

3. 讨论与协作

通过评论和讨论促进社区参与。

关键操作：

  • 查看协议级别和步骤级别的评论
  • 创建新评论和线程回复
  • 编辑或删除自己的评论
  • 分析讨论模式和反馈
  • 响应用户问题和问题

参考： 阅读references/discussions.md获取讨论管理、评论线程和协作工作流。

4. 工作空间管理

在具有基于角色的权限的团队工作空间中组织协议。

关键操作：

  • 列出和访问用户工作空间
  • 检索工作空间详情和成员列表
  • 请求访问或加入工作空间
  • 列出工作空间特定协议
  • 在工作空间中创建协议
  • 管理工作空间权限和协作

参考： 阅读references/workspaces.md获取工作空间组织、权限管理和团队协作模式。

5. 文件操作

上传、组织和管理与协议相关的文件。

关键操作：

  • 搜索工作空间文件和文件夹
  • 上传带有元数据和标签的文件
  • 下载文件和验证上传
  • 将文件组织到文件夹层次结构中
  • 更新文件元数据
  • 删除和恢复文件
  • 管理存储和组织

参考： 阅读references/file_manager.md获取文件上传程序、组织策略和存储管理。

6. 附加功能

补充功能，包括配置文件、通知和导出。

关键操作：

  • 管理用户配置文件和设置
  • 查询最近发布的协议
  • 创建和跟踪实验记录
  • 接收和管理通知
  • 导出组织数据以供存档

参考： 阅读references/additional_features.md获取配置文件管理、发布发现、实验跟踪和数据导出。

入门指南

步骤1：认证设置

在使用任何protocols.io API功能之前：

  1. 获取访问令牌（CLIENT_ACCESS_TOKEN或OAUTH_ACCESS_TOKEN）
  2. 阅读references/authentication.md获取详细认证程序
  3. 安全存储令牌
  4. 在所有请求中包含：Authorization: Bearer YOUR_TOKEN

步骤2：确定您的使用案例

确定哪个能力领域满足您的需求：

  • 处理协议？ → 阅读references/protocols_api.md
  • 管理团队协议？ → 阅读references/workspaces.md
  • 处理评论/反馈？ → 阅读references/discussions.md
  • 上传文件/数据？ → 阅读references/file_manager.md
  • 跟踪实验或配置文件？ → 阅读references/additional_features.md

步骤3：实施集成

遵循相关参考文件中的指导：

  • 每个参考包括详细的端点文档
  • 指定API参数和请求/响应格式
  • 提供常见使用案例和工作流示例
  • 包括最佳实践和错误处理指导

基础URL和请求格式

所有API请求使用基础URL：

https://protocols.io/api/v3

所有请求需要授权头：

Authorization: Bearer YOUR_ACCESS_TOKEN

大多数端点支持JSON请求/响应格式，使用Content-Type: application/json。

内容格式选项

许多端点支持content_format参数以控制协议内容的返回方式：

  • json：Draft.js JSON格式（默认）
  • html：HTML格式
  • markdown：Markdown格式

作为查询参数包含：?content_format=html

速率限制

注意API速率限制：

  • 标准端点：每个用户每分钟100个请求
  • PDF端点：登录时每分钟5个请求，未登录时每分钟3个请求

为速率限制错误（HTTP 429）实施指数退避。

常见工作流

工作流1：导入和分析协议

从protocols.io分析现有协议：

  1. 搜索：使用GET /protocols带关键词查找相关协议
  2. 检索：使用GET /protocols/{protocol_id}获取完整详情
  3. 提取：解析步骤、材料和元数据以供分析
  4. 审查讨论：检查GET /protocols/{id}/comments获取用户反馈
  5. 导出：如有需要，生成PDF以供离线参考

参考文件：protocols_api.md、discussions.md

工作流2：创建和发布协议

创建新协议并分配DOI发布：

  1. 认证：确保有有效访问令牌（见authentication.md）
  2. 创建：使用POST /protocols带标题和描述
  3. 添加步骤：对于每个步骤，使用POST /protocols/{id}/steps
  4. 添加材料：在步骤组件中记录试剂
  5. 审查：验证所有内容完整且准确
  6. 发布：使用POST /protocols/{id}/publish分配DOI

参考文件：protocols_api.md、authentication.md

工作流3：协作实验室工作空间

设置团队协议管理：

  1. 创建/加入工作空间：访问或请求工作空间成员资格（见workspaces.md）
  2. 组织结构：为实验室协议创建文件夹层次结构（见file_manager.md）
  3. 创建协议：使用POST /workspaces/{id}/protocols为团队协议
  4. 上传文件：添加实验数据和图像
  5. 启用讨论：团队成员可以评论和提供反馈
  6. 跟踪实验：用实验记录记录协议执行

参考文件：workspaces.md、file_manager.md、protocols_api.md、discussions.md、additional_features.md

工作流4：实验文档

跟踪协议执行和结果：

  1. 执行协议：在实验室执行协议
  2. 上传数据：使用文件管理器API上传结果（见file_manager.md）
  3. 创建记录：用POST /protocols/{id}/runs记录执行
  4. 链接文件：在实验记录中引用上传的数据文件
  5. 注意修改：记录任何协议偏差或优化
  6. 分析：审查多次执行以评估可重复性

参考文件：additional_features.md、file_manager.md、protocols_api.md

工作流5：协议发现和引用

在研究中查找和引用协议：

  1. 搜索：使用GET /publications查询已发布协议
  2. 过滤：使用类别和关键词过滤器查找相关协议
  3. 审查：阅读协议详情和社区评论
  4. 添加书签：使用POST /protocols/{id}/bookmarks保存有用协议
  5. 引用：在出版物中使用协议DOI（适当归属）
  6. 导出PDF：生成格式化PDF以供离线参考

参考文件：protocols_api.md、additional_features.md

Python请求示例

基本协议搜索

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

# 搜索CRISPR协议
response = requests.get(
    "https://protocols.io/api/v3/protocols",
    headers=headers,
    params={
        "filter": "public",
        "key": "CRISPR",
        "page_size": 10,
        "content_format": "html"
    }
)

protocols = response.json()
for protocol in protocols["items"]:
    print(f"{protocol['title']} - {protocol['doi']}")

创建新协议

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# 创建协议
data = {
    "title": "CRISPR-Cas9基因编辑协议",
    "description": "CRISPR基因编辑的全面协议",
    "tags": ["CRISPR", "基因编辑", "分子生物学"]
}

response = requests.post(
    "https://protocols.io/api/v3/protocols",
    headers=headers,
    json=data
)

protocol_id = response.json()["item"]["id"]
print(f"创建协议：{protocol_id}")

上传文件到工作空间

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

# 上传文件
with open("data.csv", "rb") as f:
    files = {"file": f}
    data = {
        "folder_id": "root",
        "description": "实验结果",
        "tags": "experiment,data,2025"
    }

    response = requests.post(
        "https://protocols.io/api/v3/workspaces/12345/files/upload",
        headers=headers,
        files=files,
        data=data
    )

file_id = response.json()["item"]["id"]
print(f"上传文件：{file_id}")

错误处理

为API请求实施健壮的错误处理：

import requests
import time

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:  # 速率限制
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:  # 服务器错误
                time.sleep(2 ** attempt)  # 指数退避
                continue
            else:
                response.raise_for_status()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("最大重试次数超出")

参考文件

根据您的任务加载适当的参考文件：

  • authentication.md：OAuth流程、令牌管理、速率限制
  • protocols_api.md：协议CRUD、步骤、材料、发布、PDF
  • discussions.md：评论、回复、协作
  • workspaces.md：团队工作空间、权限、组织
  • file_manager.md：文件上传、文件夹、存储管理
  • additional_features.md：配置文件、发布、实验、通知

需要特定功能时，从references/目录读取参考文件。

最佳实践

  1. 认证：安全存储令牌，切勿存储在代码或版本控制中
  2. 速率限制：实施指数退避并尊重速率限制
  3. 错误处理：适当处理所有HTTP错误代码
  4. 数据验证：在API调用前验证输入
  5. 文档：详细记录协议步骤
  6. 协作：使用评论和讨论进行团队沟通
  7. 组织：保持一致的命名和标记约定
  8. 版本控制：更新时跟踪协议版本
  9. 归属：使用DOI正确引用协议
  10. 备份：定期导出重要协议和工作空间数据

附加资源

故障排除

认证问题：

  • 验证令牌有效且未过期
  • 检查授权头格式：Bearer YOUR_TOKEN
  • 确保适当的令牌类型（CLIENT与OAUTH）

速率限制：

  • 为429错误实施指数退避
  • 监控请求频率
  • 考虑缓存频繁请求

权限错误：

  • 验证工作空间/协议访问权限
  • 检查用户在工作空间中的角色
  • 确保协议不私有，如果访问无需权限

文件上传失败：

  • 检查文件大小是否超过工作空间限制
  • 验证文件类型是否支持
  • 确保multipart/form-data编码正确

有关详细故障排除指导，请参考涵盖每个能力领域的特定参考文件。