alterlab-protocolsio

Protocols.io 集成

概述

protocols.io 托管带版本号、可引用的科学实验方案（每个已发布版本都会获得一个 10.17504/protocols.io.* 下的 DOI），还提供团队工作区、实验运行记录和文件管理器。它提供两种编程接口：

• 官方 MCP 服务 — https://www.protocols.io/mcp（Streamable HTTP；通过 OAuth 2.0 登录或使用 Bearer 客户端令牌）。它也以“protocols.io”的名称列在 Claude 的连接器目录中。
• REST API — 基础地址为 https://www.protocols.io/api，分为多个版本：大多数端点为 v3，而获取／更新实验方案、实验方案步骤、运行记录、文件管理器搜索和组织导出使用 v4。API 参考文档见 https://apidoc.protocols.io/。

何时使用此技能

• 按关键词、作者或工作区搜索 protocols.io 中的实验方案，或通过 DOI 或 URI 解析实验方案
• 以 Markdown、HTML 或 Draft.js JSON 格式读取实验方案的步骤和材料，以便分析、改编或比较
• 创建私有实验方案、填写其元数据和步骤，并发布它（或预留 DOI），以便在论文中引用
• 阅读或发布实验方案评论和步骤讨论
• 列出或加入工作区、搜索工作区文件、上传文件，以及导出组织内容
• 创建和更新实验方案的实验运行记录

不适用情形

情形	请改用
在通用电子实验记录本中记录结果（条目、附件、记录本备份）	alterlab-labarchive（LabArchives）或 alterlab-benchling（Benchling）
将书面实验方案转换为适用于 Opentrons OT-2/Flex 或 Hamilton/Tecan 液体处理器的脚本	alterlab-opentrons 或 alterlab-pylabrobot
存放预印本或选择数据／代码仓库（bioRxiv、OSF、Zenodo）	alterlab-preprint-deposition 或 alterlab-open-science
撰写或润色论文的 Methods 部分	alterlab-scientific-writing

连接后优先使用 MCP 服务

如果会话中有可用的 protocols.io 工具（连接器或 MCP 服务），请用它们进行搜索、检索和编辑：它们通过用户自己的账户运行、处理 OAuth，并返回实时数据。对于这些工具不支持的操作，或未连接任何连接器时，再使用下方的 REST 调用。要连接，请将 https://www.protocols.io/mcp 添加为远程 MCP 服务（或从 Claude 的连接器目录中添加“protocols.io”）并登录。无论使用哪种方式，报告实验方案内容时都应注明其 DOI 和检索日期。

身份验证

令牌	来源	可访问内容
CLIENT_ACCESS_TOKEN	https://www.protocols.io/developers	公开内容，以及创建该客户端的用户的私有内容
OAUTH_ACCESS_TOKEN	OAuth 2.0 授权码流程	公开内容，以及授权用户的私有内容

每次请求都要通过 Authorization: Bearer <token> 发送令牌，并将其保存在环境变量中（例如 PROTOCOLS_IO_TOKEN），切勿将其写入代码或笔记本。OAuth 令牌有效期约为一年；API 会在令牌过期前一个月发出警告，刷新令牌会使旧令牌对失效。授权链接、令牌交换和刷新调用见 references/authentication.md。

请求基础

标识符。 协议端点接受整数 id、协议 uri（slug，例如 tree-mapping-for-leaf-collection-megantic-only-baaciaaw），以及对于 v4 获取/步骤端点，接受 DOI（10.17504/protocols.io.baaciaaw 或 protocols.io.baaciaaw）。追加 /v1 可指定特定版本，追加 /latest 可指定最新版本。写入端点也接受协议 guid。

内容格式。 v4 协议、步骤和记录读取端点接受 content_format=json|html|markdown，用于指定富文本字段（描述、指南、警告、材料文本、步骤文本）的格式。json 使用 Draft.js；如果文本将用于阅读或摘要，请请求 markdown。

分页。 列表端点接受 page_id（从 1 开始）和 page_size（1–100，默认值为 10），并返回一个 pagination 对象。

错误在响应正文中。 每个响应都包含 JSON status_code，其中 0 表示成功。失败通常以 HTTP 400 返回，并附带 error_message（v3）或 status_text（v4）——缺少或无效的令牌对应 1218，已过期的 OAuth 令牌对应 1219——因此请检查 status_code，而不仅是 HTTP 状态码。

速率限制。 每位用户每分钟 100 个请求；PDF 端点（/view/<uri>.pdf）登录时每分钟允许 5 个请求，未登录时每分钟允许 3 个请求。超过限制会返回 HTTP 429。

端点一览

