protocolsio-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Protocols.io Integration

Protocols.io 集成

Overview

概述

Protocols.io is a comprehensive platform for developing, sharing, and managing scientific protocols. This skill provides complete integration with the protocols.io API v3, enabling programmatic access to protocols, workspaces, discussions, file management, and collaboration features.

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

When to Use This Skill

适用场景

Use this skill when working with protocols.io in any of the following scenarios:

Protocol Discovery: Searching for existing protocols by keywords, DOI, or category
Protocol Management: Creating, updating, or publishing scientific protocols
Step Management: Adding, editing, or organizing protocol steps and procedures
Collaborative Development: Working with team members on shared protocols
Workspace Organization: Managing lab or institutional protocol repositories
Discussion & Feedback: Adding or responding to protocol comments
File Management: Uploading data files, images, or documents to protocols
Experiment Tracking: Documenting protocol executions and results
Data Export: Backing up or migrating protocol collections
Integration Projects: Building tools that interact with protocols.io

在以下场景中使用protocols.io时，可运用本技能：

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

Core Capabilities

核心能力

This skill provides comprehensive guidance across five major capability areas:

本技能在五大核心能力领域提供全面指导：

1. Authentication & Access

1. 身份验证与访问

Manage API authentication using access tokens and OAuth flows. Includes both client access tokens (for personal content) and OAuth tokens (for multi-user applications).

Key operations:

Generate authorization links for OAuth flow
Exchange authorization codes for access tokens
Refresh expired tokens
Manage rate limits and permissions

Reference: Read

references/authentication.md

for detailed authentication procedures, OAuth implementation, and security best practices.

使用访问令牌和OAuth流程管理API身份验证，包括客户端访问令牌（用于个人内容）和OAuth令牌（用于多用户应用）。

关键操作：

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

参考： 阅读

references/authentication.md

获取详细的身份验证流程、OAuth实现方法及安全最佳实践。

2. Protocol Operations

2. 实验方案操作

Complete protocol lifecycle management from creation to publication.

Key operations:

Search and discover protocols by keywords, filters, or DOI
Retrieve detailed protocol information with all steps
Create new protocols with metadata and tags
Update protocol information and settings
Manage protocol steps (create, update, delete, reorder)
Handle protocol materials and reagents
Publish protocols with DOI issuance
Bookmark protocols for quick access
Generate protocol PDFs

Reference: Read

references/protocols_api.md

for comprehensive protocol management guidance, including API endpoints, parameters, common workflows, and examples.

覆盖从创建到发布的完整实验方案生命周期管理。

关键操作：

通过关键词、筛选条件或DOI搜索和发现实验方案
获取包含所有步骤的实验方案详细信息
创建带有元数据和标签的新实验方案
更新实验方案信息与设置
管理实验方案步骤（创建、更新、删除、重新排序）
处理实验方案的材料与试剂
发布实验方案并获取DOI
为实验方案添加书签以便快速访问
生成实验方案PDF

参考： 阅读

references/protocols_api.md

获取全面的实验方案管理指导，包括API端点、参数、常见工作流及示例。

3. Discussions & Collaboration

3. 讨论与协作

Enable community engagement through comments and discussions.

Key operations:

View protocol-level and step-level comments
Create new comments and threaded replies
Edit or delete your own comments
Analyze discussion patterns and feedback
Respond to user questions and issues

Reference: Read

references/discussions.md

for discussion management, comment threading, and collaboration workflows.

通过评论和讨论实现社区互动。

关键操作：

查看实验方案级和步骤级的评论
创建新评论及线程化回复
编辑或删除自己的评论
分析讨论模式与反馈
回应用户的问题与疑问

参考： 阅读

references/discussions.md

获取讨论管理、评论线程化及协作工作流的相关内容。

4. Workspace Management

4. 工作区管理

Organize protocols within team workspaces with role-based permissions.

Key operations:

List and access user workspaces
Retrieve workspace details and member lists
Request access or join workspaces
List workspace-specific protocols
Create protocols within workspaces
Manage workspace permissions and collaboration

Reference: Read

references/workspaces.md

for workspace organization, permission management, and team collaboration patterns.

在基于角色权限的团队工作区内组织实验方案。

关键操作：

列出并访问用户工作区
获取工作区详情及成员列表
请求访问或加入工作区
列出工作区专属的实验方案
在工作区内创建实验方案
管理工作区权限与协作

参考： 阅读

references/workspaces.md

获取工作区组织、权限管理及团队协作模式的相关内容。

5. File Operations

5. 文件操作

Upload, organize, and manage files associated with protocols.

Key operations:

