protocolsio-integration

Protocols.io 集成

概述

Protocols.io 是一个全面的平台，用于开发、分享和管理科学实验方案。此技能与 protocols.io API v3 完全集成，支持以编程方式访问实验方案、工作区、讨论、文件管理和协作功能。

何时使用此技能

在以下任一场景中使用此技能处理 protocols.io：

• 实验方案发现：按关键词、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 标头：

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. 上传数据：使用 File Manager 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}"}

# Search for CRISPR protocols
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"
}

# Create protocol
data = {
    "title": "CRISPR-Cas9 Gene Editing Protocol",
    "description": "Comprehensive protocol for CRISPR gene editing",
    "tags": ["CRISPR", "gene editing", "molecular biology"]
}

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

protocol_id = response.json()["item"]["id"]
print(f"Created protocol: {protocol_id}")

将文件上传到工作区

import requests

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

# Upload file
with open("data.csv", "rb") as f:
    files = {"file": f}
    data = {
        "folder_id": "root",
        "description": "Experimental results",
        "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"Uploaded file: {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:  # Rate limit
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:  # Server error
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                response.raise_for_status()

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

    raise Exception("Max retries exceeded")

参考文件

根据任务加载相应的参考文件：

• 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. 备份：定期导出重要协议和工作区数据

其他资源

• 官方 API 文档：https://apidoc.protocols.io/
• Protocols.io 平台：https://www.protocols.io/
• 支持：联系 protocols.io 支持团队，获取 API 访问权限并解决技术问题
• 社区：与 protocols.io 社区交流，了解最佳实践

故障排除

身份验证问题：

• 确认令牌有效且未过期
• 检查 Authorization 标头格式：Bearer YOUR_TOKEN
• 确保令牌类型正确（CLIENT 或 OAUTH）

速率限制：

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

权限错误：

• 确认工作区/协议访问权限
• 检查用户在工作区中的角色
• 如果没有访问权限，确保协议不是私有的

文件上传失败：

• 检查文件大小是否超出工作区限制
• 确认文件类型受支持
• 确保 multipart/form-data 编码正确

如需详细的故障排除指南，请参阅涵盖各项功能领域的特定参考文件。