任务	调用	详情
搜索协议	GET /v3/protocols?filter=public&key=...	references/protocols_api.md
研究人员或工作区的协议	GET /v3/researchers/<username>/protocols、GET /v3/workspaces/<uri>/protocols	protocols_api.md、workspaces.md
获取协议（含步骤和材料）	GET /v4/protocols/<id-uri-or-doi>	protocols_api.md
获取步骤/材料	GET /v4/protocols/<id>/steps、GET /v3/protocols/<id>/materials	protocols_api.md
创建协议	POST /v3/protocols/<new-guid>	protocols_api.md
更新元数据	PUT /v4/protocols/<id>（JSON）	protocols_api.md
添加、更改或删除步骤	POST / DELETE /v4/protocols/<id>/steps	protocols_api.md
发布或预留 DOI	POST /v3/protocols/<uri>/publish（prepublish=1 可预留）	protocols_api.md
收藏	POST / DELETE /v3/protocols/<uri>/bookmarks	protocols_api.md
PDF	GET https://www.protocols.io/view/<id-or-uri>.pdf	protocols_api.md
最近发布	GET /v3/publications?latest=N 或 ?from=&to=	protocols_api.md
评论和步骤讨论	/v3/protocols/<uri>/comments、/v3/steps/<step_id>/discussions	references/discussions.md
工作区和成员资格	/v3/workspaces、/v3/workspaces/<uri>/members	references/workspaces.md
文件管理器搜索、回收站、上传	/v4/filemanager/.../search、/v3/filemanager/trash、/v3/files	references/file_manager.md
个人资料、运行记录、通知、组织导出	/v3/session/profile、/v3/records、/v3/researchers/notifications、/v4/organizations/<uri>/content/exports	references/additional_features.md

除 PDF 查看端点外，所有路径均相对于 https://www.protocols.io/api。https://protocols.io/... 会重定向到 www. 主机；不存在 api.protocols.io 主机。

Python 示例

示例使用 requests，以及一个用于将 protocols.io 响应正文中的错误转换为异常的辅助函数：

import os
import time
import uuid

import requests

BASE = "https://www.protocols.io/api"
HEADERS = {"Authorization": f"Bearer {os.environ['PROTOCOLS_IO_TOKEN']}"}


def call(method, path, retries=3, **kwargs):
    """Send a request; back off on HTTP 429 and raise when the JSON status_code is not 0."""
    for attempt in range(retries):
        resp = requests.request(method, f"{BASE}{path}", headers=HEADERS, timeout=60, **kwargs)
        if resp.status_code == 429 and attempt < retries - 1:
            time.sleep(int(resp.headers.get("Retry-After", 30 * (attempt + 1))))
            continue
        try:
            data = resp.json()
        except ValueError:  # e.g. an HTML error page from a proxy
            resp.raise_for_status()
            raise
        if data.get("status_code", 0) != 0:
            message = data.get("error_message") or data.get("status_text")
            raise RuntimeError(f"protocols.io {data.get('status_code')}: {message} (HTTP {resp.status_code})")
        return data
    raise RuntimeError("protocols.io rate limit: retries exhausted")

搜索并引用

found = call("GET", "/v3/protocols", params={
    "filter": "public", "key": "CRISPR", "order_field": "relevance", "page_size": 10,
})
for item in found["items"]:
    doi = (item.get("doi") or "").removeprefix("dx.doi.org/")  # list items use a dx.doi.org/ prefix
    print(item["title"], f"https://doi.org/{doi}" if doi else "(no DOI yet)")

要进行精确匹配搜索，请在 key 中用双引号括起搜索词组。

以 Markdown 格式按 DOI 读取协议

data = call("GET", "/v4/protocols/10.17504/protocols.io.baaciaaw",
            params={"content_format": "markdown"})
protocol = data.get("payload") or data.get("protocol")  # current v4 responses use "payload"
print(protocol["title"], protocol["url"])
for number, step in enumerate(protocol.get("steps", []), start=1):
    print(number, step.get("step"))

创建、填写并发布协议

guid = uuid.uuid4().hex.upper()  # new GUID without dashes, generated client-side
created = call("POST", f"/v3/protocols/{guid}", data={"type_id": 1})  # 1 protocol, 3 collection, 4 document
uri = created["protocol"]["uri"]

call("PUT", f"/v4/protocols/{guid}", json={
    "title": "CRISPR-Cas9 knockout in HEK293T cells",
    "description": "RNP electroporation workflow with T7E1 validation.",
    "materials_text": "SpCas9 nuclease; synthetic sgRNA; Neon electroporation kit",
    "status_id": 2,  # 1 working, 2 still optimizing, 3 could not get it to work
})

# Steps are ordered by previous_guid: the first step has previous_guid None.
texts = ["Anneal and complex sgRNA with Cas9 (10 min, room temperature).",
         "Electroporate 2e5 cells per reaction.",
         "Harvest genomic DNA after 72 h and run the T7E1 assay."]
steps, previous = [], None
for text in texts:
    step_guid = uuid.uuid4().hex.upper()
    steps.append({"guid": step_guid, "previous_guid": previous, "step": text})
    previous = step_guid
call("POST", f"/v4/protocols/{guid}/steps", json={"steps": steps})

# Reserve a DOI without making it public (drop prepublish to publish openly).
call("POST", f"/v3/protocols/{uri}/publish", params={"prepublish": 1})