Search workspace files and folders
Upload files with metadata and tags
Download files and verify uploads
Organize files into folder hierarchies
Update file metadata
Delete and restore files
Manage storage and organization

Reference: Read

references/file_manager.md

for file upload procedures, organization strategies, and storage management.

上传、组织和管理与实验方案关联的文件。

关键操作：

搜索工作区文件与文件夹
上传带有元数据和标签的文件
下载文件并验证上传结果
将文件整理为文件夹层级结构
更新文件元数据
删除与恢复文件
管理存储与组织

参考： 阅读

references/file_manager.md

获取文件上传流程、组织策略及存储管理的相关内容。

6. Additional Features

6. 附加功能

Supplementary functionality including profiles, notifications, and exports.

Key operations:

Manage user profiles and settings
Query recently published protocols
Create and track experiment records
Receive and manage notifications
Export organization data for archival

Reference: Read

references/additional_features.md

for profile management, publication discovery, experiment tracking, and data export.

包括个人资料、通知与导出在内的补充功能。

关键操作：

管理用户个人资料与设置
查询近期发布的实验方案
创建并追踪实验记录
接收与管理通知
导出组织数据用于存档

参考： 阅读

references/additional_features.md

获取个人资料管理、发布内容发现、实验追踪及数据导出的相关内容。

Getting Started

快速开始

Step 1: Authentication Setup

步骤1：身份验证设置

Before using any protocols.io API functionality:

Obtain an access token (CLIENT_ACCESS_TOKEN or OAUTH_ACCESS_TOKEN)
Read
```
references/authentication.md
```
for detailed authentication procedures
Store the token securely
Include in all requests as:
```
Authorization: Bearer YOUR_TOKEN
```

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

获取访问令牌（CLIENT_ACCESS_TOKEN或OAUTH_ACCESS_TOKEN）
阅读
```
references/authentication.md
```
获取详细的身份验证流程
安全存储令牌
在所有请求中包含以下头部信息：
```
Authorization: Bearer YOUR_TOKEN
```

Step 2: Identify Your Use Case

步骤2：确定使用场景

Determine which capability area addresses your needs:

Working with protocols? → Read
```
references/protocols_api.md
```
Managing team protocols? → Read
```
references/workspaces.md
```
Handling comments/feedback? → Read
```
references/discussions.md
```
Uploading files/data? → Read
```
references/file_manager.md
```
Tracking experiments or profiles? → Read
```
references/additional_features.md
```

确定你的需求对应的能力领域：

处理实验方案？ → 阅读
```
references/protocols_api.md
```
管理团队实验方案？ → 阅读
```
references/workspaces.md
```
处理评论/反馈？ → 阅读
```
references/discussions.md
```
上传文件/数据？ → 阅读
```
references/file_manager.md
```
追踪实验或管理个人资料？ → 阅读
```
references/additional_features.md
```

Step 3: Implement Integration

步骤3：实现集成

Follow the guidance in the relevant reference files:

Each reference includes detailed endpoint documentation
API parameters and request/response formats are specified
Common use cases and workflows are provided with examples
Best practices and error handling guidance included

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

每个参考文件都包含详细的端点文档
明确指定了API参数与请求/响应格式
提供了常见用例与工作流示例
包含最佳实践与错误处理指导

Base URL and Request Format

基础URL与请求格式

All API requests use the base URL:

https://protocols.io/api/v3

All requests require the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Most endpoints support JSON request/response format with

Content-Type: application/json

所有API请求使用以下基础URL：

https://protocols.io/api/v3

所有请求均需包含Authorization头部：

Authorization: Bearer YOUR_ACCESS_TOKEN

大多数端点支持JSON请求/响应格式，需设置

Content-Type: application/json

。

Content Format Options

内容格式选项

Many endpoints support a

content_format

parameter to control how protocol content is returned:

```
json
```
: Draft.js JSON format (default)
```
html
```
: HTML format
```
markdown
```
: Markdown format

Include as query parameter:

?content_format=html

许多端点支持

content_format

参数，用于控制实验方案内容的返回格式：

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

可作为查询参数添加：

?content_format=html

Rate Limiting

速率限制

Be aware of API rate limits:

Standard endpoints: 100 requests per minute per user
PDF endpoint: 5 requests/minute (signed-in), 3 requests/minute (unsigned)

Implement exponential backoff for rate limit errors (HTTP 429).

请注意API速率限制：

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

遇到速率限制错误（HTTP 429）时，实现指数退避策略。

Common Workflows

常见工作流

Workflow 1: Import and Analyze Protocol

工作流1：导入与分析实验方案

To analyze an existing protocol from protocols.io:

