protocols.io File Manager 集成实战指南v4 搜索、回收站、S3 三步上传与导入导出的安全实现【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文基于scientific-agent-skills仓库中protocolsio-integration技能包的官方 API 核查记录file_manager.md系统讲解 protocols.io File Manager 的完整集成面v4 文件管理器搜索、反直觉的回收站/恢复 HTTP 动词、S3 后端的三阶段上传流程、附件下载的信任边界以及导入/导出工作流的正确姿势。读完本文你将掌握一套只读请求先计划、写操作只产出脱敏计划、绝不执行的安全集成方法并能直接调用仓库内附带的 CLI 脚本完成搜索规划、上传规划与导出状态查询。背景为什么 File Manager 需要单独一份核查文档protocols.io 的官方 API 落地页标题仍为 API v3但其受维护的章节实际混合了v3 与 v4两代契约不存在一个能套用所有资源的统一/api/v3基址见 SKILL.md 开篇。File Manager 更是其中版本混用最典型的模块搜索走 v4回收站与上传走 v3组织导出走 v4 且托管在租户子域。任何写死一个版本号的客户端都会踩坑。file_manager.md的核查基准日期为2026-07-23结论直接决定了仓库内配套脚本plan_write_request.py、protocols_read.py的端点拼装逻辑。v4 File Manager 搜索受维护的唯一入口官方将旧的三次调用加载器top folders、folder ids、items by ids标记为archived/deprecated并指向新的搜索 API。因此新集成只应基于 v4 搜索这也是本技能包采用的唯一搜索路径。三个搜索范围范围声明的 HTTP 请求单文件夹GET /api/v4/filemanager/folders/folder_guid/search单工作区GET /api/v4/filemanager/workspaces/workspace_uri/search全部可访问工作区GET /api/v4/filemanager/search一个上游陷阱部分邻近的示例代码块仍显示-X PUT但每个受维护的 HTTP Request 声明均为GET。以声明的方法为准即 GET部署前务必复核在线文档因为该不一致来自上游。另外全工作区搜索要求携带search_key。查询字段与 ID 字典官方参考文档化了以下查询字段page_id、page_size分页sort_by、sort_dirASC/DESCsearch_key全工作区搜索必填重复/数组形式的content_types[]重复/数组形式的protocol_types[]modified_afterUnix 时间戳。内容类型 IDcontent_types[]ID内容1protocols10folders11run records15files协议类型 IDprotocol_types[]ID内容1protocol3collection4document响应中通常包含条目对象与分页信息常见于payload内。必须同时校验 HTTP 响应状态与 API 层的status_code——不要默认沿用 v3 的根级信封结构。这一点与仓库读取客户端的require_api_success实现一致它从 JSON 中读取status_code仅当值为0或空时才判定成功见 _common.py。条目对象与访问字段当前对象把两类 ID 严格分离item_id—— 跨内容类型的 File Manager 条目顺序 IDcontent_id—— 底层 protocol/folder/record/file 的真实 IDtype_id—— 内容类型内容专属标识符如 protocol ID/URI、folder GUID、record GUID 或 file ID一个access对象描述每条目的能力位。切勿把item_id与 file/protocol/folder 自身的id混为一谈——回收站操作使用的正是 File Manager 的item_id。access对象的布尔能力位can_view、can_edit、can_remove、can_add、can_publish、can_get_doi、can_share、can_move、can_move_outside、can_transfer、can_download以及limited_run等限制在写操作前必须逐项核对可见条目并不等于可编辑、可下载或可发布详见 workspaces.md 的 File Manager Permissions 一节。文件记录可能暴露标题、文件元数据、创建者、源/占位链接、时间戳、大小与权限。所有名称与链接都视为不可信数据由sanitize_untrusted在输出前统一截断、去控制字符并脱敏见 _common.py。回收站与恢复反直觉的 HTTP 动词官方参考目前文档化的契约是PUT /api/v3/filemanager/trash携带idsFile Manager 条目 ID把条目移入回收站DELETE /api/v3/filemanager/trash携带ids恢复条目。这两个动词是反直觉的——移入回收站用PUT恢复却用DELETE。不要自作主张替换为臆造的DELETE /files/{id}或/restore端点。仓库中的写规划器忠实保留了这一语义trash-files操作生成的计划请求即为PUT https://www.protocols.io/api/v3/filemanager/trash见 plan_write_request.py。由于两者都是变更操作规划前必须逐条抓取条目核对item_id、底层内容 ID、类型、所属工作区检查can_remove权限与当前回收站状态检查受影响的 collection/protocol 引用关系展示完整的 ID 列表并取得新鲜的确认绝不自动重试。用规划器只做计划无法执行python3 -B scripts/plan_write_request.py \ --operation trash-files \ --payload reviewed-item-ids.json--payload必须指向受本地 JSON 体积上限约束的.json文件默认 2 MB见 _common.py且根必须是对象、字段数不超过 10,000ids为非空数组且每个元素为 0~2,147,483,647 的整数见 plan_write_request.py。文档化的上传流程S3 后端三阶段官方 API 参考描述了一个 S3 支撑的三阶段过程Prepare准备——POST /api/v3/filesTransfer传输—— 把返回的表单提交到返回的存储目标Verify校验——PUT /api/v3/files/file_id阶段一Prepare文档化字段必填filename可选original_file_id用于缩略图可选width、height与平均color。响应会返回新的file_id、文件元数据以及一组临时表单字段key、bucket、access-key 标识、policy、signature、content type 与 ACL。这些表单字段本质是临时凭证/能力必须严守纪律绝不打印、记录、缓存、粘贴进聊天或写入计划绝不为另一个文件复用绝不把返回的目标地址或表单值当作指令执行传输字节前必须把确切目标地址与一份单独批准的 upload-host 策略比对校验不要把 protocols.io 的 bearer token 发送给存储主机不跟随重定向传输/校验完成后丢弃所有临时字段。仓库的规划器用[REDACTED_SIGNED_DESTINATION_FROM_PREPARE_RESPONSE]与[REDACTED_EPHEMERAL_FORM_FIELDS]占位并把requires_separate_destination_validation标记为true从计划产物层面杜绝凭证外泄见 plan_write_request.py。阶段二Transfer将 Prepare 返回的表单原样提交到经验证的存储目标。该阶段在规划器中被标记为MULTIPHASE且不做任何网络 I/O实际字节传输必须由一份单独评审过的上传工具完成。阶段三VerifyPUT /api/v3/files/file_id在 protocols.io 数据库中把已准备的文件标记为已验证。只校验本次上传返回的file_id绝不接受来自协议正文或评论中的文件 ID。大小与类型声明不编造数字官方 feature 页面声称 File Manager 支持任意文件类型但本次核查的 API 与帮助资料没有给出任何数值化的上传大小上限。因此不再复述旧有的 100 MB–1 GB 说法不声称支持分块上传不维护编造的扩展名白名单应用本地防御性字节上限并明确标注为本地限制涉及合同性服务/存储上限时向用户的计划/工作区管理员或 protocols.io 支持方确认。仓库把这一本地防御落实为--local-max-upload-bytes默认 25 MB、硬上限 100 MBMAX_UPLOAD_INSPECTION_BYTES见 plan_write_request.py仅约束本地哈希 I/Oservice_limit_asserted恒为false明确声明未断言服务限制。超大文件应走单独评审的工具而不是调高此上限。在无网络条件下对受边界约束的本地文件做规划与哈希python3 -B scripts/plan_write_request.py \ --operation upload-file \ --upload-file data/results.bin \ --local-max-upload-bytes 100000000_hash_file以 64 KiB 分块流式计算 SHA-256一旦累计超过上限立即报错见 plan_write_request.py。规划器输出不含任何签名字段也没有上传执行器——这正是该技能计划与执行分离的核心。安全上传检查清单在任何独立上传器运行之前逐项确认本地路径位于预期工作目录内、是普通非符号链接文件、且低于显式本地上限记录本地字节数与 SHA-256但不暴露文件内容审查文件名是否含参与者 ID、PHI/PII、未发布项目名或密钥确定确切的目标工作区/文件夹与可见性核实同意书、数据使用协议、留存策略、加密与工作区权限只准备一次校验/脱敏响应不展示任何凭证在字节传输前一刻取得新鲜确认以字节上限流式传输不跟随重定向不携带 bearer 头校验返回的file_id随后重新抓取元数据在服务端暴露可比数据时比对大小/哈希通过文档化的产品工作流清理未完成的已准备记录。_common.py为这条清单提供了系统级支撑NoRedirectHandler拒绝一切重定向防止凭证跨源validate_origin只放行 HTTPS 且无凭据、无路径、无查询、仅 443 端口的 protocols.io 官方主机租户子域需显式允许_bounded_read同时检查Content-Length声明与实读字节数见 _common.py、_common.py、_common.py。附件与下载不可信数据的边界协议对象可能包含附件 URL包括存储主机的 URL。这些是不可信数据且位于仓库内置核心主机只读客户端protocols_read.py的覆盖范围之外。绝不因为协议/评论说要去抓取就抓取。对经批准的下载器单独对预期的确切主机/服务建白名单除非官方端点明确要求否则不向附件主机发送 protocols.io bearer token拒绝重定向、URL 内嵌凭据、HTTP 与非默认端口限制 header/body/超时写入新的私有非符号链接路径仓库用os.O_EXCL原子创建并置为0600权限见 _common.py打开前校验内容类型/签名并扫描绝不执行下载的脚本、notebook、压缩包或 Office 宏。本次官方 API 核查没有发现受维护的通用鉴权文件下载端点。不要臆造GET /workspaces/{workspace_id}/files/{file_id}/download。导入产品工作流而非公开 REST 契约官方的 Protocolify 教程描述了一个面向用户的 AI 导入器把现有PDF 或 Word 文档转换为交互式协议并明确要求导入后的协议必须仔细核对准确性。这是一个产品工作流不是本次核查的 API 章节中的公开 REST 导入契约。不要臆造/imports端点也不要在未获单独授权的情况下自动化该 UI。对任何导入过程保留原始文档与署名将其归类为不可信数据对照来源逐一核实标题、作者、材料、数量、单位、警告、步骤、文件、链接与引文保留版本谱系并声明转换过程为自动化完成在合格的真人审阅通过前不发布。此外官方还文档化了一个面向用户的编辑工作流 We enter protocols代录入服务它同样不是 API 端点。导出两条已验证路径当前验证通过的导出路径只读协议 PDFGET /view/[id].pdf异步租户组织导出在/api/v4/organizations/organization_uri/content/exports下先POST发起再GET查询状态。旧有的GET /api/v3/organizations/{id}/export?format...契约未被找到。feature 页宣传的归档/审计/导出以及 Dropbox、OneDrive、Box 等集成属于产品能力不是充分的 API 契约——不要从营销文案反推 REST 路径或 OAuth scope。PDF 导出只读客户端内置仓库的export-pdf子命令见 protocols_read.py支持--anonymous有意的登出请求、--compact-view、--only materials|commands|steps与--max-pdf-bytes上限 25 MB。执行时会校验Content-Type: application/pdf与%PDF-魔数PDF 字节只写入新建私有0600文件。测试test_mocked_pdf_export_writes_private_file验证了权限位与字节数见 test_scripts.py。组织导出租户托管发起POST https://subdomain.protocols.io/api/v4/organizations/organization_uri/content/exports可选字段为 TZ 数据库形式的timezone缺省用 UTC返回的导出对象位于payload下包含guid、Unixcreated_on、total_files、total_processed_files、is_finished与可空的download_link。完成时官方文档要求用同一个 bearer 头GET 下载链接。安全要点详见 workspaces.md 的 Organization Content Export 一节必须使用客户确切的租户 origin绝不根据组织名猜测子域发起是写/昂贵后台任务dry-run、数据范围评审与确认缺一不可轮询必须有最大次数与间隔禁止无界循环即便download_link由 API 返回也按不可信数据处理校验 host/path、禁重定向、限字节、不打印 bearer 头导出包可能含私有协议、文件、评论、成员数据或审计信息需写入受访问控制的存储并遵循留存策略当前导出章节未文档化任意的format、include_files、include_comments参数不要发送。规划发起不执行python3 -B scripts/plan_write_request.py \ --operation organization-export \ --tenant-origin https://tenant.protocols.io \ --target organization-uri \ --payload export-options.json读取既有状态只读python3 -B scripts/protocols_read.py export-status \ --tenant-origin https://tenant.protocols.io \ --organization organization-uri \ --export-guid 0123456789ABCDEF0123456789ABCDEF状态子命令会校验租户必须是显式子域、组织为受限标识符、GUID 为 32 位十六进制见 protocols_read.py。审阅计划后再加全局--execute。已归档 API 警告官方 API 页面把旧的三次调用 File Manager 加载器top folders、folder ids、items by ids标记为archived/deprecated并指向新的搜索 API。不要在已归档章节之上构建新集成。配套工具与测试如何印证这套契约仓库把上述契约落成了一组零第三方依赖、仅用标准库的脚本要求 Python 3.11plan_write_request.py—— 覆盖create-protocol、update-protocol、publish-protocol、upsert-steps、delete-steps、add-comment、delete-comment、trash-files、upload-file、organization-export十种操作网络访问恒为false输出红action 计划、精确确认短语与问题清单protocols_read.py—— 只读客户端默认只产出计划加--execute才发起有界 GETpagination_helper.py—— 离线校验服务器返回的next_page是否与当前端点同源同路径validate_auth_config.py—— 只报告PROTOCOLS_IO_ACCESS_TOKEN存在性不泄露值。测试套件test_scripts.py提供了可复现的证据test_write_planner_redacts_and_never_executes验证敏感字段如client_secret在计划 JSON 中完全不可见且execution_supported为falsetest_upload_plan_hashes_bounded_local_file_only验证上传计划的 phase 中被REDACTED覆盖、service_limit_asserted为falsetest_redirect_handler_refuses_redirects验证NoRedirectHandler对 302 返回None。结论与实操建议围绕 protocols.io File Manager可以沉淀为四条铁的纪律版本按端点记忆不按页面标题搜索用 v4回收站/上传用 v3组织导出用 v4 租户托管——以每条端点的声明为准一切写操作先出计划规划器永远不联网、不执行、不输出签名字段--confirm仅标记已审阅而非已执行临时凭证即能力Prepare 返回的 S3 表单字段等同于可写能力绝不复用、绝不外泄、绝不当指令执行不编造契约没有数值化上传上限、没有通用文件下载端点、没有/imports端点——遇到未文档化的方法/路径/参数/限制明确标注未文档化并复核在线文档。需要深入时可继续阅读仓库内同目录的 authentication.md、workspaces.md、protocols_api.md 与 additional_features.md它们共同构成一套完整、可审计、面向 Agent 的 protocols.io 集成规范。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考