发布协议需要标题和至少一位作者；而且，带有 DOI 的版本无法再编辑，因此请先在 Web 编辑器中检查协议。已发布的协议仅接受 PUT 字段中的一部分（关键词、免责声明、伦理声明、手稿引用、参考文献、资助方，以及状态/警告标志）；内容更改需要创建新版本，但 API 文档未说明如何创建，因此请在 Web 编辑器中创建。

上传文件

上传需要调用 3 次：注册文件、使用返回的策略将字节发送到 S3，然后确认：

path = "results.csv"
prep = call("POST", "/v3/files", data={"filename": os.path.basename(path)})
form, meta = prep["formData"], prep["metaData"]
fields = {"key": form["key"], "acl": form["acl"], "AWSAccessKeyId": form["AWSAccessKeyId"],
          "Policy": form["Policy"], "Signature": form["Signature"], "Content-Type": form["ContentType"]}
with open(path, "rb") as fh:  # the file must be the last form field
    s3 = requests.post(f"https://{form['s3_bucket']}.s3.amazonaws.com/", data=fields,
                       files={"file": (os.path.basename(path), fh)}, timeout=300)
s3.raise_for_status()
call("PUT", f"/v3/files/{meta['file_id']}")  # verify the upload

文档中的上传调用不接受文件夹、工作区或标签字段。将返回的 file_id 添加到集合（使用 content_type_id 15 的 collection_items），或在 Web 应用中整理文件。S3 步骤遵循标准的 S3 POST 策略表单，但 API 文档未详细说明；请先用小文件尝试。参见 references/file_manager.md。

常见工作流

导入并分析现有协议。 搜索（GET /v3/protocols），以 Markdown 格式获取所选协议（GET /v4/protocols/<doi>），读取其评论（GET /v3/protocols/<uri>/comments）以了解已报告的修正，并记录所用的 DOI 和版本。

起草并发布实验室协议。 创建协议（POST /v3/protocols/<guid>），设置元数据（PUT /v4/protocols/<guid>），按顺序添加步骤（POST /v4/protocols/<guid>/steps），在 Web 编辑器中与合著者审阅，然后在论文审稿期间使用 prepublish=1 预留 DOI，并在论文被接受后发布。

记录协议运行情况。 根据协议创建运行记录（使用 protocol_uri 调用 POST /v3/records），然后通过 PUT /v3/records/<guid> 勾选步骤并添加备注（参见 references/additional_features.md）。将原始数据存储在 ELN 或存储库中，并在其中引用该记录或协议。

团队工作区。 列出用户的工作区（GET /v3/workspaces?filter=my_groups），列出或搜索工作区中的协议和文件，并通过 POST /v3/workspaces/<uri>/members 申请加入公开工作区（参见 references/workspaces.md）。

机构存档。 在组织账户中启动完整内容导出（POST https://<subdomain>.protocols.io/api/v4/organizations/<org_uri>/content/exports），并轮询，直到设置了 download_link。

引用协议

请引用实际使用的版本：Author(s). Title. protocols.io. https://doi.org/10.17504/protocols.io.<id>；如果 DOI 带有版本后缀（/v1、/v2……），请保留该后缀。带有 DOI 的版本无法编辑，但 /latest 会指向新版本，因此请在方法部分和数据记录中固定具体版本。

故障排除

症状	可能原因及解决方法
HTTP 400，且 status_code 为 1218	缺少或格式错误的 Authorization: Bearer <token> 标头
status_code 1219，提示“token is expired”	刷新 OAuth 令牌（grant_type=refresh_token）；旧的令牌对将不再有效
私有协议返回未找到或 132 access denied	令牌所属用户无权访问；使用协议所有者的 OAuth 令牌，或请求将你添加到工作区
创建时返回 1905	已达到工作区订阅限制
步骤 POST 被拒绝（“loop detected”“multiple first steps”“steps are not forming a complete sequence”）	修正 previous_guid 链接；插入步骤时，还要重新发送后续步骤并设置新的 previous_guid
发布时返回 255 / 256 / 257	已公开 / 缺少标题 / 缺少作者
HTTP 429	每分钟请求超过 100 次（或每分钟 PDF 请求超过 5 次）；请退避重试并缓存读取结果
Mac 上的 curl 输出二进制内容	添加 --compressed

参考文件

• references/authentication.md — 令牌类型、OAuth 授权链接、令牌交换与刷新、MCP 连接、限制
• references/protocols_api.md — 搜索、获取、创建、更新、步骤、材料、发布、书签、PDF、出版物、试剂
• references/discussions.md — 协议评论、步骤讨论、运行记录评论、私信
• references/workspaces.md — 工作区列表、详情、成员资格、工作区协议
• references/file_manager.md — 文件管理器搜索、移至回收站与恢复、S3 文件上传
• references/additional_features.md — 个人资料、运行记录、通知、组织内容导出

属于 AlterLab Academic Skills 套件的一部分。