Search: Use
```
GET /protocols
```
with keywords to find relevant protocols
Retrieve: Get full details with
```
GET /protocols/{protocol_id}
```
Extract: Parse steps, materials, and metadata for analysis
Review discussions: Check
```
GET /protocols/{id}/comments
```
for user feedback
Export: Generate PDF if needed for offline reference

Reference files:

protocols_api.md

discussions.md

要分析protocols.io中的现有实验方案：

搜索：使用
```
GET /protocols
```
并传入关键词查找相关实验方案
获取详情：使用
```
GET /protocols/{protocol_id}
```
获取完整详情
提取信息：解析步骤、材料与元数据用于分析
查看讨论：调用
```
GET /protocols/{id}/comments
```
查看用户反馈
导出：如有需要，生成PDF用于离线参考

参考文件：

protocols_api.md

discussions.md

Workflow 2: Create and Publish Protocol

工作流2：创建与发布实验方案

To create a new protocol and publish with DOI:

Authenticate: Ensure you have valid access token (see
```
authentication.md
```
)
Create: Use
```
POST /protocols
```
with title and description
Add steps: For each step, use
```
POST /protocols/{id}/steps
```
Add materials: Document reagents in step components
Review: Verify all content is complete and accurate
Publish: Issue DOI with
```
POST /protocols/{id}/publish
```

Reference files:

protocols_api.md

authentication.md

要创建新实验方案并发布获取DOI：

身份验证：确保你拥有有效的访问令牌（参见
```
authentication.md
```
）
创建：使用
```
POST /protocols
```
传入标题与描述
添加步骤：对每个步骤调用
```
POST /protocols/{id}/steps
```
添加材料：在步骤组件中记录试剂信息
审核：验证所有内容完整且准确
发布：调用
```
POST /protocols/{id}/publish
```
获取DOI

参考文件：

protocols_api.md

authentication.md

Workflow 3: Collaborative Lab Workspace

工作流3：协作式实验室工作区

To set up team protocol management:

Create/join workspace: Access or request workspace membership (see
```
workspaces.md
```
)
Organize structure: Create folder hierarchy for lab protocols (see
```
file_manager.md
```
)
Create protocols: Use
```
POST /workspaces/{id}/protocols
```
for team protocols
Upload files: Add experimental data and images
Enable discussions: Team members can comment and provide feedback
Track experiments: Document protocol executions with experiment records

Reference files:

workspaces.md

file_manager.md

protocols_api.md

discussions.md

additional_features.md

要设置团队实验方案管理：

创建/加入工作区：访问或请求加入工作区（参见
```
workspaces.md
```
）
组织结构：为实验室实验方案创建文件夹层级（参见
```
file_manager.md
```
）
创建实验方案：使用
```
POST /workspaces/{id}/protocols
```
创建团队实验方案
上传文件：添加实验数据与图片
启用讨论：团队成员可添加评论并提供反馈
追踪实验：使用实验记录记录实验方案的执行过程

参考文件：

workspaces.md

file_manager.md

protocols_api.md

discussions.md

additional_features.md

Workflow 4: Experiment Documentation

工作流4：实验文档编制

To track protocol executions and results:

Execute protocol: Perform protocol in laboratory
Upload data: Use File Manager API to upload results (see
```
file_manager.md
```
)
Create record: Document execution with
```
POST /protocols/{id}/runs
```
Link files: Reference uploaded data files in experiment record
Note modifications: Document any protocol deviations or optimizations
Analyze: Review multiple runs for reproducibility assessment

Reference files:

additional_features.md

file_manager.md

protocols_api.md

要追踪实验方案的执行过程与结果：

执行实验方案：在实验室中执行实验方案
上传数据：使用文件管理器API上传结果（参见
```
file_manager.md
```
）
创建记录：调用
```
POST /protocols/{id}/runs
```
记录执行过程
关联文件：在实验记录中引用已上传的数据文件
记录修改：记录实验方案的任何偏差或优化
分析：查看多次运行结果以评估可重复性

参考文件：

additional_features.md

file_manager.md

protocols_api.md

Workflow 5: Protocol Discovery and Citation

工作流5：实验方案发现与引用

To find and cite protocols in research:

Search: Query published protocols with
```
GET /publications
```
Filter: Use category and keyword filters for relevant protocols
Review: Read protocol details and community comments
Bookmark: Save useful protocols with
```
POST /protocols/{id}/bookmarks
```
Cite: Use protocol DOI in publications (proper attribution)
Export PDF: Generate formatted PDF for offline reference

Reference files:

protocols_api.md

additional_features.md

要在研究中查找并引用实验方案：

搜索：调用
```
GET /publications
```
查询已发布的实验方案
筛选：使用类别与关键词筛选相关实验方案
审核：查看实验方案详情与社区评论
添加书签：调用
```
POST /protocols/{id}/bookmarks
```
保存有用的实验方案
引用：在出版物中使用实验方案的DOI（正确归因）
导出PDF：生成格式化PDF用于离线参考

参考文件：

protocols_api.md

additional_features.md

Python Request Examples

Python 请求示例

Basic Protocol Search

基础实验方案搜索

python

import requests

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

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']}")

undefined

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']}")

undefined

Create New Protocol

创建新实验方案

python

import requests

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

python

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}")

undefined

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}")

undefined

Upload File to Workspace

向工作区上传文件

python

import requests

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

python

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}")

undefined

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}")

undefined

Error Handling

错误处理

Implement robust error handling for API requests:

python

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")

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

python

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")

Reference Files

参考文件

Load the appropriate reference file based on your task:

authentication.md
: OAuth flows, token management, rate limiting
protocols_api.md
: Protocol CRUD, steps, materials, publishing, PDFs
discussions.md
: Comments, replies, collaboration
workspaces.md
: Team workspaces, permissions, organization
file_manager.md
: File upload, folders, storage management
additional_features.md
: Profiles, publications, experiments, notifications

To load a reference file, read the file from the

references/

directory when needed for specific functionality.

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

authentication.md
：OAuth流程、令牌管理、速率限制
protocols_api.md
：实验方案增删改查、步骤、材料、发布、PDF生成
discussions.md
：评论、回复、协作
workspaces.md
：团队工作区、权限、组织
file_manager.md
：文件上传、文件夹、存储管理
additional_features.md
：个人资料、发布内容、实验、通知

如需特定功能的详细信息，从

references/

目录中读取对应的参考文件。

Best Practices

最佳实践

Authentication: Store tokens securely, never in code or version control
Rate Limiting: Implement exponential backoff and respect rate limits
Error Handling: Handle all HTTP error codes appropriately
Data Validation: Validate input before API calls
Documentation: Document protocol steps thoroughly
Collaboration: Use comments and discussions for team communication
Organization: Maintain consistent naming and tagging conventions
Versioning: Track protocol versions when making updates
Attribution: Properly cite protocols using DOIs
Backup: Regularly export important protocols and workspace data

身份验证：安全存储令牌，切勿将其写入代码或版本控制系统
速率限制：实现指数退避策略并遵守速率限制
错误处理：妥善处理所有HTTP错误码
数据验证：在调用API前验证输入内容
文档编制：详细记录实验方案步骤
协作：使用评论和讨论进行团队沟通
组织：保持一致的命名与标签规范
版本控制：更新实验方案时追踪版本
归因：使用DOI正确引用实验方案
备份：定期导出重要的实验方案与工作区数据

Additional Resources

附加资源

Official API Documentation: https://apidoc.protocols.io/
Protocols.io Platform: https://www.protocols.io/
Support: Contact protocols.io support for API access and technical issues
Community: Engage with protocols.io community for best practices

官方API文档：https://apidoc.protocols.io/
Protocols.io平台：https://www.protocols.io/
支持：联系protocols.io支持获取API访问权限与技术问题帮助
社区：参与protocols.io社区交流最佳实践

Troubleshooting

故障排除

Authentication Issues:

Verify token is valid and not expired
Check Authorization header format:
```
Bearer YOUR_TOKEN
```
Ensure appropriate token type (CLIENT vs OAUTH)

Rate Limiting:

Implement exponential backoff for 429 errors
Monitor request frequency
Consider caching frequent requests

Permission Errors:

Verify workspace/protocol access permissions
Check user role in workspace
Ensure protocol is not private if accessing without permission

File Upload Failures:

Check file size against workspace limits
Verify file type is supported
Ensure multipart/form-data encoding is correct

For detailed troubleshooting guidance, refer to the specific reference files covering each capability area.

身份验证问题：

验证令牌有效且未过期
检查Authorization头部格式：
```
Bearer YOUR_TOKEN
```
确保使用了正确的令牌类型（CLIENT vs OAUTH）

速率限制问题：

为429错误实现指数退避策略
监控请求频率
考虑对频繁请求进行缓存

权限错误：

验证工作区/实验方案的访问权限
检查用户在工作区中的角色
若未获权限，确保实验方案不是私有状态

文件上传失败：

检查文件大小是否符合工作区限制
验证文件类型是否受支持
确保使用了正确的multipart/form-data编码

如需详细的故障排除指导，请参考各能力领域对应的参考文件。